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

> Discover iroh's performance: gigabit throughput and sub-10ms latency for P2P transfers. Learn how QUIC, zero-copy, and smart NAT traversal deliver efficient connections.

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

---

**iroh achieves gigabit-class throughput and sub-10 ms latency by combining QUIC-based transport with configurable Tokio runtimes, zero-copy blob handling, and intelligent NAT traversal that prioritizes direct hole-punched connections over relay fallbacks.**

The `n0-computer/iroh` repository provides a Rust library designed for high-performance peer-to-peer networking. Understanding the performance characteristics of iroh requires examining its core architectural decisions, from the underlying QUIC implementation to its sophisticated benchmarking instrumentation.

## Core Architectural Components Driving Performance

### QUIC Transport and Stream Multiplexing

iroh builds peer-to-peer connections on top of the **QUIC transport protocol** using the `quinn` implementation. In [`iroh/src/transport/quic.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/src/transport/quic.rs), the library leverages QUIC's native **stream multiplexing** capabilities, allowing many concurrent streams over a single connection without head-of-line blocking.

This architecture enables the library to saturate network links efficiently. Each stream maintains independent flow control, preventing a slow stream from throttling the entire connection. The transport layer handles TLS encryption automatically, ensuring that security does not compromise throughput.

### Async Runtime Optimization with Tokio

Each endpoint runs on a dedicated **Tokio async runtime**, with worker thread counts configurable via the `--workers-per-ep` parameter. The implementation in [`iroh/src/endpoint.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/src/endpoint.rs) demonstrates that spreading ACK processing and stream handling across CPU cores improves congestion-control responsiveness.

Benchmarks indicate that configuring two workers per endpoint provides an optimal balance between acknowledgment processing and data transmission. This scalability allows iroh to handle high-concurrency workloads across multiple CPU cores without bottlenecks.

### Zero-Copy Data Handling

For blob transfers, iroh utilizes **zero-copy operations** through the `iroh-blobs` protocol. By employing **BLAKE3-based content addressing**, the system streams data without copying between buffers. This approach significantly reduces CPU overhead and memory pressure, particularly when transferring multi-terabyte datasets.

The content-addressing scheme ensures data integrity while maintaining the performance benefits of direct memory access patterns.

### Connection Path Selection

The library implements intelligent **NAT traversal** with a performance-first approach. It attempts hole-punching to establish direct peer-to-peer connections before falling back to encrypted relay servers. Direct paths deliver the lowest possible round-trip time (RTT), typically achieving sub-10 ms latency on local area networks.

When relay fallback is necessary (configurable via `--only-relay` for testing), the connection preserves end-to-end encryption while maintaining measurable throughput characteristics.

## Benchmarking iroh Performance

### Configurable Load Parameters

The repository includes `iroh-bench`, a dedicated benchmarking tool located in [`iroh/bench/src/lib.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/bench/src/lib.rs). This utility drives the library under configurable loads using parameters that mirror real-world deployment scenarios:

- **Clients** (`--clients`): Number of simultaneous endpoints
- **Streams** (`--streams`): Concurrent streams per client
- **Max-streams** (`--max-streams`): Upper bound for simultaneous streams
- **Payload sizes** (`--download-size`, `--upload-size`): Transfer volumes with SI prefix support
- **Workers** (`--workers-per-ep`): Tokio worker threads per endpoint

### Key Metrics and Statistics

The statistics collection implementation in [`iroh/bench/src/stats.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/bench/src/stats.rs) captures granular performance data through the `Stats` and `StreamStats` structures. The system records:

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

Sample output from `iroh-bench` demonstrates the tool's reporting capabilities:

```text
Overall upload stats:

Transferred 4.09 GiB on 8 streams in 5.12 s (0.80 MiB/s)

Time to first byte (TTFB): 12.4 ms

Total chunks: 12345
Average chunk time: 0.41 ms
Average chunk size: 0.32 KiB

Stream upload metrics:
      │  Throughput   │ Duration 
──────┼───────────────┼──────────
 AVG  │ 0.79 MiB/s │   5.12 s
 P0   │ 0.78 MiB/s │   5.10 s
 …
 P100 │ 0.81 MiB/s │   5.15 s

```

## Performance Optimization Strategies

### Scaling Concurrent Streams

QUIC's stream-level flow control architecture allows iroh to utilize **efficient multiplexing** across many parallel streams. This design prevents individual stream congestion from impacting overall connection performance, enabling full link utilization even with mixed workload types.

### Tuning MTU and Chunk Behavior

The library adapts to network conditions through configurable **Maximum Transmission Unit (MTU)** settings (`--initial-mtu`). Smaller MTU values increase chunk counts but maintain low per-chunk latency, while larger MTU configurations reduce overhead and maximize raw throughput. The `chunk_time` histograms in the benchmark output reveal these adaptation patterns in real-time.

### Runtime Worker Configuration

For CPU-bound operations, increasing `--workers-per-ep` beyond the default distributes workload across cores. The benchmark implementation shows that this scaling improves performance for high-throughput scenarios where single-threaded runtimes would bottleneck on cryptographic operations or congestion control calculations.

## Code Examples

### Running Benchmarks Programmatically

You can embed the benchmark logic directly in Rust applications using the internal API:

```rust
// Example: Run a simple benchmark from Rust code
use iroh::bench::{self, Opt, Commands};
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(())
}

```

### Accessing Transfer Statistics

Extract detailed metrics from completed transfers using the stats module:

```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

- **High-throughput QUIC transport**: Utilizes `quinn` for multiplexed streams with minimal head-of-line blocking, enabling gigabit-class data transfers.
- **Scalable async architecture**: Configurable Tokio workers (`--workers-per-ep`) allow CPU-intensive operations to scale across cores.
- **Zero-copy efficiency**: BLAKE3-based content addressing in `iroh-blobs` eliminates unnecessary memory copies during large file transfers.
- **Intelligent path selection**: Prioritizes direct hole-punched connections for sub-10 ms latency, with encrypted relay fallback for connectivity guarantees.
- **Comprehensive instrumentation**: Built-in benchmarking tools in [`iroh/bench/src/stats.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/bench/src/stats.rs) provide TTFB, throughput, and chunk-level latency histograms.

## Frequently Asked Questions

### What throughput can iroh achieve on local networks?

On local area networks with direct hole-punched connections, iroh achieves **gigabit-class throughput** with latency under 10 milliseconds. The QUIC-based transport in [`iroh/src/transport/quic.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/src/transport/quic.rs) saturates network links through efficient stream multiplexing, while the benchmark suite confirms sustained high bandwidth across multiple concurrent streams.

### How does iroh handle NAT traversal without sacrificing performance?

iroh attempts **NAT hole-punching** first to establish direct peer-to-peer paths, falling back to encrypted relays only when necessary. Direct connections minimize RTT, while the relay path (testable via `--only-relay`) maintains end-to-end encryption and measurable throughput. This prioritization ensures optimal performance characteristics even in complex network topologies.

### What is the optimal Tokio worker configuration for iroh endpoints?

Benchmarks indicate that **two workers per endpoint** (`--workers-per-ep 2`) provide the best balance for most workloads. This configuration, implemented in the endpoint runtime, separates ACK processing from data transmission across CPU cores, improving congestion-control responsiveness without excessive thread overhead.

### How does iroh minimize CPU overhead during large file transfers?

The library employs **zero-copy blob handling** via BLAKE3 content addressing in the `iroh-blobs` protocol. By streaming data without copying between buffers, iroh reduces memory pressure and CPU cycles, making it efficient for multi-terabyte transfers while maintaining cryptographic verification of content integrity.