# Nuthatch: the book

> A guided tour of how Nuthatch turns chain logs into durable, queryable data.

Checked against Nuthatch 5.22.0 (2026-11-17).

HTML version: https://nuthatch-indexer.com/docs/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](https://nuthatch-indexer.com/docs/book/the-cursor.md) and [data that survives a restart](https://nuthatch-indexer.com/docs/book/storage-and-sealing.md).
If you are deciding whether to port a subgraph, begin with [the data problem](https://nuthatch-indexer.com/docs/book/the-data-problem.md)
and then use the practical [subgraph fallback guide](https://nuthatch-indexer.com/docs/build/subgraph-fallback.md).

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](https://nuthatch-indexer.com/docs/book/the-data-problem.md) - what a nest is for, and what it is not.
2. [The authored nest](https://nuthatch-indexer.com/docs/book/the-authored-nest.md) - making a small, reproducible description of
   chain data.
3. [The cursor](https://nuthatch-indexer.com/docs/book/the-cursor.md) - following a chain without confusing a temporary tip for
   history.
4. [Storage and sealing](https://nuthatch-indexer.com/docs/book/storage-and-sealing.md) - hot data, cold data, finality and SQL.
5. [Reading the index](https://nuthatch-indexer.com/docs/book/reading-the-index.md) - tables, views, entities, APIs and the boundary of
   event-derived truth.
6. [Maintaining an answer](https://nuthatch-indexer.com/docs/book/maintaining-an-answer.md) - when an aggregate belongs in the
   indexing path, and what it costs.
7. [Identity, upgrades and reuse](https://nuthatch-indexer.com/docs/book/identity-upgrades-and-reuse.md) - why package identity
   and data identity are separate things.
8. [The runtime](https://nuthatch-indexer.com/docs/book/the-runtime.md) - many nests, tenants, cursors and scaled workers.
9. [Operating a truthful index](https://nuthatch-indexer.com/docs/book/operating-a-truthful-index.md) - 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:

10. [One log, end to end](https://nuthatch-indexer.com/docs/book/one-log-end-to-end.md) - from an RPC response to a durable query
   result.
11. [A reorganisation, walked through](https://nuthatch-indexer.com/docs/book/a-reorganisation-walked-through.md) - rollback at
   the hot boundary, and why a finality violation halts rather than guesses.
12. [A lease handover, walked through](https://nuthatch-indexer.com/docs/book/a-lease-handover-walked-through.md) - 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](https://nuthatch-indexer.com/docs/contributing/rfcs.md)
and [implementation internals](https://nuthatch-indexer.com/docs/contributing/internals.md) remain the primary material for
contributors who want every last moving part.
