bootnode

package
v0.0.1 Latest Latest
Warning

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

 Go to latest Published: Nov 2, 2025 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

Package bootnode implements an Ethereum beacon chain bootnode.

This package provides a specialized discv5 bootnode implementation with:

  • Fork digest filtering for Ethereum consensus layer
  • Node database and persistence
  • Routing table management with IP limits
  • Discovery and ping services

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Config 

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

	// BindIP is the IP address to bind to
	BindIP net.IP

	// BindPort is the UDP port to bind to
	BindPort int

	// ENRIP is the IPv4 address to advertise in the ENR (optional, uses BindIP if nil)
	ENRIP net.IP

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

	// ENRPort is the UDP port to advertise in the ENR (0 = use BindPort)
	ENRPort int

	// CLConfig is the consensus layer configuration for fork digest filtering
	CLConfig *config.Config

	// GracePeriod is how long to accept old fork digests (default 60 minutes)
	GracePeriod time.Duration

	// BootNodes are the initial nodes to connect to
	BootNodes []*node.Node

	// NodeDB is the database for storing discovered nodes (required)
	NodeDB *nodedb.NodeDB

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

	// SessionLifetime is how long sessions remain valid (default 12 hours)
	SessionLifetime time.Duration

	// MaxSessions is the maximum number of cached sessions (default 1000)
	MaxSessions int

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

	// MaxNodeAge is the maximum time since last seen (default 24 hours)
	MaxNodeAge time.Duration

	// MaxFailures is the maximum consecutive failures (default 3)
	MaxFailures int

	// EnableIPDiscovery enables automatic IP discovery from PONG responses (default false)
	EnableIPDiscovery bool

	// Logger for debug messages
	Logger logrus.FieldLogger
}

Config contains configuration for the beacon bootnode.

func DefaultConfig 

func DefaultConfig() *Config

DefaultConfig returns a default bootnode configuration.

type HandlerStats 

type HandlerStats struct {
	PacketsReceived   int
	PacketsSent       int
	InvalidPackets    int
	FilteredResponses int
	FindNodeReceived  int
	PendingHandshakes int
	PendingChallenges int
}

HandlerStats contains protocol handler statistics.

type Service 

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

Service is the beacon chain bootnode service.

It wraps the generic discv5 library with beacon chain specific features:

  • Fork digest filtering
  • Node database and persistence
  • Routing table with IP limits
  • Discovery and ping services

func New 

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

New creates a new beacon bootnode service.

Example: 

config := bootnode.DefaultConfig()
config.PrivateKey = privKey
config.CLConfig = clConfig

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

func (*Service) CheckAndAddNode 

func (s *Service) CheckAndAddNode(n *node.Node) bool

CheckAndAddNode performs all admission checks and adds node to table if it passes.

This method handles:

  • Admission filter validation (fork digest)
  • DB existence check for updates
  • IP limit validation
  • Ping-before-add for new nodes when pool is full
  • Adding to routing table if all checks pass

func (*Service) Discv5Service 

func (s *Service) Discv5Service() *discv5.Service

Discv5Service returns the underlying discv5 service.

func (*Service) ForkFilter 

func (s *Service) ForkFilter() *config.ForkDigestFilter

ForkFilter returns the fork digest filter.

func (*Service) GetAcceptedCurrent 

func (s *Service) GetAcceptedCurrent() int

func (*Service) GetAcceptedOld 

func (s *Service) GetAcceptedOld() int

func (*Service) GetActiveNodes 

func (s *Service) GetActiveNodes() []*node.Node

GetActiveNodes returns the active nodes from the routing table. Only active nodes are returned (inactive nodes in DB are not shown).

func (*Service) GetCurrentDigest 

func (s *Service) GetCurrentDigest() string

func (*Service) GetCurrentFork 

func (s *Service) GetCurrentFork() string

func (*Service) GetGracePeriod 

func (s *Service) GetGracePeriod() string

func (*Service) GetNetworkName 

func (s *Service) GetNetworkName() string

func (*Service) GetOldDigests 

func (s *Service) GetOldDigests() map[string]time.Duration

func (*Service) GetRejectedExpired 

func (s *Service) GetRejectedExpired() int

func (*Service) GetRejectedInvalid 

func (s *Service) GetRejectedInvalid() int

func (*Service) GetStats 

func (s *Service) GetStats() ServiceStats

GetStats returns service statistics for display.

func (*Service) GetTotalChecks 

func (s *Service) GetTotalChecks() int

func (*Service) LocalNode 

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

LocalNode returns the local node information.

func (*Service) Lookup 

func (s *Service) Lookup(ctx context.Context, target node.ID) ([]*node.Node, error)

Lookup performs a node lookup for the target ID.

func (*Service) LookupWithFilter 

func (s *Service) LookupWithFilter(ctx context.Context, target node.ID, k int, filter enr.ENRFilter) ([]*node.Node, error)

LookupWithFilter performs a lookup with an ENR filter.

func (*Service) NodeDB 

func (s *Service) NodeDB() *nodedb.NodeDB

NodeDB returns the node database.

func (*Service) Ping 

func (s *Service) Ping(n *node.Node) (bool, time.Duration, error)

Ping sends a PING to a node and waits for PONG.

func (*Service) PingMultiple 

func (s *Service) PingMultiple(nodes []*node.Node) map[node.ID]bool

PingMultiple sends PINGs to multiple nodes in parallel.

func (*Service) RandomWalk 

func (s *Service) RandomWalk(ctx context.Context) ([]*node.Node, error)

RandomWalk performs a random walk to discover new nodes.

func (*Service) Start 

func (s *Service) Start() error

Start starts the bootnode service.

This starts all background tasks:

  • Discv5 protocol handler
  • Fork digest periodic updates
  • Node discovery and maintenance

func (*Service) Stop 

func (s *Service) Stop() error

Stop stops the bootnode service.

This gracefully shuts down all components by cancelling the context. Background tasks are context-aware and will exit promptly.

func (*Service) Table 

func (s *Service) Table() *table.FlatTable

Table returns the routing table.

type ServiceStats 

type ServiceStats struct {
	PeerID        string
	BindAddress   string
	Uptime        time.Duration
	TableSize     int
	BucketsFilled int // Deprecated for FlatTable
	ActiveNodes   int
	InactiveNodes int
	TableStats    table.TableStats
	LookupStats   discover.LookupStats
	PingStats     discover.PingStats
	SessionStats  SessionStats
	HandlerStats  HandlerStats
	ForkFilter    *config.ForkFilterStats
	NodeDBStats   nodedb.NodeDBStats
}

ServiceStats contains statistics about the bootnode service.

type SessionStats 

type SessionStats struct {
	Total   int
	Active  int
	Expired int
}

SessionStats contains session-related statistics.

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 discover implements node discovery operations for discv5.
 Package discover implements node discovery operations for discv5.

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.