ethrex_storage/
lib.rs

1//! # ethrex Storage
2//!
3//! This crate provides persistent storage for the ethrex Ethereum client.
4//!
5//! ## Overview
6//!
7//! The storage layer handles:
8//! - Block storage (headers, bodies, receipts)
9//! - State storage (accounts, code, storage slots)
10//! - Merkle Patricia Trie management
11//! - Transaction indexing
12//! - Chain configuration
13//!
14//! ## Architecture
15//!
16//! ```text
17//! ┌─────────────────────────────────────────────────┐
18//! │                    Store                        │
19//! │  (High-level API for blockchain operations)     │
20//! └─────────────────────────────────────────────────┘
21//!                        │
22//!           ┌────────────┴────────────┐
23//!           ▼                         ▼
24//! ┌─────────────────┐       ┌─────────────────┐
25//! │  InMemoryBackend │       │  RocksDBBackend │
26//! │    (Testing)     │       │  (Production)   │
27//! └─────────────────┘       └─────────────────┘
28//! ```
29//!
30//! ## Storage Backends
31//!
32//! - **InMemory**: Fast, non-persistent storage for testing
33//! - **RocksDB**: Production-grade persistent storage (requires `rocksdb` feature)
34//!
35//! ## Usage
36//!
37//! ```ignore
38//! use ethrex_storage::{Store, EngineType};
39//!
40//! // Create a new store with RocksDB backend
41//! let store = Store::new("./data", EngineType::RocksDB)?;
42//!
43//! // Or from a genesis file
44//! let store = Store::new_from_genesis(
45//!     Path::new("./data"),
46//!     EngineType::RocksDB,
47//!     "genesis.json"
48//! ).await?;
49//!
50//! // Add a block
51//! store.add_block(block).await?;
52//!
53//! // Query state
54//! let balance = store.get_account_info(block_number, address)?.map(|a| a.balance);
55//! ```
56//!
57//! ## State Management
58//!
59//! State is stored using Merkle Patricia Tries for efficient verification:
60//! - **State Trie**: Maps account addresses to account data
61//! - **Storage Tries**: Maps storage keys to values for each contract
62//! - **Code Storage**: Separate storage for contract bytecode
63//!
64//! The store maintains a cache layer (`TrieLayerCache`) for efficient state access
65//! without requiring full trie traversal for recent blocks.
66
67pub mod api;
68pub mod backend;
69pub mod error;
70mod layering;
71pub mod migrations;
72pub mod rlp;
73pub mod store;
74pub mod trie;
75pub mod utils;
76
77pub use layering::apply_prefix;
78pub use store::{
79    AccountUpdatesList, DEFAULT_ROCKSDB_BLOCK_CACHE_SIZE_BYTES, EngineType, Store, StoreConfig,
80    UpdateBatch, has_valid_db, hash_address, hash_key, read_chain_id_from_db,
81};
82
83/// Store Schema Version, must be updated on any breaking change.
84///
85/// When bumping this version, add a corresponding migration function to
86/// `migrations::MIGRATIONS`. The migration framework will automatically
87/// upgrade existing databases instead of requiring a full resync.
88pub const STORE_SCHEMA_VERSION: u64 = 3;
89
90/// Name of the file storing the metadata about the database.
91///
92/// This file contains version information and is used to detect
93/// incompatible database formats on startup.
94pub const STORE_METADATA_FILENAME: &str = "metadata.json";
ethrex_storage/lib.rs

ethrex_storage/
lib.rs
