erc_4626.vault_protocol.ember.deposit_redeem

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

Ember synchronous-deposit and operator-finalised redemption support.

Ember deposits follow ERC-4626 deposit(uint256,address) semantics, while withdrawals use redeemShares(uint256,address) and are later paid directly to the requested receiver by the vault operator. See the Ember vault contracts.

Classes

`EmberDepositManager`	Ember adapter with synchronous deposits and asynchronous redemptions.
`EmberRedemptionRequest`	Two-call Ember redemption request: share approval and queue creation.
`EmberRedemptionTicket`	Persisted Ember withdrawal request.

class EmberRedemptionTicket

Bases: eth_defi.vault.deposit_redeem.RedemptionTicket

Persisted Ember withdrawal request.

Ember’s globally monotonic request sequence identifies the later RequestProcessed event. The request block bound makes the terminal log lookup efficient and makes restart-safe persistence possible.

request_sequence_number: int: Globally monotonic Ember withdrawal request sequence.

block_number: int: Block that emitted RequestRedeemed.

block_timestamp: datetime.datetime: Naive UTC timestamp of block_number.

get_request_id()

Return Ember’s globally monotonic withdrawal request identifier.

Returns: Request sequence number used by the operator processing event.
Return type: int

__init__(vault_address, owner, to, raw_shares, tx_hash, request_sequence_number, block_number, block_timestamp)

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_sequence_number (int) –
block_number (int) –
block_timestamp (datetime.datetime) –

Return type

None

class EmberRedemptionRequest

Bases: eth_defi.vault.deposit_redeem.RedemptionRequest

Two-call Ember redemption request: share approval and queue creation.

parse_redeem_transaction(tx_hashes)

Parse and validate the RequestRedeemed receipt event.

The event is emitted by the Ember vault even when the outer transaction is a GuardV0 SimpleVault or Lagoon module call. Its timestamp is required to equal the receipt block timestamp at millisecond precision.

Parameters: tx_hashes (list[hexbytes.main.HexBytes]) – Hashes broadcast for this request; the final hash is redemption.
Returns: Validated, restart-safe Ember redemption ticket.
Raises: CannotParseRedemptionTransaction – If the receipt does not contain one matching Ember request event.
Return type: eth_defi.erc_4626.vault_protocol.ember.deposit_redeem.EmberRedemptionTicket

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

Bases: eth_defi.erc_4626.deposit_redeem.ERC4626DepositManager

Ember adapter with synchronous deposits and asynchronous redemptions.

Create an Ember manager for a protocol-specific Ember vault.

Parameters: vault – Ember vault adapter whose ABI exposes the custom withdrawal queue.

__init__(vault)

Create an Ember manager for a protocol-specific Ember vault.

Parameters: vault (EmberVault) – Ember vault adapter whose ABI exposes the custom withdrawal queue.

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

Build one synchronous Ember deposit call with an explicit receiver.

Ember uses standard ERC-4626 deposits but emits VaultDeposit rather than Deposit. The generic constructor otherwise remains suitable.

Parameters

owner (eth_typing.evm.HexAddress) – Address funding the denomination token transfer.
to (Optional[eth_typing.evm.HexAddress]) – Share receiver; defaults to owner.
amount (Optional[decimal.Decimal]) – Decimal denomination amount, mutually exclusive with raw amount.
raw_amount (Optional[int]) – Raw denomination amount, mutually exclusive with decimal amount.
check_max_deposit (bool) – Check the vault’s current ERC-4626 maximum when requested.
check_enough_token (bool) – Check the owner’s current denomination balance when requested.

Returns

One-call synchronous deposit request.

Return type

eth_defi.erc_4626.deposit_redeem.ERC4626DepositRequest

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

Build Ember share approval followed by redeemShares.

Ember does not use ERC-4626 redeem. It escrows shares after a self-allowance and lets its operator transfer the final assets later.

Parameters

owner (eth_typing.evm.HexAddress) – Owner of Ember vault shares.
to (Optional[eth_typing.evm.HexAddress]) – Final asset receiver; defaults to owner.
shares (Optional[decimal.Decimal]) – Decimal shares, mutually exclusive with raw shares.
raw_shares (Optional[int]) – Raw shares, mutually exclusive with decimal shares.
check_max_deposit (bool) – Retained inherited API argument; Ember applies its own queue rules.
check_enough_token (bool) – Validate the owner’s current share balance before binding calls.

Returns

Two-call Ember request in approval then redemption order.

Return type

eth_defi.erc_4626.vault_protocol.ember.deposit_redeem.EmberRedemptionRequest

has_synchronous_deposit()

Return whether Ember deposits finish in their submitted transaction.

Returns: Always True for Ember deposits.
Return type: bool

has_synchronous_redemption()

Return whether Ember redemptions finish in their submitted transaction.

Returns: Always False because an operator later processes the request.
Return type: bool

is_deposit_in_progress(owner)

Return whether Ember has an asynchronous deposit queue.

Parameters: owner (eth_typing.evm.HexAddress) – Ignored; Ember deposits are synchronous.
Returns: Always False.
Return type: bool

is_redemption_in_progress(owner)

Check the owner-specific Ember pending withdrawal amount.

getAccountState(owner) returns the owner’s totalPendingWithdrawalShares as its first ABI-named value, followed by that same owner’s pending sequence list. This is not a vault-global pending-share getter.

Parameters: owner (eth_typing.evm.HexAddress) – Ember share owner to inspect.
Returns: True when this owner has pending withdrawal shares.
Return type: bool

can_create_deposit_request(owner)

Check whether Ember currently advertises deposit availability.

The inherited API has no amount parameter, so this is not a cap or fillability guarantee. The actual deposit call still enforces the requested amount and current remaining cap.

Parameters: owner (eth_typing.evm.HexAddress) – Prospective deposit receiver used for maxDeposit.
Returns: True when deposits are unpaused and a positive maximum exists.
Return type: bool

can_create_redemption_request(owner)

Check current Ember withdrawal queue availability for an owner.

Parameters: owner (eth_typing.evm.HexAddress) – Owner whose share balance is checked.
Returns: True when withdrawals are unpaused and the owner can redeem at least Ember’s minimum withdrawal share amount.
Return type: bool

estimate_redemption_delay()

Return Ember’s off-chain operator service estimate.

The value comes from EmberVault.get_estimated_lock_up(), which reads Ember’s cached off-chain metadata and uses its documented four-day fallback. It is not an on-chain processing deadline.

Returns: Documented estimated operator processing interval.
Return type: datetime.timedelta

get_redemption_delay_over(address)

Return no deadline because Ember processing is operator-driven.

Parameters: address (Union[eth_typing.evm.HexAddress, str]) – Ignored Ember requester address.
Returns: Always None because no deterministic on-chain deadline exists.
Return type: Optional[datetime.datetime]

can_finish_redeem(redemption_ticket)

Report that an Ember depositor never owns a final claim call.

Parameters: redemption_ticket (eth_defi.erc_4626.vault_protocol.ember.deposit_redeem.EmberRedemptionTicket) – Ember ticket whose settlement is operator-finalised.
Returns: Always False.
Return type: bool

finish_redemption(redemption_ticket)

Return no call because only Ember’s operator may process withdrawals.

Parameters: redemption_ticket (eth_defi.erc_4626.vault_protocol.ember.deposit_redeem.EmberRedemptionTicket) – Ember ticket retained for type validation.
Returns: Always None; never an operator-only processing call.
Return type: Optional[web3.contract.contract.ContractFunction]

get_redemption_request_status(ticket)

Map the exact Ember request sequence to pending or consumed state.

Parameters: ticket (eth_defi.erc_4626.vault_protocol.ember.deposit_redeem.EmberRedemptionTicket) – Persisted Ember redemption request.
Returns: pending while its sequence remains in the owner list, otherwise none. none is not evidence of successful payment.
Return type: eth_defi.vault.deposit_redeem.AsyncVaultRequestStatus

fetch_completed_redemption_tx_hash(ticket)

Locate and validate the operator RequestProcessed transaction.

The globally monotonic request sequence selects a candidate event within the ticket’s request-block-to-tip range. Owner, receiver and shares are then validated rather than used as filters, preventing a malformed ABI decode from being silently converted into a false None.

Parameters: ticket (eth_defi.vault.deposit_redeem.RedemptionTicket) – Ember redemption ticket whose terminal event is sought.
Returns: Unique matching operator transaction, or None before observed.
Raises: ValueError – If a matching sequence has inconsistent identity or duplicates.
Return type: Optional[hexbytes.main.HexBytes]

analyse_deposit(claim_tx_hash, deposit_ticket)

Analyse the actual Ember VaultDeposit receipt event.

Parameters

claim_tx_hash (Union[hexbytes.main.HexBytes, str]) – Mined direct, GuardV0 or Lagoon-module deposit transaction.
deposit_ticket (Optional[eth_defi.vault.deposit_redeem.DepositTicket]) – Expected request details when available.

Returns

Executed deposit amounts or a transaction failure result.

Return type

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

analyse_redemption(claim_tx_hash, redemption_ticket)

Analyse one terminal Ember operator processing event.

Parameters

claim_tx_hash (Union[hexbytes.main.HexBytes, str]) – Operator transaction hash returned by completion lookup.
redemption_ticket (Optional[eth_defi.vault.deposit_redeem.RedemptionTicket]) – Ember ticket used to select and validate the terminal event.

Returns

Executed payout, or skipped/cancelled terminal failure evidence.

Return type

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

serialize_redemption_ticket(ticket)

Serialise Ember’s sequence and canonical request-block identity.

Parameters: ticket (eth_defi.erc_4626.vault_protocol.ember.deposit_redeem.EmberRedemptionTicket) – Ember ticket to persist across a process restart.
Returns: JSON-compatible base and Ember-specific ticket fields.
Return type: dict

reconstruct_redemption_ticket(data)

Rebuild an Ember ticket from its serialised request identity.

Parameters: data (dict) – JSON-compatible data returned by serialize_redemption_ticket().
Returns: Ticket ready for current-state and terminal-event checks.
Return type: eth_defi.erc_4626.vault_protocol.ember.deposit_redeem.EmberRedemptionTicket

fetch_vault_flow_events(hypersync_client, start_block, end_block)

Fetch historical Ember RequestRedeemed queue requests.

Parameters

hypersync_client – Configured Ethereum Hypersync client.
start_block (int) – Inclusive request-event block range start.
end_block (int) – Inclusive request-event block range end.

Returns

Event-derived pending redemption discovery hints in chain order.

Return type

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

can_finish_deposit(deposit_ticket)

Synchronous deposits can be finished immediately.

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

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

How many shares we get for a deposit.

Parameters

owner (eth_typing.evm.HexAddress) –
amount (decimal.Decimal) –
block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) –

Return type

decimal.Decimal

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

How many denomination tokens we get for a redeem.

Parameters

owner (eth_typing.evm.HexAddress) –
shares (decimal.Decimal) –
block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) –

Return type

decimal.Decimal

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

get_deposit_approval_target()

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

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

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

get_deposit_delay_over(address)

Estimate when a pending async deposit request will settle.

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

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

get_deposit_request_status(ticket)

Query the current status of an async deposit request.

Default implementation probes via can_finish_deposit(). Subclasses should override for more accurate status reporting (e.g. distinguishing reclaimable from pending).

Parameters: ticket (eth_defi.vault.deposit_redeem.DepositTicket) –
Return type: eth_defi.vault.deposit_redeem.AsyncVaultRequestStatus

get_max_deposit(owner)

How much we can deposit

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

reclaim_deposit(ticket)

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

Returns None if the protocol does not support reclaim.

Parameters: ticket (eth_defi.vault.deposit_redeem.DepositTicket) –
Return type: Optional[web3.contract.contract.ContractFunction]

reclaim_withdrawal(ticket)

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

Returns None if the protocol does not support reclaim.

Parameters: ticket (eth_defi.vault.deposit_redeem.RedemptionTicket) –
Return type: Optional[web3.contract.contract.ContractFunction]

reconstruct_deposit_ticket(data)

Reconstruct a deposit ticket from a serialised dict.

Default returns a base DepositTicket. Subclasses override for protocol-specific ticket types.

Parameters: data (dict) –
Return type: eth_defi.vault.deposit_redeem.DepositTicket

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