tokenised_fund.vault

Documentation for eth_defi.tokenised_fund.vault Python module.

Shared base class for legally structured tokenised-fund vault adapters.

This namespace is reserved for products with a legal fund structure. A DeFi vault is not a tokenised fund merely because it issues ERC-20 shares or settles at epochs.

Classes

`TokenisedFundDepositManager`	Fail-closed, non-operational manager for permissioned tokenised funds.
`TokenisedFundVault`	Base class for every tokenised fund protocol adapter.

class TokenisedFundDepositManager

Bases: eth_defi.vault.deposit_redeem.VaultDepositManager

Fail-closed, non-operational manager for permissioned tokenised funds.

Tokenised funds are issuer-operated products whose subscriptions and redemptions require investor eligibility (KYC, allow-list, transfer agent) and offchain servicing, so there is no publicly executable onchain flow. This manager still implements the full VaultDepositManager interface — but every operational method is fail-closed — so scanner metadata can distinguish a deliberately unsupported permissioned product from an adapter whose capability is merely unknown. It never constructs, settles or analyses a transaction. All refusals route through _reject(), which raises VaultFlowUnavailable with a fixed reason (TOKENISED_FUND_FLOW_UNAVAILABLE) and the requested direction/phase.

Deposit process

Unsupported / fail-closed. has_synchronous_deposit() returns False; estimate_deposit(), create_deposit_request(), finish_deposit() and analyse_deposit() all raise VaultFlowUnavailable. can_create_deposit_request() returns False and get_max_deposit() returns zero.

Redemption process

Unsupported / fail-closed. has_synchronous_redemption() returns False; estimate_redeem(), create_redemption_request(), finish_redemption() and analyse_redemption() all raise VaultFlowUnavailable. can_create_redemption_request() and can_finish_redeem() return False.

Queues and settlement

None. No ticket can be created, so is_deposit_in_progress() and is_redemption_in_progress() return False, and reclaim_deposit() / reclaim_withdrawal() raise.

Lockups and cooldowns

Not applicable / not queryable. estimate_redemption_delay() raises VaultFlowUnavailable, and get_redemption_delay_over() returns None because no redemption can ever be created.

Whitelisting / access control

Permissioned. At the vault level TokenisedFundVault.is_whitelisted_deposit() always returns True, marking these subscriptions as gated, but concrete membership is not queryable here — eligibility is enforced offchain by the issuer, so is_account_whitelisted stays protocol-specific and this base manager does not attempt to evaluate it.

Anvil settlement (force_settle)

Unlike the synchronous ERC-4626 managers, force_settle() does not perform a no-op: it raises VaultFlowUnavailable (phase="settlement"), because there is no fund transaction to settle.

force_settle(ticket, *, mock=None, ignore_liquidity=False)

Reject settlement of an unsupported tokenised-fund flow.

Parameters

ticket (Optional[Union[eth_defi.vault.deposit_redeem.DepositTicket, eth_defi.vault.deposit_redeem.RedemptionTicket]]) –
mock (Optional[object]) –
ignore_liquidity (bool) –

Return type

eth_defi.vault.deposit_redeem.VaultForcedSettlementResult

reclaim_deposit(ticket)

Reject recovery because this manager cannot create deposit tickets.

Parameters: ticket (eth_defi.vault.deposit_redeem.DepositTicket) –
Return type: Optional[web3.contract.contract.ContractFunction]

reclaim_withdrawal(ticket)

Reject recovery because this manager cannot create redemption tickets.

Parameters: ticket (eth_defi.vault.deposit_redeem.RedemptionTicket) –
Return type: Optional[web3.contract.contract.ContractFunction]

has_synchronous_deposit()

Return false because no public deposit flow is supported.

Return type: bool

has_synchronous_redemption()

Return false because no public redemption flow is supported.

Return type: bool

estimate_deposit(owner, amount, block_identifier='latest')

Reject estimation of an unsupported deposit.

Parameters

owner (Optional[eth_typing.evm.HexAddress]) –
amount (decimal.Decimal) –
block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) –

Return type

decimal.Decimal

estimate_redeem(owner, shares, block_identifier='latest')

Reject estimation of an unsupported redemption.

Parameters

owner (Optional[eth_typing.evm.HexAddress]) –
shares (decimal.Decimal) –
block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) –

Return type

decimal.Decimal

create_deposit_request(owner, to=None, amount=None, raw_amount=None, check_max_deposit=True, check_enough_token=True)

Reject creation of a public tokenised-fund deposit.

Parameters

owner (eth_typing.evm.HexAddress) –
to (eth_typing.evm.HexAddress) –
amount (decimal.Decimal) –
raw_amount (int) –
check_max_deposit (bool) –
check_enough_token (bool) –

Return type

eth_defi.vault.deposit_redeem.DepositRequest

create_redemption_request(owner, to=None, shares=None, raw_shares=None, check_max_deposit=True, check_enough_token=True)

Reject creation of a public tokenised-fund redemption.

Parameters

owner (eth_typing.evm.HexAddress) –
to (eth_typing.evm.HexAddress) –
shares (decimal.Decimal) –
raw_shares (int) –
check_max_deposit (bool) –
check_enough_token (bool) –

Return type

eth_defi.vault.deposit_redeem.RedemptionRequest

is_redemption_in_progress(owner)

Return false because this manager cannot create redemptions.

Parameters: owner (eth_typing.evm.HexAddress) –
Return type: bool

is_deposit_in_progress(owner)

Return false because this manager cannot create deposits.

Parameters: owner (eth_typing.evm.HexAddress) –
Return type: bool

can_create_deposit_request(owner)

Return false because public tokenised-fund deposits are unsupported.

Parameters: owner (eth_typing.evm.HexAddress) –
Return type: bool

get_max_deposit(owner)

Return zero because this manager refuses public deposits.

Parameters: owner (eth_typing.evm.HexAddress) –
Return type: decimal.Decimal

can_create_redemption_request(owner)

Return false because public tokenised-fund redemptions are unsupported.

Parameters: owner (eth_typing.evm.HexAddress) –
Return type: bool

can_finish_redeem(redemption_ticket)

Return false because this manager cannot create redemptions.

Parameters: redemption_ticket (eth_defi.vault.deposit_redeem.RedemptionTicket) –
Return type: bool

can_finish_deposit(deposit_ticket)

Return false because this manager cannot create deposits.

Parameters: deposit_ticket (eth_defi.vault.deposit_redeem.DepositTicket) –
Return type: bool

finish_deposit(deposit_ticket)

Reject completion of an unsupported deposit.

Parameters: deposit_ticket (eth_defi.vault.deposit_redeem.DepositTicket) –
Return type: web3.contract.contract.ContractFunction

finish_redemption(redemption_ticket)

Reject completion of an unsupported redemption.

Parameters: redemption_ticket (eth_defi.vault.deposit_redeem.RedemptionTicket) –
Return type: Optional[web3.contract.contract.ContractFunction]

estimate_redemption_delay()

Reject delay estimation for an unsupported redemption.

Return type: datetime.timedelta

get_redemption_delay_over(address)

Return no deadline because no redemption can be created.

Parameters: address (Union[eth_typing.evm.HexAddress, str]) –
Return type: Optional[datetime.datetime]

analyse_deposit(claim_tx_hash, deposit_ticket)

Reject analysis because this manager cannot produce deposit transactions.

Parameters

claim_tx_hash (Union[hexbytes.main.HexBytes, str]) –
deposit_ticket (Optional[eth_defi.vault.deposit_redeem.DepositTicket]) –

Return type

Union[eth_defi.vault.deposit_redeem.DepositRedeemEventAnalysis, eth_defi.vault.deposit_redeem.DepositRedeemEventFailure]

analyse_redemption(claim_tx_hash, redemption_ticket)

Reject analysis because this manager cannot produce redemption transactions.

Parameters

claim_tx_hash (Union[hexbytes.main.HexBytes, str]) –
redemption_ticket (Optional[eth_defi.vault.deposit_redeem.RedemptionTicket]) –

Return type

Union[eth_defi.vault.deposit_redeem.DepositRedeemEventAnalysis, eth_defi.vault.deposit_redeem.DepositRedeemEventFailure]

__init__(vault)

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

check_deposit_whitelist(owner)

Reject a deposit when the vault’s whitelist excludes the owner.

Shared deposit-preflight helper implementing the whitelisting contract every manager must honour: when a vault applies a deposit whitelist policy that is applicable and queryable, and owner is not a member of it, raise WhitelistingRequired before any transaction is broadcast so the caller can surface a “whitelisting required” state instead of paying gas for a guaranteed revert.

The check is intentionally conservative — it only raises when the whitelist information can be obtained and is applicable:

if is_whitelisted_deposit() raises NotImplementedError, the vault-wide policy cannot be determined for this adapter/version, so no exception is raised;
if the vault is permissionless, no exception is raised;
if is_account_whitelisted() raises NotImplementedError, per-account membership cannot be queried, so no exception is raised;
only when the policy is applicable and the owner is provably not admitted is WhitelistingRequired raised.

Adapters that need a stricter fail-closed policy for an unknown admission state should override their own preflight and raise VaultFlowUnavailable in addition to calling this helper (see the Lagoon manager for an example).

Parameters: owner (eth_typing.evm.HexAddress) – Deposit owner and controller whose whitelist membership is checked.
Raises: WhitelistingRequired – When the vault applies an applicable, queryable whitelist policy and owner is not permitted to deposit.
Return type: None

create_deposit_request_for_guard_validation(owner, raw_amount)

Build deposit calldata for a closed-vault GuardV0 policy check.

This Anvil-only diagnostic path is for a consumer that has already received a typed deposit_closed or deposit_paused preflight result. Adapters must override it only after proving that their typed result represents a temporary vault closure rather than a capacity or amount restriction. The returned calls must be supplied individually to GuardV0.validateCall(); callers must never broadcast them to the closed protocol vault.

Parameters

owner (eth_typing.evm.HexAddress) – SimpleVaultV0/Safe address that would own the shares.
raw_amount (int) – Denomination-token amount in the selected asset’s raw unit.

Returns

Manager-generated deposit request suitable only for isolated GuardV0 validation.

Raises

UnsupportedVaultSimulation – Unless the protocol-specific manager implements this diagnostic path.

Return type

eth_defi.vault.deposit_redeem.DepositRequest

create_redemption_request_for_analysis(owner, raw_shares)

Rebuild request metadata for a transaction that already executed.

The default preserves existing manager behaviour without checking an escrowed wallet balance. Protocols whose admission changes on request must override this hook so receipt parsing never reruns live preflights.

Parameters

owner (eth_typing.evm.HexAddress) – Original share owner.
raw_shares (int) – Exact requested native shares.

Returns

Request parser and original call shape.

Return type

eth_defi.vault.deposit_redeem.RedemptionRequest

fetch_completed_redemption_tx_hash(ticket)

Find an operator-owned terminal redemption transaction when available.

Claim-based protocols finish through finish_redemption() and do not need this lookup. Operator-finalised protocols override the hook to find and validate the transaction that paid the requested receiver.

Parameters: ticket (eth_defi.vault.deposit_redeem.RedemptionTicket) – Persisted redemption request to locate.
Returns: Terminal transaction hash, or None if the protocol has not observed one yet.
Return type: Optional[hexbytes.main.HexBytes]

fetch_pending_redemption_value(ticket, block_identifier='latest')

Quote a ticket when ordinary share valuation no longer represents it.

The default retains normal share valuation. Protocols with fixed request-time entitlements or burned pending shares override this hook. Returning a value does not recognise cash or complete settlement.

Parameters

ticket (eth_defi.vault.deposit_redeem.RedemptionTicket) – Persisted request belonging to one trade.
block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Block used for all valuation reads.

Returns

Net denomination value, or None to value ordinary shares.

Return type

Optional[decimal.Decimal]

fetch_vault_flow_events(hypersync_client, start_block, end_block)

Fetch asynchronous vault request events from an indexed backend.

The base implementation returns no events for vault managers that do not have a two-phase deposit or redemption flow.

Parameters

hypersync_client – Configured Hypersync client for this vault’s chain.
start_block (int) – Inclusive start block.
end_block (int) – Inclusive end block.

Returns

Iterator of protocol-neutral pending vault flow events.

Return type

collections.abc.Iterator[eth_defi.vault.flow_events.PendingVaultFlow]

force_redemption_liquidity(owner, raw_shares, failure)

Provision an unavailable synchronous redemption on an Anvil fork.

Concrete managers may implement this only for a source-proven liquidity failure. The default is deliberately unsupported: this hook must never bypass admission, minimums, maturity or time locks.

Parameters

owner (eth_typing.evm.HexAddress) – Redemption owner.
raw_shares (int) – Exact raw share quantity requested.
failure (eth_defi.vault.deposit_redeem.VaultFlowUnavailable) – Typed preflight failure that prompted the intervention request.

Returns

Structured intervention evidence from a concrete manager.

Raises

UnsupportedVaultSimulation – Always for managers without a protocol-specific implementation.

Return type

eth_defi.vault.deposit_redeem.VaultRedemptionSimulationIntervention

get_deposit_approval_target()

Return the ERC-20 spender required for a deposit request.

Standard ERC-4626 and the currently supported async adapters pull denomination tokens from the vault address itself. An adapter using a different router or silo must override this method; guarded callers use it to whitelist and validate the exact approval calldata.

Returns: ERC-20 approval spender address.
Return type: eth_typing.evm.HexAddress

get_deposit_delay_over(address)

Estimate when a pending async deposit request will settle.

Mirror of get_redemption_delay_over() for the deposit side.
Used to show an estimated settlement time for unsettled deposits (e.g. in the trade-executor trade-ui table).
Default returns None: the protocol has no deterministic onchain settlement schedule (e.g. operator-driven ERC-7540 vaults like Lagoon). Subclasses with a predictable settlement cadence (e.g. Ostium V1.5) override this to return an estimated UTC timestamp.

Parameters: address (Union[eth_typing.evm.HexAddress, str]) – Owner of the pending deposit request.
Returns: Naive UTC timestamp when the deposit is expected to settle, or None when no onchain estimate is available.
Return type: Optional[datetime.datetime]

get_deposit_request_status(ticket)

Query the current status of an async deposit request.

Default implementation probes via can_finish_deposit(). Subclasses should override for more accurate status reporting (e.g. distinguishing reclaimable from pending).

Parameters: ticket (eth_defi.vault.deposit_redeem.DepositTicket) –
Return type: eth_defi.vault.deposit_redeem.AsyncVaultRequestStatus

get_redemption_request_status(ticket)

Query the current status of an async redemption request.

Default implementation probes via can_finish_redeem(). Subclasses should override for more accurate status reporting.

Parameters: ticket (eth_defi.vault.deposit_redeem.RedemptionTicket) –
Return type: eth_defi.vault.deposit_redeem.AsyncVaultRequestStatus

reconstruct_deposit_ticket(data)

Reconstruct a deposit ticket from a serialised dict.

Default returns a base DepositTicket. Subclasses override for protocol-specific ticket types.

Parameters: data (dict) –
Return type: eth_defi.vault.deposit_redeem.DepositTicket

reconstruct_redemption_ticket(data)

Reconstruct a redemption ticket from a serialised dict.

Async vault managers must override this to return their protocol-specific ticket subclass. The base implementation raises NotImplementedError because RedemptionTicket has abstract methods.

Parameters: data (dict) –
Return type: eth_defi.vault.deposit_redeem.RedemptionTicket

serialize_deposit_ticket(ticket)

Serialise a deposit ticket to a dict for persistence.

The trade-executor stores this in trade.other_data so that the settlement retry module can reconstruct the ticket after a process restart.

Default implementation stores base DepositTicket fields. Subclasses override to add protocol-specific fields (e.g. settlement_id for Ostium, requestId for ERC-7540).

Parameters: ticket (eth_defi.vault.deposit_redeem.DepositTicket) –
Return type: dict

serialize_redemption_ticket(ticket)

Serialise a redemption ticket to a dict for persistence.

Default implementation stores base RedemptionTicket fields. Subclasses override to add protocol-specific fields.

Parameters: ticket (eth_defi.vault.deposit_redeem.RedemptionTicket) –
Return type: dict

class TokenisedFundVault

Bases: eth_defi.vault.base.VaultBase

Base class for every tokenised fund protocol adapter.

Tokenised fund classification belongs to the adapter type instead of a manually maintained address list. This also covers legally structured products discovered dynamically from issuer registries, such as Asseto funds. It must not be used for ordinary DeFi vault protocols.

Parameters

token_cache –
Token cache for vault tokens.

Allows to pass eth_defi.token.TokenDiskCache to speed up operations.
require_denomination_token –
If True, accessing denomination_token will raise RuntimeError when the on-chain lookup returns None.

Use for deployment scripts and operational contexts where a missing denomination token is always a hard error.

is_whitelisted_deposit()

Classify tokenised-fund subscriptions as permissioned.

Tokenised-fund adapters model issuer-operated products whose subscriptions require investor eligibility, issuer approval, or both. This is a vault-wide classification: individual adapters may expose different KYC, allow-list, transfer-agent, or offchain settlement mechanisms, so is_account_whitelisted() remains protocol-specific.

Returns: Always True because tokenised-fund deposits are permissioned.
Return type: bool

get_deposit_manager()

Return a manager that explicitly refuses public fund operations.

The manager gives runtime callers a typed refusal, while get_deposit_manager_capability() provides the corresponding report metadata. Concrete issuer integrations must replace both only after implementing their complete permission-aware dealing lifecycle.

Returns: Non-operational tokenised-fund deposit manager.
Return type: eth_defi.tokenised_fund.vault.TokenisedFundDepositManager

get_deposit_manager_capability()

Report explicit lack of public deposit and redemption support.

Returns: A two-direction capability with both operations disabled.
Return type: eth_defi.vault.deposit_redeem.VaultDepositManagerCapability

get_flags()

Return vault flags including the tokenised fund classification.

Preserve address- and protocol-specific flags supplied by the generic vault implementation, then add the descriptive flag used by tokenised fund listings. This base class is reserved for products with a legal fund structure, and must not be used merely because a DeFi vault issues epoch-settled shares.

Returns: A new set containing all generic flags and VaultFlag.tokenised_fund.
Return type: set[eth_defi.vault.flag.VaultFlag]

get_link(referral=None)

Return the issuer’s most useful public fund link.

Tokenised-fund adapters must provide a product landing page where one exists, then fall back to an official announcement, curator page or protocol page. A block-explorer address is technical contract metadata, not an investor-facing product link, and is never a valid fallback for these products.

Parameters: referral (Optional[str]) – Optional referral code. Tokenised-fund products currently do not use it.
Returns: An official issuer, curator or protocol URL.
Raises: NotImplementedError – Always. Concrete adapters must select the appropriate official link rather than inheriting VaultBase’s explorer URL.
Return type: str

__init__(token_cache=None, require_denomination_token=False)

Parameters

token_cache (Optional[dict]) –
Token cache for vault tokens.

Allows to pass eth_defi.token.TokenDiskCache to speed up operations.
require_denomination_token (bool) –
If True, accessing denomination_token will raise RuntimeError when the on-chain lookup returns None.

Use for deployment scripts and operational contexts where a missing denomination token is always a hard error.

abstract property address: eth_typing.evm.HexAddress

Vault contract address.

Often vault protocols need multiple contracts per vault, so what this function returns depends on the protocol

abstract 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 in Markdown.

The website shows this as “About the vault” and renders it as Markdown. Write it in paragraphs of two or three sentences separated by a blank line. Bold text, inline links and #### subheadings are allowed. Adapters must use normalise_vault_description() on offchain text, which converts carriage returns and literal \n / \r escapes to real line breaks. See docs/README-vault-description-formatting.md for the field rules.

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

fetch_available_liquidity(block_identifier='latest')

Read the adapter’s available denomination-token liquidity.

Single-market adapters report market liquidity. Multi-market adapters such as Morpho and IPOR currently report idle vault assets, which can understate redeemable liquidity in their underlying markets. A user’s withdrawal can also be limited by share ownership or protocol restrictions. Non-lending adapters should leave this method unimplemented.

maxRedeem(address(0)) cannot measure market-wide liquidity because ERC-4626 caps redemptions by the owner’s share balance. The zero address normally holds no shares, so a zero result says nothing about 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]

abstract fetch_denomination_token()

Read denomination token from onchain.

Use denomination_token() for cached access.

Return type: eth_defi.token.TokenDetails

fetch_denomination_token_address()

Get the address for the denomination token when one exists.

Synthetic accounting units used by some tokenised funds do not have an ERC-20 denomination token and return None.

This may trigger an RPC call.

Returns: ERC-20 denomination token address, or None for a synthetic accounting unit.
Return type: Optional[eth_typing.evm.HexAddress]

fetch_deposit_closed_reason()

Get human-readable reason why deposits are closed.

Override in protocol-specific subclasses
Default behaviour: no closure reason is known (return None)

Returns

Human-readable string explaining why deposits are closed, or None if deposits are open or the adapter cannot determine a closure reason. Use fetch_deposit_open() for explicit tri-state availability metadata.

Example reasons:

”Epoch redemption window closed (opens in 14h)”
”Vault paused by admin”
”Max deposit cap reached”
”Vault utilisation too high”

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]

abstract fetch_info()

Read vault parameters from the chain.

Use info() property for cached access.

Return type: eth_defi.vault.base.VaultInfo

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]

abstract fetch_nav()

Fetch the most recent onchain NAV value.

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

abstract fetch_portfolio(universe, block_identifier=None)

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

Return type

eth_defi.vault.base.VaultPortfolio

fetch_redemption_closed_reason()

Get human-readable reason why redemptions are closed.

Override in protocol-specific subclasses
Default behaviour: assume redemptions are always open (return None)

Returns

Human-readable string explaining why redemptions are closed, or None if redemptions are open.

Example reasons:

”Epoch funding phase in progress (opens in 2d 5h)”
”Vault paused by admin”
”Vault utilisation too high - insufficient liquidity”

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]

abstract fetch_share_token()

Read share token details onchain.

Use share_token() for cached access.

Return type: eth_defi.token.TokenDetails

fetch_utilisation_percent(block_identifier='latest')

Read the adapter’s lending or capital-deployment utilisation.

Single-market adapters measure borrower utilisation. Multi-market adapters such as Morpho and IPOR currently measure allocation outside the vault, rather than aggregate utilisation by underlying borrowers. Non-lending adapters should leave this method unimplemented.

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

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

get_deposit_fee(block_identifier)

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

Internal: Use get_fee_data().

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

get_estimated_lock_up()

What is the estimated lock-up period for this vault.

Returns: None if not know
Return type: Optional[datetime.timedelta]

get_fee_data(block_identifier='latest')

Get fee data structure for this vault.

Component fee reads share the requested block. Existing no-argument callers retain latest-state behaviour.

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Common fee source block, default latest.
Returns: Fee mode and component fractions.
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]

abstract 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

abstract get_historical_reader(stateful)

Get share price reader to fetch historical returns.

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

get_management_fee(block_identifier)

Get the current management fee as a percent.

Internal: Use get_fee_data().

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

get_notes()

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

Return type: Optional[str]

get_performance_fee(block_identifier)

Get the current performance fee as a percent.

Internal: Use get_fee_data().

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

get_protocol_name()

Return the name of the vault protocol.

Return type: str

get_risk()

Get risk profile of this vault.

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

get_share_price_source()

Return the source used for share-price observations.

Vault integrations override this method when they expose a share price. Returning None distinguishes unsupported or unknown pricing from a known source classification.

Returns: Share-price source, or None when the adapter does not provide one.
Return type: Optional[eth_defi.vault.price_source.PriceSource]

get_strategy_tags()

Get the known investment strategy classifications for this vault.

Override this method when an adapter or its metadata source can determine the vault’s strategy. None means the strategy information is missing or has not yet been classified; it is distinct from an empty set, which would mean the strategy was evaluated but did not match any available tag. Maintained mappings normally omit an unclassified address; use StrategyTag.unknown only when research establishes that the strategy itself is unknown.

Returns: Strategy tag set, or None when the information is missing.
Return type: Optional[set[eth_defi.vault.strategy_tag.StrategyTag]]

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

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]

abstract 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

Return type: bool

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

abstract 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

Return type: bool

property info: eth_defi.vault.base.VaultInfo

Get info dictionary related to this vault deployment.

Get cached data on the various vault parameters

Returns: Vault protocol specific information dictionary

is_account_whitelisted(address)

Determine whether an account 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

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

abstract 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]

Single-line, single-sentence vault summary.

Summaries must not contain newline or carriage-return characters, paragraph breaks, or literal \n / \r escape sequences. Adapters must use normalise_vault_short_description() on offchain text. When automatically copying a description or a provider-supplied summary, retain only its first sentence, including the ending punctuation.

Shorter version of description() suitable for listings and tables
Plain text only: Markdown (links, emphasis, lists) is not allowed, because listings and tables render the short description verbatim. Put links and formatted copy in description() or get_notes()
Returns None if not available
Override in subclasses that support offchain metadata

abstract property symbol: str: Vault share token symbol

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.