Universal libp2p Transport for @suaveplan/network. Composes WebSockets or WebRTC sub-transports with Noise + Yamux, identify + ping + bootstrap + circuit-relay-v2, all wired through an injectable libp2p factory so the package itself never bundles libp2p at module-eval.

Documentation tree

connection — (no submodules)
- connection — (no submodules)
errors — (no submodules)
- errors — (no submodules)
frame — Implements length-prefixed binary framing for envelopes traversing a libp2p stream. Each frame is a 4-byte big-endian l…
peer-message — Defines the wire-format codec for envelopes flowing between libp2p peers. Encoding uses the @suaveplan/serialize Mess…
send — Outbound stream-based envelope shipping over libp2p. Each send opens a new protocol stream, writes a single framed en…
otel — (no submodules)
- otel — (no submodules)
plugin — (no submodules)
- plugin — (no submodules)
streams — (no submodules)
- streams — (no submodules)
transport — (no submodules)
- transport — (no submodules)
types — (no submodules)
- types — (no submodules)

- [connection](./src/connection/connection.md) — _(no submodules)_- [errors](./src/errors/errors.md) — _(no submodules)_- [errors](./src/errors/errors.md) — _(no submodules)_- [frame](./src/messaging/frame.md) — Implements length-prefixed binary framing for envelopes traversing a libp2p stream. Each frame is a 4-byte big-endian l…

peer-message — Defines the wire-format codec for envelopes flowing between libp2p peers. Encoding uses the @suaveplan/serialize Mess…
send — Outbound stream-based envelope shipping over libp2p. Each send opens a new protocol stream, writes a single framed en…
otel — (no submodules)- otel — (no submodules)- plugin — (no submodules)- plugin — (no submodules)- streams — (no submodules)- streams — (no submodules)- transport — (no submodules)- transport — (no submodules)- types — (no submodules)- types — (no submodules)- connection — (no submodules)- errors — (no submodules)- errors — (no submodules)- frame — Implements length-prefixed binary framing for envelopes traversing a libp2p stream. Each frame is a 4-byte big-endian l…
peer-message — Defines the wire-format codec for envelopes flowing between libp2p peers. Encoding uses the @suaveplan/serialize Mess…
send — Outbound stream-based envelope shipping over libp2p. Each send opens a new protocol stream, writes a single framed en…
otel — (no submodules)- otel — (no submodules)- plugin — (no submodules)- plugin — (no submodules)- streams — (no submodules)- streams — (no submodules)- transport — (no submodules)- transport — (no submodules)- types — (no submodules)- types — (no submodules)- connection — (no submodules)- errors — (no submodules)- errors — (no submodules)- frame — Implements length-prefixed binary framing for envelopes traversing a libp2p stream. Each frame is a 4-byte big-endian l…
peer-message — Defines the wire-format codec for envelopes flowing between libp2p peers. Encoding uses the @suaveplan/serialize Mess…
send — Outbound stream-based envelope shipping over libp2p. Each send opens a new protocol stream, writes a single framed en…
otel — (no submodules)- otel — (no submodules)- plugin — (no submodules)- plugin — (no submodules)- streams — (no submodules)- streams — (no submodules)- transport — (no submodules)- transport — (no submodules)- types — (no submodules)- types — (no submodules)- connection — (no submodules)- errors — (no submodules) - errors — (no submodules)- frame — Implements length-prefixed binary framing for envelopes traversing a libp2p stream. Each frame is a 4-byte big-endian l…
peer-message — Defines the wire-format codec for envelopes flowing between libp2p peers. Encoding uses the @suaveplan/serialize Mess…
send — Outbound stream-based envelope shipping over libp2p. Each send opens a new protocol stream, writes a single framed en…
otel — (no submodules) - otel — (no submodules)- plugin — (no submodules) - plugin — (no submodules)- streams — (no submodules) - streams — (no submodules)- transport — (no submodules) - transport — (no submodules)- types — (no submodules) - types — (no submodules)

Install

bun add @suaveplan/network-transport-libp2p

Quick Start

import { Libp2pPlugin, Libp2pTransport } from "@suaveplan/network-transport-libp2p";

const transport = new Libp2pTransport({
    libp2pFactory: async (cfg) => {
        const { createLibp2p } = await import("libp2p");
        const { websockets } = await import("@libp2p/websockets");
        const { noise } = await import("@chainsafe/libp2p-noise");
        const { yamux } = await import("@chainsafe/libp2p-yamux");
        const { bootstrap } = await import("@libp2p/bootstrap");
        const { identify } = await import("@libp2p/identify");
        const { ping } = await import("@libp2p/ping");

        return (await createLibp2p({
            addresses: { listen: cfg.addresses.listen as string[] },
            transports: [websockets()],
            connectionEncryption: [noise()],
            streamMuxers: [yamux()],
            peerDiscovery: [bootstrap({ list: cfg.bootstrap as string[] })],
            services: { identify: identify(), ping: ping() },
            connectionManager: {
                maxConnections: cfg.maxConnections,
                dialTimeout: cfg.dialTimeoutMs,
            },
        })) as unknown as import("@suaveplan/network-transport-libp2p").Libp2pNodeLike;
    },
    bootstrap: ["/dns4/bootstrap.example/tcp/443/wss/p2p/Qm…"],
    subTransport: "websockets",
});

await transport.start();

Sub-Transport Selection

`subTransport`	Default `addresses.listen`	Notes
`"websockets"` (default)	`/ip4/0.0.0.0/tcp/0/ws`	Universal — works in browser and Node.
`"webrtc"`	`/webrtc`	Browser-tier sub-transport; relies on the libp2p `webrtc` module.

TCP and mDNS are deferred to a server-tier sibling package.

Plugin Wrapper

import { Libp2pPlugin } from "@suaveplan/network-transport-libp2p";

const plugin = new Libp2pPlugin({
    libp2pFactory,
    bootstrap: bootstrapList,
});
node.use(plugin);
await node.start();

Security & Hardening

bootstrap is mandatory — empty list rejected at construction with INVALID_OPTIONS. There is no public-bootstrap fallback.
libp2pFactory is mandatory — the package never falls back to a default libp2p constructor; callers control the security posture.
All public boundaries validated by Zod.
11-code structured error registry.
AbortSignal threaded through every async path.
Default frame cap: 1 MiB. Default message timeout: 5 s. Default dial timeout: 10 s.

Observability

Instrument	Type	Attributes
`libp2p.connections_opened_total`	counter	`outcome`
`libp2p.streams_opened_total`	counter	—
`libp2p.bytes_total`	counter	`direction`
`libp2p.dial_ms`	histogram	—
`libp2p.stream_ttfb_ms`	histogram	—
`libp2p.active_peers`	gauge	—

Demo

The 749-line React demo lives in a separate Wave-7 package (@suaveplan/react-network-libp2p-demo) so this package stays React-free.

Module Layout

src/types/ — structural type contracts.
src/errors/ — NET_LIBP2P_CODES + NetLibp2pError.
src/otel/ — counters, histograms, gauges, span helper.
src/messaging/peer-message.md — wire format.
src/messaging/frame.md — length-prefixed framing.
src/messaging/send.md — outbound stream send.
src/streams/ — inbound stream handler + drain.
src/connection/ — node lifecycle.
src/transport/ — Libp2pTransport.
src/plugin/ — Libp2pPlugin.