digest

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

• Variables
• type BlockState
• type EpochState
• type GrandpaState
• type Handler
  • func NewHandler(lvl log.Level, blockState BlockState, epochState EpochState, ...) (*Handler, error)
  • func (h *Handler) HandleDigests(header *types.Header) error
  • func (h *Handler) Start() error
  • func (h *Handler) Stop() error

Variables

var (
	ErrUnknownConsensusEngineID = errors.New("unknown consensus engine ID")
)

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

func (h *Handler) HandleDigests(header *types.Header) error

HandleDigests handles consensus digests for an imported block

func (*Handler) Start

func (h *Handler) Start() error

Start starts the Handler

func (*Handler) Stop

func (h *Handler) Stop() error

Stop stops the Handler