update docs for 1.0-rc.1

about/faq.mdx

@@ -47,15 +47,17 @@ Running your own relay doesn't affect interoperability. Your endpoints can still
 
 Yes.
 When you share a `EndpointAddr`s with "direct addresses", then iroh will try to use these addresses to establish a connection with or without a relay.
-If you're in a local network together you can enable [local network discovery](https://docs.rs/iroh/latest/iroh/endpoint/struct.Builder.html#method.discovery_local_network) to help establish connections in LANs even when the `EndpointAddr` doesn't contain direct addresses.
+If you're in a local network together you can enable [local network address lookup](/connecting/local-address-lookup) to help establish connections in LANs even when the `EndpointAddr` doesn't contain direct addresses.
 
 
 ## How can I control which relay servers iroh connects to?
 
 Iroh will only talk to relay servers that it knows URLs for.
 By default iroh is configured with 3 relay servers from the [default `RelayMap`](https://docs.rs/iroh/latest/iroh/defaults/prod/index.html).
-If you do not disable the default discovery services or other discovery services, then iroh might connect to relay servers discovered that way.
-By changing iroh's relay mode or relay map you can control the home relay the endpoint connects to, and by wrapping or writing your own `Discovery` service, you gain control over the relay URLs iroh can discover.
+If your endpoint has address lookup services configured (which is
+the default with the `N0` preset), then iroh might connect to 
+relay servers discovered that way.
+By changing iroh's relay mode or relay map you can control the home relay the endpoint connects to, and by wrapping or writing your own `AddressLookup` service, you gain control over the relay URLs iroh can discover.
 
 
 ## How can I monitor endpoint connection status to update a UI?
@@ -75,15 +77,16 @@ This returns an `impl Watchable<Value = bool>` that reflects whether the endpoin
 Iroh gives you full control over which endpoints are allowed to connect via [endpoint hooks](/connecting/endpoint-hooks). Hooks let you intercept incoming connections before they're accepted, so you can allow or reject them based on the connecting endpoint's ID, your own allowlist/denylist logic, or any application-specific policy.
 
 
-## What is "Discovery" in iroh and which one should I enable?
+## What is "Address Lookup" in iroh and which one should I enable?
 
-For most usage, using the services that are enabled by default in the `iroh::Endpoint::builder` is the best default.
-Discovery helps iroh find ways to connect to a specific Endpoint ID.
+For most usage, using the services that are enabled with the `iroh::endpoint::presets::N0` preset is the best default.
+
+Address Lookup helps iroh find ways to connect to a specific Endpoint ID.
 The Endpoint ID on its own can only be used to identify if you're talking to the right recipient, but doesn't tell how to address the recipient on its own.
-Via configured discovery mechanisms, iroh resolves an Endpoint ID to IP addresses and relay URLs that help to actually attempt a connection.
-For more information on available discovery mechanisms, take a look at the [address lookup module](https://docs.rs/iroh/latest/iroh/address_lookup/index.html).
-It's also possible to combine multiple discovery mechanisms at once, or write your own.
-We think it's particularly helpful to write application-specific discovery mechanisms that are tailored to an application's need.
+Via configured address lookup mechanisms, iroh resolves an Endpoint ID to IP addresses and relay URLs that help to actually attempt a connection.
+For more information on available address lookup mechanisms, take a look at the [address lookup docs](/concepts/address-lookup).
+It's also possible to combine multiple address lookup mechanisms at once, or write your own.
+We think it's particularly helpful to write application-specific address lookup mechanisms that are tailored to an application's need.
 
 
 ## What ports does iroh use?
@@ -105,8 +108,8 @@ Iroh supports custom transports, which means you can route connections over Tor.
 The company behind iroh is number 0.
 It is partly venture capital and partly founder backed (as in: founders have invested their own money).
 Number 0 is healthy and has investors we actually think are a value-add.
-We earn revenue through [Iroh Services](https://services.iroh.computer), which provides managed relay and DNS discovery infrastructure to keep your endpoints connected, from free public infrastructure for development and testing to dedicated cloud deployments for production.
-We rely on iroh remaining open source, and are committed to keeping it that way, including server-side code for relays and DNS discovery.
+We earn revenue through [Iroh Services](https://services.iroh.computer), which provides managed relay and DNS address lookup infrastructure to keep your endpoints connected, from free public infrastructure for development and testing to dedicated cloud deployments for production.
+We rely on iroh remaining open source, and are committed to keeping it that way, including server-side code for relays and DNS address lookup.
 
 
 ## How does iroh compare to WebRTC?
@@ -115,7 +118,7 @@ Both iroh and WebRTC solve the same core problem (establishing direct P2P connec
 
 **WebRTC** was designed for real-time media (audio and video) in browsers. It brings a complex stack: ICE for NAT traversal, STUN/TURN for relay, DTLS for encryption, SCTP for data channels, and a signaling layer that you have to implement yourself (WebRTC deliberately leaves signaling unspecified). This flexibility is powerful but adds significant complexity and is more expensive to run at scale.
 
-**Iroh** is built around QUIC (TLS 1.3) and focuses on reliable, encrypted data connections. The API is simpler: you connect to an endpoint ID and get a QUIC connection. Relays are stateless and cheap. Hole-punching works roughly 9 out of 10 times. There's no signaling layer to design; discovery mechanisms handle address resolution.
+**Iroh** is built around QUIC (TLS 1.3) and focuses on reliable, encrypted data connections. The API is simpler: you connect to an endpoint ID and get a QUIC connection. Relays are stateless and cheap. Hole-punching works roughly 9 out of 10 times. There's no signaling layer to design; address lookup mechanisms handle address resolution.
 
 - **Browser support.** Both WebRTC and iroh work in browsers. [Get started with iroh in the browser](https://docs.iroh.computer/deployment/other-languages#webassembly-and-browsers). However, WebRTC remains the only choice for hole-punched connections due to the current state of Web APIs.
 - **Media streaming.** WebRTC has first-class support for audio and video. Iroh is a general-purpose data transport, but you can run [MoQ (Media over QUIC)](https://www.iroh.computer/blog/secure-video-everywhere) on top of iroh for low-latency media streaming.
@@ -148,7 +151,7 @@ Iroh is designed to be modular: you get a solid, reliable connection layer and c
 
 Where iroh tends to win:
 
-- **Peer discovery and NAT traversal.** Iroh's [NAT traversal](/concepts/nat-traversal) and discovery story is significantly smoother. Getting peers to find each other reliably is one of the hardest parts of libp2p in practice; iroh has largely solved this.
+- **Peer discovery and NAT traversal.** Iroh's [NAT traversal](/concepts/nat-traversal) and address lookup story is significantly smoother. Getting peers to find each other reliably is one of the hardest parts of libp2p in practice; iroh has largely solved this.
 - **Direct messaging.** Iroh gives you reliable, encrypted QUIC connections directly to specific peers. Straightforward to build routing or direct message delivery on top of.
 - **Gossip.** [iroh-gossip](https://github.com/n0-computer/iroh-gossip/) provides gossipsub-like fan-out on top of iroh connections.
 - **Blob transfer.** Iroh has a built-in [blob transfer protocol](https://docs.rs/iroh-blobs) for exchanging hash-addressed data, similar to what you'd use IPFS for.
@@ -178,7 +181,7 @@ Adopting the current best post-quantum-secure algorithm, for example Xyber, woul
 A Xyber public key is 37x larger than an Ed25519 public key.
 This has implications for connection establishment speed:
 For example, the initial handshake for a connection wouldn't fit into a normal UDP packet anymore.
-It also means DNS packets used for DNS discovery at the moment might get fragmented, etc.
+It also means DNS packets used for DNS address lookup at the moment might get fragmented, etc.
 It would also mean Endpoint IDs would be exactly 37x as big.
 To support post-quantum-cryptography, we would need to trade off usability with the risk should a sufficiently powerful quantum computers would become real.
 We believe it is much more important to serve existing use cases efficiently, so they have encryption *today*.

concepts/discovery.mdx → concepts/address-lookup.mdx

@@ -1,30 +1,26 @@
 ---
-title: "Discovery"
+title: "Address Lookup"
 ---
 
-
-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. 
+Address Lookup is the glue that connects an [Endpoint ID](/concepts/endpoints#endpoint-identifiers) to something we can dial. Address Lookup services resolve Endpoint IDs to either their home Relay URL or direct-dialing information.
 
 <Note>
-  More details on discovery in the address lookup module [documentation](https://docs.rs/iroh/latest/iroh/address_lookup/index.html)
+  More details can be found in the address lookup module [documentation](https://docs.rs/iroh/latest/iroh/address_lookup/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/relays) an endpoint is findable at, but they could also publish their direct addresses.
-
-
-## Discovery Services
+Address Lookup services form an automated system for an [Endpoint](/concepts/endpoints) to retrieve addressing information. Each iroh endpoint will automatically publish their own addressing information with configured address lookup services. Usually this means publishing which [Home Relay](/concepts/relays) an endpoint is findable at, but they could also publish their direct addresses.
 
-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.
+## Address Lookup Services
 
+iroh ships several address lookup implementations. **By default, iroh uses DNS/Pkarr address lookup** to resolve EndpointIDs to addresses. It publishes signed records to a server and resolves them via DNS.
 
 | Name | Description | Default |
 | --- | --- | --- |
-| [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](#endpoint-announces-via-pkarr) | uses Pkarr Servers over HTTP | ✅ Enabled (via DNS) |
-|  [DHT](#dht-discovery) | uses the BitTorrent Mainline DHT | ❌ Disabled |
+| [DNS/Pkarr](#endpoint-address-lookup-via-dns) | publishes signed records to a server and resolves them over DNS | ✅ Enabled |
+| [Local](/connecting/local-address-lookup) | uses an mDNS-like system to find endpoints on the local network | ❌ Disabled |
+| [DHT](/connecting/dht-address-lookup) | publishes the same signed records to the BitTorrent Mainline DHT | ❌ Disabled |
 
-### The motivation
+## Background on address lookup and DNS/Pkarr
 
 We want iroh to establish connections with as little friction as possible. Our
 first big push toward chipping away at this goal was adding [NAT traversal](/concepts/nat-traversal) into
@@ -48,21 +44,21 @@ address data?
 
 ### The solution
 
-We had two "guiding lights" while doing research on global endpoint discovery:
+We had two "guiding lights" while doing research on global endpoint address lookup:
 
 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 endpoint
-discovery in the future, that needed to work in tandem with whatever federated
+address lookup in the future, that needed to work in tandem with whatever federated
 solution we came up with.
 
 Second, it was very important for us as an organization that we do not invent
-protocols and specs unnecessarily. Can we instead leverage standards that have
+protocols and specs unnecessarily. Can we instead build on 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 endpoint
-discovery in iroh**!
+address lookup in iroh**!
 
 ## The approach
 
@@ -85,16 +81,16 @@ that endpoint. So the Pkarr packet currently only needs to contain the EndpointI
 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 [n0.computer](https://n0.computer).
+on an `iroh-dns-server` instance that is run by [n0.computer](https://n0.computer).
 
 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 endpoint discovery via DNS queries in greater detail.
+The following sections describe the format of the Pkarr publishing records and endpoint address lookup via DNS queries in greater detail.
 
-## Endpoint discovery via DNS
+## Endpoint address lookup 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 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):
+When connecting to an unknown `EndpointId`, the DNS address lookup mechanism in iroh will perform a DNS query to discover relays or addresses for the endpoint. The DNS address lookup 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-endpoint-id>.<origin-domain> TXT`
 
@@ -111,7 +107,7 @@ This spec defines the following attributes:
 - `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).
+**Ready to use DNS address lookup?** Learn how to configure DNS address lookup in your application in the [DNS Address Lookup guide](/connecting/dns-address-lookup).
 </Note>
 
 ## Endpoint announces via `pkarr`
@@ -126,13 +122,13 @@ 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
 [`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
-iroh natively, see below for our plans).
+BitTorrent Mainline DHT, as specified by Pkarr. iroh supports this through
+[DHT address lookup](/connecting/dht-address-lookup), which is opt-in.
 
 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.
+**Want to publish via Pkarr?** This is handled automatically when using DNS address lookup. See the [DNS Address Lookup guide](/connecting/dns-address-lookup) for configuration details.
 </Note>