What Are the Core Components of iroh? A Technical Architecture Guide

The core components of iroh consist of a centralized Endpoint that manages QUIC connections, cryptographic identity primitives from iroh-base, address lookup services for peer discovery, relay infrastructure for NAT traversal, and supporting modules for metrics, DNS resolution, and network diagnostics.

The n0-computer/iroh repository provides a Rust library for end-to-end encrypted peer-to-peer communication over QUIC. Understanding the core components of iroh is essential for developers building decentralized applications that require reliable NAT traversal and cryptographic identity management without traditional client-server distinctions.

The Endpoint: Central Connection Manager

The Endpoint serves as the primary interface for creating, binding, and driving an iroh node. Exported in [iroh/src/lib.rs](https://github.com/n0-computer/iroh/blob/main/iroh/src/lib.rs#L78-L82), this structure manages QUIC connections, streams, and the complete lifecycle of the node.

When binding an endpoint, you configure the RelayMode to define how the node discovers and communicates with relay servers. As defined in [iroh/src/lib.rs](https://github.com/n0-computer/iroh/blob/main/iroh/src/lib.rs#L82-L85), options include the default "number-0" relay, custom relay configurations, or direct-only mode for environments where relay support is unnecessary.

Identity and Cryptographic Foundations

The iroh-base crate provides the fundamental types shared across the entire ecosystem. Located in [iroh-base/src/lib.rs](https://github.com/n0-computer/iroh/blob/main/iroh-base/src/lib.rs), this module defines EndpointId, PublicKey, SecretKey, RelayUrl, and TransportAddr, along with validation helpers that ensure type safety across network boundaries.

The tls module in [iroh/src/tls.rs](https://github.com/n0-computer/iroh/blob/main/iroh/src/tls.rs) implements the TLS layer used by QUIC. Each endpoint generates its own SecretKey that doubles as the TLS certificate, effectively removing the classical distinction between client and server certificates and enabling purely key-based authentication.

Peer Discovery and Address Resolution

The address_lookup service, implemented in [iroh/src/address_lookup.rs](https://github.com/n0-computer/iroh/blob/main/iroh/src/address_lookup.rs), resolves an EndpointId to a relay URL and optional direct IP addresses via DNS. This abstraction makes connecting possible using only the peer's public key, without requiring prior knowledge of network coordinates.

Supporting the address lookup system, the portmapper module ([iroh/src/portmapper.rs](https://github.com/n0-computer/iroh/blob/main/iroh/src/portmapper.rs)) attempts UDP and TCP hole punching by probing NAT mappings. This improves direct connectivity rates when peers reside behind network address translators.

The iroh-dns crate ([iroh-dns/src/dns.rs](https://github.com/n0-computer/iroh/blob/main/iroh-dns/src/dns.rs)) provides the client-side DNS functionality that publishes and resolves endpoint records, while iroh-dns-server ([iroh-dns-server/src/server.rs](https://github.com/n0-computer/iroh/blob/main/iroh-dns-server/src/server.rs)) implements a minimal DNS-over-HTTPS/Do53 server that stores signed DNS packets for iroh endpoints.

Relay Infrastructure and Protocols

The iroh-relay crate contains the standalone relay implementation for scenarios where direct QUIC connections fail. The server logic in [iroh-relay/src/server.rs](https://github.com/n0-computer/iroh/blob/main/iroh-relay/src/server.rs) handles encrypted forwarding and address discovery helpers, while the client-side components (used automatically by Endpoint) manage the fallback tunneling.

Low-level QUIC message definitions—including handshake protocols, stream management, and ping mechanisms—reside in the protocol module at [iroh/src/protocol.rs](https://github.com/n0-computer/iroh/blob/main/iroh/src/protocol.rs). These messages facilitate communication between endpoints and relay servers.

Observability and Diagnostics

The metrics module in [iroh/src/metrics.rs](https://github.com/n0-computer/iroh/blob/main/iroh/src/metrics.rs) exports Prometheus-style metrics for endpoints, relays, and DNS servers, tracking connection counts, bytes transferred, and ping latency.

For network troubleshooting, the net_report module ([iroh/src/net_report.rs](https://github.com/n0-computer/iroh/blob/main/iroh/src/net_report.rs)) provides optional diagnostics that query latency to relays, probe NAT behavior, and generate comprehensive connectivity reports. Note that this API is currently marked as unstable.

Implementation Examples

The iroh/examples/ directory contains ready-to-run demonstrations showing typical usage patterns. These include establishing connections, listening for incoming peers, implementing custom transports, and configuring authentication hooks.

Practical Usage Patterns

The following examples demonstrate interactions with the core components of iroh. These assume the with_crypto_provider feature is enabled, which is the default when compiling for native targets.

Creating and Binding an Endpoint

// Create and bind an endpoint using the default "number 0" relay
let ep = iroh::Endpoint::bind(iroh::defaults::N0).await?;

// Connect to a remote peer using its EndpointId (public key) and ALPN
let conn = ep
    .connect(remote_addr, b"my-alpn")
    .await?;

// Open a bi-directional stream and exchange data
let (mut send, mut recv) = conn.open_bi().await?;
send.write_all(b"hello iroh").await?;
send.finish().await?;
let reply = recv.read_to_end(usize::MAX).await?;

// Graceful shutdown
conn.close(0u8.into(), b"finished");
ep.close().await;

Accepting Incoming Connections

// Configure the endpoint with supported ALPN protocols
let ep = iroh::Endpoint::builder(iroh::defaults::N0)
    .alpns(vec![b"my-alpn".to_vec()])
    .bind()
    .await?;

loop {
    // Wait for inbound QUIC connections
    let conn = ep.accept().await?.await?;
    let (mut send, mut recv) = conn.accept_bi().await?;
    
    // Echo back received data
    let data = recv.read_to_end(usize::MAX).await?;
    send.write_all(&data).await?;
    send.finish().await?;
}

DNS-Based Address Lookup

// Configure the endpoint to use DNS address resolution
let builder = iroh::endpoint::Builder::new(iroh::defaults::N0);
let builder = builder.address_lookup(iroh::address_lookup::DnsAddressLookup::default());
let ep = builder.bind().await?;

// Now connect using only the peer's public key (EndpointId)
// The address lookup service resolves the relay URL and direct addresses automatically

Summary

• The Endpoint in iroh/src/lib.rs serves as the central object managing QUIC connections, stream lifecycle, and node configuration.
• iroh-base provides cryptographic primitives including EndpointId, PublicKey, and SecretKey that form the identity layer.
• address_lookup and iroh-dns enable peer discovery using only public keys, abstracting away IP address management.
• iroh-relay and portmapper provide NAT traversal through relay servers and hole punching when direct connections fail.
• metrics and net_report offer observability into connection health and network topology.
• The examples/ directory provides reference implementations for common connection patterns.

Frequently Asked Questions

What is the role of the Endpoint in iroh?

The Endpoint is the central abstraction that binds to a local socket, manages QUIC connections, and coordinates with relay servers. It handles the complete lifecycle of peer-to-peer connections, from initial handshake through stream multiplexing, and is exported as the primary API entry point in iroh/src/lib.rs.

How does iroh handle peer discovery without IP addresses?

Iroh uses the address_lookup service combined with iroh-dns to resolve a peer's EndpointId (their public key) to network coordinates. This allows connections using only cryptographic identities, with the DNS layer handling the mapping to relay URLs and direct IP addresses transparently.

What is the purpose of the relay system in iroh?

The iroh-relay infrastructure provides encrypted forwarding when direct QUIC connections fail due to NAT or firewall restrictions. The relay server (iroh-relay/src/server.rs) acts as a fallback path, while the portmapper module simultaneously attempts to establish direct connections through hole punching.

How does iroh implement TLS authentication?

Iroh implements TLS using self-certified keys where each endpoint's SecretKey doubles as its TLS certificate. This approach, implemented in iroh/src/tls.rs, eliminates the traditional client-server certificate distinction and enables authentication based purely on cryptographic identity rather than hierarchical certificate chains.

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