erc_4626.vault_protocol.t3tris.deposit_redeem

Documentation for eth_defi.erc_4626.vault_protocol.t3tris.deposit_redeem Python module.

T3tris asynchronous deposit and redemption flow.

T3tris vaults in closed mode take deposits and redemptions as requests. The vault curator settles all pending requests of the current epoch, and the owner then claims the minted shares or the redeemed assets. The lifecycle matches ERC-7540, but the function signatures differ, so this manager reuses the generic queued manager and overrides only the calls whose ABI differs.

See README-t3tris.md in this package for the verified call semantics and the GuardV0 coverage.

Module Attributes

T3TRIS_ORACLE_ABI

Minimal T3tris oracle interface used by the Anvil settlement driver.

T3TRIS_SETTLE_FEE_CLAIM_TYPE

feeClaimType passed by the T3tris curator in observed settlements.

T3TRIS_OPEN_MODE_UNSUPPORTED

Stable preflight result for a vault in synchronous open mode.

T3TRIS_REQUEST_IN_PROGRESS

Stable preflight result when the owner already has an open request.

Classes

T3trisDepositManager

Asynchronous T3tris request, settlement and claim flow.

T3TRIS_ORACLE_ABI = [{'type': 'function', 'name': 'owner', 'inputs': [], 'outputs': [{'name': '', 'type': 'address'}], 'stateMutability': 'view'}, {'type': 'function', 'name': 'setTotalAssets', 'inputs': [{'name': 'totalAssets', 'type': 'uint256'}], 'outputs': [], 'stateMutability': 'nonpayable'}]

Minimal T3tris oracle interface used by the Anvil settlement driver.

No oracle ABI is published. setTotalAssets(uint256) is the call the oracle owner sends onchain before each settlement.

T3TRIS_SETTLE_FEE_CLAIM_TYPE = 0

feeClaimType passed by the T3tris curator in observed settlements.

T3TRIS_OPEN_MODE_UNSUPPORTED = 'synchronous_mode_unsupported'

Stable preflight result for a vault in synchronous open mode.

T3TRIS_REQUEST_IN_PROGRESS = 'request_in_progress'

Stable preflight result when the owner already has an open request.

class T3trisDepositManager

Bases: eth_defi.erc_7540.deposit_redeem.ERC7540DepositManager

Asynchronous T3tris request, settlement and claim flow.

Deposit process. Asynchronous. The owner approves the denomination token to the vault, then create_deposit_request() builds requestDeposit(owner, false, assets, ""). The vault-wide epoch id is read from the DepositRequest event into an ERC7540DepositTicket. After the curator settles the epoch, finish_deposit() builds claimDeposit(owner).

Redemption process. Asynchronous. create_redemption_request() builds requestRedeem(owner, owner, owner, false, shares); after settlement finish_redemption() builds claimRedeem(owner, owner, false).

Queues and settlement. Request ids are vault-wide epochs and the per-owner state is keyed by (owner, requestId). Claims are owner-wide, and a new request first claims any settled request in the same direction. This manager therefore refuses a new request while the owner has a pending or claimable one, and reads every ticket’s status for its own request id.

Whitelisting / access control. Deposits use the shared check_deposit_whitelist() preflight backed by isDepositWhitelisted. Redemptions check isWithdrawWhitelisted when the withdrawal whitelist is enabled.

Unsupported surfaces. Open-mode synchronous vaults, Permit2 deposits, unsafe flows and request decreases are not implemented.

Anvil settlement. force_settle() impersonates the oracle owner to refresh the valuation and the curator to call settle().

Initialise the manager for a T3tris vault.

Parameters

vault – T3tris vault adapter. It is not an ERC7540Vault because its request and claim ABI differs from the standard.

__init__(vault)

Initialise the manager for a T3tris vault.

Parameters

vault (eth_defi.erc_4626.vault_protocol.t3tris.vault.T3trisVault) – T3tris vault adapter. It is not an ERC7540Vault because its request and claim ABI differs from the standard.

is_deposit_in_progress(owner)

Check whether the owner has a pending or claimable deposit request.

Parameters

owner (eth_typing.evm.HexAddress) – Request owner.

Returns

True when the owner’s latest deposit request is open.

Return type

bool

is_redemption_in_progress(owner)

Check whether the owner has a pending or claimable redemption request.

Parameters

owner (eth_typing.evm.HexAddress) – Request owner.

Returns

True when the owner’s latest redemption request is open.

Return type

bool

can_create_deposit_request(owner)

Return whether a deposit request would pass the preflight.

Parameters

owner (eth_typing.evm.HexAddress) – Request owner.

Returns

True when no preflight refusal applies.

Return type

bool

can_create_redemption_request(owner)

Return whether a redemption request would pass the preflight.

Parameters

owner (eth_typing.evm.HexAddress) – Share owner.

Returns

True when no preflight refusal applies.

Return type

bool

create_deposit_request(owner, to=None, amount=None, raw_amount=None, check_max_deposit=True, check_enough_token=True)

Build a T3tris requestDeposit transaction.

Parameters
  • owner (eth_typing.evm.HexAddress) – Asset owner and share receiver.

  • to (eth_typing.evm.HexAddress) – Must be None or owner; T3tris claims to the request receiver.

  • amount (decimal.Decimal) – Human-readable denomination-token amount.

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

  • check_max_deposit (bool) – Ignored. maxDeposit describes only the open-mode flow.

  • check_enough_token (bool) – Verify that the owner holds the denomination tokens.

Returns

Request wrapper ready for signing and parsing.

Raises

VaultFlowUnavailable – If a preflight refuses the request.

Return type

eth_defi.erc_7540.deposit_redeem.ERC7540DepositRequest

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

Build a T3tris requestRedeem transaction.

Parameters
  • owner (eth_typing.evm.HexAddress) – Share owner and asset receiver.

  • to (eth_typing.evm.HexAddress) – Must be None or owner.

  • shares (decimal.Decimal) – Human-readable vault-share amount.

  • raw_shares (int) – Raw vault-share amount, overriding shares.

  • check_max_deposit (bool) – Ignored; kept for the common manager API.

  • check_enough_token (bool) – Verify that the owner holds the requested shares.

Returns

Request wrapper ready for signing and parsing.

Raises

VaultFlowUnavailable – If a preflight refuses the request.

Return type

eth_defi.erc_7540.deposit_redeem.ERC7540RedemptionRequest

create_redemption_request_for_analysis(owner, raw_shares)

Rebuild a mined redemption request without rerunning preflights.

The open-request preflight would reject the very request being analysed.

Parameters
Returns

Request parser with the original call shape.

Return type

eth_defi.erc_7540.deposit_redeem.ERC7540RedemptionRequest

get_deposit_request_status(ticket)

Map the ticket’s own request epoch to the generic status.

Parameters

ticket (eth_defi.erc_7540.deposit_redeem.ERC7540DepositTicket) – Deposit ticket.

Returns

Claimable, pending or empty request status.

Return type

eth_defi.vault.deposit_redeem.AsyncVaultRequestStatus

get_redemption_request_status(ticket)

Map the ticket’s own request epoch to the generic status.

Parameters

ticket (eth_defi.erc_7540.deposit_redeem.ERC7540RedemptionTicket) – Redemption ticket.

Returns

Claimable, pending or empty request status.

Return type

eth_defi.vault.deposit_redeem.AsyncVaultRequestStatus

can_finish_deposit(deposit_ticket)

Check whether the ticket’s deposit epoch has been settled.

Parameters

deposit_ticket (eth_defi.erc_7540.deposit_redeem.ERC7540DepositTicket) – Deposit ticket.

Returns

True when shares are claimable.

Return type

bool

can_finish_redeem(redemption_ticket)

Check whether the ticket’s redemption epoch has been settled.

Parameters

redemption_ticket (eth_defi.erc_7540.deposit_redeem.ERC7540RedemptionTicket) – Redemption ticket.

Returns

True when assets are claimable.

Return type

bool

finish_deposit(deposit_ticket)

Build claimDeposit(receiver) for a settled request.

Parameters

deposit_ticket (eth_defi.vault.deposit_redeem.DepositTicket) – Settled deposit ticket.

Returns

Bound claim function.

Return type

web3.contract.contract.ContractFunction

finish_redemption(redemption_ticket)

Build claimRedeem(owner, receiver, false) for a settled request.

Parameters

redemption_ticket (eth_defi.vault.deposit_redeem.RedemptionTicket) – Settled redemption ticket.

Returns

Bound claim function.

Return type

web3.contract.contract.ContractFunction

analyse_deposit(claim_tx_hash, deposit_ticket)

Analyse a claimDeposit transaction.

Parameters
Returns

Shares received and assets deposited, or a failure.

Return type

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

analyse_redemption(claim_tx_hash, redemption_ticket)

Analyse a claimRedeem transaction.

Parameters
Returns

Shares burned and assets received, or a failure.

Return type

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

get_estimated_lock_up()

Return the vault’s non-binding settlement estimate.

T3trisVault.get_withdrawal_period() is the source of truth; this keeps the estimate available through the manager API, as Lagoon’s manager does.

Returns

Average settlement interval, or None when unknown.

Return type

Optional[datetime.timedelta]

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

Settle the current T3tris epoch on an Anvil fork.

Refreshes the oracle valuation as the oracle owner, at unchanged total assets, then settles as the curator. Settlement processes every pending request in the epoch, not only the ticket’s. A redemption settlement pulls assets from the curator wallet, so it fails as a typed result when the curator cannot pay.

Parameters
Returns

Before/after status and the two settlement transaction hashes.

Raises

UnsupportedVaultSimulation – If the provider is not Anvil, an unsupported option is given, the ticket is not pending or the settlement does not complete.

Return type

eth_defi.vault.deposit_redeem.VaultForcedSettlementResult

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:

  • if is_whitelisted_deposit() raises NotImplementedError, the vault-wide policy cannot be determined for this adapter/version, so no exception is raised;

  • if the vault is permissionless, no exception is raised;

  • if is_account_whitelisted() raises NotImplementedError, per-account membership cannot be queried, so no exception is raised;

  • only when the policy is applicable and the owner is provably not admitted is WhitelistingRequired raised.

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

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

deposit_request_class

alias of eth_defi.erc_7540.deposit_redeem.ERC7540DepositRequest

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

Estimate shares for a denomination-token amount.

ERC-7540 retains the ERC-4626 convertToShares preview used here; the estimate does not imply that the request is currently admissible.

Parameters
  • owner (eth_typing.evm.HexAddress) – Request controller. The standard preview is not owner-specific.

  • amount (decimal.Decimal) – Human-readable denomination-token amount.

  • block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Block at which to read the conversion rate.

Returns

Estimated human-readable share amount.

Return type

decimal.Decimal

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

Estimate denomination tokens for a vault-share amount.

ERC-7540 retains the ERC-4626 convertToAssets preview used here; the estimate does not imply that the request is currently admissible.

Parameters
  • owner (eth_typing.evm.HexAddress) – Request controller. The standard preview is not owner-specific.

  • shares (decimal.Decimal) – Human-readable vault-share amount.

  • block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Block at which to read the conversion rate.

Returns

Estimated human-readable denomination-token amount.

Return type

decimal.Decimal

estimate_redemption_delay()

Return no deterministic protocol-level redemption delay.

Settlement timing is controlled by each vault operator and is outside the ERC-7540 standard.

Returns

Zero-duration sentinel for an unspecified delay.

Return type

datetime.timedelta

fetch_completed_redemption_tx_hash(ticket)

Find an operator-owned terminal redemption transaction when available.

Claim-based protocols finish through finish_redemption() and do not need this lookup. Operator-finalised protocols override the hook to find and validate the transaction that paid the requested receiver.

Parameters

ticket (eth_defi.vault.deposit_redeem.RedemptionTicket) – Persisted redemption request to locate.

Returns

Terminal transaction hash, or None if the protocol has not observed one yet.

Return type

Optional[hexbytes.main.HexBytes]

fetch_pending_redemption_value(ticket, block_identifier='latest')

Quote a ticket when ordinary share valuation no longer represents it.

The default retains normal share valuation. Protocols with fixed request-time entitlements or burned pending shares override this hook. Returning a value does not recognise cash or complete settlement.

Parameters
  • ticket (eth_defi.vault.deposit_redeem.RedemptionTicket) – Persisted request belonging to one trade.

  • block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Block used for all valuation reads.

Returns

Net denomination value, or None to value ordinary shares.

Return type

Optional[decimal.Decimal]

fetch_vault_flow_events(hypersync_client, start_block, end_block)

Fetch standard ERC-7540 request events using Hypersync.

ERC-7540 vaults emit DepositRequest for deposit requests and RedeemRequest for redemption requests. Protocol-specific legacy events must be handled by a protocol manager subclass.

Parameters
  • hypersync_client – Configured Hypersync client for the vault chain.

  • start_block (int) – Inclusive start block.

  • end_block (int) – Inclusive end block.

Returns

Iterator of indexed pending vault flow events in chain order.

Return type

collections.abc.Iterator[eth_defi.vault.flow_events.PendingVaultFlow]

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

get_deposit_approval_target()

Return the ERC-20 spender required for a deposit request.

Standard ERC-4626 and the currently supported async adapters pull denomination tokens from the vault address itself. An adapter using a different router or silo must override this method; guarded callers use it to whitelist and validate the exact approval calldata.

Returns

ERC-20 approval spender address.

Return type

eth_typing.evm.HexAddress

get_deposit_delay_over(address)

Estimate when a pending async deposit request will settle.

  • Mirror of get_redemption_delay_over() for the deposit side.

  • Used to show an estimated settlement time for unsettled deposits (e.g. in the trade-executor trade-ui table).

  • Default returns None: the protocol has no deterministic 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]

get_deposit_event_signatures()

Return accepted claim-deposit event signatures.

ERC-7540 claims retain the ERC-4626 Deposit event shape.

Returns

Standard ERC-4626 Deposit topic emitted by ERC-7540 claims.

Return type

set[eth_typing.encoding.HexStr]

get_max_deposit(owner)

How much we can deposit

Parameters

owner (eth_typing.evm.HexAddress) –

Return type

Optional[decimal.Decimal]

get_redemption_delay_over(address)

Return the legacy sentinel for an unknown account deadline.

Generic ERC-7540 vaults do not expose a deterministic per-account settlement deadline.

Parameters

address (Union[eth_typing.evm.HexAddress, str]) – Request controller.

Returns

Naive Unix epoch sentinel retained for backwards compatibility.

Return type

datetime.datetime

get_redemption_event_signatures()

Return accepted claim-redemption event signatures.

ERC-7540 claims retain the ERC-4626 Withdraw event shape.

Returns

Standard ERC-4626 Withdraw topic emitted by ERC-7540 claims.

Return type

set[eth_typing.encoding.HexStr]

has_synchronous_deposit()

Report that deposits use the asynchronous request lifecycle.

Returns

Always False for ERC-7540.

Return type

bool

has_synchronous_redemption()

Report that redemptions use the asynchronous request lifecycle.

Returns

Always False for ERC-7540.

Return type

bool

reclaim_deposit(ticket)

Return a function to recover funds after a failed async deposit settlement.

Returns None if the protocol does not support reclaim.

Parameters

ticket (eth_defi.vault.deposit_redeem.DepositTicket) –

Return type

Optional[web3.contract.contract.ContractFunction]

reclaim_withdrawal(ticket)

Return a function to recover shares after a failed async withdrawal settlement.

Returns None if the protocol does not support reclaim.

Parameters

ticket (eth_defi.vault.deposit_redeem.RedemptionTicket) –

Return type

Optional[web3.contract.contract.ContractFunction]

reconstruct_deposit_ticket(data)

Reconstruct a deposit ticket from persistent data.

Both the current string form and the legacy integer form of raw token amounts are accepted for backwards compatibility.

Parameters

data (dict) – Data produced by serialize_deposit_ticket().

Returns

Reconstructed ERC-7540 deposit ticket.

Return type

eth_defi.erc_7540.deposit_redeem.ERC7540DepositTicket

reconstruct_redemption_ticket(data)

Reconstruct a redemption ticket from persistent data.

Both the current string form and the legacy integer form of raw share amounts are accepted for backwards compatibility.

Parameters

data (dict) – Data produced by serialize_redemption_ticket().

Returns

Reconstructed ERC-7540 redemption ticket.

Return type

eth_defi.erc_7540.deposit_redeem.ERC7540RedemptionTicket

redemption_request_class

alias of eth_defi.erc_7540.deposit_redeem.ERC7540RedemptionRequest

serialize_deposit_ticket(ticket)

Serialise an ERC-7540 deposit ticket.

The generic base ticket payload is extended with the ERC-7540 request identifier needed for later status checks.

Parameters

ticket (eth_defi.erc_7540.deposit_redeem.ERC7540DepositTicket) – Deposit ticket to serialise.

Returns

Persistent ticket data including vault_request_id.

Return type

dict

serialize_redemption_ticket(ticket)

Serialise an ERC-7540 redemption ticket.

The ERC-7540 request identifier is retained so a restarted process can query the request-specific claimable amount.

Parameters

ticket (eth_defi.erc_7540.deposit_redeem.ERC7540RedemptionTicket) – Redemption ticket to serialise.

Returns

Persistent ticket data including vault_request_id.

Return type

dict