Tickets

Tl;DR: Tickets are a way to share dialing information between iroh nodes. They're a single token that contains everything needed to connect to another node, or to fetch a blob or document.

Tickets are a single serialized token containing everything needed to kick off an interaction with another node running iroh. Here's an example of one:

docaaacarwhmusoqf362j3jpzrehzkw3bqamcp2mmbhn3fmag3mzzfjp4beahj2v7aezhojvfqi5wltr4vxymgzqnctryyup327ct7iy4s5noxy6aaa

Yes, they're long.

They're also very powerful. Tickets combine a piece of info with dialing information for the node 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:

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 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 point 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.

Creating Tickets

by default, tickets only include the nodeID If you still want to add relay and direct addresses to the ticket, you can pass --addr-options RelayAndAddresses to the ticket generation commands.

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 additinonal 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 NodeID. Tickets can contain information that can go stale quickly. instead focus on caching nodeIDs, and letting iroh transparently resolve dialing details at runtime.