erc_4626.deposit_probe

Documentation for eth_defi.erc_4626.deposit_probe Python module.

Anvil-only guarded vault-deposit probe.

The probe is intentionally an operator tool: it certifies a manager-generated deposit request from SimpleVaultV0 through its GuardV0. It never uses a private key supplied by an operator and never targets an upstream RPC endpoint.

Large all-protocol runs are intentionally long-lived: each candidate deploys and exercises contracts on a fresh Anvil fork. Interactive runners must run bounded protocol batches and resume from the durable status file, rather than imposing one short wall-clock timeout on the complete sweep.

Module Attributes

PROBE_EXECUTION_EXCEPTIONS

Expected Anvil, RPC, and contract errors from an individual probe attempt.

Functions

`fetch_max_deposit_guidance`(vault)	Read the ERC-4626 `maxDeposit` response for operator guidance only.
`log_probe_tables`(rows)	Log per-vault outcomes and aggregate outcome counts as tables.
`probe_candidate`(web3, candidate, amount, ...)	Run one guarded deposit attempt on an already verified Anvil fork.
`require_simulation`()	Require explicit acknowledgement before creating an Anvil fork.
`run_from_environment`()	Run the guarded Anvil probe configured through environment variables.
`select_candidates`(database, *, selection[, ...])	Select database candidates with deterministic order and fail-closed metadata.
`update_status`(path, key, result)	Atomically store one durable, hash-free probe result in local state.

Classes

`VaultDepositProbeCandidate`	One database vault selected for a guarded deposit attempt.
`VaultDepositProbeOutput`	One human-readable result row for a completed or skipped probe.

Exceptions

AnvilProbeTransactionError

Anvil mined a probe transaction with a failing status.

DEFAULT_STATUS_PATH = PosixPath('/home/runner/work/web3-ethereum-defi/web3-ethereum-defi/eth_defi/data/deposit-status/vault-deposit-status.json'): Version-controlled package artefact refreshed by the guarded Anvil probe.

PROBE_EXECUTION_EXCEPTIONS = (<class 'ConnectionError'>, <class 'RuntimeError'>, <class 'TimeoutError'>, <class 'requests.exceptions.RequestException'>, <class 'ValueError'>, <class 'web3.exceptions.BadFunctionCallOutput'>, <class 'web3.exceptions.ContractLogicError'>, <class 'web3.exceptions.TimeExhausted'>, <class 'web3.exceptions.TransactionNotFound'>, <class 'web3.exceptions.Web3Exception'>): Expected Anvil, RPC, and contract errors from an individual probe attempt.

exception AnvilProbeTransactionError

Bases: RuntimeError

Anvil mined a probe transaction with a failing status.

__init__(*args, **kwargs)

__new__(**kwargs)

add_note(note, /): Add a note to the exception

with_traceback(tb, /): Set self.__traceback__ to tb and return self.

class VaultDepositProbeCandidate

Bases: object

One database vault selected for a guarded deposit attempt.

property key: str

Return canonical persistent-state key.

The key prevents checksum casing differences from creating duplicate status records for the same chain and vault.

Returns: <chain_id>-<lowercase_address> status key.

property denomination_token_label: str

Return a compact human-readable denomination-token identifier.

Returns: Scanned denomination symbol followed by its checksummed address.

__init__(spec, row, denomination_token_address)

Parameters

spec (eth_defi.vault.base.VaultSpec) –
row (eth_defi.vault.vaultdb.VaultRow) –
denomination_token_address (eth_typing.evm.HexAddress) –

Return type

None

class VaultDepositProbeOutput

Bases: object

One human-readable result row for a completed or skipped probe.

protocol: str: Scanner protocol name.

address: Union[eth_typing.evm.HexAddress, str]: Vault contract address.

name: str: Scanner vault name.

denomination_token: str: Symbol and address of the denomination token.

outcome: str: Probe outcome used for summary statistics.

status: str: Concise result shown in the detailed table.

max_deposit_guidance: str: Informational maxDeposit(address(0)) response, never a decision input.

failure_reason: Optional[str]: Failure detail, absent for successful probes.

revert_reason: Optional[str]: Raw Anvil exception text for reverted execution.

__init__(protocol, address, name, denomination_token, outcome, status, max_deposit_guidance, failure_reason, revert_reason)

Parameters

protocol (str) –
address (Union[eth_typing.evm.HexAddress, str]) –
name (str) –
denomination_token (str) –
outcome (str) –
status (str) –
max_deposit_guidance (str) –
failure_reason (Optional[str]) –
revert_reason (Optional[str]) –

Return type

None

require_simulation()

Require explicit acknowledgement before creating an Anvil fork.

The flag is an operator-intent gate only; provider identity is separately checked immediately before any transaction is signed.

Raises: AnvilProbeTransactionError – If SIMULATE is not exactly true.
Return type: None

select_candidates(database, *, selection, min_tvl=None, denomination_token=None, protocol=None, vault_ids=None, chain_id=None, include_uncertified=False, max_per_protocol=None)

Select database candidates with deterministic order and fail-closed metadata.

min_tvl compares the scanner’s USD NAV values. A denomination token may optionally narrow that selection further.

Parameters

database (eth_defi.vault.vaultdb.VaultDatabase) – Local scanner metadata database.
selection (str) – One of min_tvl, protocol, all_protocols or vault_ids.
min_tvl (Optional[decimal.Decimal]) – Minimum USD NAV for min_tvl selection.
denomination_token (Optional[eth_typing.evm.HexAddress]) – Optional denomination-token filter for min_tvl selection.
protocol (Optional[str]) – Case-insensitive protocol name for protocol selection.
vault_ids (Optional[str]) – Comma-separated vault identifiers for explicit selection.
chain_id (Optional[int]) – Optional EVM chain filter applied to every selection mode.
include_uncertified (bool) – Include legacy database rows without scanner capability metadata. Their adapter capability is still recomputed and enforced on the Anvil fork.
max_per_protocol (Optional[int]) – Optional highest-N NAV limit applied independently in all_protocols mode.

Returns

Deterministically ordered, deposit-capable EVM candidates.

Raises

ValueError – If selection mode requirements are not met.

Return type

list[eth_defi.erc_4626.deposit_probe.VaultDepositProbeCandidate]

update_status(path, key, result)

Atomically store one durable, hash-free probe result in local state.

Re-reading under the lock preserves concurrent writers. Current-attempt fields are rebuilt from result so evidence from an older attempt cannot leak into a later failure or success.

Parameters

path (pathlib.Path) – Status-file destination.
key (str) – Canonical vault key.
result (dict[str, object]) – Current attempt result without fork-local transaction identifiers.

Raises

ValueError – If a successful result does not identify a positive integer fork block.

Return type

None

log_probe_tables(rows)

Log per-vault outcomes and aggregate outcome counts as tables.

The detailed table is emitted after results are persisted, allowing an operator to compare terminal output with the durable local status file.

Parameters: rows (list[eth_defi.erc_4626.deposit_probe.VaultDepositProbeOutput]) – Completed or skipped vault-probe rows.
Returns: None after logging both human-readable tables at info level.
Return type: None

fetch_max_deposit_guidance(vault)

Read the ERC-4626 maxDeposit response for operator guidance only.

ERC-4626 permits conservative underestimates. In particular, Morpho V2 always returns zero because its external gates are address-dependent. The guarded deposit transaction, rather than this advisory call, decides whether the vault accepts a SimpleVaultV0 deposit.

Parameters: vault (eth_defi.erc_4626.vault.ERC4626Vault) – Constructed ERC-4626 reader whose standard contract accessor is queried.
Returns: Raw maxDeposit(address(0)) result as text, or a concise unavailable marker when the optional accessor cannot be read.
Return type: str

probe_candidate(web3, candidate, amount, fork_block_number)

Run one guarded deposit attempt on an already verified Anvil fork.

Returned data is safe to persist. Ephemeral Anvil transaction hashes are deliberately excluded.

Parameters

web3 (web3.main.Web3) – Verified Anvil fork provider.
candidate (eth_defi.erc_4626.deposit_probe.VaultDepositProbeCandidate) – Selected local database vault.
amount (decimal.Decimal) – Human-readable denomination-token deposit amount.
fork_block_number (Optional[int]) – Upstream block at which the fork started.

Returns

Hash-free status result for persistent local state.

Return type

dict[str, object]

run_from_environment()

Run the guarded Anvil probe configured through environment variables.

Candidate selection comes from the local vault database. The function launches one isolated fork per vault and stores the durable result after each attempt. A fresh process prevents one blocked upstream state read from contaminating later candidates. All-protocol runs can take a long time; interactive callers should invoke bounded protocol batches and resume using the status file instead of terminating the complete sweep early.

Returns

Process exit status 0 after all selected chain batches finish.

Raises

RuntimeError – If simulation confirmation, provider validation, or snapshot recovery fails.
ValueError – If required environment configuration is malformed or absent.

Return type

int