erc_4626.deposit_redeem

Documentation for eth_defi.erc_4626.deposit_redeem Python module.

ERC-4626 deposit and redeem requests.

Classes

`ERC4626DepositManager`	Standard synchronous ERC-4626 deposit and redemption flow.
`ERC4626DepositRequest`	Synchronous deposit request for ERC-4626 vaults.
`ERC4626DepositTicket`	Synchronous deposit request for ERC-4626 vaults.
`ERC4626RedemptionRequest`	Synchronous deposit request for ERC-4626 vaults.
`ERC4626RedemptionTicket`	Synchronous deposit request for ERC-4626 vaults.

class ERC4626DepositTicket

Bases: eth_defi.vault.deposit_redeem.DepositRequest

Synchronous deposit request for ERC-4626 vaults.

No-op as requests are synchronous

__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 ERC4626DepositRequest

Bases: eth_defi.vault.deposit_redeem.DepositRequest

Synchronous deposit request for ERC-4626 vaults.

__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 ERC4626RedemptionTicket

Bases: eth_defi.vault.deposit_redeem.RedemptionTicket

Synchronous deposit request for ERC-4626 vaults.

No-op as requests are synchronous

__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 ERC4626RedemptionRequest

Bases: eth_defi.vault.deposit_redeem.RedemptionRequest

Synchronous deposit request for ERC-4626 vaults.

__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 ERC4626DepositManager

Bases: eth_defi.vault.deposit_redeem.VaultDepositManager

Standard synchronous ERC-4626 deposit and redemption flow.

Supported simulation path

Standard ERC-4626 deposit and redeem calls complete in their originating transaction. force_settle() therefore accepts None and performs the Anvil-validated shared no-op.

Known limitations

This manager is suitable only for vaults whose selected asset uses the standard ERC-4626 entry points. Queued, delegated, multi-asset and protocol-specific settlement flows must provide a specialised manager.

__init__(vault)

Parameters: vault (ERC4626Vault) –

create_redemption_request(owner, to=None, 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.erc_4626.deposit_redeem.ERC4626RedemptionRequest

can_finish_deposit(deposit_ticket)

Synchronous deposits can be finished immediately.

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

can_finish_redeem(redemption_ticket)

Synchronous redemptions can be finished immediately.

Parameters: redemption_ticket (eth_defi.erc_4626.deposit_redeem.ERC4626RedemptionTicket) –

can_create_deposit_request(owner)

Can we start depositing now.

Vault can be full?

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

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

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

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

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

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

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

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.vault.deposit_redeem.RedemptionTicket) – 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

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

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

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]

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]

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

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