Skip to main content
netspecsEthereum networking

3.1.5.Consensus discovery

Stage
Current
Version
Sources
4 pinned sources

discv5 runs on UDP and returns signed Ethereum Node Records. The consensus client adapts those records to libp2p service discovery and peer routing. The shared discv5 page owns UDP sessions, routing, and lookup. This page owns consensus compatibility and peer selection.

Candidate to peer

A client performs these steps:

  1. Start discv5 lookups from configured bootnodes and live peers.
  2. Verify the ENR signature, sequence number, identity key, and addresses.
  3. Check eth2 against the local fork schedule.
  4. Prefer candidates whose attnets serves a needed duty.
  5. Convert the ENR's TCP or QUIC address to a libp2p multiaddr and dial it.
  6. Complete the libp2p secure-channel and protocol handshake, then request metadata and observe peer behavior.

The client also checks syncnets and prefers a candidate that serves a needed sync-committee duty.

The client checks nfd against the local fork schedule and can use the advertised custody count when it selects data-column peers.

A valid ENR is only a candidate. The handshake proves the Peer ID and selects the transport and application protocols. Discovery failure does not imply a libp2p failure.

Fork and status checks

The client prefers a complete ENRForkID match. It may connect when the current digest matches but the next-fork fields differ. The peers remain usable until the earlier advertised boundary.

An nfd mismatch cannot cause a disconnect before the advertised boundary and may cause one at or after it.

After connection, the client sends status and compares the peer's fork digest and finalized checkpoint. A digest mismatch or an irreconcilable finalized checkpoint is a chain incompatibility, not a stale discovery hint.

Subnet and custody selection

For an attestation duty, the client first filters ENRs by the corresponding bit in attnets. It then asks for metadata and keeps the peer only as a useful candidate when the bit remains set. The advertisement does not force the peer to accept every message.

For a sync-committee duty, the client also filters syncnets and checks that the bit remains set in metadata.

A Fulu node can use cgc and metadata custody_group_count to choose peers that should hold required data columns. The count is not proof of a particular group. The client derives the expected groups from the peer ID, checks the metadata minimum, and confirms the claim with sample requests. See [custody] (/data-availability/custody) for the derivation and serving window.

Record refresh

The node increments the ENR sequence number when a fork boundary, next-fork field, or persistent subnet bit changes. Metadata increments its own seq_number when a metadata field changes. The two counters are independent. A stale ENR is refreshed through discv5 before the client applies a behavior penalty.

The node also increments the ENR sequence number when its custody count changes.

Failure handling

Ignore invalid signatures, stale sequence numbers, unsupported addresses, and records with malformed consensus fields. Do not infer compatibility from a valid ENR alone or punish a peer for a discovery hint that metadata disproves. Apply peer scoring only after the connected peer fails a validated request or gossip check. Keep retry and disconnect decisions local to the connection manager.

Scope and status

This page defines the discv5-to-libp2p adapter, fork checks, subnet selection, and custody-aware peer selection. Unscheduled custody behavior remains a data-availability concern, not a current deployment claim.