Merge pull request #3 from n0-computer/rae/docs-review

Docs ready for review

Author: okdistribute

about/changelog.mdx

@@ -2,4 +2,30 @@
 title: "Roadmap"
 ---
 
-Placeholder: High-level roadmap and planned features.
+## now
+
+## next
+
+#### Draft specification
+
+Draft a specification for the iroh protocol, outlining all open standards iroh uses, noting any deviations
+
+self-signed TLS
+QUIC
+ICE over QUIC
+STUN over QUIC
+DNS Discovery
+Pkarr
+MDNs
+WebSockets
+iroh relay
+finalize 1.0 spec
+ratify the iroh 1.0 wire protocol
+
+Finalize FFI integration
+protocol developers have a clear path for integrating rust protocols into other languages
+
+documentation refinement
+ensure documentation is accurate and robust
+
+## later

about/roadmap.mdx

@@ -14,17 +14,15 @@ Endpoint discovery is an automated system for an [Endpoint](/concepts/endpoints)
 
 ## Discovery Services
 
-There are four different implementations of the discovery service in iroh. iroh
-uses the DNS discovery system to resolve EndpointIds to addresses, but you can choose to opt-in and configure
-iroh to use any of the other discovery systems.
+There are four different implementations of the discovery service in iroh. **By default, iroh uses DNS discovery** to resolve EndpointIds to addresses. Local and DHT discovery are **disabled by default** and must be explicitly configured if you want to use them.
 
 
-| Name | Description | |
+| Name | Description | Default |
 | --- | --- | --- |
-| [DNS](/connecting/global-discovery) | uses a custom Domain Name System server |
-| [Local](/connecting/local-discovery) | uses an mDNS-like system to find endpoints on the local network |
-| [Pkarr](/connecting/global-discovery#pkarr-discovery) | uses Pkarr Servers over HTTP |
-|  [DHT](/conecting/global-discovery/#dht-discovery) | uses the BitTorrent Mainline DHT |
+| [DNS](#node-discovery-via-dns) | uses a custom Domain Name System server | ✅ Enabled |
+| [Local](#local-discovery) | uses an mDNS-like system to find endpoints on the local network | ❌ Disabled |
+| [Pkarr](#node-announces-via-pkarr) | uses Pkarr Servers over HTTP | ✅ Enabled (via DNS) |
+|  [DHT](#dht-discovery) | uses the BitTorrent Mainline DHT | ❌ Disabled |
 
 ### The motivation
 
@@ -87,7 +85,7 @@ that node. So the Pkarr packet currently only needs to contain the Node ID and
 the relay URL of its preferred relay server (which we call its “home relay”).
 When Pkarr publishing is enabled on your iroh node, your node will create a
 Pkarr packet with its Node ID and relay URL, sign it, and defaults to publishing
-on an `iroh-dns` server that is run by number0.
+on an `iroh-dns` server that is run by [the n0 team](https://n0.computer).
 
 From there, others can discover your dialing information by resolving your Node
 ID using regular DNS. It’s worth noting that others must still learn your node
@@ -97,21 +95,25 @@ The following sections describe the format of the Pkarr publishing records and N
 
 ## Node discovery via DNS
 
-When connecting to an unknown `EndpointId`, the DNS discovery mechanism in iroh will perform a DNS query to discover relays or addresses for the node. The DNS discovery is configured with a *origin domain* (which defaults to *dns.iroh.link*, a server run by n0). iroh will then perform a DNS query through the configured DNS resolver (which defaults to using the host system's nameservers):
+When connecting to an unknown `EndpointId`, the DNS discovery mechanism in iroh will perform a DNS query to discover relays or addresses for the node. The DNS discovery is configured with a *origin domain* (which defaults to *dns.iroh.link*, a server run by n0). iroh will then perform a DNS query through the configured DNS resolver (which defaults to using the host system's nameservers):
 
 `_iroh.<z32-node-id>.<origin-domain> TXT`
 
-- `_iroh` is the record name defined in this spec
-- `<z32-node-id>` is the [z32](https://crates.io/crates/z32) encoding of the 32-byte long `EndpointId` (which is a string of 52 characters)
-- `<origin-domain>` is the configured origin domain
-- `TXT` is the queried record type
+- `_iroh` is the record name defined in this spec
+- `<z32-node-id>` is the [z32](https://crates.io/crates/z32) encoding of the 32-byte long `EndpointId` (which is a string of 52 characters)
+- `<origin-domain>` is the configured origin domain
+- `TXT` is the queried record type
 
-The returned TXT records must contain a string value of the form `key=value`, as defined in [RFC1464](https://www.rfc-editor.org/rfc/rfc1464).
+The returned TXT records must contain a string value of the form `key=value`, as defined in [RFC1464](https://www.rfc-editor.org/rfc/rfc1464).
 
 This spec defines the following attributes:
 
-- `relay=<url>`: The home relay for this node, e.g. `https://euw1-1.derp.iroh.network`.
-- `addr=<addr> <addr> ..` A space-separated list of socket addresses for this iroh node. Each address is an IPv4 or IPv6 address with a port (e.g. `1.2.3.4:7367` or `[::1]:3521`
+- `relay=<url>`: The home relay for this node, e.g. `https://euw1-1.derp.iroh.network`.
+- `addr=<addr> <addr> ..` A space-separated list of socket addresses for this iroh node. Each address is an IPv4 or IPv6 address with a port (e.g. `1.2.3.4:7367` or `[::1]:3521`)
+
+<Note>
+**Ready to use DNS discovery?** Learn how to configure DNS discovery in your application in the [DNS Discovery guide](/connecting/dns-discovery).
+</Note>
 
 ## Node announces via `pkarr`
 
@@ -122,7 +124,7 @@ must be `_iroh.<node-id>.` The encoded node ID must be the root name, no other
 origin but `.` (the single dot) is permitted.
 
 Those packets are published to a Pkarr relay server, which is a HTTP service
-handling PUT requests with the signed packets. iroh’s Pkarr server is
+handling PUT requests with the signed packets. iroh's Pkarr server is
 [`iroh-dns-server`](https://crates.io/crates/iroh-dns-server), which serves the
 received records over DNS. Pkarr packets can also be published onto the
 bittorrent mainline DHT, as specified by Pkarr (this is not yet supported in
@@ -132,12 +134,29 @@ DNS servers that support this spec will receive these Pkarr signed packets,
 check their signature and format validity, and then serve each contained record,
 with the DNS server's configured *origin domain* appended to all record names.
 
+<Note>
+**Want to publish via Pkarr?** This is handled automatically when using DNS discovery. See the [DNS Discovery guide](/connecting/dns-discovery) for configuration details.
+</Note>
 
 ## Local Discovery
 
-Global servers aren't the only way to find other iroh endpoint. Iroh also supports local
+**Note: Local discovery is disabled by default and must be explicitly enabled.**
+
+Global servers aren't the only way to find other iroh endpoints. Iroh also supports local
 discovery, where endpoints on the same local network can find each other &
-exchange dialing information without a relay using mDNS.  This is useful for
-offline environments, or for bootstrapping a network before a relay is available. For
-more info on configuring local discovery, see the [local discovery
-documentation](/connecting/local-discovery).
+exchange dialing information without a relay using mDNS. This is useful for
+offline environments, or for bootstrapping a network before a relay is available.
+
+<Note>
+**Want to enable local discovery?** Learn how to configure and enable mDNS-based local discovery in the [Local Discovery guide](/connecting/local-discovery).
+</Note>
+
+## DHT Discovery
+
+**Note: DHT discovery is disabled by default and must be explicitly enabled.**
+
+The Distributed Hash Table (DHT) discovery uses the BitTorrent Mainline DHT to publish and discover node addresses in a fully decentralized manner. This allows nodes to find each other without relying on centralized DNS servers.
+
+<Note>
+**Want to enable DHT discovery?** Learn how to configure and enable DHT-based discovery in the [DHT Discovery guide](/connecting/dht-discovery).
+</Note>

concepts/discovery.mdx

@@ -2,4 +2,64 @@
 title: "Holepunching"
 ---
 
-Placeholder: Describe NAT traversal and holepunching techniques.
+When two devices want to connect directly over the internet, they face a common problem: **Network Address Translation (NAT)**. Most home and office networks use NAT, which acts like a one-way door—devices inside the network can reach out to the internet, but the internet can't easily reach back in.
+
+## The Problem: NAT Blocks Direct Connections
+
+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 block the incoming connection because they don't recognize it as a response to something you requested. This is NAT protecting your network.
+
+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
+
+**Holepunching** is a clever technique that tricks NAT routers into allowing direct connections between peers without manual configuration or relying entirely on relay servers.
+
+Here's how it works:
+
+### 1. Initial Contact Through a Relay
+
+Both peers first connect to a shared [relay server](/concepts/relays). The relay acts as a meeting point where peers can coordinate without being able to connect directly yet.
+
+### 2. Sharing Connection Information
+
+Through the relay, peers exchange their:
+- **Public IP addresses** (how they appear to the outside internet)
+- **Port numbers** (the specific door number the router assigned them)
+- **Local addresses** (in case they're on the same network)
+
+### 3. Simultaneous Outbound Connection
+
+Here's the magic: both peers try to connect to each other **at the same time**. When peer A sends a packet to peer B's public address, A's router creates a temporary rule allowing responses from B. When peer B sends a packet to peer A at the same moment, B's router does the same.
+
+Because both routers now have rules expecting traffic from each other, the packets get through, and a direct connection is established!
+
+### 4. Fallback to Relay
+
+If holepunching fails (some networks use particularly strict NAT configurations), iroh automatically falls back to routing traffic through the relay server. This ensures connections always work, even if they can't be direct.
+
+## Why This Matters
+
+With holepunching, iroh applications can:
+- **Connect directly** between devices without manual network configuration
+- **Reduce latency** by avoiding relay servers when possible
+- **Save bandwidth** by keeping data transfer peer-to-peer
+- **Maintain privacy** by not routing all traffic through third parties
+
+The best part? All of this happens automatically—you don't need to understand the technical details to benefit from it.
+
+## How iroh Implements Holepunching
+
+iroh uses a sophisticated holepunching implementation built on top of QUIC and integrates with the relay system. For technical details on the implementation, see:
+
+- [iroh's holepunching implementation](https://docs.rs/iroh/latest/iroh/endpoint/index.html#nat-traversal)
+- [Relay system documentation](/concepts/relays)
+- [Dedicated infrastructure setup](/deployment/dedicated-infrastructure)
+- [Endpoint configuration](https://docs.rs/iroh/latest/iroh/endpoint/struct.Endpoint.html)
+
+<Note>
+Holepunching works in most network configurations, but some corporate firewalls or cellular networks may still require relay fallback. iroh handles this automatically.
+</Note>

concepts/holepunching.mdx

@@ -19,6 +19,31 @@ There are situations where a direct connection _can't_ be established, and in th
 
 We're working on formally collecting the direct connection rate from production iroh networks. Anecdotal evidence points to the holepunching rate being around 90%, meaning 9 out of 10 times, a direct connection is established.
 
+### Why this architecture is powerful
+
+This approach makes uptime management significantly easier compared to
+traditional client-server architectures:
+
+**Stateless servers, stateful clients**  
+Unlike traditional servers that store your application's data and state, relay
+servers are just connection facilitators. All your business logic and data lives
+in your clients. This means:
+
+- **No database synchronization** - You don't need to worry about keeping multiple server databases in sync or handling data replication
+- **No state migration** - When a relay goes down, clients simply reconnect to another relay without any data loss or state transfer
+- **Simple server management** - Relay servers are lightweight and easy to spin up or down. No complex deployment procedures or data migration steps
+
+**Automatic failover**  
+iroh clients automatically try multiple relays when connecting. If one relay is unavailable, clients seamlessly fall back to another relay in your list without application-level retry logic. Your peers will find each other as long as at least one relay is reachable.
+
+**Multi-cloud resilience**  
+For even better guarantees, you can distribute relays across multiple cloud providers. If one provider experiences an outage, your application keeps running on relays hosted elsewhere. Since relays don't store state, you can freely mix providers without worrying about cross-cloud data consistency.
+
+**Cost-effective scaling**  
+Adding capacity means spinning up more lightweight relay instances, not provisioning databases or managing complex stateful server infrastructure. You can easily scale up for peak usage and scale down during quiet periods.
+
+This architecture inverts the traditional model: instead of treating servers as precious stateful resources and clients as disposable, relay-based architectures treat relays as disposable connection facilitators while clients own the application state and logic.
+
 ## Connection Changes
 
 During the lifespan of a connection, networking conditions can change, for

concepts/relays.mdx

@@ -25,7 +25,7 @@ use iroh::Endpoint;
 
 #[tokio::main]
 async fn main() {
-    let endpoint = Endpoint::builder().bind().await?;
+    let endpoint = Endpoint::bind().await?;
     // ...
 }
 ```
@@ -35,3 +35,13 @@ async fn main() {
 incoming connections
 2. `await` keyword is used to wait for the endpoint
 to be created in an asynchronous context.
+
+## Next Steps
+
+With an endpoint created, you can now start discovering and connecting to other endpoints.
+
+Explore the following guides to learn more:
+- [DNS Global Discovery](/connecting/dns-discovery)
+- [Local Network Discovery](/connecting/local-discovery)
+- [Gossip and Topic Broadcast](/connecting/gossip)
+- [Writing a Protocol](/protocols/writing-a-protocol)

connecting/creating-endpoint.mdx

@@ -9,41 +9,73 @@ home relay addresses. This allows any iroh endpoint to be discoverable globally,
 as long as they are connected to the same relay that is reachable from the public
 internet.
 
+## Using DNS Discovery
+
+DNS discovery is the default discovery mechanism in iroh, so you don't need to
+do anything special to enable it.
+
+[Number 0](https://n0.computer) provides a set of public DNS servers that are
+free to use, and are configured by default. You're more than welcome to run
+production systems using the public relays if you find performance acceptable.
+The public servers do rate-limit traffic, there is no guaranteed uptime. 
+
+If you need more capacity or uptime guarantees or SLAs, you can
+run your own DNS server, or [contact us about hosted DNS
+options](https://cal.com/team/number-0/n0-protocol-services?overlayCalendar=true).
+
+
 ```rust
 use iroh::Endpoint;
+use iroh_tickets::endpoint::EndpointTicket;
 
 #[tokio::main]
 async fn main() -> anyhow::Result<()> {
     let endpoint = Endpoint::bind().await?;
 
     println!("endpoint id: {:?}", endpoint.id());
+
+   let ticket = EndpointTicket::new(endpoint.addr());
+   println!("Share this ticket to let others connect to your endpoint: {ticket}");
+
     Ok(())
 }
 ```
 
-To discover other endpoints, you can use an EndpointId or a [Ticket](/concepts/tickets) that contains
+To discover other endpoints over DNS, you can use an EndpointId or a [Ticket](/concepts/tickets) that contains
 an EndpointId.
 
-## Dedicated DNS Server
+## Use your own DNS Server
 
 By default, iroh will look up the endpoint on a public shared instance of the
 DNS discovery server. If you'd like to run your own private DNS discovery server
 for more guaranteed privacy and uptime guarantees, you can configure iroh to use
 it.
 
 
+Two nodes must connect to the same DNS discovery server to find each other using
+DNS discovery.
+
 TODO: rust code for custom dns server
 
+## Disable DNS Discovery
+
+DNS discovery is opt-out, so if you don't want your endpoint to be discoverable
+via DNS, you can disable it by using the `Endpoint::empty_builder` method
+instead of `Endpoint::builder`.
+
+
+```rust
+use iroh::Endpoint;
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+      let endpoint = Endpoint::empty_builder().bind().await?;
+      // your code here
+      Ok(())
+}
+```   
+
 ## Important notes 
 
-1. DNS discovery is the default discovery mechanism in iroh, so you don't need
-   to do anything special to enable it.
-2. DNS discovery only publishes the home relay of an endpoint, not its direct
-   addresses. 
-3. DNS discovery is opt-out, so if you don't want your endpoint to be
-   discoverable via DNS, you can disable it by using the
-   `Endpoint::empty_builder` method instead of `Endpoint::builder`.
-4. Two nodes must connect to the same DNS discovery server to find each other using DNS discovery.