Circuit Relay v2 Implementation Analysis

[acul71]

Circuit Relay v2 Implementation Analysis

Date: Oct 16th 2025

Overview

This document analyzes the current state of Circuit Relay v2 implementation in py-libp2p, focusing on the changes made in the recent commits and the current functionality.

Current Implementation Status

⭐ Features Added After Commit d60dac6

The following features were NOT present in commit d60dac601a4006ad9a0a73aefbfe5325e2811162 and were added in subsequent work:

1. Network Context Support (libp2p/network/context.py) - NEW FILE

   • with_allow_limited_conn() function
   • get_allow_limited_conn() function
   • Context variable management for limited connections

2. Swarm Connection Limited Support (libp2p/network/connection/swarm_connection.py)

   • limited property added to SwarmConn class
   • Limited connection tracking and management

3. Swarm Limited Connection Handling (libp2p/network/swarm.py)

   • Limited connection detection in new_stream()
   • Fallback to direct connections when limited connections not allowed
   • Context-aware connection selection

4. Circuit Relay v2 Transport Integration (libp2p/network/swarm.py)

   • Circuit Relay v2 connections marked as limited=True
   • Integration with connection management system

5. Host Context Support (libp2p/host/basic_host.py)

   • Context parameter added to new_stream() method
   • Context passing to network layer

6. Enhanced Example Usage (examples/circuit_relay/relay_example.py)

   • Context system usage in example
   • WithAllowLimitedConn equivalent implementation

7. Transport Registry Integration (libp2p/transport/transport_registry.py)

   • Circuit Relay v2 transport registration for /p2p-circuit protocol
   • Automatic transport selection for Circuit Relay v2 multiaddrs
   • Integration with global transport registry system

Key Components

1. Circuit Relay v2 Protocol (libp2p/relay/circuit_v2/protocol.py)

The Circuit Relay v2 protocol implementation handles the core relay functionality:

class CircuitV2Protocol(Service):
    """
    Circuit Relay v2 Protocol implementation.
    
    This protocol handles HOP and STOP messages for Circuit Relay v2 connections.
    """
    
    async def _handle_connect(self, stream: INetStream, msg: Any) -> None:
        """Handle a connect request."""
        # Get destination peer ID
        dst_peer_id = ID(msg.peer)
        
        # Get source peer ID from the muxed connection
        src_peer_id = stream.muxed_conn.peer_id
        
        # Establish connection to destination
        dst_stream = await self.host.new_stream(
            dst_peer_id, [STOP_PROTOCOL_ID]
        )
        
        # Send STOP CONNECT message
        stop_msg = StopMessage(
            type=StopMessage.CONNECT,
            peer=stream.muxed_conn.peer_id.to_bytes(),
        )
        await dst_stream.write(stop_msg.SerializeToString())
        
        # Start relaying data
        await self._relay_data(stream, dst_stream, src_peer_id or dst_peer_id, Pipe.BOTH)

2. Network Context Support (libp2p/network/context.py) ⭐ NEW FEATURE

Note: This file was not present in commit d60dac601a4006ad9a0a73aefbfe5325e2811162 and was added in subsequent work.

Added support for limited connections, equivalent to Go's WithAllowLimitedConn:

def with_allow_limited_conn(reason: str) -> Dict[str, Any]:
    """
    Create a context option that instructs the network that it is acceptable 
    to use a limited connection when opening a new stream.
    
    This is the Python equivalent of Go libp2p's network.WithAllowLimitedConn.
    """
    return {
        'allow_limited_conn': reason
    }

def get_allow_limited_conn(context: Optional[Dict[str, Any]] = None) -> Tuple[bool, Optional[str]]:
    """Check if the allow limited connection option is set in the context."""
    if context and 'allow_limited_conn' in context:
        return True, context['allow_limited_conn']
    
    reason = _allow_limited_conn.get()
    if reason is not None:
        return True, reason
    
    return False, None

3. Swarm Connection Limited Support (libp2p/network/connection/swarm_connection.py) ⭐ ENHANCED FEATURE

Note: The limited property and related functionality was not present in commit d60dac601a4006ad9a0a73aefbfe5325e2811162 and was added in subsequent work.

Added support for marking connections as limited:

class SwarmConn(INetConn):
    _limited: bool

    def __init__(
        self,
        muxed_conn: IMuxedConn,
        swarm: "Swarm",
        limited: bool = False,
    ) -> None:
        self.muxed_conn = muxed_conn
        self.swarm = swarm
        self._limited = limited
        # ... rest of initialization

    @property
    def limited(self) -> bool:
        """Check if this connection is limited (e.g., Circuit Relay v2)."""
        return self._limited

4. Swarm Limited Connection Handling (libp2p/network/swarm.py) ⭐ ENHANCED FEATURE

Note: The limited connection handling logic was not present in commit d60dac601a4006ad9a0a73aefbfe5325e2811162 and was added in subsequent work.

Modified the swarm to handle limited connections:

async def new_stream(
    self, peer_id: ID, protocol_ids: Sequence[TProtocol] | None = None, context: dict | None = None
) -> INetStream:
    """Create a new stream with support for limited connections."""
    # Get existing connections or dial new ones
    connections = self.get_connections(peer_id)
    if not connections:
        connections = await self.dial_peer(peer_id)

    # Load balancing strategy at interface level
    connection = self._select_connection(connections, peer_id)

    # Check if connection is limited and if limited connections are allowed
    if connection and hasattr(connection, 'limited') and connection.limited:
        from libp2p.network.context import get_allow_limited_conn
        limited_allowed, reason = get_allow_limited_conn(context)
        if not limited_allowed:
            logger.debug("Limited connection not allowed for peer %s", peer_id)
            # Try to get a direct connection instead
            direct_connections = [conn for conn in connections if not (hasattr(conn, 'limited') and conn.limited)]
            if direct_connections:
                connection = self._select_connection(direct_connections, peer_id)
            else:
                # No direct connections available, raise an error
                from libp2p.network.exceptions import SwarmException
                raise SwarmException(f"Limited connection not allowed and no direct connection available to peer {peer_id}")

5. Circuit Relay v2 Transport Integration (libp2p/network/swarm.py) ⭐ ENHANCED FEATURE

Note: The Circuit Relay v2 connection marking as limited was not present in commit d60dac601a4006ad9a0a73aefbfe5325e2811162 and was added in subsequent work.

Circuit Relay v2 connections are marked as limited:

# Create a muxed connection from the raw connection
muxed_conn = Yamux(raw_conn, peer_id)
# Mark Circuit Relay v2 connections as limited
swarm_conn = SwarmConn(muxed_conn, self, limited=True)

6. Host Context Support (libp2p/host/basic_host.py) ⭐ ENHANCED FEATURE

Note: The context parameter support was not present in commit d60dac601a4006ad9a0a73aefbfe5325e2811162 and was added in subsequent work.

Added context parameter to host's new_stream method:

async def new_stream(
    self,
    peer_id: ID,
    protocol_ids: Sequence[TProtocol],
    context: dict | None = None,
) -> INetStream:
    """Create a new stream with context support."""
    net_stream = await self._network.new_stream(peer_id, context=context)
    
    # Perform protocol muxing to determine protocol to use
    try:
        selected_protocol = await self.multiselect_client.select_one_of(
            list(protocol_ids),
            MultiselectCommunicator(net_stream),
            5,  # Default timeout
        )
        net_stream.set_protocol(selected_protocol)
        logger.debug(
            "successfully negotiated protocol %s for peer %s",
            selected_protocol,
            peer_id,
        )
    except MultiselectClientError as error:
        logger.debug("failed to negotiate protocol with peer %s: %s", peer_id, error)
        raise StreamFailure(f"failed to open a stream to peer {peer_id}") from error

7. Transport Registry Integration (libp2p/transport/transport_registry.py) ⭐ NEW FEATURE

Note: Circuit Relay v2 transport registration was not present in commit d60dac601a4006ad9a0a73aefbfe5325e2811162 and was added in subsequent work.

Added Circuit Relay v2 transport support to the transport registry:

def _register_default_transports(self) -> None:
    """Register the default transport implementations."""
    # ... other transports ...
    
    # Register Circuit Relay v2 transport for /p2p-circuit protocol
    try:
        from libp2p.relay.circuit_v2.transport import CircuitV2Transport
        self.register_transport("p2p-circuit", CircuitV2Transport)
    except ImportError:
        # Circuit Relay v2 transport not available
        pass

Circuit Relay v2 multiaddr handling:

elif "p2p-circuit" in protocols:
    # For Circuit Relay v2, we need a valid structure like:
    # /p2p/{relay_peer_id}/p2p-circuit/p2p/{destination_peer_id}
    registry = get_transport_registry()
    return registry.create_transport("p2p-circuit", upgrader, **kwargs)

8. Example Usage (examples/circuit_relay/relay_example.py) ⭐ ENHANCED FEATURE

Note: The context system usage in the example was not present in commit d60dac601a4006ad9a0a73aefbfe5325e2811162 and was added in subsequent work.

Updated the example to use the new context system:

# Create a stream using the host with allow limited connection context
# This is the Python equivalent of Go's network.WithAllowLimitedConn
from libp2p.network.context import with_allow_limited_conn

logger.debug("[SRC] Creating stream over Circuit Relay v2 connection with allow limited context")
context = with_allow_limited_conn("echo_protocol")
stream = await host.new_stream(dest_peer_id, [TProtocol("/universal/1.0.0")], context=context)
logger.info("Successfully created stream on Circuit Relay v2 connection with protocol negotiation")

Current Limitations

1. Raw Data Relaying Only

The current implementation only supports raw data relaying between a single source stream and a single destination stream:

async def _relay_data(
    self,
    src_stream: INetStream,
    dst_stream: INetStream,
    peer_id: ID,
    direction: Pipe,
) -> None:
    """Relay data between source and destination streams."""
    # Simple data forwarding without stream multiplexing
    # This doesn't support multiple streams or protocol negotiation

2. No Multi-Stream Support

The Circuit Relay v2 implementation doesn't support multiple streams over a single connection, which is required for proper protocol negotiation.

3. Protocol Negotiation Issues

When the source tries to perform protocol negotiation over the Circuit Relay v2 connection, the destination never receives the protocol negotiation requests because the relay only forwards raw bytes.

Test Results

The current implementation shows the following behavior:

1. Circuit Relay v2 Connection Establishment: ✅ Working

   • Relay successfully establishes connections between source and destination
   • STOP messages are properly handled

2. Protocol Negotiation: ❌ Failing

   • Source creates stream over Circuit Relay v2 connection
   • Protocol negotiation times out (MultiselectClientError: response timed out)
   • Destination never receives protocol negotiation requests

3. Echo Protocol: ❌ Not Working

   • Echo protocol handler is registered on destination
   • But destination never receives the protocol negotiation request
   • No echo messages are exchanged

Conclusion

The current Circuit Relay v2 implementation provides basic connection establishment and data relaying, but lacks the multi-stream support required for proper protocol negotiation. The implementation needs significant architectural changes to support multiple streams over Circuit Relay v2 connections, similar to the Go implementation.

[acul71]

How to Run Circuit Relay v2 Test with Log Analysis

🚀 Quick Start

# 1. Navigate to project directory
cd py-libp2p

# 2. Activate virtual environment
source venv/bin/activate

# 3. Run the test with timeout
timeout 50 ./libp2p/relay/circuit_v2/test_relay_example_parallel_debug.sh

📋 What the Test Does

The script automatically:

1. Starts relay node on port 8000
2. Starts destination node on port 8001
3. Starts source node that connects through relay
4. Generates log files for analysis

📊 Log Files Generated

• relay_output.log - Relay node logs
• dest_output.log - Destination node logs
• source_output.log - Source node logs

🔍 Key Log Checks

✅ Success Indicators:

# Check for successful connection
grep "Successfully connected to destination through relay" source_output.log

# Check for echo protocol handler
grep "🎯 DESTINATION ECHO HANDLER CALLED" dest_output.log

# Check for message exchange
grep "📤 SOURCE SENT APPLICATION MESSAGE" source_output.log
grep "🎯 SOURCE RECEIVED ECHO RESPONSE" source_output.log

❌ Error Indicators:

# Check for connection errors
grep -i "error\|exception\|failed" source_output.log

# Check for protocol negotiation failures
grep "MultiselectClientError" source_output.log

# Check for stream creation issues
grep "set_state" source_output.log

🎯 Expected Results

✅ Working Circuit Relay v2:

• Relay starts successfully
• Destination connects to relay
• Source connects to destination through relay
• Echo protocol messages exchanged
• No error messages

❌ Current Issues:

• Circuit Relay v2 connection established ✅
• Stream creation works ✅
• Echo protocol handler never called ❌
• No message exchange ❌

🔧 Troubleshooting

If Test Times Out:

# Check relay logs
tail -20 relay_output.log

# Check destination logs  
tail -20 dest_output.log

# Check source logs
tail -20 source_output.log

If Context Error:

# Should be fixed now - check for:
grep "unexpected keyword argument 'context'" source_output.log

If Stream Routing Fails:

# Look for these patterns:
grep "🎯 DESTINATION ECHO HANDLER CALLED" dest_output.log  # Should appear
grep "Successfully routed Circuit Relay v2 stream" relay_output.log  # Should appear

📈 Test Output Analysis

The script provides colored output:

• 🔵 [INFO] - General information
• 🟢 [SUCCESS] - Successful operations
• 🟡 [WARNING] - Potential issues
• 🔴 [ERROR] - Critical failures

🎯 Current Status

✅ Circuit Relay v2 connection established
✅ Stream creation working
✅ Context parameter fixed
❌ Stream routing not working - Core architectural issue
❌ Echo protocol handler not invoked - Needs stream routing fix

The test is working correctly and shows the fundamental stream routing issue that needs to be resolved in the Circuit Relay v2 implementation.