> ## Documentation Index
> Fetch the complete documentation index at: https://docs.iroh.computer/llms.txt
> Use this file to discover all available pages before exploring further.

# Protocols

A **protocol** defines how two iroh endpoints exchange messages and coordinate
behavior. Once you've established an iroh connection, protocols determine what
happens next: transferring files, syncing documents, broadcasting messages, or
whatever your application needs.

iroh provides the pool of encrypted QUIC connections - protocols define what to
do with them.

## Peer-to-peer protocols

Unlike HTTP's client/server model where one side only sends requests and the
other only responds, peer-to-peer protocols typically support **both**
initiating and accepting connections on the same endpoint.

This means:

* Any peer can request data from any other peer
* Any peer can offer data to any other peer
* Roles can change over time (today's client is tomorrow's server)

You can still build client/server-style protocols if your application needs that
distinction, but iroh's P2P foundation gives you more flexibility.

## Building blocks, not a framework

iroh is designed as a set of composable building blocks. The core `iroh` crate
gives you endpoints and connections. From there, you choose:

**Use existing protocols** - Pick from protocols built by the iroh community:

* [`iroh-blobs`](/protocols/blobs) - Content-addressed blob storage and transfer
* [`iroh-docs`](/protocols/documents) - Collaborative key-value documents with CRDTs
* [`iroh-gossip`](/connecting/gossip) - Topic-based message broadcasting in swarms
* [`iroh-automerge`](https://github.com/n0-computer/iroh-experiments/tree/main/iroh-automerge) - Automerge document sync (experimental)

**Build your own** - Create custom protocols using:

* Raw QUIC streams via iroh's connection API (most common approach)
* RPC frameworks like [`irpc`](https://github.com/n0-computer/irpc) with [`iroh-irpc`](https://github.com/n0-computer/irpc)

Each protocol is a separate crate you can add as needed. You're never locked
into a particular set of protocols - mix and match, or build something entirely
new.

## How protocols work

### ALPN identifiers

Protocols use [Application-Layer Protocol
Negotiation](https://datatracker.ietf.org/doc/html/rfc7301) (ALPN) strings to
identify themselves. When an endpoint accepts a connection, it uses the ALPN to
route to the correct protocol handler.

For example, `iroh-blobs` uses the ALPN `/iroh-bytes/VERSION`. When a peer connects
with this ALPN, the endpoint knows to handle it as a blobs request.

You can also use multiple ALPN identifiers for version negotiation. A connecting
peer might offer `/my-protocol/2` and `/my-protocol/1`, letting the accepting
peer respond with whichever version it supports.

### The accept loop

When your endpoint receives an incoming connection, it checks the requested ALPN
and routes to the appropriate protocol handler. This is similar to HTTP routing,
but happens at the connection level rather than per-request.

You can handle this routing yourself by accepting connections directly, or use
iroh's [`Router`](https://docs.rs/iroh/latest/iroh/protocol/struct.Router.html)
to automatically route connections to registered protocol handlers.

## Learn more

Ready to start building with protocols?

**Using existing protocols:**

* [Blob storage with iroh-blobs](/protocols/blobs)
* [Document collaboration with iroh-docs](/protocols/documents)
* [Message broadcasting with iroh-gossip](/connecting/gossip)

**Building your own:**

* [Write your own protocol guide](/protocols/writing-a-protocol)
* [QUIC streaming patterns](/protocols/using-quic)
* [Router API documentation](https://docs.rs/iroh/latest/iroh/protocol/struct.Router.html)