Crate sc_state_db

source ·
Expand description

State database maintenance. Handles canonicalization and pruning in the database.


Canonicalization window tracks a tree of blocks identified by header hash. The in-memory overlay allows to get any trie node that was inserted in any of the blocks within the window. The overlay is journaled to the backing database and rebuilt on startup. There’s a limit of 32 blocks that may have the same block number in the canonicalization window.

Canonicalization function selects one root from the top of the tree and discards all other roots and their subtrees. Upon canonicalization all trie nodes that were inserted in the block are added to the backing DB and block tracking is moved to the pruning window, where no forks are allowed.

§Canonicalization vs Finality

Database engine uses a notion of canonicality, rather then finality. A canonical block may not be yet finalized from the perspective of the consensus engine, but it still can’t be reverted in the database. Most of the time during normal operation last canonical block is the same as last finalized. However if finality stall for a long duration for some reason, there’s only a certain number of blocks that can fit in the non-canonical overlay, so canonicalization of an unfinalized block may be forced.


See RefWindow for pruning algorithm details. StateDb prunes on each canonicalization until pruning constraints are satisfied.


  • A set of state node changes.
  • A set of changes to the backing database.
  • Pruning constraints. If none are specified pruning is
  • State DB maintenance. See module description. Can be shared across threads.



  • Basic set of requirements for the Block hash and node key types.
  • Backend database trait. Read-only.
  • Backend database trait. Read-only.

Type Aliases§