1use 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
24pub(crate) struct CachedStateProvider<S> {
26 state_provider: S,
28
29 caches: ExecutionCache,
31
32 metrics: CachedStateMetrics,
34}
35
36impl<S> CachedStateProvider<S>
37where
38 S: StateProvider,
39{
40 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#[derive(Metrics, Clone)]
53#[metrics(scope = "sync.caching")]
54pub(crate) struct CachedStateMetrics {
55 code_cache_hits: Gauge,
57
58 code_cache_misses: Gauge,
60
61 code_cache_size: Gauge,
66
67 storage_cache_hits: Gauge,
69
70 storage_cache_misses: Gauge,
72
73 storage_cache_size: Gauge,
78
79 account_cache_hits: Gauge,
81
82 account_cache_misses: Gauge,
84
85 account_cache_size: Gauge,
90}
91
92impl CachedStateMetrics {
93 pub(crate) fn reset(&self) {
95 self.code_cache_hits.set(0);
97 self.code_cache_misses.set(0);
98
99 self.storage_cache_hits.set(0);
101 self.storage_cache_misses.set(0);
102
103 self.account_cache_hits.set(0);
105 self.account_cache_misses.set(0);
106 }
107
108 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#[derive(Debug, Clone, PartialEq, Eq)]
133pub(crate) enum SlotStatus {
134 NotCached,
136 Empty,
138 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 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#[derive(Debug, Clone)]
299pub(crate) struct ExecutionCache {
300 code_cache: Cache<B256, Option<Bytecode>>,
302
303 storage_cache: Cache<Address, AccountStorageCache>,
306
307 account_cache: Cache<Address, Option<Account>>,
309}
310
311impl ExecutionCache {
312 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 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 pub(crate) fn invalidate_account_storage(&self, address: &Address) {
342 self.storage_cache.invalidate(address);
343 }
344
345 pub(crate) fn total_storage_slots(&self) -> usize {
347 self.storage_cache.iter().map(|addr| addr.len()).sum()
348 }
349
350 pub(crate) fn insert_state(&self, state_updates: &BundleState) -> Result<(), ()> {
369 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 account.status.is_not_modified() {
378 continue
379 }
380
381 if account.was_destroyed() {
383 self.account_cache.invalidate(addr);
385
386 self.invalidate_account_storage(addr);
387 continue
388 }
389
390 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 for (storage_key, slot) in &account.storage {
400 self.insert_storage(*addr, (*storage_key).into(), Some(slot.present_value));
403 }
404
405 self.account_cache.insert(*addr, Some(Account::from(account_info)));
408 }
409
410 Ok(())
411 }
412}
413
414#[derive(Debug)]
416pub(crate) struct ExecutionCacheBuilder {
417 code_cache_entries: u64,
419
420 storage_cache_entries: u64,
422
423 account_cache_entries: u64,
425}
426
427impl ExecutionCacheBuilder {
428 pub(crate) fn build_caches(self, total_cache_size: u64) -> ExecutionCache {
430 let storage_cache_size = (total_cache_size * 8888) / 10000; let account_cache_size = (total_cache_size * 556) / 10000; let code_cache_size = (total_cache_size * 556) / 10000; const EXPIRY_TIME: Duration = Duration::from_secs(7200); const TIME_TO_IDLE: Duration = Duration::from_secs(3600); let storage_cache = CacheBuilder::new(self.storage_cache_entries)
438 .weigher(|_key: &Address, value: &AccountStorageCache| -> u32 {
439 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; } else {
463 weight += 8; }
465 weight as u32
466 }
467 None => 8, }
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 (40 + bytecode.len()) as u32
481 }
482 None => 8, }
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 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#[derive(Debug, Clone)]
514pub(crate) struct SavedCache {
515 hash: B256,
517
518 caches: ExecutionCache,
520
521 metrics: CachedStateMetrics,
523}
524
525impl SavedCache {
526 pub(super) const fn new(
528 hash: B256,
529 caches: ExecutionCache,
530 metrics: CachedStateMetrics,
531 ) -> Self {
532 Self { hash, caches, metrics }
533 }
534
535 pub(crate) const fn executed_block_hash(&self) -> B256 {
537 self.hash
538 }
539
540 pub(crate) fn split(self) -> (ExecutionCache, CachedStateMetrics) {
542 (self.caches, self.metrics)
543 }
544
545 pub(crate) const fn cache(&self) -> &ExecutionCache {
547 &self.caches
548 }
549
550 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#[derive(Debug, Clone)]
563pub(crate) struct AccountStorageCache {
564 slots: Cache<StorageKey, Option<StorageValue>>,
566}
567
568impl AccountStorageCache {
569 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 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 pub(crate) fn insert_storage(&self, key: StorageKey, value: Option<StorageValue>) {
590 self.slots.insert(key, value);
591 }
592
593 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 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 let address = Address::random();
714 let storage_key = StorageKey::random();
715 let account = ExtendedAccount::new(0, U256::ZERO);
716
717 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 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 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 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 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 let address = Address::random();
758 let storage_key = StorageKey::random();
759 let storage_value = U256::from(1);
760
761 let caches = ExecutionCacheBuilder::default().build_caches(1000);
763 caches.insert_storage(address, storage_key, Some(storage_value));
764
765 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 let storage_key = StorageKey::random();
774 let address = Address::random();
775
776 let caches = ExecutionCacheBuilder::default().build_caches(1000);
778
779 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 let address = Address::random();
789 let storage_key = StorageKey::random();
790
791 let caches = ExecutionCacheBuilder::default().build_caches(1000);
793 caches.insert_storage(address, storage_key, None);
794
795 let slot_status = caches.get_storage(&address, &storage_key);
797 assert_eq!(slot_status, SlotStatus::Empty);
798 }
799}