swift-libp2p

0.2.3

Star

Modern libp2p networking stack for Swift

What's New

0.2.3

2026-06-27T02:22:15Z

Preserve all concurrently opened inbound QUIC streams in LibP2PNode and update SWIM/WebRTC dependency floors.

swift-libp2p

A modern Swift implementation of the libp2p networking stack with wire-protocol compatibility with Go and Rust implementations. Built on Swift Concurrency (async/await, actors) for safe, high-performance peer-to-peer networking. The data plane is moving toward an Embedded-first, [UInt8]/ByteBuffer-currency stance on the embedded branch.

Release status. The released 0.2.0 ships the prior API. The Embedded-first API documented here (LibP2PCore, [UInt8]/ByteBuffer payload paths, DiscoveryPipeline, ConnectionProvider) lives on the unreleased embedded branch (M8 pending) and is not tagged — pin to the branch to use it.

Features

Transport

TCP (SwiftNIO), QUIC (RFC 9000), WebSocket, WebRTC Direct (DTLS + SCTP), WebTransport, Memory (testing)

Security

Noise XX (X25519 + ChaChaPoly + SHA256), TLS 1.3, Private Network (PSK + XSalsa20), Plaintext (testing)

Multiplexing

Yamux (flow control, keep-alive), Mplex, QUIC/SCTP native multiplexing

Discovery

SWIM membership, mDNS, CYCLON random sampling, Plumtree gossip, Beacon (BLE/WiFi/LoRa proximity)

Protocols

Identify, Ping, GossipSub v1.1/v1.2, Kademlia DHT (S/Kademlia), Plumtree, Circuit Relay v2, AutoNAT, DCUtR, Rendezvous, HTTP

NAT Traversal

Traversal Coordinator (local direct -> direct IP -> hole punch -> relay fallback), UPnP + NAT-PMP

Security Posture

Resource limits are enforced by default: NodeConfiguration.resourceManager is non-optional and defaults to an enforcing DefaultResourceManager (per-protocol/peer/connection limits). There is no silent "unlimited" default; opting out requires an explicit NullResourceManager().
Plaintext security is not @_exported from the P2P umbrella module (import P2PSecurityPlaintext explicitly). Production validation rejects plaintext and a disabled resource manager as errors.
PSK private networks (Pnet) are wired into both dial and listen and fail closed when a configured PSK cannot be applied.
GossipSub validates messages before inserting into the seen-cache, verifies signed peer-exchange records, and bounds control traffic (IHAVE/IWANT/GRAFT/PRUNE/IDONTWANT).
Kademlia's default validator verifies IPNS and public-key record signatures.
Identify verifies signed peer records when present; Circuit Relay, Rendezvous, and AutoNAT apply reservation/registration/rate limits.

Requirements

Swift 6.2+
macOS 26+ / iOS 26+ / tvOS 26+ / watchOS 26+ / visionOS 26+

Installation

To use the Embedded-first API documented here, pin to the embedded branch (see the release status caveat above):

dependencies: [
    .package(url: "https://github.com/1amageek/swift-libp2p.git", branch: "embedded")
]

The released tag ships the prior API:

dependencies: [
    .package(url: "https://github.com/1amageek/swift-libp2p.git", from: "0.2.0")
]

P2P module re-exports common dependencies (batteries-included):

.target(name: "YourApp", dependencies: ["P2P"])

Or pick individual modules:

.target(name: "YourApp", dependencies: [
    "P2PCore",
    "P2PTransportTCP",
    "P2PSecurityNoise",
    "P2PMuxYamux",
    "P2PProtocols"
])

Quick Start

import P2P

let node = Node(configuration: NodeConfiguration(
    keyPair: .generateEd25519(),
    listenAddresses: [Multiaddr("/ip4/0.0.0.0/tcp/4001")!],
    transports: [TCPTransport()],
    security: [NoiseUpgrader()],
    muxers: [YamuxMuxer()]
))

try await node.start()
print("Listening as \(node.peerID)")

// Connect to a remote peer
let peer = try await node.connect(
    to: Multiaddr("/ip4/192.168.1.100/tcp/4001/p2p/12D3KooW...")!
)

// Open a stream
let stream = try await node.newStream(to: peer, protocol: "/chat/1.0.0")
try await stream.write(ByteBuffer(string: "Hello!"))

Products

The P2P umbrella re-exports the common batteries-included set; individual modules can also be imported directly.

Core

Module	Description
`P2PCore`	PeerID, Multiaddr, KeyPair, EventBroadcaster, Varint, Multihash
`P2PNegotiation`	multistream-select v1 (+ 0-RTT lazy)
`P2PNAT`	NAT device detection, UPnP + NAT-PMP port mapping
`P2PRuntime`	runtime contracts such as `ConnectionProvider` and `RuntimeConfiguration`

Transport

Module	Description
`P2PTransport`	Transport / Listener / RawConnection protocols
`P2PTransportTCP`	SwiftNIO-based TCP
`P2PTransportQUIC`	QUIC (0-RTT, connection migration)
`P2PTransportWebSocket`	WebSocket (HTTP/1.1 upgrade)
`P2PTransportWebRTC`	WebRTC Direct (DTLS 1.2 + SCTP)
`P2PTransportWebTransport`	WebTransport over QUIC
`P2PTransportMemory`	In-memory transport for testing

Security

Module	Description
`P2PSecurity`	`SecurityUpgrader`, `SecureChannel`
`P2PSecurityNoise`	Noise XX (X25519 + ChaChaPoly + SHA256)
`P2PSecurityTLS`	TLS 1.3 with libp2p certificate extension
`P2PPnet`	Private Network (PSK + XSalsa20, go-libp2p compatible). A configured PSK (`NodeConfiguration(privateNetwork:)`) is applied before security on both dial and listen, and fails closed if it cannot be applied (no unprotected fallback).
`P2PSecurityPlaintext`	Plaintext (testing only)
`P2PCertificate`	X.509 certificate generation/verification

Multiplexing

Module	Description
`P2PMux`	Muxer / `StreamSession` / `StreamChannel` protocols
`P2PMuxYamux`	Yamux (256KB window, flow control, keep-alive)
`P2PMuxMplex`	Mplex

Discovery

Module	Description
`P2PDiscovery`	discovery services, address books, peer stores, `DiscoveryPipeline`
`P2PDiscoverySWIM`	SWIM membership (swift-SWIM integration)
`P2PDiscoveryMDNS`	mDNS local network discovery
`P2PDiscoveryCYCLON`	CYCLON random peer sampling
`P2PDiscoveryPlumtree`	Plumtree gossip-based discovery
`P2PDiscoveryBeacon`	BLE / WiFi / LoRa proximity discovery
`P2PDiscoveryWiFiBeacon`	WiFi beacon adapter (UDP multicast)

Protocols

Module	Description
`P2PProtocols`	capability protocols, service roles, `ServicePipeline`
`P2PIdentify`	Peer information exchange (+ Push)
`P2PPing`	Connection liveness check
`P2PGossipSub`	Pub/Sub messaging (v1.1 scoring + v1.2 IDONTWANT)
`P2PKademlia`	DHT (S/Kademlia, latency tracking, persistent storage)
`P2PPlumtree`	Epidemic Broadcast Trees
`P2PCircuitRelay`	Relay v2 (client + server)
`P2PAutoNAT`	NAT reachability detection
`P2PDCUtR`	Direct Connection Upgrade through Relay
`P2PRendezvous`	Namespace-based peer discovery
`P2PHTTP`	HTTP semantics over libp2p

Integration

Module	Description
`P2PRuntime`	expert-facing runtime layer with `ConnectionProvider` and `RuntimeConfiguration`
`P2P`	batteries-included facade with `Node`, `NodeGroup`, `Service`, `Discovery`, and the `NodeGroupBuilder` result builder

Architecture

The public surface is split into two layers: P2P (the batteries-included facade) and P2PRuntime (expert-facing runtime APIs). Runtime-facing connections are unified behind ConnectionProvider, service composition is explicit through ServicePipeline, discovery composition through DiscoveryPipeline, and payload paths are normalized on ByteBuffer.

Layer Stack

┌─────────────────────────────────────────────────────────────┐
│  Application                                                │
│  (GossipSub, Kademlia, your protocols)                      │
├─────────────────────────────────────────────────────────────┤
│  P2P facade                                                 │
│  Node / NodeGroup / NodeGroupBuilder(result builder)        │
├─────────────────────────────────────────────────────────────┤
│  P2PRuntime                                                 │
│  NodeRuntime / Swarm / ConnectionPool / Traversal           │
│  ServicePipeline / DiscoveryPipeline                        │
├─────────────────────────────────────────────────────────────┤
│  Runtime connection contract                                │
│  ConnectionProvider / ConnectionAcceptor / Candidate        │
├─────────────────────────────────────────────────────────────┤
│  Protocol Negotiation (multistream-select)                  │
├─────────────────────────────────────────────────────────────┤
│  Stream Multiplexing          Yamux, Mplex                  │
├─────────────────────────────────────────────────────────────┤
│  Security                     Noise, TLS 1.3, Pnet          │
├─────────────────────────────────────────────────────────────┤
│  Transport      TCP, QUIC, WebSocket, WebRTC, WebTransport  │
├─────────────────────────────────────────────────────────────┤
│  NAT Traversal  Circuit Relay v2, AutoNAT, DCUtR            │
├─────────────────────────────────────────────────────────────┤
│  Core           PeerID, Multiaddr, KeyPair, Events          │
└─────────────────────────────────────────────────────────────┘

Composition Model

Node is the facade composition root
NodeRuntime owns startup ordering, listeners, swarm startup, and discovery auto-connect
ServicePipeline resolves service components into lifecycle services, inbound handlers, peer observers, discovery sources, and listen-address contributors
DiscoveryPipeline owns child discovery services and their startup hooks

Data Plane

The payload path is designed around ByteBuffer.

transports, security wrappers, muxers, and stream I/O exchange ByteBuffer
control-plane codecs may still use Data
crypto and native adapter boundaries may still require Data
DataPathCopyGuardTests prevents new Data(buffer:) / ByteBuffer(bytes:) bridges from re-entering runtime-facing paths

This keeps hot-path payload movement on ByteBuffer while isolating unavoidable Data conversions to protocol and crypto boundaries. The currently allowed exceptions are the Noise decrypt boundary, the plaintext handshake protobuf decode, and legacy MplexFrame convenience APIs.

Connection Flow

connect(to: Multiaddr)
  │
  ├─ Traversal Coordinator (stage-by-stage)
  │    ├─ 1. Local Direct (same LAN)
  │    ├─ 2. Direct IP
  │    ├─ 3. Hole Punch (AutoNAT + DCUtR)
  │    └─ 4. Relay (Circuit Relay v2)
  │
  ├─ ConnectionProvider.dial()
  │    ├─ transport -> security -> mux pipeline
  │    └─ or native secured provider (QUIC/WebRTC/WebTransport)
  │
  ├─ ConnectionPool.add()
  ├─ Swarm emits .peerConnected (fire-and-forget)
  ├─ Node event loop -> PeerObserver dispatch
  └─ Node emits NodeEvent.peerConnected

Configuration

Node Configuration

let node = Node(configuration: NodeConfiguration(
    keyPair: .generateEd25519(),
    listenAddresses: [Multiaddr("/ip4/0.0.0.0/tcp/4001")!],
    transports: [TCPTransport()],
    security: [NoiseUpgrader()],
    muxers: [YamuxMuxer()],
    pool: PoolConfiguration(
        limits: .init(highWatermark: 100, lowWatermark: 80, maxConnectionsPerPeer: 2),
        reconnectionPolicy: .default,
        idleTimeout: .seconds(300)
    )
))

Services

Services are composed explicitly via ServicePipeline or Node { ... }:

let node = Node(
    keyPair: .generateEd25519(),
    listenAddresses: [Multiaddr("/ip4/0.0.0.0/tcp/4001")!],
    transports: [TCPTransport()],
    security: [NoiseUpgrader()],
    muxers: [YamuxMuxer()]
) {
    GossipSub()
    Kademlia()
}

try await node.start()

Node.start() succeeds only after built-in discovery components have completed their startup hooks. A discovery startup failure is surfaced as a start error; it is not downgraded to a warning.

Production Profile

For a safer default operating profile, use .production:

let node = Node(
    profile: .production,
    keyPair: .generateEd25519(),
    listenAddresses: [Multiaddr("/ip4/0.0.0.0/tcp/4001")!],
    transports: [TCPTransport()],
    security: [NoiseUpgrader()],
    muxers: [YamuxMuxer()]
) {
    Identify()
    GossipSub()
}

The production profile enables resource accounting and production-oriented pool and health-check defaults. Production validation reports an error (not a warning) for plaintext security and for a disabled resource manager.

NodeConfiguration.resourceManager is non-optional and defaults to an enforcing DefaultResourceManager. There is no silent "unlimited" default: per-protocol, per-peer, and per-connection limits are enforced. Opting out of limits requires an explicit NullResourceManager(), which production validation rejects as an error.

Plaintext security is not @_exported from the umbrella P2P module; callers that want it must import P2PSecurityPlaintext directly, and it is rejected by production validation.

You can also validate a node before startup:

do {
    try await node.start(validating: .production, behavior: .strict)
} catch let error as NodeStartValidationError {
    print("validation errors:", error.validation.errors)
    print("validation warnings:", error.validation.warnings)
}

The intended release path is:

compose with Node(profile: .production) { ... }
start with try await node.start(validating: .production, behavior: .strict)
run scripts/production-gate.sh --include-benchmarks before shipping

Reusable groups can be modeled directly as NodeGroup values:

let chatStack = NodeGroup {
    Identify()
    GossipSub()
    MDNS()
}

let node = Node {
    chatStack
}

If you want a custom type, conform to NodeComponent and implement body declaratively:

struct MetricsStack: NodeComponent {
    let ping = PingService()

    var body: some NodeComponent {
        NodeGroup {
            Service(ping)
                .handlesInboundStreams()
        }
    }
}

Discovery with Auto-Connect

let node = Node(
    keyPair: .generateEd25519(),
    listenAddresses: [Multiaddr("/ip4/0.0.0.0/tcp/4001")!],
    transports: [TCPTransport()],
    security: [NoiseUpgrader()],
    muxers: [YamuxMuxer()],
    discoveryConfig: .autoConnectEnabled
) {
    Identify()
    MDNS()
    SWIM()
}

Events

// Node events
Task {
    for await event in node.events {
        switch event {
        case .peerConnected(let peer):
            print("Connected: \(peer)")
        case .peerDisconnected(let peer):
            print("Disconnected: \(peer)")
        case .newListenAddr(let addr):
            print("Listening on: \(addr)")
        default: break
        }
    }
}

// Service events (e.g., GossipSub — EventBroadcaster, multi-consumer)
Task {
    for await event in gossipsub.events {
        switch event {
        case .messageReceived(let topic, let message):
            print("Message on \(topic): \(message.data)")
        default: break
        }
    }
}

Concurrency Model

Pattern	When	Examples
`actor`	I/O heavy, user-facing API	Node, Swarm, HealthMonitor
`class + Mutex<T>`	High-frequency, sync access	ConnectionPool, PeerStore
`struct`	Data containers	NodeConfiguration, SwarmEvent

Event Patterns

Pattern	Consumers	Examples
`EventEmitting` (single)	One `for await` loop	Ping, Identify, AutoNAT, Kademlia
`EventBroadcaster` (multi)	Multiple independent loops	GossipSub, SWIM, mDNS, Node

Wire Protocol Compatibility

Protocol	Protocol ID	Specification
multistream-select	`/multistream/1.0.0`	spec
TLS 1.3	`/tls/1.0.0`	spec
Noise	`/noise`	spec
Yamux	`/yamux/1.0.0`	spec
Mplex	`/mplex/6.7.0`	spec
Identify	`/ipfs/id/1.0.0`	spec
Ping	`/ipfs/ping/1.0.0`	spec
Circuit Relay v2	`/libp2p/circuit/relay/0.2.0/hop`	spec
GossipSub	`/meshsub/1.1.0`	spec
Kademlia	`/ipfs/kad/1.0.0`	spec
AutoNAT	`/libp2p/autonat/1.0.0`	spec
DCUtR	`/libp2p/dcutr`	spec
Plumtree	`/plumtree/1.0.0`	paper
CYCLON	`/cyclon/1.0.0`	paper
WebRTC Direct	`/webrtc-direct`	spec

Performance

Hot paths are optimized to avoid heap churn and super-linear work: Base58 decode and Multiaddr.bytes are O(n); Kademlia closestPeers uses partial sort + bucket-proximity expansion; the GossipSub message cache and SWIM/Discovery peer stores use O(1) indexed/LRU structures; Noise HKDF avoids intermediate Data allocations; Yamux/Mplex read/write paths use offset tracking instead of repeated slice copies.

Representative numbers from the in-tree benchmark harness (DataPathBenchmarks, NoiseCryptoBenchmarks):

Benchmark	Result
Noise encrypt 32B	1621.57 ns/op
Noise encrypt 256B	1896.24 ns/op
Noise decrypt 256B	2317.60 ns/op
Noise roundtrip 1KB	5877.08 ns/op
Memory + Plaintext + Yamux connect	49644.06 ns/op
Memory + Noise + Yamux connect	569969.08 ns/op
Memory + TLS + Yamux connect	1429667.75 ns/op
Memory + Plaintext + Yamux roundtrip 1KB	12.00 MiB/s
Memory + Noise + Yamux roundtrip 1KB	23.18 MiB/s
Memory + TLS + Yamux roundtrip 1KB	36.28 MiB/s
Memory + Noise + Yamux roundtrip 32KB	86.04 MiB/s

Run the benchmarks via the production-readiness gate:

scripts/production-gate.sh
scripts/production-gate.sh --include-benchmarks

The gate runs the runtime-facing copy guard, the public Node DSL tests, and the Node end-to-end suite, then the opt-in live localhost network lane and interop smoke lane. With --include-benchmarks it also runs the release benchmark snapshot for DataPathBenchmarks and NoiseCryptoBenchmarks.

Testing

# Build
swift build

# Run deterministic correctness tests (always use timeout)
scripts/swift-test-timeout.sh 120 --disable-sandbox
scripts/swift-test-timeout.sh 60 --disable-sandbox --filter P2PTests

# Live localhost network tests are opt-in: TCP, UDP, QUIC, WebSocket, WebTransport, WebRTC, NAT, and discovery
scripts/live-network-test.sh

# Interoperability tests are opt-in and require Docker
scripts/interop-test.sh smoke

# Benchmarks are opt-in and kept out of default `swift test`
scripts/run-benchmarks.sh --configuration release

Dependencies

Package	Purpose
swift-nio	Network I/O
swift-crypto	Cryptographic primitives
swift-certificates	X.509 handling
swift-asn1	ASN.1 encoding
swift-log	Logging
swift-tls	TLS 1.3 (pure Swift)
swift-quic	QUIC (RFC 9000)
swift-webrtc	WebRTC Direct

References

License

MIT License

Description

Swift Tools 6.2.0

View More Packages from this Author

Dependencies

Last updated: Sun Jun 28 2026 06:14:02 GMT-0900 (Hawaii-Aleutian Daylight Time)