erc_4626.vault_protocol.flying_tulip.vault

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

Flying Tulip sftUSD vault adapter and contextual historical reader.

sftUSD is an ERC-4626 vault with separately claimable FT rewards. The contextual reader emits a non-redeemable, reinvested share_price_equivalence history while ordinary live ERC-4626 calls retain the contract-reported principal accounting.

Only the reviewed chain/address pairs in the deployment registry instantiate this adapter. The scanner does not use contract selectors to discover or map Flying Tulip vault equivalents.

Module Attributes

FLYING_TULIP_UNSUPPORTED_FLOW_REASON

Stable explanation returned until the circuit-breaker queue transaction lifecycle is implemented and verified on a shared Anvil fork.

Functions

get_flying_tulip_historical_context_path()

Return the shared Flying Tulip contextual-cache path.

Classes

`FlyingTulipHistoricalReader`	Read replayed FT distribution-adjusted share-price equivalents.
`FlyingTulipVault`	Read-only Flying Tulip sftUSD adapter.

FLYING_TULIP_UNSUPPORTED_FLOW_REASON = 'Flying Tulip redemption may return a circuit-breaker queue ID; generic ERC-4626 transactions are unsupported until the queued lifecycle is implemented': Stable explanation returned until the circuit-breaker queue transaction lifecycle is implemented and verified on a shared Anvil fork.

get_flying_tulip_historical_context_path()

Return the shared Flying Tulip contextual-cache path.

Returns: Common protocol-owned DuckDB cache filename.
Return type: pathlib.Path

class FlyingTulipHistoricalReader

Bases: eth_defi.vault.base.VaultHistoricalReader

Read replayed FT distribution-adjusted share-price equivalents.

property uses_contextual_history: bool

Select the source-event history path rather than static multicalls.

Returns: Always True.

construct_multicalls()

Return no static calls because the price series is epoch sourced.

Returns: Empty iterable.
Return type: collections.abc.Iterable[eth_defi.event_reader.multicall_batcher.EncodedCall]

process_result(block_number, timestamp, call_results)

Reject the generic fixed-block history path.

Parameters

block_number (int) – Unused static-call block.
timestamp (datetime.datetime) – Unused static-call timestamp.
call_results (list[eth_defi.event_reader.multicall_batcher.EncodedCallResult]) – Unused static-call results.

Returns

Never returns.

Raises

RuntimeError – Always, because contextual replay owns this history.

Return type

eth_defi.vault.base.VaultHistoricalRead

fetch_contextual_historical_reads(start_block, end_block, step)

Yield stored price-equivalence rows for the common Parquet writer.

Parameters

start_block (int) – Inclusive caller block boundary.
end_block (int) – Exclusive caller block boundary.
step (int) – Common scanner’s approximate block bucket width.

Returns

Sparse, reward-adjusted historical rows.

Return type

collections.abc.Iterable[eth_defi.vault.base.VaultHistoricalRead]

__init__(vault)

Parameters: vault (eth_defi.vault.base.VaultBase) –

property share_price_change_threshold: float

Return this reader’s sparse share-price comparison threshold.

Event-only readers may require every exact price change; ordinary readers retain the existing ten-basis-point suppression threshold.

Returns: Non-negative relative suppression threshold.

property uses_share_price_equivalence: bool

Return whether cash flows must be ignored by the sparse filter.

Vault-like products without a standard share-price method can still expose a supply-normalised price equivalent. Their TVL and supply changes must not create false performance observations.

Returns: True when the vault carries the share_price_equivalence feature.

class FlyingTulipVault

Bases: eth_defi.erc_4626.vault.ERC4626Vault

Read-only Flying Tulip sftUSD adapter.

The adapter retains regular ERC-4626 principal methods. It deliberately refuses generic deposits/redemptions, because a redemption can transfer value to Flying Tulip’s circuit breaker and return a queue ID instead of immediately delivering ftUSD.

Create an adapter only for a reviewed sftUSD proxy.

Parameters

web3 – Web3 connection for a reviewed deployment chain.
spec – Chain and sftUSD proxy specification.
kwargs – Common ERC-4626 adapter keyword arguments.

__init__(web3, spec, **kwargs)

Create an adapter only for a reviewed sftUSD proxy.

Parameters

web3 (web3.main.Web3) – Web3 connection for a reviewed deployment chain.
spec (eth_defi.vault.base.VaultSpec) – Chain and sftUSD proxy specification.
kwargs – Common ERC-4626 adapter keyword arguments.

Return type

None

property short_description: str

Return the maintained sftUSD scanner summary.

Returns: Concise description explaining the external reward model.

fetch_reward_token_address(block_identifier='latest')

Return the reviewed FT reward-token address for this deployment.

The finite sftUSD deployment registry supplies this address directly, so vault identification and reward-token mapping require no ABI selectors. block_identifier remains accepted to preserve the common vault-adapter interface.

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Ignored historical or current state block.
Returns: Checksum FT token address.
Return type: eth_typing.evm.HexAddress

property reward_token: eth_defi.token.TokenDetails

Fetch FT metadata on the active deployment chain.

Returns: Cached FT token details.

get_historical_reader(stateful)

Return the contextual external-reward history reader.

Parameters: stateful (bool) – Retained common-reader compatibility argument.
Returns: Flying Tulip’s source-event reader.
Return type: eth_defi.vault.base.VaultHistoricalReader

get_deposit_manager()

Refuse unsafe generic ERC-4626 request construction.

Returns: Never returns.
Raises: NotImplementedError – Queue-aware lifecycle support is pending.
Return type: eth_defi.vault.deposit_redeem.VaultDepositManager

get_deposit_manager_capability()

Hide transaction capability until both redemption outcomes are safe.

Returns: None so public metadata does not imply synchronous redemption.
Return type: Optional[eth_defi.vault.deposit_redeem.VaultDepositManagerCapability]

get_management_fee(block_identifier)

Return Flying Tulip’s zero direct 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]) – Unused fee-read block.
Returns: 0.0.
Return type: float

get_performance_fee(block_identifier)

Return Flying Tulip’s zero direct performance fee.

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

get_deposit_fee(block_identifier)

Return the USDC-funded Flying Tulip vault-equivalent entry fee.

The direct ftUSD-to-sftUSD conversion is fee-free. For consistent comparison with USDC-denominated vaults, the common fee field models the preceding USDC-to-ftUSD mint fee instead.

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Unused fee-read block.
Returns: Chain-specific externalised USDC entry fee.
Return type: float

get_withdraw_fee(block_identifier)

Return the USDC-funded Flying Tulip vault-equivalent exit fee.

The direct sftUSD-to-ftUSD conversion is fee-free. For consistent comparison with USDC-denominated vaults, the common fee field models the following ftUSD-to-USDC redemption fee instead.

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Unused fee-read block.
Returns: Chain-specific externalised USDC exit fee.
Return type: float

get_notes()

Explain the USDC-equivalent entry and exit fee model.

The fee fields deliberately represent entering from and returning to USDC so Flying Tulip can be compared with other vaults. The returned Markdown distinguishes those conversion fees from the fee-free direct sftUSD wrapping route and links to the authoritative deployment.

Returns: Protocol note with the fee route and operational caveats.
Return type: str

get_strategy_tags()

Return conservative, address-reviewed Flying Tulip strategy tags.

Returns: Tag copy, or None for an unclassified reviewed deployment.
Return type: Optional[set[eth_defi.vault.strategy_tag.StrategyTag]]

get_link(referral=None)

Return Flying Tulip’s ftUSD application page.

Parameters: referral (Optional[str]) – Unsupported referral code.
Returns: Public staking application URL.
Return type: str

fetch_scan_record_extra_data()

Mark the historical curve as non-redeemable in scanner exports.

Returns: Common metadata plus explicit live and synthetic semantics.
Return type: dict[str, object]

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. Current mappings expire after seven days because proxy upgrades may change relationships. These entries are not evidence of a token relationship at an arbitrary historical block.

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 or this adapter cannot safely use zero-address maxDeposit as a global availability read.
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_deposit_open()

Fetch the current protocol-defined deposit availability.

This is deliberately a tri-state value. True and False mean that the adapter read an authoritative vault-wide state; None means that the generic adapter cannot safely determine the state. It is separate from fetch_deposit_closed_reason(), because an absent human-readable reason does not prove that deposits are open.

Returns: True when deposits are open, False when they are closed, or None when the protocol does not expose a reliable global availability read.
Return type: Optional[bool]

fetch_idle_lending_snapshot(total_assets, block_identifier)

Read the idle balance once for adapters with idle-based utilisation.

This helper is opt-in: idle assets are not redeemable liquidity for every lending protocol. See the protocol’s liquidity documentation.

Morpho v1 and IPOR metadata call this after reading total assets, avoiding duplicate idle-balance reads for liquidity and utilisation. Reuse the exact raw assets only when their source block and decimal value match; converting an externally supplied Decimal back to raw units is a fallback for callers that did not first fetch assets through this adapter.

Parameters

total_assets (decimal.Decimal) – Previously fetched TVL in denomination-token units.
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]) – Numeric block used for both economic inputs.

Returns

(idle_liquidity, utilisation): a Decimal balance in denomination token units and the fraction of total assets allocated (0 to 1). Both members are None when the denomination token is unavailable; zero total assets produces zero utilisation.

Return type

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

fetch_info()

Use info() property for cached access.

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

fetch_minimum_deposit(block_identifier='latest')

Fetch a source-proven minimum deposit in decimal token units.

A None result means this adapter does not expose a known minimum; it does not prove the protocol accepts arbitrarily small deposits. A zero result means the adapter positively established that the vault has no minimum deposit.

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Block at which to read the protocol configuration.
Returns: Decimal denomination-token minimum, or None when unknown.
Return type: Optional[decimal.Decimal]

fetch_minimum_redemption(block_identifier='latest')

Fetch a source-proven redemption minimum in decimal share units.

A None result means this adapter does not expose a known minimum; it does not prove the protocol accepts arbitrarily small redemptions. A zero result means the adapter positively established that the vault has no minimum redemption.

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Block at which to read the protocol configuration.
Returns: Decimal vault-share minimum, or None when unknown.
Return type: Optional[decimal.Decimal]

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_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 live reads reuse the current relationship until its seven-day deadline. Explicit historical reads bypass this disk cache because ERC-7575 relationships may change through proxy upgrades.

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 number to read.

Use web3.eth.block_number for the last block.

Returns

The vault value in underlyinh token

Return type

Optional[decimal.Decimal]

fetch_total_supply(block_identifier)

What is the current outstanding shares.

Example:

Parameters

Block number to read.

Use web3.eth.block_number for the last block.

Returns

The vault value in underlyinh token

Return type

decimal.Decimal

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

The vault metadata scan stores this result as _flags in vault-metadata-db.pickle. top_vaults_by_chain.json is generated from those stored values through scripts/erc-4626/vault-analysis-json.py / eth_defi.vault.top_vaults_json.

After editing manual flags in eth_defi.vault.flag, rerun the vault metadata scan and top-vault JSON post-processing. Regenerating the JSON from an old metadata database will not pick up new manual flags.

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_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_share_price_source()

Return the standard ERC-4626 share-price source.

ERC-4626 prices are calculated from vault accounting values read at a specific block, including protocol-specific overrides that expose the same state through another contract view.

Returns: Smart-contract state source.
Return type: eth_defi.vault.price_source.PriceSource

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

Return an export caveat for the vault-wide whitelist status.

Adapters may attach a concise, stable explanation when a classification is an explicitly requested operating assumption or excludes an integration-specific permission mechanism. The note describes the policy classification only; it must not be used to report temporary deposit availability.

Returns: Export note, or None when the classification needs no caveat.
Return type: Optional[str]

get_withdrawal_period()

Return binding withdrawal timing and optional settlement estimates.

Unlike get_estimated_lock_up(), this reports the redemption lifecycle after a user submits a valid withdrawal request. Adapters use min_period and max_period only for a binding smart-contract timing rule. An adapter may instead return a non-binding estimated_settlement for backtesting an offchain operating cadence or redemption wait; that estimate never establishes claimability and does not require a synthetic timing bound.

Returns: Withdrawal period details, or None when unavailable.
Return type: Optional[eth_defi.vault.base.WithdrawalPeriod]

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 has completed the vault’s KYC policy.

The result concerns KYC, manual identity approval, or recipient allowlist membership only. A protocol may still require scheduling, a token balance, 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 has the required pre-approval.
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 deposits require pre-approved recipient accounts.

Protocol adapters override this predicate only when the deployed contract version has verified implementation source or a canonical application ABI that proves a reliable vault-wide policy read. An explicitly documented operating assumption may also override it, but must set whitelist_notes so consumers can distinguish it from a source-proven result. True means the vault requires KYC, manual identity approval, or a source-proven recipient allowlist; False means its policy is permissionless. An open date, lock-up, epoch, pause, cap, token balance, or other runtime eligibility condition must not affect the result. A source-proven override requires a fixed-block adapter test for every supported implementation generation. An operating assumption requires a unit test that asserts both its classification and its caveat. This is independent of a caller’s current balance, allowance, pause state, capacity, and request lifecycle.

Returns: True when deposits require account pre-approval and False when they do not.
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

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: int | None

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.