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.
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.
RefWindow for pruning algorithm details.
StateDb prunes on each canonicalization until
pruning constraints are satisfied.