add tickets & more on quickstart

Author: okdistribute

concepts/discovery.mdx

@@ -11,6 +11,7 @@ Discovery is the glue that connects an [Endpoint](/concepts/endpoints#endpoint-i
 
 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.
 
+
 ## Discovery Services
 
 There are four different implementations of the discovery service in iroh. iroh

concepts/endpoints.mdx

@@ -13,18 +13,9 @@ endpoints, while still remaining independent connections. This will result in
 more optimal network behaviour.
 
 
-## Endpoint Identifiers
-
-Each endpoint in iroh has a unique identifier (`EndpointID`) created as a
-cryptographic key. This can be used to globally identify an endpoint. Because
-`EndpointIDs` are cryptographic keys, they are also the mechanism by which all
-traffic is always encrypted for a specific endpoint only.
-
-See the [EndpointID](https://docs.rs/iroh/latest/iroh/type.EndpointId.html) documentation for more information.
-
 ## Connections
 
-Because we're in a peer-2-peer context, either endpoint might be operating as
+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.
@@ -38,6 +29,65 @@ A [Relay](/concepts/relays) server can be used to make the connections reliable.
 Due to the light-weight properties of QUIC streams a stream can only be accepted once the initiating peer has sent some data on it.
 </Note>
 
+
+## Endpoint Identifiers
+
+Each endpoint in iroh has a unique identifier (`EndpointID`) created as a
+cryptographic key. This can be used to globally identify an endpoint. Because
+`EndpointIDs` are cryptographic keys, they are also the mechanism by which all
+traffic is always encrypted for a specific endpoint only.
+
+See the [EndpointID](https://docs.rs/iroh/latest/iroh/type.EndpointId.html) documentation for more information.
+
+# Endpoint Addresses
+
+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 id: PublicKey,
+    pub addrs: BTreeSet<TransportAddr>,
+}
+```
+
+You'll interact with `EndpointAddr`s a fair amount when working with iroh. It's also quite normal to construct addresses manually from, say, endpoint identifiers stored in your application database.
+
+When we call [`connect`](https://docs.rs/iroh/latest/iroh/endpoint/struct.Endpoint.html#method.connect) on an [Endpoint](https://www.iroh.computer/docs/concepts/endpoint), we need to pass either a `EndpointAddr`, or something that can turn into a `EndpointAddr`. In iroh `Endpoint`s will have different fields populated depending on where they came from, and the discovery services you've configured your endpoint with.
+
+### Interaction with discovery
+
+From the above struct, the only _required_ field is the `id`. And because of
+this, there's an implementation of `From` that can turn `EndpointIDs` directly
+into EndpointAddrs. _but this will only work if you have a discovery service
+that can resolve EndpointIDs enabled_. Thankfully, we enable discovery by
+default:
+
+```rust
+use iroh::Endpoint;
+
+// enables dialing by EndpointAddrs that only have EndpointIDs by default:
+let ep = Endpoint::builder()
+    .bind()
+    .await?;
+```
+
+This is why we actively encourage configuring a discovery service, and DNS is the most common one we recommend. Because we're in p2p land dialing details & even home relays for an endpoint can change on very short notice, making this data go stale quickly. Endpoint Identifiers are a practical source of stability that counteracts this.
+
+### When to provide full details
+
+If you have full dialing details, it's well worth providing them as part of a
+`EndpointAddr` passed to `connect`. Iroh can use this to skip the network
+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
+
+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.
+
 ## Building on Endpoints
 
 Endpoints are a low-level primitive that iroh exposes on purpose. For some

concepts/tickets.mdx

@@ -0,0 +1,47 @@
+Tickets are a way to share dialing information between iroh endpoints. They're a
+single token that contains everything needed to connect to another endpoint or gossip topic.
+
+You can use the default iroh endpoint tickets or build your own tickets using the `iroh-tickets` crate.
+
+<Note>
+Have a ticket? Try pasting it into the [iroh ticket explorer](https://ticket.iroh.computer) to break it down! Here's an [example](https://ticket.iroh.computer?ticket=docaaacarwhmusoqf362j3jpzrehzkw3bqamcp2mmbhn3fmag3mzzfjp4beahj2v7aezhojvfqi5wltr4vxymgzqnctryyup327ct7iy4s5noxy6aaa)
+</Note>
+
+Tickets are a single serialized token containing everything needed to kick off an interaction with another endpoint running iroh. Here's an example of one:
+
+```text
+docaaacarwhmusoqf362j3jpzrehzkw3bqamcp2mmbhn3fmag3mzzfjp4beahj2v7aezhojvfqi5wltr4vxymgzqnctryyup327ct7iy4s5noxy6aaa
+```
+
+Yes, they're long. 
+
+They're also very powerful. Tickets combine a piece of info with _dialing information for the endpoint to fetch from_. We've seen numerous content-addressed systems force users to copy and paste long hashes around, and we figure if you're going to have to copy and paste something, it might as well contain both the hash and a hint about where to find the data. Tickets also work very well in QR codes!
+
+In practice this is a _massive_ speed pickup for iroh. When you're given a ticket, you have everything you need to construct a request
+
+## Kinds of Tickets
+
+Currently, there are three kinds of tickets:
+
+| Type | Description | Contents |
+| --- | --- | --- | 
+| `endpoint` | A token for connecting to an iroh endpoint | `Endpoint Address` |
+| `blob` | A token for fetching a [blob](/docs/layers/blobs) or [collection](/docs/layers/blobs#collections) | `Hash`, `HashOrCollection`, `Endpoint Address`  |
+| `document` | A read/write access token to a [document](/proto/iroh-docs), plus an endpoint address | `DocID`, `Read/Write Capability`, `[Endpoint Address]` |
+
+Tickets always start with an ascii string that describes the type of ticket (eg: `blob`), followed by a base32-lowercase-encoded payload. The payload is [postcard-encoded data](https://postcard.jamesmunns.com/wire-format.html) that contains the information needed to use the ticket. We chose postcard because it's extremely succinct.
+
+## Tickets are sensitive
+
+When you create a ticket, it embeds the IP addresses of the machines you're using to create the ticket. This means that if you share a ticket with someone, they can use it to connect to your machine. This is a feature, not a bug. It's a way to bootstrap connections between peers without needing a central server. It also means you should be careful about sharing tickets with people you don't want to have your IP address.
+
+It's worth pointing out this setup is considerably better than full peer-2-peer systems, which _broadcast_ your IP to peers. Instead in iroh, we use tickets to form a "cozy network" between peers you explicitly want to connect with. It's possible to go "full p2p" & configure your app to broadcast dialing details, but we think tickets represent a better middle-ground default.
+
+## Document Tickets are _secrets_
+
+When you create a document ticket, you're creating a secret that allows someone to read or write to a document. This means that you should be careful about sharing document tickets with people you don't trust. What's more, someone who has a document ticket can use it to create new tickets for the same document. This means that if you share a document ticket with someone, they can use it to create new tickets for the same document, and share those tickets with others.
+
+## Tickets in Apps
+Using tickets in your app comes down to what you're trying to accomplish. For short-lived sessions where both devices are online at the same time, tickets are an incredibly powerful way to bootstrap connections, and require no additional servers for coordination.
+
+If you have any means of automating (like, a central database or server to bootstrap from) we recommend you _do not_ use tickets in your app, and instead program around the idea that you can _dial by EndpointID_. Tickets can contain information that can go stale quickly. instead focus on caching `endpointIDs`, and letting iroh transparently resolve dialing details at runtime.

docs.json

@@ -23,6 +23,7 @@
               "group": "How it works",
               "pages": [
                 "concepts/endpoints",
+                "concepts/tickets",
                 "concepts/discovery",
                 "concepts/relays",
                 "concepts/holepunching",
@@ -42,13 +43,14 @@
             ]
           },
           {
-            "group": "Sending Data",
+            "group": "Communicating over Iroh",
             "pages": [
               "protocols/kv-crdts",
               "protocols/blobs",
               "protocols/rpc",
               "protocols/automerge",
               "protocols/streaming",
+              "examples/chat",
               "protocols/writing-a-protocol"
             ]
           },

examples/chat.mdx

@@ -1,8 +1,7 @@
----
-title: "Building a P2P Chat Application with Iroh"
----
 import { YouTube } from '@/components/youtube'
 
+## Building a P2P Chat Application with Iroh
+
 <iframe width="560" height="315" src="https://www.youtube.com/embed/ogN_mBkWu7o?si=Y-GqkmGBRZfRhclc" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
 
 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.

quickstart.mdx

@@ -26,7 +26,7 @@ cd ping-pong
 Now, add the dependencies we'll need for this example:
 
 ```bash
-cargo add iroh iroh-ping tokio anyhow
+cargo add iroh iroh-ping iroh-tickets tokio anyhow
 ```
 
 From here on we'll be working inside the `src/main.rs` file.
@@ -105,6 +105,9 @@ async fn main() -> anyhow::Result<()> {
     // connections in the iroh p2p world
     let recv_ep = Endpoint::builder().bind().await?;
 
+    // bring the endpoint online before accepting connections
+    recv_ep.online().await;
+
     // Then we initialize a struct that can accept ping requests over iroh connections
     let ping = Ping::new();
 
@@ -121,6 +124,7 @@ async fn main() -> anyhow::Result<()> {
 
 With these two lines, we've initialized iroh-blobs and gave it access to our `Endpoint`.
 
+### Ping: Send
 At this point what we want to do depends on whether we want to accept incoming iroh connections from the network or create outbound iroh connections to other endpoints.
 Which one we want to do depends on if the executable was called with `send` as
 an argument or `receive`, so let's parse these two options out from the CLI
@@ -171,10 +175,126 @@ cargo run
 I   Compiling ping-quickstart v0.1.0 (/Users/raemckelvey/dev/ping-quickstart)
     Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.62s
      Running `target/debug/ping-quickstart`
-accepted connection from 32c5772d26bff78923ef6e85f665f23b96ee06655832649910a560af59c84e22
 ping took: 1.189375ms to complete
 ```
 
+## Part 2: Separate Sender and Receiver
+
+Round-trip time isn't very useful when both roles live in the same binary
+instance. Let's split the app into two subcommands so you can run the receiver
+on one machine and the sender on another.
+
+### What is a ticket?
+
+When an iroh endpoint comes online, it has an address containing its node ID,
+relay URL, and direct addresses. An `EndpointTicket` wraps this address into a
+serializable ticket—a short string you can copy and paste. Share this ticket
+with senders so they can dial the receiver without manually exchanging
+networking details.
+
+A ticket is made from an endpoint's address like this:
+
+```rust
+use iroh_tickets::{Ticket, endpoint::EndpointTicket};
+
+let ticket = EndpointTicket::new(recv_ep.addr());
+println!("{ticket}");
+```
+
+For more details on tickets, see [Discovery](/concepts/discovery).
+
+### Receiver
+
+The receiver creates an endpoint, brings it online, prints its ticket, then runs
+a router that accepts incoming ping requests indefinitely:
+
+```rust
+// filepath: src/main.rs
+use anyhow::{anyhow, Result};
+use iroh::{Endpoint, protocol::Router};
+use iroh_ping::Ping;
+use iroh_tickets::{Ticket, endpoint::EndpointTicket};
+use std::env;
+
+async fn run_receiver() -> Result<()> {
+    let recv_ep = Endpoint::builder().bind().await?;
+    recv_ep.online().await;
+
+    let ping = Ping::new();
+
+    let ticket = EndpointTicket::new(recv_ep.addr());
+    println!("{ticket}");
+
+    Router::builder(recv_ep)
+        .accept(iroh_ping::ALPN, ping)
+        .spawn();
+
+    // Keep the receiver running indefinitely
+    loop {
+        tokio::time::sleep(tokio::time::Duration::from_secs(60)).await;
+    }
+}
+```
+
+### Sender
+
+The sender parses the ticket, creates its own endpoint, and pings the receiver's address:
+
+```rust
+// filepath: src/main.rs
+async fn run_sender(ticket: EndpointTicket) -> Result<()> {
+    let send_ep = Endpoint::builder().bind().await?;
+    let send_pinger = Ping::new();
+    let rtt = send_pinger.ping(&send_ep, ticket.endpoint_addr().clone()).await?;
+    println!("ping took: {:?} to complete", rtt);
+    Ok(())
+}
+```
+
+### Wiring it together
+
+Parse the command-line arguments to determine whether to run as receiver or sender:
+
+```rust
+// filepath: src/main.rs
+#[tokio::main]
+async fn main() -> Result<()> {
+    let mut args = env::args().skip(1);
+    let role = args
+        .next()
+        .ok_or_else(|| anyhow!("expected 'receiver' or 'sender' as the first argument"))?;
+
+    match role.as_str() {
+        "receiver" => run_receiver().await,
+        "sender" => {
+            let ticket_str = args
+                .next()
+                .ok_or_else(|| anyhow!("expected ticket as the second argument"))?;
+            let ticket = EndpointTicket::deserialize(&ticket_str)
+                .map_err(|e| anyhow!("failed to parse ticket: {}", e))?;
+
+            run_sender(ticket).await
+        }
+        _ => Err(anyhow!("unknown role '{}'; use 'receiver' or 'sender'", role)),
+    }
+}
+```
+
+### Running it
+
+In one terminal, start the receiver:
+
+```bash
+cargo run -- receiver
+```
+
+It will print a ticket. Copy that ticket and run the sender in another terminal:
+
+```bash
+cargo run -- sender <TICKET>
+```
+
+You should see the round-trip time printed by the sender.
 
 ## That's it!