Skip to main content

foundry_evm_traces/identifier/
signatures.rs

1use alloy_json_abi::{Error, Event, Function, JsonAbi};
2use alloy_primitives::{
3    B256, Selector,
4    map::{HashMap, HashSet},
5};
6use eyre::Result;
7use foundry_common::{
8    abi::{get_error, get_event, get_func},
9    fs,
10    selectors::{OpenChainClient, SelectorKind},
11};
12use foundry_config::Config;
13use serde::{Deserialize, Serialize};
14use std::{
15    collections::BTreeMap,
16    path::{Path, PathBuf},
17    sync::Arc,
18};
19use tokio::sync::RwLock;
20
21/// Cache for function, event and error signatures. Used by [`SignaturesIdentifier`].
22#[derive(Debug, Default, Deserialize)]
23#[serde(try_from = "SignaturesDiskCache")]
24pub struct SignaturesCache {
25    signatures: HashMap<SelectorKind, Option<String>>,
26}
27
28/// Disk representation of the signatures cache.
29///
30/// `S` is the signature string type: owned when the cache is loaded, borrowed when it is saved.
31#[derive(Serialize, Deserialize)]
32struct SignaturesDiskCache<S = String> {
33    functions: BTreeMap<Selector, S>,
34    errors: BTreeMap<Selector, S>,
35    events: BTreeMap<B256, S>,
36}
37
38impl From<SignaturesDiskCache> for SignaturesCache {
39    fn from(value: SignaturesDiskCache) -> Self {
40        let functions = value
41            .functions
42            .into_iter()
43            .map(|(selector, signature)| (SelectorKind::Function(selector), signature));
44        let errors = value
45            .errors
46            .into_iter()
47            .map(|(selector, signature)| (SelectorKind::Error(selector), signature));
48        let events = value
49            .events
50            .into_iter()
51            .map(|(selector, signature)| (SelectorKind::Event(selector), signature));
52        Self {
53            signatures: functions
54                .chain(errors)
55                .chain(events)
56                .map(|(sel, sig)| (sel, (!sig.is_empty()).then_some(sig)))
57                .collect(),
58        }
59    }
60}
61
62impl<'a, S: From<&'a str>> From<&'a SignaturesCache> for SignaturesDiskCache<S> {
63    fn from(value: &'a SignaturesCache) -> Self {
64        let (functions, errors, events) = value.signatures.iter().fold(
65            (BTreeMap::new(), BTreeMap::new(), BTreeMap::new()),
66            |mut acc, (kind, signature)| {
67                // Only persist resolved signatures. Unknown selectors (None) are kept
68                // in-memory for session dedup but not written to disk, so they can be
69                // re-queried in future sessions once the signature database is updated.
70                if let Some(value) = signature.as_deref().map(S::from) {
71                    match *kind {
72                        SelectorKind::Function(selector) => _ = acc.0.insert(selector, value),
73                        SelectorKind::Error(selector) => _ = acc.1.insert(selector, value),
74                        SelectorKind::Event(selector) => _ = acc.2.insert(selector, value),
75                    }
76                }
77                acc
78            },
79        );
80        Self { functions, errors, events }
81    }
82}
83
84impl Serialize for SignaturesCache {
85    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
86    where
87        S: serde::Serializer,
88    {
89        SignaturesDiskCache::<&str>::from(self).serialize(serializer)
90    }
91}
92
93impl SignaturesCache {
94    /// Loads the cache from a file.
95    #[instrument(target = "evm::traces", name = "SignaturesCache::load")]
96    pub fn load(path: &Path) -> Self {
97        trace!(target: "evm::traces", ?path, "reading signature cache");
98        fs::read_json_file(path)
99            .inspect_err(
100                |err| warn!(target: "evm::traces", ?path, ?err, "failed to read cache file"),
101            )
102            .unwrap_or_default()
103    }
104
105    /// Saves the cache to a file.
106    #[instrument(target = "evm::traces", name = "SignaturesCache::save", skip(self))]
107    pub fn save(&self, path: &Path) {
108        if let Some(parent) = path.parent()
109            && let Err(err) = std::fs::create_dir_all(parent)
110        {
111            warn!(target: "evm::traces", ?parent, %err, "failed to create cache");
112        }
113        if let Err(err) = fs::write_json_file(path, self) {
114            warn!(target: "evm::traces", %err, "failed to flush signature cache");
115        } else {
116            trace!(target: "evm::traces", "flushed signature cache")
117        }
118    }
119
120    /// Updates the cache from an ABI.
121    pub fn extend_from_abi(&mut self, abi: &JsonAbi) {
122        self.extend(Self::signatures_from_abi(abi));
123    }
124
125    /// Updates the cache from ABIs without overwriting previous entries from the same batch.
126    fn extend_from_abis_without_collisions<'a>(
127        &mut self,
128        abis: impl IntoIterator<Item = &'a JsonAbi>,
129    ) {
130        let mut seeded: HashSet<SelectorKind> = HashSet::default();
131        for abi in abis {
132            for (selector, signature) in Self::signatures_from_abi(abi) {
133                if seeded.insert(selector) {
134                    self.insert(selector, signature);
135                } else {
136                    trace!(target: "evm::traces", ?selector, %signature, "skipping duplicate ABI signature");
137                }
138            }
139        }
140    }
141
142    fn signatures_from_abi(abi: &JsonAbi) -> impl Iterator<Item = (SelectorKind, String)> + '_ {
143        abi.items().filter_map(|item| match item {
144            alloy_json_abi::AbiItem::Function(f) => {
145                Some((SelectorKind::Function(f.selector()), f.signature()))
146            }
147            alloy_json_abi::AbiItem::Error(e) => {
148                Some((SelectorKind::Error(e.selector()), e.signature()))
149            }
150            alloy_json_abi::AbiItem::Event(e) => {
151                Some((SelectorKind::Event(e.selector()), event_cache_signature(&e)))
152            }
153            _ => None,
154        })
155    }
156
157    /// Inserts a single signature into the cache.
158    pub fn insert(&mut self, key: SelectorKind, value: String) {
159        self.extend(std::iter::once((key, value)));
160    }
161
162    /// Extends the cache with multiple signatures.
163    pub fn extend(&mut self, signatures: impl IntoIterator<Item = (SelectorKind, String)>) {
164        self.signatures
165            .extend(signatures.into_iter().map(|(k, v)| (k, (!v.is_empty()).then_some(v))));
166    }
167
168    /// Gets a signature from the cache.
169    pub fn get(&self, key: &SelectorKind) -> Option<Option<String>> {
170        self.signatures.get(key).cloned()
171    }
172
173    /// Returns true if the cache contains a signature.
174    pub fn contains_key(&self, key: &SelectorKind) -> bool {
175        self.signatures.contains_key(key)
176    }
177}
178
179/// Returns the event signature stored in the cache: like [`Event::full_signature`], with indexed
180/// flags and parameter names, but with struct parameters written as plain tuples, because
181/// [`Event::parse`] rejects named tuple components.
182fn event_cache_signature(event: &Event) -> String {
183    let mut sig = format!("event {}(", event.name);
184    for (i, input) in event.inputs.iter().enumerate() {
185        if i > 0 {
186            sig.push_str(", ");
187        }
188        input.selector_type_raw(&mut sig);
189        if input.indexed {
190            sig.push_str(" indexed");
191        }
192        if !input.name.is_empty() {
193            sig.push(' ');
194            sig.push_str(&input.name);
195        }
196    }
197    sig.push(')');
198    if event.anonymous {
199        sig.push_str(" anonymous");
200    }
201    sig
202}
203
204/// An identifier that tries to identify functions and events using signatures found at
205/// `https://openchain.xyz` or a local cache.
206#[derive(Clone, Debug)]
207pub struct SignaturesIdentifier(Arc<SignaturesIdentifierInner>);
208
209#[derive(Debug)]
210struct SignaturesIdentifierInner {
211    /// Cached selectors for functions, events and custom errors.
212    cache: RwLock<SignaturesCache>,
213    /// ABI events keyed by topic0 and indexed topic count.
214    local_events: HashMap<(B256, usize), Vec<Event>>,
215    /// Location where to save the signature cache.
216    cache_path: Option<PathBuf>,
217    /// The OpenChain client to fetch signatures from. `None` if disabled on construction.
218    client: Option<OpenChainClient>,
219}
220
221impl SignaturesIdentifier {
222    /// Creates a new `SignaturesIdentifier` with the default cache directory.
223    pub fn new(offline: bool) -> Result<Self> {
224        Self::new_with(Config::foundry_cache_dir().as_deref(), offline)
225    }
226
227    /// Creates a new `SignaturesIdentifier` from the global configuration.
228    pub fn from_config(config: &Config) -> Result<Self> {
229        Self::new(config.offline || config.tracing.external_identification_timeout == 0)
230    }
231
232    /// Creates an offline `SignaturesIdentifier` with the default cache directory and local ABIs.
233    pub fn new_offline_with_abis<'a>(abis: impl IntoIterator<Item = &'a JsonAbi>) -> Result<Self> {
234        Ok(Self::new_offline_with_abis_from_cache(Config::foundry_cache_dir().as_deref(), abis))
235    }
236
237    /// Creates a new `SignaturesIdentifier`.
238    ///
239    /// - `cache_dir` is the cache directory to store the signatures.
240    /// - `offline` disables the OpenChain client.
241    pub fn new_with(cache_dir: Option<&Path>, offline: bool) -> Result<Self> {
242        let client = if offline { None } else { Some(OpenChainClient::new()?) };
243        Ok(Self::from_cache(Self::load_cache(cache_dir), client))
244    }
245
246    fn new_offline_with_abis_from_cache<'a>(
247        cache_dir: Option<&Path>,
248        abis: impl IntoIterator<Item = &'a JsonAbi>,
249    ) -> Self {
250        let abis = abis.into_iter().collect::<Vec<_>>();
251        let (mut cache, cache_path) = Self::load_cache(cache_dir);
252        cache.extend_from_abis_without_collisions(abis.iter().copied());
253        let local_events = Self::local_events_from_abis(abis);
254        Self::from_cache_and_events((cache, cache_path), None, local_events)
255    }
256
257    fn load_cache(cache_dir: Option<&Path>) -> (SignaturesCache, Option<PathBuf>) {
258        if let Some(cache_dir) = cache_dir {
259            let path = cache_dir.join("signatures");
260            let cache = SignaturesCache::load(&path);
261            (cache, Some(path))
262        } else {
263            Default::default()
264        }
265    }
266
267    fn from_cache(
268        (cache, cache_path): (SignaturesCache, Option<PathBuf>),
269        client: Option<OpenChainClient>,
270    ) -> Self {
271        Self::from_cache_and_events((cache, cache_path), client, Default::default())
272    }
273
274    fn from_cache_and_events(
275        (cache, cache_path): (SignaturesCache, Option<PathBuf>),
276        client: Option<OpenChainClient>,
277        local_events: HashMap<(B256, usize), Vec<Event>>,
278    ) -> Self {
279        Self(Arc::new(SignaturesIdentifierInner {
280            cache: RwLock::new(cache),
281            local_events,
282            cache_path,
283            client,
284        }))
285    }
286
287    fn local_events_from_abis<'a>(
288        abis: impl IntoIterator<Item = &'a JsonAbi>,
289    ) -> HashMap<(B256, usize), Vec<Event>> {
290        let mut local_events: HashMap<(B256, usize), Vec<Event>> = HashMap::default();
291        for abi in abis {
292            for event in abi.events() {
293                local_events
294                    .entry((
295                        event.selector(),
296                        event.inputs.iter().filter(|input| input.indexed).count(),
297                    ))
298                    .or_default()
299                    .push(event.clone());
300            }
301        }
302        local_events
303    }
304
305    /// Saves the cache to the file system.
306    pub fn save(&self) {
307        self.0.save();
308    }
309
310    /// Identifies `Function`s.
311    pub async fn identify_functions(
312        &self,
313        identifiers: impl IntoIterator<Item = Selector>,
314    ) -> Vec<Option<Function>> {
315        self.identify_map(identifiers.into_iter().map(SelectorKind::Function), get_func).await
316    }
317
318    /// Identifies a `Function`.
319    pub async fn identify_function(&self, identifier: Selector) -> Option<Function> {
320        self.identify_functions([identifier]).await.pop().unwrap()
321    }
322
323    /// Identifies `Event`s.
324    pub async fn identify_events(
325        &self,
326        identifiers: impl IntoIterator<Item = B256>,
327    ) -> Vec<Option<Event>> {
328        self.identify_map(identifiers.into_iter().map(SelectorKind::Event), get_event).await
329    }
330
331    /// Identifies an `Event`.
332    pub async fn identify_event(&self, identifier: B256) -> Option<Event> {
333        self.identify_events([identifier]).await.pop().unwrap()
334    }
335
336    /// Identifies an `Event`, preferring local ABI events with the matching indexed topic count.
337    pub async fn identify_event_with_indexed_count(
338        &self,
339        identifier: B256,
340        indexed_count: usize,
341    ) -> Option<Event> {
342        if let Some(events) = self.0.local_events.get(&(identifier, indexed_count))
343            && let Some(event) = events.first()
344        {
345            return Some(event.clone());
346        }
347        self.identify_event(identifier).await
348    }
349
350    /// Identifies `Error`s.
351    pub async fn identify_errors(
352        &self,
353        identifiers: impl IntoIterator<Item = Selector>,
354    ) -> Vec<Option<Error>> {
355        self.identify_map(identifiers.into_iter().map(SelectorKind::Error), get_error).await
356    }
357
358    /// Identifies an `Error`.
359    pub async fn identify_error(&self, identifier: Selector) -> Option<Error> {
360        self.identify_errors([identifier]).await.pop().unwrap()
361    }
362
363    /// Identifies a list of selectors.
364    pub async fn identify(&self, selectors: &[SelectorKind]) -> Vec<Option<String>> {
365        if selectors.is_empty() {
366            return vec![];
367        }
368        trace!(target: "evm::traces", ?selectors, "identifying selectors");
369
370        let mut cache_r = self.0.cache.read().await;
371        if let Some(client) = &self.0.client
372            && selectors.iter().any(|selector| !cache_r.contains_key(selector))
373        {
374            drop(cache_r);
375            let mut cache_w = self.0.cache.write().await;
376            let query = selectors
377                .iter()
378                .copied()
379                .filter(|selector| !cache_w.contains_key(selector))
380                .collect::<Vec<_>>();
381            if !query.is_empty()
382                && let Ok(res) = client.decode_selectors(&query).await
383            {
384                for (selector, signatures) in std::iter::zip(query, res) {
385                    cache_w.signatures.insert(selector, signatures.into_iter().next());
386                }
387            }
388            drop(cache_w);
389            cache_r = self.0.cache.read().await;
390        }
391        selectors.iter().map(|selector| cache_r.get(selector).unwrap_or_default()).collect()
392    }
393
394    async fn identify_map<T>(
395        &self,
396        selectors: impl IntoIterator<Item = SelectorKind>,
397        get_type: impl Fn(&str) -> Result<T>,
398    ) -> Vec<Option<T>> {
399        let results = self.identify(&Vec::from_iter(selectors)).await;
400        results.into_iter().map(|r| r.and_then(|r| get_type(&r).ok())).collect()
401    }
402}
403
404impl SignaturesIdentifierInner {
405    fn save(&self) {
406        // We only identify new signatures if the client is enabled.
407        if let Some(path) = &self.cache_path
408            && self.client.is_some()
409        {
410            self.cache
411                .try_read()
412                .expect("SignaturesIdentifier cache is locked while attempting to save")
413                .save(path);
414        }
415    }
416}
417
418impl Drop for SignaturesIdentifierInner {
419    fn drop(&mut self) {
420        self.save();
421    }
422}
423
424#[cfg(test)]
425mod tests {
426    use super::*;
427
428    #[test]
429    fn zero_external_identification_timeout_disables_client() {
430        let mut config = Config::default();
431        config.tracing.external_identification_timeout = 0;
432
433        let identifier = SignaturesIdentifier::from_config(&config).unwrap();
434
435        assert!(identifier.0.client.is_none());
436    }
437
438    #[test]
439    fn unknown_signatures_not_persisted_to_disk() {
440        let known_selector = SelectorKind::Function(Selector::from([0xaa, 0xbb, 0xcc, 0xdd]));
441        let unknown_selector = SelectorKind::Error(Selector::from([0x11, 0x22, 0x33, 0x44]));
442
443        let mut cache = SignaturesCache::default();
444        cache.signatures.insert(known_selector, Some("transfer(address,uint256)".into()));
445        cache.signatures.insert(unknown_selector, None);
446
447        // Verify both are in memory.
448        assert!(cache.contains_key(&known_selector));
449        assert!(cache.contains_key(&unknown_selector));
450
451        // Round-trip through the disk format.
452        let disk: SignaturesDiskCache = (&cache).into();
453        let reloaded = SignaturesCache::from(disk);
454
455        // Known signature survives the round-trip.
456        assert_eq!(reloaded.get(&known_selector), Some(Some("transfer(address,uint256)".into())));
457        // Unknown signature is gone — it will be re-queried next session.
458        assert_eq!(reloaded.get(&unknown_selector), None);
459        assert!(!reloaded.contains_key(&unknown_selector));
460    }
461
462    #[tokio::test]
463    async fn abi_seeded_signatures_are_not_persisted_to_disk() {
464        let temp = tempfile::tempdir().unwrap();
465        let event = Event::parse("event CodexEphemeral(uint256 indexed value)").unwrap();
466        let mut abi = JsonAbi::new();
467        abi.events.insert(event.name.clone(), vec![event.clone()]);
468
469        {
470            let identifier =
471                SignaturesIdentifier::new_offline_with_abis_from_cache(Some(temp.path()), [&abi]);
472            let decoded = identifier.identify_event(event.selector()).await;
473            assert_eq!(decoded.as_ref().map(Event::full_signature), Some(event.full_signature()));
474            identifier.save();
475        }
476
477        let reloaded = SignaturesCache::load(&temp.path().join("signatures"));
478        assert!(!reloaded.contains_key(&SelectorKind::Event(event.selector())));
479    }
480
481    #[test]
482    fn abi_seeded_collisions_keep_first_signature() {
483        let first = Event::parse("event CodexCollision(uint256 indexed value)").unwrap();
484        let second = Event::parse("event CodexCollision(uint256 value)").unwrap();
485
486        let mut first_abi = JsonAbi::new();
487        first_abi.events.insert(first.name.clone(), vec![first.clone()]);
488        let mut second_abi = JsonAbi::new();
489        second_abi.events.insert(second.name.clone(), vec![second]);
490
491        let mut cache = SignaturesCache::default();
492        cache.extend_from_abis_without_collisions([&first_abi, &second_abi]);
493
494        assert_eq!(
495            cache.get(&SelectorKind::Event(first.selector())),
496            Some(Some(first.full_signature()))
497        );
498    }
499
500    #[tokio::test]
501    async fn abi_seeded_events_prefer_matching_indexed_count() {
502        let one_topic =
503            Event::parse("event CodexIndexedCount(uint256 indexed marker, uint256 value)").unwrap();
504        let two_topics =
505            Event::parse("event CodexIndexedCount(uint256 indexed marker, uint256 indexed value)")
506                .unwrap();
507
508        let mut one_topic_abi = JsonAbi::new();
509        one_topic_abi.events.insert(one_topic.name.clone(), vec![one_topic.clone()]);
510        let mut two_topics_abi = JsonAbi::new();
511        two_topics_abi.events.insert(two_topics.name.clone(), vec![two_topics.clone()]);
512
513        let identifier = SignaturesIdentifier::new_offline_with_abis_from_cache(
514            None,
515            [&two_topics_abi, &one_topic_abi],
516        );
517
518        let decoded_one_topic =
519            identifier.identify_event_with_indexed_count(one_topic.selector(), 1).await.unwrap();
520        let decoded_two_topics =
521            identifier.identify_event_with_indexed_count(two_topics.selector(), 2).await.unwrap();
522
523        assert_eq!(decoded_one_topic.full_signature(), one_topic.full_signature());
524        assert_eq!(decoded_two_topics.full_signature(), two_topics.full_signature());
525    }
526
527    #[tokio::test]
528    async fn abi_seeded_events_with_struct_params_are_identified() {
529        let event: Event = serde_json::from_str(
530            r#"{"type":"event","name":"Placed","anonymous":false,"inputs":[
531                {"name":"by","type":"address","indexed":true},
532                {"name":"order","type":"tuple","indexed":false,"components":[
533                    {"name":"who","type":"address"},{"name":"amount","type":"uint256"}]},
534                {"name":"orders","type":"tuple[]","indexed":false,"components":[
535                    {"name":"who","type":"address"},{"name":"amount","type":"uint256"}]}]}"#,
536        )
537        .unwrap();
538        let mut abi = JsonAbi::new();
539        abi.events.insert(event.name.clone(), vec![event.clone()]);
540
541        let mut cache = SignaturesCache::default();
542        cache.extend_from_abi(&abi);
543        assert_eq!(
544            cache.get(&SelectorKind::Event(event.selector())),
545            Some(Some(
546                "event Placed(address indexed by, (address,uint256) order, (address,uint256)[] orders)"
547                    .into()
548            ))
549        );
550
551        let identifier = SignaturesIdentifier::from_cache((cache, None), None);
552        let decoded = identifier.identify_event(event.selector()).await.unwrap();
553        assert_eq!(decoded.selector(), event.selector());
554        assert_eq!(decoded.inputs.iter().filter(|i| i.indexed).count(), 1);
555    }
556}