NaraDepositManager

Documentation for eth_defi.erc_4626.vault_protocol.nara.deposit_redeem.NaraDepositManager Python class.

class NaraDepositManager

Bases: eth_defi.erc_4626.deposit_redeem.ERC4626DepositManager

NaraUSD+ manager with direct deposits and claimed cooldown redemptions.

Attributes summary

web3

Methods summary

__init__(vault)
analyse_deposit(claim_tx_hash, deposit_ticket)	Analyse a mined ERC-4626 deposit or guarded SimpleVault wrapper.
analyse_redemption(claim_tx_hash, ...)	Analyse a mined ERC-4626 redemption or guarded SimpleVault wrapper.
can_create_deposit_request(owner)	Check NaraUSD+'s current ERC-4626 deposit maximum.
can_create_redemption_request(owner)	Check whether the owner can start a NaraUSD+ cooldown.
can_finish_deposit(deposit_ticket)	Synchronous deposits can be finished immediately.
can_finish_redeem(redemption_ticket)	Check whether a NaraUSD+ cooldown claim can now be submitted.
create_deposit_request(owner[, to, amount, ...])
create_redemption_request(owner[, to, ...])	Start the owner-specific NaraUSD+ share cooldown.
estimate_deposit(owner, amount[, ...])	How many shares we get for a deposit.
estimate_redeem(owner, shares[, ...])	How many denomination tokens we get for a redeem.
estimate_redemption_delay()	Read the currently configured NaraUSD+ cooldown duration.
fetch_completed_redemption_tx_hash(ticket)	Find an operator-owned terminal redemption transaction when available.
fetch_cooldown(address)	Read an owner's current NaraUSD+ cooldown state.
fetch_vault_flow_events(hypersync_client, ...)	Fetch asynchronous vault request events from an indexed backend.
finish_deposit(deposit_ticket)	Can we finish the deposit process in async vault.
finish_redemption(redemption_ticket)	Build the NaraUSD+ post-cooldown claim transaction.
get_deposit_approval_target()	Return the ERC-20 spender required for a deposit request.
get_deposit_delay_over(address)	Estimate when a pending async deposit request will settle.
get_deposit_request_status(ticket)	Query the current status of an async deposit request.
get_max_deposit(owner)	How much we can deposit
get_redemption_delay_over(address)	Return an owner's cooldown expiry, when one exists.
get_redemption_request_status(ticket)	Report whether a NaraUSD+ cooldown is pending or claimable.
has_synchronous_deposit()	Does this vault support synchronous deposits?
has_synchronous_redemption()	Return whether NaraUSD+ redemptions settle immediately.
is_deposit_in_progress(owner)	Check if the owner has an active deposit request.
is_redemption_in_progress(owner)	Check whether an owner has an unclaimed NaraUSD+ cooldown.
reclaim_deposit(ticket)	Return a function to recover funds after a failed async deposit settlement.
reclaim_withdrawal(ticket)	Return a function to recover shares after a failed async withdrawal settlement.
reconstruct_deposit_ticket(data)	Reconstruct a deposit ticket from a serialised dict.
reconstruct_redemption_ticket(data)	Reconstruct a NaraUSD+ cooldown ticket after a process restart.
serialize_deposit_ticket(ticket)	Serialise a deposit ticket to a dict for persistence.
serialize_redemption_ticket(ticket)	Serialise a NaraUSD+ ticket with its exact cooldown identity.

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

Start the owner-specific NaraUSD+ share cooldown.

Parameters

• owner (eth_typing.evm.HexAddress) – NaraUSD+ share owner initiating the cooldown.

• to (Optional[eth_typing.evm.HexAddress]) – Final NaraUSD receiver, defaulting to the share owner.

• shares (Optional[decimal.Decimal]) – Decimal NaraUSD+ share amount, exclusive with raw_shares.

• raw_shares (Optional[int]) – Raw NaraUSD+ share amount, exclusive with shares.

• check_max_deposit (bool) – Retained inherited argument; Nara controls redemption through cooldown state.

• check_enough_token (bool) – Check the owner’s current NaraUSD+ balance.

Returns

One-call cooldown request to settle through finish_redemption().

Return type

eth_defi.erc_4626.vault_protocol.nara.deposit_redeem.NaraRedemptionRequest

has_synchronous_redemption()

Return whether NaraUSD+ redemptions settle immediately.

Returns

Always False because the owner must complete a cooldown first.

Return type

bool

is_redemption_in_progress(owner)

Check whether an owner has an unclaimed NaraUSD+ cooldown.

Parameters

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

Returns

True when the vault records a non-zero cooldown deadline.

Return type

bool

can_create_deposit_request(owner)

Check NaraUSD+’s current ERC-4626 deposit maximum.

Parameters

owner (eth_typing.evm.HexAddress) – Prospective deposit receiver.

Returns

True when the current maximum is positive.

Return type

bool

can_create_redemption_request(owner)

Check whether the owner can start a NaraUSD+ cooldown.

Parameters

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

Returns

True when the owner has shares and no active cooldown.

Return type

bool

estimate_redemption_delay()

Read the currently configured NaraUSD+ cooldown duration.

Returns

Current cooldown as a timedelta.

Return type

datetime.timedelta

fetch_cooldown(address)

Read an owner’s current NaraUSD+ cooldown state.

Parameters

address (Union[eth_typing.evm.HexAddress, str]) – NaraUSD+ share owner.

Returns

Cooldown expiry timestamp and raw escrowed NaraUSD assets.

Return type

tuple[int, int]

get_redemption_delay_over(address)

Return an owner’s cooldown expiry, when one exists.

Parameters

address (Union[eth_typing.evm.HexAddress, str]) – NaraUSD+ share owner.

Returns

Naive UTC cooldown expiry, or None when no claim is pending.

Return type

Optional[datetime.datetime]

can_finish_redeem(redemption_ticket)

Check whether a NaraUSD+ cooldown claim can now be submitted.

Parameters

redemption_ticket (eth_defi.erc_4626.vault_protocol.nara.deposit_redeem.NaraRedemptionTicket) – Persisted cooldown request.

Returns

True when the current chain timestamp has reached the deadline.

Return type

bool

reconstruct_redemption_ticket(data)

Reconstruct a NaraUSD+ cooldown ticket after a process restart.

Parameters

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

Returns

NaraUSD+ cooldown ticket.

Return type

eth_defi.erc_4626.vault_protocol.nara.deposit_redeem.NaraRedemptionTicket

serialize_redemption_ticket(ticket)

Serialise a NaraUSD+ ticket with its exact cooldown identity.

Parameters

ticket (eth_defi.erc_4626.vault_protocol.nara.deposit_redeem.NaraRedemptionTicket) – NaraUSD+ cooldown ticket.

Returns

JSON-compatible persistent ticket data.

Return type

dict

get_redemption_request_status(ticket)

Report whether a NaraUSD+ cooldown is pending or claimable.

Parameters

ticket (eth_defi.erc_4626.vault_protocol.nara.deposit_redeem.NaraRedemptionTicket) – NaraUSD+ cooldown ticket.

Returns

pending before maturity, claimable afterwards, or none when the cooldown was claimed, removed, or superseded by another cooldown for the same owner.

Return type

eth_defi.vault.deposit_redeem.AsyncVaultRequestStatus

finish_redemption(redemption_ticket)

Build the NaraUSD+ post-cooldown claim transaction.

Parameters

redemption_ticket (eth_defi.erc_4626.vault_protocol.nara.deposit_redeem.NaraRedemptionTicket) – Matured cooldown ticket.

Returns

unstake contract call that sends NaraUSD to the requested receiver.

Return type

web3.contract.contract.ContractFunction

__init__(vault)

Parameters

vault (ERC4626Vault) –

analyse_deposit(claim_tx_hash, deposit_ticket)

Analyse a mined ERC-4626 deposit or guarded SimpleVault wrapper.

A ticket identifies an expected SimpleVault wrapper by address. The event analyser still filters events by the underlying vault address.

Parameters

• claim_tx_hash (Union[hexbytes.main.HexBytes, str]) – Mined deposit transaction hash.

• deposit_ticket (Optional[eth_defi.vault.deposit_redeem.DepositTicket]) – Optional ticket whose owner identifies a guarded wrapper.

Returns

Decoded executed deposit quantities or a revert description.

Return type

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

analyse_redemption(claim_tx_hash, redemption_ticket)

Analyse a mined ERC-4626 redemption or guarded SimpleVault wrapper.

A ticket identifies the wrapper only for the transaction-target check; the decoded Withdraw event must still originate from this vault.

Parameters

• claim_tx_hash (Union[hexbytes.main.HexBytes, str]) – Mined redemption transaction hash.

• redemption_ticket (Optional[eth_defi.vault.deposit_redeem.RedemptionTicket]) – Optional ticket whose owner identifies a guarded wrapper.

Returns

Decoded executed redemption quantities or a revert description.

Return type

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

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

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

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]

has_synchronous_deposit()

Does this vault support synchronous deposits?

• E.g. ERC-4626 vaults

Return type

bool

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

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