FrankencoinVault
Documentation for eth_defi.erc_4626.vault_protocol.frankencoin.vault.FrankencoinVault Python class.
- class FrankencoinVault
Bases:
eth_defi.erc_4626.vault.ERC4626VaultFrankencoin 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, useget_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, accessingdenomination_tokenwill raiseRuntimeErrorwhen the on-chain lookup returnsNone.
Attributes summary
Get the vault smart contract address.
Chain this vault is on
Get the token which denominates the vault valuation
Deposit manager assocaited with this vault
Human-readable vault strategy description.
Is this ERC-7540 vault with asynchronous deposits.
Flow manager associated with this vault
Return the svZCHF wrapper contract with Frankencoin-specific ABI.
Get info dictionary related to this vault deployment.
Protocol-supplied vault manager or curator display name.
Return a human-readable name for this vault.
Whether this wrapper is the canonical full-product TVL row.
Return the underlying Frankencoin savings module address.
ERC-20 that presents vault shares.
One-liner vault summary.
Vault share token symbol
Alias for
denomination_token()vault_addressvault_address_checksumlessGet vault deployment.
Methods summary
__init__(web3, spec[, token_cache, ...])- param web3
Check if maxDeposit(address(0)) can be used to check global deposit availability.
Check if maxRedeem(address(0)) can be used to check global redemption availability.
fetch_available_liquidity([block_identifier])Get the amount of denomination token available for immediate withdrawal.
Read denomination token from onchain.
Get the
asset()denomination token address of this vault.Check if deposits are closed using maxDeposit(address(0)).
Get when deposits will next be open.
Use
info()property for cached access.fetch_nav([block_identifier])Fetch the Frankencoin savings product NAV.
fetch_portfolio(universe[, ...])Read the current token balances of a vault.
Check if redemptions are closed using maxRedeem(address(0)).
Get when withdrawals/redemptions will next be open.
Fetch protocol-specific private scan row columns.
fetch_share_price(block_identifier)Get the svZCHF wrapper share price.
Read share token details onchain.
fetch_share_token_address([block_identifier])Get share token of this vault.
fetch_total_assets(block_identifier)Return Frankencoin savings product TVL.
fetch_total_supply(block_identifier)What is the current outstanding shares.
fetch_utilisation_percent([block_identifier])Get the percentage of assets currently lent out.
Get all information we can extract from the vault smart contracts.
get_deposit_fee(block_identifier)Deposit fee is set to zero by default as vaults usually do not have deposit fees.
Get deposit manager to deposit/redeem from the vault.
Declare the exact generic ERC-4626 implementation's two-way flow.
Return the savings module interest delay as a lock-up estimate.
Get fee data structure for this vault.
Get how this vault accounts its fees.
Get various vault state flags from the smart contract.
Get flow manager to read indiviaul settle events.
get_historical_reader(stateful)Return the Frankencoin historical reader.
get_link([referral])Return the Frankencoin token and savings vault page.
get_management_fee(block_identifier)Return the vault management fee.
Get a human readable message if we know somethign special is going on with this vault.
get_performance_fee(block_identifier)Return the vault performance fee.
Return the name of the vault protocol.
get_risk()Get risk profile of this vault.
get_spec()Build static metadata for a verified synchronous manager.
get_withdraw_fee(block_identifier)Withdraw fee is set to zero by default as vaults usually do not have withdraw fees.
Does this vault support block range-based event queries for deposits and redemptions.
Frankencoin has an optional per-account referral fee.
Deposits go automatically to all open positions.
is_valid()Check if this vault is valid.
Check whether the live vault exposes the standard ERC-4626 surface.
- 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
Trueif 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
- 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
- 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 oftotal_assets / total_supply.
- 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
- 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
- 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.
- 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.
- get_estimated_lock_up()
Return the savings module interest delay as a lock-up estimate.
The verified
SavingsV2source 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
- get_link(referral=None)
Return the Frankencoin token and savings vault page.
- __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, useget_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, accessingdenomination_tokenwill raiseRuntimeErrorwhen the on-chain lookup returnsNone.
- 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
- 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
- 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
Noneresults 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
- fetch_denomination_token()
Read denomination token from onchain.
Use
denomination_token()for cached access.- Return type
- fetch_denomination_token_address()
Get the
asset()denomination token address of this vault.Results are disk-cached per
(chain_id, vault_address)viaeth_defi.erc_4626.vault_tokenwhen the vault was constructed with aeth_defi.token.TokenDiskCacheand no pinneddefault_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
Nonepath taken on revert / broken contract is never cached, matching the behaviour ofeth_defi.vault.base.VaultBase.denomination_token()which explicitly avoids memoisingNoneso transient failures can be retried.To disable the cache, pass
token_cache=None(or any non-TokenDiskCachedict) when constructing the vault, or construct with a pinneddefault_block_identifier.- Returns
Denomination token address, or
Noneif the vault contract is broken and did not return a valid address.- Return type
- 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.
- 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
- fetch_info()
Use
info()property for cached access.- Returns
See
LagoonVaultInfo- Return type
- 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
- 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.
- 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
- 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().
- fetch_share_token()
Read share token details onchain.
Use
share_token()for cached access.- Return type
- 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)viaeth_defi.erc_4626.vault_tokenwhen the vault was constructed with aeth_defi.token.TokenDiskCache. Under normal circumstances theblock_identifierargument 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 toself.vault_addressbut 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-TokenDiskCachedict) when constructing the vault, or construct with a pinneddefault_block_identifierto 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 pinneddefault_block_identifier.- Return type
- 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
- 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
- fetch_vault_info()
Get all information we can extract from the vault smart contracts.
- Return type
- 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().
- get_deposit_manager()
Get deposit manager to deposit/redeem from the vault.
- Return type
- 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 usesupports_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
- get_fee_mode()
Get how this vault accounts its fees.
- Return type
- 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
- get_flow_manager()
Get flow manager to read indiviaul settle events.
Only supported if
has_block_range_event_support()is True
- Return type
- get_notes()
Get a human readable message if we know somethign special is going on with this vault.
- get_protocol_name()
Return the name of the vault protocol.
- Return type
- get_risk()
Get risk profile of this vault.
- Return type
- 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
- 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().
- 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
- 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 tablesReturns 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
Truewhenassetsucceeds with a non-zero asset address. Deposit and redemption availability is established only by a guarded fork transaction, not by ERC-4626max*advisory values.- Return type
- 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.