Purpose and Scope
This document describes the persistent and in-memory storage architecture used by StableNet to maintain blockchain state, blocks, and receipts.It covers the layered storage structure from the high-level StateDB caching layer down to the raw database backends, including the Merkle Patricia Trie, caching strategies, and the snapshot system. For state transitions and EVM execution, see State Transitions and Gas.
For blockchain management and canonical chain maintenance, see Blockchain Management.
For detailed information on the ancient store and data lifecycle, see Ancient Store and Data Lifecycle.
Storage Layer Hierarchy
StableNet’s storage architecture is composed of multiple layers, each providing a different level of abstraction and performance optimization.StateDB: State Caching Layer
StateDB is the core interface for reading and modifying blockchain state.It is an advanced caching layer that provides journaling-based atomicity guarantees and snapshot-based rollback capabilities.
StateDB Structure
| Component | Type | Purpose |
|---|---|---|
db | Database | Trie database interface |
trie | Trie | Account trie root |
snaps | *snapshot.Tree | Snapshot tree for fast access |
snap | snapshot.Snapshot | Currently active snapshot |
stateObjects | map[common.Address]*stateObject | Active account objects |
stateObjectsPending | map[common.Address]struct{} | Finalized but uncommitted objects |
stateObjectsDirty | map[common.Address]struct{} | Objects modified during execution |
stateObjectsDestruct | map[common.Address]*types.StateAccount | Destructed objects |
accounts | map[common.Hash][]byte | Modified account data |
storages | map[common.Hash]map[common.Hash][]byte | Modified storage slots |
accountsOrigin | map[common.Address][]byte | Original account values |
storagesOrigin | map[common.Address]map[common.Hash][]byte | Original storage values |
journal | *journal | State change log |
validRevisions | []revision | Snapshot revisions |
refund | uint64 | Gas refund counter |
State Object Management
Each account is managed as astateObject, which wraps the base types.StateAccount and tracks execution-time changes.
| Field | Type | Purpose |
|---|---|---|
address | common.Address | Account address |
addrHash | common.Hash | Keccak256(address) |
origin | *types.StateAccount | Original account data |
data | types.StateAccount | Current account data |
trie | Trie | Storage trie |
code | Code | Contract bytecode |
originStorage | Storage | Original storage |
pendingStorage | Storage | Pending storage (awaiting commit) |
dirtyStorage | Storage | Modified storage during execution |
dirtyCode | bool | Code modification flag |
selfDestructed | bool | Self-destruct marker |
deleted | bool | Deletion marker |
created | bool | Created in current transaction |
Journaling and Snapshots
StateDB records all state changes in a journal to guarantee rollback capability.Each journal entry implements a
revert() method and includes the following change types:
balanceChangenonceChangestorageChangecodeChangeextraChangecreateObjectChangeselfDestructChangetouchChangeaddLogChange
Merkle Patricia Trie Implementation
The Merkle Patricia Trie (MPT) is the core cryptographic data structure used to store state.StableNet supports both hash-based and path-based storage schemes.
Trie Node Types
| Node Type | Purpose | Structure |
|---|---|---|
fullNode | 16-way branching | Children [17]node |
shortNode | Path compression | Key []byte, Val node |
valueNode | Leaf value | []byte |
hashNode | Hash reference | []byte |
Storage Schemes: Hash vs Path
StableNet supports two trie storage schemes.| Scheme | Key Format | Purpose |
|---|---|---|
| Hash Scheme | Node hash | Content-addressed storage |
| Path Scheme | Trie path | History and pruning support |
The hash scheme is simpler but does not embed history.
BlockChain Caching Strategy
BlockChain minimizes database access by using multiple LRU caches.| Cache | Size | Purpose |
|---|---|---|
| bodyCache | 256 | Block bodies |
| blockCache | 256 | Full blocks |
| receiptsCache | 32 | Receipts |
| txLookupCache | 1024 | Transaction lookup |
| headerCache | 512 | Block headers |
| tdCache | 1024 | Total difficulty |
| numberCache | 2048 | Hash → block number |
Snapshot System
Snapshots provide a flattened view of state, enabling fast access to accounts and storage without traversing the state trie.Snapshot Layers
| Layer | Purpose | Storage |
|---|---|---|
difflayer | Recent changes | Memory |
disklayer | Base state | Disk |
Snapshot Configuration
| Field | Default | Purpose |
|---|---|---|
SnapshotLimit | 256MB | Snapshot cache size |
SnapshotNoBuild | false | Disable background building |
SnapshotWait | true | Wait on startup |
State Commit and Finalization
State changes proceed through modification → finalization → trie update → commit stages.The final result is returned as a new state root hash.
Raw Database and Ancient Store
At the lowest level, a key-value database is used, and old data is migrated to the ancient store.Ancient Store Characteristics
- Reduced active database size
- Fast sequential access to historical data
- Enables pruning of the active database
- Supports Era1 archive generation
Cache Configuration Summary
| Configuration | Default | Purpose |
|---|---|---|
TrieCleanLimit | 256MB | Clean trie cache |
TrieDirtyLimit | 256MB | Dirty trie cache |
TrieTimeLimit | 5 minutes | Flush delay |
SnapshotLimit | 256MB | Snapshot cache |
StateHistory | 0 | State history |
bodyCacheLimit | 256 | Block bodies |
blockCacheLimit | 256 | Full blocks |
receiptsCacheLimit | 32 | Receipts |
txLookupCacheLimit | 1024 | Transaction lookup |