Nuthatch

The book · 5.22.0 · November 2026

Print / save PDF

Nuthatch: the book

This is the long-form companion to the Nuthatch documentation. The reference manual tells you which command and setting to use. This book explains why the machine is shaped as it is, what invariants it protects, and what each boundary buys you when something goes wrong at three in the morning.

It describes Nuthatch 5.22.0. It was checked against the source on 2026-11-01 for 5.16.0, against what 5.17.0 changed on 2026-11-04, and against what the five releases from 5.17.1 to 5.19.0 changed on 2026-11-11, when the commands and flags it names were also read against the 5.19.0 binary’s help. 5.20.0 changed the SQL engine’s revision and nothing a chapter narrates. 5.21.0 changed when segments are verified, which the storage chapter now describes. 5.22.0 took label sets out of both identities, which the identity chapter now says; its answers as of a block, issuer recipes and evidence bundles are new routes and commands that no chapter narrates, and the reference manual covers them. It is deliberately grounded in the running implementation, not a design sketch for a future product: each mechanism a chapter narrates was read against the function that implements it, and the worked examples in the first two appendices were re-run on the 4.11.0 release binary. They were replayed again on a 5.9.0 build on 2026-10-23 and reached the same outcomes at that day’s block heights; the figures printed are the dated ones each appendix gives. Where the system has a limitation, it is named. A system that is honest about its edge is more useful than one that claims to be a universal solvent.

How to read it

Read the chapters in order if you are learning the architecture. If you already operate a nest, start with the cursor and data that survives a restart. If you are deciding whether to port a subgraph, begin with the data problem and then use the practical subgraph fallback guide.

Each chapter links outward to the corresponding reference material. The book gives the reasoning; the manual gives you the precise TOML, route and command spelling.

Contents

  1. The data problem - what a nest is for, and what it is not.
  2. The authored nest - making a small, reproducible description of chain data.
  3. The cursor - following a chain without confusing a temporary tip for history.
  4. Storage and sealing - hot data, cold data, finality and SQL.
  5. Reading the index - tables, views, entities, APIs and the boundary of event-derived truth.
  6. Maintaining an answer - when an aggregate belongs in the indexing path, and what it costs.
  7. Identity, upgrades and reuse - why package identity and data identity are separate things.
  8. The runtime - many nests, tenants, cursors and scaled workers.
  9. Operating a truthful index - verification, security, failure isolation and the questions worth asking before trusting a number.

The appendices slow the camera down over three mechanisms which are easy to describe quickly and quite another matter to implement correctly:

  1. One log, end to end - from an RPC response to a durable query result.
  2. A reorganisation, walked through - rollback at the hot boundary, and why a finality violation halts rather than guesses.
  3. A lease handover, walked through - the fencing rule that makes two scaled workers safe. Scaled mode is a separate Linux build, so this one is read against the code and dated rather than re-run.

The chapters are intended to stand up to a close read. The RFC archive and implementation internals remain the primary material for contributors who want every last moving part.