1use alloy_primitives::{
4 map::{AddressMap, AddressSet, DefaultHashBuilder, FbBuildHasher},
5 Address, Bytes,
6};
7use evm2::{
8 evm::{
9 precompile::{PrecompileOutput, PrecompileProvider},
10 PrewarmSet,
11 },
12 interpreter::{GasTracker, Message},
13 Evm, EvmTypesHost, PrecompileError,
14};
15use moka::policy::EvictionPolicy;
16#[cfg(feature = "metrics")]
17use reth_metrics::Metrics;
18use reth_primitives_traits::dashmap::DashMap;
19use std::{fmt, hash::Hash, sync::Arc};
20use tracing::error;
21
22const MAX_CACHE_SIZE: u32 = 1024 * 1024;
24
25const MAX_PRECOMPILE_CACHE_INPUT_SIZE: usize = 2 * 1024;
27
28pub struct PrecompileCacheMap<S>(Arc<DashMap<Address, Arc<PrecompileCache<S>>, FbBuildHasher<20>>>);
30
31impl<S> fmt::Debug for PrecompileCacheMap<S> {
32 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
33 f.debug_struct("PrecompileCacheMap").finish_non_exhaustive()
34 }
35}
36
37impl<S> Clone for PrecompileCacheMap<S> {
38 fn clone(&self) -> Self {
39 Self(Arc::clone(&self.0))
40 }
41}
42
43impl<S> Default for PrecompileCacheMap<S> {
44 fn default() -> Self {
45 Self(Arc::new(DashMap::with_hasher(Default::default())))
46 }
47}
48
49impl<S> PrecompileCacheMap<S>
50where
51 S: Eq + Hash + std::fmt::Debug + Send + Sync + Clone + 'static,
52{
53 fn cache_for_address(&self, address: Address) -> Arc<PrecompileCache<S>> {
55 if let Some(cache) = self.0.get(&address) {
56 return cache.clone()
57 }
58
59 self.0.entry(address).or_default().clone()
60 }
61}
62
63struct PrecompileCache<S> {
65 cache: moka::sync::Cache<Bytes, CacheEntry<S>, DefaultHashBuilder>,
66 #[cfg(feature = "metrics")]
67 metrics: std::sync::OnceLock<CachedPrecompileMetrics>,
68}
69
70impl<S> fmt::Debug for PrecompileCache<S> {
71 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
72 f.debug_struct("PrecompileCache").finish_non_exhaustive()
73 }
74}
75
76impl<S> Default for PrecompileCache<S>
77where
78 S: Eq + Hash + std::fmt::Debug + Send + Sync + Clone + 'static,
79{
80 fn default() -> Self {
81 Self {
82 cache: moka::sync::CacheBuilder::new(MAX_CACHE_SIZE as u64)
83 .eviction_policy(EvictionPolicy::lru())
84 .weigher(|key: &Bytes, value: &CacheEntry<S>| {
85 (key.len() + value.output.bytes().len()) as u32
86 })
87 .build_with_hasher(Default::default()),
88 #[cfg(feature = "metrics")]
89 metrics: Default::default(),
90 }
91 }
92}
93
94impl<S> PrecompileCache<S>
95where
96 S: Eq + Hash + std::fmt::Debug + Send + Sync + Clone + 'static,
97{
98 fn get(&self, input: &[u8], spec: S) -> Option<CacheEntry<S>> {
99 self.cache.get(input).filter(|entry| entry.spec == spec)
100 }
101
102 fn insert(&self, input: Bytes, value: CacheEntry<S>) -> usize {
103 self.cache.insert(input, value);
104 self.cache.entry_count() as usize
105 }
106}
107
108#[derive(Debug, Clone, PartialEq, Eq)]
110struct CacheEntry<S> {
111 output: PrecompileOutput,
112 regular_gas_used: u64,
113 spec: S,
114}
115
116pub struct CachedPrecompileProvider<T, S>
118where
119 T: EvmTypesHost,
120 S: Eq + Hash + std::fmt::Debug + Send + Sync + Clone + 'static,
121{
122 inner: evm2::Precompiles<T>,
123 cache_map: PrecompileCacheMap<S>,
124 caches: AddressMap<Arc<PrecompileCache<S>>>,
126 spec_id: S,
127 policy: PrecompileCachePolicy,
128 #[cfg_attr(not(feature = "metrics"), allow(dead_code))]
129 metrics_enabled: bool,
130}
131
132impl<T, S> fmt::Debug for CachedPrecompileProvider<T, S>
133where
134 T: EvmTypesHost,
135 S: Eq + Hash + std::fmt::Debug + Send + Sync + Clone + 'static,
136{
137 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
138 f.debug_struct("CachedPrecompileProvider").finish_non_exhaustive()
139 }
140}
141
142impl<T, S> CachedPrecompileProvider<T, S>
143where
144 T: EvmTypesHost,
145 S: Eq + Hash + std::fmt::Debug + Send + Sync + Clone + 'static,
146{
147 pub fn new(
152 inner: evm2::Precompiles<T>,
153 cache_map: PrecompileCacheMap<S>,
154 spec_id: S,
155 policy: PrecompileCachePolicy,
156 metrics_enabled: bool,
157 ) -> Self {
158 Self { inner, cache_map, caches: Default::default(), spec_id, policy, metrics_enabled }
159 }
160}
161
162impl<T, S> PrecompileProvider<T> for CachedPrecompileProvider<T, S>
163where
164 T: EvmTypesHost,
165 S: Eq + Hash + std::fmt::Debug + Send + Sync + Clone + 'static,
166{
167 fn addresses(&self) -> Vec<Address> {
168 self.inner.addresses()
169 }
170
171 fn warm_addresses(&self, warm: &mut PrewarmSet) {
172 self.inner.warm_addresses(warm);
173 }
174
175 fn precompile_ids(&self) -> Vec<(Address, evm2::precompiles::PrecompileId)> {
176 self.inner.precompile_ids()
177 }
178
179 fn move_precompiles(
180 &mut self,
181 moves: &[(Address, Address)],
182 ) -> Result<(), evm2::precompiles::MovePrecompileError> {
183 self.inner.move_precompiles(moves)?;
184 if moves.iter().any(|(source, dest)| source != dest) {
185 if let PrecompileCachePolicy::Addresses(addresses) = &mut self.policy {
186 let mut sources = AddressSet::default();
187 let moved = moves
188 .iter()
189 .filter(|(source, dest)| source != dest && sources.insert(*source))
190 .map(|(source, dest)| (*source, *dest, addresses.contains(source)))
191 .collect::<Vec<_>>();
192 let addresses = Arc::make_mut(addresses);
193 for (source, _, _) in &moved {
194 addresses.remove(source);
195 }
196 for (_, dest, cacheable) in moved {
197 if cacheable {
198 addresses.insert(dest);
199 } else {
200 addresses.remove(&dest);
201 }
202 }
203 }
204 self.cache_map = PrecompileCacheMap::default();
208 self.caches.clear();
209 }
210 Ok(())
211 }
212
213 fn contains(&self, address: &Address) -> bool {
214 self.inner.contains(address)
215 }
216
217 fn execute(
218 &mut self,
219 evm: &mut Evm<'_, T>,
220 message: &Message<T>,
221 gas: &mut GasTracker,
222 ) -> Option<Result<PrecompileOutput, PrecompileError>> {
223 let address = message.call_target;
224 if !self.policy.allows(&address) {
225 return self.inner.execute(evm, message, gas);
226 }
227 let cache =
228 self.caches.entry(address).or_insert_with(|| self.cache_map.cache_for_address(address));
229 #[cfg(feature = "metrics")]
230 let metrics = self.metrics_enabled.then(|| {
231 cache.metrics.get_or_init(|| CachedPrecompileMetrics::new_with_address(address))
232 });
233
234 let cacheable_input = message.input.len() <= MAX_PRECOMPILE_CACHE_INPUT_SIZE;
235 if cacheable_input &&
236 let Some(entry) = cache.get(evm.message_input(message), self.spec_id.clone())
237 {
238 return Some(match gas.spend(entry.regular_gas_used).map_err(PrecompileError::from) {
239 Ok(()) => {
240 #[cfg(feature = "metrics")]
241 if let Some(metrics) = metrics {
242 metrics.precompile_cache_hits.increment(1);
243 }
244 Ok(entry.output)
245 }
246 Err(err) => {
247 #[cfg(feature = "metrics")]
248 if let Some(metrics) = metrics {
249 metrics.precompile_errors.increment(1);
250 }
251 Err(err)
252 }
253 })
254 }
255
256 let input = cacheable_input.then(|| Bytes::copy_from_slice(evm.message_input(message)));
258 let before = GasSnapshot::new(gas);
259 let result = self.inner.execute(evm, message, gas)?;
260 let after = GasSnapshot::new(gas);
261
262 match &result {
263 Ok(output) if let Some(input) = input => {
264 if before.reservoir != after.reservoir {
265 error!(
266 target: "evm::precompile_cache",
267 %address,
268 "cacheable precompile decremented reservoir, skipping cache insertion"
269 );
270 } else if before.state_gas_spent != after.state_gas_spent {
271 error!(
272 target: "evm::precompile_cache",
273 %address,
274 "cacheable precompile used state gas, skipping cache insertion"
275 );
276 } else if before.refunded != after.refunded {
277 error!(
278 target: "evm::precompile_cache",
279 %address,
280 "cacheable precompile changed refund gas, skipping cache insertion"
281 );
282 } else if let Some(regular_gas_used) = after.spent.checked_sub(before.spent) {
283 let _size = cache.insert(
284 input,
285 CacheEntry {
286 output: output.clone(),
287 regular_gas_used,
288 spec: self.spec_id.clone(),
289 },
290 );
291 #[cfg(feature = "metrics")]
292 if let Some(metrics) = metrics {
293 metrics.precompile_cache_size.set(_size as f64);
294 metrics.precompile_cache_misses.increment(1);
295 }
296 } else {
297 error!(
298 target: "evm::precompile_cache",
299 %address,
300 "cacheable precompile returned regular gas, skipping cache insertion"
301 );
302 }
303 }
304 Ok(_) => {}
305 Err(_) =>
306 {
307 #[cfg(feature = "metrics")]
308 if let Some(metrics) = metrics {
309 metrics.precompile_errors.increment(1);
310 }
311 }
312 }
313
314 Some(result)
315 }
316}
317
318#[derive(Debug, Clone, Default)]
323pub enum PrecompileCachePolicy {
324 #[default]
326 Disabled,
327 All,
329 Addresses(Arc<AddressSet>),
331}
332
333impl PrecompileCachePolicy {
334 fn allows(&self, address: &Address) -> bool {
335 match self {
336 Self::Disabled => false,
337 Self::All => true,
338 Self::Addresses(addresses) => addresses.contains(address),
339 }
340 }
341}
342
343#[derive(Debug)]
344struct GasSnapshot {
345 spent: u64,
346 reservoir: u64,
347 state_gas_spent: i64,
348 refunded: i64,
349}
350
351impl GasSnapshot {
352 const fn new(gas: &GasTracker) -> Self {
353 Self {
354 spent: gas.spent(),
355 reservoir: gas.reservoir(),
356 state_gas_spent: gas.state_gas_spent(),
357 refunded: gas.refunded(),
358 }
359 }
360}
361
362#[cfg(feature = "metrics")]
364#[derive(Metrics, Clone)]
365#[metrics(scope = "sync.caching")]
366pub struct CachedPrecompileMetrics {
367 pub precompile_cache_hits: metrics::Counter,
369
370 pub precompile_cache_misses: metrics::Counter,
372
373 pub precompile_cache_size: metrics::Gauge,
375
376 pub precompile_errors: metrics::Counter,
378}
379
380#[cfg(feature = "metrics")]
381impl CachedPrecompileMetrics {
382 pub fn new_with_address(address: Address) -> Self {
384 Self::new_with_labels(&[("address", format!("0x{address:02x}"))])
385 }
386}
387
388#[cfg(test)]
389mod tests {
390 use super::*;
391 use alloy_primitives::{Address, B256, U256};
392 use evm2::{
393 env::BlockEnv,
394 evm::{precompile::NoPrecompiles, InMemoryDB},
395 interpreter::{Message, MessageKind},
396 registry::TxRegistry,
397 BaseEvmTypes, SpecId,
398 };
399
400 #[test]
401 fn cached_precompile_metadata_matches_inner() {
402 let precompiles = evm2::Precompiles::<BaseEvmTypes>::base(SpecId::OSAKA);
403 let expected = precompiles.precompile_ids();
404 assert!(!expected.is_empty());
405 let cached = CachedPrecompileProvider::new(
406 precompiles,
407 PrecompileCacheMap::default(),
408 SpecId::OSAKA,
409 PrecompileCachePolicy::All,
410 false,
411 );
412 assert_eq!(cached.precompile_ids(), expected);
413 }
414
415 #[test]
416 fn moves_preserve_custom_precompiles_with_borrowed_database() {
417 let spec = SpecId::OSAKA;
418 let identity = Address::with_last_byte(4);
419 let custom = Address::with_last_byte(0x40);
420 let moved = Address::with_last_byte(0x41);
421 let mut precompiles = evm2::Precompiles::<BaseEvmTypes>::base(spec);
422 let custom_entry = precompiles.as_map_mut().remove(identity).unwrap().with_address(custom);
423 precompiles.as_map_mut().insert(custom_entry);
424 let provider = CachedPrecompileProvider::new(
425 precompiles,
426 PrecompileCacheMap::default(),
427 spec,
428 PrecompileCachePolicy::All,
429 false,
430 );
431 let mut database = InMemoryDB::default();
432 let mut evm = Evm::<BaseEvmTypes>::new(
433 spec,
434 BlockEnv::<BaseEvmTypes>::default(),
435 TxRegistry::new(),
436 &mut database,
437 provider,
438 );
439 let standard = Address::with_last_byte(2);
440 crate::Evm::move_precompiles(&mut evm, [(standard, moved)]).unwrap();
441 assert!(evm.precompiles().contains(&custom));
442 assert!(!evm.precompiles().contains(&identity));
443 assert!(!evm.precompiles().contains(&standard));
444 crate::Evm::move_precompiles(&mut evm, [(custom, identity)]).unwrap();
445 assert!(!evm.precompiles().contains(&custom));
446 assert!(evm.precompiles().contains(&identity));
447 assert!(evm.precompiles().contains(&moved));
448 let before = evm.precompiles().precompile_ids();
449 assert!(crate::Evm::move_precompiles(&mut evm, [(custom, standard)]).is_err());
450 assert_eq!(evm.precompiles().precompile_ids(), before);
451 }
452
453 #[test]
454 fn moves_isolate_cached_outputs_without_disabling_caching() {
455 let spec = SpecId::OSAKA;
456 let identity = Address::with_last_byte(4);
457 let destination = Address::with_last_byte(2);
458 let input = Bytes::from_static(b"input");
459 let shared = PrecompileCacheMap::default();
460 shared.cache_for_address(destination).insert(
461 input.clone(),
462 CacheEntry {
463 output: PrecompileOutput::new(Bytes::from_static(b"old implementation")),
464 regular_gas_used: 60,
465 spec,
466 },
467 );
468 let mut provider = CachedPrecompileProvider::new(
469 evm2::Precompiles::<BaseEvmTypes>::base(spec),
470 shared.clone(),
471 spec,
472 PrecompileCachePolicy::Addresses(Arc::new(AddressSet::from_iter([identity]))),
473 false,
474 );
475 provider.move_precompiles(&[(identity, destination)]).unwrap();
476 let mut evm = Evm::<BaseEvmTypes>::new(
477 spec,
478 BlockEnv::<BaseEvmTypes>::default(),
479 TxRegistry::new(),
480 InMemoryDB::default(),
481 NoPrecompiles::default(),
482 );
483 let message = Message::<BaseEvmTypes> {
484 kind: MessageKind::Call,
485 gas_limit: 30_000,
486 destination,
487 code_address: destination,
488 call_target: destination,
489 input: input.clone().into(),
490 ..Default::default()
491 };
492 for _ in 0..2 {
493 let output = provider
494 .execute(&mut evm, &message, &mut GasTracker::new(30_000))
495 .unwrap()
496 .unwrap();
497 assert_eq!(output.bytes(), input.as_ref());
498 }
499 assert_eq!(
500 provider
501 .cache_map
502 .cache_for_address(destination)
503 .get(&input, spec)
504 .unwrap()
505 .output
506 .bytes(),
507 input.as_ref()
508 );
509 assert_eq!(
510 shared.cache_for_address(destination).get(&input, spec).unwrap().output.bytes(),
511 b"old implementation"
512 );
513 }
514
515 #[test]
516 fn caches_successful_precompile_output() {
517 let cache_map = PrecompileCacheMap::default();
518 let mut provider = CachedPrecompileProvider::new(
519 evm2::Precompiles::base(SpecId::OSAKA),
520 cache_map.clone(),
521 SpecId::OSAKA,
522 PrecompileCachePolicy::All,
523 false,
524 );
525 let mut evm = Evm::<BaseEvmTypes>::new(
526 SpecId::OSAKA,
527 BlockEnv::<BaseEvmTypes>::default(),
528 TxRegistry::new(),
529 InMemoryDB::default(),
530 NoPrecompiles::default(),
531 );
532 let address = Address::with_last_byte(4);
533 let message = Message::<BaseEvmTypes> {
534 kind: MessageKind::Call,
535 gas_limit: 30_000,
536 destination: address,
537 caller: Address::ZERO,
538 input: Bytes::copy_from_slice(b"cached-input").into(),
539 value: U256::ZERO,
540 code_address: address,
541 call_target: address,
542 salt: B256::ZERO,
543 ..Default::default()
544 };
545
546 let mut gas = GasTracker::new(30_000);
547 let output = provider
548 .execute(&mut evm, &message, &mut gas)
549 .expect("identity precompile exists")
550 .expect("identity precompile succeeds");
551 assert_eq!(output.bytes(), b"cached-input");
552
553 let cache = cache_map.cache_for_address(address);
554 let entry =
555 cache.get(evm.message_input(&message), SpecId::OSAKA).expect("cache entry exists");
556 assert_eq!(entry.output.bytes(), b"cached-input");
557 assert_eq!(entry.regular_gas_used, 18);
558
559 let mut hit_gas = GasTracker::new(30_000);
560 let output = provider
561 .execute(&mut evm, &message, &mut hit_gas)
562 .expect("identity precompile exists")
563 .expect("cached identity precompile succeeds");
564 assert_eq!(output.bytes(), b"cached-input");
565 assert_eq!(hit_gas.spent(), 18);
566 }
567 #[test]
568 fn identity_cache_obeys_input_size_boundary() {
569 let cache = PrecompileCacheMap::default();
570 let mut provider = CachedPrecompileProvider::new(
571 evm2::Precompiles::base(SpecId::OSAKA),
572 cache.clone(),
573 SpecId::OSAKA,
574 PrecompileCachePolicy::All,
575 false,
576 );
577 let mut evm = Evm::<BaseEvmTypes>::new(
578 SpecId::OSAKA,
579 BlockEnv::<BaseEvmTypes>::default(),
580 TxRegistry::new(),
581 InMemoryDB::default(),
582 NoPrecompiles::default(),
583 );
584 let address = Address::with_last_byte(4);
585 for len in [2048, 2049] {
586 let message = Message::<BaseEvmTypes> {
587 kind: MessageKind::Call,
588 gas_limit: 30_000,
589 destination: address,
590 code_address: address,
591 call_target: address,
592 input: Bytes::from(vec![1; len]).into(),
593 ..Default::default()
594 };
595 let output = provider
596 .execute(&mut evm, &message, &mut GasTracker::new(30_000))
597 .unwrap()
598 .unwrap();
599 assert_eq!(output.bytes(), evm.message_input(&message));
600 assert_eq!(
601 cache
602 .cache_for_address(address)
603 .get(evm.message_input(&message), SpecId::OSAKA)
604 .is_some(),
605 len == 2048
606 );
607 }
608 }
609
610 #[test]
611 fn caller_dependent_precompiles_are_not_cached() {
612 let spec = SpecId::OSAKA;
613 let custom = Address::with_last_byte(0x40);
614 let identity = Address::with_last_byte(4);
615 for policy in [
616 PrecompileCachePolicy::Disabled,
617 PrecompileCachePolicy::Addresses(Arc::new(AddressSet::from_iter([identity]))),
618 ] {
619 let cache = PrecompileCacheMap::default();
620 let mut precompiles = evm2::Precompiles::<BaseEvmTypes>::base(spec);
621 precompiles.as_map_mut().insert(evm2::precompiles::Precompile::new(
622 custom,
623 evm2::precompiles::PrecompileId::custom("caller"),
624 |_, message, gas| {
625 gas.spend(10)?;
626 Ok(PrecompileOutput::new(Bytes::copy_from_slice(message.caller.as_slice())))
627 },
628 ));
629 let mut provider =
630 CachedPrecompileProvider::new(precompiles, cache.clone(), spec, policy, false);
631 provider.move_precompiles(&[(identity, custom), (custom, identity)]).unwrap();
633 let mut evm = Evm::<BaseEvmTypes>::new(
634 spec,
635 BlockEnv::<BaseEvmTypes>::default(),
636 TxRegistry::new(),
637 InMemoryDB::default(),
638 NoPrecompiles::default(),
639 );
640 for caller in [Address::repeat_byte(0xaa), Address::repeat_byte(0xbb)] {
641 let message = Message::<BaseEvmTypes> {
642 caller,
643 destination: identity,
644 code_address: identity,
645 call_target: identity,
646 gas_limit: 30_000,
647 ..Default::default()
648 };
649 let output = provider
650 .execute(&mut evm, &message, &mut GasTracker::new(30_000))
651 .unwrap()
652 .unwrap();
653 assert_eq!(output.bytes(), caller.as_slice());
654 }
655 assert!(!cache.0.contains_key(&identity));
656 assert!(!provider.cache_map.0.contains_key(&identity));
657 }
658 }
659}