beacon

package
v1.22.7 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 19, 2026 License: GPL-3.0 Imports: 51 Imported by: 0

README

Dora: beaconchain indexer

Welcome to the documentation for the indexer package of Dora the Beacon Chain Explorer. This package is responsible for indexing the beacon chain, including blocks, duties, and the current chain state. It consumes events from one or more pool.consensus.Client clients, updates database indexes, and provides functions to gain insights into the current network state.

Overview

The indexer package is divided into several components:

  • Initialization routine
  • Input processor
  • Caching subsystems
    • Block cache
    • Epoch cache
    • Fork cache
  • Processing routines
    • Finalization
    • Pruning
    • Synchronization

Initialization Routine

The initialization routine prefills all caching subsystems with the latest preserved state from the database. It uses the currently finalized epoch as a boundary for loading entities, so only objects between the current wallclock epoch and the current finalized epoch are restored. Entities older than inMemoryEpochs are directly pruned to save memory. This process runs before the indexer starts to receive events from the attached clients. For networks with large unfinality periods, this might take a few seconds to minutes.

Input Processor

The input processor consumes events from an underlying consensus pool client and feeds the caching subsystems with new data. It:

  • Attaches to "block" and "head" events.
  • Processes each received block, loading its block header and body.
  • Ensures the completeness of the block cache by backfilling parent blocks.
  • Dumps fully received blocks into the unfinalized blocks table for restoration after restart.
  • Tracks the latest head of the client and detects chain reorgs.

An instance of the input processor is created for every client attached to the indexer via indexer.AddClient.

Caching Subsystems

Block Cache

The block cache subsystem keeps an overview of all unfinalized blocks in the network. It:

  • Provides block accessors by various block properties.
  • Checks block relationships and calculates distances between blocks.
  • Might hold pruned blocks (without block bodies), but bodies can be restored on purpose.
Epoch Cache

The epoch cache subsystem maintains an overview of unfinalized epoch stats. It:

  • Holds duty and epoch statistics for each epoch.
  • Identifies epoch stats by the epoch's dependent root and number.
  • Might hold pruned epoch stats, keeping only proposer + sync committee duties and aggregations in memory
  • Can restores full epoch stats from the database, which is an expensive operation.
  • Can pre-calculate the next epoch stats, however this might not be accurate all the time.
Fork Cache

The fork cache subsystem keeps an overview of all unfinalized forks in the network. It:

  • Identifies forks by the base block root and leaf block root.
  • Numbers forks with an ascending internal counter.
  • Holds the fork detection system to identify current fork IDs and detect possible forks.
  • Uses forkId as a placeholder for unknown or canonical finalized forks.

Processing Routines

Finalization Routine

The finalization routine processes unfinalized blocks from the block cache after finalization. It:

  • Writes blocks, epoch aggregations, and child objects to the database.
  • Stores orphaned blocks in the orphaned blocks table.
  • Wipes processed blocks and epoch stats from caches.
Pruning Routine

The pruning routine pre-finalizes old unfinalized epochs and prunes memory-heavy data from cache. It:

  • Is controlled by the inMemoryEpochs setting.
  • Generates non-final epoch voting aggregations.
  • Writes blocks and child objects to the database.
  • Stores pruned epoch aggregations in cache and the unfinalized epochs table for restoration.
Synchronization Routine

The synchronization routine processes all missed historic data. It:

  • Ensures each epoch is properly indexed.
  • Loads canonical blocks and dependent states from a ready node.
  • Computes epoch aggregations and writes them, along with canonical blocks and child objects, to the database.
  • Is triggered by failed finalization or the initialization routine.

Documentation

Overview

Code generated by dynamic-ssz. DO NOT EDIT. Hash: 23cc3d81625bca9f5609a71ab4097c8e2e896f2fb49ddcc1567f532b4e30ec00 Version: v1.2.2 (https://github.com/pk910/dynamic-ssz)

Index

Constants

View Source 
const (
	BuilderStatusExited     uint16 = 1 << iota // Builder has exited (withdrawable_epoch reached)
	BuilderStatusSuperseded                    // Builder index was reused, this pubkey is no longer active
)

Builder status flag constants representing different builder states

View Source 
const (
	ValidatorStatusEligible    uint16 = 1 << iota // Validator is eligible for activation
	ValidatorStatusPending                        // Validator is pending activation
	ValidatorStatusExited                         // Validator has exited
	ValidatorStatusSlashed                        // Validator has been slashed
	ValidatorStatusHasAddress                     // Validator has withdrawal credentials set to 0x01 or 0x02
	ValidatorStatusCompounding                    // Validator is set to compound rewards (0x02)
)

Validator status flag constants representing different validator states

View Source 
const BuilderIndexFlag = uint64(1 << 40)

BuilderIndexFlag separates builder indices from validator indices in the pubkey cache

View Source 
const EtherGweiFactor = 1_000_000_000
View Source 
const FarFutureEpoch = phase0.Epoch(math.MaxUint64)

Variables

This section is empty.

Functions

func CalculateMinMaxTimesForStorage added in v1.17.0 

func CalculateMinMaxTimesForStorage(times []ExecutionTime) (uint32, uint32)

CalculateMinMaxTimesForStorage calculates the overall min/max times from a list of client execution times

func GetBuilderStatusFlags added in v1.21.0 

func GetBuilderStatusFlags(builder *gloas.Builder) uint16

GetBuilderStatusFlags calculates the status flags for a builder

func GetValidatorStatusFlags added in v1.14.0 

func GetValidatorStatusFlags(validator *phase0.Validator) uint16

GetValidatorStatusFlags calculates the status flags for a validator Returns a bitmask of flags representing the validator's state

func LoadBeaconBlock 

func LoadBeaconBlock(ctx context.Context, client *Client, root phase0.Root) (*all.SignedBeaconBlock, error)

LoadBeaconBlock loads the block body from the RPC client as a fork-agnostic *all.SignedBeaconBlock.

func LoadBeaconHeader 

func LoadBeaconHeader(ctx context.Context, client *Client, root phase0.Root) (*phase0.SignedBeaconBlockHeader, error)

LoadBeaconHeader loads the block header from the client.

func LoadBeaconHeaderBySlot 

func LoadBeaconHeaderBySlot(ctx context.Context, client *Client, slot phase0.Slot) (*phase0.SignedBeaconBlockHeader, phase0.Root, bool, error)

LoadBeaconHeaderBySlot loads the block header with given slot number from the client.

func LoadBeaconState 

func LoadBeaconState(ctx context.Context, client *Client, root phase0.Root) (*all.BeaconState, error)

LoadBeaconState loads the beacon state from the client as a fork-agnostic *all.BeaconState.

func LoadExecutionPayload added in v1.21.0 

func LoadExecutionPayload(ctx context.Context, client *Client, root phase0.Root) (*all.SignedExecutionPayloadEnvelope, error)

LoadExecutionPayload loads the execution payload from the client.

func MarshalBlockAccessList added in v1.22.0 

func MarshalBlockAccessList(bal []byte, compress bool) (version uint64, data []byte, err error)

MarshalBlockAccessList wraps raw EIP-7928 RLP BAL bytes for blockdb storage. Returns (0, nil, nil) for empty input so callers can hand the result straight to BlockData{BalVersion, BalData} and have the "BAL absent" case map to flags not setting BlockDataFlagBal.

func MarshalSignedBeaconBlockSSZ added in v1.22.6 

func MarshalSignedBeaconBlockSSZ(dynSsz *dynssz.DynSsz, block *all.SignedBeaconBlock, compress, forceSSZ bool) (uint64, []byte, error)

MarshalSignedBeaconBlockSSZ marshals a fork-agnostic signed beacon block to SSZ (or JSON when SSZ encoding is disabled at runtime). The returned version word stores the fork in the lower bits, with optional compression and JSON-format flags OR-ed in.

func MarshalVersionedSignedExecutionPayloadEnvelopeSSZ added in v1.21.0 

func MarshalVersionedSignedExecutionPayloadEnvelopeSSZ(dynSsz *dynssz.DynSsz, payload *all.SignedExecutionPayloadEnvelope, compress bool) (version uint64, ssz []byte, err error)

MarshalVersionedSignedExecutionPayloadEnvelopeSSZ marshals a signed execution payload envelope using SSZ encoding.

func UnmarshalBlockAccessList added in v1.22.0 

func UnmarshalBlockAccessList(version uint64, data []byte) ([]byte, error)

UnmarshalBlockAccessList decodes a BAL byte slice previously produced by MarshalBlockAccessList, returning the raw RLP bytes.

func UnmarshalSignedBeaconBlockSSZ added in v1.22.6 

func UnmarshalSignedBeaconBlockSSZ(dynSsz *dynssz.DynSsz, versionWord uint64, ssz []byte) (*all.SignedBeaconBlock, error)

UnmarshalSignedBeaconBlockSSZ inverts MarshalSignedBeaconBlockSSZ.

func UnmarshalVersionedSignedExecutionPayloadEnvelopeSSZ added in v1.21.0 

func UnmarshalVersionedSignedExecutionPayloadEnvelopeSSZ(dynSsz *dynssz.DynSsz, version uint64, ssz []byte) (*all.SignedExecutionPayloadEnvelope, error)

UnmarshalVersionedSignedExecutionPayloadEnvelopeSSZ unmarshals a versioned signed execution payload envelope using SSZ encoding.

func UnwrapDbBuilder added in v1.21.0 

func UnwrapDbBuilder(dbBuilder *dbtypes.Builder) *gloas.Builder

UnwrapDbBuilder converts a dbtypes.Builder to a gloas.Builder

func UnwrapDbValidator added in v1.14.0 

func UnwrapDbValidator(dbValidator *dbtypes.Validator) *phase0.Validator

UnwrapDbValidator unwraps a dbtypes.Validator to a phase0.Validator

Types

type Block 

type Block struct {
	Root     phase0.Root
	Slot     phase0.Slot
	BlockUID uint64
	// contains filtered or unexported fields
}

Block represents a beacon block.

func (*Block) AddExecutionTime added in v1.17.0 

func (block *Block) AddExecutionTime(ctx context.Context, execTime ExecutionTime)

AddExecutionTime adds an execution time to this block

func (*Block) AwaitBlock 

func (block *Block) AwaitBlock(ctx context.Context, timeout time.Duration) *all.SignedBeaconBlock

AwaitBlock waits for the fork-agnostic signed beacon block of this block to be available.

func (*Block) AwaitExecutionPayload added in v1.21.0 

func (block *Block) AwaitExecutionPayload(ctx context.Context, timeout time.Duration) *all.SignedExecutionPayloadEnvelope

AwaitExecutionPayload waits for the execution payload of this block to be available.

func (*Block) AwaitHeader 

func (block *Block) AwaitHeader(ctx context.Context, timeout time.Duration) *phase0.SignedBeaconBlockHeader

AwaitHeader waits for the signed beacon block header of this block to be available.

func (*Block) Dispose added in v1.14.0 

func (block *Block) Dispose()

func (*Block) EnsureBlock 

func (block *Block) EnsureBlock(loadBlock func() (*all.SignedBeaconBlock, error)) (bool, error)

EnsureBlock ensures that the fork-agnostic signed beacon block of this block is available.

func (*Block) EnsureExecutionPayload added in v1.21.0 

func (block *Block) EnsureExecutionPayload(loadExecutionPayload func() (*all.SignedExecutionPayloadEnvelope, error)) (bool, error)

EnsureExecutionPayload ensures that the execution payload of this block is available.

func (*Block) EnsureHeader 

func (block *Block) EnsureHeader(loadHeader func() (*phase0.SignedBeaconBlockHeader, error)) error

EnsureHeader ensures that the signed beacon block header of this block is available.

func (*Block) GetBlock 

func (block *Block) GetBlock(ctx context.Context) *all.SignedBeaconBlock

GetBlock returns the fork-agnostic signed beacon block of this block.

func (*Block) GetBlockIndex 

func (block *Block) GetBlockIndex(ctx context.Context) *BlockBodyIndex

GetBlockIndex returns the block index of this block.

func (*Block) GetCachedBlock added in v1.22.2 

func (block *Block) GetCachedBlock() *all.SignedBeaconBlock

GetCachedBlock returns the in-memory fork-agnostic signed beacon block if it is currently held in the block cache. Returns nil if the body would only be available via a database lookup. Use this when a caller wants to operate purely on cached state without triggering disk I/O.

func (*Block) GetDbBlock 

func (block *Block) GetDbBlock(indexer *Indexer, isCanonical bool) *dbtypes.Slot

GetDbBlock returns the database representation of this block.

func (*Block) GetDbConsolidationRequests 

func (block *Block) GetDbConsolidationRequests(indexer *Indexer, isCanonical bool) []*dbtypes.ConsolidationRequest

GetDbConsolidationRequests returns the database representation of the consolidation requests in this block.

func (*Block) GetDbDeposits 

func (block *Block) GetDbDeposits(indexer *Indexer, depositIndex *uint64, isCanonical bool) []*dbtypes.Deposit

GetDbDeposits returns the database representation of the deposits in this block.

func (*Block) GetDbSlashings 

func (block *Block) GetDbSlashings(indexer *Indexer, isCanonical bool) []*dbtypes.Slashing

GetDbSlashings returns the database representation of the slashings in this block.

func (*Block) GetDbVoluntaryExits 

func (block *Block) GetDbVoluntaryExits(indexer *Indexer, isCanonical bool) []*dbtypes.VoluntaryExit

GetDbVoluntaryExits returns the database representation of the voluntary exits in this block.

func (*Block) GetDbWithdrawalRequests added in v1.12.0 

func (block *Block) GetDbWithdrawalRequests(indexer *Indexer, isCanonical bool) []*dbtypes.WithdrawalRequest

GetDbWithdrawalRequests returns the database representation of the withdrawal requests in this block.

func (*Block) GetDbWithdrawals added in v1.21.0 

func (block *Block) GetDbWithdrawals(indexer *Indexer, isCanonical bool) []*dbtypes.Withdrawal

GetDbWithdrawals returns the database representation of the withdrawals in this block.

func (*Block) GetExecutionPayload added in v1.21.0 

func (block *Block) GetExecutionPayload(ctx context.Context) *all.SignedExecutionPayloadEnvelope

GetExecutionPayload returns the execution payload of this block.

func (*Block) GetExecutionTimes added in v1.17.0 

func (block *Block) GetExecutionTimes() []ExecutionTime

GetExecutionTimes returns a copy of the execution times for this block

func (*Block) GetForkId 

func (block *Block) GetForkId() ForkKey

GetForkId returns the fork ID of this block.

func (*Block) GetHeader 

func (block *Block) GetHeader() *phase0.SignedBeaconBlockHeader

GetHeader returns the signed beacon block header of this block.

func (*Block) GetMaxExecutionTime added in v1.17.0 

func (block *Block) GetMaxExecutionTime() uint32

GetMaxExecutionTime returns the maximum execution time across all clients

func (*Block) GetMinExecutionTime added in v1.17.0 

func (block *Block) GetMinExecutionTime() uint32

GetMinExecutionTime returns the minimum execution time across all clients

func (*Block) GetParentRoot 

func (block *Block) GetParentRoot() *phase0.Root

GetParentRoot returns the parent root of this block.

func (*Block) GetSeenBy 

func (block *Block) GetSeenBy() []*Client

GetSeenBy returns a list of clients that have seen this block.

func (*Block) HasExecutionPayload added in v1.21.0 

func (block *Block) HasExecutionPayload() bool

HasExecutionPayload returns true if this block has an execution payload.

func (*Block) SetBlock 

func (block *Block) SetBlock(body *all.SignedBeaconBlock)

SetBlock sets the fork-agnostic signed beacon block of this block.

func (*Block) SetExecutionPayload added in v1.21.0 

func (block *Block) SetExecutionPayload(payload *all.SignedExecutionPayloadEnvelope)

SetExecutionPayload sets the execution payload of this block.

func (*Block) SetHeader 

func (block *Block) SetHeader(header *phase0.SignedBeaconBlockHeader)

SetHeader sets the signed beacon block header of this block.

func (*Block) SetSeenBy 

func (block *Block) SetSeenBy(client *Client, recvDelay int32)

SetSeenBy sets the client that has seen this block.

type BlockBodyIndex 

type BlockBodyIndex struct {
	Graffiti            [32]byte
	ExecutionExtraData  []byte
	ExecutionHash       phase0.Hash32
	ExecutionParentHash phase0.Hash32
	ExecutionNumber     uint64
	SyncParticipation   float32
	EthTransactionCount uint64
	BlobCount           uint64
	BuilderIndex        uint64
	GasUsed             uint64
	GasLimit            uint64
	BlockSize           uint64
}

BlockBodyIndex holds important block properties that are used as index for cache lookups. this structure should be preserved after pruning, so the block is still identifiable.

type BuilderData added in v1.21.0 

type BuilderData struct {
	WithdrawableEpoch phase0.Epoch
}

BuilderData contains the essential builder state information for active builders. Only WithdrawableEpoch can change during a builder's lifetime; all other fields are static.

type BuilderSetStreamer added in v1.21.0 

type BuilderSetStreamer func(index gloas.BuilderIndex, flags uint16, activeData *BuilderData, builder *gloas.Builder) error

BuilderSetStreamer is a callback for streaming builder data

type CacheDebugMapStats added in v1.20.4 

type CacheDebugMapStats struct {
	Length int
	Size   int64
}

CacheDebugMapStats holds the entry count and estimated memory footprint of a Go map's hash table structure (buckets + overhead, not values behind pointers).

type CacheDebugStats added in v1.13.0 

type CacheDebugStats struct {
	BlockCache struct {
		SlotMap        CacheDebugMapStats
		RootMap        CacheDebugMapStats
		ParentMap      CacheDebugMapStats
		ExecBlockMap   CacheDebugMapStats
		BlockHeader    uint64
		BlockBodies    uint64
		BlockIndexes   uint64
		BlockSize      uint64
		EstimatedTotal int64
	}
	EpochCache struct {
		StatsMap       CacheDebugMapStats
		StateMap       CacheDebugMapStats
		StatsFull      uint64
		StatsPrecalc   uint64
		StatsPruned    uint64
		StateLoaded    uint64
		VotesCacheLen  uint64
		VotesCacheHit  uint64
		VotesCacheMiss uint64
		EstimatedTotal int64
	}
	ForkCache struct {
		ForkMap            CacheDebugMapStats
		ParentIdCacheLen   uint64
		ParentIdCacheHit   uint64
		ParentIdCacheMiss  uint64
		ParentIdsCacheLen  uint64
		ParentIdsCacheHit  uint64
		ParentIdsCacheMiss uint64
		EstimatedTotal     int64
	}
	ValidatorCache struct {
		Validators        uint64
		ValidatorDiffs    uint64
		ValidatorData     uint64
		ValidatorActivity uint64
		PubkeyMap         CacheDebugMapStats
		EstimatedTotal    int64
	}
	TotalEstimated int64
}

type ChainHead 

type ChainHead struct {
	HeadBlock             *Block        // The head block of the chain.
	AggregatedHeadVotes   phase0.Gwei   // The aggregated votes of the last 2 epochs for the head block.
	PerEpochVotingPercent []float64     // The voting percentage in the last epochs.
	PerEpochVotes         []phase0.Gwei // The votes in the last epochs.
}

ChainHead represents a head block of the chain.

type Client 

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

Client represents a consensus pool client that should be used for indexing beacon blocks.

func (*Client) GetClient 

func (c *Client) GetClient() *consensus.Client

func (*Client) GetIndex 

func (c *Client) GetIndex() uint16

func (*Client) GetPriority 

func (c *Client) GetPriority() int

type EpochStats 

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

EpochStats holds the epoch-specific information based on the underlying dependent beacon state.

func (*EpochStats) GetDbEpoch 

func (es *EpochStats) GetDbEpoch(indexer *Indexer, headBlock *Block) *dbtypes.Epoch

GetDbEpoch returns the database Epoch representation for the EpochStats.

func (*EpochStats) GetDependentRoot added in v1.12.1 

func (es *EpochStats) GetDependentRoot() phase0.Root

func (*EpochStats) GetEpoch 

func (es *EpochStats) GetEpoch() phase0.Epoch

func (*EpochStats) GetEpochVotes 

func (es *EpochStats) GetEpochVotes(indexer *Indexer, headBlock *Block) *EpochVotes

GetEpochVotes aggregates & returns the EpochVotes for the EpochStats.

func (*EpochStats) GetOrLoadValues 

func (es *EpochStats) GetOrLoadValues(ctx context.Context, indexer *Indexer, withPrecalc bool, keepInCache bool) *EpochStatsValues

GetOrLoadValues returns the EpochStats values, loading them from the database if necessary.

func (*EpochStats) GetValues 

func (es *EpochStats) GetValues(withPrecalc bool) *EpochStatsValues

GetValues returns the EpochStats values.

type EpochStatsPacked 

type EpochStatsPacked struct {
	ActiveValidators           []EpochStatsPackedValidator `ssz-max:"10000000"`
	ProposerDuties             []phase0.ValidatorIndex     `ssz-max:"100"`
	SyncCommitteeDuties        []phase0.ValidatorIndex     `ssz-max:"10000"`
	RandaoMix                  phase0.Hash32               `ssz-size:"32"`
	NextRandaoMix              phase0.Hash32               `ssz-size:"32"`
	TotalBalance               phase0.Gwei
	ActiveBalance              phase0.Gwei
	FirstDepositIndex          uint64
	PendingWithdrawals         []electra.PendingPartialWithdrawal `ssz-max:"10000000"`
	BuilderPendingWithdrawals  []gloas.BuilderPendingWithdrawal   `ssz-max:"10000000"`
	DelayedBuilderPaymentCount uint32
	SourceBlockUid             uint64
	PendingConsolidations      []electra.PendingConsolidation `ssz-max:"10000000"`
	ConsolidatingBalance       phase0.Gwei
}

EpochStatsPacked holds the packed values for the epoch-specific information. 

generate ssz: (this is really ugly, needs path patching and post-fixing to work)
sszgen --suffix ssz --path . --include $GOPATH/pkg/mod/github.com/ethpandaops/go-eth2-client\@v0.26.0/spec/phase0,$GOPATH/pkg/mod/github.com/ethpandaops/go-eth2-client\@v0.26.0/spec/electra --objs EpochStatsPacked

func (*EpochStatsPacked) HashTreeRoot added in v1.15.0 

func (t *EpochStatsPacked) HashTreeRoot() (root [32]byte, err error)

func (*EpochStatsPacked) HashTreeRootWith added in v1.15.0 

func (t *EpochStatsPacked) HashTreeRootWith(hh sszutils.HashWalker) error

func (*EpochStatsPacked) MarshalSSZ added in v1.15.0 

func (t *EpochStatsPacked) MarshalSSZ() ([]byte, error)

func (*EpochStatsPacked) MarshalSSZTo added in v1.15.0 

func (t *EpochStatsPacked) MarshalSSZTo(buf []byte) (dst []byte, err error)

func (*EpochStatsPacked) SizeSSZ added in v1.15.0 

func (t *EpochStatsPacked) SizeSSZ() (size int)

func (*EpochStatsPacked) UnmarshalSSZ added in v1.15.0 

func (t *EpochStatsPacked) UnmarshalSSZ(buf []byte) (err error)

type EpochStatsPackedValidator 

type EpochStatsPackedValidator struct {
	ValidatorIndexOffset uint32 // offset to the previous index in the list (this is smaller than storing the full validator index)
	EffectiveBalanceEth  uint32 // effective balance in full ETH
}

EpochStatsPackedValidator holds the packed values for an active validator.

type EpochStatsValues 

type EpochStatsValues struct {
	RandaoMix                  phase0.Hash32
	NextRandaoMix              phase0.Hash32
	ActiveIndices              []phase0.ValidatorIndex
	EffectiveBalances          []uint32 // effective balance in full ETH of last epoch for pre-fulu stats, effective balance in full ETH of current epoch for fulu+ stats
	ProposerDuties             []phase0.ValidatorIndex
	AttesterDuties             [][][]duties.ActiveIndiceIndex
	SyncCommitteeDuties        []phase0.ValidatorIndex
	PtcDuties                  [][]duties.ActiveIndiceIndex // [slot_index][ptc_member_index] - PTC duties for Gloas+ epochs
	ActiveValidators           uint64
	TotalBalance               phase0.Gwei
	ActiveBalance              phase0.Gwei
	EffectiveBalance           phase0.Gwei
	FirstDepositIndex          uint64
	PendingWithdrawals         []electra.PendingPartialWithdrawal
	BuilderPendingWithdrawals  []gloas.BuilderPendingWithdrawal
	DelayedBuilderPaymentCount uint32 // number of delayed payments at the tail of BuilderPendingWithdrawals
	SourceBlockUid             uint64 // block UID of the source block (last block of parent epoch)
	PendingConsolidations      []electra.PendingConsolidation
	ConsolidatingBalance       phase0.Gwei
}

EpochStatsValues holds the values for the epoch-specific information.

func (*EpochStatsValues) GetEffectiveBalance 

func (v *EpochStatsValues) GetEffectiveBalance(index duties.ActiveIndiceIndex) phase0.Gwei

GetEffectiveBalance returns the effective balance for the given active validator indice.

type EpochVotes 

type EpochVotes struct {
	CurrentEpoch struct {
		TargetVoteAmount phase0.Gwei
		HeadVoteAmount   phase0.Gwei
		TotalVoteAmount  phase0.Gwei
	}
	NextEpoch struct {
		TargetVoteAmount phase0.Gwei
		HeadVoteAmount   phase0.Gwei
		TotalVoteAmount  phase0.Gwei
	}
	TargetVotePercent float64
	HeadVotePercent   float64
	TotalVotePercent  float64
	AmountIsCount     bool
}

EpochVotes represents the aggregated votes for an epoch.

type ExecutionTime added in v1.17.0 

type ExecutionTime struct {
	ClientType uint8  // client type
	MinTime    uint16 // milliseconds
	MaxTime    uint16 // milliseconds
	AvgTime    uint16 // milliseconds
	Count      uint16 // number of clients
}

ExecutionTime represents execution timing data for a specific client

type ExecutionTimeData added in v1.17.0 

type ExecutionTimeData interface {
	GetClient() *execution.Client
	GetTime() uint16
}

ExecutionTimeData is an interface for execution time data

type ExecutionTimeProvider added in v1.17.0 

type ExecutionTimeProvider interface {
	GetAndDeleteExecutionTimes(blockHash common.Hash) []ExecutionTimeData
}

ExecutionTimeProvider is an interface for getting execution times from cache

type Fork 

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

Fork represents a fork in the beacon chain.

func (*Fork) GetBase 

func (fork *Fork) GetBase() (phase0.Slot, phase0.Root)

func (*Fork) GetLeaf 

func (fork *Fork) GetLeaf() (phase0.Slot, phase0.Root)

func (*Fork) GetParent 

func (fork *Fork) GetParent() ForkKey

type ForkHead 

type ForkHead struct {
	ForkId ForkKey
	Fork   *Fork
	Block  *Block
}

ForkHead represents a fork head with its ID, fork, and block.

type ForkKey 

type ForkKey uint64

ForkKey represents a key used for indexing forks.

type Indexer 

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

Indexer is responsible for indexing the ethereum beacon chain.

func NewIndexer 

func NewIndexer(ctx context.Context, logger logrus.FieldLogger, consensusPool *consensus.Pool) *Indexer

NewIndexer creates a new instance of the Indexer.

func (*Indexer) AddClient 

func (indexer *Indexer) AddClient(index uint16, client *consensus.Client, priority int, archive bool, skipValidators bool) *Client

AddClient adds a new consensus pool client to the indexer.

func (*Indexer) GetActivationExitQueueLengths added in v1.14.0 

func (indexer *Indexer) GetActivationExitQueueLengths(epoch phase0.Epoch, overrideForkId *ForkKey) (uint64, uint64)

GetActivationExitQueueLengths returns the activation and exit queue lengths for the given epoch.

func (*Indexer) GetActivityHistoryLength added in v1.13.0 

func (indexer *Indexer) GetActivityHistoryLength() uint16

func (*Indexer) GetAllClients 

func (indexer *Indexer) GetAllClients() []*Client

GetAllClients returns a slice of all clients in the indexer.

func (*Indexer) GetBlockBids added in v1.21.0 

func (indexer *Indexer) GetBlockBids(parentBlockRoot phase0.Root, slot phase0.Slot) []*dbtypes.BlockBid

GetBlockBids returns the execution payload bids for a given parent block root and slot. It first checks the in-memory cache, then falls back to the database. Filtering by slot is required because orphaned/skipped predecessor slots share the same parent root as the canonical block that ends up replacing them.

func (*Indexer) GetBlockByParentRoot 

func (indexer *Indexer) GetBlockByParentRoot(blockRoot phase0.Root) []*Block

GetBlockByParentRoot returns a slice of blocks with the given parent root.

func (*Indexer) GetBlockByRoot 

func (indexer *Indexer) GetBlockByRoot(blockRoot phase0.Root) *Block

GetBlockByRoot returns the block with the given block root.

func (*Indexer) GetBlockByStateRoot 

func (indexer *Indexer) GetBlockByStateRoot(stateRoot phase0.Root) *Block

GetBlockByStateRoot returns the block with the given state root.

func (*Indexer) GetBlockCacheState 

func (indexer *Indexer) GetBlockCacheState() (finalizedEpoch phase0.Epoch, prunedEpoch phase0.Epoch)

GetBlockCacheState returns the state of the block cache, including the last finalized epoch and the last pruned epoch. this represents the internal cache state and might be behind the actual finalization checkpoint.

func (*Indexer) GetBlockDistance 

func (indexer *Indexer) GetBlockDistance(baseRoot phase0.Root, headRoot phase0.Root) (bool, uint64)

GetBlockDistance returns whether the base root is in the canonical chain defined by the head root and the distance between both blocks.

func (*Indexer) GetBlocksByExecutionBlockHash 

func (indexer *Indexer) GetBlocksByExecutionBlockHash(blockHash phase0.Hash32) []*Block

GetBlocksByExecutionBlockHash returns a slice of blocks with the given execution block hash.

func (*Indexer) GetBlocksByExecutionBlockNumber 

func (indexer *Indexer) GetBlocksByExecutionBlockNumber(blockNumber uint64) []*Block

GetBlocksByExecutionBlockNumber returns a slice of blocks with the given execution block number.

func (*Indexer) GetBlocksByForkId added in v1.18.3 

func (indexer *Indexer) GetBlocksByForkId(forkId ForkKey) []*Block

GetBlocksByForkId returns a slice of blocks that belong to the specified forkId.

func (*Indexer) GetBlocksBySlot 

func (indexer *Indexer) GetBlocksBySlot(slot phase0.Slot) []*Block

GetBlocksBySlot returns a slice of blocks with the given slot.

func (*Indexer) GetBuilderByIndex added in v1.21.0 

func (indexer *Indexer) GetBuilderByIndex(index gloas.BuilderIndex, overrideForkId *ForkKey) *gloas.Builder

GetBuilderByIndex returns the builder by index for the canonical head.

func (*Indexer) GetBuilderSetSize added in v1.21.0 

func (indexer *Indexer) GetBuilderSetSize() uint64

GetBuilderSetSize returns the size of the builder set cache.

func (*Indexer) GetCacheDebugStats added in v1.13.0 

func (indexer *Indexer) GetCacheDebugStats() *CacheDebugStats

func (*Indexer) GetCanonicalHead 

func (indexer *Indexer) GetCanonicalHead(overrideForkId *ForkKey) *Block

GetCanonicalHead returns the canonical head block of the chain.

func (*Indexer) GetChainHeads 

func (indexer *Indexer) GetChainHeads() []*ChainHead

GetChainHeads returns the chain heads sorted by voting percentages.

func (*Indexer) GetDynSSZ added in v1.14.0 

func (indexer *Indexer) GetDynSSZ() *dynssz.DynSsz

GetDynSSZ returns the dynSsz instance used by the indexer.

func (*Indexer) GetEpochStats 

func (indexer *Indexer) GetEpochStats(epoch phase0.Epoch, overrideForkId *ForkKey) *EpochStats

GetEpochStats returns the epoch stats for the given epoch and optional fork ID override.

func (*Indexer) GetEpochStatsByBlockRoot added in v1.15.0 

func (indexer *Indexer) GetEpochStatsByBlockRoot(epoch phase0.Epoch, blockRoot phase0.Root) *EpochStats

func (*Indexer) GetEpochStatsByEpoch added in v1.18.3 

func (indexer *Indexer) GetEpochStatsByEpoch(epoch phase0.Epoch) []*EpochStats

GetEpochStatsByEpoch returns the epoch stats for the given epoch.

func (*Indexer) GetFinalizedForkId added in v1.18.3 

func (indexer *Indexer) GetFinalizedForkId() ForkKey

GetFinalizedForkId returns the finalized fork id.

func (*Indexer) GetForkHeads 

func (indexer *Indexer) GetForkHeads() []*ForkHead

GetForkHeads returns a slice of fork heads in the indexer.

func (*Indexer) GetFullValidatorByIndex added in v1.14.0 

func (indexer *Indexer) GetFullValidatorByIndex(validatorIndex phase0.ValidatorIndex, epoch phase0.Epoch, overrideForkId *ForkKey, withBalances bool) *v1.Validator

GetFullValidatorByIndex returns the full validator set entry for a given validator index, including balances and validator status. If an overrideForkId is provided, the validator for the fork is returned.

func (*Indexer) GetInclusionListsBySlot added in v1.21.0 

func (indexer *Indexer) GetInclusionListsBySlot(slot phase0.Slot) []*v1.SignedInclusionList

GetInclusionListsBySlot returns the cached inclusion lists for a given slot.

func (*Indexer) GetLatestDepositQueue added in v1.15.0 

func (indexer *Indexer) GetLatestDepositQueue(overrideForkId *ForkKey) []*electra.PendingDeposit

GetLatestDepositQueue returns the latest deposit queue for the given epoch and optional fork ID override.

func (*Indexer) GetLatestDepositQueueByBlockRoot added in v1.15.0 

func (indexer *Indexer) GetLatestDepositQueueByBlockRoot(blockRoot phase0.Root) (phase0.Root, phase0.Slot, phase0.Gwei, []*electra.PendingDeposit)

GetLatestDepositQueueByBlockRoot returns the latest deposit queue for the given block root.

func (*Indexer) GetOrphanedBlockByRoot 

func (indexer *Indexer) GetOrphanedBlockByRoot(blockRoot phase0.Root) (*Block, error)

GetOrphanedBlockByRoot returns the orphaned block with the given block root.

func (*Indexer) GetParentForkIds added in v1.12.1 

func (indexer *Indexer) GetParentForkIds(forkId ForkKey) []ForkKey

GetParentForkIds returns the parent fork ids of the given fork.

func (*Indexer) GetReadyClient 

func (indexer *Indexer) GetReadyClient(preferArchive bool) *Client

GetReadyClient returns a single client that is on the finalized chain and preference for archive clients.

func (*Indexer) GetReadyClientByBlockRoot 

func (indexer *Indexer) GetReadyClientByBlockRoot(blockRoot phase0.Root, preferArchive bool) *Client

GetReadyClientByBlockRoot returns a single client that is ready for requests for the chain including the block root and preference for archive clients.

func (*Indexer) GetReadyClients 

func (indexer *Indexer) GetReadyClients(preferArchive bool) []*Client

GetReadyClients returns a slice of clients that are on the finalized chain and preference for archive clients.

func (*Indexer) GetReadyClientsByBlockRoot 

func (indexer *Indexer) GetReadyClientsByBlockRoot(blockRoot phase0.Root, preferArchive bool) []*Client

GetReadyClientsByBlockRoot returns a slice of clients that are ready for requests for the chain including the block root and preference for archive clients.

func (*Indexer) GetReadyClientsByCheckpoint 

func (indexer *Indexer) GetReadyClientsByCheckpoint(finalizedEpoch phase0.Epoch, finalizedRoot phase0.Root, preferArchive bool) []*Client

GetReadyClientsByCheckpoint returns a slice of clients that are ready for processing based on the finalized root and preference for archive clients.

func (*Indexer) GetRecentBuilderBalances added in v1.21.0 

func (indexer *Indexer) GetRecentBuilderBalances(overrideForkId *ForkKey) []phase0.Gwei

GetRecentBuilderBalances returns the most recent builder balances for the given fork. Starts with epoch-boundary balances and replays in-epoch blocks to reflect live state: builder withdrawals/payments are deducted and builder deposits are credited.

func (*Indexer) GetRecentValidatorBalances added in v1.14.0 

func (indexer *Indexer) GetRecentValidatorBalances(overrideForkId *ForkKey) []phase0.Gwei

GetRecentValidatorBalances returns the most recent validator balances for the given fork.

func (*Indexer) GetSynchronizerState added in v1.12.1 

func (indexer *Indexer) GetSynchronizerState() (running bool, syncHead phase0.Epoch)

GetSynchronizerState returns the state of the synchronizer, including whether it is running and the current epoch.

func (*Indexer) GetValidatorActivity added in v1.13.0 

func (indexer *Indexer) GetValidatorActivity(validatorIndex phase0.ValidatorIndex) ([]ValidatorActivity, phase0.Epoch)

GetValidatorActivity returns the validator activity for a given validator index.

func (*Indexer) GetValidatorActivityCount added in v1.14.0 

func (indexer *Indexer) GetValidatorActivityCount(validatorIndex phase0.ValidatorIndex, startEpoch phase0.Epoch) (uint64, phase0.Epoch)

GetValidatorActivityCount returns the number of validator activity for a given validator index.

func (*Indexer) GetValidatorByIndex added in v1.13.0 

func (indexer *Indexer) GetValidatorByIndex(index phase0.ValidatorIndex, overrideForkId *ForkKey) *phase0.Validator

GetValidatorByIndex returns the validator by index for a given forkId.

func (*Indexer) GetValidatorFlags added in v1.14.0 

func (indexer *Indexer) GetValidatorFlags(validatorIndex phase0.ValidatorIndex) uint16

GetValidatorFlags returns the validator flags for a given validator index.

func (*Indexer) GetValidatorInclusionDistance added in v1.20.4 

func (indexer *Indexer) GetValidatorInclusionDistance(validatorIndex phase0.ValidatorIndex, lookbackEpochs phase0.Epoch) (count uint64, totalDelay uint64)

GetValidatorInclusionDistance returns the attestation count and total inclusion delay for a validator over the last lookbackEpochs epochs, using only cached blocks.

func (*Indexer) GetValidatorIndexByPubkey added in v1.13.0 

func (indexer *Indexer) GetValidatorIndexByPubkey(pubkey phase0.BLSPubKey) (phase0.ValidatorIndex, bool)

GetValidatorIndexByPubkey returns the validator index for a given pubkey.

func (*Indexer) GetValidatorSetSize added in v1.14.0 

func (indexer *Indexer) GetValidatorSetSize() uint64

GetValidatorSetSize returns the size of the validator set cache.

func (*Indexer) GetValidatorStatusMap added in v1.14.0 

func (indexer *Indexer) GetValidatorStatusMap(epoch phase0.Epoch, blockRoot phase0.Root) map[v1.ValidatorState]uint64

GetValidatorStatusMap returns the validator status map for the validator set at a given block root.

func (*Indexer) IsCanonicalBlock 

func (indexer *Indexer) IsCanonicalBlock(block *Block, overrideForkId *ForkKey) bool

func (*Indexer) IsCanonicalBlockByHead added in v1.14.0 

func (indexer *Indexer) IsCanonicalBlockByHead(block *Block, headBlock *Block) bool

func (*Indexer) SetExecutionTimeProvider added in v1.17.0 

func (indexer *Indexer) SetExecutionTimeProvider(executionTimeProvider ExecutionTimeProvider)

func (*Indexer) StartIndexer 

func (indexer *Indexer) StartIndexer()

StartIndexer starts the indexing process.

func (*Indexer) StopIndexer added in v1.14.0 

func (indexer *Indexer) StopIndexer()

func (*Indexer) StreamActiveBuilderDataForRoot added in v1.21.0 

func (indexer *Indexer) StreamActiveBuilderDataForRoot(blockRoot phase0.Root, activeOnly bool, epoch *phase0.Epoch, cb BuilderSetStreamer) error

StreamActiveBuilderDataForRoot streams the available builder set data for a given blockRoot.

func (*Indexer) StreamActiveValidatorDataForRoot added in v1.14.0 

func (indexer *Indexer) StreamActiveValidatorDataForRoot(blockRoot phase0.Root, activeOnly bool, epoch *phase0.Epoch, cb ValidatorSetStreamer) error

StreamActiveValidatorDataForRoot streams the available validator set data for a given blockRoot.

func (*Indexer) SubscribeBlockEvent added in v1.19.9 

func (indexer *Indexer) SubscribeBlockEvent(capacity int, blocking bool) *utils.Subscription[*Block]

type NoOpExecutionTimeProvider added in v1.17.0 

type NoOpExecutionTimeProvider struct{}

NoOpExecutionTimeProvider is a no-op implementation

func (*NoOpExecutionTimeProvider) GetAndDeleteExecutionTimes added in v1.17.0 

func (n *NoOpExecutionTimeProvider) GetAndDeleteExecutionTimes(blockHash common.Hash) []ExecutionTimeData

type ValidatorActivity added in v1.13.0 

type ValidatorActivity struct {
	VoteBlock *Block // the block where the vote was included
	VoteDelay uint16 // the inclusion delay of the vote in slots
}

ValidatorActivity represents a validator's activity in an epoch. entry size: 18 bytes (10 bytes data + 8 bytes pointer) max. entries per validator: 3-8 (inMemoryEpochs) total memory consumption:

  • 10k active validators: min: 10000 * 18 * 3 = 540kB = 0.54MB max: 10000 * 18 * 8 = 1440kB = 1.44MB
  • 100k active validators: min: 100000 * 18 * 3 = 5400kB = 5.4MB max: 100000 * 18 * 8 = 14400kB = 14.4MB
  • 1M active validators: min: 1000000 * 18 * 3 = 54000kB = 54MB max: 1000000 * 18 * 8 = 144000kB = 144MB

type ValidatorData added in v1.14.0 

type ValidatorData struct {
	ActivationEligibilityEpoch phase0.Epoch
	ActivationEpoch            phase0.Epoch
	ExitEpoch                  phase0.Epoch
	EffectiveBalanceEth        uint32
}

ValidatorData contains the essential validator state information for active validators

func (*ValidatorData) EffectiveBalance added in v1.14.0 

func (v *ValidatorData) EffectiveBalance() phase0.Gwei

EffectiveBalance returns the effective balance of the validator.

type ValidatorSetStreamer added in v1.14.0 

type ValidatorSetStreamer func(index phase0.ValidatorIndex, flags uint16, activeData *ValidatorData, validator *phase0.Validator) error

Source Files

View all Source files

Directories

Path Synopsis
Package statetransition implements consensus-spec state transition functions for Fulu+ beacon states.
 Package statetransition implements consensus-spec state transition functions for Fulu+ beacon states.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.