3.1.2.discv4

discv4 is the execution network's signed UDP discovery protocol. It stores secp256k1 node identities in a Kademlia-like table and returns endpoint tuples or ENRs to authenticated requesters. The ENR page owns the record format; this page owns the discv4 packets and table.

Identity and distance

The node ID is the secp256k1 public key that signs the packet. Routing distance is the XOR of the Keccak-256 hashes of two public keys:

distance(a, b) = keccak256(a) XOR keccak256(b)

Every record used by discv4 uses the ENR v4 identity scheme. A node resolves a record by looking up its public key, then sending ENRREQUEST to the node that owns the key.

Packet envelope

Every packet is a UDP datagram no larger than 1280 bytes:

packet  = hash || signature || packet-type || packet-data
hash    = keccak256(signature || packet-type || packet-data)
signature = secp256k1-sign(packet-type || packet-data)

signature is 65 bytes, encoded as r || s || v. packet-type is one byte. packet-data is an RLP list. A receiver ignores extra list elements and bytes after the list. It checks the packet hash and signature before it reads the packet type.

Message inventory

enr-seq lets a peer learn that the sender has a newer record. EIP-868 added ENRREQUEST and ENRRESPONSE and added this optional sequence field to PING and PONG.

Expired packets must not be processed. A PONG is unsolicited when its ping-hash does not match the most recent PING; a receiver ignores it.

Endpoint proof and amplification control

A sender is endpoint-verified after it returns a valid PONG whose ping-hash matches a recent PING. The proof remains valid for 12 hours. NEIGHBORS and ENRRESPONSE are larger replies, so the receiver sends them only after this proof. If no communication has occurred for 12 hours, a node sends a ping before it sends a discovery query that needs a proof.

Routing table

The table has 256 buckets. Bucket i holds nodes with 2^i <= distance < 2^(i+1) and has a maximum of 16 entries. Entries are ordered from least recently seen to most recently seen.

When a full bucket receives a candidate, the node pings the least-recent entry. It removes that entry and adds the candidate only when the entry does not reply. Implementations can keep replacement entries for a full bucket.

Lookup

A lookup starts with alpha closest known nodes, where alpha is local policy and 3 is the usual value. It sends concurrent FINDNODE requests, adds valid results, and continues with closer unqueried nodes. It ends after it has queried and received replies from the 16 closest nodes it has seen. A node that does not reply is removed from the active set until it replies.

Before it sends a NEIGHBORS reply, a node must have verified the FINDNODE sender through the endpoint-proof procedure. The proof covers the querying sender, not the liveness of each node in the response. It limits amplification toward a forged source address.

ENR retrieval and validation

When a PONG reports a newer ENR sequence, the requester sends ENRREQUEST. It checks that the request-hash in ENRRESPONSE equals the full request packet hash. It also checks that the ENR is signed by the public key that signed the response packet. The record then passes the common ENR validation rules before it enters local storage.

Apply these outcomes:

• Reject a packet with a bad hash or signature.
• Ignore an expired packet or a PING with a version other than 4.
• Ignore an unsolicited PONG.
• Do not send NEIGHBORS or ENRRESPONSE without endpoint proof.
• Ignore unknown trailing RLP fields to preserve EIP-8 compatibility.