feat: add QUIC support

[wemeetagain]

Motivation

Add native QUIC transport support to Lodestar via @chainsafe/libp2p-quic. QUIC provides lower-latency connections with built-in encryption (TLS 1.3) and multiplexing, eliminating the need for separate stream muxers and reducing handshake overhead compared to TCP+Noise+mplex.

Supersedes #7659

Description

Transport configuration

• Add QUIC transport alongside TCP using @chainsafe/libp2p-quic
• QUIC is disabled by default, enabled via --quic
• Default QUIC port is port + 1 (9001 when port is 9000), configurable via --quicPort / --quicPort6
• Add --quic and --tcp CLI flags to selectively enable/disable transports (--tcp is hidden, defaults to true)
• Fail-early validation: error if both transports disabled, or if discoveryPort and quicPort collide (both UDP)
• QUIC multiaddrs are listed before TCP in localMultiaddrs so libp2p prefers QUIC for outbound dials

ENR (Ethereum Node Record)

• Advertise quic / quic6 fields in ENR when QUIC is enabled
• Respect --tcp / --quic flags: only advertise enabled transports
• Preserve existing ENR quic port values on restart (fallback chain: CLI arg → derived port → existing ENR value)
• Clear all transport fields (tcp, quic) when testMultiaddrForLocal detects a non-local IP

Peer discovery

• enrRelevance accepts peers with TCP or QUIC (previously required TCP)
• getDiscv5Multiaddrs prefers QUIC multiaddrs from boot ENRs when QUIC is enabled, falls back to TCP
• handleDiscoveredPeer selects multiaddrs by protocol (/tcp/, /quic-v1) instead of assuming array index ordering
• handleDiscoveredPeer matches peers that share any enabled transport, not just TCP
• Normalize transport Symbol.toStringTag values for matching (@libp2p/tcp → tcp, quic → quic)
• CachedENR.multiaddrTCP is now optional to support QUIC-only peers

Documentation

• Add QUIC transport section to networking docs covering enabling, port configuration, ENR advertisement
• Update firewall ports documentation to include QUIC UDP port

Testing

• Unit tests for enrRelevance with tcp-only, quic-only, both, and neither
• Unit tests for getDiscv5Multiaddrs QUIC preference and fallback behavior
• Unit tests for port collision and both-transports-disabled validation
• Unit tests for ENR field gating (--tcp, --quic) and quic port fallback preservation
• Unit tests for multiaddr filtering with --tcp / --quic
• Fix sim test port allocation to stride by 2, leaving room for QUIC port

AI Disclosure

AI-assisted (Claude Code)

[twoeths]

I dropped few minor comments
also need to handle quic6 for direct peers too? see

lodestar/packages/beacon-node/src/network/gossip/gossipsub.ts

Line 541 in 8cdde18

const multiaddrTCP = enr.getLocationMultiaddr("tcp");

[nflaig]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 92be808c06

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

Adds native QUIC transport support to Lodestar’s libp2p stack (alongside TCP) with new CLI flags, ENR advertisement updates, discovery/dial preference changes, docs, dashboards, and unit tests.

Changes:

• Introduce QUIC transport configuration (--quic, --quicPort{,6}, hidden --tcp) and prefer QUIC multiaddrs for dialing.
• Extend ENR/discovery/direct-peers handling to accept and prioritize QUIC-only or QUIC+TCP peers.
• Add/adjust unit tests, networking docs, dashboards, and sim-test port allocation to account for QUIC.

Reviewed changes

Copilot reviewed 20 out of 21 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
pnpm-workspace.yaml	Excludes QUIC packages from pnpm minimum release age policy.
pnpm-lock.yaml	Locks @chainsafe/libp2p-quic and platform-specific optional deps.
packages/cli/test/utils/crucible/utils/ports.ts	Strides ports by 2 to leave room for QUIC port.
packages/cli/test/unit/options/beaconNodeOptions.test.ts	Updates expected network options and adds tcp/quic flag tests.
packages/cli/test/unit/cmds/initPeerIdAndEnr.test.ts	Adds tests for ENR field gating and QUIC port behavior.
packages/cli/src/options/beaconNodeOptions/network.ts	Adds QUIC ports + tcp/quic flags, validation, and multiaddr ordering.
packages/cli/src/cmds/beacon/options.ts	Adds --enr.quic / --enr.quic6 CLI overrides.
packages/cli/src/cmds/beacon/initPeerIdAndEnr.ts	Writes/clears QUIC ENR fields based on flags and locality checks.
packages/beacon-node/test/unit/network/libp2p/getDiscv5Multiaddrs.test.ts	New tests for QUIC preference/fallback in boot ENR extraction.
packages/beacon-node/test/unit/network/gossip/directPeers.test.ts	Extends direct peer ENR parsing tests for QUIC/TCP combinations.
packages/beacon-node/test/unit/network/discv5/utils.test.ts	New tests for ENR relevance with TCP/QUIC transport combinations.
packages/beacon-node/src/network/peers/discover.ts	Supports QUIC multiaddrs, transport compatibility filtering, and safer addr selection.
packages/beacon-node/src/network/options.ts	Adds quic/tcp options and defaults.
packages/beacon-node/src/network/metadata.ts	Adds ENRKey.quic.
packages/beacon-node/src/network/libp2p/index.ts	Enables QUIC transport, configures transports list, and QUIC-aware boot multiaddr selection.
packages/beacon-node/src/network/gossip/gossipsub.ts	Allows QUIC/TCP transport multiaddrs from ENR direct peers and logs all addrs.
packages/beacon-node/src/network/discv5/utils.ts	Updates ENR relevance to accept TCP or QUIC.
packages/beacon-node/package.json	Adds @chainsafe/libp2p-quic dependency.
docs/pages/run/beacon-management/networking.md	Documents QUIC usage, ports, ENR advertisement, and firewall changes.
dashboards/lodestar_libp2p.json	Updates panels/queries to include QUIC transport metrics and reorganizes panels.
.wordlist.txt	Adds QUIC/TLS to spelling allowlist.

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

[matthewkeil]

Generally looks good!!! LFG 🚀

Just need to address this comment:
#8051 (comment)

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 52.32%. Comparing base (b90dff6) to head (5058c52).
⚠️ Report is 1 commits behind head on unstable.

Additional details and impacted files

@@            Coverage Diff            @@
##           unstable    #8051   +/-   ##
=========================================
  Coverage     52.32%   52.32%           
=========================================
  Files           848      848           
  Lines         62505    62470   -35     
  Branches       4603     4597    -6     
=========================================
- Hits          32703    32689   -14     
+ Misses        29736    29716   -20     
+ Partials         66       65    -1     

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[wemeetagain]

🎉 This PR is included in v1.41.0 🎉