Storage Architecture

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 a stateObject, 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:

• balanceChange
• nonceChange
• storageChange
• codeChange
• extraChange
• createObjectChange
• selfDestructChange
• touchChange
• addLogChange

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 path scheme enables state history, efficient pruning, and historical state queries.
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 access order is diff → disk → trie fallback.

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