Discovery

Discovery is the glue that connects a Node Identifier to something we can dial. Discovery services resolve NodeIds to either a home Relay URL or direct-dialing information.

Node discovery is an automated system for an Endpoint to retrieve addressing information. Each iroh node will automatically publish their own addressing information with configured discovery services. Usually this means publishing which Home Relay a node is findable at, but they could also publish their direct addresses.

Discovery Services

There are four different implementations of the discovery service in iroh, all of which map NodeIds to addresses:

By Default, iroh uses the DNS discovery system to resolve NodeIds to addresses. And can be configured to use any of the other discovery systems.

DNS Discovery

DNS performs node lookups via the standard DNS systems. To publish to this DNS server a PkarrPublisher is needed. Number 0 runs a public instance of the DNS discovery system

Local Discovery

Local discovery adds the ability to scan local networks for other iroh nodes, using Local Swarm Discovery. This is useful for local networks, or for bootstrapping a network before a relay is available.

Local Discovery is not enabled by default, and must be enabled by the user. You'll need to add the discovery-local-network feature flag to your Cargo.toml to use it.

[dependencies]
iroh = { version = "0.1", features = ["discovery-local-network"] }

Then configure your endpoint to use local discovery concurrently with DNS discovery:

use iroh::{
    discovery::{dns::DnsDiscovery, LocalSwarmDiscovery, pkarr::PkarrPublisher, ConcurrentDiscovery},
    Endpoint, SecretKey,
};

let secret_key = SecretKey::generate(rand::rngs::OsRng);
let discovery = ConcurrentDiscovery::from_services(vec![
    Box::new(DnsDiscovery::n0_dns()),
    Box::new(LocalSwarmDiscovery::new(secret_key.public())?),
]);

let ep = Endpoint::builder()
    .secret_key(secret_key)
    .discovery(Box::new(discovery))
    .bind()
    .await?;

Pkarr Discovery

The Pkarr resolver can perform lookups from designated pkarr relay servers using HTTP. Read more about the pkarr project here.

DHT Discovery

DHT discovery uses the BitTorrent Mainline distributed hash table (DHT) to publish & resolve NodeIds.

DHT Discovery is not enabled by default, and must be enabled by the user. You'll need to add the discovery-pkarr-dht feature flag to your Cargo.toml to use it.

[dependencies]
iroh = { version = "0.1", features = ["discovery-pkarr-dht"] }

Then configure your endpoint to use DHT discovery concurrently with DNS discovery:

use iroh::{
    discovery::{dns::DnsDiscovery, pkarr::dht::DhtDiscovery, ConcurrentDiscovery},
    Endpoint, SecretKey,
};

let secret_key = SecretKey::generate(rand::rngs::OsRng);
let discovery = ConcurrentDiscovery::from_services(vec![
    Box::new(DnsDiscovery::n0_dns()),
    Box::new(DhtDiscvoery::new(secret_key.public())?),
]);

let ep = Endpoint::builder()
    .secret_key(secret_key)
    .discovery(Box::new(discovery))
    .bind()
    .await?;