erc_4626.vault

Documentation for eth_defi.erc_4626.vault Python module.

Generic ECR-4626 vault reader implementation.

Module Attributes

`CERTIFIED_SYNCHRONOUS_DEPOSIT_MANAGER_CLASSES`	Protocol reader classes whose guarded fork probes completed a deposit using their implemented deposit manager.
`KNOWN_SHARE_TOKEN_ERROR_MESSAGES`	Known error messages that indicate that share() accessor function is not accessible and contract is ERC-4626, not ERC-7540.

Classes

`ERC4626HistoricalReader`	A reader that reads the historcal state of one specific vaults.
`ERC4626Vault`	ERC-4626 vault adapter
`ERC4626VaultInfo`	Capture information about ERC- vault deployment.
`VaultReaderState`	Adaptive reading frequency for vaults.

UNKNOWN_EXCHANGE_RATE = Decimal('0.9899999999999999911182158029987476766109466552734375'): The exchange rate we use for all unknown denomination tokens

CERTIFIED_SYNCHRONOUS_DEPOSIT_MANAGER_CLASSES = frozenset({'eth_defi.erc_4626.vault_protocol.autopool.vault.AutoPoolVault', 'eth_defi.erc_4626.vault_protocol.dolomite.vault.DolomiteVault', 'eth_defi.erc_4626.vault_protocol.euler.vault.EulerEarnVault', 'eth_defi.erc_4626.vault_protocol.euler.vault.EulerVault', 'eth_defi.erc_4626.vault_protocol.fluid.vault.FluidVault', 'eth_defi.erc_4626.vault_protocol.gearbox.vault.GearboxVault', 'eth_defi.erc_4626.vault_protocol.goat.vault.GoatVault', 'eth_defi.erc_4626.vault_protocol.ipor.vault.IPORVault', 'eth_defi.erc_4626.vault_protocol.kiln.vault.KilnVault', 'eth_defi.erc_4626.vault_protocol.morpho.vault_v1.MorphoV1Vault', 'eth_defi.erc_4626.vault_protocol.morpho.vault_v2.MorphoV2Vault', 'eth_defi.erc_4626.vault_protocol.plutus.vault.PlutusVault', 'eth_defi.erc_4626.vault_protocol.royco.vault.RoycoVault', 'eth_defi.erc_4626.vault_protocol.silo.vault.SiloVault', 'eth_defi.erc_4626.vault_protocol.summer.vault.SummerVault', 'eth_defi.erc_4626.vault_protocol.superform.vault.SuperformVault', 'eth_defi.erc_4626.vault_protocol.usdx_money.vault.USDXMoneyVault', 'eth_defi.erc_4626.vault_protocol.yearn.vault.YearnV3Vault', 'eth_defi.erc_4626.vault_protocol.yo.vault.YoVault'})

Protocol reader classes whose guarded fork probes completed a deposit using their implemented deposit manager.

The exact-class rule is intentional: a specialised subclass must be separately certified instead of inheriting public transaction support.

KNOWN_SHARE_TOKEN_ERROR_MESSAGES = frozenset({'Bad Request', 'Execution reverted', 'InvalidTransaction', 'VM execution error', 'execution reverted', 'out of gas'}): Known error messages that indicate that share() accessor function is not accessible and contract is ERC-4626, not ERC-7540. Because all EVM clones have different behavior on execution reverted, this is a bit of a shitshow.

class ERC4626VaultInfo

Bases: eth_defi.vault.base.VaultInfo

Capture information about ERC- vault deployment.

address: eth_typing.evm.HexAddress: The ERC-20 token that nominates the vault assets

asset: Optional[eth_typing.evm.HexAddress]

The address of the underlying token used for the vault for accounting, depositing, withdrawing.

Some broken vaults do not expose this, and may be None. e.g. https://arbiscan.io/address/0x9d0fbc852deccb7dcdd6cb224fa7561efda74411#code

E.g. USDC.

__init__(*args, **kwargs)

__new__(**kwargs)

clear(): Remove all items from the dict.

copy(): Return a shallow copy of the dict.

fromkeys(value=None, /): Create a new dictionary with keys from iterable and values set to value.

get(key, default=None, /): Return the value for key if key is in the dictionary, else default.

items(): Return a set-like object providing a view on the dict’s items.

keys(): Return a set-like object providing a view on the dict’s keys.

pop(k[, d]) → v, remove specified key and return the corresponding value.: If the key is not found, return the default if given; otherwise, raise a KeyError.

popitem()

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

setdefault(key, default=None, /)

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

update([E, ]**F) → None. Update D from mapping/iterable E and F.: If E is present and has a .keys() method, then does: for k in E.keys(): D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values(): Return an object providing a view on the dict’s values.

VaultPollFrequency

What is the reason how often we poll this

alias of Literal[‘peaked’, ‘faded’, ‘large_tvl’, ‘small_tvl’, ‘tiny_tvl’, ‘first_read’, ‘not_started’, ‘early’]

class VaultReaderState

Bases: eth_defi.event_reader.multicall_batcher.BatchCallState

Adaptive reading frequency for vaults.

This class maintains the per-vault state of reading between different eth_call reads over time
Most vaults are uninteresting, but we do not know ahead of time which ones
We need 1h data for interesting vaults to make good trade decisions
We switch to 1h scanning if the TVL is above a threshold, otherwise we read it once per day

Note

Due to filtering, only handles stablecoin vaults correctly at the moment. Lacks exchange rate support.

Parameters

vault – The vault we are reading historical data for
tvl_threshold_1d_read – If the TVL is below this threshold, we will not read it more than once per day, otherwise hourly.
down_hard – Stop reading the vault if the TVL is down by this percentage from the peak.
min_tvl_threshold – If the vault never reaches this TVL, we stop reading it after the traction period.
traction_period – How long we wait for the vault to get traction before we stop reading it.

Parm peaked_tvl_threshold

The TVL value we first need to reach to trigger down hard condition.

SERIALISABLE_ATTRIBUTES = ('last_tvl', 'last_share_price', 'max_tvl', 'first_seen_at_block', 'first_block', 'first_read_at', 'last_call_at', 'last_block', 'peaked_at', 'peaked_tvl', 'faded_at', 'entry_count', 'chain_id', 'vault_address', 'denomination_token_address', 'share_token_address', 'one_raw_share', 'reading_restarted_count', 'vault_poll_frequency', 'token_symbol', 'unsupported_token', 'invoke_count_passed', 'invoke_count_first_read', 'invoke_count_missing_freq', 'invoke_count_throttled', 'write_filtered', 'write_done', 'rpc_error_count', 'last_rpc_error', 'call_status'): All attributes we store when we serialise the read state between runs

__init__(vault, tvl_threshold_1d_read=Decimal('10000'), tiny_tvl_threshold_rare_read=Decimal('1000'), peaked_tvl_threshold=Decimal('200000'), min_tvl_threshold=Decimal('1500'), down_hard=0.98, traction_period=datetime.timedelta(days=60))

Parameters

vault (eth_defi.erc_4626.vault.ERC4626Vault) – The vault we are reading historical data for
tvl_threshold_1d_read – If the TVL is below this threshold, we will not read it more than once per day, otherwise hourly.
down_hard – Stop reading the vault if the TVL is down by this percentage from the peak.
min_tvl_threshold – If the vault never reaches this TVL, we stop reading it after the traction period.
traction_period (datetime.timedelta) – How long we wait for the vault to get traction before we stop reading it.

Parm peaked_tvl_threshold

The TVL value we first need to reach to trigger down hard condition.

first_seen_at_block: Passed from the vault discovery reader, pass the block number as args when we know this vault popped in to the existing

last_tvl: decimal.Decimal: TVL from the last read

first_read_at: datetime.datetime: Timestamp of the block of the first successful read of this vault.

max_tvl: decimal.Decimal: Start with zero TVL

last_share_price: decimal.Decimal: Start with zero share price

last_call_at: Optional[datetime.datetime]: When this vault received its last eth_call update

last_block: Optional[int]: When this vault received its last eth_call update

peaked_at: datetime.datetime: Disable reading if the vault has peaked (TVL too much down) and is no longer active

peaked_tvl: float: What was TVL when we disabled reading due to peaking

faded_at: datetime.datetime: Disable reading if the vault has never gotten any traction

traction_period: How much time after deployment we allow to get traction

min_tvl_threshold: Minimum TVL traction threshold to start reading the vault

tiny_tvl_threshold_rare_read: Vaults we do no really care about

entry_count: How many on_called() invocations have we had

invoke_count_passed: How many should_invoke() invocations have we had

invoke_count_first_read: How many should_invoke() invocations have we had

invoke_count_missing_freq: How many should_invoke() invocations have we had

invoke_count_throttled: How many should_invoke() invocations have we had

rpc_error_count: Track RPCc errors

denomination_token_address: Cache denomination token address when preparing readers

share_token_address: Cache share token address when preparing readers

one_raw_share: One share in its raw units

one: Cache denomination token address when preparing readers

chain_id: Copy for state debuggin

vault_poll_frequency: Cache for how often we are polling this vault, the mode name

token_symbol: Cache for debuggin

unsupported_token: Cache for debuggin

call_status: dict[str, tuple[int, bool]]: Map of function names to their call status for warmup system Key is the function name from extra_data[“function”] Value is tuple (check_block: int, reverts: bool) Example: {“maxDeposit”: (12345678, True)} means maxDeposit reverts, detected at block 12345678

save()

Persist state across multiple runs.

Returns: Pickleable Python object
Return type: dict

load(data)

Load the state from a dictionary.

Parameters: data (dict) –

should_skip_call(function_name)

Check if a specific function call should be skipped for this vault.

Part of the warmup system to detect and skip broken contract calls. See README-reader-states.md for documentation.

Parameters: function_name (str) – The function name as stored in extra_data[“function”]
Returns: True if the call was marked as reverting
Return type: bool

get_call_status(function_name)

Get the status of a function call.

Parameters: function_name (str) – The function name to check
Returns: Tuple of (check_block, reverts) or None if not checked yet
Return type: Optional[tuple[int, bool]]

set_call_status(function_name, check_block, reverts)

Record the status of a function call.

Parameters

function_name (str) – The function name to record
check_block (int) – The block number when we checked
reverts (bool) – True if the call reverted

Return type

None

get_broken_calls()

Get all calls marked as broken.

Returns: Dict of function_name -> check_block for broken calls
Return type: dict[str, int]

property exchange_rate: decimal.Decimal: Get the exchange rate for TVL estimation

should_invoke(call, block_identifier, timestamp)

Check the condition if this multicall is good to go.

Parameters

call (eth_defi.event_reader.multicall_batcher.EncodedCall) –
block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, hexbytes.main.HexBytes, int]) –
timestamp (datetime.datetime) –

Return type

bool

get_frequency()

How fast we are reading this vault or should the further reading be skipped.

Return type: tuple[Literal[‘peaked’, ‘faded’, ‘large_tvl’, ‘small_tvl’, ‘tiny_tvl’, ‘first_read’, ‘not_started’, ‘early’], datetime.timedelta | None]

on_called(result, total_assets=None, share_price=None)

Parameters

result (eth_defi.event_reader.multicall_batcher.EncodedCallResult) – Result of convertToAssets() call
total_assets (Optional[decimal.Decimal]) –
share_price (Optional[decimal.Decimal]) –

on_unpriced_call(result)

Update adaptive scan state for a successful supply-only read.

Some tokenised funds expose their share supply but no reviewed scalar NAV or TVL. They still need persistent reader state so the stateful scanner can cache token metadata, advance its last-read block and throttle historical calls. Zero values are internal scheduling sentinels only; the exported historical row must continue to expose None for its share price and total assets.

Parameters: result (eth_defi.event_reader.multicall_batcher.EncodedCallResult) – Successful supply call carrying a block number and timestamp.
Return type: None

pformat()

Pretty print the current state.

Return type: str

class ERC4626HistoricalReader

Bases: eth_defi.vault.base.VaultHistoricalReader

A reader that reads the historcal state of one specific vaults.

Generate a list of multicall instances that is needed to capture the vault state in a specific block height
All calls share the same state object which we use to track disabling reads for inactive vaults
Share price (returns), supply, NAV
For performance fees etc. there are no standards so you need to subclass this for each protocol
All calls for this reader share the same

__init__(vault, stateful)

Parameters

vault (eth_defi.erc_4626.vault.ERC4626Vault) –
stateful (bool) –

get_warmup_calls()

Yield (function_name, callable, contract_call) tuples for warmup testing.

Each callable should execute a single contract call. If it raises, the function is marked as broken.

The optional contract_call is used for gas estimation to detect expensive calls before executing them. If provided, calls using excessive gas (>1M gas) will be marked as broken without execution.

Override in subclasses to add protocol-specific calls.

Returns: Iterable of (function_name, test_callable, contract_call) tuples. contract_call may be None if gas estimation is not needed.
Return type: Iterable[tuple[str, callable, Any]]

should_skip_call(function_name)

Check if a specific function call should be skipped.

Uses the reader state’s call_status map if available.

Parameters: function_name (str) – The function name to check
Returns: True if the call should be skipped
Return type: bool

construct_multicalls()

Get the onchain calls that are needed to read the share price.

Return type: Iterable[eth_defi.event_reader.multicall_batcher.EncodedCall]

construct_core_erc_4626_multicall()

Polling endpoints defined in ERC-4626 spec.

Does not include fee calls which do not have standard

Return type: Iterable[eth_defi.event_reader.multicall_batcher.EncodedCall]

process_core_erc_4626_result(call_by_name)

Decode common ERC-4626 calls.

Parameters: call_by_name (dict[str, eth_defi.event_reader.multicall_batcher.EncodedCallResult]) –
Return type: tuple

dictify_multicall_results(block_number, call_results, allow_failure=True)

Convert batch of multicalls made for this vault to more digestible dict.

Assert that all multicalls succeed

Returns

Dictionary where each multicall is keyed by its EncodedCall.extra_data["function"]

Parameters

block_number (int) –
call_results (list[eth_defi.event_reader.multicall_batcher.EncodedCallResult]) –

Return type

dict[str, eth_defi.event_reader.multicall_batcher.EncodedCallResult]

process_result(block_number, timestamp, call_results)

Process the result of mult

Calls are created in construct_multicalls()
This method combines result of this calls to a easy to manage historical record VaultHistoricalRead

Parameters

block_number (int) –
timestamp (datetime.datetime) –
call_results (list[eth_defi.event_reader.multicall_batcher.EncodedCallResult]) –

Return type

eth_defi.vault.base.VaultHistoricalRead

class ERC4626Vault

Bases: eth_defi.vault.base.VaultBase

ERC-4626 vault adapter

Handle vault operations:

Metadata
Deposit and redeem from the vault
Vault historical price reader
Also partial support for ERC-7575 extensions

More info:

Parameters

web3 – Connection we bind this instance to
spec – Chain, address tuple
token_cache –
Cache used with fetch_erc20_details() to avoid multiple calls to the same token.

Reduces the number of RPC calls when scanning multiple vaults.
features – Pass vault feature flags along, externally detected.
default_block_identifier –
Override block identifier for on-chain metadata reads.

When None, use get_safe_cached_latest_block_number() (the default, safe for broken RPCs). Set to "latest" for freshly deployed vaults whose contracts do not exist at the safe-cached block.
require_denomination_token – If True, accessing denomination_token will raise RuntimeError when the on-chain lookup returns None.

__init__(web3, spec, token_cache=None, features=None, default_block_identifier=None, require_denomination_token=False)

Parameters

web3 (web3.main.Web3) – Connection we bind this instance to
spec (eth_defi.vault.base.VaultSpec) – Chain, address tuple
token_cache (Optional[dict]) –
Cache used with fetch_erc20_details() to avoid multiple calls to the same token.

Reduces the number of RPC calls when scanning multiple vaults.
features (Optional[set[eth_defi.erc_4626.core.ERC4626Feature]]) – Pass vault feature flags along, externally detected.
default_block_identifier (Optional[Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, hexbytes.main.HexBytes, int]]) –
Override block identifier for on-chain metadata reads.

When None, use get_safe_cached_latest_block_number() (the default, safe for broken RPCs). Set to "latest" for freshly deployed vaults whose contracts do not exist at the safe-cached block.
require_denomination_token (bool) – If True, accessing denomination_token will raise RuntimeError when the on-chain lookup returns None.

is_valid()

Check if this vault is valid.

Call a known smart contract function to verify the function exists

Return type: bool

property chain_id: int: Chain this vault is on

property address: eth_typing.evm.HexAddress: Get the vault smart contract address.

property name: str: Vault name.

property symbol: str: Vault share token symbol

property vault_contract: web3.contract.contract.Contract: Get vault deployment.

property underlying_token: eth_defi.token.TokenDetails: Alias for denomination_token()

property erc_7540: bool

Is this ERC-7540 vault with asynchronous deposits.

For example previewDeposit() function and other functions will revert

fetch_denomination_token_address()

Get the asset() denomination token address of this vault.

Results are disk-cached per (chain_id, vault_address) via eth_defi.erc_4626.vault_token when the vault was constructed with a eth_defi.token.TokenDiskCache and no pinned default_block_identifier. The denomination token is immutable post-deployment, so the cached value is correct regardless of which block the caller would have asked for.

Only a definitive non-null answer is persisted. The None path taken on revert / broken contract is never cached, matching the behaviour of eth_defi.vault.base.VaultBase.denomination_token() which explicitly avoids memoising None so transient failures can be retried.

To disable the cache, pass token_cache=None (or any non- TokenDiskCache dict) when constructing the vault, or construct with a pinned default_block_identifier.

Returns: Denomination token address, or None if the vault contract is broken and did not return a valid address.
Return type: Optional[eth_typing.evm.HexAddress]

fetch_denomination_token()

Read denomination token from onchain.

Use denomination_token() for cached access.

Return type: Optional[eth_defi.token.TokenDetails]

fetch_share_token_address(block_identifier='latest')

Get share token of this vault.

Vault itself (ERC-4626)
share() accessor (ERC-7575)

Results are disk-cached per (chain_id, vault_address) via eth_defi.erc_4626.vault_token when the vault was constructed with a eth_defi.token.TokenDiskCache. Under normal circumstances the block_identifier argument is effectively ignored on cache hits — ERC-4626 share tokens are immutable post-deployment, so the cached value is correct regardless of which block the caller asked for.

Only a definitive answer from the chain is ever persisted: a successful call, or a revert matching KNOWN_SHARE_TOKEN_ERROR_MESSAGES (which positively classifies the contract as non-ERC-7575). Transient RPC failures (ProbablyNodeHasNoBlock, HTTP 502) fall back to self.vault_address but are not written to the cache, so a flaky node cannot poison a real ERC-7575 vault’s entry.

To disable the cache, pass token_cache=None (or any non- TokenDiskCache dict) when constructing the vault, or construct with a pinned default_block_identifier to force the uncached historical-read path on every call.

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, hexbytes.main.HexBytes, int]) – Block to query. Cache is only consulted/written when the caller passes the default "latest" and the vault instance has no pinned default_block_identifier.
Return type: eth_typing.evm.HexAddress

fetch_share_token()

Read share token details onchain.

Use share_token() for cached access.

Return type: eth_defi.token.TokenDetails

fetch_vault_info()

Get all information we can extract from the vault smart contracts.

Return type: eth_defi.erc_4626.vault.ERC4626VaultInfo

fetch_total_assets(block_identifier)

What is the total NAV of the vault.

Example:

assert vault.denomination_token.symbol == "USDC"
assert vault.share_token.symbol == "ipUSDCfusion"
assert vault.fetch_total_assets(block_identifier=test_block_number) == Decimal("1437072.77357")
assert vault.fetch_total_supply(block_identifier=test_block_number) == Decimal("1390401.22652875")

Parameters

block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, hexbytes.main.HexBytes, int]) –

Block number to read.

Use web3.eth.block_number for the last block.

Returns

The vault value in underlyinh token

Return type

Optional[decimal.Decimal]

fetch_total_supply(block_identifier)

What is the current outstanding shares.

Example:

Parameters

Block number to read.

Use web3.eth.block_number for the last block.

Returns

The vault value in underlyinh token

Return type

decimal.Decimal

fetch_share_price(block_identifier)

Get the current share price.

Returns

The share price in underlying token.

If supply is zero return zero.

Parameters

Return type

decimal.Decimal

fetch_portfolio(universe, block_identifier=None, allow_fallback=True)

Read the current token balances of a vault.

SHould be supported by all implementations

Parameters

universe (eth_defi.vault.base.TradingUniverse) –
block_identifier (Optional[Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, hexbytes.main.HexBytes, int]]) –
allow_fallback (bool) –

Return type

eth_defi.vault.base.VaultPortfolio

fetch_info()

Use info() property for cached access.

Returns: See LagoonVaultInfo
Return type: eth_defi.erc_4626.vault.ERC4626VaultInfo

fetch_nav(block_identifier=None)

Fetch the most recent onchain NAV value.

In the case of Lagoon, this is the last value written in the contract with updateNewTotalAssets() and ` settleDeposit()`
TODO: updateNewTotalAssets() there is no way to read pending asset update on chain

Returns: Vault NAV, denominated in denomination_token()
Return type: decimal.Decimal

get_flow_manager()

Get flow manager to read indiviaul settle events.

Only supported if has_block_range_event_support() is True

Return type: eth_defi.vault.base.VaultFlowManager

get_deposit_manager()

Get deposit manager to deposit/redeem from the vault.

Return type: ERC4626DepositManager

get_deposit_manager_capability()

Declare the exact generic ERC-4626 implementation’s two-way flow.

Subclasses need exact-type inclusion in CERTIFIED_SYNCHRONOUS_DEPOSIT_MANAGER_CLASSES. The guarded probe may separately use supports_generic_deposit_manager() as a temporary fallback without advertising it as public metadata.

Returns: Synchronous two-way capability for the exact base class, otherwise None.
Return type: Optional[eth_defi.vault.deposit_redeem.VaultDepositManagerCapability]

get_synchronous_deposit_manager_capability()

Build static metadata for a verified synchronous manager.

A caller must already have established the reader class’ guarded fork evidence. This deliberately performs no RPC reads: the capability is static library metadata, not a live vault availability check.

Returns: Synchronous two-way capability.
Return type: eth_defi.vault.deposit_redeem.VaultDepositManagerCapability

supports_generic_deposit_manager()

Check whether the live vault exposes the standard ERC-4626 surface.

This is deliberately an interface check, not a public support claim. Callers must still execute a guarded fork probe before relying on the generic manager for a protocol-specific adapter.

Returns: True when asset succeeds with a non-zero asset address. Deposit and redemption availability is established only by a guarded fork transaction, not by ERC-4626 max* advisory values.
Return type: bool

has_block_range_event_support()

Does this vault support block range-based event queries for deposits and redemptions.

If not we use chain balance polling-based approach

has_deposit_distribution_to_all_positions()

Deposits go automatically to all open positions.

Deposits do not land into the vault as cash
Instead, smart contracts automatically increase all open positions
The behaviour of Velvet Capital

get_historical_reader(stateful)

Get share price reader to fetch historical returns.

Parameters: stateful – If True, use a stateful reading strategy.
Returns: None if unsupported
Return type: eth_defi.vault.base.VaultHistoricalReader

get_estimated_lock_up()

ERC-4626 vaults do not have a lock up by fault.

Note

Because of so many protocol specific lockups, this must be explicitly set to zero.

Return type: Optional[datetime.timedelta]

can_check_deposit()

Check if maxDeposit(address(0)) can be used to check global deposit availability.

Most ERC-4626 vaults implement maxDeposit in a way that returns meaningful values when called with address(0):

Returns 0 when deposits are globally closed/capped
Returns a positive value indicating maximum deposit allowed

Override to return False in subclasses where maxDeposit(address(0)) doesn’t provide meaningful global availability information.

Returns: True if maxDeposit(address(0)) returns meaningful values for global deposit availability checking.
Return type: bool

can_check_redeem()

Check if maxRedeem(address(0)) can be used to check global redemption availability.

Most protocols return 0 for maxRedeem(address(0)) because that address has no balance/shares, not because redemptions are closed:

Gearbox: maxRedeem returns min(balanceOf(owner), convertToShares(availableLiquidity))
Most vaults: Return 0 because address(0) has no shares

Some protocols do use maxRedeem(address(0)) meaningfully:

Morpho, IPOR, Plutus: Return 0 when redemptions are globally blocked

Override to return True in subclasses that support address(0) redemption checks.

Returns: True if maxRedeem(address(0)) returns meaningful values for global redemption availability checking.
Return type: bool

fetch_deposit_closed_reason()

Check if deposits are closed using maxDeposit(address(0)).

Uses the ERC-4626 standard maxDeposit function to determine if deposits are available. Returns a human-readable reason with the max deposit amount if deposits are restricted.

Returns: Human-readable string if deposits are closed/restricted, or None if deposits are open (maxDeposit > 0).
Return type: Optional[str]

property denomination_token: Optional[eth_defi.token.TokenDetails]

Get the token which denominates the vault valuation

Used in deposits and redemptions
Used in NAV calculation
Used in profit benchmarks
Usually USDC

Returns

Token wrapper instance.

Maybe None for broken vaults like https://arbiscan.io/address/0x9d0fbc852deccb7dcdd6cb224fa7561efda74411#code

Note

None results are not cached — the next access will retry the on-chain call. This avoids permanently caching a transient RPC failure.

property deposit_manager: eth_defi.vault.deposit_redeem.VaultDepositManager: Deposit manager assocaited with this vault

property description: Optional[str]

Human-readable vault strategy description.

Fetched from protocol-specific offchain sources (e.g. Euler GitHub labels, Lagoon web app API)
Returns None if the protocol does not provide descriptions or the vault is not in the metadata source
Override in subclasses that support offchain metadata

fetch_available_liquidity(block_identifier='latest')

Get the amount of denomination token available for immediate withdrawal.

Only applicable to lending protocol vaults (IPOR, Euler, Morpho, Gearbox, etc.). Non-lending protocols should leave this method unimplemented.

Note: maxRedeem(address(0)) does NOT work as a proxy for available liquidity because it requires a specific address that has already deposited shares. For address(0), balanceOf is always 0, so maxRedeem returns 0 regardless of actual liquidity.

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Block to query. Defaults to “latest”.
Raises: NotImplementedError – For non-lending protocol vaults.
Returns: Amount in denomination token units (human-readable Decimal).
Return type: Optional[decimal.Decimal]

fetch_deposit_next_open()

Get when deposits will next be open.

For epoch-based vaults (Ostium, D2), return calculated window open time
For non-epoch vaults (Plutus, IPOR, Morpho), return None
Override in protocol-specific subclasses

Returns

Naive UTC datetime when deposits will next be available, or None if:

Deposits are currently open
Timing is unpredictable (manually controlled)
Protocol does not support timing information

Return type

Optional[datetime.datetime]

fetch_redemption_closed_reason()

Check if redemptions are closed using maxRedeem(address(0)).

Only works for protocols that implement maxRedeem in a way that returns meaningful values for address(0). Most protocols return 0 because address(0) has no shares, not because redemptions are closed.

Returns: Human-readable string if redemptions are closed, or None if redemptions are open or check is not supported.
Return type: Optional[str]

fetch_redemption_next_open()

Get when withdrawals/redemptions will next be open.

For epoch-based vaults (Ostium, D2), return calculated window open time
For non-epoch vaults (Plutus, IPOR, Morpho), return None
Override in protocol-specific subclasses

Returns

Naive UTC datetime when withdrawals will next be available, or None if:

Withdrawals are currently open
Timing is unpredictable (manually controlled)
Protocol does not support timing information

Return type

Optional[datetime.datetime]

fetch_scan_record_extra_data()

Fetch protocol-specific private scan row columns.

Some vault protocols expose structured metadata that is useful for the raw scanner output but does not fit the shared human-readable columns. Override this hook in protocol-specific subclasses instead of adding a separate branch to eth_defi.erc_4626.scan.create_vault_scan_record().

Returns: Mapping of private scan-row column names, usually prefixed with _. The default implementation returns no extra data.
Return type: dict[str, object]

fetch_utilisation_percent(block_identifier='latest')

Get the percentage of assets currently lent out.

Only applicable to lending protocol vaults (IPOR, Euler, Morpho, Gearbox, etc.). Non-lending protocols should leave this method unimplemented.

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Block to query. Defaults to “latest”.
Raises: NotImplementedError – For non-lending protocol vaults.
Returns: Utilisation as float between 0.0 and 1.0 (0% to 100%).
Return type: Optional[float]

property flow_manager: eth_defi.vault.base.VaultFlowManager: Flow manager associated with this vault

get_deposit_fee(block_identifier)

Deposit fee is set to zero by default as vaults usually do not have deposit fees.

Internal: Use get_fee_data().

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) –
Return type: Optional[float]

get_fee_data()

Get fee data structure for this vault.

Raises: ValueError – In the case of broken or unimplemented fee reading methods in the smart contract
Return type: eth_defi.vault.fee.FeeData

get_fee_mode()

Get how this vault accounts its fees.

Return type: Optional[eth_defi.vault.fee.VaultFeeMode]

get_link(referral=None)

Get a link to the vault dashboard on its native site.

By default, give RouteScan link

Parameters: referral (Optional[str]) – Optional referral code to append to the URL.
Returns: URL string
Return type: str

get_management_fee(block_identifier)

Get the current management fee as a percent.

Internal: Use get_fee_data().

Returns: 0.1 = 10%
Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) –
Return type: float

get_notes()

Get a human readable message if we know somethign special is going on with this vault.

Return type: Optional[str]

get_performance_fee(block_identifier)

Get the current performance fee as a percent.

Internal: Use get_fee_data().

Returns: 0.1 = 10%
Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) –
Return type: float

get_protocol_name()

Return the name of the vault protocol.

Return type: str

get_risk()

Get risk profile of this vault.

Return type: Optional[eth_defi.vault.risk.VaultTechnicalRisk]

get_withdraw_fee(block_identifier)

Withdraw fee is set to zero by default as vaults usually do not have withdraw fees.

Internal: Use get_fee_data().

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) –
Return type: float

has_custom_fees()

Does this vault have fees outside the shared fee model.

Custom fees cause risk in vault comparison because the shared management/performance/deposit/withdraw fee fields cannot describe the full fee structure.

Do not return True merely because a vault implements custom accessors for ordinary management, performance, deposit, or withdraw fees. Return True only when some vault fee cannot be reflected in those standard fields as a fee-like value.

Returns: True if the vault has fees outside the shared fee model.
Return type: bool

property info: eth_defi.vault.base.VaultInfo

Get info dictionary related to this vault deployment.

Get cached data on the various vault parameters

Returns: Vault protocol specific information dictionary

is_account_whitelisted(address)

Determine whether an account belongs to the vault deposit policy.

The result concerns policy membership only. A protocol may still require scheduling, an allowance, available capacity, or an open epoch before a deposit can be submitted. Callers must use the relevant deposit manager pre-flight before broadcasting a transaction.

Parameters: address (eth_typing.evm.HexAddress) – Account whose deposit-policy membership is queried.
Returns: True when the account belongs to the applicable policy.
Raises: NotImplementedError – If the adapter cannot safely query account membership.
Return type: bool

is_whitelisted_deposit()

Determine whether this vault applies a deposit whitelist policy.

Protocol adapters override this predicate only when their deployed contract version exposes a reliable vault-wide policy read. True means the vault requires account permission; False means its policy is permissionless. This is independent of a caller’s current balance, allowance, pause state, capacity, and request lifecycle.

Returns: True for a whitelist-restricted vault and False for a permissionless vault.
Raises: NotImplementedError – If the adapter cannot safely determine the policy.
Return type: bool

property manager_name: Optional[str]

Protocol-supplied vault manager or curator display name.

Used when the vault name itself does not contain the curator brand
Returns None if the protocol does not expose separate manager metadata
Override in subclasses that support manager or operator metadata

property share_token: eth_defi.token.TokenDetails

ERC-20 that presents vault shares.

User gets shares on deposit and burns them on redemption

property short_description: Optional[str]

One-liner vault summary.

Shorter version of description() suitable for listings and tables
Returns None if not available
Override in subclasses that support offchain metadata

first_seen_at_block: Optional[int]

Block number hint when this vault was deployed.

Must be set externally, as because of shitty Ethereum RPC we cannot query this. Allows us to avoid unnecessary work when scanning historical price data.

get_flags()

Get various vault state flags from the smart contract.

Override to add status flags
Also add flags from our manual flag list in eth_defi.vault.flag

Returns

Flag set.

Do not modify in place.

Return type

set[eth_defi.vault.flag.VaultFlag]