vault.deposit_redeem

Documentation for eth_defi.vault.deposit_redeem Python module.

Abstraction over different deposit/redeem flows of vaults.

Classes

`AsyncVaultRequestStatus`	Generic async vault request status.
`DepositRedeemEventAnalysis`	Analyse a vault deposit/redeem event.
`DepositRedeemEventFailure`	DepositRedeemEventFailure(tx_hash: hexbytes.main.HexBytes, revert_reason: str \| None)
`DepositRequest`	Wrap the different deposit functions async vaults implement.
`DepositTicket`	In-progress deposit request.
`RedemptionRequest`	Wrap the different redeem functions async vaults implement.
`RedemptionTicket`	In-progress redemption request.
`VaultDepositManager`	Abstraction over different deposit/redeem flows of vaults.

Exceptions

`CannotParseRedemptionTransaction`	We did no know how our redemption transaction went.
`VaultTransactionFailed`	One of vault deposit/redeem transactions reverted

class AsyncVaultRequestStatus

Bases: enum.Enum

Generic async vault request status.

Protocol adapters map their internal status to these values. Used by the trade-executor settlement retry module to determine the next action for a pending vault trade, without importing protocol-specific code.

exception CannotParseRedemptionTransaction

Bases: Exception

We did no know how our redemption transaction went.

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

class DepositRedeemEventAnalysis

Bases: object

Analyse a vault deposit/redeem event.

Done for the transaction where we get our assets into our wallet, so we can determine the actualy executed price of shares we received/sold

__init__(from_, to, denomination_amount, share_count, tx_hash, block_number, block_timestamp)

Parameters

from_ (eth_typing.evm.HexAddress) –
to (eth_typing.evm.HexAddress) –
denomination_amount (decimal.Decimal) –
share_count (decimal.Decimal) –
tx_hash (hexbytes.main.HexBytes) –
block_number (eth_typing.evm.BlockNumber) –
block_timestamp (datetime.datetime) –

Return type

None

class DepositRedeemEventFailure

Bases: object

DepositRedeemEventFailure(tx_hash: hexbytes.main.HexBytes, revert_reason: str | None)

__init__(tx_hash, revert_reason)

Parameters

tx_hash (hexbytes.main.HexBytes) –
revert_reason (Optional[str]) –

Return type

None

class DepositRequest

Bases: object

Wrap the different deposit functions async vaults implement.

__init__(vault, owner, to, amount, raw_amount, funcs, gas=None, value=None)

Parameters

vault (VaultBase) –
owner (eth_typing.evm.HexAddress) –
to (eth_typing.evm.HexAddress) –
amount (decimal.Decimal) –
raw_amount (int) –
funcs (list[web3.contract.contract.ContractFunction]) –
gas (Optional[int]) –
value (Optional[decimal.Decimal]) –

Return type

None

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

Broadcast all the transactions in this request.

Parameters

from – Address to send the transactions from
gas (Optional[int]) – Gas limit to use for each transaction
from_ (eth_typing.evm.HexAddress) –

Returns

List of transaction hashes

Raises

TransactionAssertionError – If any of the transactions revert

Return type

eth_defi.vault.deposit_redeem.RedemptionTicket

parse_deposit_transaction(tx_hashes)

Parse the transaction receipt to get the actual shares redeemed.

Assumes only one redemption request per vault per transaction
Most throw an

Raises

CannotParseRedemptionTransaction – If we did not know how to parse the transaction
VaultTransactionFailed – One of transactions reverted

Parameters

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

Return type

eth_defi.vault.deposit_redeem.DepositTicket

class DepositTicket

Bases: object

In-progress deposit request.

Needed for ERC-7540

__init__(vault_address, owner, to, raw_amount, tx_hash, gas_used, block_number, block_timestamp)

Parameters

vault_address (eth_typing.evm.HexAddress) –
owner (eth_typing.evm.HexAddress) –
to (eth_typing.evm.HexAddress) –
raw_amount (int) –
tx_hash (hexbytes.main.HexBytes) –
gas_used (int) –
block_number (int) –
block_timestamp (datetime.datetime) –

Return type

None

class RedemptionRequest

Bases: object

Wrap the different redeem functions async vaults implement.

__init__(vault, owner, to, shares, raw_shares, funcs)

Parameters

vault (VaultBase) –
owner (eth_typing.evm.HexAddress) –
to (eth_typing.evm.HexAddress) –
shares (decimal.Decimal) –
raw_shares (int) –
funcs (list[web3.contract.contract.ContractFunction]) –

Return type

None

broadcast(from_=None, gas=1000000)

Broadcast all the transactions in this request.

Parameters

from – Address to send the transactions from
gas (int) – Gas limit to use for each transaction
from_ (eth_typing.evm.HexAddress) –

Returns

List of transaction hashes

Return type

list[hexbytes.main.HexBytes]

parse_redeem_transaction(tx_hashes)

Parse the transaction receipt to get the actual shares redeemed.

Assumes only one redemption request per vault per transaction

Raises: CannotParseRedemptionTransaction – If we did not know how to parse the transaction
Parameters: tx_hashes (list[hexbytes.main.HexBytes]) –
Return type: eth_defi.vault.deposit_redeem.RedemptionTicket

class RedemptionTicket

Bases: object

In-progress redemption request.

Needs to wait until the epoch time is over or owner has settled
Serialisable class

__init__(vault_address, owner, to, raw_shares, tx_hash)

Parameters

vault_address (eth_typing.evm.HexAddress) –
owner (eth_typing.evm.HexAddress) –
to (eth_typing.evm.HexAddress) –
raw_shares (int) –
tx_hash (hexbytes.main.HexBytes) –

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

Bases: abc.ABC

Abstraction over different deposit/redeem flows of vaults.

__init__(vault)

Parameters: vault (eth_defi.vault.base.VaultBase) –

abstract analyse_deposit(claim_tx_hash, deposit_ticket)

Analyse the transaction where we claim shares

Return information of the actual executed price for which we got the shares for

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]

abstract analyse_redemption(claim_tx_hash, redemption_ticket)

Analyse the transaction where we claim our capital back.

Return information of the actual executed price for which we got the shares for

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

Can we start depositing now.

Vault can be full?

Parameters: owner (eth_typing.evm.HexAddress) –
Return type: bool

abstract 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

abstract can_finish_deposit(deposit_ticket)

Can we finish the deposit process in async reposits

Parameters: deposit_ticket (eth_defi.vault.deposit_redeem.DepositTicket) –
Return type: bool

abstract can_finish_redeem(redemption_ticket)

Check if the redemption request can be redeemed now.

Phase 2 of redemption, after settlement

Parameters: redemption_ticket (eth_defi.vault.deposit_redeem.RedemptionTicket) – Redemption redemption_ticket ticket from create_redemption_request()
Returns: True if can be redeemed now
Return type: bool

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

Create a redemption request.

Abstracts IPOR, Lagoon, Gains, other vault redemption flow.

See eth_defi.gains.vault.GainsVault for an example usage.

Flow

create_redemption_request
sign and broadcast the transaction
parse success and redemption request id from the transaction
wait until the redemption delay is over
settle the redemption request

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

Returns

Redemption request wrapper.

Return type

eth_defi.vault.deposit_redeem.RedemptionRequest

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

How many shares we get for a deposit.

Parameters

owner (Optional[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

abstract estimate_redeem(owner, shares, block_identifier='latest')

How many denomination tokens we get for a redeem.

Parameters

owner (Optional[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

abstract 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

abstract 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

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]

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

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

abstract has_synchronous_deposit()

Does this vault support synchronous deposits?

E.g. ERC-4626 vaults

Return type: bool

abstract has_synchronous_redemption()

Does this vault support synchronous deposits?

E.g. ERC-4626 vaults

Return type: bool

abstract 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

abstract 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

exception VaultTransactionFailed

Bases: Exception

One of vault deposit/redeem transactions reverted

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