Improve dual-stack / discv5 documentation

[alexandratran]

Description

Add concept page for dual-stack networking and improve clarity and accuracy on related docs. Document new config options discovery-mode, p2p-discovery-port, and p2p-discovery-port-ipv6.

The added page is here:

• https://besu-docs-git-fork-alexandratran-2004-dual-stack-hyperledger.vercel.app/public-networks/concepts/ipv6-dual-stack

And changes were made to related content, including:

• https://besu-docs-git-fork-alexandratran-2004-dual-stack-hyperledger.vercel.app/public-networks/how-to/connect/configure-ports#p2p-networking
• https://besu-docs-git-fork-alexandratran-2004-dual-stack-hyperledger.vercel.app/public-networks/concepts/node-keys#enode-url
• https://besu-docs-git-fork-alexandratran-2004-dual-stack-hyperledger.vercel.app/public-networks/concepts/node-keys#enr-url
• https://besu-docs-git-fork-alexandratran-2004-dual-stack-hyperledger.vercel.app/private-networks/how-to/configure/bootnodes#specify-a-bootnode
• https://besu-docs-git-fork-alexandratran-2004-dual-stack-hyperledger.vercel.app/public-networks/reference/options#discovery-mode
• https://besu-docs-git-fork-alexandratran-2004-dual-stack-hyperledger.vercel.app/public-networks/reference/options#p2p-discovery-port
• https://besu-docs-git-fork-alexandratran-2004-dual-stack-hyperledger.vercel.app/public-networks/reference/genesis-items#discovery-configuration-items
• https://besu-docs-git-fork-alexandratran-2004-dual-stack-hyperledger.vercel.app/public-networks/reference/api/admin#admin_nodeinfo

Related issue(s)

Fixes #2004
Fixes #2083
Fixes #2105

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
besu-docs	Ready	Preview	Aug 18, 2026 11:37pm

[alexandratran]

besu-eth/besu has two open PRs that will change the behavior this page documents. Recommend holding this PR until they land, then revisiting the items below.

Tracking:

• feat(p2p): DiscV4 + DiscV5 on shared UDP socket with --discovery-mode selector besu#10624 — DiscV4 + DiscV5 on shared UDP socket, adds --discovery-mode=BOTH|V4|V5 (default BOTH); 0/3 required reviewers approved as of writing; unresolved comment on Cluster.java bootnode-selection edge case.
• feat(p2p): add --p2p-discovery-port flag for separate UDP discovery port besu#10718 — adds --p2p-discovery-port to decouple the UDP discovery port from --p2p-port (Kubernetes host-port mapping); unresolved comment that it doesn't yet handle the IPv6 dual-stack case symmetrically; needs a DCO signoff fix.
• Discv5 metrics followup besu#10646 — metrics follow-up to #10624, also still open.

Anticipated doc impact once #10624 lands (do not action until merged/reviewed):

1. --Xv5-discovery-enabled is removed, replaced by --discovery-mode=BOTH|V4|V5. Every "Early access feature" admonition gating IPv6/dual-stack/ENR bootnodes on that flag needs updating in ipv6-dual-stack.md, node-keys.md, bootnodes.md, configure-ports.md, and options.md.
2. Discovery v5 appears to graduate out of early-access framing (the --X prefix is dropped) — re-evaluate all early-access admonitions tied to v5 specifically.
3. IPv6-only single-stack mode goes away. --p2p-host/--p2p-interface become IPv4-only; --p2p-host-ipv6/--p2p-interface-ipv6 become the only way to configure IPv6. This reverses several "for an IPv6-only node, set --p2p-host to an IPv6 value" notes added in this PR, and removes the IPv6-only rows from the admin_nodeInfo table in ipv6-dual-stack.md.
4. Dual-stack stops being DiscV5-exclusive — DiscV4 gains its own IPv6 dual-stack path. Every "dual-stack requires discovery v5" claim added in this PR needs flipping to "dual-stack requires discovery v5 or v4+v5 (BOTH)" or similar, once the exact semantics are confirmed.
5. Mixed enode/ENR bootnode lists become valid (prefix-routed: enr: → V5, enode:// → V4), reversing the currently-shipped restriction from Update --bootnodes description and throw exception is mixed enode and ENR bootnodes are present besu#9955. Update the "list of sources must specify all enode URLs or all ENR URLs" line in bootnodes.md.
6. Genesis v5Bootnodes key is dropped, merged into a unified bootnodes array — affects genesis-items.md.
7. admin_nodeInfo gains an enodeV6 field, on top of the already-documented listenAddrV6/ports.listenerV6/ports.discoveryV6.

Anticipated doc impact once #10718 lands:

8. --p2p-discovery-port decouples the UDP discovery port from --p2p-port — affects configure-ports.md and the CLI reference. Wait for the IPv6-symmetry gap to resolve before documenting IPv6 behavior here.