Iroh Address Lookup Services: Built-in and Optional Discovery Methods Explained

Iroh provides a modular address lookup system with three built-in services (MemoryLookup, DnsAddressLookup, and PkarrResolver) and optional support for mDNS and Mainline DHT discovery via external crates.

The n0-computer/iroh repository implements a flexible address lookup architecture that enables endpoints to discover network paths using only an EndpointId. This modular system allows developers to combine multiple discovery mechanisms—ranging from in-memory maps to decentralized DNS—to fit their specific deployment requirements.

Built-in Address Lookup Services

The core Iroh crate ships with three concrete implementations of the AddressLookup trait defined in iroh/src/address_lookup.rs.

MemoryLookup

The MemoryLookup service stores addressing information in-process, allowing applications to manage peer discovery programmatically. According to the source code in iroh/src/address_lookup/memory.rs, endpoints can dynamically add or remove entries using MemoryLookup::add and MemoryLookup::remove methods at runtime.

DnsAddressLookup

For traditional DNS-based discovery, DnsAddressLookup performs standard DNS queries using the iroh-dns resolver to fetch EndpointInfo records. As implemented in iroh/src/address_lookup/dns.rs, this service resolves records published via PkarrPublisher, which writes signed PKARR packets to a DNS zone.

PkarrResolver

The PkarrResolver retrieves endpoint data from a PKARR relay server over HTTP. Located in iroh/src/address_lookup/pkarr.rs, this resolver works alongside the PkarrPublisher that sends signed packets to a PKARR relay when publishing address information.

Optional External Lookup Services

Beyond the built-in implementations, Iroh supports additional discovery mechanisms through separate crates.

mDNS-based Discovery

The iroh-mdns-address-lookup crate enables local network discovery via multicast DNS. Peers publish their EndpointInfo through an mDNS responder, allowing LAN-based endpoint discovery without external infrastructure.

Mainline DHT-based Discovery

For decentralized global discovery, the iroh-mainline-address-lookup crate stores endpoint records on the Mainline Distributed Hash Table (BitTorrent DHT). Publishing occurs through a Mainline DHT client that inserts signed PKARR packets into the distributed hash table.

How Address Lookup Services Work Together

Iroh combines multiple lookup services through the AddressLookupServices registry. When configuring an endpoint via Builder::address_lookup, you can register multiple services; the system executes them in parallel and merges their result streams.

When resolving addresses, the registry yields the first usable address while continuing to process slower services. During publication, the endpoint sends data to every registered service (optionally filtered by AddrFilter).

Configuring Address Lookup in Your Application

To configure address lookup services, use the endpoint builder pattern:

use iroh::{
    Endpoint,
    address_lookup::{self, AddrFilter, PkarrPublisher},
    endpoint::{presets, Builder},
};

async fn build_endpoint() -> iroh::Result<Endpoint> {
    // Enable public PKARR/DNS publication and DNS resolution
    let ep = Endpoint::builder(presets::Minimal)
        .address_lookup(PkarrPublisher::n0_dns())               // Publishes via PKARR relay & DNS
        .address_lookup(address_lookup::DnsAddressLookup::n0_dns()) // Resolves through DNS
        .addr_filter(AddrFilter::relay_only()) // Optional: only publish relay URLs
        .bind()
        .await?;
    Ok(ep)
}

To add an in-memory lookup for dynamic peer management:

let mem = address_lookup::MemoryLookup::new();
ep.address_lookup().unwrap().add(mem);

Summary

• Iroh provides three built-in address lookup services: MemoryLookup, DnsAddressLookup, and PkarrResolver.
• Optional mDNS and Mainline DHT discovery are available via the iroh-mdns-address-lookup and iroh-mainline-address-lookup crates.
• The AddressLookupServices registry in iroh/src/address_lookup.rs runs configured services in parallel, merging their result streams.
• Services implement the AddressLookup trait, with source files located in iroh/src/address_lookup/memory.rs, iroh/src/address_lookup/dns.rs, and iroh/src/address_lookup/pkarr.rs.

Frequently Asked Questions

What is the default address lookup service in Iroh?

Iroh does not enable any address lookup services by default. Developers must explicitly configure desired services using the Builder::address_lookup method when constructing an endpoint, allowing complete control over which discovery mechanisms are active.

How does Iroh handle conflicting addresses from multiple lookup services?

The AddressLookupServices registry resolves addresses by merging streams from all configured services and yielding the first usable result. This parallel approach ensures low latency while still processing slower services in the background.

Can I implement a custom address lookup service for Iroh?

Yes, you can implement the AddressLookup trait defined in iroh/src/address_lookup.rs to create custom discovery mechanisms. Once implemented, register your custom service using Builder::address_lookup to integrate it with the existing registry.

What is the difference between PkarrResolver and DnsAddressLookup?

PkarrResolver queries PKARR relay servers directly over HTTP, while DnsAddressLookup performs standard DNS queries using the iroh-dns resolver. Both use PKARR packets for data integrity, but DnsAddressLookup relies on DNS infrastructure whereas PkarrResolver communicates directly with PKARR relays.

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