libp2p.relay package

Subpackages

• libp2p.relay.circuit_v2 package
  • Subpackages
    • libp2p.relay.circuit_v2.pb package
      • Submodules
      • libp2p.relay.circuit_v2.pb.circuit_pb2 module
      • Module contents
  • Submodules
  • libp2p.relay.circuit_v2.protocol module
    • CircuitV2Protocol
      • CircuitV2Protocol.handle_incoming_connection()
      • CircuitV2Protocol.run()
    • IHostWithStreamHandlers
      • IHostWithStreamHandlers.remove_stream_handler()
    • INetStreamWithExtras
      • INetStreamWithExtras.get_remote_peer_id()
      • INetStreamWithExtras.is_closed()
      • INetStreamWithExtras.is_open()
  • libp2p.relay.circuit_v2.transport module
    • CircuitV2Listener
      • CircuitV2Listener.close()
      • CircuitV2Listener.get_addrs()
      • CircuitV2Listener.handle_incoming_connection()
      • CircuitV2Listener.listen()
      • CircuitV2Listener.run()
    • CircuitV2Transport
      • CircuitV2Transport.create_listener()
      • CircuitV2Transport.dial()
      • CircuitV2Transport.dial_peer_info()
      • CircuitV2Transport.discover_peers()
      • CircuitV2Transport.parse_circuit_ma()
      • CircuitV2Transport.reserve()
    • TrackedRawConnection
      • TrackedRawConnection.close()
      • TrackedRawConnection.get_remote_address()
      • TrackedRawConnection.read()
      • TrackedRawConnection.write()
  • libp2p.relay.circuit_v2.discovery module
    • IHostWithMultiselect
      • IHostWithMultiselect.multiselect
    • RelayDiscovery
      • RelayDiscovery.discover_relays()
      • RelayDiscovery.get_relay()
      • RelayDiscovery.get_relay_info()
      • RelayDiscovery.get_relays()
      • RelayDiscovery.make_reservation()
      • RelayDiscovery.run()
    • RelayInfo
      • RelayInfo.discovered_at
      • RelayInfo.has_reservation
      • RelayInfo.last_seen
      • RelayInfo.peer_id
      • RelayInfo.reservation_data_limit
      • RelayInfo.reservation_expires_at
  • libp2p.relay.circuit_v2.resources module
    • RelayLimits
      • RelayLimits.data
      • RelayLimits.duration
      • RelayLimits.max_circuit_conns
      • RelayLimits.max_reservations
    • RelayResourceManager
      • RelayResourceManager.can_accept_connection()
      • RelayResourceManager.can_accept_reservation()
      • RelayResourceManager.create_reservation()
      • RelayResourceManager.has_reservation()
      • RelayResourceManager.refresh_reservation()
      • RelayResourceManager.reserve()
      • RelayResourceManager.track_data_transfer()
      • RelayResourceManager.verify_reservation()
    • Reservation
      • Reservation.can_accept_connection()
      • Reservation.get_data_to_sign()
      • Reservation.is_expired()
      • Reservation.status
      • Reservation.to_proto()
      • Reservation.track_data_transfer()
    • ReservationStatus
      • ReservationStatus.ACTIVE
      • ReservationStatus.EXPIRED
      • ReservationStatus.REJECTED
    • ReservationVoucher
      • ReservationVoucher.addrs
      • ReservationVoucher.expiration
      • ReservationVoucher.peer
      • ReservationVoucher.relay
  • libp2p.relay.circuit_v2.config module
    • ClientConfig
      • ClientConfig.auto_relay_timeout
      • ClientConfig.enable_auto_relay
      • ClientConfig.max_auto_relay_attempts
      • ClientConfig.max_concurrent_reservations
      • ClientConfig.max_relay_latency
      • ClientConfig.min_relay_score
      • ClientConfig.reservation_refresh_threshold
    • HopConfig
      • HopConfig.circuit_rate_per_ip
      • HopConfig.max_bandwidth_per_circuit
      • HopConfig.max_bandwidth_total
      • HopConfig.max_circuits_per_ip
      • HopConfig.max_circuits_total
      • HopConfig.max_reservations_per_ip
      • HopConfig.max_reservations_total
      • HopConfig.reservation_rate_per_ip
    • RelayConfig
      • RelayConfig.bootstrap_relays
      • RelayConfig.discovery_interval
      • RelayConfig.enable_client
      • RelayConfig.enable_dht_discovery
      • RelayConfig.enable_hop
      • RelayConfig.enable_stop
      • RelayConfig.limits
      • RelayConfig.max_circuit_bytes
      • RelayConfig.max_circuit_duration
      • RelayConfig.max_relays
      • RelayConfig.min_relays
      • RelayConfig.reservation_ttl
      • RelayConfig.roles
      • RelayConfig.timeouts
    • RelayRole
      • RelayRole.CLIENT
      • RelayRole.HOP
      • RelayRole.STOP
    • TimeoutConfig
      • TimeoutConfig.dcutr_read_timeout
      • TimeoutConfig.dcutr_write_timeout
      • TimeoutConfig.dial_timeout
      • TimeoutConfig.discovery_stream_timeout
      • TimeoutConfig.peer_protocol_timeout
      • TimeoutConfig.protocol_close_timeout
      • TimeoutConfig.protocol_read_timeout
      • TimeoutConfig.protocol_write_timeout
  • libp2p.relay.circuit_v2.protocol_buffer module
    • StatusCode
      • StatusCode.CONNECTION_FAILED
      • StatusCode.DIAL_REFUSED
      • StatusCode.MALFORMED_MESSAGE
      • StatusCode.OK
      • StatusCode.PERMISSION_DENIED
      • StatusCode.RESERVATION_REFUSED
      • StatusCode.RESOURCE_LIMIT_EXCEEDED
      • StatusCode.STOP_FAILED
    • create_status()
  • libp2p.relay.circuit_v2.performance_tracker module
    • RelayPerformanceTracker
      • RelayPerformanceTracker.export_metrics()
      • RelayPerformanceTracker.get_all_relay_stats()
      • RelayPerformanceTracker.get_relay_score()
      • RelayPerformanceTracker.get_relay_stats()
      • RelayPerformanceTracker.record_circuit_closed()
      • RelayPerformanceTracker.record_circuit_opened()
      • RelayPerformanceTracker.record_connection_attempt()
      • RelayPerformanceTracker.reset()
      • RelayPerformanceTracker.select_best_relay()
    • RelayStats
      • RelayStats.active_circuits
      • RelayStats.failure_count
      • RelayStats.last_updated
      • RelayStats.latency_ema_ms
      • RelayStats.relay_id
      • RelayStats.success_count
      • RelayStats.success_rate
      • RelayStats.total_attempts
  • Module contents

Module contents

Relay module for libp2p.

This package includes implementations of circuit relay protocols for enabling connectivity between peers behind NATs or firewalls.

class libp2p.relay.CircuitV2Protocol(host: IHost, limits: RelayLimits | None = None, allow_hop: bool = False, read_timeout: int = 15, write_timeout: int = 15, close_timeout: int = 10)

Bases: Service

CircuitV2Protocol implements the Circuit Relay v2 protocol.

This protocol allows peers to establish connections through relay nodes when direct connections are not possible (e.g., due to NAT).

async handle_incoming_connection(stream: INetStream, remote_peer_id: bytes) → None

Handle an incoming relay connection.

Parameters

streamINetStream

The incoming stream

remote_peer_idID

The remote peer’s ID

Raises

ConnectionError

If the connection cannot be established

async run(*, task_status: Any = TASK_STATUS_IGNORED) → None

Run the protocol service.

class libp2p.relay.CircuitV2Transport(host: IHost, protocol: CircuitV2Protocol, config: RelayConfig)

Bases: ITransport

CircuitV2Transport implements the transport interface for Circuit Relay v2.

This transport allows peers to establish connections through relay nodes when direct connections are not possible.

create_listener(handler_function: Callable[[ReadWriteCloser], Awaitable[None]]) → IListener

Create a listener on the transport.

Parameters

handler_functionTHandler

A function that is called when a new connection is received. The function should accept a connection (that implements the connection interface) as its argument.

Returns

IListener

A listener instance.

async dial(maddr: Multiaddr) → INetConn

Dial a peer using the multiaddr.

Parameters

maddrmultiaddr.Multiaddr

The multiaddr to dial

Returns

INetConn

The established connection

Raises

ConnectionError

If the connection cannot be established

async dial_peer_info(dest_info: PeerInfo, *, relay_info: PeerInfo | None = None) → IRawConnection

Dial a destination peer using a relay.

Parameters

dest_infoPeerInfo

The destination peer to dial.

relay_infoOptional[PeerInfo], optional

An optional specific relay peer to use.

Returns

RawConnection

The established raw connection to the destination peer through the relay.

Raises

ConnectionError

If the connection cannot be established.

async discover_peers(key: bytes, max_results: int = 5) → list[PeerInfo]

parse_circuit_ma(ma: Multiaddr) → tuple[Multiaddr, ID]

Parse a /p2p-circuit/p2p/<targetPeerID> path from a relay Multiaddr.

Returns:

relay_ma: Multiaddr to the relay target_peer_id: ID of the target peer

Raises:

ValueError: if the Multiaddr is not a valid circuit address

async reserve(stream: INetStream, relay_peer_id: ID, nursery: Nursery) → bool

Public method to create a reservation and start refresher if needed.

class libp2p.relay.DCUtRProtocol(host: IHost, read_timeout: int = 30, write_timeout: int = 30, dial_timeout: int = 10)

Bases: Service

DCUtRProtocol implements the Direct Connection Upgrade through Relay protocol.

This protocol allows two NATed peers to establish direct connections through hole punching, after they have established an initial connection through a relay.

async initiate_hole_punch(peer_id: ID) → bool

Initiate a hole punch with a peer.

Parameters

peer_idID

The peer to hole punch with

Returns

bool

True if hole punch was successful, False otherwise

async run(*, task_status: Any = TASK_STATUS_IGNORED) → None

Run the protocol service.

class libp2p.relay.ReachabilityChecker(host: IHost)

Bases: object

Utility class for checking peer reachability.

This class assesses whether a peer’s addresses are likely to be directly reachable or behind NAT.

async check_peer_reachability(peer_id: ID) → bool

Check if a peer is directly reachable.

Parameters

peer_idID

The peer ID to check

Returns

bool

True if peer is likely directly reachable

async check_self_reachability() → tuple[bool, list[Multiaddr]]

Check if this host is likely directly reachable.

Returns

Tuple[bool, List[Multiaddr]]

Tuple of (is_reachable, public_addresses)

get_public_addrs(addrs: list[Multiaddr]) → list[Multiaddr]

Filter a list of addresses to only include likely public ones.

Parameters

addrsList[Multiaddr]

List of addresses to filter

Returns

List[Multiaddr]

List of likely public addresses

is_addr_public(addr: Multiaddr) → bool

Check if an address is likely to be publicly reachable.

Parameters

addrMultiaddr

The multiaddr to check

Returns

bool

True if address is likely public

class libp2p.relay.RelayDiscovery(host: IHost, auto_reserve: bool = False, discovery_interval: int = 300, max_relays: int = 10, stream_timeout: int = 10, peer_protocol_timeout: int = 5)

Bases: Service

Discovery service for Circuit Relay v2 nodes.

This service discovers and keeps track of available relay nodes, and optionally makes reservations with them.

async discover_relays() → None

Discover relay nodes in the network.

This method queries the network for peers that support the Circuit Relay v2 protocol.

get_relay() → ID | None

Get a single relay peer ID for connection purposes. Prioritizes relays with active reservations.

Returns

Optional[ID]

ID of a discovered relay, or None if no relays found

get_relay_info(peer_id: ID) → RelayInfo | None

Get information about a specific relay.

Parameters

peer_idID

The ID of the relay to get information about

Returns

Optional[RelayInfo]

Information about the relay, or None if not found

get_relays() → list[ID]

Get a list of discovered relay peer IDs.

Returns

list[ID]

List of discovered relay peer IDs

async make_reservation(peer_id: ID) → bool

Make a reservation with a relay.

Parameters

peer_idID

The ID of the relay to make a reservation with

Returns

bool

True if reservation succeeded, False otherwise

async run(*, task_status: Any = TASK_STATUS_IGNORED) → None

Run the discovery service.

class libp2p.relay.RelayLimits(duration: int, data: int, max_circuit_conns: int, max_reservations: int)

Bases: object

Configuration for relay resource limits.

data: int

duration: int

max_circuit_conns: int

max_reservations: int

class libp2p.relay.RelayResourceManager(limits: RelayLimits, host: IHost | None = None)

Bases: object

Manages resources and reservations for relay operations.

This class handles: - Tracking active reservations - Enforcing resource limits - Managing connection quotas

can_accept_connection(peer_id: ID) → bool

Check if a new connection can be accepted for the given peer.

Parameters

peer_idID

The peer ID requesting the connection

Returns

bool

True if the connection can be accepted

can_accept_reservation(peer_id: ID) → bool

Check if a new reservation can be accepted for the given peer.

Parameters

peer_idID

The peer ID requesting the reservation

Returns

bool

True if the reservation can be accepted

create_reservation(peer_id: ID) → Reservation

Create a new reservation for the given peer.

Parameters

peer_idID

The peer ID to create the reservation for

Returns

Reservation

The newly created reservation

has_reservation(peer_id: ID) → bool

Check if a reservation already exists for a peer

Parameters

peer_idID

The peer ID to check for

Returns

bool

True if reservation exists, False otherwise

refresh_reservation(peer_id: ID) → int

reserve(peer_id: ID) → int

Create or update a reservation for a peer and return the TTL.

Parameters

peer_idID

The peer ID to reserve for

Returns

int

The TTL of the reservation in seconds

track_data_transfer(peer_id: ID, bytes_transferred: int) → bool

Track data transferred for a peer’s reservation.

Parameters

peer_idID

The peer ID

bytes_transferredint

Number of bytes transferred

Returns

bool

True if the data limit has not been exceeded, False otherwise

verify_reservation(peer_id: ID, proto_res: Reservation) → bool

Verify a reservation from a protobuf message.

Parameters

peer_idID

The peer ID the reservation is for

proto_resPbReservation

The protobuf reservation message

Returns

bool

True if the reservation is valid

class libp2p.relay.Reservation(peer_id: ID, limits: RelayLimits, host: IHost | None = None)

Bases: object

Represents a relay reservation.

can_accept_connection() → bool

Check if a new connection can be accepted.

get_data_to_sign() → bytes

Get the data that should be signed for this reservation.

Returns

bytes

The data to sign, which includes the domain separator, voucher, and expiration

is_expired() → bool

Check if the reservation has expired.

property status: ReservationStatus

Return the current status as a ReservationStatus enum.

to_proto() → Reservation

Convert the reservation to its protobuf representation.

Returns

PbReservation

The protobuf representation of this reservation

track_data_transfer(bytes_transferred: int) → bool

Track data transferred for this reservation.

Parameters

bytes_transferredint

Number of bytes transferred

Returns

bool

True if the data limit has not been exceeded, False otherwise

libp2p.relay.is_private_ip(ip: str) → bool

Check if an IP address is private.

Parameters

ipstr

IP address to check

Returns

bool

True if IP is private