erc_4626.vault_protocol.lagoon.deposit_redeem

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

Lagoon-specific extensions to the generic ERC-7540 flow.

Module Attributes

`LEGACY_DEPOSIT_TOPIC`	Legacy Lagoon `Deposit` event topic accepted during claim analysis.
`LEGACY_WITHDRAW_TOPIC`	Legacy Lagoon `Withdraw` event topic accepted during claim analysis.

Classes

`ERC7540DepositManager`	alias of `eth_defi.erc_4626.vault_protocol.lagoon.deposit_redeem.LagoonDepositManager`
`LagoonDepositManager`	Lagoon ERC-7540 flow with access-policy and settlement support.

ADDRESS_NOT_ALLOWED_SELECTOR = HexBytes('0x51ee5ed5'): AddressNotAllowed(address) custom-error selector in Lagoon v0.6.

NOT_WHITELISTED_SELECTOR = HexBytes('0x584a7938'): NotWhitelisted() custom-error selector in Lagoon v0.5 and earlier.

REQUEST_DEPOSIT_SELECTOR = HexBytes('0x85b77f45'): requestDeposit(uint256,address,address) Lagoon entry-point selector.

ERC7540DepositManager: alias of eth_defi.erc_4626.vault_protocol.lagoon.deposit_redeem.LagoonDepositManager

class ERC7540DepositRequest

Bases: eth_defi.vault.deposit_redeem.DepositRequest

Asynchronous deposit request for ERC-7540 vaults.

parse_deposit_transaction(tx_hashes)

Parse one standard ERC-7540 deposit-request transaction.

The final receipt must contain exactly one standard DepositRequest event from which the request identifier is read.

Parameters: tx_hashes (list[hexbytes.main.HexBytes]) – Transaction hashes belonging to the request.
Returns: Parsed request ticket with its ERC-7540 request identifier.
Raises: CannotParseRedemptionTransaction – If the receipt does not contain exactly one DepositRequest event.
Return type: eth_defi.erc_7540.deposit_redeem.ERC7540DepositTicket

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

Parameters

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

Return type

None

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

Broadcast all the transactions in this request.

Parameters

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

Returns

List of transaction hashes

Raises

TransactionAssertionError – If any of the transactions revert

Return type

eth_defi.vault.deposit_redeem.RedemptionTicket

class ERC7540DepositTicket

Bases: eth_defi.vault.deposit_redeem.DepositTicket

Asynchronous deposit request for ERC-7540 vaults.

request_id: int: ERC-7540 request identifier.

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

Parameters

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

Return type

None

class ERC7540RedemptionRequest

Bases: eth_defi.vault.deposit_redeem.RedemptionRequest

Asynchronous redemption request for ERC-7540 vaults.

parse_redeem_transaction(tx_hashes)

Parse one standard ERC-7540 redemption-request transaction.

The final receipt must contain exactly one standard RedeemRequest event from which the request identifier is read.

Parameters: tx_hashes (list[hexbytes.main.HexBytes]) – Transaction hashes belonging to the request.
Returns: Parsed request ticket with its ERC-7540 request identifier.
Raises: CannotParseRedemptionTransaction – If the receipt does not contain exactly one RedeemRequest event.
Return type: eth_defi.erc_7540.deposit_redeem.ERC7540RedemptionTicket

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

Parameters

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

Return type

None

broadcast(from_=None, gas=1000000)

Broadcast all the transactions in this request.

Parameters

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

Returns

List of transaction hashes

Return type

list[hexbytes.main.HexBytes]

class ERC7540RedemptionTicket

Bases: eth_defi.vault.deposit_redeem.RedemptionTicket

Asynchronous redemption request for ERC-7540 vaults.

request_id: int: ERC-7540 request identifier.

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

Parameters

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

Return type

None

abstract get_request_id()

Get the redemption request id.

If vault uses some sort of request ids to track the withdrawals
Needed for settlement

Return type: int

class LagoonDepositManager

Bases: eth_defi.erc_7540.deposit_redeem.ERC7540DepositManager

Lagoon ERC-7540 flow with access-policy and settlement support.

The generic ERC-7540 manager supplies standard request, claim, ticket and event handling. Lagoon adds versioned access checks, legacy claim-event topics and an Anvil settlement driver that impersonates the deployed valuation manager and Safe.

Initialise the Lagoon manager.

The constructor narrows the generic manager to Lagoon vault adapters because later operations rely on Lagoon roles and version detection.

Parameters: vault – Lagoon vault adapter.

__init__(vault)

Initialise the Lagoon manager.

The constructor narrows the generic manager to Lagoon vault adapters because later operations rely on Lagoon roles and version detection.

Parameters: vault (eth_defi.erc_4626.vault_protocol.lagoon.vault.LagoonVault) – Lagoon vault adapter.

force_settle(ticket)

Force one Lagoon settlement round on an Anvil fork.

The simulation impersonates the vault’s valuation manager and Safe, then checks that the selected request becomes claimable.

Parameters: ticket (Optional[Union[eth_defi.vault.deposit_redeem.DepositTicket, eth_defi.vault.deposit_redeem.RedemptionTicket]]) – Pending deposit or redemption ticket to progress.
Returns: Before/after status and settlement transaction hashes.
Raises: UnsupportedVaultSimulation – If the provider is not Anvil, the ticket is unsupported, or the settlement does not make the request claimable.
Return type: eth_defi.vault.deposit_redeem.VaultForcedSettlementResult

can_create_deposit_request(owner)

Return whether Lagoon’s current access policy admits an owner.

Unknown access policy fails closed. Transient provider failures still propagate so callers can distinguish an unavailable read from a known denial.

Parameters: owner (eth_typing.evm.HexAddress) – Request owner and controller.
Returns: True only when the vault is open and its access view admits the owner.
Return type: bool

get_deposit_event_signatures()

Return Lagoon claim-deposit event topics.

Legacy deployments use a non-standard topic while current releases emit the ERC-4626 Deposit event accepted by the generic manager.

Returns: Standard and legacy Lagoon deposit topics.
Return type: set[eth_typing.encoding.HexStr]

get_redemption_event_signatures()

Return Lagoon claim-redemption event topics.

Legacy deployments use a non-standard topic while current releases emit the ERC-4626 Withdraw event accepted by the generic manager.

Returns: Standard and legacy Lagoon withdrawal topics.
Return type: set[eth_typing.encoding.HexStr]

analyse_deposit(claim_tx_hash, deposit_ticket)

Analyse a completed ERC-7540 deposit claim.

The method decodes the ERC-4626 Deposit event emitted by the second-stage claim transaction. Protocol subclasses may extend the accepted event signatures for legacy deployments.

Parameters

claim_tx_hash (Union[hexbytes.main.HexBytes, str]) – Deposit-claim transaction hash.
deposit_ticket (Optional[eth_defi.vault.deposit_redeem.DepositTicket]) – Original asynchronous request ticket.

Returns

Decoded token movement, or a failed-transaction diagnostic.

Raises

RuntimeError – If a successful receipt does not contain an accepted event.

Return type

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

analyse_redemption(claim_tx_hash, redemption_ticket)

Analyse a completed ERC-7540 redemption claim.

The method decodes the ERC-4626 Withdraw event emitted by the second-stage claim transaction. Protocol subclasses may extend the accepted event signatures for legacy deployments.

Parameters

claim_tx_hash (Union[hexbytes.main.HexBytes, str]) – Redemption-claim transaction hash.
redemption_ticket (Optional[eth_defi.vault.deposit_redeem.RedemptionTicket]) – Original asynchronous request ticket.

Returns

Decoded token movement, or a failed-transaction diagnostic.

Raises

RuntimeError – If a successful receipt does not contain an accepted event.

Return type

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

can_create_redemption_request(owner)

Return whether the vault is currently open for a redemption request.

The generic ERC-7540 layer checks only the optional pause flag; protocol-specific redemption rules belong in manager subclasses.

Parameters: owner (eth_typing.evm.HexAddress) – Request owner and controller.
Returns: False when the vault reports that requests are paused.
Return type: bool

can_finish_deposit(deposit_ticket)

Check whether a deposit request is ready to claim.

The ERC-7540 claimableDepositRequest view returns a positive asset amount after the operator has settled the request.

Parameters: deposit_ticket (eth_defi.erc_7540.deposit_redeem.ERC7540DepositTicket) – Deposit request to inspect.
Returns: True when the request has claimable assets.
Return type: bool

can_finish_redeem(redemption_ticket)

Check whether a redemption request is ready to claim.

The ERC-7540 claimableRedeemRequest view returns a positive share amount after the operator has settled the request.

Parameters: redemption_ticket (eth_defi.erc_7540.deposit_redeem.ERC7540RedemptionTicket) – Redemption request to inspect.
Returns: True when the request has claimable shares.
Return type: bool

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

Build the standard ERC-7540 requestDeposit transaction.

Parameters

owner (eth_typing.evm.HexAddress) – Controller and owner of the request.
to (eth_typing.evm.HexAddress) – Unsupported separate receiver; ERC-7540 requests use owner.
amount (decimal.Decimal) – Human-readable denomination-token amount.
raw_amount (int) – Raw denomination-token amount, overriding amount.
check_max_deposit – Reserved for parity with the common manager API.
check_enough_token – Reserved for parity with the common manager API.

Returns

Request wrapper ready for signing and parsing.

Raises

VaultFlowUnavailable – If the vault’s optional pause view reports that requests are paused.

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 the standard ERC-7540 requestRedeem transaction.

Parameters

owner (eth_typing.evm.HexAddress) – Controller and owner of the request.
to (eth_typing.evm.HexAddress) – Unsupported separate receiver; ERC-7540 requests use owner.
shares (decimal.Decimal) – Human-readable vault-share amount.
raw_shares (int) – Raw vault-share amount, overriding shares.
check_max_deposit – Reserved for parity with the common manager API.
check_enough_token – Whether to verify that the owner still holds the requested shares.

Returns

Request wrapper ready for signing and parsing.

Return type

eth_defi.erc_7540.deposit_redeem.ERC7540RedemptionRequest

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

finish_deposit(deposit_ticket)

Build the ERC-7540 transaction that claims deposit shares.

The request must already be settled. The ticket supplies the controller, receiver and settled asset amount.

Parameters: deposit_ticket (eth_defi.vault.deposit_redeem.DepositTicket) – Settled asynchronous deposit ticket.
Returns: Bound three-argument deposit claim function.
Return type: web3.contract.contract.ContractFunction

finish_redemption(redemption_ticket)

Build the ERC-7540 transaction that claims redeemed assets.

The request must already be settled. The ticket supplies the controller, receiver and settled share amount.

Parameters: redemption_ticket (eth_defi.vault.deposit_redeem.RedemptionTicket) – Settled asynchronous redemption ticket.
Returns: Bound three-argument redeem claim function.
Return type: web3.contract.contract.ContractFunction

get_deposit_approval_target()

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

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

Returns: ERC-20 approval spender address.
Return type: eth_typing.evm.HexAddress

get_deposit_delay_over(address)

Estimate when a pending async deposit request will settle.

Mirror of get_redemption_delay_over() for the deposit side.
Used to show an estimated settlement time for unsettled deposits (e.g. in the trade-executor trade-ui table).
Default returns None: the protocol has no deterministic on-chain settlement schedule (e.g. operator-driven ERC-7540 vaults like Lagoon). Subclasses with a predictable settlement cadence (e.g. Ostium V1.5) override this to return an estimated UTC timestamp.

Parameters: address (Union[eth_typing.evm.HexAddress, str]) – Owner of the pending deposit request.
Returns: Naive UTC timestamp when the deposit is expected to settle, or None when no on-chain estimate is available.
Return type: Optional[datetime.datetime]

get_deposit_request_status(ticket)

Map ERC-7540 deposit state to the generic status enum.

Check the request-specific claimable amount first: an aggregate pendingDepositRequest(0, owner) query lumps together all of the owner’s requests, so probing it first would report an already-settled request as still pending whenever another request is outstanding. The generic interface has no reclaim signal, so reclaimable is never returned.

Parameters: ticket (eth_defi.erc_7540.deposit_redeem.ERC7540DepositTicket) – Deposit request to inspect.
Returns: Claimable, pending or empty request status.
Return type: eth_defi.vault.deposit_redeem.AsyncVaultRequestStatus

get_max_deposit(owner)

How much we can deposit

Parameters: owner (eth_typing.evm.HexAddress) –
Return type: Optional[decimal.Decimal]

get_redemption_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_request_status(ticket)

Map ERC-7540 redemption state to the generic status enum.

Request-specific claimable is checked before the aggregate pending query for the same reason as get_deposit_request_status().

Parameters: ticket (eth_defi.erc_7540.deposit_redeem.ERC7540RedemptionTicket) – Redemption request to inspect.
Returns: Claimable, pending or empty request status.
Return type: eth_defi.vault.deposit_redeem.AsyncVaultRequestStatus

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

is_deposit_in_progress(owner)

Check pending ERC-7540 request.

Query pendingDepositRequest(0, owner) when the request identifier is not known. Per ERC-7540, request identifier zero aggregates the controller’s pending deposit assets. A value greater than zero means at least one request remains unsettled.

Parameters: owner (eth_typing.evm.HexAddress) – Controller address to inspect.
Returns: True if the controller has pending deposit assets.
Return type: bool

is_redemption_in_progress(owner)

Check whether a controller has pending redemption shares.

Request identifier zero aggregates the controller’s pending redemption shares under ERC-7540.

Parameters: owner (eth_typing.evm.HexAddress) – Controller address to inspect.
Returns: True if the controller has pending redemption shares.
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

LagoonDepositRequest: alias of eth_defi.erc_7540.deposit_redeem.ERC7540DepositRequest