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.
| Holochain Links: | FAQ | Developer Wiki | White Paper | GoDocs |
|---|
Table of Contents
- 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
- Install Go 1.7.5](https://golang.org/dl/).
- 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
You've installed and built a distributed data engine, but you don't have a data application running in it yet. Here's the basic flow involved in getting a chain running:
hc inithc clonehc testhc gen chainhc serve
Details of each of these steps are below...
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 'pebbles@flintstone.com'
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
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.
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>
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
hc statusto view all the chains on your system and their statushc dump <HOLOCHAIN_NAME>to can inspect the contents of your local chain
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 '<my@other.identity>'
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
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
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
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
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.
- 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.
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.
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.
- 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.