Purpose and Scope
This page explains the peer discovery mechanisms used in the P2P networking layer of StableNet.Peer discovery is the process by which a node identifies other nodes in the network and obtains candidates for connection, which are then passed to the P2P server’s connection management logic.
This document covers the Discovery v4 and Discovery v5 protocols, Ethereum Node Records (ENR), bootstrap nodes, and DNS-based discovery. For connection management after discovery, see P2P Server and Peer Management.
For data exchange and synchronization with discovered peers, see Chain Synchronization.
Discovery Architecture Overview
StableNet does not rely on a single method, but instead uses multiple discovery mechanisms in parallel to build a pool of peer candidates. Discovery mechanisms:- Discovery V4: Basic peer discovery using a Kademlia-based DHT
- Discovery V5: An extended protocol with topic advertisements and enhanced cryptography
- DNS Discovery: Tree-based discovery using DNS TXT records
- Bootstrap Nodes: Static seed nodes for initial connectivity
- Protocol-specific sources: Custom iterators provided by specific protocols
enode.FairMix fairly mixes node candidates collected from multiple discovery sources.It iterates over each source in a round-robin manner to prevent any single source from monopolizing the candidate pool, and applies per-source timeouts.
Discovery V4 Protocol
Discovery V4 is a UDP-based Kademlia DHT protocol that maintains a routing table using an XOR distance metric.Nodes explore the network by issuing iterative queries to discover arbitrary peers.
V4 Protocol Operations
| Operation | Packet Type | Purpose |
|---|---|---|
| PING | 0x01 | Check node liveness and exchange endpoints |
| PONG | 0x02 | Respond to PING and confirm endpoint |
| FINDNODE | 0x03 | Request nodes close to a target ID |
| NEIGHBORS | 0x04 | Return up to 16 node records |
| ENRREQUEST | 0x05 | Request the latest ENR (EIP-868) |
| ENRRESPONSE | 0x06 | Respond with an ENR |
V4 Configuration and Setup
The Discovery V4 service is configured viap2p.Config and started during the server initialization phase in setupDiscovery().
Initialization process:
- Create a UDP socket
- Build a
discover.Configincluding the private key, network restrictions, and bootstrap nodes - Call
discover.ListenV4()to start the V4 service - Register the
ntab.RandomNodes()iterator with the discovery mixer
Discovery V5 Protocol
Discovery V5 is an extension of V4 that provides topic-based discovery and stronger cryptography.It supports both random node discovery and searching for peers interested in specific topics.
V5 Enhancements
- Topic advertisements: Nodes can advertise and search for interest-based topics
- Session keys: Reduced handshake cost for repeated communication
- ENR updates: More efficient ENR refresh mechanisms
- Improved NAT handling: Better external endpoint estimation
- Packet encryption: Authenticated encryption applied to all packets
V5 Configuration
Discovery V5 uses a separate list of bootstrap nodes and can be enabled alongside V4. Shared UDP socket: When V4 and V5 are both enabled, they share the same UDP port.Packets not handled by V4 are forwarded to V5, preventing conflicts.
Ethereum Node Records (ENR)
ENR is a signed data structure that contains a node’s identity and connectivity information.Both Discovery V4 and V5 use ENRs to exchange node metadata.
ENR Structure
Core fields:- Node ID: Identifier derived from the public key
- Sequence Number: Incremented on each ENR update
- Signature: Verifies record ownership
- Key-Value Pairs: Extensible set of attributes
| Key | Type | Description |
|---|---|---|
id | string | Identity scheme (usually v4) |
secp256k1 | bytes | Compressed public key |
ip | bytes | IPv4 address |
ip6 | bytes | IPv6 address |
tcp | uint16 | RLPx TCP port |
udp | uint16 | UDP discovery port |
eth | [chainID, forkHash, forkNext] | Chain information |
enode.LocalNode manages the local node’s ENR and automatically updates it when network conditions change.
Bootstrap Nodes
Bootstrap nodes are seed nodes used to initiate peer discovery when joining the network.They provide the first entry point when a local node has no knowledge of other peers.
Bootstrap Configuration
- Static specification via configuration files
- Specification via command-line flags
--bootnodesfor V4 bootstrap nodes--bootnodesv5for V5 bootstrap nodes
- Publicly reachable endpoints
- High availability
- Typically operated by the network maintainers
DNS Discovery
DNS Discovery distributes ENR information encoded in DNS TXT records.This allows bootstrap lists to be updated dynamically without changing node software.
DNS Discovery Tree Structure
DNS-based discovery is organized as a Merkle tree.| Record Type | Description |
|---|---|
| Root | Tree entry point and signature information |
| Branch | Links to child nodes |
| ENR | Actual node records |
| Link | References to external trees |
Integration with the P2P Server
All discovery mechanisms are initialized insetupDiscovery() and integrated via enode.FairMix.Discovered node candidates are forwarded to the dial scheduler, which attempts actual connections.
Fair Mixing Algorithm
FairMix follows these rules:
- Iterate over active sources in round-robin order
- Apply a maximum wait time per source
- Skip unresponsive sources and move to the next
- Periodically retry failed sources
Discovery Metrics
The discovery subsystem maintains the following state:- Discovery V4 routing table
- Discovery V5 service state
- Discovery mixer state
- Local ENR
- Persistent node database
Summary
StableNet’s peer discovery system is designed as a multi-layered architecture resilient to network changes.- Discovery V4 provides stable, DHT-based random discovery
- Discovery V5 adds topic-based search and enhanced security
- ENR enables extensible, signed node information exchange
- Bootstrap Nodes provide initial network entry points
- DNS Discovery enables dynamic and flexible bootstrapping
FairMix to continuously supply a balanced set of peer candidates to the dial scheduler.