testing.rpc_cache

Documentation for eth_defi.testing.rpc_cache Python module.

Seed the Foundry (Anvil) fork RPC cache from repository-supplied defaults.

Anvil persists every archive eth_call / eth_getStorageAt it replays to ~/.foundry/cache/rpc/<network>/<block>/ (see the “warm RPC cache” section of eth_defi.testing.anvil_fork_pool). CI restores that directory between runs, but on a genuinely cold cache — a first run, an evicted GitHub Actions cache, a fresh developer checkout — every fixed-block fork re-hammers the upstream archive, which is the dominant cause of the flaky-fork failures documented in docs/README-test-suite-performance.md.

This module lets the repository ship default cache files so a cold cache starts warm. The committed seed covers every fixed fork block the test suite uses — the canonical midnight blocks plus the per-test pinned blocks — because only a reproducible block is worth caching. Chains that must fork the chain tip (see NON_CACHEABLE_CHAIN_NETWORKS) are deliberately excluded. Committed seed files live under DEFAULT_SEED_DIR (mirroring Foundry’s <network>/<block>/… layout); an additional external seed directory can be supplied via the ETH_DEFI_RPC_CACHE_SEED_DIR environment variable (e.g. a large cache downloaded from durable storage). Seeding is non-destructive: an existing (warmer, more recent) cache file is never overwritten.

The seeding is wired into the session-scoped anvil_fork_pool setup in tests/conftest.py so it runs once per xdist worker before any fork launches.

Module Attributes

NON_CACHEABLE_CHAIN_NETWORKS	Chains whose fork tests cannot use a fixed historical block, so their fork cache must not be committed.
SEED_DIR_ENV_VAR	Environment variable naming an additional seed directory (same layout), applied after the repo default.
CACHE_DIR_ENV_VAR	Environment variable overriding the destination Foundry RPC cache directory (defaults to ~/.foundry/cache/rpc).

Functions

get_foundry_rpc_cache_dir()	Return the Foundry fork RPC cache directory.
seed_default_foundry_rpc_cache([cache_dir])	Seed the Foundry RPC cache from the repo default and env-supplied dirs.
seed_foundry_rpc_cache(seed_dir[, ...])	Copy repository-supplied cache files into the Foundry RPC cache.

DEFAULT_SEED_DIR: pathlib.Path = PosixPath('/home/runner/work/web3-ethereum-defi/web3-ethereum-defi/eth_defi/testing/rpc_cache_seed')

Repository-shipped default cache tree. Mirrors Foundry’s on-disk layout: <network-name>/<block>/storage.json (network name, not chain id). Ship dense caches for every fixed fork block the suite uses. See the README.md in this directory for how to capture them.

NON_CACHEABLE_CHAIN_NETWORKS: frozenset[str] = frozenset({'monad'})

Chains whose fork tests cannot use a fixed historical block, so their fork cache must not be committed. Monad provides no archive-complete historical state, so its tests fork the chain tip: the block number differs on every run, a committed cache entry would never be hit again, and it would grow the repository for nothing. See the Monad chain-quirk notes in CLAUDE.md.

SEED_DIR_ENV_VAR: str = 'ETH_DEFI_RPC_CACHE_SEED_DIR'

Environment variable naming an additional seed directory (same layout), applied after the repo default. Use for a large cache kept outside git.

CACHE_DIR_ENV_VAR: str = 'FOUNDRY_RPC_CACHE_DIR'

Environment variable overriding the destination Foundry RPC cache directory (defaults to ~/.foundry/cache/rpc). Primarily for tests.

get_foundry_rpc_cache_dir()

Return the Foundry fork RPC cache directory.

Returns

$FOUNDRY_RPC_CACHE_DIR if set, otherwise ~/.foundry/cache/rpc.

Return type

pathlib.Path

seed_foundry_rpc_cache(seed_dir, cache_dir=None, *, overwrite=False)

Copy repository-supplied cache files into the Foundry RPC cache.

Mirrors every file under seed_dir into cache_dir preserving the relative <network>/<block>/… layout. Non-destructive by default: a file that already exists in the live cache is skipped, because the live copy is at least as fresh (a fork may have extended it with more state). Nothing is ever deleted from the live cache.

Parameters

• seed_dir (pathlib.Path) – Source directory of committed/default cache files. A missing directory is a no-op (returns 0).

• cache_dir (Optional[pathlib.Path]) – Destination Foundry RPC cache directory. Defaults to get_foundry_rpc_cache_dir().

• overwrite (bool) – When True, replace existing live cache files too. Default False (never clobber a warmer live cache).

Returns

Number of files copied into the live cache.

Return type

int

seed_default_foundry_rpc_cache(cache_dir=None)

Seed the Foundry RPC cache from the repo default and env-supplied dirs.

Applies DEFAULT_SEED_DIR first, then any directory named by $ETH_DEFI_RPC_CACHE_SEED_DIR. Both are optional; a missing directory is silently skipped. Safe to call once per test session per xdist worker.

Parameters

cache_dir (Optional[pathlib.Path]) – Destination cache directory. Defaults to get_foundry_rpc_cache_dir().

Returns

Total number of files copied across all seed directories.

Return type

int