1use crate::{fs, namespaced_storage};
19use alloy_chains::Chain;
20use alloy_primitives::{Address, map::AddressMap};
21use foundry_block_explorers::contract::Metadata;
22use foundry_compilers::{
23 artifacts::{
24 CompilerOutput, SolcInput, SolcLanguage, Source, Sources, StorageLayout,
25 output_selection::OutputSelection,
26 },
27 solc::Solc,
28};
29use foundry_config::Config;
30use serde::{Deserialize, Serialize};
31use std::{
32 io::{Read, Seek, SeekFrom},
33 path::{Path, PathBuf},
34 process::{Command, Stdio},
35 sync::{
36 Arc, LazyLock, Mutex, MutexGuard, TryLockError,
37 atomic::{AtomicU64, Ordering},
38 },
39 time::{Duration, Instant},
40};
41use wait_timeout::ChildExt;
42
43const MIN_STORAGE_LAYOUT_SOLC: semver::Version = semver::Version::new(0, 6, 5);
45const BASE_PATH_SOLC: semver::Version = semver::Version::new(0, 6, 9);
47const NO_IMPORT_CALLBACK_SOLC: semver::Version = semver::Version::new(0, 8, 22);
49
50type ExternalStorageLayout = Option<(String, Arc<StorageLayout>)>;
56
57type LookupSlot = Arc<Mutex<Option<ExternalStorageLayout>>>;
59
60static LOOKUPS: LazyLock<Mutex<std::collections::HashMap<(u64, Address), LookupSlot>>> =
66 LazyLock::new(Default::default);
67
68static COMPILER: Mutex<()> = Mutex::new(());
70
71static CACHE_TEMP_ID: AtomicU64 = AtomicU64::new(0);
73
74pub fn fetch_external_storage_layouts(
87 chain: Chain,
88 addresses: impl IntoIterator<Item = Address>,
89 timeout: Duration,
90 fetch_sources: impl FnOnce(&[Address], Duration) -> AddressMap<Option<Metadata>>,
91) -> AddressMap<(String, Arc<StorageLayout>)> {
92 let cache_dir = Config::foundry_etherscan_chain_cache_dir(chain);
93 resolve(chain.id(), cache_dir.as_deref(), addresses, timeout, fetch_sources)
94}
95
96fn resolve(
99 chain_id: u64,
100 cache_dir: Option<&Path>,
101 addresses: impl IntoIterator<Item = Address>,
102 timeout: Duration,
103 fetch_sources: impl FnOnce(&[Address], Duration) -> AddressMap<Option<Metadata>>,
104) -> AddressMap<(String, Arc<StorageLayout>)> {
105 let deadline = Instant::now().checked_add(timeout).unwrap_or_else(Instant::now);
106 let mut resolved = AddressMap::default();
107
108 let mut addresses = addresses.into_iter().collect::<Vec<_>>();
111 addresses.sort_unstable();
112 addresses.dedup();
113 let slots = {
114 let Some(mut lookups) = lock_until(&LOOKUPS, deadline) else {
115 warn!(target: "external-storage", "external storage lookup timed out");
116 return resolved;
117 };
118 addresses
119 .into_iter()
120 .map(|address| (address, lookups.entry((chain_id, address)).or_default().clone()))
121 .collect::<Vec<_>>()
122 };
123
124 let mut pending = Vec::new();
125 for (address, slot) in &slots {
126 let Some(guard) = lock_until(slot, deadline) else {
128 warn!(target: "external-storage", %address, "external storage lookup timed out");
129 return resolved;
130 };
131 if let Some(cached) = &*guard {
132 if let Some((name, layout)) = cached {
133 resolved.insert(*address, (name.clone(), layout.clone()));
134 }
135 continue;
136 }
137 pending.push((*address, guard));
138 }
139
140 if pending.is_empty() {
141 return resolved;
142 }
143
144 pending.retain_mut(|(address, guard)| {
147 let Some(cached) = read_cached_layout(cache_dir, *address) else {
148 return true;
149 };
150 resolved.insert(*address, cached.clone());
151 **guard = Some(Some(cached));
152 false
153 });
154
155 if pending.is_empty() {
156 return resolved;
157 }
158
159 let remaining = deadline.saturating_duration_since(Instant::now());
160 if remaining.is_zero() {
161 warn!(target: "external-storage", "external storage lookup timed out");
162 return resolved;
163 }
164 let sources =
165 fetch_sources(&pending.iter().map(|(address, _)| *address).collect::<Vec<_>>(), remaining);
166
167 for (address, mut guard) in pending {
168 let Some(source) = sources.get(&address) else {
169 continue;
172 };
173
174 let Some(metadata) = source else {
175 *guard = Some(None);
177 continue;
178 };
179
180 let layout = compile_storage_layout(address, metadata, deadline);
181 if layout.is_none() && Instant::now() >= deadline {
182 continue;
185 }
186 if let Some((name, layout)) = &layout {
187 resolved.insert(address, (name.clone(), layout.clone()));
188 write_cached_layout(cache_dir, address, name, layout);
189 }
190 *guard = Some(layout);
193 }
194
195 resolved
196}
197
198fn compile_storage_layout(
200 address: Address,
201 metadata: &Metadata,
202 deadline: Instant,
203) -> Option<(String, Arc<StorageLayout>)> {
204 if metadata.is_vyper() {
205 trace!(target: "external-storage", %address, "skipping vyper contract");
206 return None;
207 }
208
209 match metadata.compiler_version() {
213 Ok(version) if version < MIN_STORAGE_LAYOUT_SOLC => {
214 trace!(target: "external-storage", %address, %version, "solc too old for storage layouts");
215 return None;
216 }
217 Ok(_) => {}
218 Err(err) => {
219 warn!(target: "external-storage", %address, %err, "could not read compiler version");
220 return None;
221 }
222 }
223
224 let sources = metadata
225 .sources()
226 .into_iter()
227 .map(|(path, source)| (PathBuf::from(path), Source::new(source.content)))
228 .collect::<Sources>();
229 if sources.is_empty() {
230 trace!(target: "external-storage", %address, "verified metadata has no sources");
231 return None;
232 }
233 let Some(_compiler) = lock_until(&COMPILER, deadline) else {
234 warn!(target: "external-storage", %address, "external storage compilation timed out");
235 return None;
236 };
237
238 let version = metadata.compiler_version().ok()?;
242 let mut settings = match metadata.settings() {
243 Ok(settings) => settings,
244 Err(err) => {
245 warn!(target: "external-storage", %address, %err, "failed to read compiler settings");
246 return None;
247 }
248 };
249 settings.output_selection =
250 OutputSelection::common_output_selection(["storageLayout".to_string()]);
251 let input = SolcInput::new(SolcLanguage::Solidity, sources, settings).sanitized(&version);
252 let svm_version = semver::Version::new(version.major, version.minor, version.patch);
253 let solc = match Solc::find_svm_installed_version(&svm_version) {
254 Ok(Some(solc)) => solc,
255 Ok(None) => {
256 let remaining = deadline.saturating_duration_since(Instant::now());
257 let installed =
258 crate::block_on(tokio::time::timeout(remaining, Solc::install(&svm_version)));
259 match installed {
260 Ok(Ok(solc)) => solc,
261 Ok(Err(err)) => {
262 warn!(target: "external-storage", %address, %err, "failed to install compiler");
263 return None;
264 }
265 Err(_) => {
266 warn!(target: "external-storage", %address, "compiler installation timed out");
267 return None;
268 }
269 }
270 }
271 Err(err) => {
272 warn!(target: "external-storage", %address, %err, "failed to find compiler");
273 return None;
274 }
275 };
276 let remaining = deadline.saturating_duration_since(Instant::now());
277 let output = match run_solc(&solc, &version, &input, remaining) {
278 Ok(output) => output,
279 Err(err) => {
280 warn!(target: "external-storage", %address, %err, "failed to compile contract");
281 return None;
282 }
283 };
284
285 let name = metadata.contract_name.clone();
286 let mut namespaces =
290 namespaced_storage::parse_standard_json(&input.sources, &input.settings.remappings);
291 let mut matches = output
292 .contracts
293 .iter()
294 .filter_map(|(path, contracts)| Some((path, contracts.get(&name)?)))
295 .map(|(path, contract)| {
296 let layout = contract.storage_layout.clone();
297 let Some(compiler) = &mut namespaces else { return layout };
298 extend_external_storage_layout(compiler, path.as_str().as_ref(), &name, layout, address)
299 })
300 .filter(|layout| !layout.storage.is_empty());
301 let layout = matches.next();
302 if matches.next().is_some() {
303 warn!(target: "external-storage", %address, %name, "multiple artifacts match contract name");
304 return None;
305 }
306
307 let Some(layout) = layout else {
308 warn!(target: "external-storage", %address, %name, "no storage layout in compiled artifacts");
309 return None;
310 };
311
312 Some((name, Arc::new(layout)))
313}
314
315fn extend_external_storage_layout(
319 compiler: &mut solar::sema::Compiler,
320 path: &Path,
321 name: &str,
322 layout: StorageLayout,
323 address: Address,
324) -> StorageLayout {
325 let mut extended = layout.clone();
326 let result = compiler.enter_mut(|compiler| {
327 namespaced_storage::lower(compiler)?;
328 let gcx = compiler.gcx();
329 let root = Path::new("");
331 let Some(contract) = namespaced_storage::find_contract(gcx, root, path, name) else {
332 return Ok(());
333 };
334 namespaced_storage::extend_storage_layout(&mut extended, gcx, root, contract)
335 });
336 match result {
337 Ok(()) => extended,
338 Err(err) => {
339 warn!(target: "external-storage", %address, %name, %err, "skipping ERC-7201 namespaces");
340 layout
341 }
342 }
343}
344
345fn run_solc(
347 solc: &Solc,
348 version: &semver::Version,
349 input: &SolcInput,
350 timeout: Duration,
351) -> Result<CompilerOutput, String> {
352 if timeout.is_zero() {
353 return Err("compilation timed out".to_string());
354 }
355
356 let sandbox = tempfile::tempdir().map_err(|err| err.to_string())?;
357 let mut stdin = tempfile::tempfile().map_err(|err| err.to_string())?;
358 serde_json::to_writer(&mut stdin, input).map_err(|err| err.to_string())?;
359 stdin.seek(SeekFrom::Start(0)).map_err(|err| err.to_string())?;
360 let mut stdout = tempfile::tempfile().map_err(|err| err.to_string())?;
361 let mut stderr = tempfile::tempfile().map_err(|err| err.to_string())?;
362
363 let mut command = Command::new(&solc.solc);
364 command.arg("--standard-json").current_dir(sandbox.path());
365 if version >= &BASE_PATH_SOLC {
366 command.arg("--base-path").arg(sandbox.path());
367 }
368 if version >= &NO_IMPORT_CALLBACK_SOLC {
369 command.arg("--no-import-callback");
370 }
371 command
372 .stdin(Stdio::from(stdin))
373 .stdout(Stdio::from(stdout.try_clone().map_err(|err| err.to_string())?))
374 .stderr(Stdio::from(stderr.try_clone().map_err(|err| err.to_string())?));
375
376 let mut child = command.spawn().map_err(|err| err.to_string())?;
377 let status = match child.wait_timeout(timeout) {
378 Ok(Some(status)) => status,
379 Ok(None) => {
380 let _ = child.kill();
381 let _ = child.wait();
382 return Err("compilation timed out".to_string());
383 }
384 Err(err) => {
385 let _ = child.kill();
386 let _ = child.wait();
387 return Err(err.to_string());
388 }
389 };
390 if !status.success() {
391 stderr.seek(SeekFrom::Start(0)).map_err(|err| err.to_string())?;
392 let mut message = String::new();
393 stderr.read_to_string(&mut message).map_err(|err| err.to_string())?;
394 return Err(if message.trim().is_empty() {
395 format!("solc exited with {status}")
396 } else {
397 message
398 });
399 }
400
401 stdout.seek(SeekFrom::Start(0)).map_err(|err| err.to_string())?;
402 serde_json::from_reader(stdout).map_err(|err| err.to_string())
403}
404
405#[derive(Serialize, Deserialize)]
407#[serde(rename_all = "camelCase")]
408struct CachedStorageLayout {
409 version: u32,
412 contract_name: String,
413 storage_layout: StorageLayout,
414}
415
416const CACHE_VERSION: u32 = 4;
420
421fn cache_path(cache_dir: &Path, address: Address) -> PathBuf {
423 cache_dir.join("storage_layouts").join(format!("{address}.json"))
424}
425
426fn read_cached_layout(
428 cache_dir: Option<&Path>,
429 address: Address,
430) -> Option<(String, Arc<StorageLayout>)> {
431 let path = cache_path(cache_dir?, address);
432 let cached = fs::read_json_file::<CachedStorageLayout>(&path).ok()?;
433 if cached.version != CACHE_VERSION {
434 trace!(target: "external-storage", %address, cached.version, "ignoring stale cache entry");
435 return None;
436 }
437 trace!(target: "external-storage", %address, "using cached storage layout");
438 Some((cached.contract_name, Arc::new(cached.storage_layout)))
439}
440
441fn write_cached_layout(
446 cache_dir: Option<&Path>,
447 address: Address,
448 name: &str,
449 layout: &StorageLayout,
450) {
451 let Some(cache_dir) = cache_dir else { return };
452 let path = cache_path(cache_dir, address);
453 let Some(parent) = path.parent() else { return };
454 if let Err(err) = std::fs::create_dir_all(parent) {
455 warn!(target: "external-storage", %address, %err, "failed to create storage layout cache");
456 return;
457 }
458
459 let cached = CachedStorageLayout {
460 version: CACHE_VERSION,
461 contract_name: name.to_string(),
462 storage_layout: layout.clone(),
463 };
464
465 let tmp_path = path.with_extension(format!(
468 "json.{}.{}.tmp",
469 std::process::id(),
470 CACHE_TEMP_ID.fetch_add(1, Ordering::Relaxed)
471 ));
472 match std::fs::OpenOptions::new().write(true).create_new(true).open(&tmp_path) {
473 Ok(_) => {}
474 Err(err) => {
475 warn!(target: "external-storage", %address, %err, "failed to create cache temporary file");
476 return;
477 }
478 }
479 let write = fs::write_json_file(&tmp_path, &cached).and_then(|()| {
480 std::fs::rename(&tmp_path, &path)
481 .map_err(|err| crate::errors::FsPathError::write(err, path.as_path()))
482 });
483 if let Err(err) = write {
484 warn!(target: "external-storage", %address, %err, "failed to cache storage layout");
485 let _ = std::fs::remove_file(&tmp_path);
486 }
487}
488
489pub fn lock_until<T>(mutex: &Mutex<T>, deadline: Instant) -> Option<MutexGuard<'_, T>> {
493 loop {
494 match mutex.try_lock() {
495 Ok(guard) => return Some(guard),
496 Err(TryLockError::Poisoned(err)) => return Some(err.into_inner()),
497 Err(TryLockError::WouldBlock) => {
498 let remaining = deadline.saturating_duration_since(Instant::now());
499 if remaining.is_zero() {
500 return None;
501 }
502 std::thread::sleep(remaining.min(Duration::from_millis(1)));
503 }
504 }
505 }
506}
507
508#[cfg(test)]
509mod tests {
510 use super::*;
511 use foundry_block_explorers::contract::SourceCodeMetadata;
512
513 #[cfg(unix)]
514 use std::os::unix::fs::PermissionsExt;
515
516 fn next_chain_id() -> u64 {
519 static NEXT: AtomicU64 = AtomicU64::new(1);
520 NEXT.fetch_add(1, Ordering::Relaxed)
521 }
522
523 #[test]
524 fn round_trips_a_resolved_layout() {
525 let cache_dir = tempfile::tempdir().unwrap();
526 let address = Address::with_last_byte(1);
527
528 assert!(read_cached_layout(Some(cache_dir.path()), address).is_none());
530
531 let layout = StorageLayout::default();
532 write_cached_layout(Some(cache_dir.path()), address, "Counter", &layout);
533
534 let (name, cached) = read_cached_layout(Some(cache_dir.path()), address).unwrap();
535 assert_eq!(name, "Counter");
536 assert_eq!(*cached, layout);
537 }
538
539 #[test]
540 fn ignores_cache_entries_written_by_another_version() {
541 let cache_dir = tempfile::tempdir().unwrap();
542 let address = Address::with_last_byte(1);
543 write_cached_layout(Some(cache_dir.path()), address, "Counter", &StorageLayout::default());
544
545 let path = cache_path(cache_dir.path(), address);
546 let stale = std::fs::read_to_string(&path)
547 .unwrap()
548 .replace(&format!("\"version\":{CACHE_VERSION}"), "\"version\":0");
549 std::fs::write(&path, stale).unwrap();
550
551 assert!(read_cached_layout(Some(cache_dir.path()), address).is_none());
552 }
553
554 #[test]
555 fn write_leaves_no_temporary_files_behind() {
556 let cache_dir = tempfile::tempdir().unwrap();
557 let address = Address::with_last_byte(1);
558 write_cached_layout(Some(cache_dir.path()), address, "Counter", &StorageLayout::default());
559
560 let entries = std::fs::read_dir(cache_dir.path().join("storage_layouts"))
561 .unwrap()
562 .map(|entry| entry.unwrap().file_name())
563 .collect::<Vec<_>>();
564 assert_eq!(entries, [format!("{address}.json").as_str()]);
565 }
566
567 #[test]
568 fn serves_the_disk_cache_without_looking_anything_up() {
569 let cache_dir = tempfile::tempdir().unwrap();
570 let chain_id = next_chain_id();
571 let cached = Address::with_last_byte(1);
572 let fresh = Address::with_last_byte(2);
573 write_cached_layout(Some(cache_dir.path()), cached, "Counter", &StorageLayout::default());
574
575 let mut asked_for = Vec::new();
576 let resolved = resolve(
577 chain_id,
578 Some(cache_dir.path()),
579 [cached, fresh],
580 Duration::from_secs(1),
581 |addresses, _| {
582 asked_for.extend_from_slice(addresses);
583 AddressMap::default()
584 },
585 );
586
587 assert_eq!(asked_for, [fresh]);
589 assert_eq!(resolved.keys().copied().collect::<Vec<_>>(), [cached]);
590 assert_eq!(resolved[&cached].0, "Counter");
591 }
592
593 #[test]
594 fn remembers_a_conclusive_miss_for_the_rest_of_the_run() {
595 let cache_dir = tempfile::tempdir().unwrap();
596 let chain_id = next_chain_id();
597 let address = Address::with_last_byte(1);
598
599 let mut lookups = 0;
600 let mut unverified = |addresses: &[Address], _: Duration| {
601 lookups += 1;
602 addresses.iter().map(|address| (*address, None)).collect::<AddressMap<_>>()
603 };
604
605 assert!(
606 resolve(
607 chain_id,
608 Some(cache_dir.path()),
609 [address],
610 Duration::from_secs(1),
611 &mut unverified,
612 )
613 .is_empty()
614 );
615 assert!(
616 resolve(
617 chain_id,
618 Some(cache_dir.path()),
619 [address],
620 Duration::from_secs(1),
621 &mut unverified,
622 )
623 .is_empty()
624 );
625 assert_eq!(lookups, 1, "an unverified contract should only be looked up once");
626 assert!(!cache_path(cache_dir.path(), address).exists());
627 }
628
629 #[test]
630 fn retries_an_address_the_lookup_reached_no_conclusion_about() {
631 let cache_dir = tempfile::tempdir().unwrap();
632 let chain_id = next_chain_id();
633 let address = Address::with_last_byte(1);
634
635 let mut lookups = 0;
637 let mut unavailable = |_: &[Address], _: Duration| {
638 lookups += 1;
639 AddressMap::default()
640 };
641
642 assert!(
643 resolve(
644 chain_id,
645 Some(cache_dir.path()),
646 [address],
647 Duration::from_secs(1),
648 &mut unavailable,
649 )
650 .is_empty()
651 );
652 assert!(
653 resolve(
654 chain_id,
655 Some(cache_dir.path()),
656 [address],
657 Duration::from_secs(1),
658 &mut unavailable,
659 )
660 .is_empty()
661 );
662 assert_eq!(lookups, 2, "an outage must not be remembered as \"no layout\"");
663 }
664
665 #[test]
666 fn waiting_for_an_inflight_lookup_respects_the_timeout() {
667 let chain_id = next_chain_id();
668 let address = Address::with_last_byte(1);
669 let slot = {
670 let mut lookups = LOOKUPS.lock().unwrap();
671 lookups.entry((chain_id, address)).or_default().clone()
672 };
673 let _inflight = slot.lock().unwrap();
674 let started = Instant::now();
675 let mut fetched = false;
676
677 let result = resolve(chain_id, None, [address], Duration::from_millis(20), |_, _| {
678 fetched = true;
679 AddressMap::default()
680 });
681
682 assert!(result.is_empty());
683 assert!(!fetched);
684 assert!(started.elapsed() < Duration::from_secs(1));
685 }
686
687 #[cfg(unix)]
688 #[test]
689 fn solc_is_killed_when_compilation_times_out() {
690 let dir = tempfile::tempdir().unwrap();
691 let path = dir.path().join("solc");
692 std::fs::write(&path, "#!/bin/sh\nexec sleep 10\n").unwrap();
693 std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o755)).unwrap();
694 let solc = Solc {
695 solc: path,
696 version: NO_IMPORT_CALLBACK_SOLC,
697 base_path: None,
698 allow_paths: Default::default(),
699 include_paths: Default::default(),
700 extra_args: Vec::new(),
701 };
702 let input = SolcInput::new(SolcLanguage::Solidity, Default::default(), Default::default());
703 let started = Instant::now();
704
705 assert!(
706 run_solc(&solc, &NO_IMPORT_CALLBACK_SOLC, &input, Duration::from_millis(20)).is_err()
707 );
708 assert!(started.elapsed() < Duration::from_secs(1));
709 }
710
711 #[cfg(unix)]
712 #[test]
713 fn solc_runs_in_an_empty_sandbox_with_imports_disabled() {
714 let dir = tempfile::tempdir().unwrap();
715 let path = dir.path().join("solc");
716 std::fs::write(
717 &path,
718 "#!/bin/sh\ncase \" $* \" in *\" --no-import-callback \"*) ;; *) exit 1;; esac\n[ -z \"$(ls -A)\" ] || exit 1\nprintf '{\"contracts\":{}}'\n",
719 )
720 .unwrap();
721 std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o755)).unwrap();
722 let solc = Solc {
723 solc: path,
724 version: NO_IMPORT_CALLBACK_SOLC,
725 base_path: None,
726 allow_paths: Default::default(),
727 include_paths: Default::default(),
728 extra_args: Vec::new(),
729 };
730 let input = SolcInput::new(SolcLanguage::Solidity, Default::default(), Default::default());
731
732 assert!(run_solc(&solc, &NO_IMPORT_CALLBACK_SOLC, &input, Duration::from_secs(1)).is_ok());
733 }
734
735 fn source_less_metadata() -> Metadata {
736 Metadata {
737 source_code: SourceCodeMetadata::Sources(Default::default()),
738 abi: "[]".to_string(),
739 contract_name: "MissingSources".to_string(),
740 compiler_version: "v0.8.30".to_string(),
741 optimization_used: 0,
742 runs: 0,
743 constructor_arguments: Default::default(),
744 evm_version: String::new(),
745 library: String::new(),
746 license_type: String::new(),
747 proxy: 0,
748 implementation: None,
749 swarm_source: String::new(),
750 }
751 }
752
753 #[test]
754 fn retries_after_the_compilation_budget_expires() {
755 let chain_id = next_chain_id();
756 let address = Address::with_last_byte(1);
757 let metadata = Metadata {
758 source_code: SourceCodeMetadata::SourceCode(
759 "pragma solidity ^0.8.30; contract Counter { uint256 public count; }".to_string(),
760 ),
761 contract_name: "Counter".to_string(),
762 ..source_less_metadata()
763 };
764 let _compiler = COMPILER.lock().unwrap();
766 let result =
767 resolve(chain_id, None, [address], Duration::from_millis(20), |_, remaining| {
768 std::thread::sleep(remaining);
769 [(address, Some(metadata))].into_iter().collect()
770 });
771 assert!(result.is_empty());
772
773 let mut retried = false;
774 resolve(chain_id, None, [address], Duration::from_secs(1), |addresses, _| {
775 assert_eq!(addresses, [address]);
776 retried = true;
777 AddressMap::default()
778 });
779 assert!(retried, "a compilation timeout must not be memoized as no layout");
780 }
781
782 #[test]
783 fn source_less_metadata_is_rejected_without_compiling() {
784 let metadata = source_less_metadata();
785 assert!(compile_storage_layout(Address::ZERO, &metadata, Instant::now()).is_none());
786 }
787}