chain: Index | Files | Directories

package protocol

import ""

Package protocol provides the logic to tie together storage and validation for a Chain Protocol blockchain.

This comprises all behavior that's common to every full node, as well as other functions that need to operate on the blockchain state.

Here are a few examples of typical full node types.


A generator has two basic jobs: collecting transactions from other nodes and putting them into blocks.

To add a transaction to the pending transaction pool, call AddTx for each one.

To add a new block to the blockchain, call GenerateBlock, sign the block (possibly collecting signatures from other parties), and call CommitBlock.


A signer validates blocks generated by the Generator and signs at most one block at each height.


A participant node in a network may select outputs for spending and compose transactions.

To publish a new transaction, prepare your transaction (select outputs, and compose and sign the tx) and send the transaction to the network's generator. To wait for confirmation, call BlockWaiter on successive block heights and inspect the blockchain state until you find that the transaction has been either confirmed or rejected. Note that transactions may be malleable if there's no commitment to TXSIGHASH.

To ingest a block, call ValidateBlock and CommitBlock.


Package Files

block.go protocol.go recover.go tx.go


var ErrBadBlock = errors.New("invalid block")

ErrBadBlock is returned when a block is invalid.

var ErrStaleState = errors.New("stale blockchain state")

ErrStaleState is returned when the Chain does not have a current blockchain state.

var (
    // ErrTheDistantFuture is returned when waiting for a blockheight
    // too far in excess of the tip of the blockchain.
    ErrTheDistantFuture = errors.New("block height too far in future")

func NewInitialBlock Uses

func NewInitialBlock(pubkeys []ed25519.PublicKey, nSigs int, timestamp time.Time) (*bc.Block, error)

type Chain Uses

type Chain struct {
    InitialBlockHash  bc.Hash
    MaxIssuanceWindow time.Duration // only used by generators
    // contains filtered or unexported fields

Chain provides a complete, minimal blockchain database. It delegates the underlying storage to other objects, and uses validation logic from package validation to decide what objects can be safely stored.

func NewChain Uses

func NewChain(ctx context.Context, initialBlockHash bc.Hash, store Store, pool Pool, heights <-chan uint64) (*Chain, error)

NewChain returns a new Chain using store as the underlying storage.

func (*Chain) AddTx Uses

func (c *Chain) AddTx(ctx context.Context, tx *bc.Tx) error

AddTx inserts tx into the set of "pending" transactions available to be included in the next block produced by GenerateBlock. It should only be called by the Generator.

It performs context-free validation of the tx, but does not validate against the current state tree.

It is okay to add the same transaction more than once; subsequent attempts will have no effect and return a nil error. It is also okay to add conflicting transactions to the pool. The conflict will be resolved when a block lands.

It is an error to call AddTx before the initial block has landed. Use BlockWaiter to guarantee this.

func (*Chain) BlockSoonWaiter Uses

func (c *Chain) BlockSoonWaiter(ctx context.Context, height uint64) <-chan error

WaitForBlockSoon returns a channel that waits for the block at the given height, but it is an error to wait for a block far in the future. WaitForBlockSoon will timeout if the context times out. To wait unconditionally, the caller should use WaitForBlock.

func (*Chain) BlockWaiter Uses

func (c *Chain) BlockWaiter(height uint64) <-chan struct{}

WaitForBlock returns a channel that waits for the block at the given height.

func (*Chain) CommitBlock Uses

func (c *Chain) CommitBlock(ctx context.Context, block *bc.Block, snapshot *state.Snapshot) error

CommitBlock commits the block to the blockchain.

This function:

* saves the block to the store.
* saves the state tree to the store (optionally).
* executes all new-block callbacks.

The block parameter must have already been validated before being committed.

func (*Chain) GenerateBlock Uses

func (c *Chain) GenerateBlock(ctx context.Context, prev *bc.Block, snapshot *state.Snapshot, now time.Time) (b *bc.Block, result *state.Snapshot, err error)

GenerateBlock generates a valid, but unsigned, candidate block from the current pending transaction pool. It returns the new block and a snapshot of what the state snapshot is if the block is applied.

After generating the block, the pending transaction pool will be empty.

func (*Chain) GetBlock Uses

func (c *Chain) GetBlock(ctx context.Context, height uint64) (*bc.Block, error)

GetBlock returns the block at the given height, if there is one, otherwise it returns an error.

func (*Chain) Height Uses

func (c *Chain) Height() uint64

Height returns the current height of the blockchain.

func (*Chain) Ready Uses

func (c *Chain) Ready() <-chan struct{}

Ready returns a channel that is closed when the chain has been recovered. This indicates that it is ready for access.

func (*Chain) Recover Uses

func (c *Chain) Recover(ctx context.Context) (*bc.Block, *state.Snapshot, error)

Recover performs crash recovery, restoring the blockchain to a complete state. It returns the latest confirmed block and the corresponding state snapshot.

If the blockchain is empty (missing initial block), this function returns a nil block and an empty snapshot.

func (*Chain) State Uses

func (c *Chain) State() (*bc.Block, *state.Snapshot)

State returns the most recent state available. It will not be current unless the current process is the leader. Callers should examine the returned block header's height if they need to verify the current state.

func (*Chain) Store Uses

func (c *Chain) Store() Store

Store returns the Store used by the blockchain.

func (*Chain) ValidateBlock Uses

func (c *Chain) ValidateBlock(ctx context.Context, prevState *state.Snapshot, prev, block *bc.Block) (*state.Snapshot, error)

ValidateBlock performs validation on an incoming block, in advance of committing the block. ValidateBlock returns the state after the block has been applied.

func (*Chain) ValidateBlockForSig Uses

func (c *Chain) ValidateBlockForSig(ctx context.Context, block *bc.Block) error

ValidateBlockForSig performs validation on an incoming _unsigned_ block in preparation for signing it. By definition it does not execute the sigscript.

func (*Chain) ValidateTxCached Uses

func (c *Chain) ValidateTxCached(tx *bc.Tx) error

ValidateTxCached checks a cache of prevalidated transactions before attempting to perform a context-free validation of the tx.

type Pool Uses

type Pool interface {
    // Insert adds a transaction to the pool.
    // It doesn't check for validity, or whether the transaction
    // conflicts with another.
    // It is required to be idempotent.
    Insert(context.Context, *bc.Tx) error

    // Dump wipes the pending transaction pool and returns all
    // transactions that were in the pool.
    Dump(context.Context) ([]*bc.Tx, error)

Pool provides storage for transactions in the pending transaction pool.

type Store Uses

type Store interface {
    Height(context.Context) (uint64, error)
    GetBlock(context.Context, uint64) (*bc.Block, error)
    LatestSnapshot(context.Context) (*state.Snapshot, uint64, error)

    SaveBlock(context.Context, *bc.Block) error
    FinalizeBlock(context.Context, uint64) error
    SaveSnapshot(context.Context, uint64, *state.Snapshot) error

Store provides storage for blockchain data: blocks and state tree snapshots.

Note, this is different from a state snapshot. A state snapshot provides access to the state at a given point in time -- outputs and issuance memory. The Chain type uses Store to load state from storage and persist validated data.


bcPackage bc provides the fundamental blockchain data structures used in the Chain Protocol.
mempoolPackage mempool provides a Pool implementation that keeps all pending transactions in memory.
memstorePackage memstore provides a Store implementation that keeps all blockchain state in memory.
patriciaPackage patricia implements a patricia tree, or a radix tree with a radix of 2 -- creating an uneven binary tree.
prottestPackage prottest provides utilities for Chain Protocol testing.
statePackage state provides types for encapsulating blockchain state.
validationPackage validation implements the Chain Protocol blockchain validation logic.
vmPackage vm implements the VM described in Chain Protocol 1.

Package protocol imports 12 packages (graph). Updated 2019-02-15. Refresh now. Tools for package owners.

The go get command cannot install this package because of the following issues: