github.com/tixel/holochain

Holochain

Holographic storage for distributed applications. A holochain is a monotonic distributed hash table (DHT) where every node enforces validation rules on data before publishing that data against the signed chains where the data originated.

In other words, a holochain functions very much like a blockchain without bottlenecks when it comes to enforcing validation rules, but is designed to be fully distributed with each node only needing to hold a small portion of the data instead of everything needing a full copy of a global ledger. This makes it feasible to run blockchain-like applications on devices as lightweight as mobile phones.

Code Status: Active development for proof-of-concept stage. Pre-alpha. Not for production use. We still expect to destructively restructure data chains at this time. These instructions are really for developers who want to build distributed apps on holochains, not so much for end users who should probably use a nice packaged installation.

Holochain Links:	FAQ	Developer Wiki	White Paper	GoDocs

Table of Contents

• Holochain
  • Installation
    • Installation on Windows
    • Starting a Holochain
    • 1. Initializing Holochain Service for the First Time
    • 2. Getting Application DNA
    • 3. Testing your Application
    • 4. Generate New Chain
    • 5. Launching the Holochain Server
  • Architecture Overview and Documentation
  • Development --
    • Dependencies
    • Tests
    • Contributor Guidelines
  • License
  • Acknowledgements

Installation

• Make sure you have a working environment set up for the Go language version 1.7 or later. See the installation instructions for Go.
• Follow their instructions on the above doc page for exporting your $GOPATH and adding your $GOPATH/bin directory to your search PATH for programs. (Almost all installation problems that have been reported stem from skipping one of these path related steps.)
• Install the gx package manager:

$ go get -u github.com/whyrusleeping/gx

• Then you can install the holochain command line interface with:

$ go get -d github.com/metacurrency/holochain
$ cd $GOPATH/src/github.com/metacurrency/holochain
$ make

Make sure your PATH includes the $GOPATH/bin directory so the program it builds can be easily called:

$ export PATH=$PATH:$GOPATH/bin

Since holochain is essentially a data integrity engine intended to be used by distributed applications, you will normally only do some basic setup and maintenance through the command line.

Once you've gotten everything working as described above you can execute some basic holochain commands from the command line like this: hc help

And you can get help on specific sub commands with hc <cmd> help. For example: hc gen help

Installation on Windows

• Install Go 1.7.5.
• Install Windows git. Be sure to select the appropriate options so that git is accessible from the Windows command line.
• Install GnuWin32 make.Add C:\Program Files (x86)\GnuWin32\bin to your PATHS directory. (Make sure C:\go\bin is in your PATHS directory already, too)
• Click Start, type "System" and press Enter. Click "Advanced system settings" in the sidebar. Click "Environment Variables...". Under System Variables, click New..., and put GOPATH as the name, and the path to your Go installation in the value (usually C:\go).
• Now, double-click PATH under System Variables, and click New in the window that pops up. Add the path to go's bin directory as the value (usually C:\go\bin). This will allow you to run compiled executables from anywhere in the Windows command line.
• Now click New again time and add the path to your GnuWin32 make bin directory (usually C:\Program Files (x86)\GnuWin32\bin).
• Follow the remaining instructions starting at step 2 above. You should be able to use 'go' and 'make' from the Windows command line. (Add -x to the Go 'get' command to see verbose output as the packages download.)## Usage

Setting up a Holochain

You've installed and built the distributed data integrity engine, but you haven't set up an application running on it yet. The basic flow involved in getting a chain running looks like this:

• hc init
• hc clone
• hc test
• hc gen chain
• hc serve

Instructions for each of these steps are below...

1. Initializing Holochain Service for the First Time

The first time the holochain service is run, you need to create your default public/private keys, set up config files and directories, and set a default identity token for your participation on chains. As a general user, you should only need to do this once, but as a developer, you will need to do this if you remove your .holochain directory during testing and such.

Here's a full example of the initialization command, just substitute your own email address.

hc init '[e-mail]'

2. Getting Application DNA

You can use a pre-existing holochain application configuration by replacing SOURCE with path for loading existing application files. You can source from files anywhere such as from a git repo you've cloned, from a live chain you're already running in your .holochain directory, or one of the examples included in the holochain repository.

hc clone <SOURCE_PATH> <NAME_FOR_NEW_HOLOCHAIN>

For example: hc clone ./examples/sample sample

Before you launch your chain, this is the chance for you to customize the application settings like the NAME, and the UUID

3. Testing your Application

We have designed holochains to function around test-driven development, so each developer should have tests to confirm that you've built a functioning chain. Run the tests with;

hc test <HOLOCHAIN_NAME>

If the tests fail, then you know your application DNA is broken and you should not proceed thinking that your system is going to work. If you're a developer, you should be running this command as you make changes to your holochain DNA files to leverage test-driven development. And obviously, please do not send out applications that don't pass their own tests.

4. Generate New Chain

After you have cloned and/or completed development for your chain, you need to generate the genesis entries which start your new chain. The first entry is the DNA which is the hash of all the application code. This confirms every person's chain starts with the the same code/DNA. The second block registers your keys so you have an address, identity, and signing keys for communicating on the chain.

hc gen chain <HOLOCHAIN_NAME>

5. Launching the Holochain Server

Holochains service function requests via local web sockets. This let's interface developers have a lot of freedom to build html / javascript files and drop them in that chain's UI directory. You launch the service to listen on the socket on localhost with:

hc serve <HOLOCHAIN_NAME> [<PORT>]

In a web browser you can go to localhost:3141 (or whatever PORT you served it under) to access UI files and send and receive JSON with exposed application functions

Other Useful Commands

• hc status to view all the chains on your system and their status
• hc dump <HOLOCHAIN_NAME> to can inspect the contents of your local chain

File Locations

By default hc stores all holochain data and configuration files to the ~/.holochain directory. You can override this with the -path flag or by setting the HOLOPATH environment variable, e.g.:

hc -path ~/mychains init '<[e-mail]>'
HOLOPATH=~/mychains hc

You can use the form: hc -path=/your/path/here but you must use the absolute path, as shell substitutions will not happen

Logging

The -debug flag will turn on a number of different kinds of debugging. You can also control exactly which of these logging types you wish to see in the chain's config.json file. You can also set the DEBUG environment variable to 0 or 1 to temporarily override your settings to turn everything on or off.

Architecture Overview and Documentation

Start in the Holochain Wiki, and hopefully it will keep growing with good development resources.

You can also find the auto-generated Reference API for Holochain on GoDocs

Development --

We accept Pull Requests and welcome your participation.

• Milestones and progress on Roadmap
• Kanban on Waffle of GitHub issues
• Or chat with us on gitter

Dependencies

This project depends on various parts of libp2p, which uses the gx package manager. This means that installation doesn't follow the normal "go get" process but instead also requires a make step. Thus, to install the code and dependencies run:

go get github.com/metacurrency/holochain/
make deps

If you already installed the hc command line interface the dependencies will have been installed, and this step is unnecessary.

Note that make and make deps have a side-effect of re-writing some of the imports in various files. This is how gx handles dependencies on specific versions of go imports. But this means that when you are ready to make commits to your repo, you must undo these re-writes so they don't get committed to the repo. You can do this with:

make publish

After you have made your commit and are ready to continue working, you can redo those rewrites without re-running the full dependency install with:

make work

Tests

To compile and run all the tests:

cd $GOPATH/github.com/metacurrency/holochain
make test

Or if you have already done the initial make or make deps step, you can simply use go test as usual.

Contributor Guidelines

Tech

• We use test driven development. Adding a new function or feature, should mean you've added the tests that make sure it works.
• Set your editor to automatically use gofmt on save so there's no wasted discussion on proper indentation of brace style!
• Contact us to set up a pair coding session with one of our developers to learn the lay of the land
• join our dev documentation calls twice weekly on Tuesdays and Fridays.

Social --

We are committed to foster a vibrant thriving community, including growing a culture that breaks cycles of marginalization and dominance behavior. In support of this, some open source communities adopt Codes of Conduct. We are still working on our social protocols, and empower each team to describe its own Protocols for Inclusion. Until our teams have published their guidelines, please use the link above as a general guideline.

License

Copyright (C) 2017, The MetaCurrency Project (Eric Harris-Braun, Arthur Brock, et. al.)

This program is free software: you can redistribute it and/or modify it under the terms of the license provided in the LICENSE file (GPLv3). This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Note: We are considering other 'looser' licensing options (like MIT license) but at this stage are using GPL while we're getting the matter sorted out.

Acknowledgements

• MetaCurrency & Ceptr: Holochains are a sub-project of Ceptr which is a semantic, distributed computing platform under development by the MetaCurrency Project.  
• Ian Grigg: Some of our initial plans for this architecture were inspired in 2006 by his paper about Triple Entry Accounting and his work on Ricardian Contracts.  
• Juan Benet: For all his work on IPFS and being a generally cool guy. Various functions like multihash, multiaddress, and such come from IPFS as well as the libP2P library which helped get peered node communications up and running.  
• Crypto Pioneers And of course the people who paved the road before us by writing good crypto libraries and preaching the blockchain gospel. Back in 2008, nobody understood what we were talking about when we started sharing our designs. The main reason people want it now, is because blockchains have opened their eyes to the power of decentralized architectures.