GainsDepositManager

Documentation for eth_defi.erc_4626.vault_protocol.gains.deposit_redeem.GainsDepositManager Python class.

class GainsDepositManager

Bases: eth_defi.erc_4626.deposit_redeem.ERC4626DepositManager

Gains gToken adapter: synchronous deposits, epoch-gated redemptions.

Gains Network gToken vaults keep standard ERC-4626 deposits but replace redemption with a two-phase, epoch-locked withdrawal request. See the gToken vault notes.

Deposit process. Synchronous. Deposits use the inherited ERC-4626 deposit path (standard ERC-20 approve of the denomination token then deposit); shares are minted in the same transaction. can_create_deposit_request() always returns True — the vault is permanently open for deposits (caps are enforced by the contract itself).

Redemption process. Asynchronous, two phase. create_redemption_request() builds makeWithdrawRequest(shares, owner), which locks the shares and emits WithdrawRequested(shares, currEpoch, unlockEpoch). The epoch pair is read from that event by GainsRedemptionRequest.parse_redeem_transaction() and stored in a GainsRedemptionTicket. Once the current epoch reaches unlockEpoch (can_finish_redeem()), the owner claims by calling ERC-4626 redeem(shares, to, owner) returned by finish_redemption(). There is no per-request settlement id; the ticket is tracked purely by its epoch numbers.

Queues and settlement. Settlement is epoch rollover rather than an operator queue. New withdrawal requests are only accepted while the open-PnL feed reports nextEpochValuesRequestCount() == 0 (can_create_redemption_request()); outside that window makeWithdrawRequest reverts EndOfEpoch (END_OF_EPOCH_SELECTOR), surfaced here as a typed VaultFlowUnavailable preflight refusal. Epochs advance through the permissionless forceNewEpoch() on the open-PnL feed contract.

Lockups and cooldowns. Withdrawal requests may only be created in the first part of each (roughly three-day) epoch, and the locked shares unlock only once the current epoch reaches the ticket’s unlockEpoch. estimate_redemption_delay() estimates the wait as requestsStart + requestsEvery * requestsCount seconds from the open-PnL feed configuration.

Whitelisting / access control. Permissionless — Gains gToken vaults apply no deposit whitelist or per-account access check.

Anvil settlement (force_settle). force_settle() requires an Anvil provider. No impersonation is needed: it warps Anvil time and calls the permissionless forceNewEpoch() from a funded account via force_next_gains_epoch(), repeating up to GAINS_MAX_SETTLEMENT_EPOCHS times until the ticket unlocks (current_epoch >= unlock_epoch), i.e. status moves pending -> claimable. Each iteration asserts the epoch strictly increased; if the epoch stalls or never unlocks it raises UnsupportedVaultSimulation rather than reporting a false success.

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 Gains claim independently of its outer transaction wrapper.

can_create_deposit_request(owner)

Vault is always open for deposits.

can_create_redemption_request(owner)

Gains allows request redemptioon only two first dayas of three days epoch.

can_finish_deposit(deposit_ticket)

Synchronous deposits can be finished immediately.

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 ERC-4626 deposit calldata after a proven global closure.

create_redemption_request(owner[, to, ...])

Build a redeem transction.

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

Advance the Gains epoch on Anvil until a redemption ticket unlocks.

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)

Rebuild a Gains redemption ticket from persistent JSON data.

serialize_deposit_ticket(ticket)

Serialise a deposit ticket to a dict for persistence.

serialize_redemption_ticket(ticket)

Serialise Gains' epoch fields alongside the base ticket data.
__init__(vault)
Parameters

vault (eth_defi.gains.vault.GainsVault) –

can_create_deposit_request(owner)

Vault is always open for deposits.

Parameters

owner (eth_typing.evm.HexAddress) –

Return type

bool

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

Build a redeem transction.

Note

Withdrawal requests can only be executed in the first 2 days of each epoch.

Notes on Gains / Ostium withdrawals.

Parameters
Return type

eth_defi.erc_4626.vault_protocol.gains.deposit_redeem.GainsRedemptionRequest

can_create_redemption_request(owner)

Gains allows request redemptioon only two first dayas of three days epoch.

Returns

True if can create a redemption request now

Parameters

owner (eth_typing.evm.HexAddress) –

Return type

bool

can_finish_redeem(redemption_ticket)

Check if the redemption request can be redeemed now.

  • Phase 2 of redemption, after settlement

Parameters
Returns

True if can be redeemed now

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.erc_4626.vault_protocol.gains.deposit_redeem.GainsRedemptionTicket) – 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

analyse_redemption(claim_tx_hash, redemption_ticket)

Analyse a Gains claim independently of its outer transaction wrapper.

Lagoon and other guarded vaults submit the claim through a module, so the outer transaction target is neither the Gains vault nor the share owner. The protocol’s canonical Withdraw event is the authoritative evidence: it must originate from this Gains vault and match the persisted ticket owner, receiver and share amount.

Parameters
Returns

Executed redemption amounts or a structured transaction failure.

Return type

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

serialize_redemption_ticket(ticket)

Serialise Gains’ epoch fields alongside the base ticket data.

The redemption lifecycle survives a process restart only when both epoch numbers are retained: they determine when finish_redemption becomes available.

Parameters

ticket (eth_defi.erc_4626.vault_protocol.gains.deposit_redeem.GainsRedemptionTicket) – Gains epoch redemption ticket to persist.

Returns

JSON-compatible base and epoch ticket fields.

Return type

dict

reconstruct_redemption_ticket(data)

Rebuild a Gains redemption ticket from persistent JSON data.

Parameters

data (dict) – JSON-compatible data previously returned by serialize_redemption_ticket().

Returns

Ticket suitable for status checks and later redemption.

Return type

eth_defi.erc_4626.vault_protocol.gains.deposit_redeem.GainsRedemptionTicket

has_synchronous_redemption()

Does this vault support synchronous deposits?

  • E.g. ERC-4626 vaults

Return type

bool

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

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

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

Advance the Gains epoch on Anvil until a redemption ticket unlocks.

Gains redemptions unlock after a fixed number of epochs. Epoch rollover is driven by the permissionless forceNewEpoch() on the open-PnL feed, so no privileged impersonation is required — the driver warps Anvil time and calls it from a funded account via force_next_gains_epoch().

Each iteration asserts the epoch strictly increases; if forceNewEpoch mines time but the epoch does not advance (for example an oracle/keeper dependency on some deployments) the driver raises UnsupportedVaultSimulation rather than looping or returning a false “settled”.

Parameters
Returns

Settlement outcome with before/after status and the epoch-forcing transaction hashes.

Raises

UnsupportedVaultSimulation – If the provider is not Anvil, the epoch fails to advance, or the ticket does not become redeemable within the safety cap.

Return type

eth_defi.vault.deposit_redeem.VaultForcedSettlementResult

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]

can_finish_deposit(deposit_ticket)

Synchronous deposits can be finished immediately.

Parameters

deposit_ticket (eth_defi.erc_4626.deposit_redeem.ERC4626DepositTicket) –

check_deposit_whitelist(owner)

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

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

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

  • if is_whitelisted_deposit() raises NotImplementedError, the vault-wide policy cannot be determined for this adapter/version, so no exception is raised;

  • if the vault is permissionless, no exception is raised;

  • if is_account_whitelisted() raises NotImplementedError, per-account membership cannot be queried, so no exception is raised;

  • only when the policy is applicable and the owner is provably not admitted is WhitelistingRequired raised.

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

Parameters

owner (eth_typing.evm.HexAddress) – Deposit owner and controller whose whitelist membership is checked.

Raises

WhitelistingRequired – When the vault applies an applicable, queryable whitelist policy and owner is not permitted to deposit.

Return type

None

create_deposit_request(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
Return type

eth_defi.erc_4626.deposit_redeem.ERC4626DepositRequest

create_deposit_request_for_guard_validation(owner, raw_amount)

Build ERC-4626 deposit calldata after a proven global closure.

This Anvil-only diagnostic path is available only when the selected vault’s authoritative global closure reader reports that deposits are unavailable to every account. It preserves the normal protocol admission preflight and all permanent amount constraints, while omitting the temporary closed-deposit capacity and token-balance checks needed to encode the production-equivalent deposit call.

Parameters

  • owner (eth_typing.evm.HexAddress) – Safe/SimpleVault address that would own the minted shares.

  • raw_amount (int) – Raw denomination-token amount from the rejected real-deposit attempt.

Returns

Single ERC-4626 deposit request for isolated GuardV0 validation.

Raises
Return type

eth_defi.erc_4626.deposit_redeem.ERC4626DepositRequest

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

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

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

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

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

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

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