VaultDepositManager

Documentation for eth_defi.vault.deposit_redeem.VaultDepositManager Python class.

class VaultDepositManager

Bases: abc.ABC

Abstract base for every vault deposit and redemption flow.

New public manager integrations must follow eth_defi/erc_4626/README-vault-protocol-support.md: a manager is supported only after its complete lifecycle executes through GuardV0 on an Anvil fork, with a protocol-shaped mock where fork state cannot cover a required path.

A deposit manager wraps one VaultBase and hides the differences between synchronous ERC-4626 vaults, asynchronous ERC-7540 vaults, and protocol-specific variants (Lagoon, Gains, IPOR, Ember, cSigma, and others) behind one request/settle/claim interface. This base class is policy-agnostic: it defines the contract and provides only the shared whitelist preflight and the Anvil no-op settlement; concrete subclasses supply the actual onchain behaviour.

Deposit process

A deposit is built with create_deposit_request(), which returns a DepositRequest wrapper of one or more transactions to sign and broadcast. The flow may be synchronous or asynchronous depending on the subclass — has_synchronous_deposit() reports which. The owner must first approve() the ERC-20 denomination token to the spender returned by get_deposit_approval_target() (the vault address by default). For a synchronous vault the request transaction mints shares immediately to the receiver. For an asynchronous vault the request transaction only registers a request; the shares are later claimed once settled via can_finish_deposit() and finish_deposit(). The receiver defaults to owner; a separate to receiver is only honoured where the protocol supports it. Progress is tracked with a DepositTicket.

Redemption process

A redemption is built with create_redemption_request(), returning a RedemptionRequest wrapper. has_synchronous_redemption() reports whether the flow is synchronous (shares burned and assets returned in the request transaction) or asynchronous (request now, settle, then claim). The asynchronous lifecycle is: create the request, broadcast, parse the resulting RedemptionTicket, wait for the redemption delay or operator settlement, then claim with finish_redemption(). Some operator-finalised protocols pay the receiver directly and return None from finish_redemption(); fetch_completed_redemption_tx_hash() locates that terminal transaction instead. A request is identified by its RedemptionTicket (owner, receiver, raw shares, request transaction hash, and a protocol request id via RedemptionTicket.get_request_id()).

Queues and settlement

Asynchronous protocols queue pending requests and settle them off the common interface (epoch rollovers, an operator/curator transaction, a settlement silo, etc.); get_deposit_request_status() and get_redemption_request_status() map protocol state onto AsyncVaultRequestStatus (none/pending/claimable/ reclaimable), and fetch_vault_flow_events() streams pending requests from an indexed backend. Synchronous subclasses have no queue: the request transaction is the settlement.

Lockups and cooldowns

Any lockup, cooldown, redemption delay or epoch window is protocol-specific. estimate_redemption_delay() returns the vault-wide delay (not account-specific), and get_redemption_delay_over() returns the naive UTC time an account may claim, or None when there is no deterministic onchain deadline. can_create_redemption_request() reflects windows such as an epoch that only accepts requests on some days. Synchronous subclasses report a zero delay.

Whitelisting / access control

Deposit admission is enforced by check_deposit_whitelist(), the shared preflight that every subclass must call before returning a request. It raises WhitelistingRequired only when the vault’s whitelist policy is applicable and queryable and the owner is provably not admitted; when the policy cannot be determined it stays silent and lets a genuine denial surface as an onchain revert. Subclasses needing a stricter fail-closed policy may additionally raise VaultFlowUnavailable.

Anvil settlement (force_settle)

force_settle() advances a pending ticket on an Anvil fork for integration tests. It requires an Anvil provider. For synchronous managers it is a no-op (called with None, returns a not-settlement-required result) because the request transaction already completed the lifecycle. Asynchronous managers must override it with a protocol-specific driver; the base raises UnsupportedVaultSimulation when no safe driver exists. ignore_liquidity=False preserves a real-liquidity simulation. An explicitly documented protocol driver may override the default to enable an Anvil-only liquidity-bypass simulation; its result must mark VaultForcedSettlementResult.liquidity_constraints_ignored; it is never live redemption evidence or a way to bypass production preflights.

Attributes summary

web3

Methods summary

`__init__`(vault)
`analyse_deposit`(claim_tx_hash, deposit_ticket)	Analyse the transaction where we claim shares
`analyse_redemption`(claim_tx_hash, ...)	Analyse the transaction where we claim our capital back.
`can_create_deposit_request`(owner)	Can we start depositing now.
`can_create_redemption_request`(owner)	Gains allows request redepetion only two first days of three days epoch.
`can_finish_deposit`(deposit_ticket)	Can we finish the deposit process in async reposits
`can_finish_redeem`(redemption_ticket)	Check if the redemption request can be redeemed now.
`check_deposit_whitelist`(owner)	Reject a deposit when the vault's whitelist excludes the owner.
`create_deposit_request`(owner[, to, amount, ...])	Build the deposit request transaction(s) for an owner.
`create_deposit_request_for_guard_validation`(...)	Build deposit calldata for a closed-vault GuardV0 policy check.
`create_redemption_request`(owner, to[, ...])	Create a redemption request.
`estimate_deposit`(owner, amount[, ...])	How many shares we get for a deposit.
`estimate_redeem`(owner, shares[, ...])	How many denomination tokens we get for a redeem.
`estimate_redemption_delay`()	Get the redemption delay for this vault.
`fetch_completed_redemption_tx_hash`(ticket)	Find an operator-owned terminal redemption transaction when available.
`fetch_vault_flow_events`(hypersync_client, ...)	Fetch asynchronous vault request events from an indexed backend.
`finish_deposit`(deposit_ticket)	Can we finish the deposit process in async vault.
`finish_redemption`(redemption_ticket)	Build the depositor-owned final redemption transaction when one exists.
`force_redemption_liquidity`(owner, ...)	Provision an unavailable synchronous redemption on an Anvil fork.
`force_settle`(ticket, *[, mock, ignore_liquidity])	Force the selected ticket forward on an Anvil simulation.
`get_deposit_approval_target`()	Return the ERC-20 spender required for a deposit request.
`get_deposit_delay_over`(address)	Estimate when a pending async deposit request will settle.
`get_deposit_request_status`(ticket)	Query the current status of an async deposit request.
`get_max_deposit`(owner)	How much we can deposit
`get_redemption_delay_over`(address)	Get the redemption timer left for an address.
`get_redemption_request_status`(ticket)	Query the current status of an async redemption request.
`has_synchronous_deposit`()	Does this vault support synchronous deposits?
`has_synchronous_redemption`()	Does this vault support synchronous deposits?
`is_deposit_in_progress`(owner)	Check if the owner has an active deposit request.
`is_redemption_in_progress`(owner)	Check if the owner has an active redemption request.
`reclaim_deposit`(ticket)	Return a function to recover funds after a failed async deposit settlement.
`reclaim_withdrawal`(ticket)	Return a function to recover shares after a failed async withdrawal settlement.
`reconstruct_deposit_ticket`(data)	Reconstruct a deposit ticket from a serialised dict.
`reconstruct_redemption_ticket`(data)	Reconstruct a redemption ticket from a serialised dict.
`serialize_deposit_ticket`(ticket)	Serialise a deposit ticket to a dict for persistence.
`serialize_redemption_ticket`(ticket)	Serialise a redemption ticket to a dict for persistence.

__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

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

eth_defi.vault.deposit_redeem.VaultForcedSettlementResult

abstract has_synchronous_deposit()

Does this vault support synchronous deposits?

E.g. ERC-4626 vaults

Return type: bool

abstract has_synchronous_redemption()

Does this vault support synchronous deposits?

E.g. ERC-4626 vaults

Return type: bool

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

How many shares we get for a 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

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

How many denomination tokens we get for a redeem.

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

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

Build the deposit request transaction(s) for an owner.

Abstracts the ERC-4626, ERC-7540, Lagoon and other protocol deposit flows behind a common request wrapper.

Whitelisting contract: implementations must raise WhitelistingRequired before returning a request when the vault applies a deposit whitelist policy, that policy is applicable and queryable, and owner is not permitted to deposit. Call check_deposit_whitelist() at the start of the preflight to satisfy this contract. When the whitelist information cannot be obtained (the adapter’s whitelist reads raise NotImplementedError) the manager must not raise WhitelistingRequired; it either proceeds — letting any real denial surface as an onchain revert — or fails closed with a plain VaultFlowUnavailable when unknown admission is unsafe.

Parameters

owner (eth_typing.evm.HexAddress) – Deposit owner and controller.
to (eth_typing.evm.HexAddress) – Optional separate receiver, where the protocol supports it.
amount (decimal.Decimal) – Human-readable denomination-token amount, converted using the denomination token decimals when raw_amount is not given.
raw_amount (int) – Raw denomination-token amount, overriding amount.
check_max_deposit – Preflight the deposit against the vault’s deposit capacity.
check_enough_token – Preflight that owner holds enough denomination token.

Returns

Deposit request wrapper ready for signing and parsing.

Raises

WhitelistingRequired – If the vault whitelist is applicable and excludes owner.
VaultFlowUnavailable – If the deposit cannot be safely prepared before broadcast.

Return type

eth_defi.vault.deposit_redeem.DepositRequest

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

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

Create a redemption request.

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

See eth_defi.gains.vault.GainsVault for 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

eth_defi.vault.deposit_redeem.RedemptionRequest

abstract 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

abstract 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

can_create_deposit_request(owner)

Can we start depositing now.

Vault can be full?

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

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

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]

get_max_deposit(owner)

How much we can deposit

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

abstract 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

abstract can_finish_redeem(redemption_ticket)

Check if the redemption request can be redeemed now.

Phase 2 of redemption, after settlement

Parameters: redemption_ticket (eth_defi.vault.deposit_redeem.RedemptionTicket) – Redemption redemption_ticket ticket from create_redemption_request()
Returns: True if can be redeemed now
Return type: bool

abstract can_finish_deposit(deposit_ticket)

Can we finish the deposit process in async reposits

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

abstract 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

abstract 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: Optional[web3.contract.contract.ContractFunction]

abstract 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

abstract 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

Optional[datetime.datetime]

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]

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]

abstract analyse_deposit(claim_tx_hash, deposit_ticket)

Analyse the transaction where we claim shares

Return information of the actual executed price for which we got the shares for

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]

abstract analyse_redemption(claim_tx_hash, redemption_ticket)

Analyse the transaction where we claim our capital back.

Return information of the actual executed price for which we got the shares for

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]

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

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

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

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

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

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]