README
¶
Chain Core Developer Edition
Chain Core is software designed to operate and connect to highly scalable permissioned blockchain networks conforming to the Chain Protocol. Each network maintains a cryptographically-secured transaction log, known as a blockchain, which allows partipicants to define, issue, and transfer digital assets on a multi-asset shared ledger. Digital assets share a common, interoperable format and can represent any units of value that are guaranteed by a trusted issuer — such as currencies, bonds, securities, IOUs, or loyalty points. Each Chain Core holds a copy of the ledger and independently validates each update, or “block,” while a federation of block signers ensures global consistency of the ledger.
Chain Core Developer Edition is a free, downloadable version of Chain Core that is open source and licensed under the AGPL. Individuals and organizations use Chain Core Developer Edition to learn, experiment, and build prototypes.
Chain Core Developer Edition can be run locally on Mac, Windows, or Linux to create a new blockchain network, connect to an existing blockchain network, or connect to the public Chain testnet, operated by Chain, Microsoft, and Cornell University’s IC3.
For more information about how to use Chain Core Developer Edition, see the docs: https://chain.com/docs
Download
To install Chain Core Developer Edition on Mac, Windows, or Linux, please visit our downloads page.
Contributing
Chain has adopted the code of conduct defined by the Contributor Covenant. It can be read in full here. This repository is the canonical source for Chain Core Developer Edition. Consequently, Chain engineers actively maintain this repository. If you are interested in contributing to this code base, please read our issue and pull request templates first.
Building from source
- Go version 1.7, with $GOPATH set to your preferred directory
- Postgres (we suggest Postgres.app), along with the command line tools
- protoc, if you need to compile protos
Environment
Set the CHAIN environment variable, in .profile in your home
directory, to point to the root of the Chain source code repo:
export CHAIN=$GOPATH/src/chain
You should also add $CHAIN/bin to your path (as well as
$GOPATH/bin, if it isn’t already):
PATH=$GOPATH/bin:$CHAIN/bin:$PATH
You might want to open a new terminal window to pick up the change.
Installation
Build and install from source:
$ git clone https://github.com/chain/chain $CHAIN
$ cd $CHAIN
$ go install ./cmd/...
Set up the database:
$ createdb core
Start Chain Core:
$ cored
Access the dashboard:
$ open http://localhost:1999/
Run tests:
$ go test $(go list ./... | grep -v vendor)
Developing Chain Core
Updating the schema with migrations
$ dumpschema
Dependencies
To add or update a Go dependency, do the following:
Copy the code from $GOPATH/src/x
to $CHAIN/vendor/x. For example, to vendor the package
github.com/kr/pretty, run
$ mkdir -p $CHAIN/vendor/github.com/kr
$ rm -r $CHAIN/vendor/github.com/kr/pretty
$ cp -r $GOPATH/src/github.com/kr/pretty $CHAIN/vendor/github.com/kr/pretty
$ rm -rf $CHAIN/vendor/github.com/kr/pretty/.git
(Note: don’t put a trailing slash (/) on these paths.
It can change the behavior of cp and put the files
in the wrong place.)
In your commit message, include the commit hash of the upstream repo
for the dependency. (You can find this with git rev-parse HEAD in
the upstream repo.) Also, make sure the upstream working tree is clean.
(Check with git status.)
Deploy Options
When Chain Core is deployed to a non-local host, all requests require authentication. To generate a client access token on Heroku, run the following command:
$ heroku run -a <your-heroku-app> corectl create-token <token-name>
<token-name>:<your-token>
License
Chain Core Developer Edition is licensed under the terms of the GNU Affero General Public License Version 3 (AGPL).
The Chain Java SDK (/sdk/java) is licensed under the terms of the
Apache License Version 2.0.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
benchcore
Command benchcore launches EC2 instances for benchmarking Chain Core.
|
Command benchcore launches EC2 instances for benchmarking Chain Core. |
|
corectl
Command corectl provides miscellaneous control functions for a Chain Core.
|
Command corectl provides miscellaneous control functions for a Chain Core. |
|
cored
Command cored provides the Chain Core daemon and API server.
|
Command cored provides the Chain Core daemon and API server. |
|
decode
Command decode reads hex-encoded Chain data structures and prints the decoded data structures.
|
Command decode reads hex-encoded Chain data structures and prints the decoded data structures. |
|
ed25519
Command ed25519 creates and manipulates ed25519 public and private keys.
|
Command ed25519 creates and manipulates ed25519 public and private keys. |
|
gobundle
Command gobundle encodes filesystem files as Go source.
|
Command gobundle encodes filesystem files as Go source. |
|
gobytes
Command gobytes prints its input as a []byte literal.
|
Command gobytes prints its input as a []byte literal. |
|
hex
Command hex encodes to or from hexadecimal.
|
Command hex encodes to or from hexadecimal. |
|
md2html
Command md2html recursively converts a directory of markdown files to html.
|
Command md2html recursively converts a directory of markdown files to html. |
|
metricsd
Command metricsd provides a daemon for collecting latencies and other metrics from cored and uploading them to librato.
|
Command metricsd provides a daemon for collecting latencies and other metrics from cored and uploading them to librato. |
|
migratedb
Command migratedb applies database migrations to the specified database.
|
Command migratedb applies database migrations to the specified database. |
|
multitool
Command multitool provides miscellaneous Chain-related commands.
|
Command multitool provides miscellaneous Chain-related commands. |
|
perfdash
Command perfdash is a web server that serves a performance dashboard for Chain Core.
|
Command perfdash is a web server that serves a performance dashboard for Chain Core. |
|
sha3
Command sha3 prints the binary SHA-3 digest of its input.
|
Command sha3 prints the binary SHA-3 digest of its input. |
|
shake
Command shake computes the SHAKE variable-output-length hash functions defined by FIPS-202.
|
Command shake computes the SHAKE variable-output-length hash functions defined by FIPS-202. |
|
testbot
Command testbot provides a web server for running Chain integeration tests.
|
Command testbot provides a web server for running Chain integeration tests. |
|
testnet-reset
Command testnet-reset is a convenient command to reset a blockchain network.
|
Command testnet-reset is a convenient command to reset a blockchain network. |
|
varint
Command varint encodes a decimal number to or from varint.
|
Command varint encodes a decimal number to or from varint. |
|
vet
Vet examines Go source code and reports suspicious constructs, such as Printf calls whose arguments do not align with the format string.
|
Vet examines Go source code and reports suspicious constructs, such as Printf calls whose arguments do not align with the format string. |
|
Package core implements Chain Core and its API.
|
Package core implements Chain Core and its API. |
|
accesstoken
Package accesstoken provides storage and validation of Chain Core credentials.
|
Package accesstoken provides storage and validation of Chain Core credentials. |
|
account
Package account stores and tracks accounts within a Chain Core.
|
Package account stores and tracks accounts within a Chain Core. |
|
asset
Package asset maintains a registry of all assets on a blockchain.
|
Package asset maintains a registry of all assets on a blockchain. |
|
blocksigner
Package blocksigner implements remote block signing.
|
Package blocksigner implements remote block signing. |
|
config
Package config manages persistent configuration data for Chain Core.
|
Package config manages persistent configuration data for Chain Core. |
|
coretest
Package coretest provides utilities for testing Chain Core.
|
Package coretest provides utilities for testing Chain Core. |
|
coreunsafe
Package coreunsafe contains Core logic that is unsafe for production.
|
Package coreunsafe contains Core logic that is unsafe for production. |
|
fetch
Package fetch implements block replication for participant Chain Cores.
|
Package fetch implements block replication for participant Chain Cores. |
|
generator
Package generator implements the Chain Core generator.
|
Package generator implements the Chain Core generator. |
|
leader
Package leader implements leader election between cored processes of a Chain Core.
|
Package leader implements leader election between cored processes of a Chain Core. |
|
migrate
Package migrate implements database migration for Chain Core.
|
Package migrate implements database migration for Chain Core. |
|
mockhsm
Package mockhsm provides a mock HSM for development environments.
|
Package mockhsm provides a mock HSM for development environments. |
|
query
Package query implements indexing and querying of annotated blockchain data.
|
Package query implements indexing and querying of annotated blockchain data. |
|
query/filter
Package filter parses and evaluates Chain filter expressions.
|
Package filter parses and evaluates Chain filter expressions. |
|
rpc
Package rpc implements Chain Core's RPC client.
|
Package rpc implements Chain Core's RPC client. |
|
signers
Package signers associates signers and their corresponding keys.
|
Package signers associates signers and their corresponding keys. |
|
txbuilder
Package txbuilder builds a Chain Protocol transaction from a list of actions.
|
Package txbuilder builds a Chain Protocol transaction from a list of actions. |
|
txdb
Package txdb provides storage for Chain Protocol blockchain data structures.
|
Package txdb provides storage for Chain Protocol blockchain data structures. |
|
txdb/internal/storage
Package storage is a generated protocol buffer package.
|
Package storage is a generated protocol buffer package. |
|
txfeed
Package txfeed implements Chain Core's transaction feeds.
|
Package txfeed implements Chain Core's transaction feeds. |
|
crypto
|
|
|
ed25519
Package ed25519 implements the Ed25519 signature algorithm.
|
Package ed25519 implements the Ed25519 signature algorithm. |
|
sha3pool
Package sha3pool is a freelist for SHA3-256 hash objects.
|
Package sha3pool is a freelist for SHA3-256 hash objects. |
|
database
|
|
|
pg
Package pg provides small utilities for the lib/pq database driver.
|
Package pg provides small utilities for the lib/pq database driver. |
|
pg/pgtest
Package pgtest provides support functions for tests that need to use Postgres.
|
Package pgtest provides support functions for tests that need to use Postgres. |
|
sql
Package sql provides a generic interface around SQL (or SQL-like) databases.
|
Package sql provides a generic interface around SQL (or SQL-like) databases. |
|
encoding
|
|
|
bitcoin
Package bitcoin encodes and decodes numbers and strings using the Bitcoin varint format.
|
Package bitcoin encodes and decodes numbers and strings using the Bitcoin varint format. |
|
blockchain
Package blockchain provides the tools for encoding data primitives in blockchain structures
|
Package blockchain provides the tools for encoding data primitives in blockchain structures |
|
Package env provides a convenient way to convert environment variables into Go data.
|
Package env provides a convenient way to convert environment variables into Go data. |
|
Package errors implements a basic error wrapping pattern, so that errors can be annotated with additional information without losing the original error.
|
Package errors implements a basic error wrapping pattern, so that errors can be annotated with additional information without losing the original error. |
|
generated
|
|
|
installer
|
|
|
Package log implements a standard convention for structured logging.
|
Package log implements a standard convention for structured logging. |
|
rotation
Package rotation writes and rotates log files.
|
Package rotation writes and rotates log files. |
|
splunk
Package splunk sends log data to a splunk server.
|
Package splunk sends log data to a splunk server. |
|
math
|
|
|
checked
Package checked implements basic arithmetic operations with underflow and overflow checks.
|
Package checked implements basic arithmetic operations with underflow and overflow checks. |
|
Package metrics provides convenient facilities to record on-line high-level performance metrics.
|
Package metrics provides convenient facilities to record on-line high-level performance metrics. |
|
http/httpjson
Package httpjson creates HTTP handlers to map request and response formats onto Go function signatures.
|
Package httpjson creates HTTP handlers to map request and response formats onto Go function signatures. |
|
http/limit
Package limit provides a rate limiting HTTP handler.
|
Package limit provides a rate limiting HTTP handler. |
|
http/reqid
Package reqid creates request IDs and stores them in Contexts.
|
Package reqid creates request IDs and stores them in Contexts. |
|
http/static
Package static provides a handler for serving static assets from an in-memory map.
|
Package static provides a handler for serving static assets from an in-memory map. |
|
os
|
|
|
program
Package program gets the filepath to the current program.
|
Package program gets the filepath to the current program. |
|
Package protocol provides the logic to tie together storage and validation for a Chain Protocol blockchain.
|
Package protocol provides the logic to tie together storage and validation for a Chain Protocol blockchain. |
|
bc
Package bc provides the fundamental blockchain data structures used in the Chain Protocol.
|
Package bc provides the fundamental blockchain data structures used in the Chain Protocol. |
|
mempool
Package mempool provides a Pool implementation that keeps all pending transactions in memory.
|
Package mempool provides a Pool implementation that keeps all pending transactions in memory. |
|
memstore
Package memstore provides a Store implementation that keeps all blockchain state in memory.
|
Package memstore provides a Store implementation that keeps all blockchain state in memory. |
|
patricia
Package patricia implements a patricia tree, or a radix tree with a radix of 2 -- creating an uneven binary tree.
|
Package patricia implements a patricia tree, or a radix tree with a radix of 2 -- creating an uneven binary tree. |
|
prottest
Package prottest provides utilities for Chain Protocol testing.
|
Package prottest provides utilities for Chain Protocol testing. |
|
state
Package state provides types for encapsulating blockchain state.
|
Package state provides types for encapsulating blockchain state. |
|
validation
Package validation implements the Chain Protocol blockchain validation logic.
|
Package validation implements the Chain Protocol blockchain validation logic. |
|
vm
Package vm implements the VM described in Chain Protocol 1.
|
Package vm implements the VM described in Chain Protocol 1. |
|
sync
|
|
|
idempotency
Package idempotency provides a duplicate function call suppression mechanism.
|
Package idempotency provides a duplicate function call suppression mechanism. |