D2DepositManager

Documentation for eth_defi.erc_4626.vault_protocol.d2.vault.D2DepositManager Python class.

class D2DepositManager

Bases: eth_defi.erc_4626.deposit_redeem.ERC4626DepositManager

D2 Finance epoch-gated ERC-4626 lifecycle with zero-price admission failure.

D2 vaults are managed derivative-strategy vaults that cycle through offchain-scheduled funding, trading (epoch) and withdrawal phases. Onchain deposits and redemptions use the standard synchronous ERC-4626 entry points, but they only succeed inside the correct phase. This manager keeps the plain ERC-4626 transaction construction of its parent while adding preflight phase gating and an explicit failure when D2 pricing is unavailable, so a caller sees an actionable VaultFlowUnavailable instead of paying gas for a guaranteed revert or trusting a zero estimate.

Deposit process

Synchronous. The owner approve()``s the denomination token and :meth:`create_deposit_request` builds a single ERC-4626 ``deposit call (inherited construction), but only after _assert_flow_open() confirms the vault is in its funding phase (isFunding()); otherwise it raises VaultFlowUnavailable carrying the next funding open time. estimate_deposit() overrides the parent: it first rejects a closed funding phase, then calls the standard previewDeposit-based estimator, and finally raises ValueError when the estimate is zero, because a zero share price means D2 pricing is undefined rather than that the deposit is free.

Redemption process

Synchronous. create_redemption_request() builds a single ERC-4626 redeem call (inherited construction) after _assert_flow_open() confirms redemptions are open — D2 permits withdrawal only when funds are not custodied and no epoch is running (notCustodiedAndNotDuringEpoch()). A closed window raises VaultFlowUnavailable with the next redemption open time.

Queues and settlement

No per-owner request queue: each deposit / redeem settles in its own transaction. The only gating is the vault-wide epoch phase, evaluated live from isFunding() and notCustodiedAndNotDuringEpoch(). Custodied epochs, operator NAV changes and delayed withdrawals are outside this adapter and are not modelled as tickets.

Lockups and cooldowns

No per-owner cooldown, but capital is effectively locked for the trading epoch: D2Vault.get_estimated_lock_up() reports the current epoch duration (epoch_end - epoch_start), which D2 documents as roughly 30-60 days. Deposits made during funding are custodied through the following trading epoch and can only be redeemed once the vault returns to a not-custodied, not-in-epoch state.

Deposit eligibility

The historical onlyWhitelisted modifier is not an identity/KYC gate: it also admits any account holding more than the public minimum balance of whitelistAsset. The lifecycle experiment funds that eligibility asset where necessary and reports a failed balance condition as flow availability, never as whitelisting-needed.

Anvil settlement (force_settle)

The standard deposit and redeem calls complete in their originating transaction, so the inherited force_settle() accepts None and performs the Anvil-validated shared no-op. This adapter improves preflight estimation and phase gating only; a successful D2 transaction path has not been fork-proven.

Attributes summary

web3

Methods summary

`__init__`(vault)
`analyse_deposit`(claim_tx_hash, deposit_ticket)	Analyse a mined ERC-4626 deposit or guarded SimpleVault wrapper.
`analyse_redemption`(claim_tx_hash, ...)	Analyse a mined ERC-4626 redemption or guarded SimpleVault wrapper.
`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)	Synchronous deposits can be finished immediately.
`can_finish_redeem`(redemption_ticket)	Synchronous redemptions can be finished immediately.
`check_deposit_whitelist`(owner)	Reject a deposit when the vault's whitelist excludes the owner.
`create_deposit_request`(owner[, to, amount, ...])	Build a deposit only during D2's funding phase.
`create_deposit_request_for_guard_validation`(...)	Build D2 deposit calldata while its funding epoch is closed.
`create_redemption_request`(owner[, to, ...])	Build a redemption only during D2's withdrawal window.
`estimate_deposit`(owner, amount[, ...])	Return an estimate or an actionable zero-price failure.
`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_depositable_raw_assets`(owner)	Read the vault's current raw deposit limit for an owner.
`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.

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

Return an estimate or an actionable zero-price failure.

Parameters

owner (Optional[eth_typing.evm.HexAddress]) – Deposit owner passed to the standard ERC-4626 estimator.
amount (decimal.Decimal) – Decimal denomination amount.
block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Block number or "latest".

Returns

Estimated decimal shares.

Raises

ValueError – If D2 pricing is undefined or the funding phase is closed.

Return type

decimal.Decimal

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

Build a deposit only during D2’s funding phase.

Arguments match the inherited ERC-4626 request interface so existing positional callers remain compatible.

Returns

Standard synchronous deposit request.

Raises

VaultFlowUnavailable – If the current D2 epoch is not accepting deposits.

Parameters

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

Return type

eth_defi.erc_4626.deposit_redeem.ERC4626DepositRequest

create_deposit_request_for_guard_validation(owner, raw_amount)

Build D2 deposit calldata while its funding epoch is closed.

This narrow diagnostic exception bypasses D2’s temporary funding window and denomination-token amount/balance checks so a caller can validate the exact manager-generated deposit call through GuardV0. D2’s separate mapping-or-eligibility-asset admission check still applies. It intentionally does not construct or validate an ERC-20 approval, nor prove an approval-before-deposit sequence: those checks add no evidence to a standalone validateCall() policy check and remain normal live simulation responsibilities.

Parameters

owner (eth_typing.evm.HexAddress) – SimpleVaultV0/Safe address that would submit the D2 deposit.
raw_amount (int) – Raw D2 denomination-token amount from the rejected preflight.

Returns

One standard ERC-4626 deposit call for isolated GuardV0 validation.

Raises

VaultFlowUnavailable – If the owner does not meet a public eligibility-asset minimum.
WhitelistingRequired – If a mapping-only deployment does not admit the owner.

Return type

eth_defi.erc_4626.deposit_redeem.ERC4626DepositRequest

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

Build a redemption only during D2’s withdrawal window.

Arguments match the inherited ERC-4626 request interface so existing positional callers remain compatible.

Returns

Standard synchronous redemption request.

Raises

VaultFlowUnavailable – If the current D2 epoch is not accepting redemptions.

Parameters

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

Return type

eth_defi.erc_4626.deposit_redeem.ERC4626RedemptionRequest

__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 ticket permits a non-vault transaction target for a guarded settlement; the decoded Withdraw event must still originate from this vault.

Parameters

claim_tx_hash (Union[hexbytes.main.HexBytes, str]) – Mined redemption transaction hash.
redemption_ticket (Optional[eth_defi.vault.deposit_redeem.RedemptionTicket]) – Optional ticket for a guarded non-vault call.

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

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

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

Read the vault’s current raw deposit limit for an owner.

Overridable deposit-limit hook. The base implementation reads the standard ERC-4626 maxDeposit(). Multi-asset or non-standard vaults that do not implement maxDeposit (for example Upshift’s multi-asset vault) override this to answer from their own limit reader, so the deposit preflight does not depend on the ERC-4626 method being present.

Parameters: owner (eth_typing.evm.HexAddress) – Account the deposit limit is queried for.
Returns: Raw deposit limit, or None when the vault exposes no limit. A zero maxDeposit is omitted from this owner-specific capacity hook (EIP-4626 is not universally honoured), consistent with eth_defi.erc_4626.flow.deposit_4626(). The normal deposit preflight separately recognises a meaningful global zero through ERC4626Vault.fetch_deposit_closed_reason().
Raises: VaultFlowUnavailable – When the vault does not expose a readable ERC-4626 maxDeposit and no protocol-specific override is provided, instead of leaking a raw web3 ABI/read error.
Return type: Optional[int]

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

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

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

Does this vault support synchronous deposits?

E.g. ERC-4626 vaults

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.

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