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#[derive(Debug, Default, Deserialize)]
23#[serde(try_from = "SignaturesDiskCache")]
24pub struct SignaturesCache {
25 signatures: HashMap<SelectorKind, Option<String>>,
26}
27
28#[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 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 #[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 #[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 pub fn extend_from_abi(&mut self, abi: &JsonAbi) {
122 self.extend(Self::signatures_from_abi(abi));
123 }
124
125 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 pub fn insert(&mut self, key: SelectorKind, value: String) {
159 self.extend(std::iter::once((key, value)));
160 }
161
162 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 pub fn get(&self, key: &SelectorKind) -> Option<Option<String>> {
170 self.signatures.get(key).cloned()
171 }
172
173 pub fn contains_key(&self, key: &SelectorKind) -> bool {
175 self.signatures.contains_key(key)
176 }
177}
178
179fn 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#[derive(Clone, Debug)]
207pub struct SignaturesIdentifier(Arc<SignaturesIdentifierInner>);
208
209#[derive(Debug)]
210struct SignaturesIdentifierInner {
211 cache: RwLock<SignaturesCache>,
213 local_events: HashMap<(B256, usize), Vec<Event>>,
215 cache_path: Option<PathBuf>,
217 client: Option<OpenChainClient>,
219}
220
221impl SignaturesIdentifier {
222 pub fn new(offline: bool) -> Result<Self> {
224 Self::new_with(Config::foundry_cache_dir().as_deref(), offline)
225 }
226
227 pub fn from_config(config: &Config) -> Result<Self> {
229 Self::new(config.offline || config.tracing.external_identification_timeout == 0)
230 }
231
232 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 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 pub fn save(&self) {
307 self.0.save();
308 }
309
310 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 pub async fn identify_function(&self, identifier: Selector) -> Option<Function> {
320 self.identify_functions([identifier]).await.pop().unwrap()
321 }
322
323 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 pub async fn identify_event(&self, identifier: B256) -> Option<Event> {
333 self.identify_events([identifier]).await.pop().unwrap()
334 }
335
336 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 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 pub async fn identify_error(&self, identifier: Selector) -> Option<Error> {
360 self.identify_errors([identifier]).await.pop().unwrap()
361 }
362
363 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 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 assert!(cache.contains_key(&known_selector));
449 assert!(cache.contains_key(&unknown_selector));
450
451 let disk: SignaturesDiskCache = (&cache).into();
453 let reloaded = SignaturesCache::from(disk);
454
455 assert_eq!(reloaded.get(&known_selector), Some(Some("transfer(address,uint256)".into())));
457 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}