Purpose and Scope
This document describes the blockchain management subsystem responsible for maintaining the canonical chain, inserting blocks, and handling chain reorganization.It explains how
BlockChain and HeaderChain track block headers, bodies, receipts, and metadata required for chain selection and state management.
Related documents:
- State management and StateDB architecture: State Management
- Transaction pool management: Transaction Pool
- Consensus-specific block sealing: Consensus and Block Production
Core Structures
BlockChain
TheBlockChain type is the central component that manages the canonical blockchain.It coordinates block insertion, validation, state execution, and chain reorganization, and works together with the consensus engine (
consensus.Engine), fork choice logic (ForkChoice), state processor (Processor), and block validator (Validator).
It tracks several key heads as internal state: the current canonical head (currentBlock), the snapshot synchronization reference block (currentSnapBlock), the finalized block (currentFinalBlock), and the safe block (currentSafeBlock).These head pointers are updated according to consensus rules and fork choice results.
HeaderChain
HeaderChain is a lightweight chain structure that manages block header storage and number–hash mappings.It is responsible for header-level validation and chain traversal, and coordinates header chain reorganization and canonical header mapping updates.
Full block insertion is handled by
BlockChain, while HeaderChain is used as a subordinate component.
Canonical Chain Management
The canonical chain represents the official chain path followed by the node. The blockchain maintains two core mappings:- Number → Hash: The canonical block hash for a given block number
- Hash → Number: The block number corresponding to a given block hash
State Loading at Initialization
During initialization, theloadLastState() method restores chain state from disk:
- Read the last head block hash from the database
- Load the head block using the hash
- Set the current block (
currentBlock) - Load the header chain head
- Load the snapshot reference block and finalized block
Block Insertion Pipeline
Block insertion is a multi-stage process that includes validation, execution, and canonical chain updates.Insertion Flow Overview
TheInsertChain() method is the main entry point for inserting a batch of blocks, and internally proceeds through the following stages:
Stage Descriptions
1. Pre-check- Check the future block cache (
futureBlocks) - Detect duplicate block insertion
- Verify parent block existence
- Call the consensus engine’s
VerifyHeader() - For WBFT, verify proposer, signatures, and validator set consistency
- Validate block number, timestamp, and gas limit rules
- Call
ValidateBody() - Verify transaction root hash matches the header
- In WBFT environments, ensure that no uncle blocks are present
- Create a StateDB based on the parent block state
- Execute each transaction via
ApplyTransaction()and run the EVM - Accumulate receipts and gas usage
- Call
ValidateState() - Validate gas usage, receipt bloom, and state root
- Write the block and receipts to the database
- Commit the state trie and update snapshots
- Evaluate the priority of the new block according to the consensus engine and fork choice rules
- Perform chain reorganization if required
- Emit
ChainEventandChainHeadEvent - Notify logs and the transaction pool of the new head
Chain Reorganization
Chain reorganization (reorg) occurs when a chain with higher priority than the current canonical chain appears according to fork choice rules.In StableNet’s WBFT environment, chain selection is based on consensus rules and epoch-based validator agreement rather than total difficulty.
Reorganization Process
- Fork choice decision: The
ForkChoicelogic determines whether the new block should be adopted as canonical - Common ancestor discovery: Find the divergence point between the existing chain and the new chain
- Canonical mapping update: Update number–hash mappings via
HeaderChain.Reorg() - Head pointer update: Update
currentBlock,currentFinalBlock, andcurrentSafeBlock
HeaderChain.Reorg() include:
- Simple extension if the parent is the current head
- Removal of replaced canonical mappings
- Rewriting mappings while traversing back to the common ancestor
- Recording headers of the new chain as canonical
- Persisting the new head header hash to the database
Caching
The blockchain uses LRU caches to minimize disk access:| Cache | Size | Purpose |
|---|---|---|
bodyCache | 256 | Block body cache |
blockCache | 256 | Full block cache |
receiptsCache | 32 | Transaction receipt cache |
txLookupCache | 1024 | Transaction location lookup |
futureBlocks | 256 | Temporary storage for future blocks |
Chain Recovery
SetHead
TheSetHead() method rewinds the chain to a specified block number. Typical use cases include:
- Recovering state after corrupted blocks
- Skipping known problematic blocks
- Re-synchronizing after chain rule changes
Reset
Reset() removes all chain data and restores the blockchain to the genesis state.
SnapSyncCommitHead
Called after snapshot synchronization completes to set the synchronized block as the canonical head:- Verify block existence
- Activate the state storage
- Validate state trie accessibility
- Update the current block pointer
- Rebuild snapshot structures
Database Schema
Block Storage Keys
| Key Pattern | Value Type | Purpose |
|---|---|---|
h{num}n | common.Hash | Canonical hash for a block number |
h{hash}n | uint64 | Block number for a hash |
H{hash}{num} | *types.Header | Block header |
b{hash}{num} | *types.Body | Block body |
r{hash}{num} | []*types.Receipt | Transaction receipts |
Chain State Keys
| Key | Purpose |
|---|---|
LastBlock | Canonical block head hash |
LastHeader | Canonical header head hash |
LastFast | Snapshot reference block hash |
LastFinalized | Finalized block hash |
SnapshotRoot | Snapshot root |
Error Handling
| Error | Condition | Handling |
|---|---|---|
ErrKnownBlock | Block already processed | Ignored |
ErrNoGenesis | Missing genesis | Initialization required |
ErrBannedHash | Block hash is banned | Rewind chain |
ErrUnknownAncestor | Missing parent block | Request from peers |
ErrPrunedAncestor | Parent state pruned | Snapshot sync required |
errInsertionInterrupted | Insertion interrupted | Abort current insertion |