libp2p.network package

Subpackages

• libp2p.network.connection package
  • Submodules
  • libp2p.network.connection.exceptions module
    • RawConnError
  • libp2p.network.connection.raw_connection module
    • RawConnection
      • RawConnection.close()
      • RawConnection.get_remote_address()
      • RawConnection.is_initiator
      • RawConnection.read()
      • RawConnection.stream
      • RawConnection.write()
  • libp2p.network.connection.swarm_connection module
    • SwarmConn
      • SwarmConn.close()
      • SwarmConn.event_closed
      • SwarmConn.get_streams()
      • SwarmConn.get_transport_addresses()
      • SwarmConn.is_closed
      • SwarmConn.muxed_conn
      • SwarmConn.new_stream()
      • SwarmConn.remove_stream()
      • SwarmConn.set_resource_scope()
      • SwarmConn.start()
      • SwarmConn.streams
      • SwarmConn.swarm
  • Module contents
• libp2p.network.stream package
  • Submodules
  • libp2p.network.stream.exceptions module
    • StreamClosed
    • StreamEOF
    • StreamError
    • StreamReset
  • libp2p.network.stream.net_stream module
    • NetStream
      • NetStream.close()
      • NetStream.close_read()
      • NetStream.close_write()
      • NetStream.get_protocol()
      • NetStream.get_remote_address()
      • NetStream.is_operational()
      • NetStream.muxed_stream
      • NetStream.protocol_id
      • NetStream.read()
      • NetStream.remove()
      • NetStream.reset()
      • NetStream.set_protocol()
      • NetStream.set_state()
      • NetStream.state
      • NetStream.write()
    • StreamState
      • StreamState.CLOSE_BOTH
      • StreamState.CLOSE_READ
      • StreamState.CLOSE_WRITE
      • StreamState.ERROR
      • StreamState.INIT
      • StreamState.OPEN
      • StreamState.RESET
  • Module contents

Submodules

libp2p.network.exceptions module

exception libp2p.network.exceptions.SwarmException

Bases: BaseLibp2pError

libp2p.network.swarm module

class libp2p.network.swarm.Swarm(peer_id: ID, peerstore: IPeerStore, upgrader: TransportUpgrader, transport: ITransport, retry_config: RetryConfig | None = None, connection_config: ConnectionConfig | QUICTransportConfig | None = None, psk: str | None = None)

Bases: Service, INetworkService

async add_conn(muxed_conn: IMuxedConn) → SwarmConn

Add a IMuxedConn to Swarm as a SwarmConn, notify “connected”, and start to monitor the connection for its new streams and disconnection.

async close() → None

Close the swarm instance and cleanup resources.

async close_peer(peer_id: ID) → None

Close all connections to the specified peer.

Parameters

peer_idID

The peer ID to close connections for.

common_stream_handler: Callable[[object], Awaitable[None]]

connection_config: ConnectionConfig | QUICTransportConfig

connections: dict[ID, list[INetConn]]

property connections_legacy: dict[ID, INetConn]

Legacy 1:1 mapping for backward compatibility.

Returns

dict[ID, INetConn]

Legacy mapping with only the first connection per peer.

async dial_addr(addr: Multiaddr, peer_id: ID) → INetConn

Enhanced: Try to create a connection to peer_id with addr using retry logic.

Parameters:

• addr – the address we want to connect with

• peer_id – the peer we want to connect to

Raises:

SwarmException – raised when an error occurs

Returns:

network connection

async dial_peer(peer_id: ID) → list[INetConn]

Try to create connections to peer_id with enhanced retry logic.

Parameters:

peer_id – peer if we want to dial

Raises:

SwarmException – raised when an error occurs

Returns:

list of muxed connections

event_listener_nursery_created: Event

get_connection(peer_id: ID) → INetConn | None

Get single connection for backward compatibility.

Parameters

peer_idID

The peer ID to get a connection for.

Returns

INetConn | None

The first available connection, or None if no connections exist.

get_connections(peer_id: ID | None = None) → list[INetConn]

Get connections for peer (like JS getConnections, Go ConnsToPeer).

Parameters

peer_idID | None

The peer ID to get connections for. If None, returns all connections.

Returns

list[INetConn]

List of connections to the specified peer, or all connections if peer_id is None.

get_connections_map() → dict[ID, list[INetConn]]

Get all connections map (like JS getConnectionsMap).

Returns

dict[ID, list[INetConn]]

The complete mapping of peer IDs to their connection lists.

get_peer_id() → ID

Retrieve the peer identifier for this network.

Returns

ID

The identifier of this peer.

async listen(*multiaddrs: Multiaddr) → bool

Parameters:

multiaddrs – one or many multiaddrs to start listening on

Returns:

true if at least one success

For each multiaddr

• Check if a listener for multiaddr exists already

• If listener already exists, continue

• Otherwise:

  • Capture multiaddr in conn handler

  • Have conn handler delegate to stream handler

  • Call listener listen with the multiaddr

  • Map multiaddr to listener

listener_nursery: Nursery | None

listeners: dict[str, IListener]

async new_stream(peer_id: ID) → INetStream

Enhanced: Create a new stream with load balancing across multiple connections.

Parameters:

peer_id – peer_id of destination

Raises:

SwarmException – raised when an error occurs

Returns:

net stream instance

notifees: list[INotifee]

async notify_all(notifier: Callable[[INotifee], Awaitable[None]]) → None

async notify_closed_stream(stream: INetStream) → None

async notify_connected(conn: INetConn) → None

async notify_disconnected(conn: INetConn) → None

async notify_listen(multiaddr: Multiaddr) → None

async notify_listen_close(multiaddr: Multiaddr) → None

async notify_opened_stream(stream: INetStream) → None

peerstore: IPeerStore

register_notifee(notifee: INotifee) → None

Parameters:

notifee – object implementing Notifee interface

Returns:

true if notifee registered successfully, false otherwise

remove_conn(swarm_conn: SwarmConn) → None

Simply remove the connection from Swarm’s records, without closing the connection.

retry_config: RetryConfig

async run() → None

Primary entry point for all service logic.

Note

This method should not be directly invoked by user code.

Services may be run using the following approaches.

self_id: ID

set_resource_manager(resource_manager: ResourceManager | None) → None

Attach a ResourceManager to wire connection/stream scopes.

set_stream_handler(stream_handler: Callable[[object], Awaitable[None]]) → None

Set the stream handler for incoming streams.

Parameters

stream_handlerStreamHandlerFn

The handler function to process incoming streams.

transport: ITransport

async upgrade_inbound_raw_conn(raw_conn: IRawConnection, maddr: Multiaddr) → IMuxedConn

Secure the inbound raw connection and upgrade it to a multiplexed connection.

Parameters:

raw_conn – the inbound raw connection to upgrade

Raises:

SwarmException – raised when security or muxer upgrade fails

Returns:

network connection with security and multiplexing established

async upgrade_outbound_raw_conn(raw_conn: IRawConnection, peer_id: ID, pre_scope: Any = None) → SwarmConn

Secure the outgoing raw connection and upgrade it to a multiplexed connection.

Parameters:

• raw_conn – the raw connection to upgrade

• peer_id – the peer this connection is to

Raises:

SwarmException – raised when security or muxer upgrade fails

Returns:

network connection with security and multiplexing established

upgrader: TransportUpgrader

libp2p.network.swarm.create_default_stream_handler(network: INetworkService) → Callable[[object], Awaitable[None]]

Module contents