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

Structured failed-flow diagnostic returned by a vault manager.

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.

VaultDepositManagerCapability

Static public integration capability of a vault deposit manager.

VaultDepositPermission

Vault-wide policy for accepting deposits.

VaultForcedSettlementResult

Outcome of an Anvil-only forced settlement attempt.

Exceptions

CannotParseRedemptionTransaction

We did no know how our redemption transaction went.

UnsupportedVaultSimulation

A vault settlement simulation cannot safely run on this provider.

VaultFlowError

Structured failure while preparing or executing a vault flow.

VaultFlowUnavailable

A vault flow cannot be safely created before transaction broadcast.

VaultTransactionFailed

One of vault deposit/redeem transactions reverted.
class VaultDepositPermission

Bases: str, enum.Enum

Vault-wide policy for accepting deposits.

This class deliberately represents only whether the vault applies a whitelist policy. It does not describe a particular account’s balance, allowance, pause state, capacity, or whether an asynchronous request is currently claimable.

The string values are persisted in vault metadata and public reports.

whitelisted = 'whitelisted'

Deposits require protocol-specific account permission.

permissionless = 'permissionless'

Any account may pass the protocol’s permission policy.

unknown = 'unknown'

The adapter cannot safely determine the vault-wide policy.

__new__(value)
capitalize()

Return a capitalized version of the string.

More specifically, make the first character have upper case and the rest lower case.

casefold()

Return a version of the string suitable for caseless comparisons.

center(width, fillchar=' ', /)

Return a centered string of length width.

Padding is done using the specified fill character (default is a space).

count()

Return the number of non-overlapping occurrences of substring sub in string S[start:end].

Optional arguments start and end are interpreted as in slice notation.

encode(encoding='utf-8', errors='strict')

Encode the string using the codec registered for encoding.

encoding

The encoding in which to encode the string.

errors

The error handling scheme to use for encoding errors. The default is ‘strict’ meaning that encoding errors raise a UnicodeEncodeError. Other possible values are ‘ignore’, ‘replace’ and ‘xmlcharrefreplace’ as well as any other name registered with codecs.register_error that can handle UnicodeEncodeErrors.

endswith()

Return True if the string ends with the specified suffix, False otherwise.

suffix

A string or a tuple of strings to try.

start

Optional start position. Default: start of the string.

end

Optional stop position. Default: end of the string.

expandtabs(tabsize=8)

Return a copy where all tab characters are expanded using spaces.

If tabsize is not given, a tab size of 8 characters is assumed.

find()

Return the lowest index in S where substring sub is found, such that sub is contained within S[start:end].

Optional arguments start and end are interpreted as in slice notation. Return -1 on failure.

format(*args, **kwargs)

Return a formatted version of the string, using substitutions from args and kwargs. The substitutions are identified by braces (‘{’ and ‘}’).

format_map(mapping, /)

Return a formatted version of the string, using substitutions from mapping. The substitutions are identified by braces (‘{’ and ‘}’).

index()

Return the lowest index in S where substring sub is found, such that sub is contained within S[start:end].

Optional arguments start and end are interpreted as in slice notation. Raises ValueError when the substring is not found.

isalnum()

Return True if the string is an alpha-numeric string, False otherwise.

A string is alpha-numeric if all characters in the string are alpha-numeric and there is at least one character in the string.

isalpha()

Return True if the string is an alphabetic string, False otherwise.

A string is alphabetic if all characters in the string are alphabetic and there is at least one character in the string.

isascii()

Return True if all characters in the string are ASCII, False otherwise.

ASCII characters have code points in the range U+0000-U+007F. Empty string is ASCII too.

isdecimal()

Return True if the string is a decimal string, False otherwise.

A string is a decimal string if all characters in the string are decimal and there is at least one character in the string.

isdigit()

Return True if the string is a digit string, False otherwise.

A string is a digit string if all characters in the string are digits and there is at least one character in the string.

isidentifier()

Return True if the string is a valid Python identifier, False otherwise.

Call keyword.iskeyword(s) to test whether string s is a reserved identifier, such as “def” or “class”.

islower()

Return True if the string is a lowercase string, False otherwise.

A string is lowercase if all cased characters in the string are lowercase and there is at least one cased character in the string.

isnumeric()

Return True if the string is a numeric string, False otherwise.

A string is numeric if all characters in the string are numeric and there is at least one character in the string.

isprintable()

Return True if all characters in the string are printable, False otherwise.

A character is printable if repr() may use it in its output.

isspace()

Return True if the string is a whitespace string, False otherwise.

A string is whitespace if all characters in the string are whitespace and there is at least one character in the string.

istitle()

Return True if the string is a title-cased string, False otherwise.

In a title-cased string, upper- and title-case characters may only follow uncased characters and lowercase characters only cased ones.

isupper()

Return True if the string is an uppercase string, False otherwise.

A string is uppercase if all cased characters in the string are uppercase and there is at least one cased character in the string.

join(iterable, /)

Concatenate any number of strings.

The string whose method is called is inserted in between each given string. The result is returned as a new string.

Example: ‘.’.join([‘ab’, ‘pq’, ‘rs’]) -> ‘ab.pq.rs’

ljust(width, fillchar=' ', /)

Return a left-justified string of length width.

Padding is done using the specified fill character (default is a space).

lower()

Return a copy of the string converted to lowercase.

lstrip(chars=None, /)

Return a copy of the string with leading whitespace removed.

If chars is given and not None, remove characters in chars instead.

static maketrans()

Return a translation table usable for str.translate().

If there is only one argument, it must be a dictionary mapping Unicode ordinals (integers) or characters to Unicode ordinals, strings or None. Character keys will be then converted to ordinals. If there are two arguments, they must be strings of equal length, and in the resulting dictionary, each character in x will be mapped to the character at the same position in y. If there is a third argument, it must be a string, whose characters will be mapped to None in the result.

partition(sep, /)

Partition the string into three parts using the given separator.

This will search for the separator in the string. If the separator is found, returns a 3-tuple containing the part before the separator, the separator itself, and the part after it.

If the separator is not found, returns a 3-tuple containing the original string and two empty strings.

removeprefix(prefix, /)

Return a str with the given prefix string removed if present.

If the string starts with the prefix string, return string[len(prefix):]. Otherwise, return a copy of the original string.

removesuffix(suffix, /)

Return a str with the given suffix string removed if present.

If the string ends with the suffix string and that suffix is not empty, return string[:-len(suffix)]. Otherwise, return a copy of the original string.

replace(old, new, /, count=- 1)

Return a copy with all occurrences of substring old replaced by new.

count

Maximum number of occurrences to replace. -1 (the default value) means replace all occurrences.

If the optional argument count is given, only the first count occurrences are replaced.

rfind()

Return the highest index in S where substring sub is found, such that sub is contained within S[start:end].

Optional arguments start and end are interpreted as in slice notation. Return -1 on failure.

rindex()

Return the highest index in S where substring sub is found, such that sub is contained within S[start:end].

Optional arguments start and end are interpreted as in slice notation. Raises ValueError when the substring is not found.

rjust(width, fillchar=' ', /)

Return a right-justified string of length width.

Padding is done using the specified fill character (default is a space).

rpartition(sep, /)

Partition the string into three parts using the given separator.

This will search for the separator in the string, starting at the end. If the separator is found, returns a 3-tuple containing the part before the separator, the separator itself, and the part after it.

If the separator is not found, returns a 3-tuple containing two empty strings and the original string.

rsplit(sep=None, maxsplit=- 1)

Return a list of the substrings in the string, using sep as the separator string.

sep

The separator used to split the string.

When set to None (the default value), will split on any whitespace character (including n r t f and spaces) and will discard empty strings from the result.

maxsplit

Maximum number of splits. -1 (the default value) means no limit.

Splitting starts at the end of the string and works to the front.

rstrip(chars=None, /)

Return a copy of the string with trailing whitespace removed.

If chars is given and not None, remove characters in chars instead.

split(sep=None, maxsplit=- 1)

Return a list of the substrings in the string, using sep as the separator string.

sep

The separator used to split the string.

When set to None (the default value), will split on any whitespace character (including n r t f and spaces) and will discard empty strings from the result.

maxsplit

Maximum number of splits. -1 (the default value) means no limit.

Splitting starts at the front of the string and works to the end.

Note, str.split() is mainly useful for data that has been intentionally delimited. With natural text that includes punctuation, consider using the regular expression module.

splitlines(keepends=False)

Return a list of the lines in the string, breaking at line boundaries.

Line breaks are not included in the resulting list unless keepends is given and true.

startswith()

Return True if the string starts with the specified prefix, False otherwise.

prefix

A string or a tuple of strings to try.

start

Optional start position. Default: start of the string.

end

Optional stop position. Default: end of the string.

strip(chars=None, /)

Return a copy of the string with leading and trailing whitespace removed.

If chars is given and not None, remove characters in chars instead.

swapcase()

Convert uppercase characters to lowercase and lowercase characters to uppercase.

title()

Return a version of the string where each word is titlecased.

More specifically, words start with uppercased characters and all remaining cased characters have lower case.

translate(table, /)

Replace each character in the string using the given translation table.

table

Translation table, which must be a mapping of Unicode ordinals to Unicode ordinals, strings, or None.

The table must implement lookup/indexing via __getitem__, for instance a dictionary or list. If this operation raises LookupError, the character is left untouched. Characters mapped to None are deleted.

upper()

Return a copy of the string converted to uppercase.

zfill(width, /)

Pad a numeric string with zeros on the left, to fill a field of the given width.

The string is never truncated.

class VaultDepositManagerCapability

Bases: object

Static public integration capability of a vault deposit manager.

This describes support implemented by eth_defi, rather than the vault’s live cap, pause, allow-list, token balance, or liquidity state. A historical probe cannot establish future acceptance: consumers must make the request against current chain state and handle a current-state revert.

Parameters

  • can_deposit – Whether a complete public deposit lifecycle is implemented.

  • can_redeem – Whether a complete public redemption lifecycle is implemented.

  • deposit_flow – Request lifecycle for deposits when supported.

  • redemption_flow – Request lifecycle for redemptions when supported.

as_dict()

Convert the capability to JSON-compatible primitives.

Returns

Directional capability object suitable for internal persistence.

Return type

dict[str, bool | str]

as_initial_public_schema()

Return the initial public schema or fail closed for partial support.

The first export version advertises only symmetric manager support: both directions must either be implemented or explicitly unsupported. Keeping the internal representation directional leaves room for a future schema revision without making a partial manager look depositable today. An explicit False/False capability remains useful because it distinguishes a deliberate refusing manager from an adapter whose transaction support is unknown.

Returns

Symmetric public capability object, or None for partial support.

Return type

Optional[dict[str, bool | str]]

__init__(can_deposit, can_redeem, deposit_flow=None, redemption_flow=None)
Parameters
Return type

None

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.

none = 'none'

No request found for this ticket

pending = 'pending'

Request submitted, awaiting settlement

claimable = 'claimable'

Settlement done, claim available

reclaimable = 'reclaimable'

Settlement failed, reclaim available to recover funds/shares

exception VaultFlowError

Bases: Exception

Structured failure while preparing or executing a vault flow.

Preflight failures use VaultFlowUnavailable; mined transaction failures use VaultTransactionFailed. The common fields let a caller preserve useful context without treating a rejected request as a transaction that needs receipt handling.

Parameters

  • reason – Human-readable reason for the failed flow.

  • protocol – Protocol adapter that detected the failure, when known.

  • vault_address – Vault address whose flow was attempted, when known.

  • caller – Address for which the flow was prepared, when known.

  • direction – deposit or redeem when known.

  • phase – Lifecycle phase such as request or transaction.

  • decoded_error – Protocol-specific decoded error name, when available.

  • raw_revert_data – Raw revert payload, when available.

  • requested_raw_amount – Requested amount in the contract’s native raw unit, when applicable.

  • available_raw_amount – Available amount in the contract’s native raw unit, when applicable.

  • function_selector – Four-byte selector of the denied protocol entry point, when known.

  • error_selector – Four-byte selector of the expected or decoded custom error, when known.

  • access_delay – Access-manager scheduling delay in seconds, when a caller is eligible only after delayed execution.

Store structured context for a vault-flow failure.

__init__(reason, *, protocol=None, vault_address=None, caller=None, direction=None, phase=None, decoded_error=None, raw_revert_data=None, requested_raw_amount=None, available_raw_amount=None, function_selector=None, error_selector=None, access_delay=None)

Store structured context for a vault-flow failure.

Parameters
Return type

None

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

Add a note to the exception

with_traceback(tb, /)

Set self.__traceback__ to tb and return self.

exception VaultTransactionFailed

Bases: eth_defi.vault.deposit_redeem.VaultFlowError

One of vault deposit/redeem transactions reverted.

Store structured context for a vault-flow failure.

__init__(reason, *, protocol=None, vault_address=None, caller=None, direction=None, phase=None, decoded_error=None, raw_revert_data=None, requested_raw_amount=None, available_raw_amount=None, function_selector=None, error_selector=None, access_delay=None)

Store structured context for a vault-flow failure.

Parameters
Return type

None

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

Add a note to the exception

with_traceback(tb, /)

Set self.__traceback__ to tb and return self.

exception VaultFlowUnavailable

Bases: eth_defi.vault.deposit_redeem.VaultFlowError

A vault flow cannot be safely created before transaction broadcast.

Store structured context for a vault-flow failure.

__init__(reason, *, protocol=None, vault_address=None, caller=None, direction=None, phase=None, decoded_error=None, raw_revert_data=None, requested_raw_amount=None, available_raw_amount=None, function_selector=None, error_selector=None, access_delay=None)

Store structured context for a vault-flow failure.

Parameters
Return type

None

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

Add a note to the exception

with_traceback(tb, /)

Set self.__traceback__ to tb and return self.

exception UnsupportedVaultSimulation

Bases: RuntimeError

A vault settlement simulation cannot safely run on this provider.

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

Bases: object

Structured failed-flow diagnostic returned by a vault manager.

protocol: Optional[str]

Protocol adapter that analysed the failed flow, when available.

vault_address: Optional[eth_typing.evm.HexAddress]

Vault whose lifecycle was being processed, when available.

direction: Optional[Literal['deposit', 'redeem']]

deposit or redeem when the manager knows the direction.

phase: Optional[str]

Lifecycle phase, such as request or claim.

receipt_status: Optional[int]

Receipt status when it was available to the analyser.

__init__(tx_hash, revert_reason, protocol=None, vault_address=None, direction=None, phase=None, receipt_status=None)
Parameters
Return type

None

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

None

class DepositTicket

Bases: object

In-progress deposit request.

tx_hash: hexbytes.main.HexBytes

Last of transaction hashes

block_number: int

Last tx block number

block_timestamp: datetime.datetime

Last tx block timestamp

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

None

class RedemptionTicket

Bases: object

In-progress redemption request.

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

  • Serialisable class

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

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

None

class VaultForcedSettlementResult

Bases: object

Outcome of an Anvil-only forced settlement attempt.

Synchronous managers return a no-op result because their successful request transaction already completes the lifecycle. Asynchronous managers return the ticket status before and after their protocol-specific settlement transaction(s).

ticket: Optional[Union[eth_defi.vault.deposit_redeem.DepositTicket, eth_defi.vault.deposit_redeem.RedemptionTicket]]

Ticket progressed by the simulation, or None for synchronous flows.

settlement_required: bool

False when the completed flow does not need a settlement transaction.

status_before: Optional[eth_defi.vault.deposit_redeem.AsyncVaultRequestStatus]

Request status before settlement, when a ticket was supplied.

status_after: Optional[eth_defi.vault.deposit_redeem.AsyncVaultRequestStatus]

Request status after settlement, when a ticket was supplied.

transaction_hashes: tuple[hexbytes.main.HexBytes, ...]

Transactions broadcast by the forced settlement helper.

__init__(ticket, settlement_required, status_before, status_after, transaction_hashes=())
Parameters
Return type

None

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 RedemptionRequest

Bases: object

Wrap the different redeem functions async vaults implement.

vault: VaultBase

Vault we are dealing with

owner: eth_typing.evm.HexAddress

Owner of the shares

to: eth_typing.evm.HexAddress

Receiver of underlying asset

shares: decimal.Decimal

Human-readable shares

raw_shares: int

Raw amount of shares

funcs: list[web3.contract.contract.ContractFunction]

Transactions we need to perform in order to open a redemption

It’s a list because for Gains we need 2 tx

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

broadcast(from_=None, gas=1000000)

Broadcast all the transactions in this request.

Parameters
Returns

List of transaction hashes

Return type

list[hexbytes.main.HexBytes]

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

None

class DepositRequest

Bases: object

Wrap the different deposit functions async vaults implement.

vault: VaultBase

Vault we are dealing with

owner: eth_typing.evm.HexAddress

Owner of the shares

to: eth_typing.evm.HexAddress

Receiver of underlying asset

amount: decimal.Decimal

Human-readable shares

raw_amount: int

Raw amount of shares

funcs: list[web3.contract.contract.ContractFunction]

Transactions we need to perform in order to open a redemption

It’s a list because for Gains we need 2 tx

gas: Optional[int]

Set transaction gas limit

value: Optional[decimal.Decimal]

Attached ETH value to the tx

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
Parameters

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

Return type

eth_defi.vault.deposit_redeem.DepositTicket

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

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

None

class VaultDepositManager

Bases: abc.ABC

Abstraction over different deposit/redeem flows of vaults.

Supported simulation path: every manager exposes force_settle() for Anvil-based integration tests. Synchronous managers use its no-op implementation; asynchronous managers override it when their selected test lifecycle needs settlement.

Known limitations: the common interface cannot infer protocol-specific settlement roles, valuations or queues. Each protocol manager documents the concrete asynchronous path it supports and raises UnsupportedVaultSimulation when it has no safe Anvil driver.

__init__(vault)
Parameters

vault (eth_defi.vault.base.VaultBase) –

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

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 estimate_deposit(owner, amount, block_identifier='latest')

How many shares we get for a deposit.

Parameters
Return type

decimal.Decimal

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

How many denomination tokens we get for a redeem.

Parameters
Return type

decimal.Decimal

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

  1. create_redemption_request

  2. sign and broadcast the transaction

  3. parse success and redemption request id from the transaction

  4. wait until the redemption delay is over

  5. settle the redemption request

Parameters
Returns

Redemption request wrapper.

Return type

eth_defi.vault.deposit_redeem.RedemptionRequest

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

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

can_create_deposit_request(owner)

Can we start depositing now.

Vault can be full?

Parameters

owner (eth_typing.evm.HexAddress) –

Return type

bool

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

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]

get_max_deposit(owner)

How much we can deposit

Parameters

owner (eth_typing.evm.HexAddress) –

Return type

Optional[decimal.Decimal]

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

abstract 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

Optional[web3.contract.contract.ContractFunction]

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

Optional[datetime.datetime]

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]

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]

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

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

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

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

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

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