Node Addresses
Node Addresses or NodeAddrs
are a common struct you'll interact when working with iroh to tell iroh what & where to dial. In rust they look like this:
pub struct NodeAddr {
pub node_id: PublicKey,
pub relay_url: Option<RelayUrl>,
pub direct_addresses: BTreeSet<SocketAddr>,
}
You'll interact with NodeAddr
s a fair amount when working with iroh. Discovery Services like local_discovery
will emit a stream of NodeAddrs
that it finds on the local network. It's also quite normal to construct addresses manually from, say, node identifiers stored in your application database.
When we call connect
on an Endpoint, we need to pass either a NodeAddr
, or something that can turn into a NodeAddr
. In iroh NodeAddr
s will have different fields populated depending on where they came from, and the discovery services you've configured your node with.
Interaction with discovery
From the above struct, the only required field is the node_id. And because of this, there's an implementation of From
that can turn NodeIDs
directly into NodeAddrs. but this will only work if you have a discovery service that can resolve NodeIDs enabled. So generally if you want to use raw NodeIDs, you'll need something that looks like this when you set up your endpoint:
use iroh::Endpoint;
let ep = Endpoint::builder()
// this part enables dialing by NodeAddrs that only have NodeIDs:
.discovery_n0()
.bind()
.await?;
This is why we actively encourage configuring a discovery service, and DNS is the most common one we recommend. Because we're in p2p land dialing details & even home relays for a node can change on very short notice, making this data go stale quickely. Node Identifiers are a practical source of stability that counteracts this.
When to provide full details
If you have full dialing details, it's well worth providing them as part of a NodeAddr
passed to connect
. Iroh can use this to skip the network roundtrip required to either do initial address discovery, or update cached addresses. So if you have a source of up to date home relay & dialing info, provide it!
Don't store relay_url & direct_addresses values
If you're persisting the contents of NodeAddr
in your app, it's probably not worth keeping the relay_url
and direct_address
fields, unless you know these details are unlikely to change. Providing stale details to the endpoint can slow down connection construction.