# Performance Characteristics of iroh: How the Rust P2P Library Achieves High-Throughput, Low-Latency Transfers

> Discover iroh's performance: achieve gigabit throughput and sub-10ms latency with its QUIC transport, async execution, and NAT traversal. Learn more about this Rust P2P library.

- Repository: [number zero/iroh](https://github.com/n0-computer/iroh)
- Tags: performance
- Published: 2026-07-03

---

**iroh delivers gigabit-class throughput and sub-10ms latency on local networks by combining QUIC-based transport via `quinn`, Tokio-powered async execution, and intelligent NAT traversal with relay fallback, while built-in benchmarking tools in `iroh-bench` provide granular metrics for TTFB, throughput, and stream concurrency.**

The `n0-computer/iroh` repository is a Rust library designed for peer-to-peer networking that prioritizes the performance characteristics of iroh through efficient resource usage and modern transport protocols. Whether transferring small control messages or multi-terabyte blobs, the library leverages asynchronous I/O and zero-copy techniques to saturate network links while maintaining predictable latency.

## QUIC-Based Transport Architecture

### Multiplexed Streams with Minimal Head-of-Line Blocking

At the foundation of iroh's performance lies its **QUIC-based transport** layer built on the `quinn` crate. QUIC provides multiplexed streams over a single connection, built-in congestion control, and TLS-encrypted packet delivery. This design enables many concurrent streams to operate simultaneously without head-of-line blocking, allowing the library to fully saturate network links. The transport abstraction is implemented in [`iroh/src/transport/quic.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/src/transport/quic.rs), which wraps the underlying QUIC primitives to provide a unified interface for peer-to-peer communication.

### Connection Establishment and Path Selection

iroh optimizes latency through intelligent **NAT traversal** with relay fallback. The system first attempts hole-punching to establish direct paths between peers, which achieve the lowest possible RTT. When direct connections fail, the library falls back to an encrypted relay that preserves end-to-end encryption. This logic is orchestrated in [`iroh/src/endpoint.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/src/endpoint.rs), where the `Endpoint` struct handles dialing, relay coordination, and path selection. Direct hole-punched connections typically achieve **sub-10ms TTFB** on local networks, while relayed connections add modest overhead but maintain security guarantees.

## Async Runtime and Resource Scaling

### Tokio Worker Configuration

Each iroh endpoint runs on a **Tokio async runtime** with configurable worker threads. The `--workers-per-ep` parameter controls parallelism, with benchmarks demonstrating that **two workers per endpoint** strikes an optimal balance between ACK processing and data sending. This configuration spreads stream handling across CPU cores, improving congestion-control responsiveness and raising achievable bandwidth. The benchmark driver in [`iroh/bench/src/lib.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/bench/src/lib.rs) exposes these settings programmatically, allowing developers to tune runtime characteristics for specific hardware.

### Zero-Copy Blob Handling

For large data transfers, iroh utilizes **zero-copy blob handling** via the `iroh-blobs` protocol. By employing BLAKE3-based content addressing, the library streams data without copying between buffers. This approach significantly reduces CPU overhead and memory pressure, particularly when processing multi-terabyte files. The protocol handlers can be layered—for example, combining gossip and blobs—while reusing the same underlying QUIC connection, avoiding the overhead of establishing additional connections.

## Benchmarking iroh Performance

The `iroh-bench` crate provides comprehensive tooling to measure the performance characteristics of iroh under configurable loads. The benchmark driver defined in [`iroh/bench/src/lib.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/bench/src/lib.rs) supports several key parameters:

- `--clients`: Number of simultaneous endpoints
- `--streams`: Concurrent streams per client
- `--max-streams`: Upper bound for simultaneous streams
- `--download-size` and `--upload-size`: Payload sizes with SI prefix support
- `--workers-per-ep`: Tokio worker threads per endpoint

### Metrics and Histograms

Performance data is collected in [`iroh/bench/src/stats.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/bench/src/stats.rs), which defines the `Stats` and `StreamStats` structs. The implementation captures:

- **Throughput**: Calculated as `size / duration` via `throughput_bps` (lines 33-34)
- **Time to First Byte (TTFB)**: Captured in `TransferResult::new` (lines 19-20) as the duration until the first byte arrives
- **Chunk metrics**: Per-chunk timings and sizes to analyze burst behavior and MTU adaptation

Sample output from the benchmarking tool includes percentile distributions for throughput and duration, enabling precise latency analysis:

```rust
// Example: Run a simple benchmark from Rust code
use iroh::bench::{self, Opt};
use clap::Parser;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Configure a benchmark: 4 clients, 4 streams each, 100 MiB download per stream
    let opt = Opt {
        clients: 4,
        streams: 4,
        max_streams: 4,
        download_size: 100 << 20, // 100 MiB
        upload_size: 0,
        ..Default::default()
    };
    // Run the Iroh benchmark directly (same logic used by `iroh-bench`)
    bench::iroh::run(opt).await?;
    Ok(())
}

```

## Optimizing Throughput and Latency

### Stream Concurrency and Flow Control

QUIC's **stream-level flow control** prevents a slow stream from throttling the entire connection. By running multiple parallel streams—configured via the `--streams` parameter—iroh can fully utilize available bandwidth. The multiplexing happens over a single connection, keeping per-connection costs low while maximizing link saturation.

### MTU and Chunk Optimization

The `--initial-mtu` setting affects how data is segmented during transfer. Smaller MTU values increase chunk count but keep per-chunk latency low, while larger MTU values reduce overhead and boost raw throughput. These characteristics are visible in the `chunk_time` metrics recorded within [`iroh/bench/src/stats.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/bench/src/stats.rs), allowing developers to tune chunk sizing for their specific network conditions.

```rust
// Example: Access per-stream statistics after a transfer
use iroh::bench::stats::{Stats, TransferResult};

fn report(stats: &Stats) {
    println!("Total bytes transferred: {}", stats.total_size);
    println!("Average throughput: {:.2} MiB/s",
        stats.stream_stats.throughput_hist.mean() as f64 / 1024.0 / 1024.0);
    println!("Mean TTFB: {:.2} ms",
        stats.stream_stats.ttfb_hist.mean() / 1_000.0);
}

```

## Summary

- **QUIC transport** enables high concurrency with minimal head-of-line blocking, allowing gigabit-class throughput over single connections.
- **Direct hole-punched connections** achieve sub-10ms TTFB on local networks, with encrypted relay fallback preserving security when NAT traversal fails.
- **Tokio runtime scaling** via `--workers-per-ep` allows CPU-intensive workloads to spread across cores, with two workers per endpoint recommended for optimal congestion control.
- **Zero-copy blob handling** minimizes CPU and memory overhead when transferring large files through BLAKE3-based content addressing.
- **Built-in benchmarking** via `iroh-bench` provides granular visibility into throughput, latency percentiles, and chunk-level timing through [`stats.rs`](https://github.com/n0-computer/iroh/blob/main/stats.rs) and [`lib.rs`](https://github.com/n0-computer/iroh/blob/main/lib.rs).

## Frequently Asked Questions

### What throughput can iroh achieve on a standard network?

iroh can saturate gigabit-class links when configured with appropriate worker threads and MTU settings. The `iroh-bench` tool measures this via the `throughput_bps` calculation in [`iroh/bench/src/stats.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/bench/src/stats.rs), with benchmarks showing consistent high bandwidth utilization across multiple concurrent streams.

### How does iroh minimize latency under NAT conditions?

The library attempts hole-punching first to establish direct paths, which typically yields sub-10ms TTFB on local networks. If direct connection fails, it falls back to encrypted relays, which adds modest latency but preserves end-to-end encryption, as implemented in the `Endpoint` logic in [`iroh/src/endpoint.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/src/endpoint.rs).

### What is the optimal configuration for CPU-intensive workloads?

Setting `--workers-per-ep 2` (or higher) spreads ACK processing and stream handling across CPU cores, improving congestion-control responsiveness. This configuration balances the async Tokio runtime according to benchmarks in the `iroh-bench` crate.

### How does iroh reduce memory usage during large file transfers?

Through zero-copy blob handling in `iroh-blobs`, the library uses BLAKE3-based content addressing to stream data without copying between buffers. This approach significantly reduces memory pressure when transferring multi-terabyte files.