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: 22 Imported by: 8



Package clique implements PoA (Proof of Authority) consensus engine which is mainly for private chains.

Consensus Engine Overview

In clique, only pre-selected nodes can propose a block. The list of these nodes are described in the header's extra field and the list can be changed by calling Propose() API.

The sequence of proposers is decided by the block number and the number of nodes which can propose a block. If a proposer proposes a block in its turn (in-turn), it will have a blockscore(formerly known as difficulty) of 2. If a proposer proposes a block in other node's turn (out-of-turn), it will have a blockscore of 1.

If an in-turn proposer didn't propose a block for some time, other nodes start to propose their block with a blockscore of 1. So the block generation can continue. But there can be a fork because several nodes can propose a block at the same time. In this case, a block reorganization will happen based on total blockscore (the sum of all blockscore from the genesis block to the current one).



This section is empty.


View Source
var (
	ExtraVanity = 32                     // Fixed number of extra-data prefix bytes reserved for signer vanity
	ExtraSeal   = crypto.SignatureLength // Fixed number of extra-data suffix bytes reserved for signer seal


Clique proof-of-authority protocol constants.

View Source
var (

	// ErrInvalidTimestamp is returned if the timestamp of a block is lower than
	// the previous block's timestamp + the minimum block period.
	ErrInvalidTimestamp = errors.New("invalid timestamp")

Various error messages to mark blocks invalid. These should be private to prevent engine specific errors from being referenced in the remainder of the codebase, inherently breaking if the engine is swapped out. Please put common error types into the consensus package.


func CalcBlockScore

func CalcBlockScore(snap *Snapshot, signer common.Address) *big.Int

CalcBlockScore is the blockScore adjustment algorithm. It returns the blockScore that a new block should have based on the previous blocks in the chain and the current signer.


type API

type API struct {
	// contains filtered or unexported fields

API is a user facing RPC API to allow controlling the signer and voting mechanisms of the proof-of-authority scheme.

func (*API) Discard

func (api *API) Discard(address common.Address)

Discard drops a currently running proposal, stopping the signer from casting further votes (either for or against).

func (*API) GetSigners

func (api *API) GetSigners(number *rpc.BlockNumber) ([]common.Address, error)

GetSigners retrieves the list of authorized signers at the specified block.

func (*API) GetSignersAtHash

func (api *API) GetSignersAtHash(hash common.Hash) ([]common.Address, error)

GetSignersAtHash retrieves the state snapshot at a given block.

func (*API) GetSnapshot

func (api *API) GetSnapshot(number *rpc.BlockNumber) (*Snapshot, error)

GetSnapshot retrieves the state snapshot at a given block.

func (*API) GetSnapshotAtHash

func (api *API) GetSnapshotAtHash(hash common.Hash) (*Snapshot, error)

GetSnapshotAtHash retrieves the state snapshot at a given block.

func (*API) Proposals

func (api *API) Proposals() map[common.Address]bool

Proposals returns the current proposals the node tries to uphold and vote on.

func (*API) Propose

func (api *API) Propose(address common.Address, auth bool)

Propose injects a new authorization proposal that the signer will attempt to push through.

type Clique

type Clique struct {
	// contains filtered or unexported fields

Clique is the proof-of-authority consensus engine proposed to support the Klaytn testnet following the Baobab attacks.

func New

func New(config *params.CliqueConfig, db database.DBManager) *Clique

New creates a Clique proof-of-authority consensus engine with the initial signers set to the ones provided by the user.

func (*Clique) APIs

func (c *Clique) APIs(chain consensus.ChainReader) []rpc.API

APIs implements consensus.Engine, returning the user facing RPC API to allow controlling the signer voting.

func (*Clique) Author

func (c *Clique) Author(header *types.Header) (common.Address, error)

Author implements consensus.Engine, returning the Klaytn address recovered from the signature in the header's extra-data section.

func (*Clique) Authorize

func (c *Clique) Authorize(signer common.Address, signFn SignerFn)

Authorize injects a private key into the consensus engine to mint new blocks with.

func (*Clique) CalcBlockScore

func (c *Clique) CalcBlockScore(chain consensus.ChainReader, time uint64, parent *types.Header) *big.Int

CalcBlockScore is the blockScore adjustment algorithm. It returns the blockScore that a new block should have based on the previous blocks in the chain and the current signer.

func (*Clique) CanVerifyHeadersConcurrently added in v1.7.0

func (c *Clique) CanVerifyHeadersConcurrently() bool

CanVerifyHeadersConcurrently returns true if concurrent header verification possible, otherwise returns false.

func (*Clique) Finalize

func (c *Clique) Finalize(chain consensus.ChainReader, header *types.Header, state *state.StateDB, txs []*types.Transaction, receipts []*types.Receipt) (*types.Block, error)

Finalize implements consensus.Engine and returns the final block.

func (*Clique) Prepare

func (c *Clique) Prepare(chain consensus.ChainReader, header *types.Header) error

Prepare implements consensus.Engine, preparing all the consensus fields of the header for running the transactions on top.

func (*Clique) PreprocessHeaderVerification added in v1.7.0

func (c *Clique) PreprocessHeaderVerification(headers []*types.Header) (chan<- struct{}, <-chan error)

PreprocessHeaderVerification prepares header verification for heavy computation before synchronous header verification such as ecrecover.

func (*Clique) Protocol

func (c *Clique) Protocol() consensus.Protocol

Protocol implements consensus.Engine.Protocol

func (*Clique) Seal

func (c *Clique) Seal(chain consensus.ChainReader, block *types.Block, stop <-chan struct{}) (*types.Block, error)

Seal implements consensus.Engine, attempting to create a sealed block using the local signing credentials.

func (*Clique) VerifyHeader

func (c *Clique) VerifyHeader(chain consensus.ChainReader, header *types.Header, seal bool) error

VerifyHeader checks whether a header conforms to the consensus rules.

func (*Clique) VerifyHeaders

func (c *Clique) VerifyHeaders(chain consensus.ChainReader, headers []*types.Header, seals []bool) (chan<- struct{}, <-chan error)

VerifyHeaders is similar to VerifyHeader, but verifies a batch of headers. 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).

func (*Clique) VerifySeal

func (c *Clique) VerifySeal(chain consensus.ChainReader, header *types.Header) error

VerifySeal implements consensus.Engine, checking whether the signature contained in the header satisfies the consensus protocol requirements.

type SignerFn

type SignerFn func(accounts.Account, []byte) ([]byte, error)

SignerFn is a signer callback function to request a hash to be signed by a backing account.

type Snapshot

type Snapshot struct {
	Number  uint64                      `json:"number"`  // Block number where the snapshot was created
	Hash    common.Hash                 `json:"hash"`    // Block hash where the snapshot was created
	Signers map[common.Address]struct{} `json:"signers"` // Set of authorized signers at this moment
	Recents map[uint64]common.Address   `json:"recents"` // Set of recent signers for spam protections
	Votes   []*Vote                     `json:"votes"`   // List of votes cast in chronological order
	Tally   map[common.Address]Tally    `json:"tally"`   // Current vote tally to avoid recalculating
	// contains filtered or unexported fields

Snapshot is the state of the authorization voting at a given point in time.

type Tally

type Tally struct {
	Authorize bool `json:"authorize"` // Whether the vote is about authorizing or kicking someone
	Votes     int  `json:"votes"`     // Number of votes until now wanting to pass the proposal

Tally is a simple vote tally to keep the current score of votes. Votes that go against the proposal aren't counted since it's equivalent to not voting.

type Vote

type Vote struct {
	Signer    common.Address `json:"signer"`    // Authorized signer that cast this vote
	Block     uint64         `json:"block"`     // Block number the vote was cast in (expire old votes)
	Address   common.Address `json:"address"`   // Account being voted on to change its authorization
	Authorize bool           `json:"authorize"` // Whether to authorize or deauthorize the voted account

Vote represents a single vote that an authorized signer made to modify the list of authorizations.

Jump to

Keyboard shortcuts

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