stategen

Documentation

Overview

Package stategen defines functions to regenerate beacon chain states by replaying blocks from a stored state checkpoint, useful for optimization and reducing a beacon node's resource consumption.

Index

• Variables
• func ReplayProcessSlots(ctx context.Context, state state.BeaconState, slot types.Slot) (state.BeaconState, error)
• type CachedGetter
• type CanonicalChecker
• type CanonicalHistory
  • func NewCanonicalHistory(h HistoryAccessor, cc CanonicalChecker, cs CurrentSlotter, ...) *CanonicalHistory
  • func (c *CanonicalHistory) BlockRootForSlot(ctx context.Context, target types.Slot) ([32]byte, error)
  • func (c *CanonicalHistory) ReplayerForSlot(target types.Slot) Replayer
• type CanonicalHistoryOption
  • func WithCache(c CachedGetter) CanonicalHistoryOption
• type CombinedCache
  • func (c CombinedCache) ByBlockRoot(r [32]byte) (state.BeaconState, error)
• type CurrentSlotter
• type HistoryAccessor
• type Replayer
• type ReplayerBuilder
• type State
  • func New(beaconDB db.NoHeadAccessDatabase, opts ...StateGenOption) *State
  • func (s *State) CombinedCache() *CombinedCache
  • func (s *State) DeleteStateFromCaches(_ context.Context, blockRoot [32]byte) error
  • func (s *State) DisableSaveHotStateToDB(ctx context.Context) error
  • func (s *State) EnableSaveHotStateToDB(_ context.Context)
  • func (s *State) ForceCheckpoint(ctx context.Context, blockRoot []byte) error
  • func (s *State) HasState(ctx context.Context, blockRoot [32]byte) (bool, error)
  • func (s *State) MigrateToCold(ctx context.Context, fRoot [32]byte) error
  • func (s *State) Resume(ctx context.Context, fState state.BeaconState) (state.BeaconState, error)
  • func (s *State) SaveFinalizedState(fSlot types.Slot, fRoot [32]byte, fState state.BeaconState)
  • func (s *State) SaveState(ctx context.Context, blockRoot [32]byte, st state.BeaconState) error
  • func (s *State) StateByRoot(ctx context.Context, blockRoot [32]byte) (state.BeaconState, error)
  • func (s *State) StateByRootIfCachedNoCopy(blockRoot [32]byte) state.BeaconState
  • func (s *State) StateByRootInitialSync(ctx context.Context, blockRoot [32]byte) (state.BeaconState, error)
• type StateGenOption
  • func WithBackfillStatus(bfs *backfill.Status) StateGenOption
• type StateManager

Variables

var ErrFutureSlotRequested = errors.New("cannot replay to future slots")

var ErrNoBlocksBelowSlot = errors.New("no blocks found in db below slot")

var ErrNoCanonicalBlockForSlot = errors.New("none of the blocks found in the db slot index are canonical")

var ErrNoDataForSlot = errors.New("cannot retrieve data for slot")

var ErrNotInCache = errors.New("state not found in cache")

var ErrReplayTargetSlotExceeded = errors.New("desired replay slot is less than state's slot")

Functions

func ReplayProcessSlots

func ReplayProcessSlots(ctx context.Context, state state.BeaconState, slot types.Slot) (state.BeaconState, error)

ReplayProcessSlots to process old slots for state gen usages. There's no skip slot cache involved given state gen only works with already stored block and state in DB.

WARNING: This method should not be used for future slot.

Types

type CachedGetter

type CachedGetter interface {
	ByBlockRoot([32]byte) (state.BeaconState, error)
}

type CanonicalChecker

type CanonicalChecker interface {
	IsCanonical(ctx context.Context, blockRoot [32]byte) (bool, error)
}

CanonicalChecker determines whether the given block root is canonical. In practice this should be satisfied by a type that uses the fork choice store.

type CanonicalHistory

type CanonicalHistory struct {
	// contains filtered or unexported fields
}

func NewCanonicalHistory

func NewCanonicalHistory(h HistoryAccessor, cc CanonicalChecker, cs CurrentSlotter, opts ...CanonicalHistoryOption) *CanonicalHistory

func (*CanonicalHistory) BlockRootForSlot

func (c *CanonicalHistory) BlockRootForSlot(ctx context.Context, target types.Slot) ([32]byte, error)

func (*CanonicalHistory) ReplayerForSlot

func (c *CanonicalHistory) ReplayerForSlot(target types.Slot) Replayer

type CanonicalHistoryOption

type CanonicalHistoryOption func(*CanonicalHistory)

func WithCache

func WithCache(c CachedGetter) CanonicalHistoryOption

type CombinedCache

type CombinedCache struct {
	// contains filtered or unexported fields
}

func (CombinedCache) ByBlockRoot

func (c CombinedCache) ByBlockRoot(r [32]byte) (state.BeaconState, error)

type CurrentSlotter

type CurrentSlotter interface {
	CurrentSlot() types.Slot
}

CurrentSlotter provides the current Slot.

type HistoryAccessor

type HistoryAccessor interface {
	HighestRootsBelowSlot(ctx context.Context, slot types.Slot) (types.Slot, [][32]byte, error)
	GenesisBlockRoot(ctx context.Context) ([32]byte, error)
	Block(ctx context.Context, blockRoot [32]byte) (interfaces.SignedBeaconBlock, error)
	StateOrError(ctx context.Context, blockRoot [32]byte) (state.BeaconState, error)
}

HistoryAccessor describes the minimum set of database methods needed to support the ReplayerBuilder.

type Replayer

type Replayer interface {
	// ReplayBlocks replays the blocks the Replayer knows about based on Builder params
	ReplayBlocks(ctx context.Context) (state.BeaconState, error)
	// ReplayToSlot invokes ReplayBlocks under the hood,
	// but then also runs process_slots to advance the state past the root or slot used in the builder.
	// For example, if you wanted the state to be at the target slot, but only integrating blocks up to
	// slot-1, you could request Builder.ReplayerForSlot(slot-1).ReplayToSlot(slot)
	ReplayToSlot(ctx context.Context, target types.Slot) (state.BeaconState, error)
}

Replayer encapsulates database query and replay logic. It can be constructed via a ReplayerBuilder.

type ReplayerBuilder

type ReplayerBuilder interface {
	// ReplayerForSlot creates a builder that will create a state that includes blocks up to and including the requested slot
	// The resulting Replayer will always yield a state with .Slot=target; if there are skipped blocks
	// between the highest canonical block in the db and the target, the replayer will fast-forward past the intervening
	// slots via process_slots.
	ReplayerForSlot(target types.Slot) Replayer
}

ReplayerBuilder creates a Replayer that can be used to obtain a state at a specified slot or root (only ForSlot implemented so far). See documentation on Replayer for more on how to use this to obtain pre/post-block states

type State

type State struct {
	// contains filtered or unexported fields
}

State is a concrete implementation of StateManager.

func New

func New(beaconDB db.NoHeadAccessDatabase, opts ...StateGenOption) *State

New returns a new state management object.

func (*State) CombinedCache

func (s *State) CombinedCache() *CombinedCache

func (*State) DeleteStateFromCaches

func (s *State) DeleteStateFromCaches(_ context.Context, blockRoot [32]byte) error

DeleteStateFromCaches deletes the state from the caches.

func (*State) DisableSaveHotStateToDB

func (s *State) DisableSaveHotStateToDB(ctx context.Context) error

DisableSaveHotStateToDB exits the mode that saves beacon state to DB for the hot states. This usually gets triggered once there's finality after long duration since finality.

func (*State) EnableSaveHotStateToDB

func (s *State) EnableSaveHotStateToDB(_ context.Context)

EnableSaveHotStateToDB enters the mode that saves hot beacon state to the DB. This usually gets triggered when there's long duration since finality.

func (*State) ForceCheckpoint

func (s *State) ForceCheckpoint(ctx context.Context, blockRoot []byte) error

ForceCheckpoint initiates a cold state save of the given block root's state. This method does not update the "last archived state" but simply saves the specified state from the root argument into the DB.

The name "Checkpoint" isn't referring to checkpoint in the sense of our consensus type, but checkpoint for our historical states.

func (*State) HasState

func (s *State) HasState(ctx context.Context, blockRoot [32]byte) (bool, error)

HasState returns true if the state exists in cache or in DB.

func (*State) MigrateToCold

func (s *State) MigrateToCold(ctx context.Context, fRoot [32]byte) error

MigrateToCold advances the finalized info in between the cold and hot state sections. It moves the recent finalized states from the hot section to the cold section and only preserves the ones that are on archived point.

func (*State) Resume

func (s *State) Resume(ctx context.Context, fState state.BeaconState) (state.BeaconState, error)

Resume resumes a new state management object from previously saved finalized checkpoint in DB.

func (*State) SaveFinalizedState

func (s *State) SaveFinalizedState(fSlot types.Slot, fRoot [32]byte, fState state.BeaconState)

SaveFinalizedState saves the finalized slot, root and state into memory to be used by state gen service. This used for migration at the correct start slot and used for hot state play back to ensure lower bound to start is always at the last finalized state.

func (*State) SaveState

func (s *State) SaveState(ctx context.Context, blockRoot [32]byte, st state.BeaconState) error

SaveState saves the state in the cache and/or DB.

func (*State) StateByRoot

func (s *State) StateByRoot(ctx context.Context, blockRoot [32]byte) (state.BeaconState, error)

StateByRoot retrieves the state using input block root.

func (*State) StateByRootIfCachedNoCopy

func (s *State) StateByRootIfCachedNoCopy(blockRoot [32]byte) state.BeaconState

StateByRootIfCachedNoCopy retrieves a state using the input block root only if the state is already in the cache.

func (*State) StateByRootInitialSync

func (s *State) StateByRootInitialSync(ctx context.Context, blockRoot [32]byte) (state.BeaconState, error)

StateByRootInitialSync retrieves the state from the DB for the initial syncing phase. It assumes initial syncing using a block list rather than a block tree hence the returned state is not copied (block batches returned from initial sync are linear). It invalidates cache for parent root because pre-state will get mutated.

WARNING: Do not use this method for anything other than initial syncing purpose or block tree is applied.

type StateGenOption

type StateGenOption func(*State)

StateGenOption is a functional option for controlling the initialization of a *State value

func WithBackfillStatus

func WithBackfillStatus(bfs *backfill.Status) StateGenOption

type StateManager

type StateManager interface {
	Resume(ctx context.Context, fState state.BeaconState) (state.BeaconState, error)
	DisableSaveHotStateToDB(ctx context.Context) error
	EnableSaveHotStateToDB(_ context.Context)
	HasState(ctx context.Context, blockRoot [32]byte) (bool, error)
	DeleteStateFromCaches(ctx context.Context, blockRoot [32]byte) error
	ForceCheckpoint(ctx context.Context, root []byte) error
	SaveState(ctx context.Context, blockRoot [32]byte, st state.BeaconState) error
	SaveFinalizedState(fSlot types.Slot, fRoot [32]byte, fState state.BeaconState)
	MigrateToCold(ctx context.Context, fRoot [32]byte) error
	StateByRoot(ctx context.Context, blockRoot [32]byte) (state.BeaconState, error)
	StateByRootIfCachedNoCopy(blockRoot [32]byte) state.BeaconState
	StateByRootInitialSync(ctx context.Context, blockRoot [32]byte) (state.BeaconState, error)
}

StateManager represents a management object that handles the internal logic of maintaining both hot and cold states in DB.