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.8, with $GOPATH set to your preferred directory
- Postgres (we suggest Postgres.app), along with the command line tools
- protoc 3.1.0 and protoc-gen-g, if you need to compile protos
- CMake 3.4 or later, to compile RocksDB and its dependencies
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=$(go env GOPATH)/src/chain
You should also add $CHAIN/bin to your path (as well as
$(go env GOPATH)/bin, if it isn’t already):
PATH=$(go env GOPATH)/bin:$CHAIN/bin:$PATH
You might want to open a new terminal window to pick up the change.
Installation
Clone this repository to $CHAIN:
$ git clone https://github.com/chain/chain $CHAIN
$ cd $CHAIN
You can build Chain Core using the build-cored-release script.
The build product allows connections over HTTP, unauthenticated
requests from localhost, and the ability to reset the Chain Core.
build-cored-release accepts a accepts a Git ref (branch, tag, or commit SHA)
from the chain repository and an output directory:
$ ./bin/build-cored-release chain-core-server-1.2.0 .
This will create two binaries in the current directory:
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)
Building from source
There are four build tags that change the behavior of the resulting binary:
reset: allows the core database to be reset through the apilocalhost_auth: allows unauthenticated requests on the loopback device (localhost)no_mockhsm: disables the MockHSM provided for developmenthttp_ok: allows plain HTTP requestsinit_cluster: automatically creates a single process cluster
The default build process creates a binary with three build tags enabled for a friendlier experience. To build from source with build tags, use the following command:
NOTE: when building from source, make sure to check out a specific tag to build. The
mainbranch is not considered stable, and may contain in progress features or an inconsistent experience.
$ go build -tags 'http_ok localhost_auth init_cluster' chain/cmd/cored
$ go build chain/cmd/corectl
Developing Chain Core
Updating the schema with migrations
$ go run cmd/dumpschema/main.go
Dependencies
To add or update a Go dependency at import path x, do the following:
Copy the code from the package's directory
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 $(go list -f {{.Dir}} 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.)
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. |
|
chainvet
chainvet examines Go source code and reports suspicious constructs, such as Printf calls whose arguments do not align with the format string.
|
chainvet examines Go source code and reports suspicious constructs, such as Printf calls whose arguments do not align with the format string. |
|
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. |
|
docgenerate
Command docgenerate generates static documentation for Chain Core and the Chain Core SDKs.
|
Command docgenerate generates static documentation for Chain Core and the Chain Core SDKs. |
|
docsync
Command docsync uploads a local directory to a specified S3 bucket
|
Command docsync uploads a local directory to a specified S3 bucket |
|
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. |
|
integtest
Command integtest compiles and runs a command to perform integration tests on Chain Core and related systems.
|
Command integtest compiles and runs a command to perform integration tests on Chain Core and related systems. |
|
md2html
Command md2html recursively converts a directory of markdown files to html.
|
Command md2html recursively converts a directory of markdown files to html. |
|
mdfmt
Command mdfmt canonicalizes the formatting of a Markdown document.
|
Command mdfmt canonicalizes the formatting of a Markdown document. |
|
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. |
|
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. |
|
report
Command report executes its argument as a child process and reports the results to S3.
|
Command report executes its argument as a child process and reports the results to S3. |
|
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. |
|
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. |
|
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. |
|
config/internal/configpb
Package configpb is a generated protocol buffer package.
|
Package configpb is a generated protocol buffer package. |
|
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
|
|
|
localdb
Package localdb provides an interface for storing local data.
|
Package localdb provides an interface for storing local data. |
|
localdb/internal/localdbtest
Package localdbtest is a generated protocol buffer package.
|
Package localdbtest is a generated protocol buffer package. |
|
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. |
|
sinkdb
Package sinkdb provides a strongly consistent key-value store.
|
Package sinkdb provides a strongly consistent key-value store. |
|
sinkdb/internal/sinkpb
Package sinkpb is a generated protocol buffer package.
|
Package sinkpb is a generated protocol buffer package. |
|
sqlutil
Package sqlutil provides SQL-related utility functions.
|
Package sqlutil provides SQL-related utility functions. |
|
desktop
|
|
|
encoding
|
|
|
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 |
|
bufpool
Package bufpool is a freelist for bytes.Buffer objects.
|
Package bufpool is a freelist for bytes.Buffer objects. |
|
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. |
|
exp
|
|
|
ivy/compiler
Package ivy provides a compiler for Chain's Ivy contract language.
|
Package ivy provides a compiler for Chain's Ivy contract language. |
|
generated
|
|
|
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/authz
Package authz is a generated protocol buffer package.
|
Package authz is a generated protocol buffer package. |
|
http/httperror
Package httperror defines the format for HTTP error responses from Chain services.
|
Package httperror defines the format for HTTP error responses from Chain services. |
|
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/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. |
|
raft
Package raft provides raft coordination.
|
Package raft provides raft coordination. |
|
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 is a generated protocol buffer package.
|
Package bc is a generated protocol buffer package. |
|
bc/bctest
Package bctest provides utilities for constructing blockchain data structures.
|
Package bctest provides utilities for constructing blockchain data structures. |
|
patricia
Package patricia computes the Merkle Patricia Tree Hash of a set of bit strings, as described in the Chain Protocol spec.
|
Package patricia computes the Merkle Patricia Tree Hash of a set of bit strings, as described in the Chain Protocol spec. |
|
prottest
Package prottest provides utilities for Chain Protocol testing.
|
Package prottest provides utilities for Chain Protocol testing. |
|
prottest/memstore
MemStore is a Store implementation that keeps all blockchain state in memory.
|
MemStore is a Store implementation that keeps all blockchain state in memory. |
|
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. |