Discovery

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

Endpoint discovery is an automated system for an Endpoint to retrieve addressing information. Each iroh endpoint will automatically publish their own addressing information with configured discovery services. Usually this means publishing which Home Relay an endpoint 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 EndpointIds to addresses:

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

DNS Discovery

DNS performs endpoint 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 endpoints, 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]
# Make sure to use the most recent version here instead of nn. (at the time of writing: 0.32)
iroh = { version = "0.nn", features = ["discovery-local-network"] }

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

use iroh::Endpoint;

let mdns = iroh::discovery::mdns::MdnsDiscovery::builder();
let ep = Endpoint::builder()
    .discovery(mdns)
    .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 EndpointIds.

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]
# Make sure to use the most recent version here instead of nn. (at the time of writing: 0.32)
iroh = { version = "0.nn", features = ["discovery-pkarr-dht"] }

Then configure your endpoint to use DHT discovery concurrently with mDNS discovery, but not with the default DNS discovery, use the Endpoint::empty_builder method. This requires specifying a RelayMode, which in this example we will keep default.

use iroh::Endpoint;

let dht_discovery = iroh::discovery::dht::DhtDiscovery::builder();
let mdns = iroh::discovery::mdns::MdnsDiscovery::builder();
let ep = Endpoint::empty_builder(iroh::RelayMode::Default)
    .discovery(dnt_discovery)
    .discovery(mdns)
    .bind()
    .await?;