{"id":13483207,"url":"https://github.com/holochain/holochain-proto","last_synced_at":"2025-03-27T14:30:42.828Z","repository":{"id":57501696,"uuid":"77254236","full_name":"holochain/holochain-proto","owner":"holochain","description":"Holographic storage for distributed applications -- a validating monotonic DHT \"backed\" by authoritative hashchains for data provenance (a Ceptr sub-project)","archived":true,"fork":false,"pushed_at":"2020-09-15T07:34:20.000Z","size":4732,"stargazers_count":880,"open_issues_count":281,"forks_count":143,"subscribers_count":157,"default_branch":"develop","last_synced_at":"2025-03-24T01:40:43.973Z","etag":null,"topics":["blockchain","ceptr","chain","dht","distributed","golang"],"latest_commit_sha":null,"homepage":"http://holochain.org","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/holochain.png","metadata":{"files":{"readme":"README.md","changelog":"change.go","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-12-23T22:40:27.000Z","updated_at":"2025-03-21T17:17:25.000Z","dependencies_parsed_at":"2022-09-13T02:40:28.145Z","dependency_job_id":null,"html_url":"https://github.com/holochain/holochain-proto","commit_stats":null,"previous_names":["metacurrency/holochain"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/holochain%2Fholochain-proto","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/holochain%2Fholochain-proto/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/holochain%2Fholochain-proto/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/holochain%2Fholochain-proto/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/holochain","download_url":"https://codeload.github.com/holochain/holochain-proto/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245862956,"owners_count":20684759,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blockchain","ceptr","chain","dht","distributed","golang"],"created_at":"2024-07-31T17:01:09.083Z","updated_at":"2025-03-27T14:30:42.055Z","avatar_url":"https://github.com/holochain.png","language":"Go","funding_links":[],"categories":["Go","Applications"],"sub_categories":["Data Storage and Sharing"],"readme":"# Holochain\n\n[![Code Status](https://img.shields.io/badge/Code-Alpha-yellow.svg)](https://github.com/holochain/holochain-proto/milestones?direction=asc\u0026sort=completeness\u0026state=all)\n[![Travis](https://img.shields.io/travis/holochain/holochain-proto/master.svg)](https://travis-ci.org/holochain/holochain-proto/branches)\n[![Codecov](https://img.shields.io/codecov/c/github/holochain/holochain-proto.svg)](https://codecov.io/gh/holochain/holochain-proto/branch/master)\n[![Go Report Card](https://goreportcard.com/badge/github.com/holochain/holochain-proto)](https://goreportcard.com/report/github.com/holochain/holochain-proto)\n[![License: GPL v3](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](http://www.gnu.org/licenses/gpl-3.0)\n[![Twitter Follow](https://img.shields.io/twitter/follow/holochain.svg?style=social\u0026label=Follow)](https://twitter.com/holochain)\n\n### Code Status\nAlpha. Not for production use. The code has not yet undergone a security audit. You should expect unstable APIs and data chains. \n\n**NOT CURRENT REPOSITORY** Holochain has been rebuilt in Rust, and this Go codebase is not maintained. Please see the [NEW REPOSITORY](https://github.com/holochain/holochain) for an updated and supported version.\n\n### Holographic storage for distributed applications\nHolochain uses 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.\n\nIn other words, Holochain apps function 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.\n\n#### History\nProof-of-concept was unveiled at our first hackathon (March 2017). Alpha 0 was released October 2017.  Alpha 1 was released May 2018.\n\u003cbr/\u003e\n\n| Holochain Links: | [FAQ](https://github.com/holochain/holochain-proto/wiki/FAQ) | [Developer Wiki](https://developer.holochain.org) | [White Paper](https://github.com/holochain/holochain-proto/blob/whitepaper/holochain.pdf) | [GoDocs](https://godoc.org/github.com/holochain/holochain-proto) |\n|---|---|---|---|---|\n\n**Table of Contents**\n\n\u003c!-- TOC depthFrom:2 depthTo:4 withLinks:1 updateOnSave:1 orderedList:0 --\u003e\n\n- [Installation](#installation)\n\t- [Quick Install](#quick-install)\n\t- [Go Based Install](#go-based-install)\n\t\t- [Unix](#unix)\n\t\t- [Windows](#windows)\n\t- [Docker Based Install](#docker-based-install)\n- [Usage](#usage)\n\t- [Getting Started](#getting-started)\n\t  - [Initializing the Holochain environment](#initializing-the-holochain-environment)\n\t  - [Joining a Holochain](#joining-a-holochain)\n\t  - [Running a Holochain](#running-a-holochain)\n\t- [Developing a Holochain](#developing-a-holochain)\n\t  - [Test-driven Application Development Locations](#test-driven-application-development)\n\t  - [File Locations](#file-locations)\n\t  - [Logging](#logging)\n\t- [Multi-instance Integration Testing](#multi-instance-integration-testing)\n- [Architecture Overview and Documentation](#architecture-overview-and-documentation)\n- [Holochain Core Development](#development)\n\t- [Contribute](#contribute)\n\t- [Dependencies](#dependencies)\n\t- [Tests](#tests)\n- [License](#license)\n- [Acknowledgements](#acknowledgements)\n\n\u003c!-- /TOC --\u003e\n\n## Installation\n**Developers Only:** At this stage, holochain is only for use by developers (either developers of applications to run on holochains, or developers of the holochain software itself). App developers should bundle their app in an installer as either approach below is not for non-technical folks.\n\nThere are two approaches to installing holochain:\n1. as a standard Go language application for direct execution on your machine\n2. using [docker](https://www.docker.com/) for execution in a container.\n\nWhich you choose depends on your preference and your purpose.  If you intend to develop holochain applications, then you should almost certainly use the docker approach as we provide a testing harness for running multiple holochain instances in a docker cluster.  If you will be developing in Go on holochain itself then you will probably end up doing both.\n\n### Quick Install\n1. Download the most recent release (https://github.com/holochain/holochain-proto/releases/) for your OS.\n2. Unzip it to your directory of choice (or compile it from source).\n3. Add that directory to your PATH if you want to call holochain-proto commands outside of that directory (this step differs by OS).\n4. The commands listed in the 'Usage' section should now be available.\n\n### Go Based Install\n\n#### Unix\n(Unix includes macOS and Linux.)\n\n1. [Download Go](https://golang.org/dl/). Download the \"Archive\" or \"Installer\" for version 1.8 or later for your CPU and OS. The \"Source\" download does not contain an executable and step 3 will fail.\n2. [Install Go](https://golang.org/doc/install) on your system.  See platform specific instructions and hints below for making this work.\n3. Setup your path (Almost all installation problems that have been reported stem from skipping this step.)\n\n    * Export the `$GOPATH` variable in your shell profile.\n    * Add `$GOPATH/bin` to your `$PATH` in your shell profile.\n\n    For example, add the following to the end of your shell profile (usually `~/.bashrc` or `~/.bash_profile`):\n````bash\n        export GOPATH=\"$HOME/go\"\n        export PATH=\"$GOPATH/bin:$PATH\"\n````\n\n4. Install the command line tool suite with:\n\n```bash\n$ go get -d -v github.com/holochain/holochain-proto\n$ cd $GOPATH/src/github.com/holochain/holochain-proto\n$ make\n```\n\n5. Test that it works (should look something like this):\n\n```bash\n$ hcadmin -v\nhcadmin version 0.0.x (holochain y)\n```\n\n#### Windows\nFirst you'll need to install some necessary programs if you don't already have them.\n* [Download Go](https://golang.org/dl/). Download the \"Archive\" or \"Installer\" for version 1.8 or later for Windows and your CPU. The \"Source\" download does not contain an executable.\n* [Install Windows git](https://git-scm.com/downloads). Be sure to select the appropriate options so that git is accessible from the Windows command line.\n* Optional: [Install GnuWin32 make](http://gnuwin32.sourceforge.net/packages/make.htm#download).\n\nNext, in your Control Panel, select *System\u003eAdvanced system settings\u003eEnvironment Variables...* and under *System Variables* do the following:\n1. Add a new entry with the name `GOPATH` and the value `%USERPROFILE%\\go` (Or your Go workspace folder).\n2. Double-click Path, and in the window that pops up add the following entries:\n    - `%GOPATH%\\bin`\n    - `C:\\Go\\bin` (Or wherever you installed Go to+`\\bin`).\n    - `C:\\Program Files (x86)\\GnuWin32\\bin` (Or wherever you installed GnuWin32 make to+`\\bin`).\n\n### Docker Based Install\nUsing docker, you don't have to install Go first. Our docker scripts manage installation of Go, holochain dependencies and holochain. The docker installation can run alongside Local (\"Go\") installation of holochain, sharing config directories.  See [docker usage](https://github.com/holochain/holochain-proto/wiki/Docker-Usage) on our wiki for more on how this works.\n\n1. Install the latest version of Docker on your machine\n    1. [Docker Installation](https://docs.docker.com/engine/installation/). The Community edition; stable is sufficient.\n    2. See [Docker Getting Started](https://docs.docker.com/engine/getstarted/step_one/) for help.\n    3. It is recommended to add your user to the `docker` group as in: [Post Installation Steps](https://docs.docker.com/engine/installation/linux/linux-postinstall/), rather than use `sudo` before all script commands. Holochain Apps cannot exploit the kinds of security concerns mentioned in the Post Installation Steps document.\n\u0026nbsp;\n1. Confirm that docker installation and permissions are working by running:\n\t```bash\n\t\t$ docker info\n\t```\n\n1. Pull our holochain image from docker hub:\n\t```bash\n\t\t$ docker pull holochain/holochain-proto:develop\n\t```\n1. To run holochain in your new environment, suitable to continue the walkthrough below in [usage](#usage)\n\t```bash\n\t\t$ docker run --rm -it --name clutter -p 3141:3141 holochain/holochain-proto:develop\n\t```\n1. This will put you into an new command shell that may behave differently than what you're used to. To exit this holochain (Alpine) shell, press `Ctrl-D` or type `exit`\n\n## Usage\nThese instructions are for using the holochain command line tool suite: `hcadmin`, `hcdev` and `hcd`.  They should work equally well for Go based or docker based installation.\n\n(Note that since Holochain is intended to be used behind distributed applications, end users should not have to do much through the command or may not have it installed at all, as the application will probably have wrapped up the holochain library internally.)\n\nEach of the tools includes a help command, e.g., run `hcadmin help` or for sub-commands run `hcadmin \u003cCOMMAND\u003e help`. For more detailed information, see [the wiki page](https://developer.holochain.org/Command_Line_Tools)\n\nThe tool suite include these commands:\n\n- `hcadmin` for administering your installed holochain applications\n- `hcd` for running and serving a holochain application\n- `hcdev` for developing and testing holochain applications\n\n### Getting Started\n\nThe instructions below walk you through the basic steps necessary to run a holochain application.\n\n#### Initializing the Holochain environment\n\n```bash\n\t$ hcadmin init 'your@emailaddress.here'\n```\nThis command creates a `~/.holochain` directory for storing all chain data, along with initial public/private key pairs based on the identity string provided as the second argument.\n\n#### Joining a Holochain\n\nYou can use the `hcadmin` tool to join a pre-existing Holochain application 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).\n\nFor example: `hcadmin join ./examples/chat chat`\n\nNote: this command will be replaced by a package management command still in development.\n\n#### Running a Holochain\nHolochains run and serve their UI via local web sockets. This allows interface developers lots of freedom to build HTML/JavaScript files and drop them in that chain's UI directory. You start a holochain and activate it's UI with the `hcd` command:\n\n```bash\n$ hcd \u003cCHAIN_NAME\u003e [PORT]\n```\n\n### Developing a Holochain\n\nThe `hcdev` tool allows you to:\n\n1. generate new holochain application source files by cloning from an existing application, from a [package file](https://metacurrency.github.io/hc-scaffold), or a simple empty template.\n2. run stand-alone or multi-node scenario tests\n3. run a holochain and serve it's UI for testing purposes\n4. dump out chain and dht data for inspection\n\nPlease see the docs for more [detailed documentation](https://developer.holochain.org/Command_Line_Tools).\n\nNote that the `hcdev` command creates a separate ~/.holochaindev directory for serving and managing chains, so your dev work won't interfere with any running holochain apps you may be using.\n\n#### Test-driven Application Development\nWe have designed Holochain around test-driven development, so the DNA should contain tests to confirm that the rest of the DNA is functional.  Our testing harness includes two types of testing, stand-alone and multi-instance scenarios.  Stand-alone tests allow you to tests the functions you create in your application.  However, testing a distributed application requires being able to spin up many instances of it and have them interact. Our docker cluster testing harness automates that process, and enables app developers to specify scenarios and roles and test instructions to run on multiple docker containers.\n\nPlease see the [App Testing](https://developer.holochain.org/Test_Driven_Development) documentation for details.\n\n\n#### File Locations\nBy default holochain data and configuration files are assumed to be stored in the `~/.holochain` directory.  You can override this with the `-path` flag or by setting the `HOLOPATH` environment variable, e.g.:\n```bash\n$ hcadmin -path ~/mychains init '\u003cmy@other.identity\u003e'\n$ HOLOPATH=~/mychains hcadmin\n```\nYou can use the form: `hcadmin -path=/your/path/here` but you must use the absolute path, as shell substitutions will not happen.\n\n#### Logging\nAll the commands take a `--debug` flag which will turn on a number of different kinds of debugging. For running chains, 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 `HCDEBUG` environment variable to 0 or 1 to temporarily override your settings to turn everything on or off.  See also the [Environment Variable](https://developer.holochain.org/Environment_Variables) documentation for more granular logging control.\n\n## Architecture Overview and Documentation\nArchitecture information and application developer documentation is in our [developer.holochain.org](https://developer.holochain.org).\n\nYou can also look through auto-generated [reference API on GoDocs](https://godoc.org/github.com/holochain/holochain-proto)\n\n## Holochain Core Development\nWe accept Pull Requests and welcome your participation. Please make sure to\ninclude the issue number your branch names and use descriptive commit messages.\n\n* Chat with us on our [Chat Server](https://chat.holochain.org) or [Gitter](https://gitter.im/metacurrency/holochain)\n\n### Contribute\nContributors to this project are expected to follow our [development protocols \u0026 practices](https://github.com/holochain/holochain-proto/wiki/Development-Protocols).\n\n### Getting started\nOnce you have followed the basic \"getting started\" guide above you will have the\nCLI tools installed locally.\n\nAll the commands (`hcadmin`, `hcd`, `hcdev`, etc.) are built from the same repo:\n\n```bash\n$ cd $GOPATH/src/github.com/holochain/holochain-proto\n```\n\nGo will throw errors complaining about not being on the `$GOPATH` if you try to\nrun `make` from a separate copy of the `holochain-proto` repository. If you want\nto contribute to Holochain core you must work in the repository created by Go.\n\nThe `Makefile` contains all the build commands for Holochain. If you make an\nupdate to a command you will need to rebuild it before the changes take effect\nat the command line.\n\nE.g. After making an update to `cmd/hcdev/hcdev.go` run `$ make hcdev` then run\n`$ hcdev` as normal.\n\n### Dependencies\nThis project depends on various parts of [libp2p](https://github.com/libp2p/go-libp2p), which uses the [gx](https://github.com/whyrusleeping/gx) package manager. All of\nwhich will be automatically installed by make by following the [setup instructions](#installation) above.\n\nThe package manager rewrites files that are tracked by git to configure imports.\nBe careful not to commit the generated imports to git!\n\n`make work` adds the imports to the repository and `make pub` reverts them.\n\nEvery `make` command should automatically add and remove imports for you. If a\n`make` command is leaving mess behind in the repo, please open a bug report.\n\nIf you want to use `go` commands directly (e.g. `go test`) then you need to run\n`make work` manually first and remember to `make pub` before committing any\nchanges.\n\n### Tests\nTo compile and run all the tests:\n```bash\n$ cd $GOPATH/src/github.com/holochain/holochain-proto\n$ make test\n```\n\n`go test` can be used instead of `make test`, but only after `make work`.\n\nThe docker setup runs tests automatically during builds.\n\n## License\n[![License: GPL v3](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](http://www.gnu.org/licenses/gpl-3.0)\n\nCopyright (C) 2018, The MetaCurrency Project (Eric Harris-Braun, Arthur Brock, et. al.)\n\nThis 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.\n\n**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.\n\n## Acknowledgements\n* **MetaCurrency \u0026 Ceptr**: Holochains are a sub-project of [Ceptr](http://ceptr.org) which is a semantic, distributed computing platform under development by the [MetaCurrency Project](http://metacurrency.org).\n\u0026nbsp;\n* **Ian Grigg**: Some of our initial plans for this architecture were inspired in 2006 by [his paper about Triple Entry Accounting](http://iang.org/papers/triple_entry.html) and his work on [Ricardian Contracts](http://iang.org/papers/ricardian_contract.html).\n\u0026nbsp;\n* **Juan Benet \u0026 the IPFS team**: For all their work on IPFS, libp2p, and various cool tools like multihash, multiaddress, etc. We use libP2P library for our transport layer and kademlia dht.\n\u0026nbsp;\n* **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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fholochain%2Fholochain-proto","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fholochain%2Fholochain-proto","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fholochain%2Fholochain-proto/lists"}