Module external_storage 

Storage layouts for contracts that are not part of the local project.

When a forked test touches a contract that isn’t in the local artifacts, its storage slots can still be decoded by compiling the verified source a block explorer has for it.

Finding that source is the caller’s job — foundry-evm-traces already knows how to ask a block explorer for it. This module owns what happens next: compiling it for a storage layout, which costs a full solc invocation, and making sure that cost is paid once. forge test runs test contracts in parallel, so lookups are:

• deduplicated process-wide by LOOKUPS, so concurrent tests touching the same contract compile it once instead of racing each other;
• persisted to disk once resolved, so later runs skip straight to the layout.

Unverified responses are memoized only for this run so later runs can discover newly verified contracts.

Re-exports

use crate::fs; 🔒

use crate::namespaced_storage; 🔒

use alloy_chains::Chain; 🔒

use alloy_primitives::Address; 🔒

use alloy_primitives::map::AddressMap; 🔒

use foundry_block_explorers::contract::Metadata; 🔒

use foundry_compilers::artifacts::CompilerOutput; 🔒

use foundry_compilers::artifacts::SolcInput; 🔒

use foundry_compilers::artifacts::SolcLanguage; 🔒

use foundry_compilers::artifacts::Source; 🔒

use foundry_compilers::artifacts::Sources; 🔒

use foundry_compilers::artifacts::StorageLayout; 🔒

use foundry_compilers::artifacts::output_selection::OutputSelection; 🔒

use foundry_compilers::solc::Solc; 🔒

use foundry_config::Config; 🔒

use serde::Deserialize; 🔒

use serde::Deserialize; 🔒

use serde::Serialize; 🔒

use serde::Serialize; 🔒

use std::io::Read; 🔒

use std::io::Seek; 🔒

use std::io::SeekFrom; 🔒

use std::path::Path; 🔒

use std::path::PathBuf; 🔒

use std::process::Command; 🔒

use std::process::Stdio; 🔒

use std::sync::Arc; 🔒

use std::sync::LazyLock; 🔒

use std::sync::Mutex; 🔒

use std::sync::MutexGuard; 🔒

use std::sync::TryLockError; 🔒

use std::sync::atomic::AtomicU64; 🔒

use std::sync::atomic::Ordering; 🔒

use std::time::Duration; 🔒

use std::time::Instant; 🔒

use wait_timeout::ChildExt; 🔒

Structs

CachedStorageLayout 🔒

Disk representation of a resolved lookup. Cleared by forge cache clean.

Constants

BASE_PATH_SOLC 🔒

First solc release with --base-path support.

CACHE_VERSION 🔒

Current CachedStorageLayout format.

MIN_STORAGE_LAYOUT_SOLC 🔒

First solc release that emits storageLayout. Matches the floor cast storage enforces.

NO_IMPORT_CALLBACK_SOLC 🔒

First solc release with --no-import-callback support.

Statics

CACHE_TEMP_ID 🔒

Makes cache publication paths unique within one process; the PID separates processes.

COMPILER 🔒

Bounds expensive compiler installation and execution across parallel tests.

LOOKUPS 🔒

Per-(chain, address) lookup slots, shared across the whole process.

Functions

cache_path 🔒

Path of the cache entry for address.

compile_storage_layout 🔒

Compiles a verified source with storageLayout output enabled and extracts the layout.

extend_external_storage_layout 🔒

Appends the ERC-7201 namespaces of contract name in source path to its solc layout.

fetch_external_storage_layouts

Resolves the storage layouts of addresses on chain, compiling verified sources as needed.

lock_until

Acquires a lock without exceeding the caller’s deadline.

read_cached_layout 🔒

Reads the layout a previous run resolved for address, if there is one.

resolve 🔒

fetch_external_storage_layouts with the cache location supplied, so tests can point it somewhere other than the user’s home directory.

run_solc 🔒

Runs solc in an empty directory and terminates it if the remaining lookup budget expires.

write_cached_layout 🔒

Persists a resolved layout so later runs can skip the fetch and the compile.

Type Aliases

ExternalStorageLayout 🔒

A resolved storage layout, or None if the contract has no layout we can use.

LookupSlot 🔒

A single address’ lookup slot: None until the lookup completes, then its memoized result.