erc_4626.vault_protocol.gains.deposit_redeem

Documentation for eth_defi.erc_4626.vault_protocol.gains.deposit_redeem Python module.

Deposit and redeem flow for GToken-like vaults.

Supports both Gains V1 (epoch-based) and Ostium V1.5 (settlement-based) flows.

Module Attributes

OSTIUM_V15_UPGRADE_BLOCK

Arbitrum block number at which the Ostium vault was upgraded to V1.5.

OSTIUM_REQUEST_STATUS_NONE

Ostium V1.5 RequestStatus enum values

Classes

GainsDepositManager

Add Gains-specific redemption logic.

GainsRedemptionRequest

Wrap Gains makeWithdrawRequest() call.

GainsRedemptionTicket

Gains redemption ticket details.

OstiumDepositRequest

Wraps Ostium V1.5 requestDeposit(uint256 assets) call.

OstiumDepositTicket

Tracks an in-progress Ostium V1.5 async deposit request.

OstiumRedemptionRequest

Wraps Ostium V1.5 requestWithdraw(uint256 shares) call.

OstiumRedemptionTicket

Tracks an in-progress Ostium V1.5 async withdrawal request.

OstiumV15DepositManager

Async deposit/redemption manager for Ostium V1.5 settlement-based flow.

Exceptions

OstiumSettlementFailed

Raised when an Ostium V1.5 settlement resulted in RECLAIMABLE status.
class GainsRedemptionTicket

Bases: eth_defi.vault.deposit_redeem.RedemptionTicket

Gains redemption ticket details.

__init__(vault_address, owner, to, raw_shares, tx_hash, current_epoch, unlock_epoch)
Parameters
Return type

None

abstract get_request_id()

Get the redemption request id.

  • If vault uses some sort of request ids to track the withdrawals

  • Needed for settlement

Return type

int

class GainsRedemptionRequest

Bases: eth_defi.vault.deposit_redeem.RedemptionRequest

Wrap Gains makeWithdrawRequest() call.

  • Revert reason: execution reverted: custom error 0xa73449b9: EndOfEpoch

See errors at:

parse_redeem_transaction(tx_hashes)

Parse the transaction receipt to get the actual shares redeemed.

  • Assumes only one redemption request per vault per transaction

Parameters

tx_hashes (list[hexbytes.main.HexBytes]) –

Return type

eth_defi.erc_4626.vault_protocol.gains.deposit_redeem.GainsRedemptionTicket

__init__(vault, owner, to, shares, raw_shares, funcs)
Parameters
Return type

None

broadcast(from_=None, gas=1000000)

Broadcast all the transactions in this request.

Parameters
Returns

List of transaction hashes

Return type

list[hexbytes.main.HexBytes]

class GainsDepositManager

Bases: eth_defi.erc_4626.deposit_redeem.ERC4626DepositManager

Add Gains-specific redemption logic.

__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

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

OSTIUM_V15_UPGRADE_BLOCK = 457238658

Arbitrum block number at which the Ostium vault was upgraded to V1.5. The proxy at 0x20D419a8e12C45f88fDA7c5760bb6923Cee27F98 was upgraded to implementation 0xd2619e2012a120504e043f61c8acb3ede2472bf7 in this tx: https://arbiscan.io/tx/0x3f25d52219c7a9b2469ac3582c6664940ede80da361b987bad6cab6336619363

exception OstiumSettlementFailed

Bases: Exception

Raised when an Ostium V1.5 settlement resulted in RECLAIMABLE status.

The user should call reclaimDeposit(settlementId) or reclaimWithdraw(settlementId) to recover their funds.

__init__(*args, **kwargs)
__new__(**kwargs)
add_note(note, /)

Add a note to the exception

with_traceback(tb, /)

Set self.__traceback__ to tb and return self.

OSTIUM_REQUEST_STATUS_NONE = 0

Ostium V1.5 RequestStatus enum values

class OstiumDepositTicket

Bases: eth_defi.vault.deposit_redeem.DepositTicket

Tracks an in-progress Ostium V1.5 async deposit request.

The settlement_id is extracted from the DepositRequestedV2 event.

settlement_id: int

Settlement ID for this deposit request

__init__(vault_address, owner, to, raw_amount, tx_hash, gas_used, block_number, block_timestamp, settlement_id)
Parameters
Return type

None

class OstiumRedemptionTicket

Bases: eth_defi.vault.deposit_redeem.RedemptionTicket

Tracks an in-progress Ostium V1.5 async withdrawal request.

The settlement_id is extracted from the WithdrawRequestedV2 event.

settlement_id: int

Settlement ID for this withdrawal request

get_request_id()

Get the redemption request id.

  • If vault uses some sort of request ids to track the withdrawals

  • Needed for settlement

Return type

int

__init__(vault_address, owner, to, raw_shares, tx_hash, settlement_id)
Parameters
Return type

None

class OstiumDepositRequest

Bases: eth_defi.vault.deposit_redeem.DepositRequest

Wraps Ostium V1.5 requestDeposit(uint256 assets) call.

After broadcasting, parse the transaction to extract the settlement_id from the DepositRequestedV2 event.

parse_deposit_transaction(tx_hashes)

Parse the DepositRequestedV2 event from requestDeposit() transaction.

DepositRequestedV2(address indexed owner, uint32 indexed settlementId, uint256 assets)

Parameters

tx_hashes (list[hexbytes.main.HexBytes]) –

Return type

eth_defi.erc_4626.vault_protocol.gains.deposit_redeem.OstiumDepositTicket

__init__(vault, owner, to, amount, raw_amount, funcs, gas=None, value=None)
Parameters
Return type

None

broadcast(from_=None, gas=None, check_value=True)

Broadcast all the transactions in this request.

Parameters
Returns

List of transaction hashes

Raises

TransactionAssertionError – If any of the transactions revert

Return type

eth_defi.vault.deposit_redeem.RedemptionTicket

class OstiumRedemptionRequest

Bases: eth_defi.vault.deposit_redeem.RedemptionRequest

Wraps Ostium V1.5 requestWithdraw(uint256 shares) call.

After broadcasting, parse the transaction to extract the settlement_id from the WithdrawRequestedV2 event.

parse_redeem_transaction(tx_hashes)

Parse the WithdrawRequestedV2 event from requestWithdraw() transaction.

WithdrawRequestedV2(address indexed owner, uint32 indexed settlementId, uint256 shares)

Parameters

tx_hashes (list[hexbytes.main.HexBytes]) –

Return type

eth_defi.erc_4626.vault_protocol.gains.deposit_redeem.OstiumRedemptionTicket

__init__(vault, owner, to, shares, raw_shares, funcs)
Parameters
Return type

None

broadcast(from_=None, gas=1000000)

Broadcast all the transactions in this request.

Parameters
Returns

List of transaction hashes

Return type

list[hexbytes.main.HexBytes]

class OstiumV15DepositManager

Bases: eth_defi.erc_4626.deposit_redeem.ERC4626DepositManager

Async deposit/redemption manager for Ostium V1.5 settlement-based flow.

V1.5 disables ERC-4626 deposit(), mint(), withdraw(), redeem() and replaces them with:

  • Deposits: requestDeposit(assets) -> settlement -> claimDeposit(settlementId)

  • Withdrawals: requestWithdraw(shares) -> settlement -> claimWithdraw(settlementId)

Settlement happens via tryNewSettlement() (public, permissionless) once maxSettlementInterval has elapsed after the previous settlement.

The is_deposit_in_progress() / is_redemption_in_progress() methods only check the current targetSettlementId. For checking specific tickets regardless of the current settlement, use get_deposit_ticket_status() / get_redemption_ticket_status().

__init__(vault)
Parameters

vault (eth_defi.erc_4626.vault_protocol.gains.vault.OstiumVault) –

fetch_vault_flow_events(hypersync_client, start_block, end_block)

Fetch Ostium V1.5 request events using Hypersync.

Ostium V1.5 emits concrete settlement ids in DepositRequestedV2 and WithdrawRequestedV2 events. These ids are stable enough to reconstruct the same tickets that live transaction parsing produces.

Parameters

  • hypersync_client – Configured Hypersync client for Arbitrum.

  • start_block (int) – Inclusive start block.

  • end_block (int) – Inclusive end block.

Returns

Iterator of indexed pending vault flow events in chain order.

Return type

collections.abc.Iterator[eth_defi.vault.flow_events.PendingVaultFlow]

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

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

Create an async deposit request via requestDeposit(assets).

  1. USDC is transferred to the vault immediately

  2. Request is queued for the next settlement

  3. After settlement, shares can be claimed via claimDeposit(settlementId)

Parameters
Return type

eth_defi.erc_4626.vault_protocol.gains.deposit_redeem.OstiumDepositRequest

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

Create an async withdrawal request via requestWithdraw(shares).

  1. OLP shares are transferred to the vault immediately

  2. Request is queued for settlement

  3. After settlement, USDC can be claimed via claimWithdraw(settlementId)

Parameters
Return type

eth_defi.erc_4626.vault_protocol.gains.deposit_redeem.OstiumRedemptionRequest

can_finish_deposit(deposit_ticket)

Check if a deposit can be claimed after settlement.

Raises

OstiumSettlementFailed – If the settlement resulted in RECLAIMABLE status. Call reclaim_deposit() to recover funds.

Parameters

deposit_ticket (eth_defi.erc_4626.vault_protocol.gains.deposit_redeem.OstiumDepositTicket) –

Return type

bool

can_finish_redeem(redemption_ticket)

Check if a withdrawal can be claimed after settlement.

Raises

OstiumSettlementFailed – If the settlement resulted in RECLAIMABLE status. Call reclaim_withdrawal() to recover shares.

Parameters

redemption_ticket (eth_defi.erc_4626.vault_protocol.gains.deposit_redeem.OstiumRedemptionTicket) –

Return type

bool

finish_deposit(deposit_ticket)

Return claimDeposit(settlementId) bound function.

Parameters

deposit_ticket (eth_defi.erc_4626.vault_protocol.gains.deposit_redeem.OstiumDepositTicket) –

Return type

web3.contract.contract.ContractFunction

finish_redemption(redemption_ticket)

Return claimWithdraw(settlementId) bound function.

Parameters

redemption_ticket (eth_defi.erc_4626.vault_protocol.gains.deposit_redeem.OstiumRedemptionTicket) –

Return type

web3.contract.contract.ContractFunction

can_create_deposit_request(owner)

V1.5 deposits are always accepted (caps enforced at settlement, not request).

Parameters

owner (eth_typing.evm.HexAddress) –

Return type

bool

can_create_redemption_request(owner)

V1.5 withdrawals can be requested any time (no epoch window restriction).

Parameters

owner (eth_typing.evm.HexAddress) –

Return type

bool

is_deposit_in_progress(owner)

Check if owner has a pending deposit for the current target settlement.

Only checks the current targetSettlementId(true). For checking a specific ticket’s settlement, use get_deposit_ticket_status().

Parameters

owner (eth_typing.evm.HexAddress) –

Return type

bool

is_redemption_in_progress(owner)

Check if owner has a pending withdrawal for the current target settlement.

Only checks the current targetSettlementId(false). For checking a specific ticket’s settlement, use get_redemption_ticket_status().

Parameters

owner (eth_typing.evm.HexAddress) –

Return type

bool

estimate_redemption_delay()

Estimate how long until a withdrawal request can be claimed.

Uses (targetSettlementId(false) - lastSettlementId) * maxSettlementInterval to account for withdrawSettlementDelay.

Return type

datetime.timedelta

get_redemption_delay_over(address)

Estimate when the next withdrawal settlement will occur.

Parameters

address (Union[eth_typing.evm.HexAddress, str]) –

Return type

datetime.datetime

get_deposit_delay_over(address)

Estimate when the next deposit settlement will occur.

Mirror of get_redemption_delay_over() but for the deposit target settlement (targetSettlementId(True)).

Parameters

address (Union[eth_typing.evm.HexAddress, str]) –

Return type

Optional[datetime.datetime]

get_target_settlement_delay_over(settlement_id)

Estimate when a current target settlement id can be processed.

Target ids come from targetSettlementId() before a concrete request ticket exists. Preserve the historical one-interval floor for this pre-request estimate.

Parameters

settlement_id (int) – Current target settlement id.

Returns

Naive UTC timestamp when tryNewSettlement() becomes eligible.

Return type

datetime.datetime

get_settlement_delay_over(settlement_id)

Estimate when an Ostium V1.5 ticket settlement id can be processed.

Ostium V1.5 request events carry the concrete settlement id that will process the request. Use that persisted id for display and recovery instead of the current targetSettlementId() value, because the target can move after later requests or settlements.

Parameters

settlement_id (int) – Ostium settlement id from a deposit or withdrawal ticket.

Returns

Naive UTC timestamp when tryNewSettlement() becomes eligible for this settlement id.

Return type

datetime.datetime

get_deposit_ticket_delay_over(ticket)

Estimate when a deposit ticket’s settlement can be processed.

Parameters

ticket (eth_defi.erc_4626.vault_protocol.gains.deposit_redeem.OstiumDepositTicket) –

Return type

datetime.datetime

get_redemption_ticket_delay_over(ticket)

Estimate when a withdrawal ticket’s settlement can be processed.

Parameters

ticket (eth_defi.erc_4626.vault_protocol.gains.deposit_redeem.OstiumRedemptionTicket) –

Return type

datetime.datetime

analyse_deposit(claim_tx_hash, deposit_ticket)

Analyse a claimDeposit() transaction.

Parses DepositClaimedV2(address indexed owner, uint32 indexed settlementId, uint256 shares) and uses the settlement price for accurate denomination amount calculation.

Parameters
Return type

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

analyse_redemption(claim_tx_hash, redemption_ticket)

Analyse a claimWithdraw() transaction.

Parses WithdrawClaimedV2(address indexed owner, uint32 indexed settlementId, uint256 assets) and uses the settlement price for accurate share price reconstruction.

Parameters
Return type

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

serialize_deposit_ticket(ticket)

Serialise an Ostium deposit ticket, including settlement_id.

Parameters

ticket (eth_defi.erc_4626.vault_protocol.gains.deposit_redeem.OstiumDepositTicket) –

Return type

dict

reconstruct_deposit_ticket(data)

Reconstruct an OstiumDepositTicket from serialised dict.

Parameters

data (dict) –

Return type

eth_defi.erc_4626.vault_protocol.gains.deposit_redeem.OstiumDepositTicket

serialize_redemption_ticket(ticket)

Serialise an Ostium redemption ticket, including settlement_id.

Parameters

ticket (eth_defi.erc_4626.vault_protocol.gains.deposit_redeem.OstiumRedemptionTicket) –

Return type

dict

reconstruct_redemption_ticket(data)

Reconstruct an OstiumRedemptionTicket from serialised dict.

Parameters

data (dict) –

Return type

eth_defi.erc_4626.vault_protocol.gains.deposit_redeem.OstiumRedemptionTicket

get_deposit_request_status(ticket)

Query Ostium V1.5 deposit status and map to generic enum.

Maps Ostium’s internal status to AsyncVaultRequestStatus without raising OstiumSettlementFailed.

Parameters

ticket (eth_defi.erc_4626.vault_protocol.gains.deposit_redeem.OstiumDepositTicket) –

Return type

eth_defi.vault.deposit_redeem.AsyncVaultRequestStatus

get_redemption_request_status(ticket)

Query Ostium V1.5 withdrawal status and map to generic enum.

Parameters

ticket (eth_defi.erc_4626.vault_protocol.gains.deposit_redeem.OstiumRedemptionTicket) –

Return type

eth_defi.vault.deposit_redeem.AsyncVaultRequestStatus

get_deposit_ticket_status(ticket)

Query deposit status for a specific ticket’s settlement ID.

Returns

One of OSTIUM_REQUEST_STATUS_* constants: NONE(0), PENDING(1), CLAIMABLE(2), RECLAIMABLE(3)

Parameters

ticket (eth_defi.erc_4626.vault_protocol.gains.deposit_redeem.OstiumDepositTicket) –

Return type

int

get_redemption_ticket_status(ticket)

Query withdrawal status for a specific ticket’s settlement ID.

Returns

One of OSTIUM_REQUEST_STATUS_* constants: NONE(0), PENDING(1), CLAIMABLE(2), RECLAIMABLE(3)

Parameters

ticket (eth_defi.erc_4626.vault_protocol.gains.deposit_redeem.OstiumRedemptionTicket) –

Return type

int

reclaim_deposit(ticket)

Return reclaimDeposit(settlementId) to recover funds after a failed settlement.

Parameters

ticket (eth_defi.erc_4626.vault_protocol.gains.deposit_redeem.OstiumDepositTicket) –

Return type

Optional[web3.contract.contract.ContractFunction]

reclaim_withdrawal(ticket)

Return reclaimWithdraw(settlementId) to recover shares after a failed settlement.

Parameters

ticket (eth_defi.erc_4626.vault_protocol.gains.deposit_redeem.OstiumRedemptionTicket) –

Return type

Optional[web3.contract.contract.ContractFunction]

cancel_deposit(ticket, raw_assets)

Return cancelRequestDeposit(settlementId, assets) to cancel a pending deposit.

Parameters
Return type

web3.contract.contract.ContractFunction

cancel_withdrawal(ticket, raw_shares)

Return cancelRequestWithdraw(settlementId, shares) to cancel a pending withdrawal.

Parameters
Return type

web3.contract.contract.ContractFunction

fetch_settlement_requests(owner)

Query on-chain status for all recent settlement IDs for an address.

Checks getDepositStatus and getWithdrawStatus for settlement IDs in the range [lastSettlementId - 10, max(depositTarget, withdrawTarget)]. This is fast (a few RPC calls) and avoids slow event scanning.

Parameters

owner (str) – Address to check.

Returns

List of dicts with keys: settlement_id, direction ("deposit" or "withdraw"), status (raw int). Only includes entries with non-NONE status.

Return type

list[dict]

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]

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

How much we can deposit

Parameters

owner (eth_typing.evm.HexAddress) –

Return type

Optional[decimal.Decimal]