reth_engine_tree/tree/
cached_state.rs

1//! Execution cache implementation for block processing.
2use alloy_primitives::{Address, StorageKey, StorageValue, B256};
3use metrics::Gauge;
4use mini_moka::sync::CacheBuilder;
5use reth_errors::ProviderResult;
6use reth_metrics::Metrics;
7use reth_primitives_traits::{Account, Bytecode};
8use reth_provider::{
9    AccountReader, BlockHashReader, BytecodeReader, HashedPostStateProvider, StateProofProvider,
10    StateProvider, StateRootProvider, StorageRootProvider,
11};
12use reth_revm::db::BundleState;
13use reth_trie::{
14    updates::TrieUpdates, AccountProof, HashedPostState, HashedStorage, MultiProof,
15    MultiProofTargets, StorageMultiProof, StorageProof, TrieInput,
16};
17use revm_primitives::map::DefaultHashBuilder;
18use std::time::Duration;
19use tracing::trace;
20
21pub(crate) type Cache<K, V> =
22    mini_moka::sync::Cache<K, V, alloy_primitives::map::DefaultHashBuilder>;
23
24/// A wrapper of a state provider and a shared cache.
25pub(crate) struct CachedStateProvider<S> {
26    /// The state provider
27    state_provider: S,
28
29    /// The caches used for the provider
30    caches: ExecutionCache,
31
32    /// Metrics for the cached state provider
33    metrics: CachedStateMetrics,
34}
35
36impl<S> CachedStateProvider<S>
37where
38    S: StateProvider,
39{
40    /// Creates a new [`CachedStateProvider`] from an [`ExecutionCache`], state provider, and
41    /// [`CachedStateMetrics`].
42    pub(crate) const fn new_with_caches(
43        state_provider: S,
44        caches: ExecutionCache,
45        metrics: CachedStateMetrics,
46    ) -> Self {
47        Self { state_provider, caches, metrics }
48    }
49}
50
51/// Metrics for the cached state provider, showing hits / misses for each cache
52#[derive(Metrics, Clone)]
53#[metrics(scope = "sync.caching")]
54pub(crate) struct CachedStateMetrics {
55    /// Code cache hits
56    code_cache_hits: Gauge,
57
58    /// Code cache misses
59    code_cache_misses: Gauge,
60
61    /// Code cache size
62    ///
63    /// NOTE: this uses the moka caches' `entry_count`, NOT the `weighted_size` method to calculate
64    /// size.
65    code_cache_size: Gauge,
66
67    /// Storage cache hits
68    storage_cache_hits: Gauge,
69
70    /// Storage cache misses
71    storage_cache_misses: Gauge,
72
73    /// Storage cache size
74    ///
75    /// NOTE: this uses the moka caches' `entry_count`, NOT the `weighted_size` method to calculate
76    /// size.
77    storage_cache_size: Gauge,
78
79    /// Account cache hits
80    account_cache_hits: Gauge,
81
82    /// Account cache misses
83    account_cache_misses: Gauge,
84
85    /// Account cache size
86    ///
87    /// NOTE: this uses the moka caches' `entry_count`, NOT the `weighted_size` method to calculate
88    /// size.
89    account_cache_size: Gauge,
90}
91
92impl CachedStateMetrics {
93    /// Sets all values to zero, indicating that a new block is being executed.
94    pub(crate) fn reset(&self) {
95        // code cache
96        self.code_cache_hits.set(0);
97        self.code_cache_misses.set(0);
98
99        // storage cache
100        self.storage_cache_hits.set(0);
101        self.storage_cache_misses.set(0);
102
103        // account cache
104        self.account_cache_hits.set(0);
105        self.account_cache_misses.set(0);
106    }
107
108    /// Returns a new zeroed-out instance of [`CachedStateMetrics`].
109    pub(crate) fn zeroed() -> Self {
110        let zeroed = Self::default();
111        zeroed.reset();
112        zeroed
113    }
114}
115
116impl<S: AccountReader> AccountReader for CachedStateProvider<S> {
117    fn basic_account(&self, address: &Address) -> ProviderResult<Option<Account>> {
118        if let Some(res) = self.caches.account_cache.get(address) {
119            self.metrics.account_cache_hits.increment(1);
120            return Ok(res)
121        }
122
123        self.metrics.account_cache_misses.increment(1);
124
125        let res = self.state_provider.basic_account(address)?;
126        self.caches.account_cache.insert(*address, res);
127        Ok(res)
128    }
129}
130
131/// Represents the status of a storage slot in the cache.
132#[derive(Debug, Clone, PartialEq, Eq)]
133pub(crate) enum SlotStatus {
134    /// The account's storage cache doesn't exist.
135    NotCached,
136    /// The storage slot exists in cache and is empty (value is zero).
137    Empty,
138    /// The storage slot exists in cache and has a specific non-zero value.
139    Value(StorageValue),
140}
141
142impl<S: StateProvider> StateProvider for CachedStateProvider<S> {
143    fn storage(
144        &self,
145        account: Address,
146        storage_key: StorageKey,
147    ) -> ProviderResult<Option<StorageValue>> {
148        match self.caches.get_storage(&account, &storage_key) {
149            SlotStatus::NotCached => {
150                self.metrics.storage_cache_misses.increment(1);
151                let final_res = self.state_provider.storage(account, storage_key)?;
152                self.caches.insert_storage(account, storage_key, final_res);
153                Ok(final_res)
154            }
155            SlotStatus::Empty => {
156                self.metrics.storage_cache_hits.increment(1);
157                Ok(None)
158            }
159            SlotStatus::Value(value) => {
160                self.metrics.storage_cache_hits.increment(1);
161                Ok(Some(value))
162            }
163        }
164    }
165}
166
167impl<S: BytecodeReader> BytecodeReader for CachedStateProvider<S> {
168    fn bytecode_by_hash(&self, code_hash: &B256) -> ProviderResult<Option<Bytecode>> {
169        if let Some(res) = self.caches.code_cache.get(code_hash) {
170            self.metrics.code_cache_hits.increment(1);
171            return Ok(res)
172        }
173
174        self.metrics.code_cache_misses.increment(1);
175
176        let final_res = self.state_provider.bytecode_by_hash(code_hash)?;
177        self.caches.code_cache.insert(*code_hash, final_res.clone());
178        Ok(final_res)
179    }
180}
181
182impl<S: StateRootProvider> StateRootProvider for CachedStateProvider<S> {
183    fn state_root(&self, hashed_state: HashedPostState) -> ProviderResult<B256> {
184        self.state_provider.state_root(hashed_state)
185    }
186
187    fn state_root_from_nodes(&self, input: TrieInput) -> ProviderResult<B256> {
188        self.state_provider.state_root_from_nodes(input)
189    }
190
191    fn state_root_with_updates(
192        &self,
193        hashed_state: HashedPostState,
194    ) -> ProviderResult<(B256, TrieUpdates)> {
195        self.state_provider.state_root_with_updates(hashed_state)
196    }
197
198    fn state_root_from_nodes_with_updates(
199        &self,
200        input: TrieInput,
201    ) -> ProviderResult<(B256, TrieUpdates)> {
202        self.state_provider.state_root_from_nodes_with_updates(input)
203    }
204}
205
206impl<S: StateProofProvider> StateProofProvider for CachedStateProvider<S> {
207    fn proof(
208        &self,
209        input: TrieInput,
210        address: Address,
211        slots: &[B256],
212    ) -> ProviderResult<AccountProof> {
213        self.state_provider.proof(input, address, slots)
214    }
215
216    fn multiproof(
217        &self,
218        input: TrieInput,
219        targets: MultiProofTargets,
220    ) -> ProviderResult<MultiProof> {
221        self.state_provider.multiproof(input, targets)
222    }
223
224    fn witness(
225        &self,
226        input: TrieInput,
227        target: HashedPostState,
228    ) -> ProviderResult<Vec<alloy_primitives::Bytes>> {
229        self.state_provider.witness(input, target)
230    }
231}
232
233impl<S: StorageRootProvider> StorageRootProvider for CachedStateProvider<S> {
234    fn storage_root(
235        &self,
236        address: Address,
237        hashed_storage: HashedStorage,
238    ) -> ProviderResult<B256> {
239        self.state_provider.storage_root(address, hashed_storage)
240    }
241
242    fn storage_proof(
243        &self,
244        address: Address,
245        slot: B256,
246        hashed_storage: HashedStorage,
247    ) -> ProviderResult<StorageProof> {
248        self.state_provider.storage_proof(address, slot, hashed_storage)
249    }
250
251    /// Generate a storage multiproof for multiple storage slots.
252    ///
253    /// A **storage multiproof** is a cryptographic proof that can verify the values
254    /// of multiple storage slots for a single account in a single verification step.
255    /// Instead of generating separate proofs for each slot (which would be inefficient),
256    /// a multiproof bundles the necessary trie nodes to prove all requested slots.
257    ///
258    /// ## How it works:
259    /// 1. Takes an account address and a list of storage slot keys
260    /// 2. Traverses the account's storage trie to collect proof nodes
261    /// 3. Returns a [`StorageMultiProof`] containing the minimal set of trie nodes needed to verify
262    ///    all the requested storage slots
263    fn storage_multiproof(
264        &self,
265        address: Address,
266        slots: &[B256],
267        hashed_storage: HashedStorage,
268    ) -> ProviderResult<StorageMultiProof> {
269        self.state_provider.storage_multiproof(address, slots, hashed_storage)
270    }
271}
272
273impl<S: BlockHashReader> BlockHashReader for CachedStateProvider<S> {
274    fn block_hash(&self, number: alloy_primitives::BlockNumber) -> ProviderResult<Option<B256>> {
275        self.state_provider.block_hash(number)
276    }
277
278    fn canonical_hashes_range(
279        &self,
280        start: alloy_primitives::BlockNumber,
281        end: alloy_primitives::BlockNumber,
282    ) -> ProviderResult<Vec<B256>> {
283        self.state_provider.canonical_hashes_range(start, end)
284    }
285}
286
287impl<S: HashedPostStateProvider> HashedPostStateProvider for CachedStateProvider<S> {
288    fn hashed_post_state(&self, bundle_state: &reth_revm::db::BundleState) -> HashedPostState {
289        self.state_provider.hashed_post_state(bundle_state)
290    }
291}
292
293/// Execution cache used during block processing.
294///
295/// Optimizes state access by maintaining in-memory copies of frequently accessed
296/// accounts, storage slots, and bytecode. Works in conjunction with prewarming
297/// to reduce database I/O during block execution.
298#[derive(Debug, Clone)]
299pub(crate) struct ExecutionCache {
300    /// Cache for contract bytecode, keyed by code hash.
301    code_cache: Cache<B256, Option<Bytecode>>,
302
303    /// Per-account storage cache: outer cache keyed by Address, inner cache tracks that account’s
304    /// storage slots.
305    storage_cache: Cache<Address, AccountStorageCache>,
306
307    /// Cache for basic account information (nonce, balance, code hash).
308    account_cache: Cache<Address, Option<Account>>,
309}
310
311impl ExecutionCache {
312    /// Get storage value from hierarchical cache.
313    ///
314    /// Returns a `SlotStatus` indicating whether:
315    /// - `NotCached`: The account's storage cache doesn't exist
316    /// - `Empty`: The slot exists in the account's cache but is empty
317    /// - `Value`: The slot exists and has a specific value
318    pub(crate) fn get_storage(&self, address: &Address, key: &StorageKey) -> SlotStatus {
319        match self.storage_cache.get(address) {
320            None => SlotStatus::NotCached,
321            Some(account_cache) => account_cache.get_storage(key),
322        }
323    }
324
325    /// Insert storage value into hierarchical cache
326    pub(crate) fn insert_storage(
327        &self,
328        address: Address,
329        key: StorageKey,
330        value: Option<StorageValue>,
331    ) {
332        let account_cache = self.storage_cache.get(&address).unwrap_or_else(|| {
333            let account_cache = AccountStorageCache::default();
334            self.storage_cache.insert(address, account_cache.clone());
335            account_cache
336        });
337        account_cache.insert_storage(key, value);
338    }
339
340    /// Invalidate storage for specific account
341    pub(crate) fn invalidate_account_storage(&self, address: &Address) {
342        self.storage_cache.invalidate(address);
343    }
344
345    /// Returns the total number of storage slots cached across all accounts
346    pub(crate) fn total_storage_slots(&self) -> usize {
347        self.storage_cache.iter().map(|addr| addr.len()).sum()
348    }
349
350    /// Inserts the post-execution state changes into the cache.
351    ///
352    /// This method is called after transaction execution to update the cache with
353    /// the touched and modified state. The insertion order is critical:
354    ///
355    /// 1. Bytecodes: Insert contract code first
356    /// 2. Storage slots: Update storage values for each account
357    /// 3. Accounts: Update account info (nonce, balance, code hash)
358    ///
359    /// ## Why This Order Matters
360    ///
361    /// Account information references bytecode via code hash. If we update accounts
362    /// before bytecode, we might create cache entries pointing to non-existent code.
363    /// The current order ensures cache consistency.
364    ///
365    /// ## Error Handling
366    ///
367    /// Returns an error if the state updates are inconsistent and should be discarded.
368    pub(crate) fn insert_state(&self, state_updates: &BundleState) -> Result<(), ()> {
369        // Insert bytecodes
370        for (code_hash, bytecode) in &state_updates.contracts {
371            self.code_cache.insert(*code_hash, Some(Bytecode(bytecode.clone())));
372        }
373
374        for (addr, account) in &state_updates.state {
375            // If the account was not modified, as in not changed and not destroyed, then we have
376            // nothing to do w.r.t. this particular account and can move on
377            if account.status.is_not_modified() {
378                continue
379            }
380
381            // If the account was destroyed, invalidate from the account / storage caches
382            if account.was_destroyed() {
383                // Invalidate the account cache entry if destroyed
384                self.account_cache.invalidate(addr);
385
386                self.invalidate_account_storage(addr);
387                continue
388            }
389
390            // If we have an account that was modified, but it has a `None` account info, some wild
391            // error has occurred because this state should be unrepresentable. An account with
392            // `None` current info, should be destroyed.
393            let Some(ref account_info) = account.info else {
394                trace!(target: "engine::caching", ?account, "Account with None account info found in state updates");
395                return Err(())
396            };
397
398            // Now we iterate over all storage and make updates to the cached storage values
399            for (storage_key, slot) in &account.storage {
400                // We convert the storage key from U256 to B256 because that is how it's represented
401                // in the cache
402                self.insert_storage(*addr, (*storage_key).into(), Some(slot.present_value));
403            }
404
405            // Insert will update if present, so we just use the new account info as the new value
406            // for the account cache
407            self.account_cache.insert(*addr, Some(Account::from(account_info)));
408        }
409
410        Ok(())
411    }
412}
413
414/// A builder for [`ExecutionCache`].
415#[derive(Debug)]
416pub(crate) struct ExecutionCacheBuilder {
417    /// Code cache entries
418    code_cache_entries: u64,
419
420    /// Storage cache entries
421    storage_cache_entries: u64,
422
423    /// Account cache entries
424    account_cache_entries: u64,
425}
426
427impl ExecutionCacheBuilder {
428    /// Build an [`ExecutionCache`] struct, so that execution caches can be easily cloned.
429    pub(crate) fn build_caches(self, total_cache_size: u64) -> ExecutionCache {
430        let storage_cache_size = (total_cache_size * 8888) / 10000; // 88.88% of total
431        let account_cache_size = (total_cache_size * 556) / 10000; // 5.56% of total
432        let code_cache_size = (total_cache_size * 556) / 10000; // 5.56% of total
433
434        const EXPIRY_TIME: Duration = Duration::from_secs(7200); // 2 hours
435        const TIME_TO_IDLE: Duration = Duration::from_secs(3600); // 1 hour
436
437        let storage_cache = CacheBuilder::new(self.storage_cache_entries)
438            .weigher(|_key: &Address, value: &AccountStorageCache| -> u32 {
439                // values based on results from measure_storage_cache_overhead test
440                let base_weight = 39_000;
441                let slots_weight = value.len() * 218;
442                (base_weight + slots_weight) as u32
443            })
444            .max_capacity(storage_cache_size)
445            .time_to_live(EXPIRY_TIME)
446            .time_to_idle(TIME_TO_IDLE)
447            .build_with_hasher(DefaultHashBuilder::default());
448
449        let account_cache = CacheBuilder::new(self.account_cache_entries)
450            .weigher(|_key: &Address, value: &Option<Account>| -> u32 {
451                match value {
452                    Some(account) => {
453                        let mut weight = 40;
454                        if account.nonce != 0 {
455                            weight += 32;
456                        }
457                        if !account.balance.is_zero() {
458                            weight += 32;
459                        }
460                        if account.bytecode_hash.is_some() {
461                            weight += 33; // size of Option<B256>
462                        } else {
463                            weight += 8; // size of None variant
464                        }
465                        weight as u32
466                    }
467                    None => 8, // size of None variant
468                }
469            })
470            .max_capacity(account_cache_size)
471            .time_to_live(EXPIRY_TIME)
472            .time_to_idle(TIME_TO_IDLE)
473            .build_with_hasher(DefaultHashBuilder::default());
474
475        let code_cache = CacheBuilder::new(self.code_cache_entries)
476            .weigher(|_key: &B256, value: &Option<Bytecode>| -> u32 {
477                match value {
478                    Some(bytecode) => {
479                        // base weight + actual bytecode size
480                        (40 + bytecode.len()) as u32
481                    }
482                    None => 8, // size of None variant
483                }
484            })
485            .max_capacity(code_cache_size)
486            .time_to_live(EXPIRY_TIME)
487            .time_to_idle(TIME_TO_IDLE)
488            .build_with_hasher(DefaultHashBuilder::default());
489
490        ExecutionCache { code_cache, storage_cache, account_cache }
491    }
492}
493
494impl Default for ExecutionCacheBuilder {
495    fn default() -> Self {
496        // With weigher and max_capacity in place, these numbers represent
497        // the maximum number of entries that can be stored, not the actual
498        // memory usage which is controlled by max_capacity.
499        //
500        // Code cache: up to 10M entries but limited to 0.5GB
501        // Storage cache: up to 10M accounts but limited to 8GB
502        // Account cache: up to 10M accounts but limited to 0.5GB
503        Self {
504            code_cache_entries: 10_000_000,
505            storage_cache_entries: 10_000_000,
506            account_cache_entries: 10_000_000,
507        }
508    }
509}
510
511/// A saved cache that has been used for executing a specific block, which has been updated for its
512/// execution.
513#[derive(Debug, Clone)]
514pub(crate) struct SavedCache {
515    /// The hash of the block these caches were used to execute.
516    hash: B256,
517
518    /// The caches used for the provider.
519    caches: ExecutionCache,
520
521    /// Metrics for the cached state provider
522    metrics: CachedStateMetrics,
523}
524
525impl SavedCache {
526    /// Creates a new instance with the internals
527    pub(super) const fn new(
528        hash: B256,
529        caches: ExecutionCache,
530        metrics: CachedStateMetrics,
531    ) -> Self {
532        Self { hash, caches, metrics }
533    }
534
535    /// Returns the hash for this cache
536    pub(crate) const fn executed_block_hash(&self) -> B256 {
537        self.hash
538    }
539
540    /// Splits the cache into its caches and metrics, consuming it.
541    pub(crate) fn split(self) -> (ExecutionCache, CachedStateMetrics) {
542        (self.caches, self.metrics)
543    }
544
545    /// Returns the [`ExecutionCache`] belonging to the tracked hash.
546    pub(crate) const fn cache(&self) -> &ExecutionCache {
547        &self.caches
548    }
549
550    /// Updates the metrics for the [`ExecutionCache`].
551    pub(crate) fn update_metrics(&self) {
552        self.metrics.storage_cache_size.set(self.caches.total_storage_slots() as f64);
553        self.metrics.account_cache_size.set(self.caches.account_cache.entry_count() as f64);
554        self.metrics.code_cache_size.set(self.caches.code_cache.entry_count() as f64);
555    }
556}
557
558/// Cache for an individual account's storage slots.
559///
560/// This represents the second level of the hierarchical storage cache.
561/// Each account gets its own `AccountStorageCache` to store accessed storage slots.
562#[derive(Debug, Clone)]
563pub(crate) struct AccountStorageCache {
564    /// Map of storage keys to their cached values.
565    slots: Cache<StorageKey, Option<StorageValue>>,
566}
567
568impl AccountStorageCache {
569    /// Create a new [`AccountStorageCache`]
570    pub(crate) fn new(max_slots: u64) -> Self {
571        Self {
572            slots: CacheBuilder::new(max_slots).build_with_hasher(DefaultHashBuilder::default()),
573        }
574    }
575
576    /// Get a storage value from this account's cache.
577    /// - `NotCached`: The slot is not in the cache
578    /// - `Empty`: The slot is empty
579    /// - `Value`: The slot has a specific value
580    pub(crate) fn get_storage(&self, key: &StorageKey) -> SlotStatus {
581        match self.slots.get(key) {
582            None => SlotStatus::NotCached,
583            Some(None) => SlotStatus::Empty,
584            Some(Some(value)) => SlotStatus::Value(value),
585        }
586    }
587
588    /// Insert a storage value
589    pub(crate) fn insert_storage(&self, key: StorageKey, value: Option<StorageValue>) {
590        self.slots.insert(key, value);
591    }
592
593    /// Returns the number of slots in the cache
594    pub(crate) fn len(&self) -> usize {
595        self.slots.entry_count() as usize
596    }
597}
598
599impl Default for AccountStorageCache {
600    fn default() -> Self {
601        // With weigher and max_capacity in place, this number represents
602        // the maximum number of entries that can be stored, not the actual
603        // memory usage which is controlled by storage cache's max_capacity.
604        Self::new(1_000_000)
605    }
606}
607
608#[cfg(test)]
609mod tests {
610    use super::*;
611    use alloy_primitives::{B256, U256};
612    use rand::Rng;
613    use reth_provider::test_utils::{ExtendedAccount, MockEthProvider};
614    use std::mem::size_of;
615
616    mod tracking_allocator {
617        use std::{
618            alloc::{GlobalAlloc, Layout, System},
619            sync::atomic::{AtomicUsize, Ordering},
620        };
621
622        #[derive(Debug)]
623        pub(crate) struct TrackingAllocator {
624            allocated: AtomicUsize,
625            total_allocated: AtomicUsize,
626            inner: System,
627        }
628
629        impl TrackingAllocator {
630            pub(crate) const fn new() -> Self {
631                Self {
632                    allocated: AtomicUsize::new(0),
633                    total_allocated: AtomicUsize::new(0),
634                    inner: System,
635                }
636            }
637
638            pub(crate) fn reset(&self) {
639                self.allocated.store(0, Ordering::SeqCst);
640                self.total_allocated.store(0, Ordering::SeqCst);
641            }
642
643            pub(crate) fn total_allocated(&self) -> usize {
644                self.total_allocated.load(Ordering::SeqCst)
645            }
646        }
647
648        unsafe impl GlobalAlloc for TrackingAllocator {
649            unsafe fn alloc(&self, layout: Layout) -> *mut u8 {
650                let ret = self.inner.alloc(layout);
651                if !ret.is_null() {
652                    self.allocated.fetch_add(layout.size(), Ordering::SeqCst);
653                    self.total_allocated.fetch_add(layout.size(), Ordering::SeqCst);
654                }
655                ret
656            }
657
658            unsafe fn dealloc(&self, ptr: *mut u8, layout: Layout) {
659                self.allocated.fetch_sub(layout.size(), Ordering::SeqCst);
660                self.inner.dealloc(ptr, layout)
661            }
662        }
663    }
664
665    use tracking_allocator::TrackingAllocator;
666
667    #[global_allocator]
668    static ALLOCATOR: TrackingAllocator = TrackingAllocator::new();
669
670    fn measure_allocation<T, F>(f: F) -> (usize, T)
671    where
672        F: FnOnce() -> T,
673    {
674        ALLOCATOR.reset();
675        let result = f();
676        let total = ALLOCATOR.total_allocated();
677        (total, result)
678    }
679
680    #[test]
681    fn measure_storage_cache_overhead() {
682        let (base_overhead, cache) = measure_allocation(|| AccountStorageCache::new(1000));
683        println!("Base AccountStorageCache overhead: {base_overhead} bytes");
684        let mut rng = rand::rng();
685
686        let key = StorageKey::random();
687        let value = StorageValue::from(rng.random::<u128>());
688        let (first_slot, _) = measure_allocation(|| {
689            cache.insert_storage(key, Some(value));
690        });
691        println!("First slot insertion overhead: {first_slot} bytes");
692
693        const TOTAL_SLOTS: usize = 10_000;
694        let (test_slots, _) = measure_allocation(|| {
695            for _ in 0..TOTAL_SLOTS {
696                let key = StorageKey::random();
697                let value = StorageValue::from(rng.random::<u128>());
698                cache.insert_storage(key, Some(value));
699            }
700        });
701        println!("Average overhead over {} slots: {} bytes", TOTAL_SLOTS, test_slots / TOTAL_SLOTS);
702
703        println!("\nTheoretical sizes:");
704        println!("StorageKey size: {} bytes", size_of::<StorageKey>());
705        println!("StorageValue size: {} bytes", size_of::<StorageValue>());
706        println!("Option<StorageValue> size: {} bytes", size_of::<Option<StorageValue>>());
707        println!("Option<B256> size: {} bytes", size_of::<Option<B256>>());
708    }
709
710    #[test]
711    fn test_empty_storage_cached_state_provider() {
712        // make sure when we have an empty value in storage, we return `Empty` and not `NotCached`
713        let address = Address::random();
714        let storage_key = StorageKey::random();
715        let account = ExtendedAccount::new(0, U256::ZERO);
716
717        // note there is no storage here
718        let provider = MockEthProvider::default();
719        provider.extend_accounts(vec![(address, account)]);
720
721        let caches = ExecutionCacheBuilder::default().build_caches(1000);
722        let state_provider =
723            CachedStateProvider::new_with_caches(provider, caches, CachedStateMetrics::zeroed());
724
725        // check that the storage is empty
726        let res = state_provider.storage(address, storage_key);
727        assert!(res.is_ok());
728        assert_eq!(res.unwrap(), None);
729    }
730
731    #[test]
732    fn test_uncached_storage_cached_state_provider() {
733        // make sure when we have something uncached, we get the cached value
734        let address = Address::random();
735        let storage_key = StorageKey::random();
736        let storage_value = U256::from(1);
737        let account =
738            ExtendedAccount::new(0, U256::ZERO).extend_storage(vec![(storage_key, storage_value)]);
739
740        // note that we extend storage here with one value
741        let provider = MockEthProvider::default();
742        provider.extend_accounts(vec![(address, account)]);
743
744        let caches = ExecutionCacheBuilder::default().build_caches(1000);
745        let state_provider =
746            CachedStateProvider::new_with_caches(provider, caches, CachedStateMetrics::zeroed());
747
748        // check that the storage is empty
749        let res = state_provider.storage(address, storage_key);
750        assert!(res.is_ok());
751        assert_eq!(res.unwrap(), Some(storage_value));
752    }
753
754    #[test]
755    fn test_get_storage_populated() {
756        // make sure when we have something cached, we get the cached value in the `SlotStatus`
757        let address = Address::random();
758        let storage_key = StorageKey::random();
759        let storage_value = U256::from(1);
760
761        // insert into caches directly
762        let caches = ExecutionCacheBuilder::default().build_caches(1000);
763        caches.insert_storage(address, storage_key, Some(storage_value));
764
765        // check that the storage is empty
766        let slot_status = caches.get_storage(&address, &storage_key);
767        assert_eq!(slot_status, SlotStatus::Value(storage_value));
768    }
769
770    #[test]
771    fn test_get_storage_not_cached() {
772        // make sure when we have nothing cached, we get the `NotCached` value in the `SlotStatus`
773        let storage_key = StorageKey::random();
774        let address = Address::random();
775
776        // just create empty caches
777        let caches = ExecutionCacheBuilder::default().build_caches(1000);
778
779        // check that the storage is empty
780        let slot_status = caches.get_storage(&address, &storage_key);
781        assert_eq!(slot_status, SlotStatus::NotCached);
782    }
783
784    #[test]
785    fn test_get_storage_empty() {
786        // make sure when we insert an empty value to the cache, we get the `Empty` value in the
787        // `SlotStatus`
788        let address = Address::random();
789        let storage_key = StorageKey::random();
790
791        // insert into caches directly
792        let caches = ExecutionCacheBuilder::default().build_caches(1000);
793        caches.insert_storage(address, storage_key, None);
794
795        // check that the storage is empty
796        let slot_status = caches.get_storage(&address, &storage_key);
797        assert_eq!(slot_status, SlotStatus::Empty);
798    }
799}