Integrating DCUtR with Circuit Relay v2 for Robust NAT Traversal

[Winter-Soren]

Overview

This discussion outlines the approach for integrating Direct Connection Upgrade through Relay (DCUtR) with Circuit Relay v2 in py-libp2p, enabling robust NAT traversal and resilient peer connectivity. The integration aims to provide fallback and upgrade mechanisms between relayed and direct connections.

Motivation

• Circuit Relay v2 allows peers to communicate when direct connections are not possible (e.g., due to NAT).
• DCUtR enables peers to upgrade relayed connections to direct connections using hole punching, reducing relay load and improving latency.
• Integrating both protocols ensures:
  • Automatic use of relays when direct connections fail.
  • Opportunistic or adaptive upgrade to direct connections when possible.
  • Fallback to relay if hole punching fails, ensuring resilience.

Workflow Diagram

sequenceDiagram
    participant A as Peer A
    participant R as Relay
    participant B as Peer B

    A->>R: 1. HOP CONNECT (to B)
    R->>B: 2. STOP CONNECT
    B->>R: 3. OK
    R->>A: 4. OK

    Note over A,B: Relay Connection Established

    A->>B: 5. DCUtR CONNECT
    B->>A: 6. DCUtR CONNECT
    A->>B: 7. DCUtR SYNC

    par Hole Punching
        A->>B: 8a. Direct connection attempt
        B->>A: 8b. Direct connection attempt
    end

    Note over A,B: Direct Connection Established

    A-->>R: 9. (Optional) Close relay connection

Loading

---

Integration Approaches

Approach 1: Proactive Upgrade with Signal-Based Detection

Relay connections are established as needed, but the system actively monitors the health and performance of the relay connection. If certain signals (e.g., high latency, handshake failures, stream resets, or timeouts) are detected, the system proactively attempts a DCUtR (hole punch) upgrade to a direct connection. All failures and switching events are logged for diagnostics.

Key Features:

• Signal-based triggers:
  • High relay latency
  • Connection instability (frequent resets, handshake failures)
  • Timeouts or unresponsiveness
• Automatic fallback:
  • If DCUtR fails, continue using the relay connection.
• Observability:
  • Detailed logging of failures and protocol switches.
• Configurability:
  • Thresholds for latency, timeouts, and instability can be tuned.

Approach 2: Opportunistic Upgrade After Relay Establishment

After establishing a relay connection, the system always attempts a DCUtR upgrade to a direct connection, regardless of the relay connection’s health or performance. This is a simpler, more aggressive approach that does not wait for signals or issues before attempting the upgrade.

Key Features:

• Always-on upgrade attempt:
  • As soon as a relay connection is established, immediately try DCUtR.
• No signal monitoring:
  • Upgrade is attempted regardless of relay performance.
• Automatic fallback:
  • If DCUtR fails, continue using the relay connection.
• Simplicity:
  • Easier to implement, but may result in unnecessary hole punch attempts.

Comparison Table

Feature	Approach 1: Signal-Based	Approach 2: Opportunistic
Upgrade Trigger	On relay issues/signals	Always after relay setup
Resource Usage	Lower (fewer attempts)	Higher (more attempts)
Complexity	Higher	Lower
Observability	High (detailed logs)	Basic logs
User Experience	Adaptive, resilient	Simple, may be wasteful