consensus

Documentation

Overview

Package consensus implements different Evrynet consensus engines.

Package consensus implements different Evrynet consensus engines.

Index

• Constants
• Variables
• type Broadcaster
• type ChainReader
• type Engine
• type FullChainReader
• type Handler
• type Peer
• type PoW
• type Tendermint

Constants

const (
	// TendermintMsg is the new message belong to evr/64.
	// it notify the protocol handler that this is a message for tendermint consensus purpose
	TendermintMsg = 0x11
)

Variables

var (
	// ErrUnknownAncestor is returned when validating a block requires an ancestor
	// that is unknown.
	ErrUnknownAncestor = errors.New("unknown ancestor")

	// ErrPrunedAncestor is returned when validating a block requires an ancestor
	// that is known, but the state of which is not available.
	ErrPrunedAncestor = errors.New("pruned ancestor")

	// ErrFutureBlock is returned when a block's timestamp is in the future according
	// to the current node.
	ErrFutureBlock = errors.New("block in the future")

	// ErrInvalidNumber is returned if a block's number doesn't equal it's parent's
	// plus one.
	ErrInvalidNumber = errors.New("invalid block number")
)

Types

type Broadcaster

type Broadcaster interface {
	// FindPeers retrives peers by addresses
	FindPeers(map[common.Address]bool) map[common.Address]Peer
	// Enqueue add a block into fetcher queue
	Enqueue(id string, block *types.Block)
}

Broadcaster defines the interface to enqueue blocks to fetcher and find peer

type ChainReader

type ChainReader interface {
	// Config retrieves the blockchain's chain configuration.
	Config() *params.ChainConfig

	// CurrentHeader retrieves the current header from the local chain.
	CurrentHeader() *types.Header

	// GetHeader retrieves a block header from the database by hash and number.
	GetHeader(hash common.Hash, number uint64) *types.Header

	// GetHeaderByNumber retrieves a block header from the database by number.
	GetHeaderByNumber(number uint64) *types.Header

	// GetHeaderByHash retrieves a block header from the database by its hash.
	GetHeaderByHash(hash common.Hash) *types.Header

	// GetBlock retrieves a block from the database by hash and number.
	GetBlock(hash common.Hash, number uint64) *types.Block
}

ChainReader defines a small collection of methods needed to access the local blockchain during header and/or uncle verification.

type Engine

type Engine interface {
	// Author retrieves the Evrynet address of the account that minted the given
	// block, which may be different from the header's coinbase if a consensus
	// engine is based on signatures.
	Author(header *types.Header) (common.Address, error)

	// VerifyHeader checks whether a header conforms to the consensus rules of a
	// given engine. Verifying the seal may be done optionally here, or explicitly
	// via the VerifySeal method.
	VerifyHeader(chain ChainReader, header *types.Header, seal bool) error

	// VerifyHeaders is similar to VerifyHeader, but verifies a batch of headers
	// concurrently. The method returns a quit channel to abort the operations and
	// a results channel to retrieve the async verifications (the order is that of
	// the input slice).
	VerifyHeaders(chain ChainReader, headers []*types.Header, seals []bool) (chan<- struct{}, <-chan error)

	// VerifyUncles verifies that the given block's uncles conform to the consensus
	// rules of a given engine.
	VerifyUncles(chain ChainReader, block *types.Block) error

	// VerifySeal checks whether the crypto seal on a header is valid according to
	// the consensus rules of the given engine.
	VerifySeal(chain ChainReader, header *types.Header) error

	// Prepare initializes the consensus fields of a block header according to the
	// rules of a particular engine. The changes are executed inline.
	Prepare(chain FullChainReader, header *types.Header) error

	// Finalize runs any post-transaction state modifications (e.g. block rewards)
	// but does not assemble the block.
	//
	// Note: The block header and state database might be updated to reflect any
	// consensus rules that happen at finalization (e.g. block rewards).
	Finalize(chain FullChainReader, header *types.Header, state *state.StateDB, txs []*types.Transaction,
		uncles []*types.Header) error

	// FinalizeAndAssemble runs any post-transaction state modifications (e.g. block
	// rewards) and assembles the final block.
	//
	// Note: The block header and state database might be updated to reflect any
	// consensus rules that happen at finalization (e.g. block rewards).
	FinalizeAndAssemble(chain FullChainReader, header *types.Header, state *state.StateDB, txs []*types.Transaction,
		uncles []*types.Header, receipts []*types.Receipt) (*types.Block, error)

	// Seal generates a new sealing request for the given input block and pushes
	// the result into the `results` channel.
	//
	// This function will be invoked immediately after the mining worker has a new
	//     mining task. It also means this function can be invoked multiple times
	//     for the same block height.
	//
	// - block: this block is expected to be modified (normally its header) to
	//     to including sealing requirement of the consensus engine. For example
	//     the nonce, mixhash and block hash will be updated in ethash, extradata
	//     and block hash will be updated in clique...
	// - results channel: this channel expects to receive 1 or more blocks after
	//     they are sealed. Those blocks will be checked against the chain and
	//     used to append to the chain, the state tree will be updated
	//     immediately then.
	// - stop channel: this channel will be closed when the miner worker has
	//     another mining task (block). A new mining task can appear during
	//     the current one.
	//
	// Note, the method returns immediately and will send the result async. More
	// than one result may also be returned depending on the consensus algorithm.
	Seal(chain ChainReader, block *types.Block, results chan<- *types.Block, stop <-chan struct{}) error

	// SealHash returns the hash of a block prior to it being sealed.
	// This hash will be used BY miner worker as the mining task identifier (mining is not limited to POW, it refers to the process to
	// come to a consensus of a block to add to the chain).
	SealHash(header *types.Header) common.Hash

	// CalcDifficulty is the difficulty adjustment algorithm. It returns the difficulty
	// that a new block should have.
	CalcDifficulty(chain ChainReader, time uint64, parent *types.Header) *big.Int

	// APIs returns the RPC APIs this consensus engine provides.
	APIs(chain ChainReader) []rpc.API

	// Close terminates any background threads maintained by the consensus engine.
	Close() error
}

Engine is an algorithm agnostic consensus engine. Note: Prepare, Finalize and FinalizeAndAssemple are used in order to populate all of the necessary header fields including the state root. Remember that in order to have state root, the state db must be updated with some post transaction effect such as block reward or anything, up to the consensus algorithm.

type FullChainReader

type FullChainReader interface {
	ChainReader
	// StateAt returns a new mutable state based on a particular point in time.
	StateAt(hash common.Hash) (*state.StateDB, error)
}

FullChainReader extends ChainReader with function StateAt to get validators for tendermint consensus

type Handler

type Handler interface {
	// HandleNewChainHead handles a new head block comes
	HandleNewChainHead(blockNumber *big.Int) error

	// HandleMsg handles a message from peer
	HandleMsg(address common.Address, data p2p.Msg) (bool, error)

	// SetBroadcaster sets the broadcaster to send message to peers
	SetBroadcaster(Broadcaster)
}

Handler should be implemented is the consensus needs to handle and send peer's message

type Peer

type Peer interface {
	// Send sends the message to this peer
	Send(msgcode uint64, data interface{}) error
	// Address return the address of a peer
	Address() common.Address
}

Peer defines the interface to communicate with peer

type PoW

type PoW interface {
	Engine

	// Hashrate returns the current mining hashrate of a PoW consensus engine.
	Hashrate() float64
}

PoW is a consensus engine based on proof-of-work.

type Tendermint

type Tendermint interface {
	Engine

	// Start starts the engine
	Start(chain FullChainReader, currentBlock func() *types.Block, verifyAndSubmitBlock func(*types.Block) error) error

	// Stop stops the engine
	Stop() error

	//Address return the coinbase of the engine
	Address() common.Address
}

Tendermint is a consensus engine to avoid byzantine failure