rust-libp2p

Scope

This skill is specifically for the Rust implementation of libp2p, not js-libp2p or go-libp2p.

Use the general libp2p skill for protocol concepts like peer IDs, multiaddrs, relays, and DHTs. Use this skill for Rust crate names, feature flags, APIs, module layout, code patterns, and implementation-specific gotchas.

When answering, prefer Rust API names and examples:

• libp2p::SwarmBuilder, not createLibp2p.
• #[derive(NetworkBehaviour)] from libp2p::swarm, not JavaScript service configuration objects.
• Behaviour, Config, and Event types from protocol crates.
• SwarmEvent loops, not callback/event-emitter style code.
• Cargo feature flags, because the root crate compiles almost nothing unless the right features are enabled. Humanity invented optional compilation and then made everyone debug missing imports. Naturally.

Version and freshness notes

rust-libp2p evolves quickly. Before giving exact API answers, check the current crate/source when possible.

Known source baseline used for this skill:

• Current published docs on docs.rs show libp2p 0.56.0.
• GitHub master metadata has moved to libp2p 0.56.1.
• The workspace MSRV is Rust 1.83.0, edition 2021.
• The root libp2p crate has no default features in 0.56.0; users must enable features explicitly.
• DeepWiki is useful for architecture, but source and rustdoc win when they disagree.

Use version = "0.56" in examples unless the user asks for an exact pinned version. For production answers, say “verify against the current libp2p/Cargo.toml and docs.rs.”

Mental model

A rust-libp2p node is built from these layers:

1. Identity: libp2p_identity::Keypair and PeerId.
2. Transport: how bytes move, such as TCP, QUIC, WebSocket, UDS, memory, or WASM transports.
3. Security upgrade: usually Noise or TLS for TCP/WebSocket. QUIC already includes TLS 1.3.
4. Stream multiplexer: usually Yamux for TCP/WebSocket. QUIC, WebTransport, and WebRTC have native multiplexing.
5. Protocol behaviour: NetworkBehaviour implementations such as ping::Behaviour, kad::Behaviour, gossipsub::Behaviour, request_response::Behaviour, identify::Behaviour, relay::client::Behaviour.
6. Swarm: the runtime orchestrator that drives transports, connection pools, behaviours, handlers, and events.

Rust-libp2p separates “how to send bytes” from “what bytes to send”:

• Transport handles dialing, listening, and producing connections.
• NetworkBehaviour decides protocol actions, emits commands to the swarm, and produces application-visible events.
• ConnectionHandler owns per-connection state and substream negotiation for a behaviour.
• Swarm<B> ties the transport to a root behaviour B. It must be polled as a stream to make progress.

Root crate and features

The root crate is libp2p. It re-exports many implementation crates behind Cargo features.

A minimal native Ping example needs:

[dependencies]
libp2p = { version = "0.56", features = ["noise", "ping", "tcp", "tokio", "yamux"] }
futures = "0.3"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
tracing-subscriber = { version = "0.3", features = ["env-filter"] }

Common feature flags:

The full feature exists, but do not recommend it blindly. It increases build time and target incompatibility risk. Use feature-specific examples unless the user explicitly wants “everything.”

Workspace and implementation crates

The repository is a monorepo with core, transports, protocols, muxers, examples, and utilities.

Important crates and paths:

SwarmBuilder API

Prefer SwarmBuilder for new examples. It is the high-level builder exported from libp2p.

Canonical native chain:

let mut swarm = libp2p::SwarmBuilder::with_new_identity()
    .with_tokio()
    .with_tcp(
        libp2p::tcp::Config::default(),
        libp2p::noise::Config::new,
        libp2p::yamux::Config::default,
    )?
    .with_behaviour(|key| {
        let peer_id = key.public().to_peer_id();
        libp2p::ping::Behaviour::default()
    })?
    .build();

Important builder methods:

with_tcp, with_websocket, and with_relay_client accept function items or tuples of function items for upgrades:

.with_tcp(
    tcp::Config::default(),
    (tls::Config::new, noise::Config::new),
    yamux::Config::default,
)?

Use this tuple form when you want fallback negotiation between security upgrades. The same pattern applies to multiplexer upgrades, though Yamux alone is the recommended default for new TCP/WebSocket stacks.

When .with_relay_client(...) is used, the .with_behaviour(...) closure receives (key, relay_behaviour) and the relay behaviour must be included in the root behaviour:

#[derive(libp2p::swarm::NetworkBehaviour)]
struct Behaviour {
    relay: libp2p::relay::client::Behaviour,
    ping: libp2p::ping::Behaviour,
}

let swarm = libp2p::SwarmBuilder::with_new_identity()
    .with_tokio()
    .with_tcp(tcp::Config::default(), noise::Config::new, yamux::Config::default)?
    .with_relay_client(noise::Config::new, yamux::Config::default)?
    .with_behaviour(|_key, relay| Behaviour {
        relay,
        ping: ping::Behaviour::default(),
    })?
    .build();

Without relay client, the behaviour closure receives only &Keypair.

Swarm API

Swarm<B> contains network state and a behaviour. It must be continuously polled as a Stream.

Useful methods:

Event loop skeleton:

use futures::StreamExt;
use libp2p::swarm::SwarmEvent;

loop {
    match swarm.select_next_some().await {
        SwarmEvent::NewListenAddr { address, .. } => {
            println!("Listening on {address}");
        }
        SwarmEvent::Behaviour(event) => {
            println!("Behaviour event: {event:?}");
        }
        SwarmEvent::ConnectionEstablished { peer_id, .. } => {
            println!("Connected to {peer_id}");
        }
        SwarmEvent::ConnectionClosed { peer_id, cause, .. } => {
            println!("Connection to {peer_id} closed: {cause:?}");
        }
        _ => {}
    }
}

If the swarm is not polled, nothing progresses. Not dialing, not listening, not protocol negotiation. A perfect machine, doing absolutely nothing, as requested by an unpolled future.

NetworkBehaviour

Every protocol crate exposes a Behaviour that implements NetworkBehaviour. Compose several behaviours with the derive macro:

use libp2p::{
    gossipsub, identify, kad, mdns, ping,
    swarm::NetworkBehaviour,
};

#[derive(NetworkBehaviour)]
struct Behaviour {
    ping: ping::Behaviour,
    identify: identify::Behaviour,
    kad: kad::Behaviour<kad::store::MemoryStore>,
    gossipsub: gossipsub::Behaviour,
    mdns: mdns::tokio::Behaviour,
}

Enable the macros feature for the derive macro:

libp2p = { version = "0.56", features = ["macros", "..."] }

Manual NetworkBehaviour implementations are advanced. They must provide:

• Associated type ConnectionHandler.
• Associated type ToSwarm.
• handle_established_inbound_connection.
• handle_established_outbound_connection.
• on_swarm_event.
• on_connection_handler_event.
• poll.

Use manual implementations only when writing a custom protocol crate or advanced behaviour. For applications, compose existing behaviours with the derive macro.

ConnectionHandler

ConnectionHandler is per-connection protocol state. Most application authors do not implement it directly.

Use it when implementing a custom protocol that needs to:

• Negotiate inbound or outbound substreams.
• Run protocol-specific state for each connection.
• Receive commands from a behaviour.
• Emit handler events back to the behaviour.

Most built-in protocols follow this pattern:

• Behaviour: global protocol state, query state, peer tables, application events.
• Handler: per-connection substream negotiation and I/O.
• Config: tunable settings.
• Event: application-facing events.

Identity and PeerId

Common identity patterns:

let keypair = libp2p::identity::Keypair::generate_ed25519();
let peer_id = keypair.public().to_peer_id();

Use SwarmBuilder::with_new_identity() for throwaway/test nodes and SwarmBuilder::with_existing_identity(keypair) when stable peer identity matters.

Enable key features as needed:

• ed25519: common default for new keys.
• rsa: useful for IPFS interoperability because many IPFS peers still use RSA identities.
• ecdsa, secp256k1: for networks that standardize on those key types.

Multiaddr

Rust examples usually parse a multiaddr from a string:

let addr: libp2p::Multiaddr = "/ip4/0.0.0.0/tcp/0".parse()?;
swarm.listen_on(addr)?;

Common native listen addresses:

/ip4/0.0.0.0/tcp/0
/ip6/::/tcp/0
/ip4/0.0.0.0/udp/0/quic-v1

Dialing usually requires the remote PeerId to appear in the multiaddr or to be known through peer store/behaviour state:

/ip4/203.0.113.10/tcp/4001/p2p/<peer-id>
/dnsaddr/bootstrap.libp2p.io/p2p/<peer-id>

Relayed address shape:

/ip4/<relay-ip>/tcp/<relay-port>/p2p/<relay-peer-id>/p2p-circuit/p2p/<dest-peer-id>

Transport choices

QUIC does not need .with_tcp(... noise ... yamux ...) style upgrades because QUIC already provides encryption and multiplexing. TCP and WebSocket do need security and mux upgrades.

The builder’s native transport methods are gated out on wasm32. Browser builds use the *-websys transports and wasm-bindgen.

Minimal Ping node

use std::{error::Error, time::Duration};

use futures::StreamExt;
use libp2p::{noise, ping, swarm::SwarmEvent, tcp, yamux, Multiaddr};

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let mut swarm = libp2p::SwarmBuilder::with_new_identity()
        .with_tokio()
        .with_tcp(
            tcp::Config::default(),
            noise::Config::new,
            yamux::Config::default,
        )?
        .with_behaviour(|_| ping::Behaviour::default())?
        .with_swarm_config(|cfg| cfg.with_idle_connection_timeout(Duration::from_secs(60)))
        .build();

    swarm.listen_on("/ip4/0.0.0.0/tcp/0".parse()?)?;

    if let Some(addr) = std::env::args().nth(1) {
        let remote: Multiaddr = addr.parse()?;
        swarm.dial(remote)?;
    }

    loop {
        match swarm.select_next_some().await {
            SwarmEvent::NewListenAddr { address, .. } => {
                println!("Listening on {address}");
            }
            SwarmEvent::Behaviour(event) => {
                println!("{event:?}");
            }
            _ => {}
        }
    }
}

Composite behaviour template

Use this pattern for real applications that need discovery plus messaging:

use std::{error::Error, time::Duration};

use futures::StreamExt;
use libp2p::{
    gossipsub, identify, kad, noise, ping,
    swarm::{NetworkBehaviour, SwarmEvent},
    tcp, yamux,
};

#[derive(NetworkBehaviour)]
struct Behaviour {
    identify: identify::Behaviour,
    kad: kad::Behaviour<kad::store::MemoryStore>,
    gossipsub: gossipsub::Behaviour,
    ping: ping::Behaviour,
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let mut swarm = libp2p::SwarmBuilder::with_new_identity()
        .with_tokio()
        .with_tcp(
            tcp::Config::default(),
            noise::Config::new,
            yamux::Config::default,
        )?
        .with_behaviour(|key| {
            let peer_id = key.public().to_peer_id();

            let identify = identify::Behaviour::new(identify::Config::new(
                "/myapp/1.0.0".to_string(),
                key.public(),
            ));

            let store = kad::store::MemoryStore::new(peer_id);
            let kad = kad::Behaviour::new(peer_id, store);

            let gossipsub = gossipsub::Behaviour::new(
                gossipsub::MessageAuthenticity::Signed(key.clone()),
                gossipsub::Config::default(),
            )?;

            Ok(Behaviour {
                identify,
                kad,
                gossipsub,
                ping: ping::Behaviour::default(),
            })
        })?
        .with_swarm_config(|cfg| cfg.with_idle_connection_timeout(Duration::from_secs(60)))
        .build();

    swarm.listen_on("/ip4/0.0.0.0/tcp/0".parse()?)?;

    loop {
        match swarm.select_next_some().await {
            SwarmEvent::NewListenAddr { address, .. } => {
                println!("Listening on {address}");
            }
            SwarmEvent::Behaviour(event) => {
                println!("{event:?}");
            }
            _ => {}
        }
    }
}

For this template, enable:

libp2p = { version = "0.56", features = [
  "gossipsub", "identify", "kad", "macros", "noise", "ping", "tcp", "tokio", "yamux"
] }

Identify

identify::Behaviour exchanges Info messages on established connections. It reports listen addresses, protocol support, observed address, and public key information.

Important Rust-specific discrepancy: Identify is not treated as core. Other behaviours do not automatically get Identify data. You must manually hook Identify events into protocols that need address information.

Kademlia integration pattern:

match event {
    SwarmEvent::Behaviour(BehaviourEvent::Identify(identify::Event::Received {
        peer_id,
        info,
        ..
    })) => {
        for addr in info.listen_addrs {
            swarm.behaviour_mut().kad.add_address(&peer_id, addr);
        }
    }
    _ => {}
}

The exact generated BehaviourEvent enum name depends on the derive macro output and the containing behaviour name. Adjust match paths to the actual compiler-generated event type.

Kademlia DHT

Use kad::Behaviour for:

• Peer discovery and routing.
• Provider records: “peer X can provide content key Y.”
• Record get/put operations.
• Interop with IPFS Kademlia when configured for the IPFS protocol name.

Common setup:

let local_peer_id = key.public().to_peer_id();
let store = kad::store::MemoryStore::new(local_peer_id);
let behaviour = kad::Behaviour::new(local_peer_id, store);

Custom config example, useful for IPFS DHT interop:

use libp2p::swarm::StreamProtocol;

const IPFS_PROTO_NAME: StreamProtocol = StreamProtocol::new("/ipfs/kad/1.0.0");

let mut cfg = kad::Config::new(IPFS_PROTO_NAME);
cfg.set_query_timeout(std::time::Duration::from_secs(5 * 60));

let store = kad::store::MemoryStore::new(local_peer_id);
let kad = kad::Behaviour::with_config(local_peer_id, store, cfg);

Practical Kademlia calls:

swarm.behaviour_mut().kad.bootstrap()?;
swarm.behaviour_mut().kad.add_address(&peer_id, addr);
swarm.behaviour_mut().kad.get_closest_peers(peer_id);
swarm.behaviour_mut().kad.get_providers(key);
swarm.behaviour_mut().kad.start_providing(key)?;

Gotchas:

• Identify is not automatic. Hook identify::Event::Received to kad.add_address.
• Without Identify or another peer discovery source, Kad may not discover beyond bootnodes.
• For provider records/content routing, make sure the node is configured for the intended mode and reachable enough for the network’s expectations.
• IPFS public DHT interop often needs RSA identity support and /ipfs/kad/1.0.0.

Gossipsub

Use gossipsub::Behaviour for pub/sub.

Common setup:

let behaviour = gossipsub::Behaviour::new(
    gossipsub::MessageAuthenticity::Signed(key.clone()),
    gossipsub::Config::default(),
)?;

Topic example:

let topic = gossipsub::IdentTopic::new("chat");
swarm.behaviour_mut().gossipsub.subscribe(&topic)?;
swarm.behaviour_mut().gossipsub.publish(topic, b"hello".to_vec())?;

Handle messages:

match event {
    gossipsub::Event::Message {
        propagation_source,
        message_id,
        message,
    } => {
        println!(
            "Got message {message_id} from {propagation_source}: {:?}",
            String::from_utf8_lossy(&message.data)
        );
    }
    _ => {}
}

Gotchas:

• Gossipsub does not do peer discovery. Combine it with mDNS, Kademlia, Rendezvous, bootstrap peers, or explicit peer dialing.
• Topic hashing behavior is configurable. Rust defaults differ from some implementations when hash_topics is enabled.
• For production networks, configure validation mode and peer scoring deliberately. Do not leave validation and scoring as an afterthought unless the application is a toy, which, fair enough, many are.

Request-response

Use request_response::Behaviour for request/response protocols where each request is sent over a new substream.

Options:

• Implement request_response::Codec yourself.
• Use predefined request_response::cbor::Behaviour if request/response types implement serde and cbor feature is enabled.
• Use predefined request_response::json::Behaviour if json feature is enabled.

Core API:

let request_id = swarm
    .behaviour_mut()
    .request_response
    .send_request(&peer_id, request);

swarm
    .behaviour_mut()
    .request_response
    .send_response(channel, response)?;

Events arrive as request_response::Event::Message with request_response::Message::{Request, Response}.

Use request-response for:

• RPC-like interactions.
• File chunk fetching.
• Metadata queries.
• One-shot application messages where pub/sub is the wrong tool.

Do not use it for long-lived streaming. Use custom streams or a protocol built for streaming.

Ping

ping::Behaviour measures liveness/RTT and emits ping events. It is useful for diagnostics but does not keep a connection alive forever by itself in a minimal node.

The default idle connection timeout can close otherwise-unused connections. Set a larger idle timeout in examples where Ping is the only active behaviour:

.with_swarm_config(|cfg| {
    cfg.with_idle_connection_timeout(std::time::Duration::from_secs(60))
})

The upstream tutorial uses a very large timeout so users can observe pings indefinitely. Do not blindly copy that into production.

mDNS

Use mdns::tokio::Behaviour for local network discovery on native Tokio builds.

Typical pattern:

• Enable mdns, tokio, and macros.
• Compose mdns::tokio::Behaviour into your root behaviour.
• On mdns::Event::Discovered, add discovered peers to the relevant behaviour, for example gossipsub.add_explicit_peer or kad.add_address.
• On mdns::Event::Expired, remove explicit peers if appropriate.

mDNS is LAN-only. It does not discover peers across the internet.

Rendezvous

Use rendezvous for peer registration/discovery around a rendezvous server. It is useful when:

• You control rendezvous points.
• Peers cannot rely on global DHT discovery.
• You want application-scoped discovery.

Rendezvous complements Kademlia or can replace it in controlled networks.

Relay, AutoNAT, DCUtR, UPnP

rust-libp2p has a NAT traversal suite:

Relay address shape:

/ip4/<relay-ip>/tcp/<relay-port>/p2p/<relay-peer-id>/p2p-circuit/p2p/<dest-peer-id>

Relay client setup uses with_relay_client(...) and requires embedding the relay client behaviour in your root behaviour.

DCUtR generally requires:

• Relay connectivity first.
• Identify, so peers can exchange observed/listen addresses.
• A relay client behaviour.
• Direct transports configured, commonly TCP and/or QUIC.
• Patience with NAT reality, the universe’s least charming firewall ruleset.

UPnP is native-only and only helps when the local router supports it. It is not available to browsers.

Metrics and observability

Enable metrics to collect protocol/swarm metrics.

Common options:

• with_bandwidth_metrics(&mut registry) wraps the transport with bandwidth metrics.
• libp2p-metrics records protocol and swarm events and exposes OpenMetrics-compatible metrics via prometheus-client.

Use metrics for production services, relay nodes, and debugging peer churn.

Connection limits and allow/block lists

The root crate re-exports:

• allow_block_list: manage allow/block lists for peers.
• connection_limits: connection count/limit utilities.
• memory_connection_limits: memory-aware limits on native builds.

Use these when building public-facing nodes, relays, or high-churn DHT/pubsub services.

Browser and WASM notes

Rust-libp2p has WASM/browser transports behind *-websys feature flags:

• webrtc-websys
• websocket-websys
• webtransport-websys
• wasm-bindgen

Do not use native tcp, dns, quic, websocket, uds, or upnp builder paths on wasm32; they are target-gated out. Browser networking has platform constraints, certificate constraints, and event-loop constraints. Treat browser examples separately from native Tokio examples.

For browser-focused libp2p answers, cross-check the current WASM examples and transport crates. The Rust WASM implementation is not a drop-in translation of js-libp2p config.

Source layout navigation

When source-checking:

• Root re-exports and feature gates: libp2p/src/lib.rs, libp2p/Cargo.toml.
• Builder: libp2p/src/builder.rs and libp2p/src/builder/phase/*.rs.
• Swarm: swarm/src/lib.rs.
• Behaviour trait: swarm/src/behaviour.rs.
• Handler trait: swarm/src/handler.rs.
• Connection pool: swarm/src/connection/pool.rs.
• Transports: transports/*/src/lib.rs.
• Protocols: protocols/*/src/lib.rs.
• Examples: examples/*.
• Ping tutorial: libp2p/src/tutorials/ping.rs.

Example applications in the repo

Use these examples as source-backed patterns:

Common mistakes

• Forgetting Cargo features, then wondering why modules do not exist.
• Using libp2p::NetworkBehaviour instead of libp2p::swarm::NetworkBehaviour for the derive macro.
• Forgetting the macros feature for #[derive(NetworkBehaviour)].
• Not polling the Swarm.
• Assuming Identify automatically feeds Kademlia.
• Assuming Gossipsub discovers peers by itself.
• Adding QUIC and then also trying to wrap it in Noise/Yamux.
• Using browser transports in native examples, or native transports in WASM examples.
• Using mplex in new code when Yamux is the recommended muxer.
• Relying on Ping to keep a connection open without adjusting idle timeout or having an actual application protocol.
• Advertising private or unroutable addresses as external addresses.
• Assuming relay traffic is invisible to the relay. Payloads are end-to-end encrypted, but relay peer IDs, timing, and connection metadata are observable.

Answering checklist

When answering rust-libp2p questions:

1. Identify target environment: native Tokio, WASM/browser, tests, or embedded/server.
2. Identify required protocols: discovery, pub/sub, request-response, DHT, NAT traversal, raw streams.
3. List the Cargo features required.
4. Prefer SwarmBuilder unless the user is writing a custom transport/protocol.
5. Use #[derive(NetworkBehaviour)] for app-level composition.
6. Include the event loop.
7. Mention Identify wiring when using Kademlia or address discovery.
8. Mention discovery requirements when using Gossipsub.
9. For NAT traversal, include relay, Identify, AutoNAT/DCUtR, and direct transports.
10. Warn about target-gated transports and version/API drift.
11. For exact APIs, cite or inspect docs.rs/source for the current version.

Quick recipes

Native TCP + Noise + Yamux

Features:

["tcp", "tokio", "noise", "yamux"]

Builder:

.with_tokio()
.with_tcp(tcp::Config::default(), noise::Config::new, yamux::Config::default)?

Native TCP + QUIC

Features:

["tcp", "quic", "tokio", "noise", "yamux"]

Builder:

.with_tokio()
.with_tcp(tcp::Config::default(), noise::Config::new, yamux::Config::default)?
.with_quic()

TCP + DNS + WebSocket

Features:

["tcp", "dns", "websocket", "tokio", "noise", "yamux"]

Builder:

.with_tokio()
.with_tcp(tcp::Config::default(), noise::Config::new, yamux::Config::default)?
.with_dns()?
.with_websocket(noise::Config::new, yamux::Config::default).await?

DHT + Identify

Features:

["kad", "identify", "macros", "tcp", "tokio", "noise", "yamux"]

Pattern:

• Compose both behaviours.
• On Identify received events, call kad.add_address(&peer_id, addr) for listen addresses.
• Add bootstrap peer addresses explicitly.
• Call kad.bootstrap() after bootstrap peers are in the routing table.

Pub/sub

Features:

["gossipsub", "identify", "mdns", "macros", "tcp", "tokio", "noise", "yamux"]

Pattern:

• Compose Gossipsub with mDNS and/or Kademlia/Rendezvous.
• Subscribe to topics.
• Add explicit peers or rely on discovered/dialed peers.
• Configure validation and scoring for production.

Request/response with CBOR

Features:

["request-response", "cbor", "macros", "tcp", "tokio", "noise", "yamux"]

Pattern:

• Define serde request and response types.
• Use request_response::cbor::Behaviour.
• Send with send_request.
• Respond with send_response using the response channel from inbound request events.

Relay client

Features:

["relay", "macros", "tcp", "tokio", "noise", "yamux"]

Pattern:

• Add .with_relay_client(...).
• Include relay behaviour in the root behaviour.
• Listen or dial relayed multiaddrs containing /p2p-circuit.
• Add Identify and DCUtR for hole punching.

Reference links

• DeepWiki rust-libp2p: https://deepwiki.com/libp2p/rust-libp2p
• GitHub repository: https://github.com/libp2p/rust-libp2p
• docs.rs libp2p: https://docs.rs/libp2p/latest/libp2p/
• crates.io libp2p: https://crates.io/crates/libp2p
• Official libp2p docs: https://docs.libp2p.io/

Source: chanderlud/telepathy — distributed by TomeVault.