erc_4626.vault_protocol.euler.vault

Documentation for eth_defi.erc_4626.vault_protocol.euler.vault Python module.

Euler Vault Kit and EulerEarn integrations.

• EVK (Euler Vault Kit): Credit vaults with borrowing functionality https://github.com/euler-xyz/euler-vault-kit Metadata repo: https://github.com/euler-xyz/euler-labels/blob/master/130/vaults.json

• EulerEarn: Metamorpho-based metavault for yield aggregation on top of EVK https://github.com/euler-xyz/euler-earn Documentation: https://docs.euler.finance/developers/euler-earn/

Module Attributes

MONAD_CHAIN_ID	Monad mainnet chain id.
ALPHAGROWTH_EULER_LIGHT_BASE_URL	AlphaGrowth's Euler Light frontend for Monad EVK vaults that Euler's official frontend cannot list because they use Balancer LP tokens as collateral.
ALPHAGROWTH_EULER_LIGHT_MONAD_METADATA	AlphaGrowth-curated Monad EVK vaults that need the Euler Light frontend.

Functions

get_alphagrowth_euler_light_metadata(...)	Get AlphaGrowth-specific metadata for Monad Euler Light vaults.
is_alphagrowth_euler_light_vault(chain_id, ...)	Check if an Euler EVK vault should link to AlphaGrowth's Euler Light UI.

Classes

EulerEarnVault	EulerEarn metavault support.
EulerEarnVaultHistoricalReader	Read EulerEarn vault core data + utilisation metrics.
EulerVault	Euler vault support.
EulerVaultHistoricalReader	Read Euler EVK vault core data + utilisation metrics.

CASH_SIGNATURE = HexBytes('0x961be391')

Keccak signatures for Euler EVK multicall

MONAD_CHAIN_ID = 143

Monad mainnet chain id.

ALPHAGROWTH_EULER_LIGHT_BASE_URL = 'https://euler.alphagrowth.io'

AlphaGrowth’s Euler Light frontend for Monad EVK vaults that Euler’s official frontend cannot list because they use Balancer LP tokens as collateral.

ALPHAGROWTH_EULER_LIGHT_MONAD_METADATA: dict[str, eth_defi.erc_4626.vault_protocol.euler.offchain_metadata.EulerVaultMetadata] = {'0x438cedce647491b1d93a73d491ec19a50194c222': {'description': 'Borrow AUSD against Balancer BPT collateral.', 'entities': ['alphagrowth', 'balancer', 'euler'], 'entity': 'alphagrowth', 'name': 'AlphaGrowth AUSD Borrow Vault', 'product': 'ausd-bpt-leverage', 'product_name': 'Stablecoin BPT Leverage'}, '0x75b6c392f778b8bcf9bdb676f8f128b4dd49ac19': {'description': 'Borrow WMON against Balancer BPT collateral.', 'entities': ['alphagrowth', 'balancer', 'euler'], 'entity': 'alphagrowth', 'name': 'AlphaGrowth WMON Borrow Vault', 'product': 'wmon-bpt-leverage', 'product_name': 'WMON BPT Leverage'}}

AlphaGrowth-curated Monad EVK vaults that need the Euler Light frontend.

Kyril from AlphaGrowth explained that these vaults have custom Balancer LP collateral support, so Euler cannot list them on the official frontend. AlphaGrowth curates its Euler vaults with governorAdmin 0x4f894Bfc9481110278C356adE1473eBe2127Fd3C, but only these two Monad vaults currently need this custom frontend link.

is_alphagrowth_euler_light_vault(chain_id, vault_address)

Check if an Euler EVK vault should link to AlphaGrowth’s Euler Light UI.

AlphaGrowth hosts a dedicated Euler Light interface for its Monad EVK vaults that cannot be listed on Euler’s official frontend because of their custom Balancer LP token collateral handling. This helper is deliberately based on the explicit unlisted vault addresses, instead of governorAdmin discovery, because other AlphaGrowth-curated Euler vaults can still use the normal Euler frontend.

Parameters

• chain_id (int) – EVM chain id for the vault.

• vault_address (str) – ERC-4626 vault contract address.

Returns

True if the vault should use the AlphaGrowth Euler Light frontend.

Return type

bool

get_alphagrowth_euler_light_metadata(chain_id, vault_address)

Get AlphaGrowth-specific metadata for Monad Euler Light vaults.

AlphaGrowth maintains labels for its Euler Light frontend in alphagrowth/ag-euler-balancer-labels. The source labels identify the AUSD vault as AUSD Borrow Vault and the WMON vault as WMON Borrow Vault with alphagrowth as the entity. We prefix the display names with AlphaGrowth so our current curator detection, which matches against vault names, can recognise these vaults without a separate on-chain governorAdmin lookup.

Source: https://github.com/alphagrowth/ag-euler-balancer-labels/tree/main/143

Parameters

• chain_id (int) – EVM chain id for the vault.

• vault_address (str) – ERC-4626 vault contract address.

Returns

Metadata override for AlphaGrowth Euler Light vaults, or None.

Return type

Optional[eth_defi.erc_4626.vault_protocol.euler.offchain_metadata.EulerVaultMetadata]

class EulerVaultHistoricalReader

Bases: eth_defi.erc_4626.vault.ERC4626HistoricalReader

Read Euler EVK vault core data + utilisation metrics.

For EVK vaults: - cash() = underlying tokens currently held by vault - totalBorrows() = outstanding borrows including accrued interest - Utilisation = totalBorrows / (cash + totalBorrows)

get_warmup_calls()

Yield warmup calls for Euler EVK vaults.

Includes base ERC-4626 calls plus Euler-specific utilisation calls.

Return type

Iterable[tuple[str, callable, any]]

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_utilisation_calls()

Add Euler EVK-specific utilisation calls.

Return type

Iterable[eth_defi.event_reader.multicall_batcher.EncodedCall]

process_utilisation_result(call_by_name)

Decode Euler EVK utilisation data.

Utilisation = totalBorrows / (cash + totalBorrows)

Parameters

call_by_name (dict[str, eth_defi.event_reader.multicall_batcher.EncodedCallResult]) –

Return type

tuple[decimal.Decimal | None, float | None]

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

__init__(vault, stateful)

Parameters

• vault (eth_defi.erc_4626.vault.ERC4626Vault) –

• stateful (bool) –

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]

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_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

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

class EulerVault

Bases: eth_defi.erc_4626.vault.ERC4626Vault

Euler vault support.

• Handle special offchain metadata

• Example vault https://etherscan.io/address/0x1e548CfcE5FCF17247E024eF06d32A01841fF404#code

• Euler ABIs https://github.com/euler-xyz/euler-interfaces

TODO: Fees

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.

get_risk()

Get risk profile of this vault.

Return type

Optional[eth_defi.vault.risk.VaultTechnicalRisk]

property name: str

Vault name.

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

property manager_name: Optional[str]

Euler product entity slug from Euler offchain metadata.

get_management_fee(block_identifier)

Euler vault kit vaults never have management fee

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_performance_fee(block_identifier)

Get Euler fee.

• Euler vaults have only fee called “interest fee”

• This is further split to “governor fee” and “protocol fee” but this distinction is not relevant for the vault user

• See https://github.com/euler-xyz/euler-vault-kit/blob/5b98b42048ba11ae82fb62dfec06d1010c8e41e6/src/EVault/EVault.sol

Returns

None if fee reading is broken

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_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]

get_link(referral=None)

Get link to the Euler EVK vault frontend.

Most EVK vaults use Euler’s official frontend. AlphaGrowth’s two Monad EVK vaults with custom Balancer LP collateral support are linked to AlphaGrowth’s Euler Light frontend instead, because Euler cannot list them on the official frontend.

Parameters

referral (Optional[str]) – Optional referral code. Not used by Euler links.

Returns

Frontend URL for this vault.

Return type

str

can_check_redeem()

Euler EVK does NOT support address(0) checks for redemption availability.

Return type

bool

get_historical_reader(stateful)

Get Euler EVK-specific historical reader with utilisation metrics.

Parameters

stateful (bool) –

Return type

eth_defi.vault.base.VaultHistoricalReader

fetch_available_liquidity(block_identifier='latest')

Get the amount of denomination token available for immediate withdrawal.

Uses Euler’s cash() function which returns the underlying tokens currently held by the vault (not lent out).

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”.

Returns

Amount in denomination token units (human-readable Decimal).

Return type

Optional[decimal.Decimal]

fetch_utilisation_percent(block_identifier='latest')

Get the percentage of assets currently lent out.

Utilisation = totalBorrows / (cash + totalBorrows)

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”.

Returns

Utilisation as float between 0.0 and 1.0 (0% to 100%).

Return type

Optional[float]

__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.

property address: eth_typing.evm.HexAddress

Get the vault smart contract address.

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

property chain_id: int

Chain this vault is on

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 erc_7540: bool

Is this ERC-7540 vault with asynchronous deposits.

• For example previewDeposit() function and other functions will revert

fetch_denomination_token()

Read denomination token from onchain.

Use denomination_token() for cached access.

Return type

Optional[eth_defi.token.TokenDetails]

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_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]

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_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

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_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_share_price(block_identifier)

Get the current share price.

Returns

The share price in underlying token.

If supply is zero return zero.

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]) –

Return type

decimal.Decimal

fetch_share_token()

Read share token details onchain.

Use share_token() for cached access.

Return type

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_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_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

decimal.Decimal

fetch_vault_info()

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

Return type

eth_defi.erc_4626.vault.ERC4626VaultInfo

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_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_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_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]

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_notes()

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

Return type

Optional[str]

get_protocol_name()

Return the name of the vault protocol.

Return type

str

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

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_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_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

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

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_valid()

Check if this vault is valid.

• Call a known smart contract function to verify the function exists

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 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

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

property symbol: str

Vault share token symbol

property underlying_token: eth_defi.token.TokenDetails

Alias for denomination_token()

property vault_contract: web3.contract.contract.Contract

Get vault deployment.

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.

class EulerEarnVault

Bases: eth_defi.erc_4626.vault.ERC4626Vault

EulerEarn metavault support.

EulerEarn is a protocol for noncustodial risk management on top of accepted ERC-4626 vaults, especially the EVK (Euler Vault Kit) vaults. Based on Metamorpho architecture.

• EulerEarn allows only accepted ERC-4626 vaults to be used as strategies

• EulerEarn vaults are themselves ERC-4626 vaults

• One EulerEarn vault is related to one underlying asset

• Users can supply or withdraw assets at any time, depending on the available liquidity

• A maximum of 30 strategies can be enabled on a given EulerEarn vault

• There are 4 different roles: owner, curator, guardian & allocator

• The vault owner can set a performance fee up to 50% of the generated interest

Links:

• GitHub: https://github.com/euler-xyz/euler-earn

• Documentation: https://docs.euler.finance/developers/euler-earn/

• Integrator guide: https://docs.euler.finance/developers/euler-earn/integrator-guide/

• Example vault: https://snowtrace.io/address/0xE1A62FDcC6666847d5EA752634E45e134B2F824B

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.

get_risk()

EulerEarn vaults have negligible risk due to battle-tested infrastructure.

Based on Metamorpho architecture with extensive audits. However, individual vaults may be blacklisted due to specific issues (e.g., xUSD exposure).

Return type

Optional[eth_defi.vault.risk.VaultTechnicalRisk]

has_custom_fees()

EulerEarn has on-chain readable performance fees.

Return type

bool

get_management_fee(block_identifier)

EulerEarn vaults do not have management fees.

Only performance fee is charged on generated interest.

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_performance_fee(block_identifier)

Get EulerEarn performance fee.

• EulerEarn charges a performance fee on generated interest

• The fee is stored as a uint96 in WAD (1e18) format

• Maximum fee is 50% (0.5e18)

See: https://github.com/euler-xyz/euler-earn/blob/main/src/EulerEarn.sol

Returns

Performance fee as a decimal (e.g., 0.10 for 10%), or None if reading fails

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_estimated_lock_up()

EulerEarn vaults allow instant withdrawals.

Users can withdraw at any time depending on available liquidity.

Return type

Optional[datetime.timedelta]

get_link(referral=None)

Get link to EulerEarn vault on Euler app.

EulerEarn vaults are shown on the Euler Finance app under the “earn” section.

Parameters

referral (Optional[str]) –

Return type

str

get_supply_queue_length(block_identifier='latest')

Get the number of strategies in the supply queue.

Returns

Number of strategies in the supply queue, or None if reading fails

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[int]

get_withdraw_queue_length(block_identifier='latest')

Get the number of strategies in the withdraw queue.

Returns

Number of strategies in the withdraw queue, or None if reading fails

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[int]

get_curator(block_identifier='latest')

Get the curator address for this vault.

The curator can manage vault parameters and strategy allocations.

Returns

Curator address, or None if reading fails

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[str]

can_check_redeem()

EulerEarn does NOT support address(0) checks for redemption availability.

Return type

bool

get_historical_reader(stateful)

Get EulerEarn-specific historical reader with utilisation metrics.

Parameters

stateful (bool) –

Return type

eth_defi.vault.base.VaultHistoricalReader

fetch_available_liquidity(block_identifier='latest')

Get the amount of denomination token available for immediate withdrawal.

Uses the idle assets pattern: asset().balanceOf(vault) returns unallocated assets.

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”.

Returns

Amount in denomination token units (human-readable Decimal).

Return type

Optional[decimal.Decimal]

fetch_utilisation_percent(block_identifier='latest')

Get the percentage of assets currently allocated to strategies.

Utilisation = (totalAssets - idle) / totalAssets

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”.

Returns

Utilisation as float between 0.0 and 1.0 (0% to 100%).

Return type

Optional[float]

__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.

property address: eth_typing.evm.HexAddress

Get the vault smart contract address.

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

property chain_id: int

Chain this vault is on

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

property erc_7540: bool

Is this ERC-7540 vault with asynchronous deposits.

• For example previewDeposit() function and other functions will revert

fetch_denomination_token()

Read denomination token from onchain.

Use denomination_token() for cached access.

Return type

Optional[eth_defi.token.TokenDetails]

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_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]

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_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

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_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_share_price(block_identifier)

Get the current share price.

Returns

The share price in underlying token.

If supply is zero return zero.

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]) –

Return type

decimal.Decimal

fetch_share_token()

Read share token details onchain.

Use share_token() for cached access.

Return type

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_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_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

decimal.Decimal

fetch_vault_info()

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

Return type

eth_defi.erc_4626.vault.ERC4626VaultInfo

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_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_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_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]

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_notes()

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

Return type

Optional[str]

get_protocol_name()

Return the name of the vault protocol.

Return type

str

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

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_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

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_valid()

Check if this vault is valid.

• Call a known smart contract function to verify the function exists

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 name: str

Vault name.

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

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

property symbol: str

Vault share token symbol

property underlying_token: eth_defi.token.TokenDetails

Alias for denomination_token()

property vault_contract: web3.contract.contract.Contract

Get vault deployment.

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.

FEE_SIGNATURE = HexBytes('0xddca3f43')

Keccak signature for EulerEarn fee

class EulerEarnVaultHistoricalReader

Bases: eth_defi.erc_4626.vault.ERC4626HistoricalReader

Read EulerEarn vault core data + utilisation metrics.

For EulerEarn (metavault): - Idle assets = asset().balanceOf(vault) - Utilisation = (totalAssets - idle) / totalAssets

Warning

EulerEarn vaults have maxDeposit() disabled because it uses excessive gas.

Research notes on TelosC Surge vault (0xa9C251F8304b1B3Fc2b9e8fcae78D94Eff82Ac66):

The EulerEarn architecture (based on Metamorpho) has loop-heavy operations that cause maxDeposit(address(0)) to consume 21-36M gas - nearly the entire Plasma block gas limit of 36M.

The gas consumption comes from:

1. _maxDeposit() in EulerEarnVaultModule.sol iterates through supplyQueue to calculate maxTotalDeposit for each strategy

2. _convertToShares() in EulerEarnBase.sol triggers _accruedFeeAndAssets() which loops through the entire withdrawQueue to calculate accrued fees

3. Maximum queue length of 30 strategies (defined in ConstantsLib.MAX_QUEUE_LENGTH) means up to 60 external contract calls per maxDeposit() invocation

Source code references:

• EulerEarnVaultModule.sol: _maxDeposit() at supplyQueue iteration

• EulerEarnBase.sol: _accruedFeeAndAssets() at withdrawQueue iteration

• ConstantsLib.sol: MAX_QUEUE_LENGTH = 30

Plasmascan: https://plasmascan.to/address/0xa9C251F8304b1B3Fc2b9e8fcae78D94Eff82Ac66

Since Multicall3 does not support per-call gas limits, and calling maxDeposit() would consume the entire block gas limit, we unconditionally skip this call for all EulerEarn vaults.

should_skip_call(function_name)

Check if a specific function call should be skipped.

EulerEarn vaults always skip maxDeposit due to excessive gas usage. See class docstring for detailed research notes.

Parameters

function_name (str) –

Return type

bool

get_warmup_calls()

Yield warmup calls for EulerEarn vaults.

Includes base ERC-4626 calls (except maxDeposit) plus idle_assets and fee calls. maxDeposit is excluded because EulerEarn vaults use excessive gas for this call.

Return type

Iterable[tuple[str, callable, any]]

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_utilisation_calls()

Add idle assets call for utilisation calculation.

Note: We use the asset token’s balanceOf to get idle assets. This requires an additional call to the asset token contract.

Return type

Iterable[eth_defi.event_reader.multicall_batcher.EncodedCall]

construct_fee_calls()

Add EulerEarn fee call.

Return type

Iterable[eth_defi.event_reader.multicall_batcher.EncodedCall]

process_utilisation_result(call_by_name, total_assets)

Decode EulerEarn utilisation data.

Utilisation = (totalAssets - idle) / totalAssets

Parameters

• call_by_name (dict[str, eth_defi.event_reader.multicall_batcher.EncodedCallResult]) –

• total_assets (Optional[decimal.Decimal]) –

Return type

tuple[decimal.Decimal | None, float | None]

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

__init__(vault, stateful)

Parameters

• vault (eth_defi.erc_4626.vault.ERC4626Vault) –

• stateful (bool) –

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]

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_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