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: ProviderCaches,
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: ProviderCaches,
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(
252 &self,
253 address: Address,
254 slots: &[B256],
255 hashed_storage: HashedStorage,
256 ) -> ProviderResult<StorageMultiProof> {
257 self.state_provider.storage_multiproof(address, slots, hashed_storage)
258 }
259}
260
261impl<S: BlockHashReader> BlockHashReader for CachedStateProvider<S> {
262 fn block_hash(&self, number: alloy_primitives::BlockNumber) -> ProviderResult<Option<B256>> {
263 self.state_provider.block_hash(number)
264 }
265
266 fn canonical_hashes_range(
267 &self,
268 start: alloy_primitives::BlockNumber,
269 end: alloy_primitives::BlockNumber,
270 ) -> ProviderResult<Vec<B256>> {
271 self.state_provider.canonical_hashes_range(start, end)
272 }
273}
274
275impl<S: HashedPostStateProvider> HashedPostStateProvider for CachedStateProvider<S> {
276 fn hashed_post_state(&self, bundle_state: &reth_revm::db::BundleState) -> HashedPostState {
277 self.state_provider.hashed_post_state(bundle_state)
278 }
279}
280
281#[derive(Debug, Clone)]
283pub(crate) struct ProviderCaches {
284 code_cache: Cache<B256, Option<Bytecode>>,
286
287 storage_cache: Cache<Address, AccountStorageCache>,
289
290 account_cache: Cache<Address, Option<Account>>,
292}
293
294impl ProviderCaches {
295 pub(crate) fn get_storage(&self, address: &Address, key: &StorageKey) -> SlotStatus {
302 match self.storage_cache.get(address) {
303 None => SlotStatus::NotCached,
304 Some(account_cache) => account_cache.get_storage(key),
305 }
306 }
307
308 pub(crate) fn insert_storage(
310 &self,
311 address: Address,
312 key: StorageKey,
313 value: Option<StorageValue>,
314 ) {
315 let account_cache = self.storage_cache.get(&address).unwrap_or_else(|| {
316 let account_cache = AccountStorageCache::default();
317 self.storage_cache.insert(address, account_cache.clone());
318 account_cache
319 });
320 account_cache.insert_storage(key, value);
321 }
322
323 pub(crate) fn invalidate_account_storage(&self, address: &Address) {
325 self.storage_cache.invalidate(address);
326 }
327
328 pub(crate) fn total_storage_slots(&self) -> usize {
330 self.storage_cache.iter().map(|addr| addr.len()).sum()
331 }
332
333 pub(crate) fn insert_state(&self, state_updates: &BundleState) -> Result<(), ()> {
346 for (code_hash, bytecode) in &state_updates.contracts {
348 self.code_cache.insert(*code_hash, Some(Bytecode(bytecode.clone())));
349 }
350
351 for (addr, account) in &state_updates.state {
352 if account.status.is_not_modified() {
355 continue
356 }
357
358 if account.was_destroyed() {
360 self.account_cache.invalidate(addr);
362
363 self.invalidate_account_storage(addr);
364 continue
365 }
366
367 let Some(ref account_info) = account.info else {
371 trace!(target: "engine::caching", ?account, "Account with None account info found in state updates");
372 return Err(())
373 };
374
375 for (storage_key, slot) in &account.storage {
377 self.insert_storage(*addr, (*storage_key).into(), Some(slot.present_value));
380 }
381
382 self.account_cache.insert(*addr, Some(Account::from(account_info)));
385 }
386
387 Ok(())
388 }
389}
390
391#[derive(Debug)]
393pub(crate) struct ProviderCacheBuilder {
394 code_cache_entries: u64,
396
397 storage_cache_entries: u64,
399
400 account_cache_entries: u64,
402}
403
404impl ProviderCacheBuilder {
405 pub(crate) fn build_caches(self, total_cache_size: u64) -> ProviderCaches {
407 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)
415 .weigher(|_key: &Address, value: &AccountStorageCache| -> u32 {
416 let base_weight = 39_000;
418 let slots_weight = value.len() * 218;
419 (base_weight + slots_weight) as u32
420 })
421 .max_capacity(storage_cache_size)
422 .time_to_live(EXPIRY_TIME)
423 .time_to_idle(TIME_TO_IDLE)
424 .build_with_hasher(DefaultHashBuilder::default());
425
426 let account_cache = CacheBuilder::new(self.account_cache_entries)
427 .weigher(|_key: &Address, value: &Option<Account>| -> u32 {
428 match value {
429 Some(account) => {
430 let mut weight = 40;
431 if account.nonce != 0 {
432 weight += 32;
433 }
434 if !account.balance.is_zero() {
435 weight += 32;
436 }
437 if account.bytecode_hash.is_some() {
438 weight += 33; } else {
440 weight += 8; }
442 weight as u32
443 }
444 None => 8, }
446 })
447 .max_capacity(account_cache_size)
448 .time_to_live(EXPIRY_TIME)
449 .time_to_idle(TIME_TO_IDLE)
450 .build_with_hasher(DefaultHashBuilder::default());
451
452 let code_cache = CacheBuilder::new(self.code_cache_entries)
453 .weigher(|_key: &B256, value: &Option<Bytecode>| -> u32 {
454 match value {
455 Some(bytecode) => {
456 (40 + bytecode.len()) as u32
458 }
459 None => 8, }
461 })
462 .max_capacity(code_cache_size)
463 .time_to_live(EXPIRY_TIME)
464 .time_to_idle(TIME_TO_IDLE)
465 .build_with_hasher(DefaultHashBuilder::default());
466
467 ProviderCaches { code_cache, storage_cache, account_cache }
468 }
469}
470
471impl Default for ProviderCacheBuilder {
472 fn default() -> Self {
473 Self {
481 code_cache_entries: 10_000_000,
482 storage_cache_entries: 10_000_000,
483 account_cache_entries: 10_000_000,
484 }
485 }
486}
487
488#[derive(Debug, Clone)]
491pub(crate) struct SavedCache {
492 hash: B256,
494
495 caches: ProviderCaches,
497
498 metrics: CachedStateMetrics,
500}
501
502impl SavedCache {
503 pub(super) const fn new(
505 hash: B256,
506 caches: ProviderCaches,
507 metrics: CachedStateMetrics,
508 ) -> Self {
509 Self { hash, caches, metrics }
510 }
511
512 pub(crate) const fn executed_block_hash(&self) -> B256 {
514 self.hash
515 }
516
517 pub(crate) fn split(self) -> (ProviderCaches, CachedStateMetrics) {
519 (self.caches, self.metrics)
520 }
521
522 pub(crate) const fn cache(&self) -> &ProviderCaches {
524 &self.caches
525 }
526
527 pub(crate) fn update_metrics(&self) {
529 self.metrics.storage_cache_size.set(self.caches.total_storage_slots() as f64);
530 self.metrics.account_cache_size.set(self.caches.account_cache.entry_count() as f64);
531 self.metrics.code_cache_size.set(self.caches.code_cache.entry_count() as f64);
532 }
533}
534
535#[derive(Debug, Clone)]
537pub(crate) struct AccountStorageCache {
538 slots: Cache<StorageKey, Option<StorageValue>>,
540}
541
542impl AccountStorageCache {
543 pub(crate) fn new(max_slots: u64) -> Self {
545 Self {
546 slots: CacheBuilder::new(max_slots).build_with_hasher(DefaultHashBuilder::default()),
547 }
548 }
549
550 pub(crate) fn get_storage(&self, key: &StorageKey) -> SlotStatus {
555 match self.slots.get(key) {
556 None => SlotStatus::NotCached,
557 Some(None) => SlotStatus::Empty,
558 Some(Some(value)) => SlotStatus::Value(value),
559 }
560 }
561
562 pub(crate) fn insert_storage(&self, key: StorageKey, value: Option<StorageValue>) {
564 self.slots.insert(key, value);
565 }
566
567 pub(crate) fn len(&self) -> usize {
569 self.slots.entry_count() as usize
570 }
571}
572
573impl Default for AccountStorageCache {
574 fn default() -> Self {
575 Self::new(1_000_000)
579 }
580}
581
582#[cfg(test)]
583mod tests {
584 use super::*;
585 use alloy_primitives::{B256, U256};
586 use rand::Rng;
587 use reth_provider::test_utils::{ExtendedAccount, MockEthProvider};
588 use std::mem::size_of;
589
590 mod tracking_allocator {
591 use std::{
592 alloc::{GlobalAlloc, Layout, System},
593 sync::atomic::{AtomicUsize, Ordering},
594 };
595
596 #[derive(Debug)]
597 pub(crate) struct TrackingAllocator {
598 allocated: AtomicUsize,
599 total_allocated: AtomicUsize,
600 inner: System,
601 }
602
603 impl TrackingAllocator {
604 pub(crate) const fn new() -> Self {
605 Self {
606 allocated: AtomicUsize::new(0),
607 total_allocated: AtomicUsize::new(0),
608 inner: System,
609 }
610 }
611
612 pub(crate) fn reset(&self) {
613 self.allocated.store(0, Ordering::SeqCst);
614 self.total_allocated.store(0, Ordering::SeqCst);
615 }
616
617 pub(crate) fn total_allocated(&self) -> usize {
618 self.total_allocated.load(Ordering::SeqCst)
619 }
620 }
621
622 unsafe impl GlobalAlloc for TrackingAllocator {
623 unsafe fn alloc(&self, layout: Layout) -> *mut u8 {
624 let ret = self.inner.alloc(layout);
625 if !ret.is_null() {
626 self.allocated.fetch_add(layout.size(), Ordering::SeqCst);
627 self.total_allocated.fetch_add(layout.size(), Ordering::SeqCst);
628 }
629 ret
630 }
631
632 unsafe fn dealloc(&self, ptr: *mut u8, layout: Layout) {
633 self.allocated.fetch_sub(layout.size(), Ordering::SeqCst);
634 self.inner.dealloc(ptr, layout)
635 }
636 }
637 }
638
639 use tracking_allocator::TrackingAllocator;
640
641 #[global_allocator]
642 static ALLOCATOR: TrackingAllocator = TrackingAllocator::new();
643
644 fn measure_allocation<T, F>(f: F) -> (usize, T)
645 where
646 F: FnOnce() -> T,
647 {
648 ALLOCATOR.reset();
649 let result = f();
650 let total = ALLOCATOR.total_allocated();
651 (total, result)
652 }
653
654 #[test]
655 fn measure_storage_cache_overhead() {
656 let (base_overhead, cache) = measure_allocation(|| AccountStorageCache::new(1000));
657 println!("Base AccountStorageCache overhead: {base_overhead} bytes");
658 let mut rng = rand::rng();
659
660 let key = StorageKey::random();
661 let value = StorageValue::from(rng.random::<u128>());
662 let (first_slot, _) = measure_allocation(|| {
663 cache.insert_storage(key, Some(value));
664 });
665 println!("First slot insertion overhead: {first_slot} bytes");
666
667 const TOTAL_SLOTS: usize = 10_000;
668 let (test_slots, _) = measure_allocation(|| {
669 for _ in 0..TOTAL_SLOTS {
670 let key = StorageKey::random();
671 let value = StorageValue::from(rng.random::<u128>());
672 cache.insert_storage(key, Some(value));
673 }
674 });
675 println!("Average overhead over {} slots: {} bytes", TOTAL_SLOTS, test_slots / TOTAL_SLOTS);
676
677 println!("\nTheoretical sizes:");
678 println!("StorageKey size: {} bytes", size_of::<StorageKey>());
679 println!("StorageValue size: {} bytes", size_of::<StorageValue>());
680 println!("Option<StorageValue> size: {} bytes", size_of::<Option<StorageValue>>());
681 println!("Option<B256> size: {} bytes", size_of::<Option<B256>>());
682 }
683
684 #[test]
685 fn test_empty_storage_cached_state_provider() {
686 let address = Address::random();
688 let storage_key = StorageKey::random();
689 let account = ExtendedAccount::new(0, U256::ZERO);
690
691 let provider = MockEthProvider::default();
693 provider.extend_accounts(vec![(address, account)]);
694
695 let caches = ProviderCacheBuilder::default().build_caches(1000);
696 let state_provider =
697 CachedStateProvider::new_with_caches(provider, caches, CachedStateMetrics::zeroed());
698
699 let res = state_provider.storage(address, storage_key);
701 assert!(res.is_ok());
702 assert_eq!(res.unwrap(), None);
703 }
704
705 #[test]
706 fn test_uncached_storage_cached_state_provider() {
707 let address = Address::random();
709 let storage_key = StorageKey::random();
710 let storage_value = U256::from(1);
711 let account =
712 ExtendedAccount::new(0, U256::ZERO).extend_storage(vec![(storage_key, storage_value)]);
713
714 let provider = MockEthProvider::default();
716 provider.extend_accounts(vec![(address, account)]);
717
718 let caches = ProviderCacheBuilder::default().build_caches(1000);
719 let state_provider =
720 CachedStateProvider::new_with_caches(provider, caches, CachedStateMetrics::zeroed());
721
722 let res = state_provider.storage(address, storage_key);
724 assert!(res.is_ok());
725 assert_eq!(res.unwrap(), Some(storage_value));
726 }
727
728 #[test]
729 fn test_get_storage_populated() {
730 let address = Address::random();
732 let storage_key = StorageKey::random();
733 let storage_value = U256::from(1);
734
735 let caches = ProviderCacheBuilder::default().build_caches(1000);
737 caches.insert_storage(address, storage_key, Some(storage_value));
738
739 let slot_status = caches.get_storage(&address, &storage_key);
741 assert_eq!(slot_status, SlotStatus::Value(storage_value));
742 }
743
744 #[test]
745 fn test_get_storage_not_cached() {
746 let storage_key = StorageKey::random();
748 let address = Address::random();
749
750 let caches = ProviderCacheBuilder::default().build_caches(1000);
752
753 let slot_status = caches.get_storage(&address, &storage_key);
755 assert_eq!(slot_status, SlotStatus::NotCached);
756 }
757
758 #[test]
759 fn test_get_storage_empty() {
760 let address = Address::random();
763 let storage_key = StorageKey::random();
764
765 let caches = ProviderCacheBuilder::default().build_caches(1000);
767 caches.insert_storage(address, storage_key, None);
768
769 let slot_status = caches.get_storage(&address, &storage_key);
771 assert_eq!(slot_status, SlotStatus::Empty);
772 }
773}