Design Documents

These design documents describe at a high level how we are building Iroh. Think of them as a constantly evolving whitepaper: Design documents should help you reason about how iroh might work one day.

These design documents are a work in progress. They change often, integrating feedback & research as we go. Each document ends with a changelog. A fine-grained history is available on github. Our goal with design documents is to present a single source of truth for our research. We gather feedback from numerous places (github discussions, twitter, meetings, chats, etc.) and integreate them here.

These are not specs

We're reserving the word specs for finished, detailed descriptions of how Iroh actually works. You should be able to write an interoperable implementation of Iroh from specs. Iroh is currently pre-1.0 sofware, and has no formalized specs.

These are not docs

Our docs describe released versions of Iroh. If you want an accurate description of actual working software, head there.


The best way to influence these documents is to share your views on the Iroh github discussion forum. Numerous conversations are already in progress there, please search before posting a new topic.


The only way to know if this design works is to build it, test it, put it into production and measure the results. We work hard to take a measurements-focused approach to designing distributed systems. Our perf suite is the primary set of figures we use to evalaute designs. The results we gather from continual experimentation directly impacts these design documents.

Next: 1. Iroh