add more information

Author: okdistribute

about/faq.mdx

@@ -2,4 +2,102 @@
 title: "FAQ"
 ---
 
-Placeholder: Frequently asked questions and answers.
+## Does iroh use relay servers?
+
+Iroh uses relay servers to support establishing direct connections, to speed up initial connection times, and to provide a fallback should direct connections between two endpoints fail or be impossible otherwise.
+By default iroh is configured with three relay servers run by number 0.
+One in the US, one in Europe and one in Asia.
+We can afford to run these servers for free, because [hole-punching](https://en.wikipedia.org/wiki/Hole_punching_(networking)) rates with iroh are really high.
+Still, to prevent abuse, we rate-limit throughput through our public relays.
+
+
+## Can relays read the traffic they route?
+
+**No, all connections in iroh are end-to-end encrypted.**
+We use QUIC which is based on TLS 1.3.
+From the perspective of our QUIC implementation, the relay is "just another UDP socket" for sending encrypted packets around.
+Because the relays are relaying traffic, they theoretically know that Endpoint ID X talks to Endpoint ID Y and how many bytes are sent this way, but only for as long as these endpoints haven't established a direct connection yet.
+However, we don't record this data on our relays.
+
+
+## How secure is iroh's end-to-end encryption?
+
+Iroh provides a secure, encrypted, forward and backward-secret, authenticated data channel between you and the recipient and protects you both from eavesdroppers.
+This assumes the Endpoint ID you're connecting to was exchanged securely, e.g. via scanning a QR code, sharing a link with the Endpoint ID in an encrypted chat app or using a trusted server and the corresponding secret keys haven't been compromised.
+The established connection is a QUIC connection, which together with TLS 1.3 specifies how it's encrypted.
+This specification is widely used, for example as part of the latest generation of HTTP, HTTP3.
+Instead of PKI-based certificates, at the moment iroh uses self-signed certificates with Endpoint IDs to authenticate both ends of the connection, borrowing [the libp2p handshake specification](https://github.com/libp2p/specs/blob/master/tls/tls.md).
+In the future, we plan on switching to the [raw public key TLS certificate type](https://datatracker.ietf.org/doc/html/rfc7250) instead.
+To make use of this end-to-end encryption, no additional setup in iroh is required, it is always enabled.
+Be aware of security caveats to forward secrecy when using the [opt-in 0-RTT feature](https://docs.rs/iroh/latest/iroh/endpoint/struct.Connecting.html#method.into_0rtt).
+
+
+## What if number 0 stops running relay servers?
+
+The relay servers we run in production [are open-source](https://github.com/n0-computer/iroh/tree/main/iroh-relay), and we highly encourage you to run your own!
+You need a server with a public IP address and a DNS name that points to that IP address.
+Automatic TLS setup via [ACME](https://en.wikipedia.org/wiki/Automatic_Certificate_Management_Environment) is built into the iroh-relay code.
+Use the configured DNS name to add your relay to the [`RelayMap`](https://docs.rs/iroh/latest/iroh/endpoint/struct.Builder.html#method.relay_mode) you configure your iroh endpoint with.
+Running a custom relay server doesn't prevent you from connecting to others connected to other relay servers.
+
+
+## Is establishing a connection without relays or when offline possible?
+
+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.
+
+
+## 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.
+
+
+## What is "Discovery" 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.
+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 [discovery module](https://docs.rs/iroh/latest/iroh/discovery/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.
+
+
+## How is iroh development funded?
+
+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 from customers today through https://n0.computer/n0ps, and are re-launching an “AWS for iroh  protocols” in 2025.
+While it will be a service you can pay for, it won’t have special treatment beyond being convenient.
+We rely on iroh remaining open source, and are committed to keeping it that way, including server-side code for relays and DNS discovery.
+
+
+## How do iroh and libp2p compare?
+
+Generally, we've put a lot of effort into making iroh "peer to peer connections that *just work*".
+This means we've kept the scope small: There's no DHT, swarm, or gossipsub.
+Instead, what you get are reliable direct [QUIC](https://en.wikipedia.org/wiki/QUIC) connections between iroh endpoints.
+On top of these, some of said libp2p features can be implemented as *protocols* on top, see for example [iroh-gossip](https://github.com/n0-computer/iroh-gossip/) which provides gossipsub-like functionality.
+While there are some features in libp2p like a DHT implementation based on kademlia that don't exist in the iroh ecosystem yet, we believe the features iroh *does* have work better.
+The iroh project was founded by developers who were deeply involved with libp2p, and wanted to build a more focused library with less configuration that would be easier to deploy and use with high reliability.
+
+
+## Is iroh post-quantum-secure?
+
+No.
+Iroh uses Ed25519 for signing and X25519/P-256 for ECDH.
+These algorithms are not post-quantum-secure.
+Adopting the current best post-quantum-secure algorithm, for example Xyber, would incur a very significant network overhead:
+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 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*.
+We fully believe the work on post-quantum-cryptography is good and important and follow developments closely.

concepts/discovery.mdx

@@ -96,8 +96,6 @@ The following sections describe the format of the Pkarr publishing records and N
 
 ## Node discovery via DNS
 
-<img src="/images/dns.gif" alt="DNS Discovery Diagram" class="my-4 rounded-lg border border-gray-200 shadow-md" />
-
 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`

concepts/protocols.mdx

@@ -2,14 +2,25 @@
 title: "Protocols"
 ---
 
-Assuming we have two endpoints connected, yay! Now we just have to… do something… with that connection. That’s where protocols come in.
-
-## Introduction
+Iroh is organized into _protocols_: Composable networking software built on iroh
+connections. 
 
 A protocol sets up everything we need to both provide data we have locally when
 others request it, and ask other endpoints that run the protocol to do whatever
 business or application logic we need.
 
+The foundation of iroh is direct connections, which protocols use to extend up
+to higher-level functionality. When integrating iroh into an application you can
+use protocols to quickly add functionality, or write your own protocol(s) to
+maintain total control over how your application communicates.
+
+Iroh is entirely composable and modular. You can run multiple protocols on the
+same endpoint, and each protocol can be used independently. This allows you to
+only include the protocols you need for your application, keeping connections
+lightweight and fast.
+
+## Compare to HTTP
+
 Coming from the world of HTTP client/server models, protocols are similar to 
 request handlers. However, they go beyond request/response by creating multiple
 streams of data and usually include both initiating & accepting protocol
@@ -19,14 +30,45 @@ Peer to peer protocols do not require a client/server distinction, both sides
 can initiate and accept connections. However, you can still build client/server
 style protocols on top of iroh if you want to.
 
+
+## ALPN identifiers
+
+Iroh builds on QUIC connections, and uses [application level protocol
+negotiation](https://datatracker.ietf.org/doc/html/rfc7301) (ALPN, a widely used
+and well specified TLS extension) to run multiple protocols on the same QUIC
+endpoint. An ALPN identifier is the string that identifies the protocol and is
+used for protocol negotiation between endpoints. 
+
+For example, the [iroh-blobs](/proto/iroh-blobs) protocol ALPN is
+[`/iroh-bytes/4`](https://github.com/n0-computer/iroh-blobs/blob/124820698cd85691e0d72aeed6e1ac028886b34a/src/protocol.rs#L353).
+This makes sure that an endpoint that accepts a connection can gracefully
+indicate whether it supports the requested protocol.
+
+You can also use multiple ALPN identifiers when connecting as a way to negotiate e.g.
+protocol versions. For example, you would connect using `/iroh-bytes/5` as well
+as `/iroh-bytes/4`, and the other side could respond with `/iroh-bytes/4` to
+indicating it doesn't have support for `/iroh-bytes/5`.
+
+
+## The Accept Loop
+
+The accept loop is the main loop of an iroh server. It listens for incoming
+connections, and then processes them. The accept loop is the entry point for all
+iroh protocols, and is where you can add your own protocol to the iroh stack.
+
+Coming from the world of HTTP servers, the accept loop is similar to the main loop of an HTTP server. The main difference is that the accept loop is more flexible, as it can run multiple protocols on the same endpoint. Normally HTTP servers hide the raw accept loop from you, and instead route to the correct handler based on the URL. In iroh, the accept loop is exposed to you, and you can use it to route to the correct protocol based on the ALPN.
+
+Assuming we have two endpoints connected, yay! Now we just have to… do something… with that connection. That’s where protocols come in.
+
+## Learn more
+
 Protocols are modules you compose together to add functionality to connections.
 Protocols exist for file transfer, game server sync, message broadcasting,
 document collaboration, all kinds of stuff. You can use off-the-shelf protocols
 to quickly add functionality, work directly with QUIC streams & build a fully
 custom protocol that does exactly what you want, or fork an existing protocol to
 get what you need.
 
-## Learn more
 - [iroh-gossip](/connecting/gossip): creating swarms of peers for broadcasting messages on topics.
 - [iroh-blobs](/protocols/blobs): storing and transferring large binary blobs of data.
 - [iroh-docs](/protocols/docs): collaborative key-value store. 

docs.json

@@ -42,11 +42,11 @@
           {
             "group": "Data Protocols",
             "pages": [
-              "protocols/streaming",
               "protocols/kv-crdts",
               "protocols/blobs",
               "protocols/rpc",
               "protocols/automerge",
+              "protocols/streaming",
               "protocols/writing-a-protocol"
             ]
           },

protocols/blobs.mdx

@@ -2,32 +2,27 @@
 title: "Blobs"
 ---
 
-Content-addressed blob storage and transfer for iroh. `iroh-blobs` implements
+Content-addressed blob storage and transfer. `iroh-blobs` implements
 request/response and streaming transfers of arbitrary-sized byte blobs, using
 BLAKE3-verified streams and content-addressed links.
 
-The page below is a concise summary of the `iroh-blobs` crate. For complete
-API details, examples, and the module reference, see the upstream docs:
-https://docs.rs/iroh-blobs/latest/iroh_blobs/
-
 ## Concepts
 
 - Blob: an opaque sequence of bytes (no embedded metadata).
 - Link: a 32-byte BLAKE3 hash that identifies a blob.
 - HashSeq: a blob that contains a sequence of links (useful for chunking/trees).
-- Provider / Requester: provider serves data; requester fetches it. A node can
-	be both.
+- Provider / Requester: provider serves data; requester fetches it. An endpoint can be both.
 
 ## Installation
 
 ```
 cargo add iroh-blobs
 ```
 
-- Primary docs and API reference: https://docs.rs/iroh-blobs/latest/iroh_blobs/
-- Examples repo: https://github.com/n0-computer/iroh-blobs/tree/main/examples
+- [Primary docs and API reference](https://docs.rs/iroh-blobs/latest/iroh_blobs/)
+- [Code samples on GitHub](https://github.com/n0-computer/iroh-blobs/tree/main/examples)
 
-## Example 
+## Examples
 
 The crate is typically used by creating a store, a `BlobsProtocol` handler,
 and registering it with an `iroh::Router`. The code below is an illustrative
@@ -74,3 +69,4 @@ async fn main() -> anyhow::Result<()> {
 	large payloads and transfer the data via the blobs protocol.
 - Use HashSeq to represent sequences of blobs (e.g., chunked content).
 - Use the downloader utilities to aggregate sources and store results locally.
+

protocols/kv-crdts.mdx

@@ -2,31 +2,28 @@
 title: "Key-value Store"
 ---
 
-Multi-dimensional key-value documents with an efficient synchronization protocol.
 
-The crate operates on Replicas. A replica contains an unlimited number of
-Entries. Each entry is identified by a key, its author, and the replica's
-namespace. Its value is the 32-byte BLAKE3 hash of the entry's content data, the
-size of this content data, and a timestamp. The content data itself is not
-stored or transferred through a replica.
+A key-value store for multi-dimensional documents, built on CRDTs, with an
+efficient synchronization protocol. `iroh-docs` provides a protocol handler for
+the iroh networking stack, enabling storage and synchronization of documents over
+peer-to-peer connections.
 
-Range-based set reconciliation is a simple approach to efficiently compute the
-union of two sets over a network, based on recursively partitioning the sets and
-comparing fingerprints of the partitions to probabilistically detect whether a
-partition requires further work.
+## When would I use this?
+
+You would use `iroh-docs` when you need a distributed key-value store that can
+handle concurrent updates from multiple peers, ensuring eventual consistency
+without conflicts. This is particularly useful for collaborative applications,
+distributed configuration management, and any scenario where data needs to be
+shared and synchronized across multiple devices or users.
 
-The crate exposes a generic storage interface with in-memory and persistent
-file-based implementations. The latter makes use of [redb], an embedded
-key-value store, and persists the whole store with all replicas to a single
-file.
 
 ## Installation
 
 ```
 cargo add iroh-docs
 ```
 
-See the [iroh-docs API documentation](https://docs.rs/iroh-docs/latest/iroh_docs/) for more details.
+- [API documentation](https://docs.rs/iroh-docs/latest/iroh_docs/) 
 
 ## Example
 
@@ -67,4 +64,22 @@ async fn main() -> anyhow::Result<()> {
     Ok(())
 }
 
-```
+```
+
+## How it works
+
+The crate operates on Replicas. A replica contains an unlimited number of
+Entries. Each entry is identified by a key, its author, and the replica's
+namespace. Its value is the 32-byte BLAKE3 hash of the entry's content data, the
+size of this content data, and a timestamp. The content data itself is not
+stored or transferred through a replica.
+
+Range-based set reconciliation is a simple approach to efficiently compute the
+union of two sets over a network, based on recursively partitioning the sets and
+comparing fingerprints of the partitions to probabilistically detect whether a
+partition requires further work.
+
+The crate exposes a generic storage interface with in-memory and persistent
+file-based implementations. The latter makes use of [redb], an embedded
+key-value store, and persists the whole store with all replicas to a single
+file.