A Peer ID is a multihash of the serialized public key.

A key pair containing both public and private keys.

Generate a new random Ed25519 key pair. Returns Left on cryptographic failure (should not occur with proper RNG).

Derive a Peer ID from a public key.

Get the raw multihash bytes of a Peer ID.

Encode a Peer ID as base58btc text.

Parse a Peer ID from text, accepting both base58btc and CIDv1 (base32lower) formats. CIDv1 format: b prefix + base32lower(0x01 || 0x72 || multihash)

Encode a Peer ID as CIDv1 text (base32lower, no padding). Format: b + base32lower(varint(1) + varint(0x72) + multihash_bytes)

A multiaddr is a list of protocol components.

A single protocol component within a multiaddr.

Split off the trailing p2ppeerId component from a multiaddr. Returns the transport address and the peer ID, or Nothing if the multiaddr does not end with a p2p component.

Render a multiaddr as text.

Parse a multiaddr from its text representation (e.g. "ip4127.0.0.1tcp4001").

The Switch: central coordinator of the libp2p networking stack.

Manages transports, connection pool, protocol handlers, and events. All mutable state is STM-based for safe concurrent access.

Create a new Switch with the given local identity. All internal state is initialized empty.

Register a transport with the switch. Appends to the list of transports; order matters for selectTransport.

Start listening on the given addresses.

For each address, selects a matching transport, binds a listener, and spawns an accept loop that handles inbound connections. Returns the actual bound addresses (port 0 resolved to actual port). Fails if the switch is already closed.

Get the current listen addresses from all active listeners.

Shut down the switch. Cancels all accept loop threads, closes all listeners, tears down all pooled connections, then sets the closed flag.

Dial a peer, reusing existing connections or establishing new ones.

Implements the full dial flow: 1. Pool reuse: return existing Open connection if available 2. Backoff check: reject if peer recently failed 3. Deduplication: coalesce concurrent dials to same peer via TMVar 4. Staggered parallel dial with 250ms delay (Happy Eyeballs) 5. First success: upgrade, add to pool, return 6. All fail: record backoff, return error

Tear down a connection: remove it from the pool, release its resource reservation, publish a Disconnected event, and close the muxer session together with the underlying transport.

Idempotent: the state transition to ConnClosed is atomic, so concurrent calls (accept loop exit, explicit close, switchClose) perform the teardown exactly once.

Open an outbound stream on a connection, reserving a stream slot against the peer's resource scope. The slot is released when the returned stream is closed (exactly once, even on double close).

Errors that can occur during a dial operation.

Resource limit violation error.

Register a protocol stream handler. Overwrites any existing handler for the same protocol ID. The changed protocol set is pushed to connected peers via identify push (specs/identify) in the background.

Remove a protocol stream handler. The changed protocol set is pushed to connected peers via identify push (specs/identify) in the background.

Abstraction for stream I/O to enable testing with in-memory buffers.

A protocol stream handler.

Receives the connection the stream runs over and the stream I/O. The connection exposes the remote peer identity (connPeerId) and addresses (connRemoteAddr, connLocalAddr), which protocols like Identify (observedAddr) and the NAT stack need.

A protocol identifier (e.g. "noise", "yamux/1.0.0").

An upgraded (secure + multiplexed) connection to a remote peer.

Transport provides dial/listen capabilities for a specific protocol.

Create a new TCP transport.

Connection gater: policy-based admission control.

Called at multiple points during connection establishment to allow or deny based on policy (IP blocklist, Peer ID allowlist, etc.).

Default gater that allows all connections.

Register Identify protocol handlers on the Switch.

Registers: ipfsid/1.0.0 — respond to Identify requests ipfsidpush1.0.0 — handle Identify Push from remote

Request Identify from a remote peer (initiator side).

Opens a new stream, negotiates ipfsid/1.0.0, then reads one varint-length-prefixed protobuf message. The publicKey field is validated against the connection's authenticated peer id (see validatePublicKey).

Push our current IdentifyInfo to every connected peer (sender side of ipfsidpush1.0.0).

Per specs/identify: open a stream to each remote peer, negotiate the push protocol id, send one Identify message and close the stream. Call this whenever local state advertised via identify changes (listen addresses, registered protocols). Failures on individual peers (e.g. push protocol not supported) are ignored.

Register the Ping handler on the Switch.

The installed handler shares one PingLimiter, so concurrent inbound ping streams are capped at maxPingStreamsPerPeer per remote peer.

Send a single Ping to a remote peer (initiator side).

Convenience wrapper: opens a ping session, pings once, and closes the stream. For repeated pings to the same peer, use withPingSession to reuse one stream instead of opening one per call.

The single outbound ping stream to a peer, negotiated and ready.

Obtain with openPingSession (or scoped via withPingSession), send pings with ping, and always release with closePingSession. A session whose ping failed (timeout, mismatch, I/O error) closes its stream immediately and rejects further pings.

Concurrent ping calls on one session are serialized on psLock: exactly one write/echo exchange runs on the stream at a time, so concurrent callers queue instead of interleaving their 32-byte payloads on the wire.

Open a ping stream on the connection and negotiate the protocol.

The stream is opened through the Switch so it is counted against the peer's stream limits; the reservation is released when the session is closed. On any failure the stream (if opened) is closed before returning.

Send one ping on the session with the default timeout (pingTimeoutMicros). The session's stream is reused across calls.

Send one ping on the session, waiting at most the given number of microseconds for the echo. On failure the session is closed: a stream whose echo timed out or went wrong cannot be reused, because a late echo would corrupt the next ping.

The whole exchange runs under the session lock, so concurrent callers are queued one after another on the single stream. The closed check happens under the lock too: a caller queued behind a failed ping sees the session as closed instead of writing into a poisoned stream.

Close the session's stream (signalling EOF to the responder's echo loop) and release its stream reservation. Idempotent.

Run an action with a ping session, closing it afterwards even if the action throws. Returns Left if the session could not be opened.

Successful ping result.

Ping error types.

Configuration for the NAT traversal handlers.

Default NAT configuration: default relay limits, and inbound relayed streams are left to the remote end (no local consumer).

Register all four NAT protocol handlers on the Switch.

Creates the relay server state from ncRelayConfig and returns it so callers can inspect reservations/circuits.

Register the AutoNAT server handler (libp2pautonat/1.0.0).

The dial-back deliberately bypasses the connection pool: reusing the requester's existing connection would always report success. Instead a fresh transport dial + upgrade verifies both reachability and identity, and the probe connection is closed immediately (go-libp2p uses a separate dialer host for the same reason).

Register the Circuit Relay v2 hop handler (libp2pcircuitrelay0.2.0/hop): serve RESERVE and CONNECT requests.

Register the Circuit Relay v2 stop handler (libp2pcircuitrelay0.2.0/stop): accept inbound relayed streams and hand them to the application callback.

Register the DCUtR handler (libp2pdcutr).

Answers the CONNECT/SYNC exchange with our listen addresses and dials the initiator's addresses through the Switch for the hole punch.

Mutable relay server state.

Relay server configuration.

Default relay configuration.

Create new relay state from configuration.

A GossipSub node: Router + Switch integration.

GossipSub router parameters.

Default GossipSub parameters per spec.

Create a new GossipSub node with a Router wired to the Switch.

The Router's gsSendRPC callback opens/reuses outbound streams to peers via the Switch's connection pool.

Start the GossipSub node: register stream handler, notifier, and start heartbeat.

Stop the GossipSub node: cancel heartbeat and unregister handler.

Subscribe to a topic.

Unsubscribe from a topic.

Publish a message to a topic (signed with the Switch's identity key).