core

Documentation

Index

• func Encode(val interface{}) ([]byte, error)
• func GetAggregatedEpochValidatorSetSeal(blockNumber, epoch uint64, seals MessageSet) (types.IstanbulEpochValidatorSetSeal, error)
• func GetAggregatedSeal(seals MessageSet, round *big.Int) (types.IstanbulAggregatedSeal, error)
• func PrepareCommittedSeal(hash common.Hash, round *big.Int) []byte
• func UnionOfSeals(aggregatedSignature types.IstanbulAggregatedSeal, seals MessageSet) (types.IstanbulAggregatedSeal, error)
• type CoreBackend
• type Engine
  • func New(backend CoreBackend, config *istanbul.Config) Engine
• type MessageSet
• type MsgBacklog
• type RoundChangeSetSummary
• type RoundState
• type RoundStateDB
• type RoundStateDBOptions
• type RoundStateSummary
• type State
  • func (s State) Cmp(y State) int
  • func (s State) String() string
• type StateProcessResult

Functions

func Encode

func Encode(val interface{}) ([]byte, error)

func GetAggregatedEpochValidatorSetSeal

func GetAggregatedEpochValidatorSetSeal(blockNumber, epoch uint64, seals MessageSet) (types.IstanbulEpochValidatorSetSeal, error)

GetAggregatedEpochValidatorSetSeal aggregates all the given seals for the SNARK-friendly epoch encoding to a bls aggregated signature. Returns an empty signature on a non-epoch block.

func GetAggregatedSeal

func GetAggregatedSeal(seals MessageSet, round *big.Int) (types.IstanbulAggregatedSeal, error)

GetAggregatedSeal aggregates all the given seals for a given message set to a bls aggregated signature and bitmap

func PrepareCommittedSeal

func PrepareCommittedSeal(hash common.Hash, round *big.Int) []byte

PrepareCommittedSeal returns a committed seal for the given hash and round number.

func UnionOfSeals

func UnionOfSeals(aggregatedSignature types.IstanbulAggregatedSeal, seals MessageSet) (types.IstanbulAggregatedSeal, error)

UnionOfSeals combines a BLS aggregated signature with an array of signatures. Accounts for double aggregating the same signature by only adding aggregating if the validator was not found in the previous bitmap. This function assumes that the provided seals' validator set is the same one which produced the provided bitmap

Types

type CoreBackend

type CoreBackend interface {
	// Address returns the owner's address
	Address() common.Address

	// ChainConfig retrieves the blockchain's chain configuration.
	ChainConfig() *params.ChainConfig

	// Validators returns the validator set
	Validators(proposal istanbul.Proposal) istanbul.ValidatorSet
	NextBlockValidators(proposal istanbul.Proposal) (istanbul.ValidatorSet, error)

	// EventMux returns the event mux in backend
	EventMux() *event.TypeMux

	// Gossip will send a message to all connnected peers
	Gossip(payload []byte, ethMsgCode uint64) error

	// Multicast sends a message to it's connected nodes filtered on the 'addresses' parameter (where each address
	// is associated with those node's signing key)
	// If sendToSelf is set to true, then the function will send an event to self via a message event
	Multicast(addresses []common.Address, payload []byte, ethMsgCode uint64, sendToSelf bool) error

	// Commit delivers an approved proposal to backend.
	// The delivered proposal will be put into blockchain.
	Commit(proposal istanbul.Proposal, aggregatedSeal types.IstanbulAggregatedSeal, aggregatedEpochValidatorSetSeal types.IstanbulEpochValidatorSetSeal, stateProcessResult *StateProcessResult) error

	// Verify verifies the proposal. If a consensus.ErrFutureBlock error is returned,
	// the time difference of the proposal and current time is also returned.
	Verify(istanbul.Proposal) (*StateProcessResult, time.Duration, error)

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

	// Sign with the data with the BLS key, using either a direct or composite hasher and optional cip22 encoding
	SignBLS([]byte, []byte, bool, bool) (blscrypto.SerializedSignature, error)

	// CheckSignature verifies the signature by checking if it's signed by
	// the given validator
	CheckSignature(data []byte, addr common.Address, sig []byte) error

	// GetCurrentHeadBlock retrieves the last block
	GetCurrentHeadBlock() istanbul.Proposal

	// GetCurrentHeadBlockAndAuthor retrieves the last block alongside the author for that block
	GetCurrentHeadBlockAndAuthor() (istanbul.Proposal, common.Address)

	// LastSubject retrieves latest committed subject (view and digest)
	LastSubject() (istanbul.Subject, error)

	// HasBlock checks if the combination of the given hash and height matches any existing blocks
	HasBlock(hash common.Hash, number *big.Int) bool

	// AuthorForBlock returns the proposer of the given block height
	AuthorForBlock(number uint64) common.Address

	// HashForBlock returns the block header hash of the given block height
	HashForBlock(number uint64) common.Hash

	// ParentBlockValidators returns the validator set of the given proposal's parent block
	ParentBlockValidators(proposal istanbul.Proposal) istanbul.ValidatorSet

	IsPrimaryForSeq(seq *big.Int) bool
	UpdateReplicaState(seq *big.Int)
}

CoreBackend provides the Istanbul backend application specific functions for Istanbul core

type Engine

type Engine interface {
	Start() error
	Stop() error
	// CurrentView returns the current view or nil if none
	CurrentView() *istanbul.View
	// CurrentRoundState returns the current roundState or nil if none
	CurrentRoundState() RoundState
	// CurrentRoundChangeSet returns the current round change set summary:
	// a collection of the latest round change messages from all other
	// validators.
	CurrentRoundChangeSet() *RoundChangeSetSummary

	SetAddress(common.Address)
	// Validator -> CommittedSeal from Parent Block
	ParentCommits() MessageSet
	// ForceRoundChange will force round change to the current desiredRound + 1
	ForceRoundChange()

	// ResendPreprepare sends again the preprepare message.
	ResendPreprepare() error
	// GossipPrepares gossips to other validators all the prepares received in the current round.
	GossipPrepares() error
	// GossipCommits gossips to other validators all the commits received in the current round.
	GossipCommits() error
}

func New

func New(backend CoreBackend, config *istanbul.Config) Engine

New creates an Istanbul consensus core

type MessageSet

type MessageSet interface {
	fmt.Stringer
	Add(msg *istanbul.Message) error
	GetAddressIndex(addr common.Address) (uint64, error)
	Remove(address common.Address)
	Values() (result []*istanbul.Message)
	Size() int
	Get(addr common.Address) *istanbul.Message
	Addresses() []common.Address
	Serialize() ([]byte, error)
}

type MsgBacklog

type MsgBacklog interface {
	// contains filtered or unexported methods
}

MsgBacklog represent a backlog of future messages It works by:

• allowing storing messages with "store()"
• call eventListener when a backlog message becomes "present"
• updates its notion of time/state with updateState()

type RoundChangeSetSummary

type RoundChangeSetSummary struct {
	RoundForVal map[common.Address]uint64   `json:"roundForVal"`
	ValsInRound map[uint64][]common.Address `json:"valsInRound"`
}

RoundChangeSetSummary holds a print friendly view of a RoundChangeSet.

type RoundState

type RoundState interface {
	// mutation functions
	StartNewRound(nextRound *big.Int, validatorSet istanbul.ValidatorSet, nextProposer istanbul.Validator) error
	StartNewSequence(nextSequence *big.Int, validatorSet istanbul.ValidatorSet,
		nextProposer istanbul.Validator, parentCommits MessageSet, consensusFork bool) error
	TransitionToPreprepared(preprepare *istanbul.Preprepare) error
	TransitionToPrepreparedV2(preprepareV2 *istanbul.PreprepareV2) error
	TransitionToWaitingForNewRound(r *big.Int, nextProposer istanbul.Validator) error
	TransitionToCommitted() error
	TransitionToPrepared(quorumSize int) error
	AddCommit(msg *istanbul.Message) error
	AddPrepare(msg *istanbul.Message) error
	AddParentCommit(msg *istanbul.Message) error
	SetPendingRequest(pendingRequest *istanbul.Request) error
	SetProposalVerificationStatus(proposalHash common.Hash, verificationStatus error)
	SetStateProcessResult(proposalHash common.Hash, blockProcessResult *StateProcessResult)

	// view functions
	DesiredRound() *big.Int
	State() State
	GetPrepareOrCommitSize() int
	GetValidatorByAddress(address common.Address) istanbul.Validator
	ValidatorSet() istanbul.ValidatorSet
	Proposer() istanbul.Validator
	IsProposer(address common.Address) bool
	Subject() *istanbul.Subject
	Preprepare() *istanbul.Preprepare
	PreprepareV2() *istanbul.PreprepareV2
	Proposal() istanbul.Proposal
	Round() *big.Int
	Commits() MessageSet
	Prepares() MessageSet
	ParentCommits() MessageSet
	PendingRequest() *istanbul.Request
	Sequence() *big.Int
	View() *istanbul.View
	PreparedCertificate() istanbul.PreparedCertificate
	GetProposalVerificationStatus(proposalHash common.Hash) (verificationStatus error, isCached bool)
	GetStateProcessResult(proposalHash common.Hash) (result *StateProcessResult)
	Summary() *RoundStateSummary
}

type RoundStateDB

type RoundStateDB interface {
	GetLastView() (*istanbul.View, error)
	// GetOldestValidView returns the oldest valid view that can be stored on the db
	// it might or might not be present on the db
	GetOldestValidView() (*istanbul.View, error)
	GetRoundStateFor(view *istanbul.View, consensusForked bool) (RoundState, error)
	UpdateLastRoundState(rs RoundState) error
	Close() error
}

type RoundStateDBOptions

type RoundStateDBOptions struct {
	// contains filtered or unexported fields
}

RoundStateDBOptions are the options for a RoundStateDB instance

type RoundStateSummary

type RoundStateSummary struct {
	State              string       `json:"state"`
	Sequence           *big.Int     `json:"sequence"`
	Round              *big.Int     `json:"round"`
	DesiredRound       *big.Int     `json:"desiredRound"`
	PendingRequestHash *common.Hash `json:"pendingRequestHash"`

	ValidatorSet []common.Address `json:"validatorSet"`
	Proposer     common.Address   `json:"proposer"`

	Prepares      []common.Address `json:"prepares"`
	Commits       []common.Address `json:"commits"`
	ParentCommits []common.Address `json:"parentCommits"`

	Preprepare          *istanbul.PreprepareSummary          `json:"preprepare"`
	PreparedCertificate *istanbul.PreparedCertificateSummary `json:"preparedCertificate"`
}

type State

type State uint64

State represents the IBFT state

const (
	StateAcceptRequest State = iota
	StatePreprepared
	StatePrepared
	StateCommitted
	StateWaitingForNewRound
)

Different IBFT Core States

func (State) Cmp

func (s State) Cmp(y State) int

Cmp compares s and y and returns:

-1 if s is the previous state of y
 0 if s and y are the same state
+1 if s is the next state of y

func (State) String

func (s State) String() string

type StateProcessResult

type StateProcessResult struct {
	State    *state.StateDB
	Receipts types.Receipts
	Logs     []*types.Log
}

StateProcessResult represents processing results from StateProcessor.