README
¶
Gossamer digest Package
In general, the term "digest" refers to a summary that includes important pieces of information. In the case of
Polkadot-like networks, a "digest" is an extensible
field of a block header that provides information related to some network protocol, such as those implemented by a
consensus engine or
blockchain runtime. This package deals exclusively
with the handling of consensus digests,
which are messages that originate from a blockchain runtime and are consumed by consensus engines. Consensus digests are
formally described in
Section 5.1.2 of the Polkadot Specification.
What follows is a description of Gossamer's consensus digest Handler, including the consensus engines the Handler
supports, and the messages the Handler may receive & corresponding actions it can dispatch.
Handler
The digest Handler implements the
Service interface, which means that it
exposes Start and Stop functions. When a
Gossamer Node is started, a digest Handler is created
with the NewHandler function and started
along with the Gossamer node's other services. The digest Handler maintains two goroutines, handleBlockImport and
handleBlockFinalisation, which handle imported and finalised blocks respectively - these goroutines listen for
messages on channels provided by the
BlockState.
The digest Handler also exposes two public functions:
NextGrandpaAuthorityChange
and HandleDigests.
NextGrandpaAuthorityChange is consumed by the
GRANDPA service to determine the block number of
the next GRANDPA authority change.
HandleDigests is invoked by the core service for each new block; this function reads the consensus digests from the
block and dispatches actions based on the digest contents. The digest Handler supports digests from the BABE
(authorship) and GRANDPA (finalisation) consensus engines - the following sections describe the messages in these
digests and the actions Gossamer takes when it receives them.
BABE Messages
BABE is a block production algorithm that assigns block authorship rights over periods of time referred to as "slots", which are a subdivision of an "epoch". One of the benefits of BABE is that it is able to provide a blockchain runtime with secure, decentralized randomness. Furthermore, BABE seeks to ensure the liveness of a blockchain by defining multiple tiers of potential block producers for each epoch. BABE digests may contain one of the three message types described below.
Next Epoch
This message is issued by the runtime on the first block of every epoch - it provides the BABE consensus engine with the authority set and randomness for the next epoch.
Disabled
A message of this type will contain the ID of an authority; this authority should cease all authority functionality and all other authorities should ignore any authority-related messages from the identified authority. Note: Gossamer has not implemented supported for messages of this type.
Next Config
Messages of this type may only be issued in the first block of an epoch. This message type supplies configuration parameters that should be applied from the next epoch onwards. The parameters in this configuration relate to how backup authorities are selected.
GRANDPA Messages
Provable finality securely assures participants in a blockchain network that a block (and the transactions it contains) will not be reverted. Gossamer implements the GRANDPA finality protocol, which, like BABE, uttilizes a rotating validator set. The GRANDPA protocol defines the following consensus digest messages:
Scheduled Change
These messages contain a list of new authority IDs and a delay, specified as a number of finalised blocks, after which the change should be applied.
Forced Change
This message is similar to the scheduled changes message type, however the delay is calculated using imported blocks (as opposed to finalised blocks), which means that the change is valid for multiple candidate chains.
Disabled
A message of this type will contain the ID of an authority; this authority should cease all authority functionality and all other authorities should ignore any authority-related messages from the identified authority. Note: Gossamer has not implemented support for messages of this type.
Pause
Messages of this type specify a delay after which the current authority set should be paused.
Resume
Messages of this type specify a delay after which the current authority set should be resumed.
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
var (
ErrUnknownConsensusEngineID = errors.New("unknown consensus engine ID")
)
Functions ¶
This section is empty.
Types ¶
type BlockState ¶
type BlockState interface {
BestBlockHeader() (*types.Header, error)
GetImportedBlockNotifierChannel() chan *types.Block
FreeImportedBlockNotifierChannel(ch chan *types.Block)
GetFinalisedNotifierChannel() chan *types.FinalisationInfo
FreeFinalisedNotifierChannel(ch chan *types.FinalisationInfo)
}
BlockState interface for block state methods
type EpochState ¶
type EpochState interface {
GetEpochForBlock(header *types.Header) (uint64, error)
SetEpochData(epoch uint64, info *types.EpochData) error
SetConfigData(epoch uint64, info *types.ConfigData) error
StoreBABENextEpochData(epoch uint64, hash common.Hash, nextEpochData types.NextEpochData)
StoreBABENextConfigData(epoch uint64, hash common.Hash, nextEpochData types.NextConfigData)
FinalizeBABENextEpochData(finalizedHeader *types.Header) error
FinalizeBABENextConfigData(finalizedHeader *types.Header) error
}
EpochState is the interface for state.EpochState
type GrandpaState ¶
type GrandpaState interface {
SetNextChange(authorities []grandpa.Voter, number uint) error
IncrementSetID() (newSetID uint64, err error)
SetNextPause(number uint) error
SetNextResume(number uint) error
GetCurrentSetID() (uint64, error)
HandleGRANDPADigest(header *types.Header, digest scale.VaryingDataType) error
ApplyScheduledChanges(finalizedHeader *types.Header) error
ApplyForcedChanges(importedHeader *types.Header) error
}
GrandpaState is the interface for the state.GrandpaState
type Handler ¶
type Handler struct {
// contains filtered or unexported fields
}
Handler is used to handle consensus messages and relevant authority updates to BABE and GRANDPA
func NewHandler ¶
func NewHandler(lvl log.Level, blockState BlockState, epochState EpochState, grandpaState GrandpaState) (*Handler, error)
NewHandler returns a new Handler
func (*Handler) HandleDigests ¶
HandleDigests handles consensus digests for an imported block
Source Files