--- name: dart-libp2p-host description: Use when creating or configuring a dart_libp2p host in Dart (package:dart_libp2p, Libp2p.new_, Config): identity keys, UDX/TCP transports, Noise, Yamux, listen addresses, connect, peerstore, identify, ping, event bus, resource limits, shutdown, tests and go-libp2p interop. triggers: dart_libp2p, Libp2p.new_, BasicHost, UDXTransport, TCPTransport, NoiseSecurity, YamuxSession, MultiplexerConfig, ConnectionManager, generateEd25519KeyPair, AddrInfo, PingService, EvtPeerConnectednessChanged, ConfigurableLimiter, libp2p host --- # dart_libp2p host ## What it is `dart_libp2p` is a Dart port of the libp2p stack: a `Host` with a peer ID, transports (UDX over UDP, TCP), Noise security, Yamux multiplexing, Identify, Ping, a peerstore, an event bus and a resource manager. It interoperates with go-libp2p over TCP (and over UDX with peers that carry go-udx). This skill covers building, running and closing a host. Use another skill for: your own wire protocol on top of the host (`dart-libp2p-custom-protocol`), relays, NAT, hole punching and mDNS (`dart-libp2p-nat-relay`), GossipSub (`dart-libp2p-gossipsub`), the DHT (`dart-libp2p-kad-dht`), WebRTC or BLE transports (`dart-libp2p-webrtc`, `dart-libp2p-ble`). ## Install ```yaml dependencies: dart_libp2p: ^4.12.0 # Only if you import package:dart_udx yourself (e.g. to share a UDX instance): # dart_udx: ^4.3.0 ``` Dart SDK `^3.5.0`. Imports used below: ```dart import 'package:dart_libp2p/dart_libp2p.dart' hide Option; // Host, MultiAddr, AddrInfo, PeerId, Context, keys, events import 'package:dart_libp2p/config/config.dart'; // Libp2p, Config, Option import 'package:dart_libp2p/p2p/transport/udx_transport.dart'; import 'package:dart_libp2p/p2p/transport/tcp_transport.dart'; import 'package:dart_libp2p/p2p/transport/connection_manager.dart'; import 'package:dart_libp2p/p2p/security/noise/noise_protocol.dart'; // NoiseSecurity (optional: default) import 'package:dart_libp2p/p2p/protocol/ping/ping.dart'; // PingService import 'package:dart_libp2p/p2p/host/basic/basic_host.dart'; // BasicHost extras ``` The barrel exports a routing `Option` typedef that clashes with the config `Option`; hide it (as above) or import `config.dart` with a prefix. ## Core workflow ### Minimal host ```dart Future createHost({required KeyPair identity, int port = 0}) async { final connManager = ConnectionManager(); // share it with the transports final host = await Libp2p.new_([ Libp2p.identity(identity), Libp2p.connManager(connManager), Libp2p.transport(UDXTransport(connManager: connManager)), Libp2p.transport(TCPTransport(connManager: connManager)), // no resourceManager: uses the host's Libp2p.listenAddrs([ MultiAddr('/ip4/0.0.0.0/udp/$port/udx'), MultiAddr('/ip4/0.0.0.0/tcp/$port'), ]), Libp2p.userAgent('my-app/1.0.0'), Libp2p.identifyUserAgent('my-app/1.0.0'), // Noise and Yamux (/yamux/1.0.0) are added by default. ]); await host.start(); // Libp2p.new_ does NOT listen; start() does. return host; } void main() async { final a = await createHost(identity: await generateEd25519KeyPair()); final b = await createHost(identity: await generateEd25519KeyPair()); // Dial b by its real listen addresses (see Gotchas: host.addrs drops loopback). await a.connect(AddrInfo(b.id, b.network.listenAddresses)); final rtt = await PingService(a).ping(b.id).first; print('rtt ${rtt.rtt} error ${rtt.error}'); await a.close(); await b.close(); // the process exits once every host is closed } ``` ### Persist the identity The peer ID comes from the key. A node that others dial by `/p2p/` (a relay, a bootstrap node) must keep its key. ```dart // Save: protobuf bytes, the format go-libp2p's crypto.MarshalPrivateKey writes. final bytes = keyPair.privateKey.marshal(); // Load: final priv = await Ed25519PrivateKey.unmarshal(bytes); final loaded = KeyPair(priv.publicKey, priv); // Or keep the 32-byte seed (what the internet_chat demo does): final seed = keyPair.privateKey.raw; // Ed25519 seed final again = await generateEd25519KeyPairFromSeed(seed); ``` Store the file with mode 600. Other key types: `generateRsaKeyPair()`, `generateEcdsaKeyPair()` (P-256); Ed25519 is the default and the cheapest. ### Addresses to hand out ```dart // What other peers should dial (filtered by the AddrsFactory, see Gotchas): for (final a in host.addrs) print('$a/p2p/${host.id.toBase58()}'); // Parse one back: final info = AddrInfo.fromMultiaddr(MultiAddr('/ip4/203.0.113.7/udp/4001/udx/p2p/12D3KooW...')); await host.connect(info); ``` A server whose interface address is private (cloud VM) must announce its public address itself: ```dart Libp2p.addrsFactory((addrs) => [ ...addrs.where((a) => !a.isLoopback() && a.valueForProtocol('ip4') != '0.0.0.0' && a.valueForProtocol('ip6') != '::'), MultiAddr('/ip4/203.0.113.7/udp/4001/udx'), MultiAddr('/ip4/203.0.113.7/tcp/4001'), ]), ``` ### Peerstore and Identify Identify runs on every new connection, in both directions, and fills the peerstore. `connect()` returns after Identify. ```dart final protos = await host.peerStore.protoBook.getProtocols(peer); final addrs = await host.peerStore.addrBook.addrs(peer); final key = await host.peerStore.keyBook.pubKey(peer); final first = await host.peerStore.protoBook.firstSupportedProtocol(peer, ['/app/2.0.0', '/app/1.0.0']); // Bootstrap address that never expires: await host.peerStore.addrBook.addAddrs(peer, addrs, AddressTTL.permanentAddrTTL); ``` `connect()` stores the given addresses with a 5-minute TTL. `newStream()` dials from the peerstore, so it works only for a connected peer or one whose addresses are stored. ### Connections ```dart host.network.connectedness(peer) == Connectedness.connected; host.network.peers; // connected peer IDs host.network.connsToPeer(peer); // List conn.remoteMultiaddr.hasProtocol('p2p-circuit'); // relayed? await host.network.closePeer(peer); ``` ### Event bus ```dart final sub = host.eventBus.subscribe([EvtPeerConnectednessChanged, EvtPeerIdentificationCompleted]); sub.stream.listen((dynamic e) { if (e is EvtPeerConnectednessChanged) print('${e.peer} ${e.connectedness}'); if (e is EvtPeerIdentificationCompleted) print('${e.peer} speaks ${e.protocols}'); }); // ... later await sub.close(); ``` `subscribe` is synchronous and returns a `Subscription`; `emitter(Type)` is async and its `Emitter` must be closed. Other events: `EvtLocalReachabilityChanged`, `EvtLocalAddressesUpdated`, `EvtLocalProtocolsUpdated`, `EvtPeerProtocolsUpdated`, `EvtPeerIdentificationFailed`, `EvtNATDeviceTypeChanged`. `EvtPeerConnectednessChanged` fires on a peer's first connection and when its last one closes. For per-connection callbacks use `host.network.notify(NotifyBundle(...))`. ### Resource limits A host from `Libp2p.new_` has go-libp2p's default limits (1 GiB / 512 FD budget: 256 connections total, 8 per peer, 68 inbound streams per peer and protocol). Over a limit you get `ResourceLimitExceededException`. ```dart import 'package:dart_libp2p/p2p/host/resource_manager/limiter.dart'; // ConfigurableLimiter, LimiterConfig, FixedLimiter import 'package:dart_libp2p/p2p/host/resource_manager/limit.dart'; // BaseLimit Libp2p.resourceLimiter(ConfigurableLimiter( LimiterConfig.scaled(memory: 2 * 1024 * 1024 * 1024, fds: 4096))), // or custom: LimiterConfig(peer: BaseLimit(conns: 4), protocolOverrides: {...}) // no limits: Libp2p.resourceLimiter(FixedLimiter()) // no tracking: Libp2p.resourceManager(NullResourceManager()) await host.network.resourceManager.viewSystem((scope) async => print(scope.stat)); ``` ### Tuning Yamux ```dart Libp2p.muxer('/yamux/1.0.0', (conn, isClient) => YamuxSession( conn as TransportConn, const MultiplexerConfig(maxStreams: 256, keepAliveInterval: Duration(seconds: 15)), isClient)), ``` (`YamuxSession`, `MultiplexerConfig`: `p2p/transport/multiplexing/yamux/session.dart`, `p2p/transport/multiplexing/multiplexer.dart`.) Defaults: 256 KiB frames, 16 MiB max window, keep-alive 10 s, no pong in 30 s closes the session, stream open timeout 10 s. ### Other options worth knowing `Libp2p.dialTimeout` (15 s), `Libp2p.relayDialTimeout` (30 s), `Libp2p.negotiationTimeout` (10 s, multistream on `newStream`), `Libp2p.ping(false)`, `Libp2p.autoNAT(false)`, `Libp2p.autoNATv2Server(false)` (phones), `Libp2p.holePunching(bool)`, `Libp2p.connectionGater(BasicConnGater()..blockPeer(id))` (`p2p/network/conn_gater.dart`), `Libp2p.observedAddrActivationThreshold(n)`. Relay and NAT options: see `dart-libp2p-nat-relay`. ### Shutdown ```dart await host.close(); // stops services, timers, connections, listeners, peerstore ``` Close everything you started on top first (pubsub, DHT, your own timers), then the host. A host cannot be restarted; build a new one. ## Key concepts / API map - `Libp2p.new_(List