Merge pull request #5 from n0-computer/rae/docs-review2

Update based on feedback

Author: okdistribute

about/changelog.mdx

@@ -0,0 +1,4 @@
+---
+title: "Changelog"
+url: "https://iroh.computer/changelog"
+---

about/roadmap.mdx

@@ -0,0 +1,4 @@
+---
+title: "Roadmap"
+url: "https://iroh.computer/roadmap"
+---

concepts/discovery.mdx

@@ -3,25 +3,25 @@ title: "Discovery"
 ---
 
 
-Discovery is the glue that connects an [Endpoint](/concepts/endpoints#endpoint-identifiers) to something we can dial. Discovery services resolve EndpointIds to either a home Relay URL or direct-dialing information. 
+Discovery is the glue that connects an [Endpoint](/concepts/endpoints#endpoint-identifiers) to something we can dial. Discovery services resolve EndpointIDs to either a home Relay URL or direct-dialing information. 
 
 <Note>
   More details on discovery in the discovery module [documentation](https://docs.rs/iroh/latest/iroh/discovery/index.html)
 </Note>
 
-Endpoint discovery is an automated system for an [Endpoint](/concepts/endpoints) to retrieve addressing information. Each iroh endpoint will automatically publish their own addressing information with configured discovery services. Usually this means publishing which [Home Relay](/concepts/relay#home-relay) an endpoint is findable at, but they could also publish their direct addresses.
+Endpoint discovery is an automated system for an [Endpoint](/concepts/endpoints) to retrieve addressing information. Each iroh endpoint will automatically publish their own addressing information with configured discovery services. Usually this means publishing which [Home Relay](/concepts/relays) an endpoint is findable at, but they could also publish their direct addresses.
 
 
 ## Discovery Services
 
-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.
+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 | Default |
 | --- | --- | --- |
-| [DNS](#node-discovery-via-dns) | uses a custom Domain Name System server | ✅ Enabled |
+| [DNS](#endpoint-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) |
+| [Pkarr](#endpoint-announces-via-pkarr) | uses Pkarr Servers over HTTP | ✅ Enabled (via DNS) |
 |  [DHT](#dht-discovery) | uses the BitTorrent Mainline DHT | ❌ Disabled |
 
 ### The motivation
@@ -32,27 +32,27 @@ 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
 computers inside their local NAT.
 
-But even with holepunching, you need to know *where* to dial. Dialing a node in
+But even with holepunching, you need to know *where* to dial. Dialing an endpoint in
 iroh needs either an IP address to talk to, or the URL of a relay to which the
-remote node is connected. To make things easier, you can use
+remote endpoint is connected. To make things easier, you can use
 [tickets](/concepts/tickets) early-on. Tickets are easily encodable
-bytestrings that contain a node id, socket addresses and a relay URL. Tickets
+bytestrings that contain an endpoint ID, socket addresses and a relay URL. Tickets
 work well, but they are long - and they expire: People change networks or
 relays, and then old tickets cannot find you anymore. So while tickets work well
 in some scenarios, they are not frictionless or universally usable.
 
-But what if you didn’t need to know the relay URL or socket address in order to
-dial a node? Could we enable iroh users to dial peers using _the least amount of
-information possible_, ie can we enable dialing _only by Node ID_, and no other
+But what if you didn't need to know the relay URL or socket address in order to
+dial an endpoint? Could we enable iroh users to dial peers using _the least amount of
+information possible_, ie can we enable dialing _only by EndpointID_, and no other
 address data?
 
 ### The solution
 
-We had two “guiding lights” while doing research on global node discovery:
+We had two "guiding lights" while doing research on global endpoint discovery:
 
 First, we needed to see a path forward that would allow for a fully distributed
 topology, even if our first solution had a federated structure. If we (or some
-contributor) wanted to create or opt into a fully p2p version of global node
+contributor) wanted to create or opt into a fully p2p version of global endpoint
 discovery in the future, that needed to work in tandem with whatever federated
 solution we came up with.
 
@@ -61,7 +61,7 @@ protocols and specs unnecessarily. Can we instead leverage standards that have
 stood the test of time (and scrutiny) in novel ways to solve our problem? It
 turns out, we can! And we can do it using one of the oldest and most dependable
 technologies we have on the internet: DNS. Using the DNS standard along side
-Pkarr (public-key addressable resource records), **we now have global node
+Pkarr (public-key addressable resource records), **we now have global endpoint
 discovery in iroh**!
 
 ## The approach
@@ -74,53 +74,52 @@ names_ to [_resource
 records_](https://datatracker.ietf.org/doc/html/rfc1035#section-3.2), of which
 IP addresses are one type. Pkarr allows us to publish DNS records that resolve
 **elliptic curve keys** (not domain names) to resource records instead. Our
-**Node IDs** in iroh are elliptic curve public keys. This means we can publish
-an association between iroh Node IDs and some resource records. Importantly,
+**EndpointIDs** in iroh are elliptic curve public keys. This means we can publish
+an association between iroh EndpointIDs and some resource records. Importantly,
 these records are signed, so that you can verify that the record was actually
-published by the node with the given Node ID.
-
-As long as iroh has a Node ID and its associated relay URL (the address of the
-relay server that node uses to hole-punch and proxy relay packets), we can dial
-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
+published by the endpoint with the given EndpointID.
+
+As long as iroh has an EndpointID and its associated relay URL (the address of the
+relay server that endpoint uses to hole-punch and proxy relay packets), we can dial
+that endpoint. So the Pkarr packet currently only needs to contain the EndpointID and
+the relay URL of its preferred relay server (which we call its "home relay").
+When Pkarr publishing is enabled on your iroh endpoint, your endpoint will create a
+Pkarr packet with its EndpointID and relay URL, sign it, and defaults to publishing
 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
-ID for this to work,
+From there, others can discover your dialing information by resolving your EndpointID using regular DNS. It's worth noting that others must still learn your endpoint
+ID for this to work.
 
-The following sections describe the format of the Pkarr publishing records and Node discovery via DNS queries in greater detail.
+The following sections describe the format of the Pkarr publishing records and endpoint discovery via DNS queries in greater detail.
 
-## Node discovery via DNS
+## Endpoint 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 endpoint. 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.<z32-endpoint-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)
+- `<z32-endpoint-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).
 
 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 endpoint, e.g. `https://euw1-1.derp.iroh.network`.
+- `addr=<addr> <addr> ..` A space-separated list of socket addresses for this iroh endpoint. 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`
+## Endpoint announces via `pkarr`
 
-Nodes announce their address information in
+Endpoints announce their address information in
 [Pkarr](https://github.com/Nuhvi/pkarr/) signed packets. The TXT records, as
 described below, are added to the `answers` section of a DNS server. Their name
-must be `_iroh.<node-id>.` The encoded node ID must be the root name, no other
+must be `_iroh.<endpoint-id>.` The encoded endpoint 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
@@ -137,26 +136,3 @@ 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
-
-**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.
-
-<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/endpoints.mdx

@@ -44,7 +44,7 @@ See the [EndpointID](https://docs.rs/iroh/latest/iroh/type.EndpointId.html) docu
 Endpoint Addresses or [`EndpointAddrs`](https://docs.rs/iroh/latest/iroh/struct.EndpointAddr.html) are a common struct you'll interact when working with iroh to tell iroh what & where to dial. In rust they look like this:
 
 ```rust
-pub struct Addr {
+pub struct EndpointAddr {
     pub id: PublicKey,
     pub addrs: BTreeSet<TransportAddr>,
 }
@@ -81,12 +81,34 @@ 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
+### What to persist in your application
 
-If you're persisting the contents of `EndpointAddrs` 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.
+When storing endpoint information in your application database, what you should
+persist depends on whether you're using discovery:
+
+**If you're using discovery (recommended):**
+Store just the `EndpointID`. When you need to connect, construct an
+`EndpointAddr` from the ID and let discovery resolve the current dialing
+details. This is the most robust approach since relay URLs and direct addresses
+can change frequently in P2P networks.
+
+```rust
+// Store in your database
+let endpoint_id: EndpointId = ...;
+
+// Later, when connecting
+let addr = EndpointAddr::from(endpoint_id);
+endpoint.connect(addr, ALPN).await?;
+```
+
+**If you're not using discovery:**
+You'll need to store full `EndpointAddr` information (including the `addrs`
+field with relay and direct address information). Without discovery, iroh has no
+way to resolve an `EndpointID` to dialing details.
+
+Keep in mind that stored dialing details can become stale quickly. Providing
+outdated information may slow down connection establishment as iroh tries
+addresses that no longer work before falling back to other methods.
 
 ## Building on Endpoints
 

concepts/holepunching.mdx

@@ -6,7 +6,12 @@ When two devices want to connect directly over the internet, they face a common
 
 ## 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.
+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
+challenging.
 
 Traditionally, this problem was solved by:
 - **Port forwarding**: Manually configuring your router to allow specific connections (tedious and requires technical knowledge)
@@ -16,7 +21,7 @@ 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.
+**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.
 
 Here's how it works:
 
@@ -33,9 +38,9 @@ Through the relay, peers exchange their:
 
 ### 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.
+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 NAT creates a mapping and the firewall creates a temporary rule allowing responses from B. When peer B sends a packet to peer A at the same moment, B's NAT and firewall do the same.
 
-Because both routers now have rules expecting traffic from each other, the packets get through, and a direct connection is established!
+Because both NAT mappings are established and both firewalls now have rules expecting traffic from each other, the packets get through, and a direct connection is established!
 
 ### 4. Fallback to Relay