Specification
The specification says what the code cannot: what each part of Dassie
is for, the rules that span parts, what must never change, and why.
It lives in the repository, in
spec/.
This page is a map of it.
On this page
What it holds, and what it leaves out
These docs tell you how to use Dassie. The spec tells you how it is meant to work, for anyone who changes it or wants to check it:
- what a part is for, and how it fits with the others;
- invariants, and contracts between parts and between versions;
- the surfaces that must never change, and what pins them;
- the reasons for choices you would not guess.
It leaves out what the code already says. Values, limits, timeouts, field lists, flags and environment variables live only in the code, where they cannot drift, and the spec points to the module that holds them. It also keeps no history: no dates, milestones or "used to". Git has the timeline.
The spec describes what Dassie does today. Work that is not built yet is kept apart, in the roadmap and the designs, so you can always tell the two apart.
Where to start
- The overview: what Dassie is, the words the rest of the spec uses, the life of a node, and the frozen surfaces that must never change.
- Engineering: the rules every crate and package follows. The code is deterministic, bounded and asserted, so that simulations can test it far beyond what review could.
- The area docs for the part you care about. The index maps every crate, app, package and contract in the repository to the docs to read for it.
Read a decision when an area doc links to it and you want to know why a rule is what it is.
The areas
Each area doc states one part's rules and links the decisions behind them.
| Area | What it covers |
|---|---|
| Identity | The recovery phrase, the keys it derives, the node ID |
| Encoding | The OER subset every wire format is written in |
| ILP | Interledger packets, error codes, ILDCP and BTP |
| STREAM | STREAM connections, frames and crypto |
| Ledger | The node's double-entry books and the owner's funds |
| Connector | The packet path: fees, spread, spending caps, exchange rates |
| Peer protocol | The wire protocol between nodes, over QUIC |
| Network | Bootstrap nodes, registration, peering, routing, names |
| Settlement | Settlement schemes, external assets, credit and thresholds |
| Settlement hubs | A hub's rules, its ledger, its validators and its fees |
| XRPL | The XRP Ledger accounts and the schemes on them |
| Payments | Open Payments: wallet addresses, grants, payments, quotes |
| Rate feed | A core node's signed snapshot of the quotes and ladders it swaps at, and how others ask for it |
| Node | The daemon: startup, configuration, the dassie command, logging |
| HTTP | Listeners, routes, certificates, setup, login, front doors |
| RPC | The owner's RPC contract and its live streams |
| Release | Builds, the mirror, signing, the installer and the updater |
| Wallet | The owner's web app |
| Website | dassie.land: these docs, the STREAM toy and the architecture page |
| Desktop | The desktop app, its window and its tray |
| Dev | The local dev network and its dashboard |
| DSUSD keeper | The testnet dollar token and the pool that prices it |
| Market maker VM | The VM that runs the project's market maker and its node on the testnet |
| Proof servers | The patched XRP Ledger servers that answer the node's proofs |
| Testing | Test levels, golden vectors and the simulations |
This list follows the spec's own; when the two differ, the spec's README is right.
Decisions
A decision records one choice between real alternatives: the facts
that forced it, what was chosen, what it costs, and what was rejected
and why. Area docs link the decisions behind their rules. Each has a
name of its own, such as
own-books,
and a name is never given to another decision, so code can cite it
for good. Design decisions
lists them all, one line each.
Designs and the roadmap
Two parts of the spec describe what is not built yet.
- The roadmap lists the open areas of work, each with what "done" means. Areas move forward side by side; there are no numbered milestones. What's next says the same in plain words.
- The designs hold large pieces of work in full: the rest of settlement hubs, of the periphery and of names, and checking the XRP Ledger's validators. Direct settlement keeps how peers once settled without a hub, and what bringing it back would take.
When a piece of work is built, what it does moves into the area docs, and its entry leaves the roadmap.
Citing the spec
Code, docs and pull requests cite the spec by path and heading, such
as spec/areas/peer-protocol.md#versions, and a decision
by its file, such as spec/decisions/own-fulfills.md.
A test in the repository, scripts/spec_test.ts, checks
that every such link and citation still leads somewhere.
If you change Dassie, the spec changes with it. Contributing says how.
