Skip to main content

foundry_evm_traces/identifier/
external.rs

1use super::{IdentifiedAddress, TraceIdentifier};
2use crate::{CallTraceNode, debug::ContractSources};
3use alloy_json_abi::JsonAbi;
4use alloy_primitives::{
5    Address,
6    map::{AddressMap, AddressSet, Entry, HashMap, HashSet},
7};
8use eyre::WrapErr;
9use foundry_block_explorers::{contract::Metadata, errors::EtherscanError};
10use foundry_common::compile::etherscan_project;
11use foundry_config::{Chain, Config, EtherscanConfigs, NamedChain, ResolvedEtherscanConfig};
12use foundry_evm_core::constants::{CHEATCODE_ADDRESS, HARDHAT_CONSOLE_ADDRESS};
13use futures::{
14    future::{Either, join_all, select},
15    stream::{FuturesUnordered, Stream, StreamExt},
16    task::{Context, Poll},
17};
18use serde::Deserialize;
19use std::{
20    borrow::Cow,
21    pin::{Pin, pin},
22    sync::{
23        Arc,
24        atomic::{AtomicBool, Ordering},
25    },
26    time::{Duration, Instant},
27};
28
29/// A trace identifier that tries to identify addresses using Etherscan.
30pub struct ExternalIdentifier {
31    fetchers: Vec<Arc<dyn ExternalFetcherT>>,
32    /// Cached contracts.
33    contracts: HashMap<Address, (FetcherKind, Option<Metadata>)>,
34    /// Remaining time external identification may block trace rendering.
35    remaining_budget: Duration,
36    clock: Arc<dyn Clock>,
37}
38
39/// The [`Config`] settings an [`ExternalIdentifier`] is built from, detached from the config
40/// itself.
41///
42/// Lets a consumer that keeps only a snapshot of the config — the cheatcode config — build an
43/// identifier for a chain it doesn't learn until runtime, when a test selects a fork.
44#[derive(Clone, Debug, Default)]
45pub struct ExternalIdentifierConfig {
46    /// Whether network access is disabled altogether.
47    offline: bool,
48    /// How long identification may block, in seconds. Zero disables it.
49    timeout: u64,
50    /// Whether to skip system proxy lookups when building the explorer client.
51    no_proxy: bool,
52    /// The `[etherscan]` table, and the settings that pick an entry out of it.
53    etherscan: EtherscanConfigs,
54    etherscan_alias: Option<String>,
55    etherscan_api_key: Option<String>,
56    /// The configured chain, used when the caller doesn't name one.
57    chain: Option<Chain>,
58}
59
60impl ExternalIdentifierConfig {
61    /// Takes the settings an [`ExternalIdentifier`] needs out of `config`.
62    pub fn new(config: &Config) -> Self {
63        Self {
64            offline: config.offline,
65            timeout: config.tracing.external_identification_timeout,
66            no_proxy: config.eth_rpc_no_proxy,
67            etherscan: config.etherscan.clone(),
68            etherscan_alias: config.etherscan_alias().map(str::to_string),
69            etherscan_api_key: config.etherscan_api_key.clone(),
70            chain: config.chain,
71        }
72    }
73
74    /// Builds an identifier that looks contracts up on `chain`.
75    ///
76    /// Returns `None` when there is nothing to look them up with: identification is off, or
77    /// neither Sourcify nor a block explorer is usable.
78    pub fn identifier(&self, chain: Option<Chain>) -> Option<ExternalIdentifier> {
79        self.identifier_with(
80            chain,
81            self.etherscan_alias.as_deref(),
82            self.etherscan_api_key.as_deref(),
83            true,
84        )
85    }
86
87    /// Builds an identifier for compiling storage layouts on exactly `chain`.
88    ///
89    /// Storage layouts are cached by chain, so an alias for another chain must not override the
90    /// chain that executed the recorded storage access. Sourcify is omitted because its compact
91    /// response does not contain the verified sources required for compilation.
92    pub fn storage_identifier(&self, chain: Chain) -> Option<ExternalIdentifier> {
93        self.identifier_with(Some(chain), None, self.literal_api_key(), false)
94    }
95
96    fn identifier_with(
97        &self,
98        chain: Option<Chain>,
99        etherscan_alias: Option<&str>,
100        etherscan_api_key: Option<&str>,
101        sourcify: bool,
102    ) -> Option<ExternalIdentifier> {
103        if self.offline || self.timeout == 0 {
104            return None;
105        }
106
107        let (chain, etherscan) = self.resolve_explorer(chain, etherscan_alias, etherscan_api_key);
108
109        let mut fetchers = Vec::<Arc<dyn ExternalFetcherT>>::new();
110        // Sourcify never indexes local development chains.
111        if sourcify
112            && let Some(chain) = chain
113            && !matches!(chain.named(), Some(NamedChain::AnvilHardhat | NamedChain::Dev))
114        {
115            debug!(target: "evm::traces::external", ?chain, "using sourcify identifier");
116            fetchers.push(Arc::new(SourcifyFetcher::new(chain)));
117        }
118        if let Some(config) = etherscan {
119            debug!(target: "evm::traces::external", chain=?config.chain, url=?config.api_url, "using etherscan identifier");
120            match config.into_client_with_no_proxy(self.no_proxy) {
121                Ok(client) => {
122                    fetchers.push(Arc::new(EtherscanFetcher::new(client)));
123                }
124                Err(err) => {
125                    warn!(target: "evm::traces::external", ?err, "failed to create etherscan client");
126                }
127            }
128        }
129        if fetchers.is_empty() {
130            debug!(target: "evm::traces::external", "no fetchers enabled");
131            return None;
132        }
133
134        Some(ExternalIdentifier {
135            fetchers,
136            contracts: Default::default(),
137            remaining_budget: Duration::from_secs(self.timeout),
138            clock: Arc::new(TokioClock),
139        })
140    }
141
142    /// Picks the explorer config and the chain to look contracts up on.
143    fn resolve_explorer(
144        &self,
145        chain: Option<Chain>,
146        etherscan_alias: Option<&str>,
147        etherscan_api_key: Option<&str>,
148    ) -> (Option<Chain>, Option<ResolvedEtherscanConfig>) {
149        let mut resolved =
150            self.etherscan.resolve_for(etherscan_alias, etherscan_api_key, chain.or(self.chain));
151        // Only an alias can resolve to a chain other than the requested one. An alias pinned to
152        // another chain must not redirect lookups away from the traced chain.
153        if let Some(chain) = chain
154            && let Ok(Some(config)) = &resolved
155            && config.chain.is_some_and(|c| c != chain)
156        {
157            resolved = self.etherscan.resolve_for(None, self.literal_api_key(), Some(chain));
158        }
159        match resolved {
160            Ok(Some(config)) => (chain.or(config.chain), Some(config)),
161            Ok(None) => {
162                warn!(target: "evm::traces::external", "etherscan config not found");
163                (chain, None)
164            }
165            Err(err) => {
166                warn!(target: "evm::traces::external", ?err, "failed to get etherscan config");
167                (chain, None)
168            }
169        }
170    }
171
172    /// Maximum time a storage-layout lookup may block.
173    pub const fn storage_timeout(&self) -> Duration {
174        Duration::from_secs(self.timeout)
175    }
176
177    /// Returns `etherscan_api_key` unless it names an `[etherscan]` entry.
178    ///
179    /// `etherscan_api_key` also accepts a table alias. An alias name must not be sent as the
180    /// literal API key when the alias itself is not used.
181    fn literal_api_key(&self) -> Option<&str> {
182        self.etherscan_api_key.as_deref().filter(|key| !self.etherscan.contains_key(*key))
183    }
184}
185
186impl ExternalIdentifier {
187    /// Creates a new external identifier with the given client.
188    pub fn new(config: &Config, chain: Option<Chain>) -> eyre::Result<Option<Self>> {
189        Ok(ExternalIdentifierConfig::new(config).identifier(chain))
190    }
191
192    /// Goes over the list of contracts we have pulled from the traces, clones their source from
193    /// Etherscan and compiles them locally, for usage in the debugger.
194    pub async fn get_compiled_contracts(&self) -> eyre::Result<ContractSources> {
195        // Collect contract info upfront so we can reference it in error messages
196        let contracts_info: Vec<_> = self
197            .contracts
198            .iter()
199            // filter out vyper files and contracts without metadata
200            .filter_map(|(addr, (_, metadata))| {
201                if let Some(metadata) = metadata.as_ref()
202                    && !metadata.is_vyper()
203                {
204                    Some((*addr, metadata))
205                } else {
206                    None
207                }
208            })
209            .collect();
210
211        let outputs_fut = contracts_info
212            .iter()
213            .map(|(addr, metadata)| async move {
214                sh_println!("Compiling: {} {addr}", metadata.contract_name)?;
215                let root = tempfile::tempdir()?;
216                let root_path = root.path();
217                let project = etherscan_project(metadata, root_path)?;
218                let output = project.compile()?;
219                if output.has_compiler_errors() {
220                    eyre::bail!("{output}");
221                }
222
223                Ok((project, output, root))
224            })
225            .collect::<Vec<_>>();
226
227        // poll all the futures concurrently
228        let outputs = join_all(outputs_fut).await;
229
230        let mut sources: ContractSources = Default::default();
231
232        // construct the map
233        for (idx, res) in outputs.into_iter().enumerate() {
234            let (addr, metadata) = &contracts_info[idx];
235            let name = &metadata.contract_name;
236            let (project, output, _) =
237                res.wrap_err_with(|| format!("Failed to compile contract {name} at {addr}"))?;
238            sources
239                .insert(&output, project.root(), None)
240                .wrap_err_with(|| format!("Failed to insert contract {name} at {addr}"))?;
241        }
242
243        Ok(sources)
244    }
245
246    fn identify_from_metadata(
247        &self,
248        address: Address,
249        metadata: &Metadata,
250    ) -> IdentifiedAddress<'static> {
251        let label = metadata.contract_name.clone();
252        let abi = metadata.abi().ok().map(Cow::Owned);
253        IdentifiedAddress {
254            address,
255            label: Some(label.clone()),
256            contract: Some(label),
257            abi,
258            constructor_args_offset: None,
259            artifact_id: None,
260        }
261    }
262
263    fn cache_fetched(&mut self, address: Address, value: (FetcherKind, Option<Metadata>)) {
264        match self.contracts.entry(address) {
265            Entry::Occupied(mut occupied_entry) => {
266                let old = occupied_entry.get();
267                // Only override when the new result is strictly better:
268                // - new has metadata and old doesn't, OR
269                // - both have metadata but new is from Etherscan and old is not.
270                // Never downgrade a successful lookup to None.
271                let should_replace = match (&old.1, &value.1) {
272                    (None, Some(_)) => true,
273                    (Some(_), None) => false,
274                    _ => {
275                        matches!(value.0, FetcherKind::Etherscan)
276                            && !matches!(old.0, FetcherKind::Etherscan)
277                    }
278                };
279                if should_replace {
280                    occupied_entry.insert(value);
281                }
282            }
283            Entry::Vacant(vacant_entry) => {
284                vacant_entry.insert(value);
285            }
286        }
287    }
288
289    async fn fetch_addresses_async(&mut self, addresses: &[Address]) {
290        self.fetch_addresses_with_timeout(addresses, self.remaining_budget).await;
291    }
292
293    async fn fetch_addresses_with_timeout(&mut self, addresses: &[Address], timeout: Duration) {
294        let timeout = timeout.min(self.remaining_budget);
295        if addresses.is_empty() || timeout.is_zero() {
296            return;
297        }
298
299        let clock = Arc::clone(&self.clock);
300        let fetchers = self
301            .fetchers
302            .clone()
303            .into_iter()
304            .map(|fetcher| ExternalFetcher::new(fetcher, addresses, Arc::clone(&clock)));
305        let started = clock.now();
306        let deadline = clock.sleep(timeout);
307        let timed_out = {
308            let fetch = pin!(async {
309                let mut fetched = futures::stream::select_all(fetchers);
310                while let Some((address, value)) = fetched.next().await {
311                    self.cache_fetched(address, value);
312                }
313            });
314            matches!(select(fetch, deadline).await, Either::Right(_))
315        };
316        self.remaining_budget = self.remaining_budget.saturating_sub(clock.now() - started);
317        if timed_out && self.remaining_budget.is_zero() {
318            warn!(target: "evm::traces::external", "external identification timed out; disabling it for the remainder of this session");
319        }
320    }
321
322    /// Fetches all verified ABIs and whether each proxy chain was fully resolved.
323    pub async fn get_abis(
324        &mut self,
325        addresses: &[Address],
326    ) -> Vec<(Address, eyre::Result<(Vec<JsonAbi>, bool)>)> {
327        const MAX_PROXY_DEPTH: usize = 16;
328
329        struct Chain {
330            current: Option<Address>,
331            visited: HashSet<Address>,
332            abis: Vec<JsonAbi>,
333            complete: bool,
334        }
335
336        let mut chains = addresses
337            .iter()
338            .map(|&address| Chain {
339                current: Some(address),
340                visited: HashSet::default(),
341                abis: Vec::new(),
342                complete: true,
343            })
344            .collect::<Vec<_>>();
345
346        for _ in 0..MAX_PROXY_DEPTH {
347            let to_fetch = chains
348                .iter()
349                .filter_map(|chain| chain.current)
350                .filter(|address| !self.contracts.contains_key(address))
351                .collect::<HashSet<_>>()
352                .into_iter()
353                .collect::<Vec<_>>();
354            self.fetch_addresses_async(&to_fetch).await;
355
356            let mut has_next = false;
357            for chain in &mut chains {
358                let Some(current) = chain.current else { continue };
359                if !chain.visited.insert(current) {
360                    chain.current = None;
361                    chain.complete = false;
362                    continue;
363                }
364                let Some((_, Some(metadata))) = self.contracts.get(&current) else {
365                    chain.current = None;
366                    chain.complete = false;
367                    continue;
368                };
369                if let Ok(abi) = metadata.abi() {
370                    chain.abis.push(abi);
371                } else {
372                    chain.complete = false;
373                }
374                chain.current = (metadata.proxy != 0).then_some(metadata.implementation).flatten();
375                if metadata.proxy != 0 && chain.current.is_none() {
376                    chain.complete = false;
377                }
378                has_next |= chain.current.is_some();
379            }
380            if !has_next {
381                break;
382            }
383        }
384
385        chains
386            .into_iter()
387            .zip(addresses.iter().copied())
388            .map(|(mut chain, address)| {
389                chain.complete &= chain.current.is_none();
390                let result = if chain.abis.is_empty() {
391                    Err(eyre::eyre!("external ABI lookup failed"))
392                } else {
393                    Ok((chain.abis.into_iter().rev().collect(), chain.complete))
394                };
395                (address, result)
396            })
397            .collect()
398    }
399
400    /// Fetches metadata for the exact addresses supplied, without following explorer proxy hints.
401    ///
402    /// Storage decoding uses the implementation address recorded by the EVM, which is authoritative
403    /// for historical forks and proxies that upgrade over time.
404    pub async fn get_metadata(
405        &mut self,
406        addresses: &[Address],
407        timeout: Duration,
408    ) -> AddressMap<Option<Metadata>> {
409        let to_fetch = addresses
410            .iter()
411            .copied()
412            .filter(|address| !self.contracts.contains_key(address))
413            .collect::<Vec<_>>();
414        self.fetch_addresses_with_timeout(&to_fetch, timeout).await;
415        addresses
416            .iter()
417            .filter_map(|address| {
418                self.contracts.get(address).map(|(_, metadata)| (*address, metadata.clone()))
419            })
420            .collect()
421    }
422}
423
424impl TraceIdentifier for ExternalIdentifier {
425    fn identify_addresses(&mut self, nodes: &[&CallTraceNode]) -> Vec<IdentifiedAddress<'_>> {
426        if nodes.is_empty() {
427            return Vec::new();
428        }
429
430        trace!(target: "evm::traces::external", "identify {} addresses", nodes.len());
431
432        let mut identities = Vec::new();
433        let mut to_fetch = AddressSet::default();
434
435        // Check cache first.
436        for &node in nodes {
437            let address = node.trace.address;
438            // Foundry-only addresses that are never deployed contracts on a real chain.
439            if matches!(address, CHEATCODE_ADDRESS | HARDHAT_CONSOLE_ADDRESS) {
440                continue;
441            }
442            if let Some((_, metadata)) = self.contracts.get(&address) {
443                if let Some(metadata) = metadata {
444                    identities.push(self.identify_from_metadata(address, metadata));
445                } else {
446                    // Do nothing. We know that this contract was not verified.
447                }
448            } else {
449                to_fetch.insert(address);
450            }
451        }
452
453        if to_fetch.is_empty() {
454            return identities;
455        }
456        if self.remaining_budget.is_zero() {
457            return identities;
458        }
459        trace!(target: "evm::traces::external", "fetching {} addresses", to_fetch.len());
460
461        let to_fetch = to_fetch.into_iter().collect::<Vec<_>>();
462        foundry_common::block_on(self.fetch_addresses_async(&to_fetch));
463
464        for address in to_fetch {
465            if let Some((_, Some(metadata))) = self.contracts.get(&address) {
466                identities.push(self.identify_from_metadata(address, metadata));
467            }
468        }
469        trace!(target: "evm::traces::external", "identified {} addresses", identities.len());
470        identities
471    }
472}
473
474type FetchFuture =
475    Pin<Box<dyn Future<Output = (Address, Result<Option<Metadata>, EtherscanError>)>>>;
476
477/// Maximum number of times a single address is retried after a rate limit or a transient
478/// Cloudflare block before we give up on it. Bounded so a persistent block can't loop forever.
479const MAX_TRANSIENT_RETRIES: u32 = 5;
480
481type Sleep = Pin<Box<dyn Future<Output = ()> + Send>>;
482
483/// The source of time for the identification budget and the rate limit backoff.
484///
485/// Tests replace it to drive time by hand.
486trait Clock: Send + Sync {
487    fn now(&self) -> Instant;
488    fn sleep(&self, duration: Duration) -> Sleep;
489}
490
491/// The [`Clock`] backed by tokio's timers.
492struct TokioClock;
493
494impl Clock for TokioClock {
495    fn now(&self) -> Instant {
496        Instant::now()
497    }
498
499    fn sleep(&self, duration: Duration) -> Sleep {
500        Box::pin(tokio::time::sleep(duration))
501    }
502}
503
504/// A rate limit aware fetcher.
505///
506/// Fetches information about multiple addresses concurrently, while respecting rate limits.
507struct ExternalFetcher {
508    /// The fetcher
509    fetcher: Arc<dyn ExternalFetcherT>,
510    /// The time we wait if we hit the rate limit
511    timeout: Duration,
512    /// The backoff we are currently waiting for before making a new request
513    backoff: Option<Sleep>,
514    clock: Arc<dyn Clock>,
515    /// The maximum amount of requests to send concurrently
516    concurrency: usize,
517    /// The addresses we have yet to make requests for
518    queue: Vec<Address>,
519    /// The in progress requests
520    in_progress: FuturesUnordered<FetchFuture>,
521    /// Per-address retry counter for rate limits and transient Cloudflare blocks.
522    attempts: HashMap<Address, u32>,
523}
524
525impl ExternalFetcher {
526    fn new(
527        fetcher: Arc<dyn ExternalFetcherT>,
528        to_fetch: &[Address],
529        clock: Arc<dyn Clock>,
530    ) -> Self {
531        Self {
532            timeout: fetcher.timeout(),
533            backoff: None,
534            clock,
535            concurrency: fetcher.concurrency(),
536            fetcher,
537            queue: to_fetch.to_vec(),
538            in_progress: FuturesUnordered::new(),
539            attempts: HashMap::default(),
540        }
541    }
542
543    fn queue_next_reqs(&mut self) {
544        while self.in_progress.len() < self.concurrency {
545            let Some(addr) = self.queue.pop() else { break };
546            let fetcher = Arc::clone(&self.fetcher);
547            self.in_progress.push(Box::pin(async move {
548                trace!(target: "evm::traces::external", ?addr, "fetching info");
549                let res = fetcher.fetch(addr).await;
550                (addr, res)
551            }));
552        }
553    }
554
555    /// Requeues `addr` after a backoff, unless it already used all of its retries.
556    ///
557    /// Returns `false` when the address is dropped. A dropped address is not cached, so a
558    /// transient failure does not become an "unverified" result.
559    fn retry(&mut self, addr: Address) -> bool {
560        let attempts = self.attempts.entry(addr).or_default();
561        *attempts += 1;
562        if *attempts > MAX_TRANSIENT_RETRIES {
563            return false;
564        }
565        self.backoff = Some(self.clock.sleep(self.timeout));
566        self.queue.push(addr);
567        true
568    }
569}
570
571impl Stream for ExternalFetcher {
572    type Item = (Address, (FetcherKind, Option<Metadata>));
573
574    fn poll_next(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
575        let pin = self.get_mut();
576
577        let _guard =
578            info_span!("evm::traces::external", kind=?pin.fetcher.kind(), "ExternalFetcher")
579                .entered();
580
581        if pin.fetcher.invalid_api_key().load(Ordering::Relaxed) {
582            return Poll::Ready(None);
583        }
584
585        loop {
586            if let Some(mut backoff) = pin.backoff.take()
587                && backoff.as_mut().poll(cx).is_pending()
588            {
589                pin.backoff = Some(backoff);
590                return Poll::Pending;
591            }
592
593            pin.queue_next_reqs();
594
595            let mut made_progress_this_iter = false;
596            match pin.in_progress.poll_next_unpin(cx) {
597                Poll::Pending => {}
598                Poll::Ready(None) => return Poll::Ready(None),
599                Poll::Ready(Some((addr, res))) => {
600                    made_progress_this_iter = true;
601                    match res {
602                        Ok(metadata) => {
603                            return Poll::Ready(Some((addr, (pin.fetcher.kind(), metadata))));
604                        }
605                        Err(EtherscanError::ContractCodeNotVerified(_)) => {
606                            return Poll::Ready(Some((addr, (pin.fetcher.kind(), None))));
607                        }
608                        Err(EtherscanError::RateLimitExceeded) => {
609                            if pin.retry(addr) {
610                                warn!(target: "evm::traces::external", "rate limit exceeded, backing off");
611                            } else {
612                                warn!(target: "evm::traces::external", "rate limit exceeded, giving up on address");
613                            }
614                        }
615                        Err(EtherscanError::InvalidApiKey) => {
616                            warn!(target: "evm::traces::external", "invalid api key");
617                            // mark key as invalid
618                            pin.fetcher.invalid_api_key().store(true, Ordering::Relaxed);
619                            return Poll::Ready(None);
620                        }
621                        Err(EtherscanError::ChainNotSupported(chain)) => {
622                            warn!(target: "evm::traces::external", %chain, "chain not supported");
623                            // No address on this chain can resolve, so stop using the fetcher.
624                            pin.fetcher.invalid_api_key().store(true, Ordering::Relaxed);
625                            return Poll::Ready(None);
626                        }
627                        Err(EtherscanError::BlockedByCloudflare) => {
628                            // A Cloudflare block is transient rate limiting (often triggered
629                            // by request bursts), not a permanent failure like an invalid key.
630                            // Back off and retry the address a bounded number of times instead
631                            // of aborting the whole stream, which would abandon every still-
632                            // queued address and leave traces only partially decoded (#9880).
633                            if pin.retry(addr) {
634                                warn!(target: "evm::traces::external", "blocked by cloudflare, backing off");
635                            } else {
636                                warn!(target: "evm::traces::external", "blocked by cloudflare, giving up on address");
637                                // No conclusion: do not turn a transient outage into a cached
638                                // "unverified" result.
639                            }
640                        }
641                        Err(err) => {
642                            warn!(target: "evm::traces::external", ?err, "could not get info");
643                            // Only ContractCodeNotVerified is a conclusive negative result.
644                        }
645                    }
646                }
647            }
648
649            if !made_progress_this_iter {
650                return Poll::Pending;
651            }
652        }
653    }
654}
655
656#[derive(Debug, Clone, Copy, PartialEq, Eq)]
657enum FetcherKind {
658    Etherscan,
659    Sourcify,
660}
661
662#[async_trait::async_trait]
663trait ExternalFetcherT: Send + Sync {
664    fn kind(&self) -> FetcherKind;
665    fn timeout(&self) -> Duration;
666    fn concurrency(&self) -> usize;
667    fn invalid_api_key(&self) -> &AtomicBool;
668    async fn fetch(&self, address: Address) -> Result<Option<Metadata>, EtherscanError>;
669}
670
671struct EtherscanFetcher {
672    client: foundry_block_explorers::Client,
673    invalid_api_key: AtomicBool,
674}
675
676impl EtherscanFetcher {
677    const fn new(client: foundry_block_explorers::Client) -> Self {
678        Self { client, invalid_api_key: AtomicBool::new(false) }
679    }
680}
681
682#[async_trait::async_trait]
683impl ExternalFetcherT for EtherscanFetcher {
684    fn kind(&self) -> FetcherKind {
685        FetcherKind::Etherscan
686    }
687
688    fn timeout(&self) -> Duration {
689        Duration::from_secs(1)
690    }
691
692    fn concurrency(&self) -> usize {
693        5
694    }
695
696    fn invalid_api_key(&self) -> &AtomicBool {
697        &self.invalid_api_key
698    }
699
700    async fn fetch(&self, address: Address) -> Result<Option<Metadata>, EtherscanError> {
701        self.client.contract_source_code(address).await.map(|mut metadata| metadata.items.pop())
702    }
703}
704
705struct SourcifyFetcher {
706    client: reqwest::Client,
707    chain: Chain,
708    url: String,
709    invalid_api_key: AtomicBool,
710}
711
712impl SourcifyFetcher {
713    fn new(chain: Chain) -> Self {
714        Self {
715            client: reqwest::Client::builder()
716                .user_agent(foundry_common::DEFAULT_USER_AGENT)
717                .build()
718                .expect("Client::builder() with static config cannot fail"),
719            chain,
720            url: format!("https://sourcify.dev/server/v2/contract/{}", chain.id()),
721            invalid_api_key: AtomicBool::new(false),
722        }
723    }
724}
725
726#[async_trait::async_trait]
727impl ExternalFetcherT for SourcifyFetcher {
728    fn kind(&self) -> FetcherKind {
729        FetcherKind::Sourcify
730    }
731
732    fn timeout(&self) -> Duration {
733        Duration::from_secs(1)
734    }
735
736    fn concurrency(&self) -> usize {
737        5
738    }
739
740    fn invalid_api_key(&self) -> &AtomicBool {
741        &self.invalid_api_key
742    }
743
744    async fn fetch(&self, address: Address) -> Result<Option<Metadata>, EtherscanError> {
745        let url = format!("{url}/{address}?fields=abi,compilation", url = self.url);
746        let response = self
747            .client
748            .get(url)
749            .send()
750            .await
751            .map_err(|e| EtherscanError::Unknown(e.to_string()))?;
752        let code = response.status();
753        match code.as_u16() {
754            // Not verified.
755            404 => return Err(EtherscanError::ContractCodeNotVerified(address)),
756            // Too many requests.
757            429 => return Err(EtherscanError::RateLimitExceeded),
758            // Bad request. Only a recognized error code is final; anything else is not cached.
759            400 => {
760                let error = response
761                    .json::<SourcifyError>()
762                    .await
763                    .map_err(|e| EtherscanError::Unknown(e.to_string()))?;
764                return Err(match error.custom_code.as_str() {
765                    "unsupported_chain" => EtherscanError::ChainNotSupported(self.chain),
766                    "invalid_parameter" => EtherscanError::ContractCodeNotVerified(address),
767                    _ => EtherscanError::Unknown(format!("{error:#?}")),
768                });
769            }
770            _ => {}
771        }
772        let response: SourcifyResponse =
773            response.json().await.map_err(|e| EtherscanError::Unknown(e.to_string()))?;
774        trace!(target: "evm::traces::external", "Sourcify response for {address}: {response:#?}");
775        match response {
776            SourcifyResponse::Success(metadata) => Ok(Some(metadata.into())),
777            SourcifyResponse::Error(error) => Err(EtherscanError::Unknown(format!("{error:#?}"))),
778        }
779    }
780}
781
782/// Sourcify API response for `/v2/contract/{chainId}/{address}`.
783#[derive(Debug, Clone, Deserialize)]
784#[serde(untagged)]
785enum SourcifyResponse {
786    Success(SourcifyMetadata),
787    Error(SourcifyError),
788}
789
790#[derive(Debug, Clone, Deserialize)]
791#[serde(rename_all = "camelCase")]
792#[expect(dead_code)] // Used in Debug.
793struct SourcifyError {
794    custom_code: String,
795    message: String,
796    error_id: String,
797}
798
799#[derive(Debug, Clone, Deserialize)]
800#[serde(rename_all = "camelCase")]
801struct SourcifyMetadata {
802    #[serde(default)]
803    abi: Option<Box<serde_json::value::RawValue>>,
804    #[serde(default)]
805    compilation: Option<Compilation>,
806}
807
808#[derive(Debug, Clone, Deserialize)]
809#[serde(rename_all = "camelCase")]
810struct Compilation {
811    #[serde(default)]
812    compiler_version: String,
813    #[serde(default)]
814    name: String,
815}
816
817impl From<SourcifyMetadata> for Metadata {
818    fn from(metadata: SourcifyMetadata) -> Self {
819        let SourcifyMetadata { abi, compilation } = metadata;
820        let (contract_name, compiler_version) = compilation
821            .map(|c| (c.name, c.compiler_version))
822            .unwrap_or_else(|| (String::new(), String::new()));
823        // Defaulted fields may be fetched from sourcify but we don't make use of them.
824        Self {
825            source_code: foundry_block_explorers::contract::SourceCodeMetadata::Sources(
826                Default::default(),
827            ),
828            abi: Box::<str>::from(abi.unwrap_or_default()).into(),
829            contract_name,
830            compiler_version,
831            optimization_used: 0,
832            runs: 0,
833            constructor_arguments: Default::default(),
834            evm_version: String::new(),
835            library: String::new(),
836            license_type: String::new(),
837            proxy: 0,
838            implementation: None,
839            swarm_source: String::new(),
840        }
841    }
842}
843
844#[cfg(test)]
845mod tests {
846    use super::*;
847    use futures::task::ArcWake;
848    use std::{
849        collections::HashSet as StdHashSet,
850        future::pending,
851        io::{Read, Write},
852        net::TcpListener,
853        sync::{
854            Mutex,
855            atomic::{AtomicUsize, Ordering as AtomicOrdering},
856        },
857        task::Waker,
858    };
859
860    /// A [`Clock`] that moves only when [`ManualClock::run`] has nothing else to do, then jumps to
861    /// the earliest pending sleep.
862    struct ManualClock {
863        start: Instant,
864        state: Arc<Mutex<ClockState>>,
865    }
866
867    #[derive(Default)]
868    struct ClockState {
869        elapsed: Duration,
870        sleepers: Vec<(Duration, Waker)>,
871    }
872
873    struct ManualSleep {
874        state: Arc<Mutex<ClockState>>,
875        deadline: Duration,
876    }
877
878    struct WakeFlag(AtomicBool);
879
880    impl ArcWake for WakeFlag {
881        fn wake_by_ref(arc_self: &Arc<Self>) {
882            arc_self.0.store(true, AtomicOrdering::Relaxed);
883        }
884    }
885
886    impl ManualClock {
887        fn new() -> Arc<Self> {
888            Arc::new(Self { start: Instant::now(), state: Default::default() })
889        }
890
891        /// Polls `fut` to completion, jumping to the earliest pending sleep whenever nothing else
892        /// can progress.
893        fn run<F: Future>(&self, fut: F) -> F::Output {
894            let mut fut = pin!(fut);
895            let woken = Arc::new(WakeFlag(AtomicBool::new(false)));
896            let waker = futures::task::waker(Arc::clone(&woken));
897            let mut cx = Context::from_waker(&waker);
898            loop {
899                woken.0.store(false, AtomicOrdering::Relaxed);
900                if let Poll::Ready(output) = fut.as_mut().poll(&mut cx) {
901                    return output;
902                }
903                if woken.0.load(AtomicOrdering::Relaxed) {
904                    continue;
905                }
906                let mut state = self.state.lock().unwrap();
907                let next = state.sleepers.iter().map(|(deadline, _)| *deadline).min();
908                state.elapsed = state.elapsed.max(next.expect("pending without a sleep"));
909                for (_, waker) in state.sleepers.drain(..) {
910                    waker.wake();
911                }
912            }
913        }
914    }
915
916    impl Clock for ManualClock {
917        fn now(&self) -> Instant {
918            self.start + self.state.lock().unwrap().elapsed
919        }
920
921        fn sleep(&self, duration: Duration) -> Sleep {
922            let deadline = self.state.lock().unwrap().elapsed + duration;
923            Box::pin(ManualSleep { state: Arc::clone(&self.state), deadline })
924        }
925    }
926
927    impl Future for ManualSleep {
928        type Output = ();
929
930        fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<()> {
931            let mut state = self.state.lock().unwrap();
932            if state.elapsed >= self.deadline {
933                return Poll::Ready(());
934            }
935            state.sleepers.push((self.deadline, cx.waker().clone()));
936            Poll::Pending
937        }
938    }
939
940    struct TestFetcher {
941        kind: FetcherKind,
942        delay: Option<Duration>,
943        clock: Arc<dyn Clock>,
944        contract_name: Option<&'static str>,
945        calls: Arc<AtomicUsize>,
946        invalid: AtomicBool,
947    }
948
949    #[async_trait::async_trait]
950    impl ExternalFetcherT for TestFetcher {
951        fn kind(&self) -> FetcherKind {
952            self.kind
953        }
954
955        fn timeout(&self) -> Duration {
956            Duration::from_millis(1)
957        }
958
959        fn concurrency(&self) -> usize {
960            1
961        }
962
963        fn invalid_api_key(&self) -> &AtomicBool {
964            &self.invalid
965        }
966
967        async fn fetch(&self, _address: Address) -> Result<Option<Metadata>, EtherscanError> {
968            self.calls.fetch_add(1, AtomicOrdering::Relaxed);
969            let Some(delay) = self.delay else { return pending().await };
970            if !delay.is_zero() {
971                self.clock.sleep(delay).await;
972            }
973            Ok(self.contract_name.map(metadata))
974        }
975    }
976
977    struct RateLimitedFetcher {
978        calls: Arc<AtomicUsize>,
979        invalid: AtomicBool,
980    }
981
982    #[async_trait::async_trait]
983    impl ExternalFetcherT for RateLimitedFetcher {
984        fn kind(&self) -> FetcherKind {
985            FetcherKind::Sourcify
986        }
987
988        fn timeout(&self) -> Duration {
989            Duration::from_millis(5)
990        }
991
992        fn concurrency(&self) -> usize {
993            1
994        }
995
996        fn invalid_api_key(&self) -> &AtomicBool {
997            &self.invalid
998        }
999
1000        async fn fetch(&self, _address: Address) -> Result<Option<Metadata>, EtherscanError> {
1001            self.calls.fetch_add(1, AtomicOrdering::Relaxed);
1002            Err(EtherscanError::RateLimitExceeded)
1003        }
1004    }
1005
1006    struct ErrorFetcher {
1007        calls: Arc<AtomicUsize>,
1008        invalid: AtomicBool,
1009    }
1010
1011    #[async_trait::async_trait]
1012    impl ExternalFetcherT for ErrorFetcher {
1013        fn kind(&self) -> FetcherKind {
1014            FetcherKind::Etherscan
1015        }
1016
1017        fn timeout(&self) -> Duration {
1018            Duration::ZERO
1019        }
1020
1021        fn concurrency(&self) -> usize {
1022            1
1023        }
1024
1025        fn invalid_api_key(&self) -> &AtomicBool {
1026            &self.invalid
1027        }
1028
1029        async fn fetch(&self, _address: Address) -> Result<Option<Metadata>, EtherscanError> {
1030            self.calls.fetch_add(1, AtomicOrdering::Relaxed);
1031            Err(EtherscanError::Unknown("temporary explorer failure".to_string()))
1032        }
1033    }
1034
1035    fn metadata(contract_name: &str) -> Metadata {
1036        SourcifyMetadata {
1037            abi: None,
1038            compilation: Some(Compilation {
1039                compiler_version: String::new(),
1040                name: contract_name.to_string(),
1041            }),
1042        }
1043        .into()
1044    }
1045
1046    fn test_identifier(
1047        fetchers: Vec<Arc<dyn ExternalFetcherT>>,
1048        remaining_budget: Duration,
1049    ) -> ExternalIdentifier {
1050        test_identifier_with_clock(fetchers, remaining_budget, Arc::new(TokioClock))
1051    }
1052
1053    fn test_identifier_with_clock(
1054        fetchers: Vec<Arc<dyn ExternalFetcherT>>,
1055        remaining_budget: Duration,
1056        clock: Arc<dyn Clock>,
1057    ) -> ExternalIdentifier {
1058        ExternalIdentifier { fetchers, contracts: Default::default(), remaining_budget, clock }
1059    }
1060
1061    #[test]
1062    fn zero_timeout_disables_external_identification() {
1063        let mut config = Config::default();
1064        config.tracing.external_identification_timeout = 0;
1065
1066        assert!(ExternalIdentifier::new(&config, Some(Chain::mainnet())).unwrap().is_none());
1067    }
1068
1069    #[test]
1070    fn alias_for_another_chain_does_not_redirect_lookups() {
1071        let config = ExternalIdentifierConfig {
1072            timeout: 1,
1073            etherscan: serde_json::from_value(serde_json::json!({
1074                "mainnet": { "key": "key" }
1075            }))
1076            .unwrap(),
1077            etherscan_alias: Some("mainnet".to_string()),
1078            etherscan_api_key: Some("mainnet".to_string()),
1079            ..Default::default()
1080        };
1081
1082        assert!(config.storage_identifier(Chain::from(8453)).is_none());
1083
1084        let kinds = |identifier: ExternalIdentifier| {
1085            identifier.fetchers.iter().map(|fetcher| fetcher.kind()).collect::<Vec<_>>()
1086        };
1087        assert_eq!(
1088            kinds(config.identifier(Some(Chain::from(8453))).unwrap()),
1089            [FetcherKind::Sourcify]
1090        );
1091        assert_eq!(
1092            kinds(config.identifier(Some(Chain::mainnet())).unwrap()),
1093            [FetcherKind::Sourcify, FetcherKind::Etherscan]
1094        );
1095
1096        // The traced chain's own entry is used instead of the foreign alias.
1097        let config = ExternalIdentifierConfig {
1098            etherscan: serde_json::from_value(serde_json::json!({
1099                "mainnet": { "key": "key" },
1100                "base": { "key": "key" }
1101            }))
1102            .unwrap(),
1103            ..config
1104        };
1105        let (chain, etherscan) =
1106            config.resolve_explorer(Some(Chain::from(8453)), Some("mainnet"), Some("mainnet"));
1107        assert_eq!(chain, Some(Chain::from(8453)));
1108        assert_eq!(etherscan.unwrap().chain, Some(Chain::from(8453)));
1109
1110        // A chainless alias keeps its explorer URL without clearing the traced chain.
1111        let config = ExternalIdentifierConfig {
1112            etherscan: serde_json::from_value(serde_json::json!({
1113                "custom": { "key": "key", "url": "https://explorer.invalid/api" }
1114            }))
1115            .unwrap(),
1116            etherscan_alias: Some("custom".to_string()),
1117            etherscan_api_key: Some("custom".to_string()),
1118            ..config
1119        };
1120        assert_eq!(
1121            kinds(config.identifier(Some(Chain::from(8453))).unwrap()),
1122            [FetcherKind::Sourcify, FetcherKind::Etherscan]
1123        );
1124    }
1125
1126    /// Fetcher that returns a transient Cloudflare block the first time it sees an address, then
1127    /// succeeds. Mirrors Etherscan/Cloudflare throttling a burst of concurrent requests.
1128    struct FlakyCloudflareFetcher {
1129        seen: Mutex<StdHashSet<Address>>,
1130        invalid: AtomicBool,
1131    }
1132
1133    #[async_trait::async_trait]
1134    impl ExternalFetcherT for FlakyCloudflareFetcher {
1135        fn kind(&self) -> FetcherKind {
1136            FetcherKind::Etherscan
1137        }
1138        fn timeout(&self) -> Duration {
1139            Duration::from_millis(1)
1140        }
1141        fn concurrency(&self) -> usize {
1142            1
1143        }
1144        fn invalid_api_key(&self) -> &AtomicBool {
1145            &self.invalid
1146        }
1147        async fn fetch(&self, address: Address) -> Result<Option<Metadata>, EtherscanError> {
1148            let first_time = self.seen.lock().unwrap().insert(address);
1149            if first_time { Err(EtherscanError::BlockedByCloudflare) } else { Ok(None) }
1150        }
1151    }
1152
1153    /// Regression test for #9880: a transient Cloudflare block on one address must not abandon the
1154    /// rest of the queue. Before the fix the fetcher returned `Poll::Ready(None)` on the first
1155    /// block, ending the stream and leaving later addresses unidentified (partial trace decoding).
1156    #[tokio::test]
1157    async fn cloudflare_block_retries_instead_of_abandoning_queue() {
1158        let addrs: Vec<Address> = (1u8..=4).map(Address::with_last_byte).collect();
1159        let fetcher: Arc<dyn ExternalFetcherT> = Arc::new(FlakyCloudflareFetcher {
1160            seen: Mutex::new(StdHashSet::new()),
1161            invalid: AtomicBool::new(false),
1162        });
1163
1164        let collected: Vec<_> =
1165            ExternalFetcher::new(fetcher, &addrs, Arc::new(TokioClock)).collect().await;
1166
1167        let got: StdHashSet<Address> = collected.into_iter().map(|(addr, _)| addr).collect();
1168        let want: StdHashSet<Address> = addrs.into_iter().collect();
1169        assert_eq!(got, want, "every address must be yielded despite a transient cloudflare block");
1170    }
1171
1172    #[test]
1173    fn timeout_keeps_partial_results_and_opens_circuit() {
1174        let clock = ManualClock::new();
1175        let successful_calls = Arc::new(AtomicUsize::new(0));
1176        let stalled_calls = Arc::new(AtomicUsize::new(0));
1177        let fetchers: Vec<Arc<dyn ExternalFetcherT>> = vec![
1178            Arc::new(TestFetcher {
1179                kind: FetcherKind::Sourcify,
1180                delay: Some(Duration::ZERO),
1181                clock: clock.clone(),
1182                contract_name: Some("PartialResult"),
1183                calls: Arc::clone(&successful_calls),
1184                invalid: AtomicBool::new(false),
1185            }),
1186            Arc::new(TestFetcher {
1187                kind: FetcherKind::Etherscan,
1188                delay: None,
1189                clock: clock.clone(),
1190                contract_name: None,
1191                calls: Arc::clone(&stalled_calls),
1192                invalid: AtomicBool::new(false),
1193            }),
1194        ];
1195        let mut identifier =
1196            test_identifier_with_clock(fetchers, Duration::from_millis(20), clock.clone());
1197        let address = Address::with_last_byte(1);
1198
1199        clock.run(identifier.fetch_addresses_async(&[address]));
1200
1201        assert!(identifier.remaining_budget.is_zero());
1202        assert_eq!(
1203            identifier.contracts[&address].1.as_ref().unwrap().contract_name,
1204            "PartialResult"
1205        );
1206        assert_eq!(successful_calls.load(AtomicOrdering::Relaxed), 1);
1207        assert_eq!(stalled_calls.load(AtomicOrdering::Relaxed), 1);
1208
1209        clock.run(identifier.fetch_addresses_async(&[Address::with_last_byte(2)]));
1210        assert_eq!(successful_calls.load(AtomicOrdering::Relaxed), 1);
1211        assert_eq!(stalled_calls.load(AtomicOrdering::Relaxed), 1);
1212    }
1213
1214    #[tokio::test(flavor = "multi_thread")]
1215    async fn timeout_returns_partial_identity() {
1216        let fetchers: Vec<Arc<dyn ExternalFetcherT>> = vec![
1217            Arc::new(TestFetcher {
1218                kind: FetcherKind::Sourcify,
1219                delay: Some(Duration::ZERO),
1220                clock: Arc::new(TokioClock),
1221                contract_name: Some("PartialResult"),
1222                calls: Arc::new(AtomicUsize::new(0)),
1223                invalid: AtomicBool::new(false),
1224            }),
1225            Arc::new(TestFetcher {
1226                kind: FetcherKind::Etherscan,
1227                delay: None,
1228                clock: Arc::new(TokioClock),
1229                contract_name: None,
1230                calls: Arc::new(AtomicUsize::new(0)),
1231                invalid: AtomicBool::new(false),
1232            }),
1233        ];
1234        let mut identifier = test_identifier(fetchers, Duration::from_millis(20));
1235        let mut node = CallTraceNode::default();
1236        node.trace.address = Address::with_last_byte(1);
1237
1238        let identities = identifier.identify_addresses(&[&node]);
1239
1240        assert_eq!(identities.len(), 1);
1241        assert_eq!(identities[0].label.as_deref(), Some("PartialResult"));
1242    }
1243
1244    #[test]
1245    fn timeout_budget_is_cumulative_across_fetches() {
1246        let clock = ManualClock::new();
1247        let calls = Arc::new(AtomicUsize::new(0));
1248        let fetcher: Arc<dyn ExternalFetcherT> = Arc::new(TestFetcher {
1249            kind: FetcherKind::Sourcify,
1250            delay: Some(Duration::from_millis(20)),
1251            clock: clock.clone(),
1252            contract_name: Some("FirstResult"),
1253            calls: Arc::clone(&calls),
1254            invalid: AtomicBool::new(false),
1255        });
1256        let mut identifier =
1257            test_identifier_with_clock(vec![fetcher], Duration::from_millis(30), clock.clone());
1258        let first = Address::with_last_byte(1);
1259        let second = Address::with_last_byte(2);
1260
1261        clock.run(identifier.fetch_addresses_async(&[first]));
1262        assert!(identifier.contracts[&first].1.is_some());
1263        assert_eq!(identifier.remaining_budget, Duration::from_millis(10));
1264
1265        clock.run(identifier.fetch_addresses_async(&[second]));
1266        assert!(identifier.remaining_budget.is_zero());
1267        assert!(!identifier.contracts.contains_key(&second));
1268        assert_eq!(calls.load(AtomicOrdering::Relaxed), 2);
1269    }
1270
1271    #[test]
1272    fn metadata_requests_preserve_cumulative_budget() {
1273        let clock = ManualClock::new();
1274        let calls = Arc::new(AtomicUsize::new(0));
1275        let fetcher: Arc<dyn ExternalFetcherT> = Arc::new(TestFetcher {
1276            kind: FetcherKind::Etherscan,
1277            delay: None,
1278            clock: clock.clone(),
1279            contract_name: None,
1280            calls: Arc::clone(&calls),
1281            invalid: AtomicBool::new(false),
1282        });
1283        let mut identifier =
1284            test_identifier_with_clock(vec![fetcher], Duration::from_millis(30), clock.clone());
1285        let address = Address::with_last_byte(1);
1286
1287        assert!(
1288            clock.run(identifier.get_metadata(&[address], Duration::from_millis(10))).is_empty()
1289        );
1290        assert_eq!(identifier.remaining_budget, Duration::from_millis(20));
1291        assert!(clock.run(identifier.get_metadata(&[address], Duration::from_secs(1))).is_empty());
1292        assert!(identifier.remaining_budget.is_zero());
1293        assert!(clock.run(identifier.get_metadata(&[address], Duration::from_secs(1))).is_empty());
1294        assert_eq!(calls.load(AtomicOrdering::Relaxed), 2);
1295    }
1296
1297    #[test]
1298    fn rate_limit_retries_cannot_escape_timeout_budget() {
1299        let clock = ManualClock::new();
1300        let calls = Arc::new(AtomicUsize::new(0));
1301        let fetcher: Arc<dyn ExternalFetcherT> = Arc::new(RateLimitedFetcher {
1302            calls: Arc::clone(&calls),
1303            invalid: AtomicBool::new(false),
1304        });
1305        let mut identifier =
1306            test_identifier_with_clock(vec![fetcher], Duration::from_millis(20), clock.clone());
1307
1308        clock.run(identifier.fetch_addresses_async(&[Address::with_last_byte(1)]));
1309
1310        assert!(identifier.remaining_budget.is_zero());
1311        assert!(calls.load(AtomicOrdering::Relaxed) > 1);
1312    }
1313
1314    #[test]
1315    fn rate_limit_retries_are_bounded() {
1316        let clock = ManualClock::new();
1317        let calls = Arc::new(AtomicUsize::new(0));
1318        let fetcher: Arc<dyn ExternalFetcherT> = Arc::new(RateLimitedFetcher {
1319            calls: Arc::clone(&calls),
1320            invalid: AtomicBool::new(false),
1321        });
1322
1323        let fetched = clock.run(
1324            ExternalFetcher::new(fetcher, &[Address::with_last_byte(1)], clock.clone())
1325                .collect::<Vec<_>>(),
1326        );
1327
1328        assert!(fetched.is_empty());
1329        assert_eq!(calls.load(AtomicOrdering::Relaxed), MAX_TRANSIENT_RETRIES as usize + 1);
1330    }
1331
1332    struct UnsupportedChainFetcher {
1333        calls: Arc<AtomicUsize>,
1334        invalid: AtomicBool,
1335    }
1336
1337    #[async_trait::async_trait]
1338    impl ExternalFetcherT for UnsupportedChainFetcher {
1339        fn kind(&self) -> FetcherKind {
1340            FetcherKind::Sourcify
1341        }
1342
1343        fn timeout(&self) -> Duration {
1344            Duration::ZERO
1345        }
1346
1347        fn concurrency(&self) -> usize {
1348            1
1349        }
1350
1351        fn invalid_api_key(&self) -> &AtomicBool {
1352            &self.invalid
1353        }
1354
1355        async fn fetch(&self, _address: Address) -> Result<Option<Metadata>, EtherscanError> {
1356            self.calls.fetch_add(1, AtomicOrdering::Relaxed);
1357            Err(EtherscanError::ChainNotSupported(Chain::from_id(12345)))
1358        }
1359    }
1360
1361    #[tokio::test]
1362    async fn unsupported_chain_disables_fetcher() {
1363        let calls = Arc::new(AtomicUsize::new(0));
1364        let mut identifier = test_identifier(
1365            vec![Arc::new(UnsupportedChainFetcher {
1366                calls: Arc::clone(&calls),
1367                invalid: AtomicBool::new(false),
1368            })],
1369            Duration::from_secs(1),
1370        );
1371
1372        identifier
1373            .fetch_addresses_async(&[Address::with_last_byte(1), Address::with_last_byte(2)])
1374            .await;
1375        identifier.fetch_addresses_async(&[Address::with_last_byte(3)]).await;
1376
1377        assert_eq!(calls.load(AtomicOrdering::Relaxed), 1);
1378    }
1379
1380    #[test]
1381    fn sourcify_skips_local_chains() {
1382        let config = ExternalIdentifierConfig { timeout: 1, ..Default::default() };
1383
1384        assert!(config.identifier(Some(Chain::from_id(31337))).is_none());
1385        assert!(config.identifier(Some(Chain::dev())).is_none());
1386        assert!(config.identifier(Some(Chain::mainnet())).is_some());
1387    }
1388
1389    #[tokio::test(flavor = "multi_thread")]
1390    async fn foundry_addresses_are_not_fetched() {
1391        let calls = Arc::new(AtomicUsize::new(0));
1392        let mut identifier = test_identifier(
1393            vec![Arc::new(TestFetcher {
1394                kind: FetcherKind::Sourcify,
1395                delay: Some(Duration::ZERO),
1396                clock: Arc::new(TokioClock),
1397                contract_name: None,
1398                calls: Arc::clone(&calls),
1399                invalid: AtomicBool::new(false),
1400            })],
1401            Duration::from_secs(1),
1402        );
1403        let nodes = [CHEATCODE_ADDRESS, HARDHAT_CONSOLE_ADDRESS].map(|address| {
1404            let mut node = CallTraceNode::default();
1405            node.trace.address = address;
1406            node
1407        });
1408
1409        assert!(identifier.identify_addresses(&[&nodes[0], &nodes[1]]).is_empty());
1410        assert_eq!(calls.load(AtomicOrdering::Relaxed), 0);
1411    }
1412
1413    /// Serves one HTTP response with status 400 and `body`, then returns the Sourcify result.
1414    async fn sourcify_bad_request(body: &'static str) -> EtherscanError {
1415        let listener = TcpListener::bind("127.0.0.1:0").unwrap();
1416        let addr = listener.local_addr().unwrap();
1417        std::thread::spawn(move || {
1418            let (mut stream, _) = listener.accept().unwrap();
1419            let _ = stream.read(&mut [0; 4096]);
1420            let response = format!(
1421                "HTTP/1.1 400 Bad Request\r\ncontent-length: {}\r\nconnection: close\r\n\r\n{body}",
1422                body.len()
1423            );
1424            stream.write_all(response.as_bytes()).unwrap();
1425        });
1426        let mut fetcher = SourcifyFetcher::new(Chain::mainnet());
1427        fetcher.url = format!("http://{addr}");
1428        fetcher.fetch(Address::with_last_byte(1)).await.unwrap_err()
1429    }
1430
1431    #[tokio::test]
1432    async fn sourcify_bad_request_is_final_only_when_recognized() {
1433        let error =
1434            sourcify_bad_request(r#"{"customCode":"unsupported_chain","message":"","errorId":""}"#)
1435                .await;
1436        assert!(matches!(error, EtherscanError::ChainNotSupported(_)));
1437
1438        let error =
1439            sourcify_bad_request(r#"{"customCode":"invalid_parameter","message":"","errorId":""}"#)
1440                .await;
1441        assert!(matches!(error, EtherscanError::ContractCodeNotVerified(_)));
1442
1443        let error =
1444            sourcify_bad_request(r#"{"customCode":"other","message":"","errorId":""}"#).await;
1445        assert!(matches!(error, EtherscanError::Unknown(_)));
1446
1447        let error = sourcify_bad_request("<html>bad request</html>").await;
1448        assert!(matches!(error, EtherscanError::Unknown(_)));
1449    }
1450
1451    #[tokio::test]
1452    async fn transient_errors_are_not_cached_as_unverified() {
1453        let calls = Arc::new(AtomicUsize::new(0));
1454        let mut identifier = test_identifier(
1455            vec![Arc::new(ErrorFetcher {
1456                calls: Arc::clone(&calls),
1457                invalid: AtomicBool::new(false),
1458            })],
1459            Duration::from_secs(1),
1460        );
1461        let address = Address::with_last_byte(1);
1462
1463        assert!(identifier.get_metadata(&[address], Duration::from_secs(1)).await.is_empty());
1464        assert!(identifier.get_metadata(&[address], Duration::from_secs(1)).await.is_empty());
1465        assert_eq!(calls.load(AtomicOrdering::Relaxed), 2);
1466    }
1467
1468    #[test]
1469    fn etherscan_metadata_takes_precedence() {
1470        let address = Address::with_last_byte(1);
1471        let mut identifier = test_identifier(Vec::new(), Duration::ZERO);
1472
1473        identifier
1474            .cache_fetched(address, (FetcherKind::Sourcify, Some(metadata("SourcifyResult"))));
1475        identifier.cache_fetched(address, (FetcherKind::Etherscan, None));
1476        assert_eq!(
1477            identifier.contracts[&address].1.as_ref().unwrap().contract_name,
1478            "SourcifyResult"
1479        );
1480
1481        identifier
1482            .cache_fetched(address, (FetcherKind::Etherscan, Some(metadata("EtherscanResult"))));
1483        assert_eq!(
1484            identifier.contracts[&address].1.as_ref().unwrap().contract_name,
1485            "EtherscanResult"
1486        );
1487    }
1488
1489    #[tokio::test]
1490    async fn proxy_metadata_preserves_address_identity_and_all_abis() {
1491        let proxy = Address::with_last_byte(1);
1492        let implementation_address = Address::with_last_byte(2);
1493        let mut proxy_metadata = metadata("Proxy");
1494        proxy_metadata.abi =
1495            r#"[{"anonymous":false,"inputs":[],"name":"ProxyEvent","type":"event"}]"#.to_string();
1496        proxy_metadata.proxy = 1;
1497        proxy_metadata.implementation = Some(implementation_address);
1498        let mut implementation = metadata("Implementation");
1499        implementation.abi =
1500            r#"[{"anonymous":false,"inputs":[],"name":"ImplementationEvent","type":"event"}]"#
1501                .to_string();
1502        let mut identifier = test_identifier(Vec::new(), Duration::from_secs(1));
1503        let identity = identifier.identify_from_metadata(proxy, &proxy_metadata);
1504        assert_eq!(identity.contract.as_deref(), Some("Proxy"));
1505        identifier.cache_fetched(proxy, (FetcherKind::Etherscan, Some(proxy_metadata)));
1506        identifier
1507            .cache_fetched(implementation_address, (FetcherKind::Etherscan, Some(implementation)));
1508
1509        let mut results = identifier.get_abis(&[proxy]).await;
1510        let (result_address, result) = results.pop().unwrap();
1511        let (abis, complete) = result.unwrap();
1512        let event_names =
1513            abis.into_iter().map(|abi| abi.events.into_keys().next().unwrap()).collect::<Vec<_>>();
1514
1515        assert_eq!(result_address, proxy);
1516        assert!(complete);
1517        assert_eq!(event_names, ["ImplementationEvent", "ProxyEvent"]);
1518
1519        identifier.contracts.remove(&implementation_address);
1520        let (_, result) = identifier.get_abis(&[proxy]).await.pop().unwrap();
1521        let (abis, complete) = result.unwrap();
1522        assert_eq!(abis.len(), 1);
1523        assert!(!complete);
1524    }
1525
1526    #[tokio::test]
1527    async fn storage_metadata_does_not_follow_explorer_proxy_hints() {
1528        let proxy = Address::with_last_byte(1);
1529        let implementation_address = Address::with_last_byte(2);
1530        let mut proxy_metadata = metadata("Proxy");
1531        proxy_metadata.proxy = 1;
1532        proxy_metadata.implementation = Some(implementation_address);
1533        let mut identifier = test_identifier(Vec::new(), Duration::from_secs(1));
1534        identifier.cache_fetched(proxy, (FetcherKind::Etherscan, Some(proxy_metadata)));
1535        identifier.cache_fetched(
1536            implementation_address,
1537            (FetcherKind::Etherscan, Some(metadata("CurrentImplementation"))),
1538        );
1539
1540        let result = identifier.get_metadata(&[proxy], Duration::from_secs(1)).await;
1541
1542        assert_eq!(result[&proxy].as_ref().unwrap().contract_name, "Proxy");
1543        assert_eq!(result.len(), 1);
1544    }
1545}