Dependencies for the Iroh Project: A Complete Guide to the Core Crate

The iroh crate depends on 35+ direct dependencies including tokio for async runtime, blake3 for content-addressed hashing, ed25519-dalek for cryptographic identities, and a custom QUIC stack (noq), all declared in iroh/Cargo.toml.

The iroh project by n0-computer is a Rust-based peer-to-peer networking stack that enables secure, distributed communication. Understanding the dependencies for the iroh project is essential for developers integrating the library, debugging build issues, or auditing the security surface area. This guide breaks down every direct dependency declared in the core crate's manifest, explaining their architectural roles and version constraints.

Core Runtime Dependencies

The iroh crate lists its primary dependencies in iroh/Cargo.toml (lines 24–64). These crates form the foundation of the library's networking, cryptographic, and async capabilities.

Cryptography and Hashing

Secure peer-to-peer networking relies on robust cryptographic primitives. According to the source code, iroh integrates several specialized crates:

• blake3 (version 1.8.3, no default features): Provides fast cryptographic hashing for content-addressed identifiers at line 25.
• ed25519-dalek (version =3.0.0-rc.0 with features serde, rand_core, zeroize, pkcs8, pem): Handles public-key cryptography for peer identities and signing, defined at line 31.
• data-encoding (version 2.2): Implements base-64 and base-32 encoding for keys and identifiers at line 28.
• rand (version 0.10): Supplies cryptographically secure random number generation for keys and nonces at line 47.

Async Runtime and I/O

All I/O operations and timers in iroh are powered by the Tokio ecosystem:

• tokio (version 1.44.1, features io-util, macros, sync, rt): The asynchronous runtime declared across lines 54–59.
• tokio-stream (version 0.1.15, feature sync): Provides stream combinators built on top of Tokio at line 60.
• tokio-util (version 0.7, features io-util, io, rt): Utility extensions including codec support at line 61.
• bytes (version 1.11): Efficient buffer management for I/O streams at line 26.
• pin-project (version 1): Utilities for pinning async futures at line 42.

Networking and Transport

Iroh implements QUIC-based transport using a custom stack:

• noq (version 1.0.0, features rustls): The QUIC implementation used for the transport layer at line 44.
• noq-proto (version 1.0.0): Protocol definitions for the QUIC stack at line 45.
• noq-udp (version 1.0.0): UDP socket abstraction used by the transport at line 46.
• rustls (version 0.23.33, no default features): TLS stack for secure connections, particularly by the relay client at line 50.
• webpki-types (package alias rustls-pki-types, version 1.12): X.509 type definitions for TLS verification at line 64.
• http (version 1): HTTP types and utilities used by the relay client at line 32.
• reqwest (version 0.13, features rustls-no-provider, stream): HTTP client for fetching discovery documents at line 48.
• ipnet (version 2): IPv4/IPv6 network manipulation for subnet checks at line 33.

Data Serialization and Utilities

• serde (version 1.0.219, features derive, rc): Handles serialization of configuration and protocol messages at line 51.
• derive_more (version 2.0.1): Reduces boilerplate with derive macros for common traits at line 30.
• strum (version 0.28, feature derive): Enum utilities providing Display and FromStr implementations at line 53.
• smallvec (version 1.11.1): Optimizes collections with few items via small-vector optimization at line 52.
• rustc-hash (version 2): Fast hash map implementation for internal caches at line 49.
• url (version 2.5, feature serde): URL parsing for relay URLs and endpoint addresses at line 63.
• tracing (version 0.1): Structured, async-compatible logging framework at line 62.

Workspace Dependencies

The iroh repository is organized as a Cargo workspace. The core crate depends on several sibling crates declared in iroh/Cargo.toml:

• iroh-base (version 1.0.0, path ../iroh-base, features key, relay): Core data structures including keys and relay URLs at line 34.
• iroh-dns (version 1.0.0, path ../iroh-dns): DNS resolution for peer discovery at line 35.
• iroh-relay (version 1.0.0, path ../iroh-relay, no default features): Relay server and client implementation for NAT traversal at line 36.

Additional n0-computer ecosystem crates include:

• n0-future (version 0.3): Helper traits for async programming at line 37.
• n0-error (version 1.0.0): Error handling wrappers including anyhow support at line 38.
• n0-watcher (version 1.0.0): File-system watching for hot-reloading configuration at line 39.

Platform-Specific and Optional Dependencies

Certain dependencies are gated by target platform or feature flags:

• hickory-resolver (version 0.26.0, no default features): DNS resolution for non-wasm targets at line 77.
• portmapper (version 0.19, optional): UPnP/NAT-PMP port mapping for peer-to-peer connectivity at line 78.
• noq (with runtime-tokio and rustls features): Enables the QUIC stack on non-wasm platforms at lines 79–80.
• wasm-bindgen-futures (version 0.4): Bridges Rust futures to JavaScript promises for wasm targets at line 92.
• time (version 0.3, feature wasm-bindgen): Time handling required by x509_parser in browsers at lines 94–95.
• getrandom (version 0.4, feature wasm_js): Secure random number generation for wasm at lines 95–96.

Note that the crate also includes dev-dependencies (such as axum and pretty_assertions) that are only compiled for tests and examples, not required for downstream users.

How to Use Iroh in Your Project

To utilize these dependencies in your own application, add iroh to your Cargo.toml:

[dependencies]
iroh = { git = "https://github.com/n0-computer/iroh", rev = "main" }

Creating a Peer Identity and Dialing

The following example demonstrates creating an endpoint and connecting to a remote peer using the cryptographic types from iroh-base:

use iroh::endpoint::Endpoint;
use iroh::iroh_base::key::PublicKey;
use std::net::SocketAddr;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Load the default endpoint (creates a keypair if none exists)
    let ep = Endpoint::default().await?;

    // Example: connect to a remote peer given its public key and socket
    let remote_key = PublicKey::from_hex("ab...")?;
    let remote_addr: SocketAddr = "127.0.0.1:4000".parse()?;
    let conn = ep.connect(remote_key, remote_addr).await?;

    println!("connected to {}!", conn.remote_id());
    Ok(())
}

This code leverages the Endpoint struct defined in iroh/src/endpoint.rs and the PublicKey type from iroh-base/src/key.rs.

Using the Built-In Relay for NAT Traversal

For peers behind NAT, the relay client provides connectivity:

use iroh::relay::RelayClient;
use iroh::iroh_base::relay_url::RelayUrl;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Connect to a public relay
    let relay_url = RelayUrl::parse("https://relay.iroh.example")?;
    let client = RelayClient::new(relay_url).await?;

    // Obtain a mapped address that can be shared with peers
    let mapped = client.register().await?;
    println!("relay address: {}", mapped);
    Ok(())
}

The implementation resides in iroh-relay/src/client.rs and utilizes the rustls and http dependencies for secure communication.

Summary

• The iroh crate declares 35+ direct dependencies in iroh/Cargo.toml, ranging from cryptographic libraries to async runtime components.
• Core dependencies include tokio for async execution, blake3 for hashing, ed25519-dalek for signatures, and the custom noq QUIC stack.
• Workspace dependencies (iroh-base, iroh-dns, iroh-relay) provide essential data structures and networking capabilities.
• Platform-specific dependencies support both native targets (via hickory-resolver and portmapper) and WebAssembly (via wasm-bindgen-futures and getrandom).
• Dev-dependencies are excluded from production builds, keeping the runtime footprint minimal for downstream users.

Frequently Asked Questions

What version of Tokio does iroh require?

Iroh requires tokio version 1.44.1 with specific features enabled (io-util, macros, sync, rt), as specified at lines 54–59 of iroh/Cargo.toml. This version provides the async runtime that powers all I/O and timers in the library.

Is the QUIC implementation in iroh based on quinn or another library?

Iroh uses a custom QUIC implementation called noq (version 1.0.0) rather than quinn. The dependency appears at line 44 of iroh/Cargo.toml, accompanied by noq-proto and noq-udp for protocol definitions and UDP socket abstraction respectively.

Can I compile iroh for WebAssembly targets?

Yes, iroh supports WebAssembly through conditional dependencies. The manifest includes wasm-bindgen-futures (line 92), time with wasm-bindgen feature (lines 94–95), and getrandom with wasm_js feature (lines 95–96) specifically for browser environments. Certain native dependencies like hickory-resolver are excluded from wasm builds.

Are all the dependencies required for production use?

No, the crate separates dev-dependencies (used for testing and examples) from runtime dependencies. Production builds only require the dependencies listed in the [dependencies] section of iroh/Cargo.toml. Optional features like portmapper can also be disabled to reduce the dependency tree for specific use cases.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}