feat(discv5)!: prefer IPv4 for dual-stack ENRs and fail requests on send error

[MysticRyuujin]

Motivation

A node that binds both 0.0.0.0 and :: contacts every dual-stack ENR over IPv6 and never falls back. getSocketAddressMultiaddrOnENR prefers udp6 whenever ipMode.ip6 is set, the chosen address is frozen into the NodeContact, and transport/udp.ts calls socket.send without a callback, so a failed send is never observed. With requestRetries: 1 the request dies on the 1 s timeout with zero retransmits.

In a Docker container without an IPv6 route this means zero peers forever once the bootnode list has no IPv4-only entry. Lodestar v1.48.0 hit exactly this on sepolia and hoodi after the built-in bootnodes moved to a dual-stack fleet (ChainSafe/lodestar#10104 is the caller-side mitigation). Fresh nodes sent no discv5 packets at all; the same image with an IPv4-only bind discovered peers at once.

A second defect surfaced while tracing this: verifyEnr joins the family comparisons with ??, so for a dual-stack ENR observed over IPv6 the IPv4 comparison returns false and the IPv6 endpoint is never checked. With the default allowUnverifiedSessions: false the session is dropped. Dual-stack peers that reach a dual-stack node over IPv6 are rejected today.

Description

• Dual-stack ENRs are contacted over IPv4 first. The order is configurable through the new optional ISessionConfig.dualStackPreferredFamily (4 | 6, default 4). IPMode stays a pure capability. This matches go-ethereum, which prefers IPv4 on a tie for dual-stack records.
• UDPTransportService.send resolves or rejects through the socket.send callback. dgram reports send errors only that way. A rejected request send fails the request at once with the new RequestErrorType.SendFailed, guarded against late callbacks for a request that was already answered or replaced. Response and challenge sends keep the log-only path.
• Discv5 remembers the socket address each node last sent an authenticated message from (confirmedAddrs, written on decrypted requests and verified responses only, bounded like the session cache, cleared on Disconnected and stop). Later requests to that node reuse it through contactFor, so a peer that dialed us over IPv6 keeps getting IPv6 and IPv6 address votes keep flowing under the IPv4-first default. An outgoing handshake never writes the cache: it proves nothing about the address until something comes back. createNodeContactAt builds an Enr contact at a given bare address; a Raw contact would trigger the internal FINDNODE(0) ENR exchange after session expiry and carry a /p2p suffix that fails the reply address check.
• The IPv6 vote-harvest ping (bucket-full outgoing peers) prefers IPv6 explicitly and is marked as a probe. A probe failure does not fail requests queued behind it (failRequest hands the queue to sendNextRequest instead of failSession) and does not mark the peer Disconnected in rpcFailure. The probe flag survives the pending queue.
• verifyEnr accepts a dual-stack ENR observed over either family.
• New metric discv5_request_failed_count{reason}.

Breaking

Dual-stack peers are now contacted over IPv4 first. Set dualStackPreferredFamily: 6 to restore the previous order. A host with working IPv6 and broken IPv4 loses connectivity to dual-stack peers until it sets that option; a follow-up adds per-request fallback to the other family.

Tests

• test/unit/util/ip.test.ts, test/unit/session/nodeInfo.test.ts: selection order and the endpoint-override contact.
• test/unit/transport/udp.test.ts: send rejects on an undeliverable datagram, before start, and for an unbound family.
• test/unit/session/service.test.ts: stub transport; SendFailed without waiting for the timeout, queue failure semantics, probe isolation, probe flag through the queue, verifyEnr over either family.
• test/e2e/dualStack.test.ts: loopback nodes where the peer advertises an unreachable IPv6 address next to reachable 127.0.0.1. Default reaches it over IPv4 (2001:db8::1, which some kernels blackhole and others refuse); IPv6-first fails fast with SendFailed (::ffff:127.0.0.1, which an IPv6-only socket refuses on every platform); a peer that dialed us over ::1 is contacted back over ::1.

The existing mainnetBootnodes e2e cannot show this regression because the mainnet list still has IPv4-only entries.

Follow-up

Sequential endpoint fallback in SessionService: try the other family after a SendFailed or a timeout, with a bounded success cache. This PR leaves the single request-send chokepoint, the probe flag in both layers and contactFor in place for it.

Verification on an IPv4-only Docker host

Lodestar built from a throwaway branch that overrides @chainsafe/discv5 with this branch, run on a Linux host whose Docker bridge has no IPv6 route, with --listenAddress 0.0.0.0 --listenAddress6 :: so both sockets are bound, built-in bootnodes only (SKIP_FETCH_NETWORK_BOOTNODES=1), 90 seconds after start:

node	discv5 connected	kad table	ENRs decoded	request failures
sepolia, this branch	15	20	138	147 Timeout, 8 SendFailed
sepolia, unpatched v1.48.0	0	7 (bootnodes only)	0	metric not available
hoodi, this branch	17	20	3	6 Timeout

The unpatched node never decodes a single ENR: every request goes to an IPv6 address and dies on the timeout. The SendFailed count on the patched node is the IPv6 vote-harvest probes, which are isolated from the routing table by design. The unit and e2e suites also pass on that host inside a node:24 container both with host networking (IPv6 route present) and on the bridge network (none).

AI Assistance Disclosure

This PR was written primarily by Claude Code: the investigation, the code, the tests and this description. I directed the work and validated the fix on our own infrastructure. A second model (Codex) reviewed the design twice and the diff twice before submission. Replies in this PR may also be drafted with AI assistance.