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

Add Gains-specific redemption logic.

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)	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.
`create_deposit_request`(owner[, to, amount, ...])
`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_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_settle`(ticket)	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)	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

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

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

redemption_request_ticket – Redemption request ticket from create_redemption_request()
redemption_ticket (eth_defi.erc_4626.vault_protocol.gains.deposit_redeem.GainsRedemptionTicket) –

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

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

analyse_deposit(claim_tx_hash, deposit_ticket)

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

A ticket identifies an expected SimpleVault wrapper by address. 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 whose owner identifies a guarded wrapper.

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 identifies the wrapper only for the transaction-target check; 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 whose owner identifies a guarded wrapper.

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

Synchronous deposits can be finished immediately.

Parameters: deposit_ticket (eth_defi.erc_4626.deposit_redeem.ERC4626DepositTicket) –

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

decimal.Decimal

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

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_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_settle(ticket)

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.
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 on-chain 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 on-chain 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 on-chain 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