tendermint

README

Tendermint consensus for NeuralChain

init

-- TOBE written

metrics collections:

The specific metrics required for tunning Tendermint consensus is implemented and can be collected with flag

--metrics --metrics.influxdb 

when running normal ./gev command. Note that the influxDB instance has to be preconfigured to store the metrics required.

To achieve the requied metrics, table manipulation is required as metrics are collected as raw counter over time. The available metrics are in the following measurements:

gev.eth/consensus/tendermint/in/packets.meter
gev.eth/consensus/tendermint/in/traffic.meter
gev.eth/consensus/tendermint/out/packets.meter
gev.eth/consensus/tendermint/out/traffic.meter
gev.eth/consensus/tendermint/proposalwait.timer
gev.eth/consensus/tendermint/rounds.meter

The other metrics (tx/blocks per second etc...) are available in normal NeuralChain metrics

Documentation

Index

• Variables
• type Backend
• type Config
  • func (cfg *Config) Commit(t time.Time) time.Time
  • func (cfg *Config) PrecommitCatchupTimeout(round int64) time.Duration
  • func (cfg *Config) PrecommitTimeout(round int64) time.Duration
  • func (cfg *Config) PrevoteCatchupTimeout(round int64) time.Duration
  • func (cfg *Config) PrevoteTimeout(round int64) time.Duration
  • func (cfg Config) ProposeTimeout(round int64) time.Duration
• type FaultyMode
  • func (f FaultyMode) Uint64() uint64
• type FinalCommittedEvent
• type MessageEvent
• type NewBlockEvent
• type ProposalSelector
• type ProposerPolicy
• type StopCoreEvent
• type Validator
• type ValidatorSet
• type Validators
  • func (slice Validators) Len() int
  • func (slice Validators) Less(i, j int) bool
  • func (slice Validators) Swap(i, j int)
• type View

Variables

var (
	// ErrStartedEngine is returned if the engine is already started
	ErrStartedEngine = errors.New("engine is already started")
	// ErrStoppedEngine is returned if the engine is stopped
	ErrStoppedEngine = errors.New("engine is already stopped")
	// ErrEmptyCommittedSeals is returned if the field of committed seals is zero.
	ErrEmptyCommittedSeals = errors.New("zero committed seals")
	// ErrEmptyValSet is returned if the field of validator set is zero.
	ErrEmptyValSet = errors.New("zero validator set")
	// ErrMismatchValSet is returned if the field of validator set is mismatch.
	ErrMismatchValSet = errors.New("mismatch validator set")
	// ErrMismatchTxhashes is returned if the TxHash in header is mismatch.
	ErrMismatchTxhashes = errors.New("mismatch transaction hashes")
	// errInvalidSignature is returned when given signature is not signed by given
	// address.
	ErrInvalidSignature = errors.New("invalid signature")
	// errUnknownBlock is returned when the list of validators is requested for a block
	// that is not part of the local blockchain.
	ErrUnknownBlock = errors.New("unknown block")
	// errUnauthorized is returned if a header is signed by a non authorized entity.
	ErrUnauthorized = errors.New("unauthorized")
	// errInvalidDifficulty is returned if the difficulty of a block is not 1
	ErrInvalidDifficulty = errors.New("invalid difficulty")
	// errInvalidExtraDataFormat is returned when the extra data format is incorrect
	ErrInvalidExtraDataFormat = errors.New("invalid extra data format")
	// errInvalidMixDigest is returned if a block's mix digest is not Tendermint digest.
	ErrInvalidMixDigest = errors.New("invalid Tendermint mix digest")
	// errInvalidCommittedSeals is returned if the committed seal is not signed by any of parent validators.
	ErrInvalidCommittedSeals = errors.New("invalid committed seals")
	// errInvalidVotingChain is returned if an authorization list is attempted to
	// be modified via out-of-range or non-contiguous headers.
	ErrInvalidVotingChain = errors.New("invalid voting chain")
	// errCoinBaseInvalid is returned if the value of coin base is not equals proposer's address in header
	ErrCoinBaseInvalid = errors.New("invalid coin base address")
	// errInvalidUncleHash is returned if a block contains an non-empty uncle list.
	ErrInvalidUncleHash = errors.New("non empty uncle hash")
	// errInvalidVote is returned if a nonce value is something else that the two
	// allowed constants of 0x00..0 or 0xff..f.
	ErrInvalidVote = errors.New("vote nonce not 0x0000000000000000 or 0xffffffffffffffff")
	// errInvalidCandidate is return if the extra data's modifiedValidator is empty or nil
	ErrInvalidCandidate = errors.New("candidate for validator is invalid")
	// ErrUnknownParent is return when a proposal is sent with unknown parent hash
	ErrUnknownParent = errors.New("unknown parent")
	// ErrFinalizeZeroBlock is returned if node finalize with block number = 0
	ErrFinalizeZeroBlock = errors.New("finalize zero block")
)

var DefaultConfig = &Config{
	ProposerPolicy:        RoundRobin,
	Epoch:                 30000,
	StakingSCAddress:      &common.Address{},
	BlockPeriod:           1,
	TimeoutPropose:        3000 * time.Millisecond,
	TimeoutProposeDelta:   500 * time.Millisecond,
	TimeoutPrevote:        1000 * time.Millisecond,
	TimeoutPrevoteDelta:   500 * time.Millisecond,
	TimeoutPrecommit:      1000 * time.Millisecond,
	TimeoutPrecommitDelta: 500 * time.Millisecond,
	TimeoutCommit:         1000 * time.Millisecond,
	FaultyMode:            Disabled.Uint64(),
	UseEVMCaller:          false,
	IndexStateVariables:   staking.DefaultConfig,
}

Types

type Backend

type Backend interface {
	// Address returns the NeuralChain address of the node running this backend
	Address() common.Address

	// EventMux returns the event mux used for Core to subscribe/ send events back to Backend.
	// Think of it as pub/sub models
	EventMux() *event.TypeMux

	// Sign signs input data with the backend's private key
	Sign([]byte) ([]byte, error)

	// Gossip sends a message to all validators (exclude self)
	// these message are send via p2p network interface.
	Gossip(valSet ValidatorSet, blockNumber *big.Int, round int64, msgType uint64, payload []byte) error

	// Broadcast sends a message to all validators (including self)
	// It will call gossip and post an identical event to its EventMux().
	Broadcast(valSet ValidatorSet, blockNumber *big.Int, round int64, msgType uint64, payload []byte) error

	// Multicast sends a message to a group of given address
	// returns error if sending is failed, or not found the targets address
	Multicast(targets map[common.Address]bool, payload []byte) error

	// Validators returns the validator set
	// we should only use this method when core is started.
	Validators(blockNumber *big.Int) ValidatorSet

	// CurrentHeadBlock get the current block of from the canonical chain.
	CurrentHeadBlock() *types.Block

	// FindExistingPeers check validator peers exist or not by address
	FindExistingPeers(targets ValidatorSet) map[common.Address]consensus.Peer

	//Commit send the consensus block back to miner, it should also handle the logic after a block get enough vote to be the next block in chain
	Commit(block *types.Block)

	//Cancel send the consensus block back to miner if it is invalid for consensus.
	Cancel(block *types.Block)

	// VerifyProposalHeader 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.
	VerifyProposalHeader(header *types.Header) error

	// VerifyProposalBlock verify post-processor state of proposal block (txs, Root, receipt).
	// If success, the result will be send to the pending tasks of miner
	VerifyProposalBlock(block *types.Block) error
}

Backend provides application specific functions for Tendermint core

type Config

type Config struct {
	ProposerPolicy        ProposerPolicy   `toml:",omitempty"` // The policy for proposer selection
	Epoch                 uint64           `toml:",omitempty"` // The number of blocks after which to checkpoint and reset the pending votes
	StakingSCAddress      *common.Address  `toml:",omitempty"` // The staking SC address for validating when deploy SC
	BlockPeriod           uint64           `toml:",omitempty"` // Default minimum difference between two consecutive block's timestamps in second
	TimeoutPropose        time.Duration    //Duration waiting a propose
	TimeoutProposeDelta   time.Duration    //Increment if timeout happens at propose step to reach eventually synchronous
	TimeoutPrevote        time.Duration    //Duration waiting for more prevote after 2/3 received
	TimeoutPrevoteDelta   time.Duration    //Increment if timeout happens at prevoteWait to reach eventually synchronous
	TimeoutPrecommit      time.Duration    //Duration waiting for more precommit after 2/3 received
	TimeoutPrecommitDelta time.Duration    //Duration waiting to increase if precommit wait expired to reach eventually synchronous
	TimeoutCommit         time.Duration    //Duration waiting to start round with new height
	FixedValidators       []common.Address // The fixed validators
	BlockReward           *big.Int         //BlockReward for accumulating reward

	FaultyMode uint64 `toml:",omitempty"` // The faulty node indicates the faulty node's behavior

	UseEVMCaller        bool
	IndexStateVariables *staking.IndexConfigs //The index of state variables has stored in stateDB
}

Config store all the configuration required for a Tendermint consensus

func (*Config) Commit

func (cfg *Config) Commit(t time.Time) time.Time

Commit returns the amount of time to wait for straggler votes after receiving +2/3 precommits for a single block (ie. a commit).

func (*Config) PrecommitCatchupTimeout

func (cfg *Config) PrecommitCatchupTimeout(round int64) time.Duration

PrecommitCatchupTimeout returns the amount of time to wait for precommit msgs before sending catchup msg Notes: if node 1 did not receive a polka of prevote msg, it will delay max = prevoteWaitTimeout before sending precommit So node 2 received a polka of prevote msg, it will entered precommit earlier than node 1 by prevoteWaitTimeout In here, node 2 sleep about 2 times of prevoteWaitTimeout before assuming that sending precommit message of node 1 has problem

func (*Config) PrecommitTimeout

func (cfg *Config) PrecommitTimeout(round int64) time.Duration

PrecommitTimeout returns the amount of time to wait for straggler votes after receiving any +2/3 precommits

func (*Config) PrevoteCatchupTimeout

func (cfg *Config) PrevoteCatchupTimeout(round int64) time.Duration

PrevoteCatchupTimeout returns the amount of time to wait for prevote msgs before sending catchup msg Notes: if node 1 did not receive propose msg, it will delay max = proposeTimeout before sending prevote So node 2 received propose msg, it will entered prevote earlier than node 1 by proposeTimeout In here, node 2 sleep about 2 times of proposeTimeout before assuming that sending prevote message of node 1 has problem

func (*Config) PrevoteTimeout

func (cfg *Config) PrevoteTimeout(round int64) time.Duration

PrevoteTimeout returns the amount of time to wait for straggler votes after receiving any +2/3 prevotes

func (Config) ProposeTimeout

func (cfg Config) ProposeTimeout(round int64) time.Duration

ProposeTimeout return the timeout for a specific round The formula is timeout= TimeoutPropose + round*TimeoutProposeDelta

type FaultyMode

type FaultyMode uint64

FaultyMode is the config mode to enable fauty node

const (
	// Disabled disables the faulty mode
	Disabled FaultyMode = iota
	// SendFakeProposal sends the proposal with the fake info
	SendFakeProposal
	// RandomlyStopSendingMsg randomly stop message sending
	RandomlyStopSendingMsg
)

func (FaultyMode) Uint64

func (f FaultyMode) Uint64() uint64

type FinalCommittedEvent

type FinalCommittedEvent struct {
	BlockNumber *big.Int
}

FinalCommittedEvent is posted when a proposal is committed

type MessageEvent

type MessageEvent struct {
	Payload []byte
}

MessageEvent is posted for Tendermint engine communication

type NewBlockEvent

type NewBlockEvent struct {
	Block *types.Block
}

NewBlockEvent is the event sent from Backend to Core after engine.Seal() is called. It included the latest eligible block from tx_pool

type ProposalSelector

type ProposalSelector func(ValidatorSet, common.Address, int64) Validator

type ProposerPolicy

type ProposerPolicy uint64

const (
	RoundRobin ProposerPolicy = iota
	Sticky
)

type StopCoreEvent

type StopCoreEvent struct{}

StopCoreEvent is posted when core is stopped

type Validator

type Validator interface {
	// Address returns address
	Address() common.Address

	// String representation of Validator
	String() string
}

type ValidatorSet

type ValidatorSet interface {
	// Return the validator size
	Size() int
	// Return the validator array
	List() []Validator
	// Get validator by index
	GetByIndex(i int64) Validator
	// Get validator by given address
	// If the address does not exist in the validator set, it will return -1
	GetByAddress(addr common.Address) (int, Validator)
	// AddValidator add the input validator to a list validators. It return false if this validator existed.
	AddValidator(address common.Address) bool
	// RemoveValidator remove the input validator from a list. It return false if the validator exist and is removed.
	// If the validator is not in the set, this function will return false
	RemoveValidator(address common.Address) bool
	// Copy validator set
	Copy() ValidatorSet
	// Get the minimum number of votes for a polka
	MinMajority() int
	// Get the minimum number of peers to archive consensus
	MinPeers() int
	// Get the maximum number of faulty nodes
	F() int
	// V get the minimum number of vote nodes
	V() int
	// Get proposer policy
	Policy() ProposerPolicy
	// Check whether the validator with given address is a proposer
	IsProposer(address common.Address) bool
	// CalcProposer return the proposer for the different of round number indicated
	CalcProposer(lastProposer common.Address, roundDiff int64)
	// GetProposer return the current proposer
	GetProposer() Validator
	// Height return block height when valSet is init
	Height() int64
	// GetNeighbors returns address of neighbor to rebroadcast tendermint message
	GetNeighbors(addr common.Address) map[common.Address]bool
}

ValidatorSet interface handles validator, proposer for defaultSet

type Validators

type Validators []Validator

Validators type is list of Validator

func (Validators) Len

func (slice Validators) Len() int

Len must be implemented for sort.Sort()

func (Validators) Less

func (slice Validators) Less(i, j int) bool

Less must be implemented for sort.Sort()

func (Validators) Swap

func (slice Validators) Swap(i, j int)

Swap must be implemented for sort.Sort()

type View

type View struct {
	Round       int64
	BlockNumber *big.Int
}

View includes a round number and a height of block we want to commit