testing.token_cache

Documentation for eth_defi.testing.token_cache Python module.

Ship a prebuilt ERC-20 / vault token cache so tests do not refetch it over RPC.

Vault token lookups are cached at two levels, and both only engage when the vault’s ``token_cache`` is a :py:class:`~eth_defi.token.TokenDiskCache`:

the vault → denomination / share token address resolution (eth_defi.erc_4626.vault_token), gated on isinstance(self.token_cache, TokenDiskCache) in eth_defi.erc_4626.vault;
the ERC-20 token metadata (name / symbol / decimals / supply) read by eth_defi.token.fetch_erc20_details().

The default cache — eth_defi.token.DEFAULT_TOKEN_CACHE — is an in-memory cachetools.LRUCache. It therefore (a) silently disables the address-resolution cache entirely, and (b) starts empty in every new process, and pytest runs many (one per pytest-xdist worker). Vaults consequently re-read token addresses and metadata over RPC on every cold fork, sequentially, per worker. On a throttled CI provider each of those reads can stall — the same failure mode documented in eth_defi.testing.anvil_fork_pool.

This module ships that data in the repository as a small SQLite TokenDiskCache (TOKEN_CACHE_SEED_PATH) and installs it as the default vault token cache for the test session, so both cache levels engage and start warm.

Rebuilding the shipped cache

The seed is regenerated from a real run rather than hand-maintained. Set ETH_DEFI_TOKEN_CACHE_REBUILD=1 and run the tests you want covered; every token resolved during the run is merged back into the seed at session end:

source .local-test.env &&         ETH_DEFI_TOKEN_CACHE_REBUILD=1         poetry run pytest tests/erc_4626/vault_protocol/ -m "not slow"
git add eth_defi/testing/token_cache_seed/

See eth_defi/testing/README.md for the create / update / purge process, and eth_defi.testing.rpc_cache for the sibling Anvil fork-state seed.

Module Attributes

`REBUILD_ENV_VAR`	When truthy, tokens resolved during the session are merged back into `TOKEN_CACHE_SEED_PATH` at session end.
`DISABLE_ENV_VAR`	When truthy, skip installing the shipped cache (e.g.

Functions

`install_token_cache`([worker_id])	Install the shipped token cache as the default for vaults in this session.
`is_token_cache_rebuild_requested`()	Check whether the shipped token cache should be regenerated.
`is_token_cache_seeding_disabled`()	Check whether the caller asked to skip token cache seeding.
`merge_into_token_cache_seed`(cache[, seed_path])	Merge tokens resolved during the session back into the shipped seed.

TOKEN_CACHE_SEED_PATH: pathlib.Path = PosixPath('/home/runner/work/web3-ethereum-defi/web3-ethereum-defi/eth_defi/testing/token_cache_seed/tokens.sqlite'): Committed SQLite token cache shipped with the repository.

REBUILD_ENV_VAR: str = 'ETH_DEFI_TOKEN_CACHE_REBUILD': When truthy, tokens resolved during the session are merged back into TOKEN_CACHE_SEED_PATH at session end.

DISABLE_ENV_VAR: str = 'ETH_DEFI_TOKEN_CACHE_DISABLE': When truthy, skip installing the shipped cache (e.g. to measure cold behaviour).

is_token_cache_seeding_disabled()

Check whether the caller asked to skip token cache seeding.

Returns: True when $ETH_DEFI_TOKEN_CACHE_DISABLE is truthy.
Return type: bool

is_token_cache_rebuild_requested()

Check whether the shipped token cache should be regenerated.

Returns: True when $ETH_DEFI_TOKEN_CACHE_REBUILD is truthy.
Return type: bool

install_token_cache(worker_id='master')

Install the shipped token cache as the default for vaults in this session.

Copies TOKEN_CACHE_SEED_PATH to a private per-worker working file (so concurrent pytest-xdist workers never contend on one SQLite file and the committed seed is never mutated in place), opens it as a TokenDiskCache, and points eth_defi.vault.base.DEFAULT_TOKEN_CACHE at it. Every vault constructed without an explicit token_cache then uses the disk cache, which is what enables the address-resolution cache as well as the metadata cache.

Parameters: worker_id (str) – pytest-xdist worker id, used to keep working files separate.
Returns: The installed cache. When no seed is committed yet this is an empty cache, so a rebuild run can still fill it.
Return type: eth_defi.token.TokenDiskCache

merge_into_token_cache_seed(cache, seed_path=PosixPath('/home/runner/work/web3-ethereum-defi/web3-ethereum-defi/eth_defi/testing/token_cache_seed/tokens.sqlite'))

Merge tokens resolved during the session back into the shipped seed.

Used by the rebuild flow so the committed seed is regenerated from a real test run instead of being hand-maintained. Existing seed entries are preserved; only new keys are added.

Parameters

cache (eth_defi.token.TokenDiskCache) – Session cache to read (as returned by install_token_cache()).
seed_path (pathlib.Path) – Committed SQLite cache to update. Created if missing.

Returns

Number of new entries written to the seed file.

Return type

int