Skip to main content

reth_evm/
precompile_cache.rs

1//! Precompile cache for payload prewarming.
2
3use 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
22/// Default max cache size for [`PrecompileCache`].
23const MAX_CACHE_SIZE: u32 = 1024 * 1024;
24
25/// Maximum input retained by a precompile cache.
26const MAX_PRECOMPILE_CACHE_INPUT_SIZE: usize = 2 * 1024;
27
28/// Stores caches for each precompile.
29pub 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    /// Get the precompile cache for the given address.
54    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
63/// Cache for one precompile's inputs and outputs.
64struct 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/// Cache entry for a successful precompile output.
109#[derive(Debug, Clone, PartialEq, Eq)]
110struct CacheEntry<S> {
111    output: PrecompileOutput,
112    regular_gas_used: u64,
113    spec: S,
114}
115
116/// A caching EVM precompile provider.
117pub 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 already resolved from `cache_map`, so repeated calls skip the shared map lookup.
125    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    /// Creates a new cached precompile provider.
148    ///
149    /// Metrics are labelled by address and shared with the cache. Disable them for prewarming
150    /// so speculative work does not count towards execution cache statistics.
151    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            // The shared cache still belongs to the unmodified table used by other EVMs.
205            // Relocated entries need a private cache because address alone no longer identifies
206            // the same precompile implementation.
207            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        // Copy the input before running the precompile: it may be a range of the caller's memory.
257        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/// Precompiles whose output and gas usage depend only on input and specification.
319///
320/// Eligible precompiles must not read execution context or state, mutate state, or emit logs.
321/// Custom factories are uncached unless they explicitly select a policy.
322#[derive(Debug, Clone, Default)]
323pub enum PrecompileCachePolicy {
324    /// No precompiles are eligible for caching.
325    #[default]
326    Disabled,
327    /// Every installed precompile is pure and eligible for caching.
328    All,
329    /// Only these precompile implementations are eligible for caching.
330    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/// Metrics for the cached precompile.
363#[cfg(feature = "metrics")]
364#[derive(Metrics, Clone)]
365#[metrics(scope = "sync.caching")]
366pub struct CachedPrecompileMetrics {
367    /// Precompile cache hits.
368    pub precompile_cache_hits: metrics::Counter,
369
370    /// Precompile cache misses.
371    pub precompile_cache_misses: metrics::Counter,
372
373    /// Precompile cache size. Uses the LRU cache length as the size metric.
374    pub precompile_cache_size: metrics::Gauge,
375
376    /// Precompile execution errors.
377    pub precompile_errors: metrics::Counter,
378}
379
380#[cfg(feature = "metrics")]
381impl CachedPrecompileMetrics {
382    /// Registers cache metrics labelled by the precompile address.
383    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            // Move the stateful implementation onto a formerly cacheable address.
632            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}