erc_4626.vault_protocol.frankencoin.vault

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

Frankencoin savings vault support.

Frankencoin is an over-collateralised, oracle-free Swiss franc stablecoin protocol. Its Savings Vaults are ERC-4626 wrappers for the Frankencoin savings module, allowing users to deposit ZCHF and receive svZCHF shares.

The vaults do not have protocol-wide management, performance, deposit, or withdrawal fees. They do support an optional per-account referral fee that is deducted from earned interest and paid to the configured referrer.

Homepage: https://frankencoin.com/
Token and savings vault page: https://frankencoin.com/token/
Documentation: https://docs.frankencoin.com/
GitHub: https://github.com/Frankencoin-ZCHF/Frankencoin
Savings module source: https://github.com/Frankencoin-ZCHF/Frankencoin/blob/main/contracts/minting/v2/SavingsV2.sol

Module Attributes

`FRANKENCOIN_SAVINGS_VAULT_ABI`	Minimal ABI for the svZCHF wrapper contract.
`FRANKENCOIN_ETHEREUM_SAVINGS_VAULT`	Frankencoin Savings Vault on Ethereum.
`FRANKENCOIN_ETHEREUM_LEGACY_SAVINGS_VAULT`	Legacy Frankencoin Savings Vault on Ethereum picked up by vault discovery.
`FRANKENCOIN_BASE_SAVINGS_VAULT`	Frankencoin Savings Vault on Base.
`FRANKENCOIN_GNOSIS_SAVINGS_VAULT`	Frankencoin Savings Vault on Gnosis.
`FRANKENCOIN_SAVINGS_VAULTS_BY_CHAIN`	ERC-4626 Frankencoin Savings Vault wrappers by chain.
`FRANKENCOIN_SAVINGS_VAULTS`	Frankencoin Savings Vault addresses across supported chains.
`FRANKENCOIN_PRODUCT_TVL_VAULTS_BY_CHAIN`	Frankencoin wrappers that represent the full savings product TVL.
`FRANKENCOIN_PRODUCT_TVL_VAULTS`	Frankencoin Savings Vault addresses that report full savings product TVL.
`MAX_REFERRAL_FEE`	Maximum optional referral fee in the Frankencoin savings module.
`FRANKENCOIN_SAVINGS_BALANCE_CALL_COUNT`	Number of ZCHF balance calls needed for Frankencoin savings TVL.

Classes

`FrankencoinHistoricalReader`	Read Frankencoin savings TVL across the wrapper and savings module.
`FrankencoinVault`	Frankencoin ERC-4626 savings vault support.

FRANKENCOIN_SAVINGS_VAULT_ABI = [{'inputs': [], 'name': 'savings', 'outputs': [{'type': 'address'}], 'stateMutability': 'view', 'type': 'function'}]: Minimal ABI for the svZCHF wrapper contract.

FRANKENCOIN_ETHEREUM_SAVINGS_VAULT = '0xe5f130253ff137f9917c0107659a4c5262abf6b0'

Frankencoin Savings Vault on Ethereum.

https://etherscan.io/token/0xE5F130253fF137f9917C0107659A4c5262abf6b0

FRANKENCOIN_ETHEREUM_LEGACY_SAVINGS_VAULT = '0x637f00cab9665cb07d91bfb9c6f3fa8fabfef8bc'

Legacy Frankencoin Savings Vault on Ethereum picked up by vault discovery.

This wrapper points at the same Frankencoin savings module as the official Ethereum svZCHF wrapper.

https://etherscan.io/token/0x637F00cAb9665cB07d91bfB9c6f3fa8faBFEF8BC

FRANKENCOIN_BASE_SAVINGS_VAULT = '0xa09ebdf8a01b9ef04149319d64f83b9c01a5b585'

Frankencoin Savings Vault on Base.

https://basescan.org/address/0xa09EBdf8A01b9ef04149319D64F83b9C01a5b585

FRANKENCOIN_GNOSIS_SAVINGS_VAULT = '0x6165946250dd04740ab1409217e95a4f38374fe9'

Frankencoin Savings Vault on Gnosis.

https://gnosisscan.io/token/0x6165946250dd04740ab1409217e95a4f38374fe9

FRANKENCOIN_SAVINGS_VAULTS_BY_CHAIN = {1: frozenset({'0x637f00cab9665cb07d91bfb9c6f3fa8fabfef8bc', '0xe5f130253ff137f9917c0107659a4c5262abf6b0'}), 100: frozenset({'0x6165946250dd04740ab1409217e95a4f38374fe9'}), 8453: frozenset({'0xa09ebdf8a01b9ef04149319d64f83b9c01a5b585'})}: ERC-4626 Frankencoin Savings Vault wrappers by chain.

FRANKENCOIN_SAVINGS_VAULTS = frozenset({'0x6165946250dd04740ab1409217e95a4f38374fe9', '0x637f00cab9665cb07d91bfb9c6f3fa8fabfef8bc', '0xa09ebdf8a01b9ef04149319d64f83b9c01a5b585', '0xe5f130253ff137f9917c0107659a4c5262abf6b0'}): Frankencoin Savings Vault addresses across supported chains.

FRANKENCOIN_PRODUCT_TVL_VAULTS_BY_CHAIN = {1: frozenset({'0x637f00cab9665cb07d91bfb9c6f3fa8fabfef8bc'}), 100: frozenset({'0x6165946250dd04740ab1409217e95a4f38374fe9'}), 8453: frozenset({'0xa09ebdf8a01b9ef04149319d64f83b9c01a5b585'})}

Frankencoin wrappers that represent the full savings product TVL.

Ethereum has two svZCHF wrappers that point at the same savings module. Only the legacy wrapper is currently discovered in production data, so it is the canonical row for Ethereum product-level TVL.

FRANKENCOIN_PRODUCT_TVL_VAULTS = frozenset({'0x6165946250dd04740ab1409217e95a4f38374fe9', '0x637f00cab9665cb07d91bfb9c6f3fa8fabfef8bc', '0xa09ebdf8a01b9ef04149319d64f83b9c01a5b585'}): Frankencoin Savings Vault addresses that report full savings product TVL.

MAX_REFERRAL_FEE = 0.25

Maximum optional referral fee in the Frankencoin savings module.

Source: AbstractSavings.setReferrer() rejects values above 250,000 ppm.

FRANKENCOIN_SAVINGS_BALANCE_CALL_COUNT = 2: Number of ZCHF balance calls needed for Frankencoin savings TVL.

class FrankencoinHistoricalReader

Bases: eth_defi.erc_4626.vault.ERC4626HistoricalReader

Read Frankencoin savings TVL across the wrapper and savings module.

Frankencoin’s ERC-4626 totalAssets() only reports assets attributed to the svZCHF wrapper inside the savings module. Most savings deposits sit directly in the underlying savings module, outside the ERC-4626 wrapper.

For Trading Strategy vault TVL we treat the savings product as a whole and write ZCHF.balanceOf(savings_module) + ZCHF.balanceOf(svZCHF_wrapper) to total_assets. The share price and total supply still come from the ERC-4626 wrapper, so performance calculations keep using the wrapper’s own exchange rate.

get_warmup_calls()

Yield warmup calls for Frankencoin vaults.

Includes the standard ERC-4626 calls plus the ZCHF balances that define the savings product TVL.

Returns: Tuples consumed by the vault warmup scanner.
Return type: collections.abc.Iterable[tuple[str, callable, object]]

construct_multicalls()

Create calls for Frankencoin historical reads.

Returns: Encoded calls for ERC-4626 state and Frankencoin savings TVL.
Return type: collections.abc.Iterable[eth_defi.event_reader.multicall_batcher.EncodedCall]

construct_savings_balance_multicalls()

Create ZCHF balance calls used to calculate savings product TVL.

Returns: Encoded ZCHF balanceOf calls for the savings module and wrapper.
Return type: collections.abc.Iterable[eth_defi.event_reader.multicall_batcher.EncodedCall]

process_savings_tvl_result(call_by_name)

Decode Frankencoin savings TVL calls.

Parameters: call_by_name (dict[str, eth_defi.event_reader.multicall_batcher.EncodedCallResult]) – Multicall results keyed by extra_data["function"].
Returns: (total_assets, errors) where total_assets is denominated in ZCHF.
Return type: tuple[decimal.Decimal | None, list[str]]

process_result(block_number, timestamp, call_results)

Process a Frankencoin historical read result.

Parameters

block_number (int) – Block number used for the read.
timestamp (datetime.datetime) – Naive UTC block timestamp.
call_results (list[eth_defi.event_reader.multicall_batcher.EncodedCallResult]) – Multicall results for this vault.

Returns

Historical row with Frankencoin savings product TVL for canonical wrappers, or regular ERC-4626 wrapper TVL for duplicate wrappers.

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

Bases: eth_defi.erc_4626.vault.ERC4626Vault

Frankencoin ERC-4626 savings vault support.

Frankencoin Savings Vaults tokenise deposits into the Frankencoin savings module. The underlying contract source documents an interest delay of up to three days before deposits start earning yield.

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.

property name: str

Return a human-readable name for this vault.

The on-chain share token name is SavingsVault ZCHF. Use the protocol-facing product name in vault listings.

property frankencoin_vault_contract: web3.contract.contract.Contract

Return the svZCHF wrapper contract with Frankencoin-specific ABI.

Returns: Web3 contract instance exposing the savings() accessor.

property savings_module_address: eth_typing.evm.HexAddress

Return the underlying Frankencoin savings module address.

Returns: Savings module address used by this svZCHF wrapper.

property reports_savings_product_tvl: bool

Whether this wrapper is the canonical full-product TVL row.

Returns: True if this wrapper should report savings-module TVL.

fetch_total_assets(block_identifier)

Return Frankencoin savings product TVL.

Frankencoin’s ERC-4626 wrapper only reports assets attributed to wrapper shareholders. The public savings product also includes direct deposits in the savings module. For canonical vault discovery rows, report the ZCHF held by both the module and the wrapper contract.

Duplicate wrappers fall back to regular ERC-4626 totalAssets() so exports do not count the same savings module TVL twice.

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Block number to read.
Returns: Total ZCHF held by the Frankencoin savings module and wrapper, or wrapper-only TVL for duplicate wrappers.
Return type: Optional[decimal.Decimal]

fetch_nav(block_identifier=None)

Fetch the Frankencoin savings product NAV.

Parameters: block_identifier (Optional[Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]]) – Block number to read.
Returns: Same value as fetch_total_assets().
Return type: Optional[decimal.Decimal]

fetch_share_price(block_identifier)

Get the svZCHF wrapper share price.

The Frankencoin TVL override represents the whole savings product, not only svZCHF shareholders. Therefore share price must still come from convertToAssets(1 share) instead of total_assets / total_supply.

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Block number to read.
Returns: svZCHF share price in ZCHF.
Return type: decimal.Decimal

get_historical_reader(stateful)

Return the Frankencoin historical reader.

Parameters: stateful (bool) – Whether the reader maintains adaptive polling state.
Returns: Frankencoin-specific historical reader.
Return type: eth_defi.vault.base.VaultHistoricalReader

has_custom_fees()

Frankencoin has an optional per-account referral fee.

Frankencoin does not charge fixed vault-level management, performance, deposit, or withdrawal fees. However, a user can configure a referrer that receives up to 25% of the earned interest, which is account-level fee data outside the shared protocol fee fields.

Return type: bool

get_management_fee(block_identifier)

Return the vault management fee.

Frankencoin Savings Vaults do not charge a protocol-wide management fee at the vault layer. Yield comes from the Frankencoin savings module.

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Unused block identifier kept for the shared vault fee API.
Returns: Management fee as a fraction.
Return type: float

get_performance_fee(block_identifier)

Return the vault performance fee.

Frankencoin Savings Vaults do not charge a protocol-wide performance fee at the vault layer. A separate optional referral fee can skim up to 25% of earned interest for accounts that configure a referrer.

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Unused block identifier kept for the shared vault fee API.
Returns: Performance fee as a fraction.
Return type: float

get_estimated_lock_up()

Return the savings module interest delay as a lock-up estimate.

The verified SavingsV2 source documents that saved ZCHF is subject to a lock-up of up to three days before it starts earning interest.

Returns: Estimated savings delay.
Return type: datetime.timedelta

get_link(referral=None)

Return the Frankencoin token and savings vault page.

Parameters: referral (Optional[str]) –
Return type: str

__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

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

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

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_risk()

Get risk profile of this vault.

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

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

Check if this vault is valid.

Call a known smart contract function to verify the function exists

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

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.