From c4ceb037192f92ef9cbfcbbac8f0bd44a8fd1ea4 Mon Sep 17 00:00:00 2001 From: Rae McKelvey <633012+okdistribute@users.noreply.github.com> Date: Thu, 18 Jun 2026 17:15:17 -0700 Subject: [PATCH 1/3] what-is-iroh: merge in "how iroh works" narrative with animated diagrams Brings the animated SVG walkthrough from iroh.computer PR #479 into the docs "What is iroh?" page: connect-by-key, guaranteed connections, library and relays, endpoint startup, peer lookup (DNS + DHT), and direct connections (hole punching + LAN). Adapts the blog's Next.js JSX to Mintlify's / convention, cross-links to existing concept/connecting pages, and renders each diagram on a white background so the SMIL/CSS animations stay readable in both light and dark themes. Keeps the existing layer-stack diagram, code example, and getting-started links. Co-Authored-By: Claude Opus 4.8 (1M context) --- images/how-iroh-works/connect-by-key.svg | 114 +++++++++ images/how-iroh-works/embedding-phone.svg | 120 +++++++++ images/how-iroh-works/endpoint-startup.svg | 143 +++++++++++ images/how-iroh-works/hole-punching-lan.svg | 155 ++++++++++++ images/how-iroh-works/hole-punching.svg | 263 ++++++++++++++++++++ images/how-iroh-works/publish-relay-dht.svg | 151 +++++++++++ images/how-iroh-works/publish-relay.svg | 126 ++++++++++ images/how-iroh-works/routing-moves.svg | 157 ++++++++++++ what-is-iroh.mdx | 130 +++++++++- 9 files changed, 1355 insertions(+), 4 deletions(-) create mode 100644 images/how-iroh-works/connect-by-key.svg create mode 100644 images/how-iroh-works/embedding-phone.svg create mode 100644 images/how-iroh-works/endpoint-startup.svg create mode 100644 images/how-iroh-works/hole-punching-lan.svg create mode 100644 images/how-iroh-works/hole-punching.svg create mode 100644 images/how-iroh-works/publish-relay-dht.svg create mode 100644 images/how-iroh-works/publish-relay.svg create mode 100644 images/how-iroh-works/routing-moves.svg diff --git a/images/how-iroh-works/connect-by-key.svg b/images/how-iroh-works/connect-by-key.svg new file mode 100644 index 0000000..12083f0 --- /dev/null +++ b/images/how-iroh-works/connect-by-key.svg @@ -0,0 +1,114 @@ + + + + + + + + + + + 10.0.0.42 + + 192.168.1.7 + + + 203.0.113.15 + + + 172.20.4.88 + + + 192.168.10.55 + + + + + + iroh + πŸ”‘ a4f7c0… + + + + + + + iroh + πŸ”‘ 8e2b1d… + + + Alice + Bob + + + + + connect + + + + + + + + + + diff --git a/images/how-iroh-works/embedding-phone.svg b/images/how-iroh-works/embedding-phone.svg new file mode 100644 index 0000000..dc950c2 --- /dev/null +++ b/images/how-iroh-works/embedding-phone.svg @@ -0,0 +1,120 @@ + + + + iOS app (Swift) +iroh via iroh-ffi + + + + swift app + + iroh + + + + + Android app (Kotlin) +iroh via iroh-ffi + + + + + kotlin app + + iroh + + + + + Native desktop (C++) +iroh via iroh-c-ffi + + + + c++ app + + iroh + + + + + + + Web app (JavaScript) +iroh compiled to WASM + + + + + + + + + js app + + iroh + + + + + Server daemon (Rust) +iroh crate directly + + + + + + + + + + + + rust daemon + + iroh + + + + + Embedded firmware (Rust) +iroh crate + + + + + + + + + + + + + + + + + + firmware + + iroh + + diff --git a/images/how-iroh-works/endpoint-startup.svg b/images/how-iroh-works/endpoint-startup.svg new file mode 100644 index 0000000..08f41b0 --- /dev/null +++ b/images/how-iroh-works/endpoint-startup.svg @@ -0,0 +1,143 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + us-west + + + + + + + + + + + + 52.10.18.7 + + + + + us-east + + + + + + + + + + + + 44.208.61.5 + + + + + eu-west + + + + + + + + + + + + 18.196.142.9 + + + + + + + + + + + + + + + iroh + πŸ”‘ 8e2b… + + + + 73.118.42.9 + + + + + + + + + + us-east: 19 ms + us-west: 71 ms + eu-west: 102 ms + + + + + + + + + + + + diff --git a/images/how-iroh-works/hole-punching-lan.svg b/images/how-iroh-works/hole-punching-lan.svg new file mode 100644 index 0000000..25aef03 --- /dev/null +++ b/images/how-iroh-works/hole-punching-lan.svg @@ -0,0 +1,155 @@ + + + + + + + + + + + + + + + + + + + + + relay + + + + + + + + + + 192.168.0.1 + + + + + + + + + iroh + πŸ”‘ 1a9c… + Alice + + + EndpointId: 1a9c… + Addr: 192.168.0.3:2104 + Addr: 4.9.8.2:2104 + relay: us-east + + + + + + + + + iroh + πŸ”‘ 8e2b… + Bob + + + EndpointId: 8e2b… + Addr: 192.168.0.5:4153 + Addr: 4.9.8.2:4153 + relay: us-east + + + + + + + + + + + + ADD_ADDRESS 192.168.0.5:4153 + ADD_ADDRESS 4.9.8.2:4153 + + + + + + + + + Bob + Candidate: 192.168.0.5:4153 + Candidate: 4.9.8.2:4153 + + + + + + + + + + + + REACH_OUT192.168.0.3:2104 + REACH_OUT4.9.8.2:2104 + + + + + + + + + Alice + Candidate: 192.168.0.3:2104 + Candidate: 4.9.8.2:2104 + + + + + + + + + + + + + + + + + + + + + + direct (LAN) + + + + + PATH_CHALLENGE + 192.168.0.5:4153 + + + + + PATH_RESPONSE + PATH_CHALLENGE + 192.168.0.3:2104 + + + + + PATH_RESPONSE + + diff --git a/images/how-iroh-works/hole-punching.svg b/images/how-iroh-works/hole-punching.svg new file mode 100644 index 0000000..98decf4 --- /dev/null +++ b/images/how-iroh-works/hole-punching.svg @@ -0,0 +1,263 @@ + + + + + + + + + + + + + + + + + + + + + + + + relay + + + + 8.3.1.9 + + + + + + + 10.0.0.1 + + + + 4.9.8.2 + + + + + + + 192.168.0.1 + + + + + + + + + iroh + πŸ”‘ 1a9c… + Alice + + + EndpointId: 1a9c… + Addr: 10.0.0.3:2104 + Addr: 8.3.1.9:2104 + relay: us-west + + + + + + + + + iroh + πŸ”‘ 8e2b… + Bob + + + EndpointId: 8e2b… + Addr: 192.168.0.3:4153 + Addr: 4.9.8.2:4153 + relay: us-east + + + + + + + + + + + + ADD_ADDRESS 192.168.0.3:4153 + ADD_ADDRESS 4.9.8.2:4153 + + + + + + + + + Bob + Candidate: 192.168.0.3:4153 + Candidate: 4.9.8.2:4153 + + + + + + + + + + + + REACH_OUT10.0.0.3:2104 + REACH_OUT8.3.1.9:2104 + + + + + + + + + Alice + Candidate: 10.0.0.3:2104 + Candidate: 8.3.1.9:2104 + I need to reach out + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + not routable + + + + + + not routable + + + + + + no mapping + + + + + + + + 4.9.8.2:4153 β†’ + 10.0.0.3:2104 + + + + + + + + + + + + + + + + + + + 8.3.1.9:2104 β†’ + 192.168.0.3:4153 + + + + + + + + + + + + + + + + PATH_CHALLENGE + 192.168.0.3:4153 + + + + + PATH_CHALLENGE + 10.0.0.3:2104 + + + + + PATH_CHALLENGE + 4.9.8.2:4153 + + + + + PATH_CHALLENGE + 8.3.1.9:2104 + + + + + PATH_RESPONSE + PATH_CHALLENGE + + + + + PATH_RESPONSE + + + + + + + + + diff --git a/images/how-iroh-works/publish-relay-dht.svg b/images/how-iroh-works/publish-relay-dht.svg new file mode 100644 index 0000000..ee35e6a --- /dev/null +++ b/images/how-iroh-works/publish-relay-dht.svg @@ -0,0 +1,151 @@ + + + + + + + + + + + + Mainline DHT + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + iroh + πŸ”‘ 8e2b… + Bob + + + NodeId: 8e2b… + Home relay: us-east + + + + + + + + + + iroh + πŸ”‘ 1a9c… + Alice + + 8e2b… is at relay us-east + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + DHT put + 8e2b… + Relay: us-east + + + + + + + DHT get + 8e2b… + + + + + + + ;; ANSWER SECTION: + TXT "relay=https://us-east" + + + + + + + + + diff --git a/images/how-iroh-works/publish-relay.svg b/images/how-iroh-works/publish-relay.svg new file mode 100644 index 0000000..6cf6556 --- /dev/null +++ b/images/how-iroh-works/publish-relay.svg @@ -0,0 +1,126 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + dns.iroh.link + + + + + 1f3a… β†’ eu-west + 7c0e… β†’ us-west + b48d… β†’ us-east + 2a91… β†’ eu-west + 8e2b… β†’ us-east + + + + + + + + + iroh + πŸ”‘ 8e2b… + Bob + + + NodeId: 8e2b… + Home relay: us-east + + + + + + + + + + iroh + πŸ”‘ 1a9c… + Alice + + + 8e2b… is at relay us-east + + + + + + + + + + + + + + + + + HTTPS PUT + Relay: us-east + Signed by: 8e2b… + + + + + + + + + DNS LOOKUP + TXT _iroh.8e2b….dns.iroh.link + + + + ;; ANSWER SECTION: + TXT "relay=https://us-east" + + + + + + + + + + diff --git a/images/how-iroh-works/routing-moves.svg b/images/how-iroh-works/routing-moves.svg new file mode 100644 index 0000000..fabe54c --- /dev/null +++ b/images/how-iroh-works/routing-moves.svg @@ -0,0 +1,157 @@ + + + + + + + + + + + 10.0.0.42 + + + + iroh + πŸ”‘ a4f7c0… + Alice + + + + + + 10.0.0.7 + 192.168.1.7 + 172.16.0.7 + + + + + iroh + πŸ”‘ 8e2b1d… + Bob + + + + + + + + + + + + + + + + + + + + + + + + home router + + 203.0.113.1 + + + + + + + 10.0.0.1 + + + + + + + mobile network + + 198.51.100.1 + + + + + + 192.168.1.1 + + + + + + + satellite internet + + 100.64.10.1 + + + 172.16.0.1 + + + + + + + + + + diff --git a/what-is-iroh.mdx b/what-is-iroh.mdx index 2333e9b..8fae503 100644 --- a/what-is-iroh.mdx +++ b/what-is-iroh.mdx @@ -2,9 +2,17 @@ title: "What is iroh?" --- -iroh is a modular networking stack written in Rust. It provides -the building blocks to create applications that can communicate -using fast, cheap, and reliable connections. +iroh is a modular networking stack written in Rust. It provides the building +blocks to create applications that can communicate using fast, cheap, and +reliable connections. + +It's a lightweight native library meant to be embedded directly into your +application β€” in Rust, or in C, C++, Swift, Python, JavaScript, and Kotlin +through [our bindings](/languages). + + + iroh embedded across six device contexts: iOS, Android, desktop, browser, server, embedded + ## Core features - **Fast**: iroh enables direct connections between @@ -32,6 +40,120 @@ and data synchronization. Any kind of CRDT or OT sync protocol can be integrated services](/protocols/rpc), and [streaming data](/protocols/streaming) with iroh's communication protocols. +## How iroh works + +iroh's job comes down to two promises: you can reach a peer no matter where it +is, and the connection you get is the best one available. + +### Connect by key + +Every iroh [endpoint](/concepts/endpoints) is identified by a cryptographic key. +That key β€” not an IP address β€” is the address. It lets you connect to a peer no +matter where it is, even as its network location changes underneath it. + + + Alice connects to Bob by key β€” IPs change, the key stays stable + + +### Guaranteed connections + +We make sure you get a connection whenever possible, and that it's as fast as +possible. When network conditions change, iroh immediately reacts and switches +to the new best path β€” transparently, without dropping the connection. + + + Alice and Bob connected via a shared router, with two more routers available for when Bob moves + + +Now that we've seen *what* iroh does, here's *how*. + +### Library and relays + +There are two pieces to the system: + +- **The iroh library** runs inside your application. It provides the API to + create endpoints, connect to other endpoints, and open connections and data + streams. +- **[Relays](/concepts/relays)** run in the background on publicly reachable + servers. They help endpoints find each other and establish direct + connections, and relay data as a fallback when a direct connection isn't + possible. + +### Endpoint startup + +An iroh endpoint is configured with a set of relays β€” the rate-limited public +relays operated by number 0, relays from iroh services, or self-hosted ones. +iroh works fine with a single relay, but works best with relays in every region +where your users are. + +On startup, an endpoint sends +[QAD](https://datatracker.ietf.org/doc/draft-ietf-quic-address-discovery/) +probes to all configured relays. This does two things: it learns the endpoint's +own public IP address, and it learns which relay is closest by latency. The +closest relay becomes the **home relay**, and the endpoint keeps a secure +WebSocket connection open to it. + + + A map of the US and Europe with iroh relays in us-west (Seattle), us-east (Delaware), and eu-west (Frankfurt), and an endpoint in Florida + + +### Finding peers + +When there are multiple relays, Alice needs to know which relay to use to reach +Bob. iroh offers two ways to publish and look up that information. + +#### DNS-based lookup + +Out of the box, iroh uses DNS. Bob publishes a signed record with his home relay +to a DNS server operated by number 0 via an HTTPS `PUT`. Anyone who wants to +reach Bob resolves that record with a DNS or HTTPS query. See +[DNS address lookup](/connecting/dns-address-lookup). + + + Bob publishes a signed DNS record with his home relay to dns.iroh.link via an HTTPS PUT; Alice resolves it with a DNS lookup + + +#### Mainline DHT lookup + +DNS works in most cases, but sometimes you want something fully peer-to-peer. +For that, iroh offers an optional lookup over the Mainline DHT: it publishes the +exact same signed record using the +[BEP 44](https://www.bittorrent.org/beps/bep_0044.html) extension. See +[DHT address lookup](/connecting/dht-address-lookup). + + + Bob publishes his signed record to several random nodes of the Mainline DHT; Alice resolves it by querying several random nodes + + +### Direct connections + +So far we've described a system where endpoints can always talk β€” but all data +flows through the relays. That adds latency, limits throughput, and costs the +relay operator money. Making connections fast and direct is arguably the most +complex part of the system. + +#### Hole punching + +Hole punching happens *inside* the QUIC connection via an +`n0_nat_traversal` extension, inspired by the +[QUIC NAT traversal draft](https://datatracker.ietf.org/doc/draft-seemann-quic-nat-traversal/) +but using its own transport parameter ID. See +[NAT traversal](/concepts/nat-traversal). + + + Alice and Bob, each behind a home router, connected through the relay β€” all data flows up to the relay and back down + + +#### Local connections + +If two devices are on the same network, hole punching isn't needed β€” each side +just needs to learn the other's local address. See +[local address lookup](/connecting/local-address-lookup). + + + Alice and Bob on the same home network discover each other over the relay, then connect directly across the LAN β€” the relay uplink fades away once the local path is validated + + ## How the pieces stack together An iroh application is a stack of small layers, each with one job: @@ -100,4 +222,4 @@ To get started with iroh, check out the [quickstart guide](/quickstart) or explo how to use them in your applications. Read the [how it works documentation](/concepts/endpoints) to understand the underlying -principles and architecture of iroh. \ No newline at end of file +principles and architecture of iroh. From 3d0fed67e627ca59d27ccad43477e6977cfe9f21 Mon Sep 17 00:00:00 2001 From: Rae McKelvey <633012+okdistribute@users.noreply.github.com> Date: Tue, 23 Jun 2026 12:23:40 -0700 Subject: [PATCH 2/3] what-is-iroh: sync diagrams and heading with latest iroh.computer#479 Pulls rklaehn's regenerated animations (all 8 SVGs updated) and renames "Guaranteed connections" -> "Reliable connections" to match the source PR. Co-Authored-By: Claude Opus 4.8 (1M context) --- images/how-iroh-works/connect-by-key.svg | 40 +++-- images/how-iroh-works/embedding-phone.svg | 45 ++--- images/how-iroh-works/endpoint-startup.svg | 64 ++++--- images/how-iroh-works/hole-punching-lan.svg | 129 +++++++------- images/how-iroh-works/hole-punching.svg | 180 ++++++++++---------- images/how-iroh-works/publish-relay-dht.svg | 90 +++++----- images/how-iroh-works/publish-relay.svg | 53 +++--- images/how-iroh-works/routing-moves.svg | 47 +++-- what-is-iroh.mdx | 2 +- 9 files changed, 313 insertions(+), 337 deletions(-) diff --git a/images/how-iroh-works/connect-by-key.svg b/images/how-iroh-works/connect-by-key.svg index 12083f0..f686cee 100644 --- a/images/how-iroh-works/connect-by-key.svg +++ b/images/how-iroh-works/connect-by-key.svg @@ -1,4 +1,5 @@ +