Version: v1.7.0 Latest Latest

This package is not in the latest version of its module.

Go to latest
Published: Oct 19, 2021 License: GPL-3.0 Imports: 14 Imported by: 26



Package istanbul is a BFT based consensus engine which implements consensus/Engine interface. Istanbul engine was inspired by Clique POA, Hyperledger's SBFT, Tendermint, HydraChain and NCCU BFT.

Istanbul engine is using 3-phase consensus and it can tolerate F faulty nodes where N = 3F + 1

In Klaytn, it is being used as the main consensus engine after modification for supports of Committee, Reward and Governance. Package istanbul has three sub-packages, core, backend, and validator. Please refer to each package's doc.go for more information.

Source Files

Various interfaces, constants and utility functions for Istanbul consensus engine

- `backend.go`: Defines Backend interface which provides application specific functions for Istanbul core
- `config.go`: Provides default configuration for Istanbul engine
- `errors.go`: Defines three errors used in Istanbul engine
- `events.go`: Defines events which are used for Istanbul engine communication
- `types.go`: Defines message structs such as Proposal, Request, View, Preprepare, Subject and ConsensusMsg
- `utils.go`: Provides three utility functions: RLPHash, GetSignatureAddress and CheckValidatorSignature
- `validator.go`: Defines Validator, ValidatorSet interfaces and Validators, ProposalSelector types



This section is empty.


View Source
var (
	// ErrUnauthorizedAddress is returned when given address cannot be found in
	// current validator set.
	ErrUnauthorizedAddress = errors.New("unauthorized address")
	// ErrStoppedEngine is returned if the engine is stopped
	ErrStoppedEngine = errors.New("stopped engine")
	// ErrStartedEngine is returned if the engine is already started
	ErrStartedEngine = errors.New("started engine")
View Source
var DefaultConfig = &Config{
	Timeout:        10000,
	BlockPeriod:    1,
	ProposerPolicy: RoundRobin,
	Epoch:          30000,
	SubGroupSize:   21,

TODO-Klaytn-Istanbul: Do not use DefaultConfig except for assigning new config


func CheckValidatorSignature

func CheckValidatorSignature(valSet ValidatorSet, data []byte, sig []byte) (common.Address, error)

func GetSignatureAddress

func GetSignatureAddress(data []byte, sig []byte) (common.Address, error)

GetSignatureAddress gets the signer address from the signature

func RLPHash

func RLPHash(v interface{}) (h common.Hash)


type Backend

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

	// Validators returns the validator set
	Validators(proposal Proposal) ValidatorSet

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

	// Broadcast sends a message to all validators (include self)
	Broadcast(prevHash common.Hash, valSet ValidatorSet, payload []byte) error

	// Gossip sends a message to all validators (exclude self)
	Gossip(valSet ValidatorSet, payload []byte) error

	GossipSubPeer(prevHash common.Hash, valSet ValidatorSet, payload []byte) map[common.Address]bool

	// Commit delivers an approved proposal to backend.
	// The delivered proposal will be put into blockchain.
	Commit(proposal Proposal, seals [][]byte) 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(Proposal) (time.Duration, error)

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

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

	// LastProposal retrieves latest committed proposal and the address of proposer
	LastProposal() (Proposal, common.Address)

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

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

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

	// HasBadBlock returns whether the block with the hash is a bad block
	HasBadProposal(hash common.Hash) bool

	GetRewardBase() common.Address

	GetSubGroupSize() uint64

	SetCurrentView(view *View)

	NodeType() common.ConnType

Backend provides application specific functions for Istanbul core

type CommitEvent

type CommitEvent struct {
	Payload []byte

type Config

type Config struct {
	Timeout        uint64         `toml:",omitempty"` // The timeout for each Istanbul round in milliseconds.
	BlockPeriod    uint64         `toml:",omitempty"` // Default minimum difference between two consecutive block's timestamps in second
	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
	SubGroupSize   uint64         `toml:",omitempty"`

type ConsensusMsg

type ConsensusMsg struct {
	PrevHash common.Hash
	Payload  []byte

type FinalCommittedEvent

type FinalCommittedEvent struct {

FinalCommittedEvent is posted when a proposal is committed

type MessageEvent

type MessageEvent struct {
	Hash    common.Hash
	Payload []byte

MessageEvent is posted for Istanbul engine communication

type Preprepare

type Preprepare struct {
	View     *View
	Proposal Proposal

func (*Preprepare) DecodeRLP

func (b *Preprepare) DecodeRLP(s *rlp.Stream) error

func (*Preprepare) EncodeRLP

func (b *Preprepare) EncodeRLP(w io.Writer) error

type Proposal

type Proposal interface {
	// Number retrieves the sequence number of this proposal
	Number() *big.Int

	// Hash retrieves the hash of this proposal
	Hash() common.Hash

	EncodeRLP(w io.Writer) error

	DecodeRLP(s *rlp.Stream) error

	String() string

	ParentHash() common.Hash

	Header() *types.Header

	WithSeal(header *types.Header) *types.Block

Proposal supports retrieving height and serialized block to be used during Istanbul consensus.

type ProposalSelector

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

type ProposerPolicy

type ProposerPolicy uint64
const (
	RoundRobin ProposerPolicy = iota

type Request

type Request struct {
	Proposal Proposal

type RequestEvent

type RequestEvent struct {
	Proposal Proposal

RequestEvent is posted to propose a proposal

type Subject

type Subject struct {
	View     *View
	Digest   common.Hash
	PrevHash common.Hash

func (*Subject) DecodeRLP

func (b *Subject) DecodeRLP(s *rlp.Stream) error

func (*Subject) EncodeRLP

func (b *Subject) EncodeRLP(w io.Writer) error

func (*Subject) String

func (b *Subject) String() string

type Validator

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

	// String representation of Validator
	String() string

	RewardAddress() common.Address
	VotingPower() uint64
	Weight() uint64

type ValidatorSet

type ValidatorSet interface {
	// Calculate the proposer
	CalcProposer(lastProposer common.Address, round uint64)
	// Return the validator size
	Size() uint64
	// Return the sub validator group size
	SubGroupSize() uint64
	// Set the sub validator group size
	SetSubGroupSize(size uint64)
	// Return the validator array
	List() []Validator
	// Return the demoted validator array
	DemotedList() []Validator
	// SubList composes a committee after setting a proposer with a default value.
	SubList(prevHash common.Hash, view *View) []Validator
	// Return whether the given address is one of sub-list
	CheckInSubList(prevHash common.Hash, view *View, addr common.Address) bool
	// SubListWithProposer composes a committee with given parameters.
	SubListWithProposer(prevHash common.Hash, proposer common.Address, view *View) []Validator
	// Get validator by index
	GetByIndex(i uint64) Validator
	// Get validator by given address
	GetByAddress(addr common.Address) (int, Validator)
	// Get demoted validator by given address
	GetDemotedByAddress(addr common.Address) (int, Validator)
	// Get current proposer
	GetProposer() Validator
	// Check whether the validator with given address is a proposer
	IsProposer(address common.Address) bool
	// Add validator
	AddValidator(address common.Address) bool
	// Remove validator
	RemoveValidator(address common.Address) bool
	// Copy validator set
	Copy() ValidatorSet
	// Get the maximum number of faulty nodes
	F() int
	// Get proposer policy
	Policy() ProposerPolicy

	IsSubSet() bool

	// Refreshes a list of candidate proposers with given hash and blockNum
	Refresh(hash common.Hash, blockNum uint64, config *params.ChainConfig, isSingle bool, governingNode common.Address, minStaking uint64) error

	SetBlockNum(blockNum uint64)

	Proposers() []Validator // TODO-Klaytn-Issue1166 For debugging

	TotalVotingPower() uint64

	Selector(valSet ValidatorSet, lastProposer common.Address, round uint64) Validator

type Validators

type Validators []Validator

func (Validators) AddressStringList added in v1.5.0

func (slice Validators) AddressStringList() []string

func (Validators) Len

func (slice Validators) Len() int

func (Validators) Less

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

func (Validators) Swap

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

type View

type View struct {
	Round    *big.Int
	Sequence *big.Int

View includes a round number and a sequence number. Sequence is the block number we'd like to commit. Each round has a number and is composed by 3 steps: preprepare, prepare and commit.

If the given block is not accepted by validators, a round change will occur and the validators start a new round with round+1.

func (*View) Cmp

func (v *View) Cmp(y *View) int

Cmp compares v and y and returns: -1 if v < y

0 if v == y

+1 if v > y

func (*View) DecodeRLP

func (v *View) DecodeRLP(s *rlp.Stream) error

func (*View) EncodeRLP

func (v *View) EncodeRLP(w io.Writer) error

EncodeRLP serializes a View into the Klaytn RLP format.

func (*View) String

func (v *View) String() string


Path Synopsis
Package backend defines backend struct which implements Backend interface of Istanbul consensus engine.
Package backend defines backend struct which implements Backend interface of Istanbul consensus engine.
Package core implements the core functionality of Istanbul consensus engine.
Package core implements the core functionality of Istanbul consensus engine.
Package mock_istanbul is a generated GoMock package.
Package mock_istanbul is a generated GoMock package.
Package validator implements the types related to the validators participating in consensus.
Package validator implements the types related to the validators participating in consensus.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL