vault.deposit_redeem

Documentation for eth_defi.vault.deposit_redeem Python module.

Abstraction over different deposit/redeem flows of vaults.

Functions

create_synchronous_settlement_result()

Create the standard no-op outcome for a synchronous vault flow.

extract_revert_data(error)

Extract raw EVM revert data from common Web3 exception shapes.

validate_closed_deposit_request_with_guard(...)

Validate manager-generated closed-deposit calls through GuardV0.

Classes

AsyncVaultRequestStatus

Generic async vault request status.

ClosedDepositGuardValidation

Evidence returned after GuardV0 accepts a closed-vault deposit call.

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.

GuardV0ValidationCall

One independently validated manager-generated call.

RedemptionRequest

Wrap the different redeem functions async vaults implement.

RedemptionTicket

In-progress redemption request.

VaultDepositManager

Abstract base for every vault deposit and redemption flow.

VaultDepositManagerCapability

Static public integration capability of a vault deposit manager.

VaultDepositPermission

Whether deposits require KYC or comparable identity approval.

VaultDirectPayoutEvidence

Evidence for an asynchronous request settled by direct token payment.

VaultForcedSettlementResult

Outcome of an Anvil-only forced settlement attempt.

VaultRedemptionPreflight

Amount-aware immediate-redemption guidance from a vault manager.

VaultRedemptionSimulationIntervention

Disclosed Anvil-only intervention used before a real redemption call.

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.

WhitelistingRequired

A deposit was attempted for a vault whose whitelist excludes the owner.
class VaultDepositPermission

Bases: str, enum.Enum

Whether deposits require KYC or comparable identity approval.

This class deliberately represents only a depositor’s KYC or manual identity-approval requirement. It does not describe a particular account’s balance, allowance, token-holding eligibility, pause state, capacity, lock-up, open date, epoch window, or whether an asynchronous request is currently claimable.

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

whitelisted = 'whitelisted'

Deposits require prior KYC or comparable manual identity approval.

permissionless = 'permissionless'

Deposits need no prior KYC or manual identity approval.

An open date, lock-up, epoch, cap, pause or token-holding condition does not change this status.

unknown = 'unknown'

The adapter cannot safely determine whether KYC is required.

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

  • deposit_unsupported_reason – Stable adapter reason when deposits are deliberately unsupported.

  • redemption_unsupported_reason – Stable adapter reason when redemptions are deliberately unsupported.

  • supports_anvil_settlement – Whether the advertised asynchronous lifecycle can be advanced with its protocol-specific ticket on an Anvil fork. None means no settlement assertion is needed for the selected synchronous direction. False publishes an advertised asynchronous lifecycle which cannot be safely advanced on Anvil.

  • anvil_settlement_unsupported_reason – Stable concrete reason why an advertised asynchronous lifecycle cannot be advanced on Anvil. Required when supports_anvil_settlement=False and forbidden otherwise.

deposit_assets: tuple[eth_typing.evm.HexAddress, ...]

Accepted token addresses for an explicit multi-asset deposit flow.

publish_partial: bool

Allow the initial public schema to expose only one flow direction.

as_dict()

Convert the capability to JSON-compatible primitives.

Returns

Directional capability object suitable for internal persistence.

Return type

dict[str, bool | str | list[eth_typing.evm.HexAddress]]

as_initial_public_schema()

Return the initial public capability schema.

Existing partial adapters remain fail-closed unless they explicitly opt in after their supported direction has been fork-proven.

Returns

JSON-compatible capability object, or None for an unpublished partial adapter.

Return type

Optional[dict[str, bool | str | list[eth_typing.evm.HexAddress]]]

__init__(can_deposit, can_redeem, deposit_flow=None, redemption_flow=None, deposit_unsupported_reason=None, redemption_unsupported_reason=None, supports_anvil_settlement=None, anvil_settlement_unsupported_reason=None, deposit_assets=(), publish_partial=False)
Parameters
Return type

None

class VaultRedemptionPreflight

Bases: object

Amount-aware immediate-redemption guidance from a vault manager.

The result is advisory because capacity can change before a transaction is mined. The manager’s request constructor must repeat an available-capacity check before broadcasting. It is currently returned only by adapters that can determine an immediate full-fill capacity from their authoritative protocol state, such as cSigma’s queue-adjusted reserve check.

Note

Trade-executor integrations must map an unavailable result, or a matching VaultFlowUnavailable from request construction, to a capacity result before their generic receipt-analysis error handling.

Parameters

  • available – Whether the requested raw shares can be redeemed immediately.

  • requested_raw_shares – Requested vault-share amount in native units.

  • available_raw_shares – Current immediate capacity in native share units, when the adapter can determine it.

  • reason – Stable adapter reason when the request is unavailable.

__init__(available, requested_raw_shares, available_raw_shares=None, reason=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.

  • asset_address – Input asset selected for a multi-asset flow, 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.

  • preflight_result – Stable consumer-facing result for a predictable refusal. This is an optional migration field: callers must fall back to decoded_error while supporting older eth-defi releases that do not populate it.

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

  • minimum_raw_amount – Protocol minimum 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.

  • next_open – Naive UTC time at which a predictable closed protocol window next opens.

Store structured context for a vault-flow failure.

__init__(reason, *, protocol=None, vault_address=None, caller=None, asset_address=None, direction=None, phase=None, decoded_error=None, preflight_result=None, raw_revert_data=None, requested_raw_amount=None, available_raw_amount=None, minimum_raw_amount=None, function_selector=None, error_selector=None, access_delay=None, next_open=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.

extract_revert_data(error)

Extract raw EVM revert data from common Web3 exception shapes.

Parameters

error (BaseException) – Web3 exception raised by eth_call.

Returns

Raw revert payload when exposed by the provider.

Return type

Optional[hexbytes.main.HexBytes]

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, asset_address=None, direction=None, phase=None, decoded_error=None, preflight_result=None, raw_revert_data=None, requested_raw_amount=None, available_raw_amount=None, minimum_raw_amount=None, function_selector=None, error_selector=None, access_delay=None, next_open=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, asset_address=None, direction=None, phase=None, decoded_error=None, preflight_result=None, raw_revert_data=None, requested_raw_amount=None, available_raw_amount=None, minimum_raw_amount=None, function_selector=None, error_selector=None, access_delay=None, next_open=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 WhitelistingRequired

Bases: eth_defi.vault.deposit_redeem.VaultFlowUnavailable

A deposit was attempted for a vault whose whitelist excludes the owner.

Raised during deposit preflight when a vault applies a deposit whitelist (permissioned) policy, that policy is applicable and queryable, and the depositing account is not a member of it. The account must be whitelisted by the vault curator before a deposit can succeed.

This is a subclass of VaultFlowUnavailable so existing callers that catch the base preflight failure keep working, while callers that want to react specifically to a missing whitelist entry — for example to surface a “whitelisting required” state instead of a generic failure — can catch this narrower type.

Message contract for diagnostics: whenever this exception is raised, its reason message (the first positional argument, i.e. the text returned by str(exc) before the structured context) must identify the failing deposit unambiguously by including all three of:

  • the chain id the vault is deployed on (chain_id()),

  • the vault contract address (address()), and

  • the depositor address that was denied (the request owner/caller).

These three values must be embedded in the message string itself — not only passed through the vault_address and caller structured fields — so a single logged message line is self-describing for diagnostics without the reader having to reconstruct the failing vault or account from surrounding context. Include the structured vault_address and caller fields as well. VaultDepositManager.check_deposit_whitelist() produces a compliant message; adapters that raise this directly must do the same.

Contract for adapter authors: every deposit manager must raise this from its deposit preflight when the vault’s whitelist policy can be determined, is applicable, and the owner is not permitted. Use VaultDepositManager.check_deposit_whitelist() to satisfy the contract. When the policy cannot be determined (the adapter’s whitelist reads raise NotImplementedError) this exception must not be raised; the deposit either proceeds and surfaces any genuine denial as an onchain revert, or a protocol adapter may fail closed with a plain VaultFlowUnavailable if unknown admission is unsafe.

Store structured context for a vault-flow failure.

__init__(reason, *, protocol=None, vault_address=None, caller=None, asset_address=None, direction=None, phase=None, decoded_error=None, preflight_result=None, raw_revert_data=None, requested_raw_amount=None, available_raw_amount=None, minimum_raw_amount=None, function_selector=None, error_selector=None, access_delay=None, next_open=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.

Parameters

  • reason – Human-readable explanation of why the simulation cannot run.

  • unsupported_reason – Stable, machine-readable adapter reason. This is retained separately from reason so consumers never need to parse exception prose.

  • protocol – Protocol adapter that rejected settlement, when known.

  • vault_address – Vault whose settlement was rejected, when known.

  • direction – deposit or redeem for the rejected asynchronous ticket.

  • phase – Lifecycle phase that was rejected. Defaults to settlement.

Store a machine-readable settlement refusal and its vault context.

Parameters

  • reason – Human-readable explanation of the refusal.

  • unsupported_reason – Stable adapter reason for consumer result mapping.

  • protocol – Protocol adapter that rejected settlement, when known.

  • vault_address – Vault whose settlement was rejected, when known.

  • direction – Rejected asynchronous ticket direction, when known.

  • phase – Rejected lifecycle phase.

__init__(reason, *, unsupported_reason=None, protocol=None, vault_address=None, direction=None, phase='settlement')

Store a machine-readable settlement refusal and its vault context.

Parameters

  • reason (str) – Human-readable explanation of the refusal.

  • unsupported_reason (Optional[str]) – Stable adapter reason for consumer result mapping.

  • protocol (Optional[str]) – Protocol adapter that rejected settlement, when known.

  • vault_address (Optional[eth_typing.evm.HexAddress]) – Vault whose settlement was rejected, when known.

  • direction (Optional[Literal['deposit', 'redeem']]) – Rejected asynchronous ticket direction, when known.

  • phase (str) – Rejected lifecycle phase.

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.

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 VaultDirectPayoutEvidence

Bases: object

Evidence for an asynchronous request settled by direct token payment.

Some protocols consume a request and pay the receiver without exposing an intermediate claimable state. Such a transition is terminal only when the request-specific event and the receiver’s denomination-token balance agree. This intentionally contains no protocol-specific event payload so consumers can apply the same terminal-result rule to every adapter.

Parameters

  • request_id – Identifier of the request consumed by the settlement transaction.

  • receiver – Receiver whose denomination-token balance was observed.

  • denomination_token – Token paid by the direct settlement.

  • raw_balance_before – Receiver balance immediately before the settlement transaction.

  • raw_balance_after – Receiver balance immediately after the settlement transaction.

  • event_name – Name of the decoded request-specific settlement event.

  • transaction_hash – Transaction that emitted event_name and paid the receiver.

has_positive_balance_delta()

Return whether the observed direct payment increased the balance.

Returns

True only when the receiver received a positive raw amount.

Return type

bool

__init__(request_id, receiver, denomination_token, raw_balance_before, raw_balance_after, event_name, transaction_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.

synthetic_assets_injected_raw: int

Denomination tokens synthetically injected on an Anvil fork to let the settlement round complete, in the denomination token’s raw units.

Zero (the default) means the settlement used only real on-fork state. A non-zero value means the driver wrote synthetic token balance into the vault (e.g. topped up a Lagoon Safe that was short of redemption liquidity) to make the ticket claimable. In that case a claimable result proves only that the settlement mechanism works on a fork — it does NOT prove the vault can currently pay this redemption onchain. supports_anvil_settlement=True similarly means “the driver can advance tickets on a fork”, not “the vault is solvent”. Callers that need a real-liquidity guarantee must assert this is zero.

liquidity_constraints_ignored: bool

True when the Anvil-only simulation explicitly bypassed a protocol liquidity admission check. This is separate from synthetic_assets_injected_raw: a protocol mock can relax a maxRedeem-style gate without minting any denomination tokens.

A result with this flag set proves the guarded call and settlement mechanics only. It is never evidence that the live deployment has enough immediately available redemption liquidity.

direct_payout_evidence: Optional[eth_defi.vault.deposit_redeem.VaultDirectPayoutEvidence]

Evidence for terminal direct-payout protocols such as Ember. It is required whenever status_after is none for an asynchronous settlement result.

is_terminal_success()

Return whether this result proves its protocol settlement finished.

Claimable tickets are terminal settlement success: the caller can now execute the ordinary protocol claim. A protocol that pays directly may instead return none only with request-specific event evidence and a positive receiver balance delta. A pending, missing, or evidence-free consumed status is never a successful forced settlement. This evaluates settlement state only: callers requiring live-liquidity evidence must also assert synthetic_assets_injected_raw == 0 and not liquidity_constraints_ignored.

Returns

True for a synchronous no-op, a claimable async ticket, or a validated direct-payout terminal transition.

Return type

bool

__init__(ticket, settlement_required, status_before, status_after, transaction_hashes=(), synthetic_assets_injected_raw=0, liquidity_constraints_ignored=False, direct_payout_evidence=None)
Parameters
Return type

None

class VaultRedemptionSimulationIntervention

Bases: object

Disclosed Anvil-only intervention used before a real redemption call.

The intervention changes fork state only. A caller must still build, broadcast and analyse the protocol’s real redemption transaction after this result is returned. It must never be interpreted as evidence that the live vault had enough redemption liquidity.

kind: Literal['liquidity_injected', 'redemption_capacity_increased']

Intervention type for machine-readable reports.

token: eth_typing.evm.HexAddress

Denomination token whose forked balance was changed.

target: eth_typing.evm.HexAddress

Vault or protocol liquidity adapter that received the token.

raw_amount: int

Raw token quantity added on the fork.

original_reason: str

Original typed preflight explanation.

original_preflight_result: Optional[str]

Original machine-readable preflight result when available.

evidence: dict[str, str | int]

Protocol-specific, JSON-safe evidence fields.

Raw integer values are serialised as strings by as_dict().

as_dict()

Return JSON-safe intervention evidence.

Integer quantities are serialised as decimal strings so large token values remain exact across JSON consumers.

Returns

Machine-readable intervention fields.

Return type

dict[str, str]

__init__(kind, token, target, raw_amount, original_reason, original_preflight_result=None, evidence=<factory>)
Parameters
Return type

None

create_synchronous_settlement_result()

Create the standard no-op outcome for a synchronous vault flow.

Synchronous requests complete in their own transaction and therefore have no ticket or settlement status to advance. Managers exposing mixed flows reuse this value for their synchronous direction.

Returns

A zero-transaction result indicating no settlement is required.

Return type

eth_defi.vault.deposit_redeem.VaultForcedSettlementResult

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 GuardV0ValidationCall

Bases: object

One independently validated manager-generated call.

Parameters

  • target – Contract address selected by the deposit manager.

  • calldata – Complete ABI-encoded call data, including its selector.

  • selector – First four bytes of calldata retained for consumer evidence.

target: eth_typing.evm.HexAddress

Contract selected by the vault manager.

calldata: eth_typing.encoding.HexStr

Complete manager-generated call data.

selector: hexbytes.main.HexBytes

Function selector extracted from the call data.

__init__(target, calldata, selector)
Parameters
Return type

None

class ClosedDepositGuardValidation

Bases: object

Evidence returned after GuardV0 accepts a closed-vault deposit call.

This proves GuardV0 compatibility of independently validated manager calls. It does not prove an ERC-20 approval sequence, a successful vault deposit or a minted share balance.

Parameters

  • vault_address – Vault whose closed deposit preflight produced the call.

  • owner – Safe/SimpleVault address used as the deposit receiver.

  • raw_amount – Requested denomination amount in raw units.

  • closure_reason – Original typed closure prose retained for reporting.

  • preflight_result – Typed closure result which authorised validation-only construction.

  • calls – Manager-generated calls accepted by GuardV0.

vault_address: eth_typing.evm.HexAddress

Vault that remains closed to an actual deposit.

owner: eth_typing.evm.HexAddress

Safe/SimpleVault used as deposit owner and receiver.

raw_amount: int

Raw denomination amount requested for the validated deposit flow.

closure_reason: str

Human-readable closure reason from the manager preflight.

preflight_result: str

Stable manager closure result, e.g. deposit_closed.

calls: tuple[eth_defi.vault.deposit_redeem.GuardV0ValidationCall, ...]

All calls which GuardV0 accepted independently.

__init__(vault_address, owner, raw_amount, closure_reason, preflight_result, calls)
Parameters
Return type

None

validate_closed_deposit_request_with_guard(request, closure, guard, asset_manager)

Validate manager-generated closed-deposit calls through GuardV0.

The request must come from VaultDepositManager.create_deposit_request_for_guard_validation() after a typed closure preflight. Each manager-generated call is encoded and passed separately to the supplied GuardV0-compatible contract using a static call. The helper neither creates an ERC-20 approval nor broadcasts a transaction, so it cannot establish approval ordering or prove that the closed vault would accept a deposit.

Parameters
Returns

Closure context plus every independently GuardV0-accepted target and selector, suitable for a consumer’s persisted outcome evidence.

Raises

ValueError – If closure is not a matching typed closed or paused deposit result.

Return type

eth_defi.vault.deposit_redeem.ClosedDepositGuardValidation

class VaultDepositManager

Bases: abc.ABC

Abstract base for every vault deposit and redemption flow.

New public manager integrations must follow eth_defi/erc_4626/README-vault-protocol-support.md: a manager is supported only after its complete lifecycle executes through GuardV0 on an Anvil fork, with a protocol-shaped mock where fork state cannot cover a required path.

A deposit manager wraps one VaultBase and hides the differences between synchronous ERC-4626 vaults, asynchronous ERC-7540 vaults, and protocol-specific variants (Lagoon, Gains, IPOR, Ember, cSigma, and others) behind one request/settle/claim interface. This base class is policy-agnostic: it defines the contract and provides only the shared whitelist preflight and the Anvil no-op settlement; concrete subclasses supply the actual onchain behaviour.

Deposit process

A deposit is built with create_deposit_request(), which returns a DepositRequest wrapper of one or more transactions to sign and broadcast. The flow may be synchronous or asynchronous depending on the subclass — has_synchronous_deposit() reports which. The owner must first approve() the ERC-20 denomination token to the spender returned by get_deposit_approval_target() (the vault address by default). For a synchronous vault the request transaction mints shares immediately to the receiver. For an asynchronous vault the request transaction only registers a request; the shares are later claimed once settled via can_finish_deposit() and finish_deposit(). The receiver defaults to owner; a separate to receiver is only honoured where the protocol supports it. Progress is tracked with a DepositTicket.

Redemption process

A redemption is built with create_redemption_request(), returning a RedemptionRequest wrapper. has_synchronous_redemption() reports whether the flow is synchronous (shares burned and assets returned in the request transaction) or asynchronous (request now, settle, then claim). The asynchronous lifecycle is: create the request, broadcast, parse the resulting RedemptionTicket, wait for the redemption delay or operator settlement, then claim with finish_redemption(). Some operator-finalised protocols pay the receiver directly and return None from finish_redemption(); fetch_completed_redemption_tx_hash() locates that terminal transaction instead. A request is identified by its RedemptionTicket (owner, receiver, raw shares, request transaction hash, and a protocol request id via RedemptionTicket.get_request_id()).

Queues and settlement

Asynchronous protocols queue pending requests and settle them off the common interface (epoch rollovers, an operator/curator transaction, a settlement silo, etc.); get_deposit_request_status() and get_redemption_request_status() map protocol state onto AsyncVaultRequestStatus (none/pending/claimable/ reclaimable), and fetch_vault_flow_events() streams pending requests from an indexed backend. Synchronous subclasses have no queue: the request transaction is the settlement.

Lockups and cooldowns

Any lockup, cooldown, redemption delay or epoch window is protocol-specific. estimate_redemption_delay() returns the vault-wide delay (not account-specific), and get_redemption_delay_over() returns the naive UTC time an account may claim, or None when there is no deterministic onchain deadline. can_create_redemption_request() reflects windows such as an epoch that only accepts requests on some days. Synchronous subclasses report a zero delay.

Whitelisting / access control

Deposit admission is enforced by check_deposit_whitelist(), the shared preflight that every subclass must call before returning a request. It raises WhitelistingRequired only when the vault’s whitelist policy is applicable and queryable and the owner is provably not admitted; when the policy cannot be determined it stays silent and lets a genuine denial surface as an onchain revert. Subclasses needing a stricter fail-closed policy may additionally raise VaultFlowUnavailable.

Anvil settlement (force_settle)

force_settle() advances a pending ticket on an Anvil fork for integration tests. It requires an Anvil provider. For synchronous managers it is a no-op (called with None, returns a not-settlement-required result) because the request transaction already completed the lifecycle. Asynchronous managers must override it with a protocol-specific driver; the base raises UnsupportedVaultSimulation when no safe driver exists. ignore_liquidity=False preserves a real-liquidity simulation. An explicitly documented protocol driver may override the default to enable an Anvil-only liquidity-bypass simulation; its result must mark VaultForcedSettlementResult.liquidity_constraints_ignored; it is never live redemption evidence or a way to bypass production preflights.

__init__(vault)
Parameters

vault (eth_defi.vault.base.VaultBase) –

check_deposit_whitelist(owner)

Reject a deposit when the vault’s whitelist excludes the owner.

Shared deposit-preflight helper implementing the whitelisting contract every manager must honour: when a vault applies a deposit whitelist policy that is applicable and queryable, and owner is not a member of it, raise WhitelistingRequired before any transaction is broadcast so the caller can surface a “whitelisting required” state instead of paying gas for a guaranteed revert.

The check is intentionally conservative — it only raises when the whitelist information can be obtained and is applicable:

Adapters that need a stricter fail-closed policy for an unknown admission state should override their own preflight and raise VaultFlowUnavailable in addition to calling this helper (see the Lagoon manager for an example).

Parameters

owner (eth_typing.evm.HexAddress) – Deposit owner and controller whose whitelist membership is checked.

Raises

WhitelistingRequired – When the vault applies an applicable, queryable whitelist policy and owner is not permitted to deposit.

Return type

None

force_redemption_liquidity(owner, raw_shares, failure)

Provision an unavailable synchronous redemption on an Anvil fork.

Concrete managers may implement this only for a source-proven liquidity failure. The default is deliberately unsupported: this hook must never bypass admission, minimums, maturity or time locks.

Parameters
Returns

Structured intervention evidence from a concrete manager.

Raises

UnsupportedVaultSimulation – Always for managers without a protocol-specific implementation.

Return type

eth_defi.vault.deposit_redeem.VaultRedemptionSimulationIntervention

force_settle(ticket, *, mock=None, ignore_liquidity=False)

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.

  • mock (Optional[object]) – Optional deployed protocol mock used only by focused local tests. Concrete asynchronous managers may use it to execute their operator/keeper settlement path without broadening production Anvil-fork authority. Passing a mock to a manager that does not implement mock settlement remains a typed unsupported simulation.

  • ignore_liquidity (bool) – Permit a protocol-specific, Anvil-only mock or fork driver to bypass an otherwise unavailable redemption-liquidity gate. This base implementation defaults to False; a documented protocol override may choose a different Anvil-only default. Managers must reject this request unless they have a tested, explicit implementation; it must never weaken a production preflight or live settlement path.

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_deposit_request(owner, to=None, amount=None, raw_amount=None, check_max_deposit=True, check_enough_token=True)

Build the deposit request transaction(s) for an owner.

Abstracts the ERC-4626, ERC-7540, Lagoon and other protocol deposit flows behind a common request wrapper.

Whitelisting contract: implementations must raise WhitelistingRequired before returning a request when the vault applies a deposit whitelist policy, that policy is applicable and queryable, and owner is not permitted to deposit. Call check_deposit_whitelist() at the start of the preflight to satisfy this contract. When the whitelist information cannot be obtained (the adapter’s whitelist reads raise NotImplementedError) the manager must not raise WhitelistingRequired; it either proceeds — letting any real denial surface as an onchain revert — or fails closed with a plain VaultFlowUnavailable when unknown admission is unsafe.

Parameters

  • owner (eth_typing.evm.HexAddress) – Deposit owner and controller.

  • to (eth_typing.evm.HexAddress) – Optional separate receiver, where the protocol supports it.

  • amount (decimal.Decimal) – Human-readable denomination-token amount, converted using the denomination token decimals when raw_amount is not given.

  • raw_amount (int) – Raw denomination-token amount, overriding amount.

  • check_max_deposit – Preflight the deposit against the vault’s deposit capacity.

  • check_enough_token – Preflight that owner holds enough denomination token.

Returns

Deposit request wrapper ready for signing and parsing.

Raises
Return type

eth_defi.vault.deposit_redeem.DepositRequest

create_deposit_request_for_guard_validation(owner, raw_amount)

Build deposit calldata for a closed-vault GuardV0 policy check.

This Anvil-only diagnostic path is for a consumer that has already received a typed deposit_closed or deposit_paused preflight result. Adapters must override it only after proving that their typed result represents a temporary vault closure rather than a capacity or amount restriction. The returned calls must be supplied individually to GuardV0.validateCall(); callers must never broadcast them to the closed protocol vault.

Parameters

  • owner (eth_typing.evm.HexAddress) – SimpleVaultV0/Safe address that would own the shares.

  • raw_amount (int) – Denomination-token amount in the selected asset’s raw unit.

Returns

Manager-generated deposit request suitable only for isolated GuardV0 validation.

Raises

UnsupportedVaultSimulation – Unless the protocol-specific manager implements this diagnostic path.

Return type

eth_defi.vault.deposit_redeem.DepositRequest

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