clconfig

package
v0.0.4 Latest Latest
Warning

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

 Go to latest Published: Jul 30, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package clconfig provides Ethereum Consensus Layer configuration parsing.

This package handles:

  • Parsing CL config files (YAML format)
  • Computing fork digests for different network forks
  • Tracking fork schedules and activation epochs

Index

Constants

View Source 
const DefaultGracePeriod = 60 * time.Minute

DefaultGracePeriod is the default time to keep nodes with old fork digests.

Variables

This section is empty.

Functions

func CompatibilityMode 

func CompatibilityMode(acceptedDigests []ForkDigest) enr.ENRFilter

CompatibilityMode creates a filter that accepts multiple fork digests.

This is useful for networks during fork transitions where you want to be more lenient with peer acceptance.

Example: 

// Accept both Capella and Deneb
filter := CompatibilityMode([]ForkDigest{capellaDigest, denebDigest})

func EncodeETH2Field 

func EncodeETH2Field(currentDigest ForkDigest, nextForkVersion [4]byte, nextForkEpoch uint64) []byte

EncodeETH2Field encodes fork information into an eth2 ENR field.

Format:

  • Bytes 0-3: Current fork digest
  • Bytes 4-7: Next fork version
  • Bytes 8-15: Next fork epoch (big endian)

Types

type BlobScheduleEntry 

type BlobScheduleEntry struct {
	Epoch            uint64 `yaml:"EPOCH"`
	MaxBlobsPerBlock uint64 `yaml:"MAX_BLOBS_PER_BLOCK"`
}

BlobScheduleEntry represents a blob parameter change at a specific epoch.

type Config 

type Config struct {
	// ConfigName is the network name (e.g., "mainnet", "prater")
	ConfigName string `yaml:"CONFIG_NAME"`

	// PresetBase is the preset base (e.g., "mainnet", "minimal")
	PresetBase string `yaml:"PRESET_BASE"`

	// Genesis configuration
	MinGenesisTime     uint64 `yaml:"MIN_GENESIS_TIME"`
	GenesisDelay       uint64 `yaml:"GENESIS_DELAY"`
	GenesisForkVersion string `yaml:"GENESIS_FORK_VERSION"`

	// Blob parameters
	MaxBlobsPerBlockElectra uint64              `yaml:"MAX_BLOBS_PER_BLOCK_ELECTRA"`
	BlobSchedule            []BlobScheduleEntry `yaml:"BLOB_SCHEDULE"`

	// Time parameters
	SecondsPerSlot uint64 `yaml:"SECONDS_PER_SLOT"`
	// contains filtered or unexported fields
}

Config represents an Ethereum consensus layer configuration.

func LoadConfig 

func LoadConfig(path string) (*Config, error)

LoadConfig loads a CL config from a YAML file.

Example: 

config, err := LoadConfig("config.yaml")
if err != nil {
    log.Fatal(err)
}

func (*Config) ForkEpochs added in v0.0.4 

func (c *Config) ForkEpochs() []uint64

ForkEpochs returns every scheduled fork epoch in ascending order, including BPO entries and excluding far-future placeholders.

Distinct from GetAllForkDigestInfos, which deduplicates by digest: the eth2 next-fork tuple changes at a boundary even when the current digest does not, so a caller scheduling work per boundary needs the raw epochs.

func (*Config) GetAllForkDigestInfos 

func (c *Config) GetAllForkDigestInfos() []ForkDigestInfo

GetAllForkDigestInfos returns all wire-valid fork digests with their metadata, on the same boundary enumeration as GetAllForkDigests.

func (*Config) GetAllForkDigests 

func (c *Config) GetAllForkDigests() []ForkDigest

GetAllForkDigests returns every fork digest that can appear on the wire for this config: one per boundary epoch, computed through the same GetForkDigestForEpoch path that produces the live current digest. Digests for same-epoch intermediate forks (never current on the wire) are intentionally not included.

func (*Config) GetBlobParamsForEpoch 

func (c *Config) GetBlobParamsForEpoch(epoch uint64) *BlobScheduleEntry

GetBlobParamsForEpoch returns the blob parameters for a given epoch (Fulu+). Returns nil if not in Fulu fork or no blob schedule applies.

func (*Config) GetCurrentForkDigest 

func (c *Config) GetCurrentForkDigest() ForkDigest

GetCurrentForkDigest returns the fork digest for the current epoch.

Calculates the current epoch based on genesis time and returns the appropriate fork digest.

func (*Config) GetForkDigest 

func (c *Config) GetForkDigest(forkVersion [4]byte, blobParams *BlobScheduleEntry) ForkDigest

GetForkDigest computes a fork digest with optional blob parameters.

For Fulu fork and later, the digest is modified with blob parameters:

  • Compute base digest: sha256(fork_version || genesis_validators_root)[:4]
  • If blobParams provided: digest XOR sha256(epoch || max_blobs_per_block)[:4]

func (*Config) GetForkDigestForEpoch 

func (c *Config) GetForkDigestForEpoch(epoch uint64) ForkDigest

GetForkDigestForEpoch computes the fork digest for a given epoch with BPO support.

func (*Config) GetForkEpoch 

func (c *Config) GetForkEpoch(forkName string) *uint64

GetForkEpoch returns the epoch for a given fork name. Returns nil if the fork is not defined.

func (*Config) GetForkNameAtEpoch 

func (c *Config) GetForkNameAtEpoch(epoch uint64) string

GetForkNameAtEpoch returns the fork name for a given epoch.

func (*Config) GetForkVersion 

func (c *Config) GetForkVersion(forkName string) [4]byte

GetForkVersion returns the fork version bytes for a given fork name. Returns zero bytes if the fork is not defined.

func (*Config) GetForkVersionAtEpoch 

func (c *Config) GetForkVersionAtEpoch(epoch uint64) [4]byte

GetForkVersionAtEpoch returns the fork version for a given epoch.

func (*Config) GetGenesisForkDigest 

func (c *Config) GetGenesisForkDigest() ForkDigest

GetGenesisForkDigest returns the fork digest for the genesis fork (Phase 0).

func (*Config) GetGenesisTime 

func (c *Config) GetGenesisTime() uint64

GetGenesisTime calculates the genesis time from MinGenesisTime and GenesisDelay. Returns 0 if not configured.

func (*Config) GetPreviousForkDigest 

func (c *Config) GetPreviousForkDigest() ForkDigest

GetPreviousForkDigest returns the wire digest that was current before the active boundary, computed on the same enumeration as GetAllForkDigests. Returns the genesis fork digest if there is no previous boundary.

func (*Config) GetPreviousForkName 

func (c *Config) GetPreviousForkName() string

GetPreviousForkName returns the name of the previous fork before the current one.

func (*Config) GetSlotsPerEpoch added in v0.0.3 

func (c *Config) GetSlotsPerEpoch() uint64

GetSlotsPerEpoch returns the slots-per-epoch used for epoch calculations.

func (*Config) SetGenesisTime 

func (c *Config) SetGenesisTime(unixTime uint64) error

SetGenesisTime sets the genesis time from a Unix timestamp.

func (*Config) SetGenesisValidatorsRoot 

func (c *Config) SetGenesisValidatorsRoot(hexRoot string) error

SetGenesisValidatorsRoot sets the genesis validators root from a hex string.

func (*Config) SetSlotsPerEpoch added in v0.0.3 

func (c *Config) SetSlotsPerEpoch(slots uint64) error

SetSlotsPerEpoch overrides slots-per-epoch used for epoch calculations.

type Epoch 

type Epoch uint64

Epoch represents a beacon chain epoch.

func GetCurrentEpoch 

func GetCurrentEpoch(genesisTime, currentTime uint64, secondsPerSlot, slotsPerEpoch uint64) Epoch

GetCurrentEpoch computes the current epoch from a Unix timestamp.

Parameters:

  • genesisTime: Unix timestamp of genesis
  • currentTime: Current Unix timestamp
  • secondsPerSlot: Seconds per slot (default 12)
  • slotsPerEpoch: Slots per epoch (default 32)

type FilterStats 

type FilterStats struct {
	TotalChecks        int
	AcceptedCurrent    int
	AcceptedOld        int
	AcceptedHistorical int
	RejectedInvalid    int
	CurrentDigest      ForkDigest
	OldDigests         int
	LastUpdate         time.Time
}

GetStats returns statistics about the filter.

type ForkData 

type ForkData struct {
	// Current version is the current fork version.
	CurrentVersion [4]byte `ssz-size:"4"`
	// GenesisValidatorsRoot is the hash tree root of the validators at genesis.
	GenesisValidatorsRoot [32]byte `ssz-size:"32"`
}

ForkData provides data about a fork.

type ForkDigest 

type ForkDigest [4]byte

ForkDigest represents a 4-byte fork digest.

func ParseETH2Field 

func ParseETH2Field(eth2Data []byte) (ForkDigest, error)

ParseETH2Field extracts the fork digest from an eth2 ENR field.

The eth2 field format is:

  • Bytes 0-3: Fork digest (this is what we check)
  • Bytes 4+: Next fork version and epoch (we ignore these)

Returns the 4-byte fork digest.

func (ForkDigest) String 

func (fd ForkDigest) String() string

String returns hex representation of fork digest.

type ForkDigestFilter 

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

ForkDigestFilter creates an ENR filter that checks fork digests dynamically.

Features:

  • Accepts nodes with ANY historically valid fork digest from the network
  • Tracks current fork digest for prioritization
  • Tracks old fork digests with grace period for response filtering
  • Only checks the first 4 bytes of the eth2 field (fork digest)
  • Ignores remainder bytes (future fork information)

func NewForkDigestFilter 

func NewForkDigestFilter(config *Config, gracePeriod time.Duration) *ForkDigestFilter

NewForkDigestFilter creates a new dynamic fork digest filter.

Parameters:

  • config: CL configuration for computing fork digests
  • gracePeriod: How long to accept old fork digests (0 = default 60 minutes)

Call Admit from admission paths and Matches from per-packet classification; only Admit moves the stats counters.

func (*ForkDigestFilter) Admit added in v0.0.4 

func (f *ForkDigestFilter) Admit(record *enr.Record) bool

Admit is Matches plus stats: it is the only entry point that moves the counters. Call it from admission paths only, never from layer classification (the same contract as elconfig.ForkFilter.RecordAdmission).

This filter accepts ALL historically valid fork digests: the current digest, old digests within the grace period, and any digest from network history. Nodes with old digests are accepted into the routing table and pinged, which triggers ENR updates.

func (*ForkDigestFilter) ComputeEth2Field 

func (f *ForkDigestFilter) ComputeEth2Field() []byte

ComputeEth2Field computes the eth2 ENR field for the current config.

This is useful when creating your own ENR.

func (*ForkDigestFilter) GetCurrentDigest 

func (f *ForkDigestFilter) GetCurrentDigest() string

GetCurrentDigest returns the current fork digest as a hex string.

func (*ForkDigestFilter) GetCurrentFork 

func (f *ForkDigestFilter) GetCurrentFork() string

GetCurrentFork returns the name of the current fork.

func (*ForkDigestFilter) GetCurrentForkDigest 

func (f *ForkDigestFilter) GetCurrentForkDigest() ForkDigest

GetCurrentForkDigest returns the current fork digest being checked.

func (*ForkDigestFilter) GetForkScoringInfo 

func (f *ForkDigestFilter) GetForkScoringInfo() *ForkScoringInfo

GetForkScoringInfo returns fork digest information for node scoring. This includes current, previous, and genesis fork digests with grace period info.

func (*ForkDigestFilter) GetGenesisForkDigest 

func (f *ForkDigestFilter) GetGenesisForkDigest() string

GetGenesisForkDigest returns the genesis fork digest as a hex string.

func (*ForkDigestFilter) GetGracePeriod 

func (f *ForkDigestFilter) GetGracePeriod() string

GetGracePeriod returns the grace period as a string.

func (*ForkDigestFilter) GetNetworkName 

func (f *ForkDigestFilter) GetNetworkName() string

GetNetworkName returns the network name (e.g., "mainnet", "testnet").

func (*ForkDigestFilter) GetOldDigests 

func (f *ForkDigestFilter) GetOldDigests() map[string]time.Duration

GetOldDigests returns old fork digests with remaining grace time.

func (*ForkDigestFilter) GetOldForkDigests 

func (f *ForkDigestFilter) GetOldForkDigests() map[ForkDigest]time.Duration

GetOldForkDigests returns the old fork digests still in grace period.

func (*ForkDigestFilter) GetPreviousForkDigest 

func (f *ForkDigestFilter) GetPreviousForkDigest() string

GetPreviousForkDigest returns the previous fork digest as a hex string.

func (*ForkDigestFilter) GetPreviousForkName 

func (f *ForkDigestFilter) GetPreviousForkName() string

GetPreviousForkName returns the name of the previous fork.

func (*ForkDigestFilter) GetStats 

func (f *ForkDigestFilter) GetStats() FilterStats

GetStats returns filter statistics.

func (*ForkDigestFilter) Matches added in v0.0.4 

func (f *ForkDigestFilter) Matches(record *enr.Record) bool

Matches reports whether a record's fork digest is acceptable.

It is pure: no counter moves and nothing is logged. Use it for per-packet layer classification, which happens far too often to be a stats signal.

func (*ForkDigestFilter) SetGracePeriod 

func (f *ForkDigestFilter) SetGracePeriod(period time.Duration)

SetGracePeriod updates the grace period for old fork digests.

func (*ForkDigestFilter) SetLogger 

func (f *ForkDigestFilter) SetLogger(logger Logger)

SetLogger sets a logger for debug output.

func (*ForkDigestFilter) Update 

func (f *ForkDigestFilter) Update()

Update updates the fork digest based on the current epoch.

This should be called periodically (e.g., every 5 minutes) to detect fork activations.

When a fork activates:

  • The old fork digest is moved to oldForkDigests with current timestamp
  • The new fork digest becomes the current digest
  • Nodes with the old digest are accepted for the grace period

type ForkDigestInfo 

type ForkDigestInfo struct {
	Digest      ForkDigest
	Name        string
	Epoch       uint64
	BlobParams  *BlobScheduleEntry
	ForkVersion [4]byte
}

ForkDigestInfo contains information about a fork digest.

type ForkScoringInfo 

type ForkScoringInfo struct {
	CurrentForkDigest  ForkDigest
	PreviousForkDigest ForkDigest
	GenesisForkDigest  ForkDigest
	GracePeriodEnd     time.Time
}

ForkScoringInfo contains fork digest information for node scoring.

type Logger 

type Logger interface {
	Debug(args ...interface{})
	Debugf(format string, args ...interface{})
}

Logger interface for debug messages

Source Files

View all Source files

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.