clconfig

package
v0.0.2 Latest Latest
Warning

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

 Go to latest Published: Dec 9, 2025 License: MIT Imports: 13 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) GetAllForkDigestInfos 

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

GetAllForkDigestInfos returns all fork digests with their metadata.

func (*Config) GetAllForkDigests 

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

GetAllForkDigests returns all possible fork digests for this config.

This is useful for creating filters that accept nodes from multiple forks. Note: For Fulu+ forks with blob schedules, this returns multiple digests per fork.

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 fork digest for the previous fork before the current one. Returns the genesis fork digest if there is no previous fork.

func (*Config) GetPreviousForkName 

func (c *Config) GetPreviousForkName() string

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

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.

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
	RejectedExpired    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)

Example: 

config, _ := LoadConfig("config.yaml")
filter := NewForkDigestFilter(config, 60*time.Minute)

// Use as admission filter
service, _ := discv5.New(&discv5.Config{
    AdmissionFilter: filter.Filter(),
})

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) Filter 

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

Filter returns an ENR admission filter function.

This filter accepts ALL historically valid fork digests:

  • Current fork digest
  • Old fork digests (within grace period)
  • Any historically valid fork digest from the network

Nodes with old digests are accepted into the routing table and will be pinged, which triggers ENR updates. Use ResponseFilter() to exclude them from FINDNODE responses.

Example: 

filter := NewForkDigestFilter(config, 60*time.Minute)
service, _ := discv5.New(&discv5.Config{
    AdmissionFilter: filter.Filter(),
    ResponseFilter: filter.ResponseFilter(),
})

func (*ForkDigestFilter) GetAcceptedCurrent 

func (f *ForkDigestFilter) GetAcceptedCurrent() int

GetAcceptedCurrent returns the count of nodes accepted with current fork digest.

func (*ForkDigestFilter) GetAcceptedOld 

func (f *ForkDigestFilter) GetAcceptedOld() int

GetAcceptedOld returns the count of nodes accepted with old fork digests.

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) GetRejectedExpired 

func (f *ForkDigestFilter) GetRejectedExpired() int

GetRejectedExpired returns the count of nodes rejected due to expired grace period.

func (*ForkDigestFilter) GetRejectedInvalid 

func (f *ForkDigestFilter) GetRejectedInvalid() int

GetRejectedInvalid returns the count of nodes rejected due to invalid fork digest.

func (*ForkDigestFilter) GetStats 

func (f *ForkDigestFilter) GetStats() FilterStats

GetStats returns filter statistics.

func (*ForkDigestFilter) GetTotalChecks 

func (f *ForkDigestFilter) GetTotalChecks() int

GetTotalChecks returns the total number of filter checks performed.

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) StartPeriodicUpdate 

func (f *ForkDigestFilter) StartPeriodicUpdate(interval time.Duration, stopCh <-chan struct{})

StartPeriodicUpdate starts a background goroutine that periodically updates the fork digest.

Parameters:

  • interval: How often to check for fork activations (e.g., 5 minutes)
  • stopCh: Channel to signal shutdown

Example: 

stopCh := make(chan struct{})
filter.StartPeriodicUpdate(5*time.Minute, genesisTime, stopCh)

// Later, to stop:
close(stopCh)

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 ForkFilterStats 

type ForkFilterStats struct {
	NetworkName     string
	CurrentFork     string
	CurrentDigest   string
	PreviousFork    string
	PreviousDigest  string
	GenesisDigest   string
	GracePeriod     string
	OldDigests      map[string]time.Duration
	AcceptedCurrent int
	AcceptedOld     int
	RejectedInvalid int
	RejectedExpired int
	TotalChecks     int
}

ForkFilterStats contains statistics about fork digest filtering.

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.