Discovery
Chapter 24: Node Discovery Protocols
Section titled “Chapter 24: Node Discovery Protocols”Overview
Section titled “Overview”Discovery protocols are essential for blockchain P2P networks as they enable nodes to find and connect to each other without needing pre-configured addresses. This chapter provides comprehensive coverage of how blockchain nodes discover peers, including Ethereum’s DiscV5, DNS discovery, and bootnode infrastructure.
24.1 Discovery Methods Overview
Section titled “24.1 Discovery Methods Overview”┌─────────────────────────────────────────────────────────────────────────────┐│ DISCOVERY PROTOCOLS │├─────────────────────────────────────────────────────────────────────────────┤│ ││ ┌─────────────────────────────────────────────────────────────────┐ ││ │ DISCV5 (Discovery V5) │ ││ │ │ ││ │ • Current Ethereum discovery protocol │ ││ │ • Kademlia-based DHT │ ││ │ • Supports topic advertisement │ ││ │ • ENR-based node records │ ││ └─────────────────────────────────────────────────────────────────┘ ││ │ ││ ▼ ││ ┌─────────────────────────────────────────────────────────────────┐ ││ │ DNS DISCOVERY │ ││ │ │ ││ │ • Domain name-based node lists │ ││ │ • Used by many blockchain networks │ ││ │ • Reliable and easy to maintain │ ││ └─────────────────────────────────────────────────────────────────┘ ││ │ ││ ▼ ││ ┌─────────────────────────────────────────────────────────────────┐ ││ │ BOOTNODES │ ││ │ │ ││ │ • Pre-configured trusted nodes │ ││ │ • Entry point for new nodes │ ││ │ • Fallback when DHT fails │ ││ └─────────────────────────────────────────────────────────────────┘ ││ │└─────────────────────────────────────────────────────────────────────────────┘Comparison of Discovery Methods
Section titled “Comparison of Discovery Methods”| Method | Type | Complexity | Reliability | Use Case |
|---|---|---|---|---|
| DiscV5 | DHT | High | High | Ethereum mainnet |
| DNS Discovery | Static | Low | Very High | All networks |
| Bootnodes | Static | Low | High | All networks |
| Static Peers | Manual | Very Low | Medium | Private networks |
24.2 DiscV5 Deep Dive
Section titled “24.2 DiscV5 Deep Dive”How DiscV5 Works
Section titled “How DiscV5 Works”┌─────────────────────────────────────────────────────────────────┐│ DISCV5 KADEMLIA DHT │├─────────────────────────────────────────────────────────────────┤│ ││ Each node has a unique node ID (256-bit random number) ││ ││ ┌─────────────────────────────────────────────────────────┐ ││ │ KADEMLIA TABLE (k-buckets) │ ││ │ │ ││ │ Bucket 0: Nodes with very similar ID (distance 0-1) │ ││ │ Bucket 1: Nodes with distance 1-2 │ ││ │ Bucket 2: Nodes with distance 2-4 │ ││ │ ... │ ││ │ Bucket 255: Nodes with very different ID │ ││ │ │ ││ │ Each bucket holds up to k=16 nodes │ ││ └─────────────────────────────────────────────────────────┘ ││ ││ FIND NODE Request: ││ ┌─────────────────────────────────────────────────────────┐ ││ │ 1. Calculate distance between my ID and target ID │ ││ │ 2. Query closest nodes in relevant buckets │ ││ │ 3. Repeat with closer nodes until can't find closer │ ││ │ 4. Return k closest nodes found │ ││ └─────────────────────────────────────────────────────────┘ ││ │└─────────────────────────────────────────────────────────────────┘Enabling DiscV5
Section titled “Enabling DiscV5”# DiscV5 in geth is enabled with --v5disc (single flag; there are no# --discv5.listenaddr / --discv5.discoverylimit / --discv5.netrestrict flags)geth \ --mainnet \ --v5disc \ --discovery.dns "enrtree://AKA3AM6LPBYEUDMVNU3BSVQJ5AD45Y7TDOHJ6WW2IRKABVWQXYZRS@nodes.ethereum.org"
# Check discovery status via RPC# eth.nodeInfo returns the ENR; admin.peers shows connected peers
# Lighthouse (Ethereum consensus client) — real flags:lighthouse beacon_node \ --network mainnet \ --discovery-port 9000 \ --enr-address 203.0.113.10 \ --enr-udp-port 9000 \ --enr-tcp-port 9000 \ --disable-upnpENR (Ethereum Node Record)
Section titled “ENR (Ethereum Node Record)”┌─────────────────────────────────────────────────────────────────┐│ ENR STRUCTURE │├─────────────────────────────────────────────────────────────────┤│ ││ ENR is a signed, self-certifying record containing: ││ ││ ┌─────────────────────────────────────────────────────────┐ ││ │ REQUIRED FIELDS: │ ││ │ ─────────────────── │ ││ │ - seq: Sequence number (incremented on each update) │ ││ │ - id: Protocol identifier (e.g., "v4") │ ││ │ - secp256k1: Compressed public key │ ││ │ - ip: IPv4 address │ ││ │ - tcp: TCP port (optional) │ ││ │ - udp: UDP port (optional) │ ││ └─────────────────────────────────────────────────────────┘ ││ ││ ┌─────────────────────────────────────────────────────────┐ ││ │ COMMON OPTIONAL FIELDS: │ ││ │ ──────────────────────── │ ││ │ - ip6: IPv6 address │ ││ │ - tcp6: IPv6 TCP port │ ││ │ - udp6: IPv6 UDP port │ ││ │ - eth: Ethereum chain data │ ││ │ - chainId: Chain identifier │ ││ │ - network: Network ID │ ││ │ - genesis: Genesis hash │ ││ │ - forkId: Current fork identifier │ ││ │ - attnets: Attestation subnet bits │ ││ └─────────────────────────────────────────────────────────┘ ││ ││ Example ENR: ││ ━━━━━━━━━━━━ ││ enr:-KG4QOtcL...@bootnode.mainnet.ethdisco.net:30303 ││ │└─────────────────────────────────────────────────────────────────┘24.3 DNS Discovery
Section titled “24.3 DNS Discovery”How DNS Discovery Works
Section titled “How DNS Discovery Works”┌─────────────────────────────────────────────────────────────────┐│ DNS DISCOVERY WORKFLOW │├─────────────────────────────────────────────────────────────────┤│ ││ ┌──────────┐ ┌──────────┐│ │ New │ │ DNS ││ │ Node │ │ Server ││ └────┬─────┘ └────┬─────┘│ │ ││ │ 1. Query DNS for ethereum nodes ││ │─────────────────────────────────────────────────────▶││ │ ││ │ 2. Return list of ENR records ││ │◀────────────────────────────────────────────────────││ │ ││ │ 3. Connect to discovered nodes ││ │─────────────────────────────────────────────────────▶││ │ ││ DNS Records: ││ ┌─────────────────────────────────────────────────────────┐ ││ │ nodes.ethereum.org IN TXT "enr:-I..@1.2.3.4:30303" │ ││ │ nodes.ethereum.org IN TXT "enr:-I..@5.6.7.8:30303" │ ││ └─────────────────────────────────────────────────────────┘ ││ │└─────────────────────────────────────────────────────────────────┘DNS Discovery Implementation
Section titled “DNS Discovery Implementation”DNS discovery uses an enrtree — a DNS tree of ENR records rooted at a URL like enrtree://<pubkey>@nodes.ethereum.org. Geth’s flag is --discovery.dns (there is no --dns.anchors or --discovery.dnsseg flag):
# Geth with DNS discovery (mainnet tree — the official enrtree URL)geth \ --mainnet \ --discovery.dns "enrtree://AKA3AM6LPBYEUDMVNU3BSVQJ5AD45Y7TDOHJ6WW2IRKABVWQXYZRS@nodes.ethereum.org"
# Multiple trees (comma-separated)geth \ --mainnet \ --discovery.dns "enrtree://...@nodes.ethereum.org,enrtree://...@all.mainnet.ethdisco.net"DNS Record Format
Section titled “DNS Record Format”# TXT record format for the root — points to subdomains (one per link tree)nodes.example.com IN TXT "enrtree-root:v1 e=<root-b64> l=<link-b64> seq=<n> sig=<sig-b64>"
# Deeper TXT records hold the actual ENR values:nodes.example.com IN TXT "enr:-KG4QOtcL..."Running your own DNS discovery tree requires the
devp2pCLI tool (devp2p dns to-cloudflare/devp2p dns sync) — see the Ethereum DevP2P docs.
24.4 Bootnodes
Section titled “24.4 Bootnodes”Purpose and Function
Section titled “Purpose and Function”┌─────────────────────────────────────────────────────────────────┐│ BOOTNODE ARCHITECTURE │├─────────────────────────────────────────────────────────────────┤│ ││ Bootnodes serve as entry points to the P2P network: ││ ││ ┌─────────────────────────────────────────────────────────┐ ││ │ NEW NODE │ ││ │ (has no peers) │ ││ └────────────────────────┬────────────────────────────────┘ ││ │ ││ ▼ ││ ┌─────────────────────────────────────────────────────────┐ ││ │ BOOTNODE │ ││ │ (well-known, always online) │ ││ │ │ ││ │ Mainnet Bootnodes: │ ││ │ ┌────────────────────────────────────────────────┐ │ ││ │ │ enr:-KG4QO...@bootnode1.ethdisco.net:30303 │ │ ││ │ │ enr:-L4sU...@bootnode2.ethdisco.net:30303 │ │ ││ │ │ enr:-LK4UC...@bootnode3.ethdisco.net:30303 │ │ ││ │ └────────────────────────────────────────────────┘ │ ││ └────────────────────────┬────────────────────────────────┘ ││ │ ││ ▼ ││ ┌─────────────────────────────────────────────────────────┐ ││ │ FULL P2P NETWORK │ ││ │ │ ││ │ New node now has peers and can continue discovering │ ││ │ more peers through the network │ ││ └─────────────────────────────────────────────────────────┘ ││ │└─────────────────────────────────────────────────────────────────┘Using Bootnodes
Section titled “Using Bootnodes”# Default bootnodes (built into client)geth --mainnet
# Custom bootnodesgeth \ --mainnet \ --bootnodes "enr:-KG4QO...@1.2.3.4:30303,enr:-LK4UC...@5.6.7.8:30303"
# Bootnodes for different networks# Goerligeth --goerli --bootnodes "enr:-K64Q..."
# Sepoliageth --sepolia --bootnodes "enr:-MS4L..."
# Run your own bootnodebootnode \ --nodekey /path/to/nodekey \ --addr 0.0.0.0:30303 \ --writeaddress # Print ENR to usePublic Bootnode Lists
Section titled “Public Bootnode Lists”| Network | DNS Discovery | ENR List |
|---|---|---|
| Ethereum Mainnet | nodes.ethereum.org | ethdisco.net |
| Goerli | nodes.goerli.ethdevops.io | - |
| Sepolia | nodes.sepolia.ethdevops.io | - |
24.5 Peer Discovery Best Practices
Section titled “24.5 Peer Discovery Best Practices”Troubleshooting Discovery Issues
Section titled “Troubleshooting Discovery Issues”# Check if node is discoverablegeth attach http://localhost:8545# Then run:admin.nodeInfo.enr
# Check connected peers (net.peerCount — eth.peerCount does not exist)net.peerCount
# Check discovery service logsjournalctl -u geth | grep -i discv5journalctl -u geth | grep -i discovery
# Test DNS resolutiondig nodes.ethereum.orgnslookup bootnode.mainnet.ethdisco.netCommon Issues and Solutions
Section titled “Common Issues and Solutions”| Issue | Cause | Solution |
|---|---|---|
| No peers found | Discovery disabled | Enable --v5disc or --discovery.dns |
| Firewall blocking | UDP blocked | Allow UDP 30303 |
| Wrong network | Using testnet bootnodes on mainnet | Use correct bootnode list |
| NAT issue | Port not forwarded | Configure port forwarding |
24.6 Interview Questions
Section titled “24.6 Interview Questions”| Question | Answer |
|---|---|
| What is DiscV5? | Ethereum’s Kademlia-based discovery protocol |
| What is an ENR? | Ethereum Node Record - self-certifying node metadata |
| How do bootnodes work? | Pre-configured nodes that new nodes connect to initially |
| What is DNS discovery? | Using DNS TXT records to find node ENR addresses |
| Why is peer discovery important? | Enables decentralized network without central servers |
Summary
Section titled “Summary”- DiscV5 is the primary Ethereum discovery protocol
- DNS discovery provides reliable fallback
- Bootnodes are essential for network entry
- ENR contains all node metadata
- Proper configuration ensures good network connectivity
Next Chapter
Section titled “Next Chapter”In Chapter 25: Network Ports & Firewall Configuration, we’ll explore port configuration and security.
Last Updated: 2026-02-20