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

> Explore the core components of iroh, including its endpoint, cryptographic identity, discovery services, and relay infrastructure. Understand the technical architecture of this peer-to-peer networking project.

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

---

**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)](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)](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)](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)](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)](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)](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)](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)](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)](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)](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)](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)](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/`](https://github.com/n0-computer/iroh/blob/main/iroh/examples/connect.rs) 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

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

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

```rust
// 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`](https://github.com/n0-computer/iroh/blob/main/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`](https://github.com/n0-computer/iroh/blob/main/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`](https://github.com/n0-computer/iroh/blob/main/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`](https://github.com/n0-computer/iroh/blob/main/iroh/src/tls.rs), eliminates the traditional client-server certificate distinction and enables authentication based purely on cryptographic identity rather than hierarchical certificate chains.