This is a top-down, source-anchored description of libbitcoin-database, the store beneath libbitcoin-node. It covers the storage primitives (heads, bodies and maps), the tables built from them, the memory-mapped storage and its recovery model, and the query layer that the node uses.
The relational concepts (natural, foreign and search keys, navigation versus search, append-only bodies published by heads, recoverability, and reliability) are from the 2021 design document for the version 4 store.
Every behavioural claim is anchored with file:line references into the
C++ source. The citations were verified against libbitcoin-database master
at commit d29fa3df (2026-10-20). Paths are relative to
include/bitcoin/database/ unless they begin with src/.
The documents#
| # | File | Topic |
|---|---|---|
| 00 | 00-overview |
Layers, the relational model, navigation versus search, file layout |
| 01 | 01-primitives |
Links, keys, heads, bodies and maps, with figures of each head type |
| 02 | 02-tables |
Every store table: map type, link, row, fields, and relations |
| 03 | 03-storage |
Memory maps, growth and remap, disk full, snapshot and restore, locking |
| 04 | 04-queries |
Query families, archival commit order, block state, confirmation, pool |
Recommended reading orders#
For a new contributor#
00 → 01 → 02, then 04 §2–§3 for how a block is written and confirmed. Read 03 when working on store lifecycle or performance.
For a formal-verification reader#
01 §5 and 03 §5 give the publication model: every write becomes
visible through a single atomic cell or size store, and recovery is a head
snapshot over append-only bodies. 04 §2 is the archival commit order
that the node's organizeN/validateN/confirmN faults rely on. The
numbered invariants are listed below.
For a node reader#
The node architecture treats the store as an
oracle. 04 is the interface it calls, and 03 §4–§6 are the
suspend, disk-full and snapshot behaviours that chaser_storage and
chaser_snapshot drive.
Conventions used throughout#
File:line citations#
Every non-trivial claim has a path:N citation. Re-grep from the repo root
after source changes and update the commit above.
Numbered invariants#
| Prefix | Doc | Roughly |
|---|---|---|
Link-* |
01 | Link domain and terminal |
Head-* |
01 | Head cell and filter semantics |
Body-* |
01 | Append-only bodies |
Map-* |
01 | Searchability and publication |
Table-* |
02 | Table relations |
Storage-* |
03 | Counter chain, remap, disk full |
Snapshot-* |
03 | Head copy and restore |
Archive-* |
04 | Archival commit order |
Confirm-* |
04 | Strong and height indexes |
Figures#
The head-type figures in 01-primitives are generated by
tools/plot-database.py. Click a figure to view it at full size.
Honest caveats#
-
No build verification. Citations are textual and were re-grepped during writing; nothing was built or executed for this documentation.
-
Comments in
store.hpp. Several member comments there name an older primitive (for example input and txs as "slab hashmap", strong and state as "record hashmap"). These pages follow the type declarations intables/. -
Consensus rules (script, BIP30/34/68 checks) live in libbitcoin-system.
04-queriesdescribes the store reads behind them, not the rules.