Hole-Punching (DCUtR) Developer Docs

[Winter-Soren]

What this covers (high-level)

• Protocol flow: CONNECT → CONNECT(resp) → SYNC → simultaneous direct dials, with relay as rendezvous.
• Timing model: initiator computes punch window using RTT (≈ now + 2×RTT + small buffer); responder dials upon SYNC.
• Address exchange: observed non-relay multiaddrs shared as bytes; decode/validation and filtering rules.
• Reachability heuristics: private/link-local/loopback screening; public addr filtering.
• Dial orchestration: parallel, bounded attempts to non-relay addresses; success criteria for direct path.
• Safety: concurrency guards, per-peer attempt caps, timeouts, malformed message handling.
• Interop edges and limitations: naive addr scoring, no timestamp in SYNC today, TCP-only, fallback preserved.

Why this matters

• Reduces relay load and latency when direct is available post-initial rendezvous.
• Preserves relay fallback for reliability.
• Enables NATed peers to establish direct paths without inbound port forwarding.

Discussion prompts

• Interop test plan: scenarios across different NATs (symmetric vs. cone), mixed IPv4/IPv6, and public/CGNAT edges.
• Timing alignment: should we include an explicit punch timestamp in SYNC for tighter coordination?
• Address selection/scoring: prioritize public over private, dedupe families, or adopt a scoring heuristic?
• Observability: desired metrics (attempts, success rate, RTT distribution, addr success histogram)?
• Rollout: default enablement strategy, safe fallbacks, and feature flags.

Links

• Developer guide: https://docs.google.com/document/d/1_v4OI_HLShTucbAPxz35xj_SfN7Vu0r3jujrH9YNVCg/edit?tab=t.0#heading=h.ffjgtwmm6ae8
• DCUtR spec: https://github.com/libp2p/specs/blob/master/relay/DCUtR.md
• Implementation PR: feat/606-enable-nat-traversal-via-hole-punching #668