bootnode

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: 26 Imported by: 0

README

Universal Bootnode Package

The bootnode package provides a production-ready, comprehensive Ethereum bootnode implementation supporting both Execution Layer (EL) and Consensus Layer (CL) discovery protocols with intelligent fork-aware filtering.

Overview

This package serves as the main orchestration layer for a universal Ethereum bootnode that can:

  • Serve EL nodes (Ethereum mainnet and testnets)
  • Serve CL nodes (Beacon chain)
  • Serve both simultaneously on the same port (dual-stack mode)
  • Support both Discovery v4 (discv4) and Discovery v5 (discv5) protocols
  • Automatically filter nodes based on fork compatibility
  • Prevent network topology leaks with LAN-aware filtering

Features

Multi-Layer Support
  • Execution Layer (EL): Full support for Ethereum execution layer networks
    • Fork ID validation via eth ENR field (EIP-2124)
    • Accepts any valid historical fork
    • Supports both mainnet and all testnets
  • Consensus Layer (CL): Full support for Ethereum beacon chain
    • Fork digest validation via eth2 ENR field
    • Grace period support for fork transitions (configurable, default 60 minutes)
    • Automatic fork schedule awareness
  • Dual Mode: Run both EL and CL simultaneously
    • Separate routing tables (500 nodes each by default)
    • Independent fork filtering per layer
    • Shared protocols and transport
Multi-Protocol Support
  • Discovery v4 (discv4): Legacy UDP protocol for EL nodes
    • Full wire protocol: PING/PONG, FINDNODE/NEIGHBORS, ENRREQUEST/ENRRESPONSE
    • Bond mechanism with storm prevention
    • Supports ENR and legacy enode URLs
    • EL-only (CL nodes don't use discv4)
  • Discovery v5 (discv5): Modern encrypted protocol
    • Supports both EL and CL nodes
    • Session management with encryption
    • Full wire protocol: PING/PONG, FINDNODE/NODES, TALKREQ/TALKRESP
  • Protocol Multiplexing: Both protocols share a single UDP socket
    • Transport layer routes packets to correct protocol handler
    • Per-IP rate limiting at transport layer
Intelligent Node Routing
  • Layer Separation: Separate routing tables for EL and CL nodes
    • Each table maintains up to 500 active nodes (configurable)
    • Independent quality tracking and statistics
    • Separate database persistence
  • Fork-Aware Filtering:
    • EL: Validates fork IDs against chain config (accepts any valid historical fork)
    • CL: Validates fork digests with grace period support
  • Protocol-Aware Responses:
    • Only returns nodes supporting the requested protocol (v4 or v5)
    • Discv4 requests only receive EL nodes with v4 support
    • Discv5 requests receive both EL and CL nodes with v5 support
  • LAN-Aware Filtering: Prevents leaking private network topology to WAN peers
    • RFC1918 address detection
    • WAN clients don't receive LAN nodes

Architecture

┌────────────────────────────────────────────────────────────────────┐
│                       Universal Bootnode Service                   │
├────────────────────────────────────────────────────────────────────┤
│                                                                    │
│  ┌────────────────────┐              ┌────────────────────┐        │
│  │   EL Routing       │              │   CL Routing       │        │
│  │   Table            │              │   Table            │        │
│  │   - 500 nodes      │              │   - 500 nodes      │        │
│  │   - IP limiting    │              │   - IP limiting    │        │
│  │   - Quality track  │              │   - Quality track  │        │
│  └─────────┬──────────┘              └─────────┬──────────┘        │
│            │                                   │                   │
│  ┌─────────┴──────────┐              ┌─────────┴──────────┐        │
│  │  EL Database       │              │  CL Database       │        │
│  │  (SQLite - layer   │              │  (SQLite - layer   │        │
│  │   'el')            │              │   'cl')            │        │
│  │  - nodes table     │              │  - nodes table     │        │
│  │  - bad_nodes table │              │  - bad_nodes table │        │
│  └────────────────────┘              └────────────────────┘        │
│                                                                    │
│  ┌──────────────────────────────────────────────────────────────┐  │
│  │                    ENR Manager                               │  │
│  │  - Local ENR with 'eth' + 'eth2' fields                      │  │
│  │  - EL Fork ID Computation (EIP-2124)                         │  │
│  │  - CL Fork Digest Computation                                │  │
│  │  - Automatic IP discovery from PONG consensus                │  │
│  │  - Dynamic ENR updates                                       │  │
│  └──────────────────────────────────────────────────────────────┘  │
│                                                                    │
│  ┌──────────────────────────────────────────────────────────────┐  │
│  │                   Maintenance Services                       │  │
│  │  - Lookup Service (random walks, iterative lookups)          │  │
│  │  - Ping Service (aliveness checks, protocol detection)       │  │
│  │  - IP Discovery Service (external IP consensus)              │  │
│  │  - Table Sweep (10% rotation every 5 minutes)                │  │
│  └──────────────────────────────────────────────────────────────┘  │
│                                                                    │
│  ┌──────────────┐                      ┌──────────────┐            │
│  │  Discv4      │                      │  Discv5      │            │
│  │  Service     │                      │  Service     │            │
│  │  - EL only   │                      │  - EL + CL   │            │
│  │  - Bonding   │                      │  - Sessions  │            │
│  │  - Storm     │                      │  - Encrypted │            │
│  │    prevention│                      │    messaging │            │
│  └──────┬───────┘                      └──────┬───────┘            │
│         │                                     │                    │
│         └──────────┬──────────────────────────┘                    │
│                    │                                               │
│         ┌──────────┴─────────────────────────┐                     │
│         │   UDP Transport (Shared)           │                     │
│         │   - Protocol multiplexing          │                     │
│         │   - Per-IP rate limiting (100/s)   │                     │
│         │   - Packet routing (v4/v5)         │                     │
│         │   - Bind: 0.0.0.0:30303            │                     │
│         └────────────────────────────────────┘                     │
└────────────────────────────────────────────────────────────────────┘

Package Structure

bootnode/
├── config.go          # Bootnode configuration
├── service.go         # Main service implementation
├── enr.go             # ENR management with eth/eth2 fields
├── elconfig/          # Execution Layer configuration
│   ├── forkid.go      # EIP-2124 fork ID calculation
│   ├── filter.go      # Fork ID filtering
│   └── parser.go      # Chain config parsing
└── clconfig/          # Consensus Layer configuration
    ├── config.go      # Beacon chain config
    └── filter.go      # Fork digest filtering

Usage

Basic Setup
import (
    "github.com/ethpandaops/bootnodoor/bootnode"
    "github.com/ethpandaops/bootnodoor/bootnode/elconfig"
    "github.com/ethpandaops/bootnodoor/bootnode/clconfig"
)

// Load configurations
elConfig, _ := elconfig.LoadChainConfig("mainnet.json")
clConfig, _ := clconfig.LoadConfig("mainnet-cl.yaml")

// Create bootnode config
config := bootnode.DefaultConfig()
config.PrivateKey = privateKey
config.Database = db
config.BindPort = 30303

// Configure EL support
config.ELConfig = elConfig
config.ELGenesisHash = genesisHash
config.ELGenesisTime = genesisTime
config.ELBootnodes = []string{
    "enode://...",  // enode format
    "enr://...",    // ENR format
}

// Configure CL support
config.CLConfig = clConfig
config.CLBootnodes = []string{
    "enr://...",    // ENR format only
}

// Create and start service
service, err := bootnode.New(config)
if err != nil {
    log.Fatal(err)
}

if err := service.Start(); err != nil {
    log.Fatal(err)
}
defer service.Stop()
EL-Only Bootnode
config := bootnode.DefaultConfig()
config.PrivateKey = privateKey
config.Database = db

// Only set EL config
config.ELConfig = elConfig
config.ELGenesisHash = genesisHash
config.ELGenesisTime = genesisTime

// Protocols: Both discv4 and discv5 enabled by default
config.EnableDiscv4 = true
config.EnableDiscv5 = true

service, _ := bootnode.New(config)
service.Start()
CL-Only Bootnode
config := bootnode.DefaultConfig()
config.PrivateKey = privateKey
config.Database = db

// Only set CL config
config.CLConfig = clConfig

// Discv4 will be disabled (CL nodes don't use discv4)
config.EnableDiscv4 = false
config.EnableDiscv5 = true

service, _ := bootnode.New(config)
service.Start()
Dual EL+CL Bootnode
config := bootnode.DefaultConfig()
config.PrivateKey = privateKey
config.Database = db

// Set both configs
config.ELConfig = elConfig
config.ELGenesisHash = genesisHash
config.ELGenesisTime = genesisTime
config.CLConfig = clConfig

// Both protocols enabled
config.EnableDiscv4 = true  // For EL
config.EnableDiscv5 = true  // For both EL and CL

service, _ := bootnode.New(config)
service.Start()

Configuration Options

Network Configuration
  • BindIP: IP address to bind to (default: 0.0.0.0)
  • BindPort: UDP port to bind to (default: 30303)
  • ENRIP: IPv4 address to advertise in ENR (auto-detected if nil)
  • ENRIP6: IPv6 address to advertise in ENR (optional)
  • ENRPort: UDP port to advertise in ENR (default: same as BindPort)
Layer Configuration
  • ELConfig: Execution layer chain configuration
  • ELGenesisHash: EL genesis block hash
  • ELGenesisTime: EL genesis block timestamp
  • ELBootnodes: List of EL bootnodes (ENR or enode format)
  • CLConfig: Consensus layer beacon chain configuration
  • CLBootnodes: List of CL bootnodes (ENR format only)
Table Configuration
  • MaxActiveNodes: Maximum active nodes per table (default: 500)
  • MaxNodesPerIP: Maximum nodes per IP address (default: 10)
  • PingInterval: How often to ping nodes (default: 30s)
  • MaxNodeAge: Maximum age before removing node (default: 24h)
  • MaxFailures: Maximum consecutive failures (default: 3)
Protocol Configuration
  • EnableDiscv4: Enable Discovery v4 protocol (default: true)
  • EnableDiscv5: Enable Discovery v5 protocol (default: true)
  • SessionLifetime: Discv5 session lifetime (default: 12h)
  • MaxSessions: Maximum discv5 sessions (default: 1024)

How It Works

Node Discovery Flow

  1. Incoming Node: A node initiates contact with the bootnode

    • Discv4: Receives PING packet, validates bond mechanism
    • Discv5: Completes WHOAREYOU handshake, establishes encrypted session

  2. Layer Detection: Bootnode examines the node's ENR fields

    • Checks for eth field → EL node detected
    • Checks for eth2 field → CL node detected
    • Both fields present → Multi-layer node (serves both networks)

  3. Fork Validation:

    • EL nodes: Validates fork ID from eth field against chain config
      • Computes expected fork ID from genesis hash and chain config
      • Accepts any valid historical fork ID
      • No grace period needed
    • CL nodes: Validates fork digest from eth2 field against beacon config
      • Computes current fork digest from current fork version + genesis validators root
      • Accepts current fork digest
      • Accepts previous fork digest within grace period (default: 60 minutes)
      • Accepts but deprioritizes historical fork digests

  4. Bad Node Check: Before accepting, checks bad_nodes table

    • If node was previously rejected, skips ENR request and validation
    • Automatic cleanup of old bad node entries
    • Prevents repeated validation overhead

  5. Table Insertion: Node is added to appropriate table(s)

    • EL nodes → EL routing table + EL database (layer='el')
    • CL nodes → CL routing table + CL database (layer='cl')
    • Multi-layer → Both tables with independent tracking
    • IP limiting enforced (max 10 nodes per IP by default)
    • Quality metrics initialized (success/failure counts, RTT)

  6. FINDNODE Responses: When a node requests peers

    • Discv4 requests: Returns only EL nodes with v4 support
      • Maximum 16 nodes per response (protocol limit)
      • Only nodes that have been pinged successfully
    • Discv5 requests: Returns appropriate nodes based on layer
      • If requester has eth field: returns EL nodes with v5 support
      • If requester has eth2 field: returns CL nodes with v5 support
      • Can return both if requester supports both layers
    • Protocol filtering: Only returns nodes supporting the request protocol
    • LAN filtering: WAN requesters don't receive RFC1918 nodes
    • Quality-based selection: Prioritizes nodes with better success rates
Fork ID Calculation (EL)

The bootnode implements EIP-2124 fork ID calculation:

Fork ID = CRC32(genesis_hash || fork1 || fork2 || ... || forkN)

Example for Mainnet:

Genesis: 0xd4e56740...
Fork 1 (Homestead): Block 1,150,000
Fork 2 (DAO): Block 1,920,000
...
Fork N (Prague): Timestamp 1746612311

Current Fork ID: {Hash: [4]byte{0x...}, Next: 1746612311}
Fork Digest Calculation (CL)

The bootnode implements beacon chain fork digest calculation:

Fork Digest = compute_fork_digest(fork_version, genesis_validators_root)

The bootnode accepts nodes on:

  • Current fork
  • Previous fork (within grace period)
  • Genesis fork (always accepted)

Local ENR Structure

The bootnode's local ENR contains both eth and eth2 fields:

ENR Fields:
- id: "v4"
- secp256k1: <compressed public key>
- ip: <IPv4 address>
- udp: <UDP port>
- eth: <EL fork ID> (12 bytes: 4-byte hash + 8-byte next)
- eth2: <CL fork digest> (16 bytes: 4-byte digest + 8-byte next + 4-byte enr-seq)

This allows the bootnode to serve both EL and CL clients.

Database Schema

The bootnode uses SQLite with WAL mode and automatic schema migrations (goose). The database contains three main tables:

Nodes Table

Stores discovered nodes with quality metrics:

CREATE TABLE nodes (
    nodeid BLOB PRIMARY KEY,        -- Node ID (32 bytes)
    layer TEXT NOT NULL,             -- 'el' or 'cl'
    ip BLOB,                         -- IPv4 address (4 bytes)
    ipv6 BLOB,                       -- IPv6 address (16 bytes, optional)
    port INTEGER,                    -- UDP port
    seq INTEGER,                     -- ENR sequence number
    fork_digest BLOB,                -- Fork ID (EL, 12 bytes) or digest (CL, 4 bytes)
    first_seen INTEGER,              -- Unix timestamp (first discovery)
    last_seen INTEGER,               -- Unix timestamp (last seen)
    last_active INTEGER,             -- Unix timestamp (last successful ping)
    enr BLOB,                        -- Full ENR record
    has_v4 INTEGER DEFAULT 0,        -- Supports Discovery v4
    has_v5 INTEGER DEFAULT 1,        -- Supports Discovery v5
    success_count INTEGER DEFAULT 0, -- Successful ping count
    failure_count INTEGER DEFAULT 0, -- Failed ping count
    avg_rtt INTEGER DEFAULT 0        -- Average round-trip time (ms)
);

CREATE INDEX idx_nodes_layer ON nodes(layer);
CREATE INDEX idx_nodes_last_seen ON nodes(layer, last_seen);
Bad Nodes Table

Optimization table to avoid repeated validation of rejected nodes:

CREATE TABLE bad_nodes (
    nodeid BLOB PRIMARY KEY,    -- Node ID (32 bytes)
    reason TEXT,                -- Rejection reason
    first_rejected INTEGER,     -- Unix timestamp (first rejection)
    last_rejected INTEGER,      -- Unix timestamp (last rejection)
    rejection_count INTEGER     -- Number of times rejected
);

CREATE INDEX idx_bad_nodes_last_rejected ON bad_nodes(last_rejected);
State Table

Stores runtime state and configuration:

CREATE TABLE state (
    key TEXT PRIMARY KEY,       -- State key
    value BLOB                  -- State value (e.g., local ENR)
);
Migration Management

The database uses goose for schema migrations:

  • Migrations in db/migrations/
  • Automatic migration on startup
  • Version tracking in goose_db_version table

Security Considerations

IP Limiting
  • Maximum 10 nodes per IP address by default
  • Prevents sybil attacks from single source
Fork Validation
  • Rejects nodes on incompatible forks
  • Grace period for old fork digests (CL)
  • Strict validation of fork IDs (EL)
LAN Awareness
  • WAN clients don't receive LAN nodes
  • Prevents network topology disclosure
Protocol Validation
  • All packets cryptographically verified
  • Invalid signatures rejected
  • Expired packets rejected

Key Features Summary

Feature Status Description
EL Support ✅ Full Execution Layer support with fork ID validation
CL Support ✅ Full Consensus Layer support with fork digest validation
Discv4 ✅ Full Discovery v4 with bonding and storm prevention
Discv5 ✅ Full Discovery v5 with encryption and sessions
Protocol Multiplexing ✅ Both protocols on same UDP port
Dual Tables ✅ Separate routing tables for EL and CL
Fork ID (EL) ✅ EIP-2124 fork ID validation
Fork Digest (CL) ✅ Fork digest with grace period
ENR with both fields ✅ Single ENR with eth + eth2 fields
Bad Node Caching ✅ Avoid repeated validation of rejected nodes
IP Discovery ✅ Automatic external IP detection from PONG consensus
LAN Filtering ✅ WAN clients don't receive LAN nodes
Quality Metrics ✅ Success/failure tracking, RTT measurement
Protocol Detection ✅ Automatic v4/v5 capability testing
Database Persistence ✅ SQLite with WAL mode and migrations
Web UI ✅ Real-time statistics and node lists

Implementation Status

Fully Implemented
  • ✅ Dual-stack bootnode service (EL + CL)
  • ✅ Fork-aware filtering for both layers
  • ✅ Protocol multiplexing (discv4 + discv5)
  • ✅ Separate routing tables with IP limiting
  • ✅ Bad node caching and optimization
  • ✅ IP discovery service
  • ✅ Lookup service (random walks, iterative lookups)
  • ✅ Ping service (aliveness checks, protocol detection)
  • ✅ ENR management with dynamic updates
  • ✅ Database persistence with migrations
  • ✅ Web UI with EL/CL breakdowns
  • ✅ LAN-aware filtering
Known Limitations
  • Table is flat (not bucket-based Kademlia), which is simpler but less optimal for very large networks
  • No geographic diversity optimization in node selection
  • No advanced node scoring beyond success/failure counts

References

Documentation

Overview

Package bootnode implements a universal Ethereum bootnode supporting both Execution Layer (EL) and Consensus Layer (CL) discovery.

The bootnode supports:

  • Discovery v4 (discv4) for EL nodes
  • Discovery v5 (discv5) for both EL and CL nodes
  • Dual routing tables (separate for EL and CL)
  • Fork-aware filtering
  • Protocol multiplexing (both protocols on same UDP port)

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func StaticHead added in v0.0.4 

func StaticHead() (block, timestamp uint64)

StaticHead returns the head a bootnode evaluates fork schedules at. It tracks no chain, so every block-scheduled fork counts as passed (exact on post-merge networks, which can only schedule forks by time) and the time head is the wall clock.

Types

type Config 

type Config struct {
	// PrivateKey is the node's secp256k1 private key (required)
	PrivateKey *ecdsa.PrivateKey

	// Database is the shared database for both EL and CL nodes (required)
	Database *db.Database

	// BindIP is the IP address to bind to (default: 0.0.0.0)
	BindIP net.IP

	// BindPort is the UDP port to bind to (default: 30303)
	BindPort uint16

	// ENRIP is the IP address to advertise in ENR (optional, auto-detected if nil)
	ENRIP net.IP

	// ENRIP6 is the IPv6 address to advertise in ENR (optional)
	ENRIP6 net.IP

	// ENRIPProvided/ENRIP6Provided record whether the advertised IP was explicitly
	// configured (vs auto-detected). An explicit address is authoritative and
	// overrides a stored ENR on restart; an auto-detected one does not, so a
	// learned/discovered address survives.
	ENRIPProvided  bool
	ENRIP6Provided bool

	// ENRPort is the UDP port to advertise in ENR (default: same as BindPort)
	ENRPort uint16

	// Per-layer overrides for migrating from separate EL and CL bootnodes that
	// have distinct node keys. Any field left zero falls back to the shared
	// value above.
	ELPrivateKey *ecdsa.PrivateKey
	CLPrivateKey *ecdsa.PrivateKey
	ELBindPort   uint16
	CLBindPort   uint16
	ELENRPort    uint16
	CLENRPort    uint16

	// ELConfig is the EL chain configuration (optional, nil disables EL support)
	ELConfig *elconfig.ChainConfig

	// ELGenesisHash is the EL genesis block hash (required if ELConfig is set)
	ELGenesisHash [32]byte

	// ELGenesisTime is the EL genesis block timestamp (required if ELConfig is set)
	ELGenesisTime uint64

	// ELBootnodes is the list of initial EL bootnodes (ENR or enode format)
	ELBootnodes []string

	// CLConfig is the CL beacon chain configuration (optional, nil disables CL support)
	CLConfig *clconfig.Config

	// CLBootnodes is the list of initial CL bootnodes (ENR format only)
	CLBootnodes []string

	// MaxActiveNodes is the maximum active nodes per table (default: 500)
	MaxActiveNodes int

	// MaxNodesPerIP is the maximum nodes allowed per IP address (default: 10)
	MaxNodesPerIP int

	// PingInterval is how often to ping nodes (default: 30s)
	PingInterval time.Duration

	// MaxNodeAge is the maximum age before considering a node dead (default: 24h)
	MaxNodeAge time.Duration

	// MaxFailures is the maximum consecutive failures before removing a node (default: 3)
	MaxFailures int

	// EnableDiscv4 enables Discovery v4 protocol (default: true)
	EnableDiscv4 bool

	// EnableDiscv5 enables Discovery v5 protocol (default: true)
	EnableDiscv5 bool

	// ServeAll disables EL/CL classification and fork-ID/digest filtering. Every
	// discovered node is pooled (into every enabled table) and served to every
	// requester, turning the bootnode into a plain discv5 rendezvous that relays
	// all peers regardless of eth/eth2 fields. Default: false (classify + filter).
	ServeAll bool

	// SessionLifetime is the discv5 session lifetime (default: 12 hours)
	SessionLifetime time.Duration

	// MaxSessions is the maximum number of discv5 sessions (default: 1024)
	MaxSessions int

	// EnableIPDiscovery enables automatic IP discovery from PONG responses
	// (default: true). An explicitly configured ENRIP/ENRIP6 is never overridden
	// by discovery regardless of this setting.
	EnableIPDiscovery bool

	// GracePeriod is the grace period for accepting old fork digests (default: 60 minutes)
	GracePeriod time.Duration

	// Logger is the logger instance (optional)
	Logger logrus.FieldLogger
}

Config contains configuration for the universal bootnode.

func DefaultConfig 

func DefaultConfig() *Config

DefaultConfig returns a configuration with sensible defaults.

You must set at least:

  • PrivateKey
  • Database
  • One of: ELConfig or CLConfig (or both)

func (*Config) ApplyDefaults 

func (c *Config) ApplyDefaults()

ApplyDefaults fills in default values for unset fields.

func (*Config) HasCL 

func (c *Config) HasCL() bool

HasCL returns true if CL support is enabled.

func (*Config) HasEL 

func (c *Config) HasEL() bool

HasEL returns true if EL support is enabled.

func (*Config) Validate 

func (c *Config) Validate() error

Validate checks if the configuration is valid.

type Discv5Stats added in v0.0.4 

type Discv5Stats struct {
	InvalidPackets    int
	FilteredResponses int
	FindNodeReceived  int
	PendingHandshakes int
	PendingChallenges int
}

Discv5Stats is the deliberate subset of protocol.HandlerStats the web UI renders, summed per identity.

type ENRManager 

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

ENRManager handles ENR creation and updates for a single identity.

The fork filters are always built for whatever layers the chain config enables (so any manager can classify a remote node), but the eth/eth2 fields written into this manager's own record are gated by servesEL/servesCL.

func NewENRManager 

func NewENRManager(cfg *Config, key *ecdsa.PrivateKey, localNode *v5node.Node, servesEL, servesCL bool) *ENRManager

NewENRManager creates a new ENR manager for one identity.

func (*ENRManager) AdmitCLNode added in v0.0.4 

func (m *ENRManager) AdmitCLNode(record *enr.Record) bool

AdmitCLNode is ClassifyCLNode plus stats. Call it from admission paths only.

func (*ENRManager) AdmitELNode added in v0.0.4 

func (m *ENRManager) AdmitELNode(record *enr.Record) (bool, elconfig.ForkID)

AdmitELNode is ClassifyELNode plus stats. Call it from admission paths only.

Records with no eth entry are consensus nodes, not wrong-fork execution nodes, and are not counted (see services.AdmissionRejectedLayer).

func (*ENRManager) ClassifyCLNode added in v0.0.4 

func (m *ENRManager) ClassifyCLNode(record *enr.Record) bool

ClassifyCLNode reports whether a record is a consensus node on an accepted fork digest.

It is pure: no counter moves. Use it for per-packet layer classification, and AdmitCLNode when the result decides admission.

func (*ENRManager) ClassifyELNode added in v0.0.4 

func (m *ENRManager) ClassifyELNode(record *enr.Record) (bool, elconfig.ForkID)

ClassifyELNode reports whether a record is an execution node on a compatible fork, along with the fork ID it advertised.

It is pure: no counter moves. Use it for per-packet layer classification, and AdmitELNode when the result decides admission.

func (*ENRManager) GetCLFilter 

func (m *ENRManager) GetCLFilter() *clconfig.ForkDigestFilter

GetCLFilter returns the CL fork digest filter (may be nil).

func (*ENRManager) GetELFilter 

func (m *ENRManager) GetELFilter() *elconfig.ForkFilter

GetELFilter returns the EL fork filter (may be nil).

func (*ENRManager) UpdateENR 

func (m *ENRManager) UpdateENR(currentBlock, currentTime uint64) (bool, error)

UpdateENR updates the local ENR with current eth and eth2 fields, reporting whether the record actually changed.

It is a no-op when the computed fields already match the published record, so periodic callers do not churn the sequence number (peers re-fetch a record on every bump).

This should be called:

  • On startup
  • After fork transitions
  • When head changes significantly (for EL fork ID Next field)

func (*ENRManager) UpdateENRWithIP 

func (m *ENRManager) UpdateENRWithIP(ip net.IP, port uint16) error

UpdateENRWithIP updates the local ENR with a new IPv4 address and UDP port.

func (*ENRManager) UpdateENRWithIP6 

func (m *ENRManager) UpdateENRWithIP6(ip net.IP, port uint16) error

UpdateENRWithIP6 updates the local ENR with a new IPv6 address and UDP port.

type Service 

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

Service is the universal bootnode service.

It provides:

  • Dual protocol support (discv4 + discv5)
  • Dual layer support (EL + CL)
  • Separate routing tables for each layer
  • Fork-aware filtering

func New 

func New(cfg *Config) (*Service, error)

New creates a new universal bootnode service.

Example: 

config := bootnode.DefaultConfig()
config.PrivateKey = privKey
config.Database = db
config.ELConfig = elConfig
config.CLConfig = clConfig

service, err := bootnode.New(config)
if err != nil {
    log.Fatal(err)
}
defer service.Stop()

func (*Service) CLConfig 

func (s *Service) CLConfig() *clconfig.Config

CLConfig returns the CL beacon chain configuration (may be nil if CL disabled).

func (*Service) CLENR added in v0.0.3 

func (s *Service) CLENR() (string, error)

CLENR returns the CL identity's ENR with the EL-only eth field removed. Empty if CL is disabled. See ELENR for the shared- vs separate-key behavior.

func (*Service) CLLocalNode added in v0.0.3 

func (s *Service) CLLocalNode() *v5node.Node

CLLocalNode returns the CL identity's local node (nil if CL disabled).

func (*Service) CLNodeDB 

func (s *Service) CLNodeDB() *nodes.NodeDB

CLNodeDB returns the CL node database (may be nil if CL disabled).

func (*Service) CLTable 

func (s *Service) CLTable() *nodes.FlatTable

CLTable returns the CL routing table (may be nil if CL disabled).

func (*Service) ELConfig 

func (s *Service) ELConfig() *elconfig.ChainConfig

ELConfig returns the EL chain configuration (may be nil if EL disabled).

func (*Service) ELENR added in v0.0.3 

func (s *Service) ELENR() (string, error)

ELENR returns the EL identity's ENR with the CL-only eth2 field removed — the record to hand to EL clients, some of which reject an ENR carrying eth2. In shared-key mode this strips eth2 from the combined record; with separate keys the EL record already omits eth2, so the strip is a no-op. Empty if EL is disabled.

func (*Service) ELLocalNode added in v0.0.3 

func (s *Service) ELLocalNode() *v5node.Node

ELLocalNode returns the EL identity's local node (nil if EL disabled).

func (*Service) ELNodeDB 

func (s *Service) ELNodeDB() *nodes.NodeDB

ELNodeDB returns the EL node database (may be nil if EL disabled).

func (*Service) ELTable 

func (s *Service) ELTable() *nodes.FlatTable

ELTable returns the EL routing table (may be nil if EL disabled).

func (*Service) ENRManager 

func (s *Service) ENRManager() *ENRManager

ENRManager returns the ENR manager.

func (*Service) GenericENR added in v0.0.3 

func (s *Service) GenericENR(node *v5node.Node) (string, error)

GenericENR returns the base64 ENR for the given identity's node with the fork fields (eth/eth2) removed. This is the record to commit to static bootnode lists, which omit fork filtering so the bootnode is accepted regardless of the client's fork state; the bootnode still advertises the full fork-filtered ENR for live discovery.

func (*Service) GetStats added in v0.0.4 

func (s *Service) GetStats() Stats

GetStats returns a snapshot of the service's discovery counters.

func (*Service) HasSeparateIdentities added in v0.0.3 

func (s *Service) HasSeparateIdentities() bool

HasSeparateIdentities reports whether EL and CL run under distinct node IDs.

func (*Service) LocalNode 

func (s *Service) LocalNode() *v5node.Node

LocalNode returns the primary identity's local node.

func (*Service) Start 

func (s *Service) Start() error

Start starts the bootnode service.

func (*Service) StartTime added in v0.0.3 

func (s *Service) StartTime() time.Time

StartTime returns when the service started running.

func (*Service) Stop 

func (s *Service) Stop() error

Stop stops the bootnode service.

type Stats added in v0.0.4 

type Stats struct {
	Lookups  services.LookupStats
	Ping     services.PingStats
	Discv5   Discv5Stats
	Discv4   v4protocol.HandlerStats
	HasV4    bool
	Sessions session.Stats
	Packets  transport.MetricsSnapshot
}

Stats aggregates the live counters the web UI renders. Everything here is summed across both layers (EL and CL lookup services) and across all discovery identities, of which there are two when separate EL and CL keys are configured.

Source Files

View all Source files

Directories

Path Synopsis
Package clconfig provides Ethereum Consensus Layer configuration parsing.
 Package clconfig provides Ethereum Consensus Layer configuration parsing.
Package elconfig implements Execution Layer config parsing and fork ID calculation.
 Package elconfig implements Execution Layer config parsing and fork ID calculation.

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.