peeroxide

Rust implementation of the Hyperswarm P2P networking stack, wire-compatible with the existing Node.js network.

This project is a faithful port targeting full interoperability with the existing Hyperswarm network. Node.js peers can discover and connect to Rust peers and vice versa.

Architecture

peeroxide-cli          — command-line toolkit (lookup, announce, ping, cp, dd, chat, init)
└── peeroxide          — topic-based peer discovery + connection management (Hyperswarm)
    └── peeroxide-dht  — Kademlia DHT, Noise handshakes, hole-punching, relay (HyperDHT)
        └── libudx     — reliable UDP transport with BBR congestion control (libudx)

Install the CLI

The peeroxide CLI bundles several subcommands (lookup, announce, ping, cp, dd, chat, node, init). The CLI was built as an example of how to use the library, and also serves as a convenient toolkit for interacting with the network from the terminal to test connectivity, share files, or chat with peers. No Rust toolchain is needed for the prebuilt CLI route.

Homebrew (macOS / Linux):

brew install rightbracket/peeroxide/peeroxide

Homebrew will auto-tap rightbracket/peeroxide on first use. Prebuilt binaries are published for macOS (universal Apple Silicon + Intel), Linux x86_64 (glibc), and Linux aarch64 (glibc).

Cargo:

cargo install peeroxide-cli

Build from upstream main:

brew install --HEAD rightbracket/peeroxide/peeroxide

After install:

peeroxide --help
peeroxide chat --help

Tap details and upgrade / uninstall instructions: https://github.com/Rightbracket/homebrew-peeroxide.

Quick Start (library)

use peeroxide::{spawn, discovery_key, JoinOpts, SwarmConfig};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = SwarmConfig::with_public_bootstrap();
    let (_task, handle, mut conn_rx) = spawn(config).await?;

    let topic = discovery_key(b"my-application");
    handle.join(topic, JoinOpts::default()).await?;

    while let Some(conn) = conn_rx.recv().await {
        println!("connected to {}", hex::encode(conn.remote_public_key()));
    }
    Ok(())
}

Crates

• peeroxide
  High-level swarm management and topic-based discovery.
• peeroxide-dht
  HyperDHT implementation including Kademlia, hole-punching, and Noise handshakes.
• libudx
  Pure Rust implementation of the UDX protocol with BBR congestion control.
• peeroxide-cli
  Command-line toolkit (peeroxide binary): lookup, announce, ping, cp, dd, chat, init.

Interoperability

All layers are validated via golden byte fixtures and live cross-language interop tests against Node.js reference implementations. The stack uses pure Rust crypto (RustCrypto) and excludes C dependencies. It targets the Rust 2024 edition and uses the tokio async runtime.

Reference Implementations

This work implements the protocols defined in the following reference projects:

• hyperswarm
• hyperdht
• dht-rpc
• hyperswarm-secret-stream
• libudx

Status

Version 1.0.0 — initial public release. The full protocol stack is implemented and validated, including live network interoperability with the Node.js reference implementation.

License

Dual-licensed under MIT OR Apache-2.0. See THIRD_PARTY_NOTICES for upstream license details.