OstiumV15DepositManager

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

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

Attributes summary

web3

Methods summary

`__init__`(vault)
`analyse_deposit`(claim_tx_hash, deposit_ticket)	Analyse a `claimDeposit()` transaction.
`analyse_redemption`(claim_tx_hash, ...)	Analyse a `claimWithdraw()` transaction.
`can_create_deposit_request`(owner)	V1.5 deposits are always accepted (caps enforced at settlement, not request).
`can_create_redemption_request`(owner)	V1.5 withdrawals can be requested any time (no epoch window restriction).
`can_finish_deposit`(deposit_ticket)	Check if a deposit can be claimed after settlement.
`can_finish_redeem`(redemption_ticket)	Check if a withdrawal can be claimed after settlement.
`cancel_deposit`(ticket, raw_assets)	Return `cancelRequestDeposit(settlementId, assets)` to cancel a pending deposit.
`cancel_withdrawal`(ticket, raw_shares)	Return `cancelRequestWithdraw(settlementId, shares)` to cancel a pending withdrawal.
`create_deposit_request`(owner[, to, amount, ...])	Create an async deposit request via `requestDeposit(assets)`.
`create_redemption_request`(owner[, to, ...])	Create an async withdrawal request via `requestWithdraw(shares)`.
`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`()	Estimate how long until a withdrawal request can be claimed.
`fetch_settlement_requests`(owner)	Query on-chain status for all recent settlement IDs for an address.
`fetch_vault_flow_events`(hypersync_client, ...)	Fetch Ostium V1.5 request events using Hypersync.
`finish_deposit`(deposit_ticket)	Return `claimDeposit(settlementId)` bound function.
`finish_redemption`(redemption_ticket)	Return `claimWithdraw(settlementId)` bound function.
`get_deposit_delay_over`(address)	Estimate when the next deposit settlement will occur.
`get_deposit_request_status`(ticket)	Query Ostium V1.5 deposit status and map to generic enum.
`get_deposit_ticket_delay_over`(ticket)	Estimate when a deposit ticket's settlement can be processed.
`get_deposit_ticket_status`(ticket)	Query deposit status for a specific ticket's settlement ID.
`get_max_deposit`(owner)	How much we can deposit
`get_redemption_delay_over`(address)	Estimate when the next withdrawal settlement will occur.
`get_redemption_request_status`(ticket)	Query Ostium V1.5 withdrawal status and map to generic enum.
`get_redemption_ticket_delay_over`(ticket)	Estimate when a withdrawal ticket's settlement can be processed.
`get_redemption_ticket_status`(ticket)	Query withdrawal status for a specific ticket's settlement ID.
`get_settlement_delay_over`(settlement_id)	Estimate when an Ostium V1.5 ticket settlement id can be processed.
`get_target_settlement_delay_over`(settlement_id)	Estimate when a current target settlement id can be processed.
`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 owner has a pending deposit for the current target settlement.
`is_redemption_in_progress`(owner)	Check if owner has a pending withdrawal for the current target settlement.
`reclaim_deposit`(ticket)	Return `reclaimDeposit(settlementId)` to recover funds after a failed settlement.
`reclaim_withdrawal`(ticket)	Return `reclaimWithdraw(settlementId)` to recover shares after a failed settlement.
`reconstruct_deposit_ticket`(data)	Reconstruct an `OstiumDepositTicket` from serialised dict.
`reconstruct_redemption_ticket`(data)	Reconstruct an `OstiumRedemptionTicket` from serialised dict.
`serialize_deposit_ticket`(ticket)	Serialise an Ostium deposit ticket, including `settlement_id`.
`serialize_redemption_ticket`(ticket)	Serialise an Ostium redemption ticket, including `settlement_id`.

__init__(vault)

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

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

claim_tx_hash (Union[hexbytes.main.HexBytes, str]) –
deposit_ticket (Optional[eth_defi.vault.deposit_redeem.DepositTicket]) –

Return type

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

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

claim_tx_hash (Union[hexbytes.main.HexBytes, str]) –
redemption_ticket (Optional[eth_defi.vault.deposit_redeem.RedemptionTicket]) –

Return type

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

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

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

cancel_deposit(ticket, raw_assets)

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

Parameters

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

Return type

web3.contract.contract.ContractFunction

cancel_withdrawal(ticket, raw_shares)

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

Parameters

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

Return type

web3.contract.contract.ContractFunction

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

USDC is transferred to the vault immediately
Request is queued for the next settlement
After settlement, shares can be claimed via claimDeposit(settlementId)

Parameters

owner (eth_typing.evm.HexAddress) – Address depositing USDC.
amount (decimal.Decimal) – USDC amount in human-readable decimal.
raw_amount (int) – USDC amount in raw token units.
to (eth_typing.evm.HexAddress) –

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

OLP shares are transferred to the vault immediately
Request is queued for settlement
After settlement, USDC can be claimed via claimWithdraw(settlementId)

Parameters

owner (eth_typing.evm.HexAddress) – Address withdrawing shares.
shares (decimal.Decimal) – Share amount in human-readable decimal.
raw_shares (int) – Share amount in raw token units.
to (eth_typing.evm.HexAddress) –

Return type

eth_defi.erc_4626.vault_protocol.gains.deposit_redeem.OstiumRedemptionRequest

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

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

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]

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]

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

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

How much we can deposit

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

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

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

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

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

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]

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

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

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

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