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
Recognise Yearn V3 closures and rejected approved deposits. |
- class YearnV3DepositManager
Bases:
eth_defi.erc_4626.deposit_redeem.ERC4626DepositManagerRecognise 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-widedeposit_limit; an owner-specific zeromaxDepositthen 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 exactdeposit()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
Nonewhen the state is open or a per-account deposit-limit module prevents a safe determination.- Return type
- 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
- 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_callis 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
Noneif 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.
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
- 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
- __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
claim_tx_hash (Union[hexbytes.main.HexBytes, str]) – Mined deposit transaction hash.
deposit_ticket (Optional[eth_defi.vault.deposit_redeem.DepositTicket]) – Optional ticket for a guarded non-vault call.
- 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
Withdrawevent must still originate from this vault, regardless of whether the transaction targets the vault directly or guarded custody.- Parameters
claim_tx_hash (Union[hexbytes.main.HexBytes, str]) – Mined redemption transaction hash.
redemption_ticket (Optional[eth_defi.vault.deposit_redeem.RedemptionTicket]) – Optional queued or staged request ticket. Custody wrapping does not require a ticket.
- 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
- 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
- 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
owneris not a member of it, raiseWhitelistingRequiredbefore 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()raisesNotImplementedError, 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()raisesNotImplementedError, 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
WhitelistingRequiredraised.
Adapters that need a stricter fail-closed policy for an unknown admission state should override their own preflight and raise
VaultFlowUnavailablein 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
owneris 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.GainsVaultfor an example usage.Flow
create_redemption_request
sign and broadcast the transaction
parse success and redemption request id from the transaction
wait until the redemption delay is over
settle the redemption request
- Parameters
owner (eth_typing.evm.HexAddress) – Deposit owner.
shares (decimal.Decimal) –
Share amount in decimal.
Will be converted to raw_shares using share_token decimals.
raw_shares (int) – Raw amount in share token
to (eth_typing.evm.HexAddress) –
- Returns
Redemption request wrapper.
- Return type
- 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
- estimate_deposit(owner, amount, block_identifier='latest')
How many shares we get for a deposit.
- Parameters
owner (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
- estimate_redeem(owner, shares, block_identifier='latest')
How many denomination tokens we get for a redeem.
- Parameters
owner (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
- 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
- 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
Noneif 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
Noneto value ordinary shares.- Return type
- 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
- 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
Nonehere: 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
Nonewhen 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
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
- 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
- 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
- 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-uitable).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
Nonewhen no onchain estimate is available.- Return type
- 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. distinguishingreclaimablefrompending).- Parameters
ticket (eth_defi.vault.deposit_redeem.DepositTicket) –
- Return type
- get_max_deposit(owner)
How much we can deposit
- Parameters
owner (eth_typing.evm.HexAddress) –
- Return type
- 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
Nonewhen 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
- 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
- Return type
- has_synchronous_deposit()
Does this vault support synchronous deposits?
E.g. ERC-4626 vaults
- Return type
- 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
- 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
- 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
- reclaim_deposit(ticket)
Return a function to recover funds after a failed async deposit settlement.
Returns
Noneif 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
Noneif the protocol does not support reclaim.- Parameters
- 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
- 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
NotImplementedErrorbecauseRedemptionTickethas abstract methods.- Parameters
data (dict) –
- Return type
- serialize_deposit_ticket(ticket)
Serialise a deposit ticket to a dict for persistence.
The trade-executor stores this in
trade.other_dataso that the settlement retry module can reconstruct the ticket after a process restart.Default implementation stores base
DepositTicketfields. Subclasses override to add protocol-specific fields (e.g.settlement_idfor Ostium,requestIdfor ERC-7540).- Parameters
ticket (eth_defi.vault.deposit_redeem.DepositTicket) –
- Return type
- serialize_redemption_ticket(ticket)
Serialise a redemption ticket to a dict for persistence.
Default implementation stores base
RedemptionTicketfields. 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