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.

Direction of a connection relative to this node. Defined here to avoid circular dependency with Switch.Types.

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

Subscribe independently to future per-connection events (no replay). Drop the channel to unsubscribe; unread channels retain queued events. Shutdown neither waits for subscribers nor signals end-of-stream.

Events emitted by the Switch for observability.

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, run the disconnect notifiers, 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, and the notifiers run once.

Notifiers run synchronously, after the pool removal has committed and before the muxer is closed, so a notifier that asks whether the peer still has a live connection (Circuit Relay v2 reservation cleanup) never sees the connection being torn down. Each is isolated so a failing notifier cannot abort the teardown.

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.

The handler owns the stream, matching go-libp2p: it must close or reset on every exit path. Dispatch does not close on return, because some handlers (Circuit Relay STOP) hand the stream off as a connection. One-shot protocols (Identify, AutoNAT) close after the single exchange; long-lived protocols (DHT, Ping, GossipSub) close when the remote half-closes or the session ends.

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.

Construct a QUIC transport using the node's long-term identity key.

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).

Identify is a one-shot exchange, so the stream is closed on every exit path — success, negotiation refusal, decode failure, timeout and exception alike. A caller that runs this per connection would otherwise leak a half-open stream per connection. The whole exchange is bounded by identifyTimeoutMicros: a peer that negotiates and then never answers must not pin a stream and a thread forever.

Run Identify against a freshly established connection and record the result in the peer store (specs/identify).

This is what makes a peer's advertised addresses and protocols known to us: without it swPeerStore only ever fills from an inbound push, so nothing is known about a peer we dialled or accepted. go-libp2p drives its IDService from the swarm's Connected notification for the same reason.

Failure is returned rather than thrown: the connection stays usable, and no peer store entry is created. There is no retry — a peer that does not answer Identify now will be picked up by a later push, if it sends one.

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.

Register the perf handler on the Switch.

Run one perf measurement against a connected peer: open a stream, negotiate perf1.0.0, run the exchange, and release the stream.

Perf protocol ID.

Successful perf exchange result.

Perf error types.

Top-level DHT node state.

Server or client mode.

Validator interface for record validation.

valValidate checks that a value is well-formed for its key and returns an error for records that must not be stored or served. valSelect picks the index of the best value among conflicting candidates for the same key (used for GET_VALUE conflict resolution).

The default validator set: pk records only. Additional namespaces can be registered by building a custom namespacedValidator and storing it in the DHT node.

DHT record (protobuf Message.Record).

field 2

A provider record for content routing.

A single entry in a k-bucket.

Create a new DHT node with the outbound sender wired to the Switch.

Registers a disconnect notifier so a cached session is dropped when the peer's last connection closes (#279).

Stop the DHT node: drop cached sessions and deregister the disconnect notifier so a stopped node cannot keep a callback alive on the Switch.

Register the DHT handler on the Switch.

Per specs/kad-dht (client and server mode), nodes operating in client mode do not offer the Kademlia protocol identifier for incoming streams, so this is a no-op for DHTClient nodes: they keep issuing outbound queries via dhtSendRequest but never serve inbound RPC.

Bootstrap the DHT: insert seeds, self-lookup, refresh every non-empty bucket.

Startup is explicit: call bootstrap or startBootstrap. newDHTNode does not start a loop, matching go-libp2p's IpfsDHT.Bootstrap. The whole run is bounded by dhtQueryTimeout (default 10s).

Start a periodic bootstrap loop. Runs one refresh immediately, then every intervalMicros. Cancelled by stopDHTNode.

Announce that the local node provides a given content key.

Performs an iterative FIND_NODE lookup for the content key, then sends ADD_PROVIDER messages to the k closest peers found. The local peer's listen addresses are included so remote peers can dial back.

Store a value in the DHT under the given key.

Performs an iterative FIND_NODE lookup for the key, then sends PUT_VALUE messages to the k closest peers. Also stores the value locally. The value is validated using the node's configured validator; if validation fails, the function returns Left with an error message.

Retrieve a value from the DHT.

Convenience wrapper around iterativeGetValue.

Find providers for a content key.

Convenience wrapper around iterativeGetProviders.

Find the closest known peers to a target peer ID.

Convenience wrapper around iterativeFindNode.

Configuration for the NAT traversal handlers.

Default NAT configuration: default relay limits and refresh tuning.

Register the NAT protocol handlers and the circuit client transport on the Switch.

Returns the relay server state (so callers can inspect reservations/circuits) and the circuit client state, which ties transportListen on a p2p-circuit address to the inbound stop streams that arrive over the connection to that relay.

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).

After the CONNECT/OK exchange the stop stream *is* the relayed connection (specsrelaycircuit-v2), so it is handed to the circuit transport's listener for the relay it arrived over. The Switch then upgrades it like any other inbound raw connection.

The relay's advertised limit is not yet enforced (issue #269).

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.

Per-Switch state shared between the circuit transport and the stop protocol handler: one inbound queue per relay we hold a reservation on.

The Circuit Relay v2 client transport.

Captures the Switch so it can dial the relay; register it after newSwitch with addTransport.

Create empty circuit state.

Tuning for client-side reservation refresh (specsrelaycircuit-v2: "the reservation becomes invalid after this time and it's the responsibility of the client to refresh").

Values follow go-libp2p's autorelay relay finder (rsvpExpirationSlack / rsvpRefreshInterval): refresh once the reservation is within rrcMargin of its expiry, checked every rrcPollInterval.

Default refresh tuning: a 2 minute margin, checked every minute.

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).