erc_4626.vault_protocol.yearn.deposit_redeem

Documentation for eth_defi.erc_4626.vault_protocol.yearn.deposit_redeem Python module.

Yearn V3 deposit preflight extensions.

Classes

YearnV3DepositManager

Recognise Yearn V3 closures and rejected approved deposits.

class YearnV3DepositManager

Bases: eth_defi.erc_4626.deposit_redeem.ERC4626DepositManager

Recognise Yearn V3 closures and rejected approved deposits.

Yearn deliberately returns zero for maxDeposit(address(0)), so the generic ERC-4626 global-closure reader cannot be used. A vault without a deposit-limit module has a vault-wide deposit_limit; an owner-specific zero maxDeposit then means shutdown or a full global limit. A module can impose account-specific policy. Once an owner has already approved the requested amount, the manager simulates its exact deposit() call to expose a vault-specific admission rejection before broadcast.

fetch_global_deposit_closure_reason(owner)

Identify a Yearn closure that is independent of account policy.

Parameters

owner (eth_typing.evm.HexAddress) – Account for the real deposit attempt and simulated receiver.

Returns

A stable closure reason, or None when the state is open or a per-account deposit-limit module prevents a safe determination.

Return type

Optional[str]

fetch_depositable_raw_assets(owner)

Read Yearn’s owner-specific capacity without normalising zero.

Parameters

owner (eth_typing.evm.HexAddress) – Account that would receive the Yearn shares.

Returns

Current raw capacity, including a zero result from an unknown deposit-limit module, which must remain a normal preflight refusal.

Return type

int

fetch_deposit_rejection(owner, raw_amount)

Simulate an approved Yearn deposit using the actual sender and amount.

A new request normally includes an ERC-20 approval, so simulating before that approval would only produce a false allowance failure. When the owner already has sufficient allowance, eth_call is the strongest admission check available for vault-specific Yearn limits. Transport failures are propagated instead of being reported as an admission rejection.

Parameters
  • owner (eth_typing.evm.HexAddress) – Account that has approved the vault and would submit the deposit.

  • raw_amount (int) – Native denomination-token amount to deposit.

Returns

A structured preflight rejection, or None if the caller has no sufficient allowance yet or the exact call succeeds.

Raises

ValueError – If the provider fails without EVM revert data.

Return type

Optional[eth_defi.vault.deposit_redeem.VaultFlowUnavailable]

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

Build a Yearn deposit or expose a predictable refusal before broadcast.

Parameters
  • owner (eth_typing.evm.HexAddress) – Account funding the assets and receiving shares.

  • to (Optional[eth_typing.evm.HexAddress]) – Unsupported separate receiver; inherited behaviour requires owner.

  • amount (Optional[decimal.Decimal]) – Decimal denomination-token amount.

  • raw_amount (Optional[int]) – Raw denomination-token amount.

  • check_max_deposit (bool) – Enable the normal global-closure and capacity preflight.

  • check_enough_token (bool) – Enable the inherited denomination-token balance preflight.

Returns

Production Yearn ERC-4626 deposit request.

Raises

VaultFlowUnavailable – When Yearn is shut down, its global deposit cap is full, or an already-approved exact deposit call is rejected.

Return type

eth_defi.erc_4626.deposit_redeem.ERC4626DepositRequest

create_deposit_request_for_guard_validation(owner, raw_amount)

Build Yearn deposit calldata after a proven global closure.

Parameters
  • owner (eth_typing.evm.HexAddress) – SimpleVaultV0/Safe address that would receive the Yearn shares.

  • raw_amount (int) – Raw denomination-token amount from the rejected live preflight.

Returns

Deposit calldata for non-broadcast GuardV0 validation.

Raises

UnsupportedVaultSimulation – If the vault has no proven global closure or provider is not Anvil.

Return type

eth_defi.erc_4626.deposit_redeem.ERC4626DepositRequest

__init__(vault)
Parameters

vault (ERC4626Vault) –

analyse_deposit(claim_tx_hash, deposit_ticket)

Analyse a mined ERC-4626 deposit or guarded SimpleVault wrapper.

A ticket permits a settlement call through a non-vault wrapper, such as a SimpleVault Safe or its module. The event analyser still filters events by the underlying vault address.

Parameters
Returns

Decoded executed deposit quantities or a revert description.

Return type

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

analyse_redemption(claim_tx_hash, redemption_ticket)

Analyse a mined ERC-4626 redemption or guarded SimpleVault wrapper.

A wrapper transaction may be synchronous or ticket-based. The decoded Withdraw event must still originate from this vault, regardless of whether the transaction targets the vault directly or guarded custody.

Parameters
Returns

Decoded executed redemption quantities or a revert description.

Return type

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

can_create_deposit_request(owner)

Can we start depositing now.

Vault can be full?

Parameters

owner (eth_typing.evm.HexAddress) –

Return type

bool

can_create_redemption_request(owner)

Gains allows request redepetion only two first days of three days epoch.

Returns

True if can create a redemption request now

Parameters

owner (eth_typing.evm.HexAddress) –

Return type

bool

can_finish_deposit(deposit_ticket)

Synchronous deposits can be finished immediately.

Parameters

deposit_ticket (eth_defi.erc_4626.deposit_redeem.ERC4626DepositTicket) –

can_finish_redeem(redemption_ticket)

Synchronous redemptions can be finished immediately.

Parameters

redemption_ticket (eth_defi.erc_4626.deposit_redeem.ERC4626RedemptionTicket) –

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_redemption_request(owner, to=None, shares=None, raw_shares=None, check_max_deposit=True, check_enough_token=True, check_max_redeem=True)

Create a redemption request.

Abstracts IPOR, Lagoon, Gains, other vault redemption flow.

See eth_defi.gains.vault.GainsVault for an example usage.

Flow

  1. create_redemption_request

  2. sign and broadcast the transaction

  3. parse success and redemption request id from the transaction

  4. wait until the redemption delay is over

  5. settle the redemption request

Parameters
Returns

Redemption request wrapper.

Return type

eth_defi.erc_4626.deposit_redeem.ERC4626RedemptionRequest

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
Returns

Request parser and original call shape.

Return type

eth_defi.vault.deposit_redeem.RedemptionRequest

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

How many shares we get for a deposit.

Parameters
Return type

decimal.Decimal

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

How many denomination tokens we get for a redeem.

Parameters
Return type

decimal.Decimal

estimate_redemption_delay()

Get the redemption delay for this vault.

  • What is overall redemption delay: not related to the current moment

  • How long it takes before a redemption request is allowed

  • This is not specific for any address, but the general vault rule

  • E.g. you get 0xa592703b is an IPOR Fusion error code AccountIsLocked, if you try to instantly redeem from IPOR vaults

Returns

Redemption delay as a datetime.timedelta

Raises

NotImplementedError – If not implemented for this vault protocoll.

Return type

datetime.timedelta

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]

finish_deposit(deposit_ticket)

Can we finish the deposit process in async vault.

  • We can claim our shares from the vault now

Parameters

deposit_ticket (eth_defi.vault.deposit_redeem.DepositTicket) –

Return type

web3.contract.contract.ContractFunction

finish_redemption(redemption_ticket)

Build the depositor-owned final redemption transaction when one exists.

Some asynchronous vaults, such as Ember, transfer funds directly from an operator transaction. They deliberately return None here: an asset manager must not attempt to invoke an operator-only settlement method on behalf of its depositor.

Parameters

redemption_ticket (eth_defi.vault.deposit_redeem.RedemptionTicket) – Persisted asynchronous redemption request.

Returns

Bound depositor claim call, or None when the protocol has no depositor-owned finish action.

Return type

web3.contract.contract.ContractFunction

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

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

Force the selected ticket forward on an Anvil simulation.

Synchronous managers do not require settlement and return a no-op result when called with None. Asynchronous managers must override this method and supply their request ticket.

Parameters
  • ticket (Optional[Union[eth_defi.vault.deposit_redeem.DepositTicket, eth_defi.vault.deposit_redeem.RedemptionTicket]]) – Pending async request ticket, or None for a synchronous flow.

  • mock (Optional[object]) – Optional deployed protocol mock used only by focused local tests. Concrete asynchronous managers may use it to execute their operator/keeper settlement path without broadening production Anvil-fork authority. Passing a mock to a manager that does not implement mock settlement remains a typed unsupported simulation.

  • ignore_liquidity (bool) – Permit a protocol-specific, Anvil-only mock or fork driver to bypass an otherwise unavailable redemption-liquidity gate. This base implementation defaults to False; a documented protocol override may choose a different Anvil-only default. Managers must reject this request unless they have a tested, explicit implementation; it must never weaken a production preflight or live settlement path.

Returns

Settlement outcome with before/after status and transaction hashes.

Raises

UnsupportedVaultSimulation – If the provider is not Anvil or an async manager lacks a driver.

Return type

eth_defi.vault.deposit_redeem.VaultForcedSettlementResult

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_max_deposit(owner)

How much we can deposit

Parameters

owner (eth_typing.evm.HexAddress) –

Return type

Optional[decimal.Decimal]

get_redemption_delay_over(address)

Get the redemption timer left for an address.

  • How long it takes before a redemption request is allowed

  • This is not specific for any address, but the general vault rule

  • E.g. you get 0xa592703b is an IPOR Fusion error code AccountIsLocked, if you try to instantly redeem from IPOR vaults

Returns

UTC timestamp when the account can redeem.

Naive datetime, or None when the protocol has no deterministic onchain deadline.

Raises

NotImplementedError – If not implemented for this vault protocoll.

Parameters

address (Union[eth_typing.evm.HexAddress, str]) –

Return type

datetime.datetime

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

has_synchronous_deposit()

Does this vault support synchronous deposits?

  • E.g. ERC-4626 vaults

Return type

bool

has_synchronous_redemption()

Keep ordinary ERC-4626 exits on the immediate execution path.

Request-level staging can still require a finish call, so callers also inspect requires_settlement.

Returns

True for the manager’s ordinary redemption capability.

Return type

bool

is_deposit_in_progress(owner)

Check if the owner has an active deposit request.

Parameters

owner (eth_typing.evm.HexAddress) – Owner of the shares

Returns

True if there is an active redemption request

Return type

bool

is_redemption_in_progress(owner)

Check if the owner has an active redemption request.

Parameters

owner (eth_typing.evm.HexAddress) – Owner of the shares

Returns

True if there is an active redemption request

Return type

bool

reclaim_deposit(ticket)

Return a function to recover funds after a failed async deposit settlement.

Returns None if the protocol does not support reclaim.

Parameters

ticket (eth_defi.vault.deposit_redeem.DepositTicket) –

Return type

Optional[web3.contract.contract.ContractFunction]

reclaim_withdrawal(ticket)

Return a function to recover shares after a failed async withdrawal settlement.

Returns None if the protocol does not support reclaim.

Parameters

ticket (eth_defi.vault.deposit_redeem.RedemptionTicket) –

Return type

Optional[web3.contract.contract.ContractFunction]

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.

The executor persists these fields before retrying settlement. Separate custody and disposal quantities keep retained shares from being mistaken for newly tradable shares or missing escrow.

Parameters

ticket (eth_defi.vault.deposit_redeem.RedemptionTicket) – Receipt-derived ticket, including shares still held in custody.

Returns

JSON-safe common fields with raw share amounts encoded as decimal strings.

Return type

dict