From 506e4b7f2ead07baef7d8e45976a1cf84ab02e8a Mon Sep 17 00:00:00 2001 From: Rae McKelvey <633012+okdistribute@users.noreply.github.com> Date: Mon, 15 Dec 2025 15:03:40 -0800 Subject: [PATCH 1/4] remove reliance on p2p language --- concepts/discovery.mdx | 2 +- concepts/endpoints.mdx | 12 ++++++------ concepts/holepunching.mdx | 6 ++---- concepts/protocols.mdx | 6 ++++-- concepts/relays.mdx | 2 +- concepts/tickets.mdx | 2 +- connecting/creating-endpoint.mdx | 10 ++-------- deployment/dedicated-infrastructure.mdx | 2 +- deployment/wasm-browser-support.mdx | 6 ++++-- examples/chat.mdx | 7 +++++-- examples/examples.mdx | 4 ++-- index.mdx | 6 +++--- protocols/automerge.mdx | 8 ++++---- protocols/blobs.mdx | 4 ++-- protocols/using-quic.md | 2 +- protocols/writing-a-protocol.mdx | 2 +- what-is-iroh.mdx | 20 ++++++++++---------- 17 files changed, 50 insertions(+), 51 deletions(-) diff --git a/concepts/discovery.mdx b/concepts/discovery.mdx index 1123658..92e8cf7 100644 --- a/concepts/discovery.mdx +++ b/concepts/discovery.mdx @@ -29,7 +29,7 @@ There are four different implementations of the discovery service in iroh. **By We want iroh to establish connections with as little friction as possible. Our first big push toward chipping away at this goal was adding [holepunching](/concepts/holepunching) into iroh. Now, devs no longer need to worry about opening up ports on their servers -/ firewalls or be resigned to only creating peer-to-peer connections to +/ firewalls or be resigned to only creating connections to computers inside their local NAT. But even with holepunching, you need to know *where* to dial. Dialing an endpoint in diff --git a/concepts/endpoints.mdx b/concepts/endpoints.mdx index b74f8bd..68cc8fa 100644 --- a/concepts/endpoints.mdx +++ b/concepts/endpoints.mdx @@ -3,22 +3,22 @@ title: "Endpoints" --- An _endpoint_ is the main API interface to create connections to, and accept -connections from other iroh endpoints. The connections are peer-to-peer and +connections from other iroh endpoints. The connections are end-to-end encrypted. Endpoints have a `EndpointID` (the public half of an Ed25519 keypair) and the private key used to sign and decrypt messages. Generally, an application will have a single endpoint instance. This ensures all -the connections made share the same peer-to-peer connections to other iroh +the connections made share the same connections to other iroh endpoints, while still remaining independent connections. This will result in more optimal network behaviour. ## Connections -Because we're in a peer-to-peer context, either endpoint might be operating as -the "server", so we use `connect` and `accept` to distinguish between the two. -The `connect` method is used to create a new connection to a remote endpoint, -while `accept` is used to accept incoming connections from a remote endpoint. +Either endpoint might be operating as the "server", so we use `connect` and +`accept` to distinguish between the two. The `connect` method is used to create +a new connection to a remote endpoint, while `accept` is used to accept incoming +connections from a remote endpoint. Connections are full-fledged QUIC connections, giving you access to most features of QUIC / HTTP3, including bidirectional and unidirectional streams. diff --git a/concepts/holepunching.mdx b/concepts/holepunching.mdx index 1005ecf..2f1c7ab 100644 --- a/concepts/holepunching.mdx +++ b/concepts/holepunching.mdx @@ -10,16 +10,14 @@ Imagine you're trying to video call a friend. Both of you are behind routers at home. When you try to connect directly to each other, your routers' firewalls block the incoming connection because they don't recognize it as a response to something you requested. The combination of NAT (which translates addresses) and -firewall rules (which filter traffic) makes direct peer-to-peer connections +firewall rules (which filter traffic) makes direct connections challenging. Traditionally, this problem was solved by: - **Port forwarding**: Manually configuring your router to allow specific connections (tedious and requires technical knowledge) - **Relay servers**: Routing all traffic through a third-party server (slow and expensive) -Neither solution is ideal for peer-to-peer applications. - -## The Solution: Holepunching +## The Innovation: Holepunching **Holepunching** is a clever technique that works around NAT and firewall restrictions to allow direct connections between peers without manual configuration or relying entirely on relay servers. diff --git a/concepts/protocols.mdx b/concepts/protocols.mdx index 0d788e6..40dec54 100644 --- a/concepts/protocols.mdx +++ b/concepts/protocols.mdx @@ -7,12 +7,14 @@ behavior. Once you've established an iroh connection, protocols determine what happens next: transferring files, syncing documents, broadcasting messages, or whatever your application needs. -iroh provides the encrypted, peer-to-peer connections - protocols define what to +iroh provides the pool of encrypted QUIC connections - protocols define what to do with them. ## Peer-to-peer protocols -Unlike HTTP's client/server model where one side only sends requests and the other only responds, peer-to-peer protocols typically support **both** initiating and accepting connections on the same endpoint. +Unlike HTTP's client/server model where one side only sends requests and the +other only responds, peer-to-peer protocols typically support **both** +initiating and accepting connections on the same endpoint. This means: - Any peer can request data from any other peer diff --git a/concepts/relays.mdx b/concepts/relays.mdx index 11f88fa..3b3b287 100644 --- a/concepts/relays.mdx +++ b/concepts/relays.mdx @@ -37,7 +37,7 @@ Relay code is open source! You can run your own relay server, or [pick a hosting provider](https://n0des.iroh.computer). -### Why this architecture is powerful +## Why this architecture is powerful This approach makes uptime management significantly easier compared to traditional client-server architectures: diff --git a/concepts/tickets.mdx b/concepts/tickets.mdx index eb2bb56..abd5107 100644 --- a/concepts/tickets.mdx +++ b/concepts/tickets.mdx @@ -62,7 +62,7 @@ The postcard encoding keeps tickets compact despite containing multiple pieces o ## Security considerations -**Tickets contain IP addresses**: When you create a ticket, it embeds the IP addresses you're currently reachable at. Sharing a ticket means sharing your IP address with whoever receives it. This is intentional - it enables direct peer-to-peer connections without a central server. +**Tickets contain IP addresses**: When you create a ticket, it embeds the IP addresses you're currently reachable at. Sharing a ticket means sharing your IP address with whoever receives it. This is intentional - it enables direct connections without a central server. This is actually *better* than many P2P systems that broadcast your IP to all peers. With tickets, you form a "cozy network" between peers you explicitly choose to connect with. diff --git a/connecting/creating-endpoint.mdx b/connecting/creating-endpoint.mdx index 0e0aa17..8a3f65c 100644 --- a/connecting/creating-endpoint.mdx +++ b/connecting/creating-endpoint.mdx @@ -6,14 +6,8 @@ An endpoint is the core building block of an iroh node. It manages network connections, handles incoming and outgoing traffic, and provides the necessary infrastructure for implementing protocols. -Once you have an Endpoint, you can use it to create connections or accept incoming connections from other endpoints. - -Unlike HTTP servers, which listen on specific ports, iroh Endpoints use a peer-to-peer -model to establish connections. This means that endpoints can connect directly -to each other without relying on a central server. - -This means that endpoints can be more resilient to network issues and can operate in -a wider range of network environments. +Once you have an Endpoint, you can use it to create connections or accept +incoming connections from other endpoints. ## Creating an Endpoint diff --git a/deployment/dedicated-infrastructure.mdx b/deployment/dedicated-infrastructure.mdx index e6cbc5c..3e1d032 100644 --- a/deployment/dedicated-infrastructure.mdx +++ b/deployment/dedicated-infrastructure.mdx @@ -8,7 +8,7 @@ DNS and end-to-end encryption over relays. This infrastructure comprises: 1. [Relays](/concepts/relays) 2. [Discovery Servers (DNS)](/concepts/discovery) -Relays forward traffic when direct peer-to-peer connections are not possible as well +Relays forward traffic when direct connections are not possible as well as facilitates holepunching for direct connections. These servers are managed and maintained by [the n0 team](https://n0.computer), and are shared by a global public network of developers. diff --git a/deployment/wasm-browser-support.mdx b/deployment/wasm-browser-support.mdx index 38d25a2..f75fc3a 100644 --- a/deployment/wasm-browser-support.mdx +++ b/deployment/wasm-browser-support.mdx @@ -28,8 +28,10 @@ This is because we can't port our hole-punching logic in iroh to browsers: They Keep in mind that *connections are end-to-end encrypted*, as always with iroh. So even though traffic from browsers is always relayed, it can't be decrypted by the relay. -There are other ways of getting peer-to-peer connections going, such as WebTransport with `serverCertificateHashes`, or WebRTC. -We may expand iroh's browser support to make use of these to try to generate fully peer-to-peer connections even when a browser node is involved in the connection. +There are other ways of getting direct connections going, such as WebTransport +with `serverCertificateHashes`, or WebRTC. We may expand iroh's browser support +to make use of these to try to generate direct connections even when a browser +node is involved in the connection. ### `iroh` crate features diff --git a/examples/chat.mdx b/examples/chat.mdx index 1f686f7..3d413b0 100644 --- a/examples/chat.mdx +++ b/examples/chat.mdx @@ -1,10 +1,13 @@ import { YouTube } from '@/components/youtube' -## Building a P2P Chat Application with Iroh +## Building a Chat Application with Iroh -This tutorial demonstrates how to build a peer-to-peer chat application from scratch using Rust and the Iroh library. While this implementation is simplified, it illustrates core concepts of P2P networking and the Iroh gossip protocol. +This tutorial demonstrates how to build a peer-to-peer chat application from +scratch using Rust and the Iroh library. While this implementation is +simplified, it illustrates core concepts of the iroh gossip +protocol. The code in the above video differs slightly from the code presented below. We recommend watching the video and following along until you get comfortable. When you are ready for a deeper dive into the code, walk through this tutorial. diff --git a/examples/examples.mdx b/examples/examples.mdx index e43baed..cc21494 100644 --- a/examples/examples.mdx +++ b/examples/examples.mdx @@ -9,7 +9,7 @@ title: "Examples" icon="image" href="https://www.iroh.computer/sendme" > - Sendme will connect your devices directly & transfer files peer-to-peer, + Sendme will connect your devices directly & transfer files, without any accounts or configuration. -A peer-to-peer multiplayer extension for Godot based on iroh. +A multiplayer extension for Godot based on iroh. - Store and transfer large binary files peer-to-peer. + Store and transfer large binary files. - Build low-latency peer-to-peer audio and video streaming applications. + Build low-latency audio and video streaming applications. Date: Mon, 15 Dec 2025 15:15:35 -0800 Subject: [PATCH 2/4] Refine core features and use cases in documentation for clarity and consistency --- what-is-iroh.mdx | 25 +++++++++++++++---------- 1 file changed, 15 insertions(+), 10 deletions(-) diff --git a/what-is-iroh.mdx b/what-is-iroh.mdx index 8105b22..15d93f0 100644 --- a/what-is-iroh.mdx +++ b/what-is-iroh.mdx @@ -7,25 +7,30 @@ the building blocks to create applications that can communicate using fast, cheap, and reliable connections. ## Core features -- **Direct**: iroh enables direct connections between +- **Fast**: iroh enables direct connections between devices, allowing them to communicate without relying on centralized servers. - It uses relay servers as a fallback when direct connections are not possible. -- **Secure**: All connections established through iroh are - authenticated and encrypted end-to-end using the QUIC protocol, ensuring data - privacy and integrity. +- **Reliable**: iroh is designed to work in challenging network conditions. It +uses relay servers as a fallback when direct connections are not possible. +- **Secure**: All connections established through iroh are authenticated and +encrypted end-to-end using the QUIC protocol, ensuring data privacy and +integrity. - **Modular**: iroh is built around a system of composable protocols that can be mixed and matched to suit the needs of different applications. This allows developers to easily add functionality such as file sharing, messaging, and real-time collaboration. ## Use cases -- **Local-first, offline-first applications**: iroh provides the networking foundation for - building applications that can operate without 100% reliance on servers. -- **File sharing**: With protocols like iroh-blobs, iroh enables efficient - file sharing. -- **Structured data**: iroh's support for flexible data protocols allows +- **Local-first, offline-first, peer-to-peer applications**: iroh provides the networking foundation for + building applications that can operate without reliance on servers. +- **Files & blobs**: With protocols like [iroh-blobs](/protocols/blobs), iroh enables efficient + file transfer. +- **Structured data**: iroh's support for flexible data protocols like [KV +CRDTs](/protocols/kv-crdts) and [Automerge](/protocols/automerge) allows developers to build applications that support real-time collaborative editing and data synchronization. Any kind of CRDT or OT sync protocol can be integrated. +- **Real-time communication**: Build [chat applications](/examples/chat), [RPC +services](/protocols/rpc), and [streaming data](/protocols/streaming) with +iroh's communication protocols. ## Getting started To get started with iroh, check out the [quickstart guide](/quickstart) or explore the From 589f940202cb29e7163cbb8ade88fce77a6a35ef Mon Sep 17 00:00:00 2001 From: Rae McKelvey <633012+okdistribute@users.noreply.github.com> Date: Mon, 15 Dec 2025 15:17:33 -0800 Subject: [PATCH 3/4] change heading to be action oriented targeting app devs --- docs.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs.json b/docs.json index 4b30ced..dc7490a 100644 --- a/docs.json +++ b/docs.json @@ -43,7 +43,7 @@ ] }, { - "group": "Communicating over Iroh", + "group": "Building your App", "pages": [ "protocols/kv-crdts", "protocols/blobs", From 0bffdafab3164c3bd9036ef3930096d76fe74e9b Mon Sep 17 00:00:00 2001 From: Rae McKelvey <633012+okdistribute@users.noreply.github.com> Date: Mon, 15 Dec 2025 15:18:36 -0800 Subject: [PATCH 4/4] Add 'How it works' group to documentation navigation and expand it --- docs.json | 1 + 1 file changed, 1 insertion(+) diff --git a/docs.json b/docs.json index dc7490a..c4624fd 100644 --- a/docs.json +++ b/docs.json @@ -21,6 +21,7 @@ "examples/examples", { "group": "How it works", + "expanded": true, "pages": [ "concepts/endpoints", "concepts/tickets",