What Kind of Data Does the iroh API Handle? A Technical Deep Dive

The iroh API handles content-addressed binary blobs, metadata collections, peer network state, and chunked transfer control structures, all implemented as strongly-typed Rust structs in the n0-computer/iroh codebase.

The iroh API from the n0-computer/iroh repository is built around a content-addressed, peer-to-peer storage model. Understanding what kind of data the iroh API handles is essential for developers building distributed applications, as the API orchestrates binary payloads, structured collections, and real-time network metadata between peers. All data types are defined as public, serializable Rust structs exposed through the main iroh crate.

Core Storage Data Types

Binary Blobs

Blob is the atomic unit of storage in iroh. Defined in iroh/src/blob.rs, a blob represents a raw binary payload addressed by a cryptographic hash (SHA-256 by default). Blobs are immutable once created and serve as the foundation for all data transfer operations in the system.

Collections

A Collection is a higher-level structure that groups multiple blobs together with optional tags and metadata. Found in iroh/src/collection.rs, collections enable synchronized operations across related data sets, such as folders or versioned file systems. Collections maintain their own integrity while referencing constituent blobs by hash.

Network and Peer Data

Remote Peer Information

The RemoteInfo struct, located in iroh/src/remote_info.rs, encapsulates everything known about a remote peer. This includes endpoint IDs, reachable addresses, capability announcements, and relay connection status. This data type drives the connection establishment process.

Local Endpoint Configuration

The Endpoint struct in iroh/src/endpoint.rs represents the local node's configuration, including listen addresses, TLS settings, and transport preferences. The endpoint serves as the entry point for all API calls and maintains the state of active peer connections.

Transfer Protocol Data

TransferRequest and TransferResponse

Chunked data movement relies on TransferRequest and TransferResponse structs defined in iroh/src/transfer.rs. These carry metadata about the requested data range, including offsets, lengths, cryptographic hashes, and checksums. They form the control layer of the wire protocol while the actual blob content streams separately.

Address Lookup Results

AddressLookup data types in iroh/src/address_lookup.rs store the results of peer discovery mechanisms. Whether resolved via DNS, PKARR, or in-memory caches, these structs map peer identifiers to their current network locations.

Operational and Infrastructure Data

Metrics and Reports

Runtime observability comes from Metrics and Report structs. The Metrics type in iroh/src/metrics.rs tracks throughput and error counts, while detailed latency reports are available in iroh/src/net_report/report.rs. These enable real-time monitoring of network health and transfer performance.

Relay Configuration

NAT traversal support relies on RelayConfig and RelayInfo structures defined in iroh-relay/src/server.rs. These data types configure relay server connections and track connection status, allowing peers to communicate even when behind firewalls or restrictive networks.

Working with iroh Data Types

Here are practical examples showing how to interact with these data structures according to the n0-computer/iroh source code.

Starting an endpoint:

use iroh::endpoint::{Builder, Endpoint};

let endpoint: Endpoint = Builder::default()
    .listen_on("[::]:0".parse().unwrap())
    .build()
    .await
    .expect("failed to start endpoint");

Storing a blob:

use iroh::blob::Blob;

let data = b"Hello, iroh!";
let blob = Blob::from_bytes(data).await?;
endpoint.put_blob(blob).await?;

Fetching a blob from a remote peer:

use iroh::remote_info::RemoteInfo;

let remote: RemoteInfo = endpoint.lookup_peer("peer-id").await?;
let fetched = endpoint.get_blob(remote, blob_hash).await?;
println!("Fetched {} bytes", fetched.len());

Syncing a collection:

use iroh::collection::Collection;

let mut coll = Collection::new();
coll.add_blob(blob_hash);
let sync_handle = endpoint.sync_collection(&coll).await?;
sync_handle.wait().await?;

Querying runtime metrics:

use iroh::net_report::Report;

let report: Report = endpoint.report().await?;
println!("Average latency: {} ms", report.relay_latencies.mean());

Summary

• Binary blobs are the atomic, content-addressed storage units handled by the iroh API, defined in iroh/src/blob.rs.
• Collections group related blobs with metadata, enabling higher-level synchronization workflows in iroh/src/collection.rs.
• RemoteInfo and Endpoint structs manage peer discovery and local network configuration in iroh/src/remote_info.rs and iroh/src/endpoint.rs.
• TransferRequest and TransferResponse control chunked data movement at the protocol level in iroh/src/transfer.rs.
• AddressLookup results resolve peer locations through DNS or PKARR in iroh/src/address_lookup.rs.
• Metrics and RelayConfig provide operational visibility and NAT traversal support in iroh/src/metrics.rs and iroh-relay/src/server.rs.

Frequently Asked Questions

What is a Blob in the iroh API?

A Blob is the fundamental data type representing an immutable binary payload addressed by its SHA-256 hash. According to iroh/src/blob.rs, blobs are the atomic units that move across the network, providing content-addressed guarantees for all stored data.

How does iroh handle peer discovery data?

Peer discovery relies on the RemoteInfo and AddressLookup structs. As implemented in iroh/src/remote_info.rs and iroh/src/address_lookup.rs, these types capture endpoint IDs, reachable addresses, and the results of DNS or PKARR resolution queries.

What metrics are available through the iroh API?

The API exposes runtime statistics through the Metrics and Report types. Defined in iroh/src/metrics.rs and iroh/src/net_report/report.rs, these track throughput, latency distributions, error counts, and relay connection quality.

How are collections structured in iroh?

Collections are metadata structures that reference multiple blobs by hash. Located in iroh/src/collection.rs, they function as tagged groupings that enable atomic synchronization of related data sets across peers.

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