Devp2p Peer Discovery

Peer Discovery — Nethereum.DevP2P

Dialing a peer (see devp2p-peer-connect) assumes you already have an enode:// URL. In practice, a node starting cold has none — it needs to find other nodes on the network before it can dial anyone. This skill covers the three discovery mechanisms Nethereum implements — discv4 (the original Kademlia UDP protocol), discv5 (its authenticated successor), and DNS ENR-tree lookup (EIP-1459, for bootstrapping from a small number of well-known DNS names) — plus two supporting pieces every long-running node needs: a stable node identity and a memory of which peers were worth reconnecting to.

Package

dotnet add package Nethereum.DevP2P

You'll want a persisted node identity (below) rather than a throwaway EthECKey.GenerateKey() — discovery is precisely the mechanism by which other nodes learn your enode:// and remember you, so a node-id that changes every restart defeats the point.

Persist your node identity

A stable enode across restarts is what lets a remote peer durably trust your node by node-id — bond once, reconnect for weeks. NodeKeyStore.LoadOrCreate loads a raw 32-byte private key from path, or generates and saves one on first run:

using Nethereum.DevP2P.NodeDb;

// EthECKey LoadOrCreate(string path, Action<string> log = null)
var localKey = NodeKeyStore.LoadOrCreate("nodekey");

Run this once at node startup instead of EthECKey.GenerateKey(). The first run creates nodekey on disk; every subsequent run loads the same key, so your node's identity (and any reputation peers have built for it) survives restarts.

Mental model: three ways to find a node

All three ultimately hand you the same thing: a list of enode (or ENR) addresses to feed into StaticPeerConnector/RlpxConnection (see devp2p-peer-connect). They differ in how much trust and infrastructure they assume up front.

Discover peers with discv5 (the one-line quickstart)

Discv5Discovery.StartMainnet is the fastest way to get a discv5 node walking the network: it builds the listener, signs a local ENR, seeds the mainnet bootnodes, starts the routing-table walk, and hands back both objects — you own teardown of each:

using Nethereum.DevP2P.Discv5;
using Nethereum.Signer;

var localKey = EthECKey.GenerateKey();

var (discovery, listener) = Discv5Discovery.StartMainnet(
    localKey,
    enqueueEnode: enode => Console.WriteLine($"discovered {enode}"));   // feed your dial loop here

// ... on shutdown — the service does NOT dispose the listener it walks:
await discovery.StopAsync();
await listener.DisposeAsync();

Every enode string handed to enqueueEnode is a live candidate — pass it straight into StaticPeerConnector.ConnectAsync, or queue it for your own dial scheduler. Note the two-step shutdown: Discv5Discovery stops the periodic walk, but it doesn't own the listener's socket, so you dispose that separately.

The full signature exposes tuning most callers don't need day one — a custom bind address/port, a logger, and a pre-dial fork-ID filter so you never bother dialing peers on the wrong chain:

(Discv5PeerDiscoveryService Discovery, Discv5Listener Listener) StartMainnet(
    EthECKey localKey,
    Action<string> enqueueEnode,
    IPAddress bindAddress = null,
    int udpPort = 0,
    Action<string> log = null,
    Func<byte[], bool> ethForkIdFilter = null,
    CancellationToken ct = default)

See the underlying protocol: discv4 ping/pong

Discv5Discovery is a convenience wrapper; underneath, discovery is a signed UDP request/response protocol. This is easiest to see with the older discv4 protocol, whose ping/pong bonding is exercised directly by a test — two Discv4Listeners on loopback, each auto-responding to the other's messages:

var keyA = EthECKey.GenerateKey();
var keyB = EthECKey.GenerateKey();

var tableA = new Discv4RoutingTable(keyA.GetPubKeyNoPrefix());
var tableB = new Discv4RoutingTable(keyB.GetPubKeyNoPrefix());

using var nodeA = new Discv4Listener(keyA, tableA);
using var nodeB = new Discv4Listener(keyB, tableB);

nodeA.Start(udpPort: 0, bindAddress: IPAddress.Loopback);
nodeB.Start(udpPort: 0, bindAddress: IPAddress.Loopback);

nodeB.PingReceived += async (_, e) =>
{
    var pong = new Discv4PongMessage
    {
        To = new Discv4Endpoint { IP = e.Sender.Address, UdpPort = (ushort)e.Sender.Port, TcpPort = 0 },
        PingHash = e.PingHash,
        Expiration = DateTimeOffset.UtcNow.AddMinutes(1).ToUnixTimeSeconds()
    };
    await nodeB.SendPongAsync(e.Sender, pong);
};

var ping = new Discv4PingMessage
{
    Version = 4,
    From = new Discv4Endpoint { IP = IPAddress.Loopback, UdpPort = (ushort)nodeA.Port, TcpPort = 30303 },
    To = new Discv4Endpoint { IP = IPAddress.Loopback, UdpPort = (ushort)nodeB.Port, TcpPort = 0 },
    Expiration = DateTimeOffset.UtcNow.AddMinutes(1).ToUnixTimeSeconds()
};
await nodeA.SendPingAsync(new IPEndPoint(IPAddress.Loopback, nodeB.Port), ping);

// After the round trip, both routing tables have learned about each other:
// tableA.Count >= 1 and tableB.Count >= 1

This is the EIP-868 endpoint-proof bonding step: a node only adds a peer to its Kademlia routing table after a successful ping/pong round trip, which is what makes discv4 resistant to naive amplification/spoofing attacks. Discv4Listener has AutoRespond = true by default, so in practice you rarely wire the PingReceived handler yourself — the harvester below does it for you.

The high-level discv4 harvester

For day-to-day use you don't drive ping/pong by hand — PeerDiscoveryService.DiscoverAsync bonds with a list of seed enodes and returns the flat list of enodes it discovered:

Task<List<string>> DiscoverAsync(
    IEnumerable<string> seedEnodes, TimeSpan perSeedTimeout, CancellationToken ct)

Feed it your bootnodes (or a previously-discovered peer list — see the persistent cache below) and it returns candidates ready for StaticPeerConnector.

Note: this signature is verified against src/Nethereum.DevP2P/README.md, but no tagged doc-example test exercises the harvester end-to-end — only the lower-level Discv4Listener ping/pong above is test-backed.