forkchoice

Documentation

Overview

Package forkchoice implements the service to support fork choice for the Ethereum beacon chain. This contains the necessary components to track latest validators votes, and balances. Then a store object to be used to calculate head. High level fork choice summary: https://notes.ethereum.org/@vbuterin/rkhCgQteN?type=view#LMD-GHOST-fork-choice-rule

Index

• Variables
• type AttestationProcessor
• type BalancesByRooter
• type BlockProcessor
• type ForkChoicer
• type Getter
• type HeadRetriever
• type ProposerBooster
• type Setter

Variables

var ErrUnknownCommonAncestor = errors.New("unknown common ancestor")

Types

type AttestationProcessor

type AttestationProcessor interface {
	ProcessAttestation(context.Context, []uint64, [32]byte, primitives.Epoch)
	InsertSlashedIndex(context.Context, primitives.ValidatorIndex)
}

AttestationProcessor processes the attestation that's used for accounting fork choice.

type BalancesByRooter

type BalancesByRooter func(context.Context, [32]byte) ([]uint64, error)

BalancesByRooter is a handler to obtain the effective balances of the state with the given block root

type BlockProcessor

type BlockProcessor interface {
	InsertNode(context.Context, state.BeaconState, [32]byte) error
	InsertOptimisticChain(context.Context, []*forkchoicetypes.BlockAndCheckpoints) error
}

BlockProcessor processes the block that's used for accounting fork choice.

type ForkChoicer

type ForkChoicer interface {
	HeadRetriever        // to compute head.
	BlockProcessor       // to track new block for fork choice.
	AttestationProcessor // to track new attestation for fork choice.
	Getter               // to retrieve fork choice information.
	Setter               // to set fork choice information.
	ProposerBooster      // ability to boost timely-proposed block roots.
}

ForkChoicer represents the full fork choice interface composed of all the sub-interfaces.

type Getter

type Getter interface {
	HasNode([32]byte) bool
	ProposerBoost() [fieldparams.RootLength]byte
	HasParent(root [32]byte) bool
	AncestorRoot(ctx context.Context, root [32]byte, slot primitives.Slot) ([32]byte, error)
	CommonAncestor(ctx context.Context, root1 [32]byte, root2 [32]byte) ([32]byte, primitives.Slot, error)
	IsCanonical(root [32]byte) bool
	FinalizedCheckpoint() *forkchoicetypes.Checkpoint
	FinalizedPayloadBlockHash() [32]byte
	JustifiedCheckpoint() *forkchoicetypes.Checkpoint
	PreviousJustifiedCheckpoint() *forkchoicetypes.Checkpoint
	JustifiedPayloadBlockHash() [32]byte
	BestJustifiedCheckpoint() *forkchoicetypes.Checkpoint
	NodeCount() int
	HighestReceivedBlockSlot() primitives.Slot
	HighestReceivedBlockRoot() [32]byte
	ReceivedBlocksLastEpoch() (uint64, error)
	ForkChoiceDump(context.Context) (*v1.ForkChoiceDump, error)
	Weight(root [32]byte) (uint64, error)
	VotedFraction(root [32]byte) (uint64, error)
}

Getter returns fork choice related information.

type HeadRetriever

type HeadRetriever interface {
	Head(context.Context, []uint64) ([32]byte, error)
	CachedHeadRoot() [32]byte
	Tips() ([][32]byte, []primitives.Slot)
	IsOptimistic(root [32]byte) (bool, error)
	AllTipsAreInvalid() bool
}

HeadRetriever retrieves head root and optimistic info of the current chain.

type ProposerBooster

type ProposerBooster interface {
	ResetBoostedProposerRoot(ctx context.Context) error
}

ProposerBooster is able to boost the proposer's root score during fork choice.

type Setter

type Setter interface {
	SetOptimisticToValid(context.Context, [fieldparams.RootLength]byte) error
	SetOptimisticToInvalid(context.Context, [fieldparams.RootLength]byte, [fieldparams.RootLength]byte, [fieldparams.RootLength]byte) ([][32]byte, error)
	UpdateJustifiedCheckpoint(*forkchoicetypes.Checkpoint) error
	UpdateFinalizedCheckpoint(*forkchoicetypes.Checkpoint) error
	SetGenesisTime(uint64)
	SetOriginRoot([32]byte)
	NewSlot(context.Context, primitives.Slot) error
	SetBalancesByRooter(BalancesByRooter)
}

Setter allows to set forkchoice information