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
- Docker Installation
- Architecture Overview and Documentation
Once you have a working environment (see OS specific instructions) you can install the Holochain command line interface with:
$ go get -d github.com/metacurrency/holochain $ cd $GOPATH/src/github.com/metacurrency/holochain $ make
Now that you’ve installed
hc you’ll need to do the first time configuration by running (just substitute your own email address.):
$ hc init '[email protected]'
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.
Most importantly you’ll need to: (Almost all installation problems that have been reported stem from skipping one of these steps.)
1. Export the
$GOPATH variable in your shell profile.
$GOPATH/bin to your
$PATH in your shell profile.
For example, add the following to the end of your shell profile (usually
export GOPATH=`$HOME/go` export PATH=$GOPATH/bin:$PATH
First you’ll need to install some necessary programs if you don’t already have them. * Install Go 1.7 or later. * Install Windows git. Be sure to select the appropriate options so that git is accessible from the Windows command line. * Install GnuWin32 make.
Next, in your Control Panel go to System>Advanced system settings>Environment Variables… and under System Variables do the following:
1. Add a new entry with the name
GOPATH and the value
%USERPROFILE%\go (Or your Go workspace folder).
2. Double-click Path, and in the window that pops up add the following entries:
C:\Go\bin (Or wherever you installed Go to+
C:\Program Files (x86)\GnuWin32\bin (Or wherever you installed GnuWin32 make to+
This section describes how to use Docker for the development of Holochain or Holochain apps.
First, you’ll need to install the latest version of Docker. See Docker Getting Started
Next, to clone the Holochain repo as well as build the Docker image, do the following:
$ git clone https://github.com/metacurrency/holochain.git . $ cd holochain $ # build a docker image with the tag 'metacurrency/holochain' $ docker build -t metacurrency/holochain .
Now that you’ve set up your image, whenever you want to make a new container from the image, do the following:
$ # run the docker container tagged 'metacurrency/holochain' $ # with ~/.holochain mounted as /root/.holochain $ # that has all ports exposed (-P) and is being run interactively (-i) $ docker run -v ~/.holochain:/root/.holochain -Pi -t metacurrency/holochain
It is perfectly possible to keep a container around for a long time. To disconnect from one and leaving it running in the background, use Ctrl+P then Ctrl+Q. However, containers are designed to be ephemeral, or rather, a Dockerfile should be designed such that destroying and creating containers is the “best practice”. To exit the container, use Ctrl+D. This will stop the container, such that it can be found listed in
docker ps -a.
By default, docker keeps absolutely everything you ever do in images on your machine. Because docker’s filesystem is so very very clever, this is done in an extremely efficient way. It is quite possible to have hundreds or thousands of container states on your machine and never notice. This is a good thing in principal. But, in practice, unless you work very hard to bury some work inside a container, you will never need to use this feature.
All of our dockerfiles, scripts and best practice processes allow you to destroy all the containers and images on your system at any time. This is how you should work with docker. If you lose work done inside a container and have no idea where it is, say so on the #docker channel in Freenode IRC. This should never happen.
In general, you will be running containers in daemonized mode. When using docker you rarely (if ever?) need to use
hc, but to get a feel for it, see Usage.
Once you’ve gotten everything working as described above you may want to use the
Since Holochain is intended to be used underneath distributed applications, end users won’t have to do much through the command line.
For the most up-to-date information on how to use
hc help or for sub-commands run
hc <COMMAND> help.
For more detailed information, see the wiki page
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 gen chain
Instructions for each of these steps are below…
Cloning Application DNA
You can load a pre-existing Holochain application DNA by running the following command (replacing SOURCE_PATH with a path to an application’s DNA and CHAIN_NAME with the name you’d like it to be stored as).
$ hc clone <SOURCE_PATH> <CHAIN_NAME>
hc clone ./examples/sample sample
You can source from files anywhere; such as a git repo you’ve cloned, a live chain you’re already running in your
.holochain directory, or one of the examples included in this repository.
Before you launch your chain, this is the chance for you to customize the application settings like the NAME, and the UUID
Testing your Application
We have designed Holochain around test-driven development, so the DNA should contain tests to confirm that the rest of the DNA is functional.
You can run a chain’s tests with:
$ hc test <CHAIN_NAME>
If you’re a developer, you should be running this command as you make changes to your DNA files to leverage test-driven development. If the tests fail, then you know your application DNA is broken and you shouldn’t think that your chain is going to work. And obviously, please do not send out applications that don’t pass their own tests.
Generate New Chain From DNA
After you have cloned a chain, you need to generate the genesis entries which start your new chain in order to use it.
$ hc gen chain <CHAIN_NAME>
The first entry is the DNA which is the hash of all the application code which 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.
Accessing the Web UI
$ hc web <CHAIN_NAME> [PORT]
In a web browser you can go to
localhost:<port> (defaults to
3141) to access UI files and send and receive JSON with exposed application functions.
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 '<[email protected]>' $ 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.
-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
Most architecture information is in the Holochain Wiki.
You can also look through auto-generated reference API on GoDocs
We accept Pull Requests and welcome your participation.
If you’d like to get involved you can: * Contact us on Gitter 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.
If you’re going to contribute to our project we expect you to adhere to the following guidelines:
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.
We use test driven development. When you add a new function or feature, be sure to add the tests that make sure it works.
For Atom, you could try this package but it requires some configuration.
To compile and run all the tests:
$ cd $GOPATH/github.com/metacurrency/holochain $ make test
If you want to use
go test instead of
make test, you’ll need to do a couple extra things because of this project’s dependency on
* Before running
go test you need to run
make work to configure the imports properly.
* If you do this, before commiting you must also run
make pub to revert the changes it makes.
Copyright © 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.
- 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.