Skip to main content

​
Purpose

The RedeemQueue contract enables delayed, batched redemptions of vault shares into underlying assets. Redemptions are processed in two phases:
  1. Oracle pricing – Shares are priced via a trusted price report.
  2. Liquidity settlement – Vault liquidity is allocated to fulfill priced requests.
This separation supports asynchronous liquidity management, gas efficiency, and protection against griefing.

​
Overview

The RedeemQueue enables users to convert their vault shares into underlying assets, introducing a time delay enforced by an oracle-defined redeemInterval. It maintains the following core invariants:
  1. Request Format: Each request is structured as a (shares, timestamp) pair.
  2. Non-Cancellable: Redemption requests cannot be cancelled to prevent griefing (e.g., submitting and canceling after unstaking starts).
  3. Multiple Requests Allowed: Users may submit multiple independent redemption requests.
Upon receiving an oracle report at reportTimestamp, the system processes all requests with:
On the next step these vault shares are converted to assets at the price specified in the oracle report in this step.

​
Liquidity Processing (Two-Stage)

To enable flexible and asynchronous liquidity management, redemption is handled in two distinct phases:
  1. Post-Request: Vault curators monitor and, if needed, pull liquidity from external protocols.
  2. Post-Oracle Report:
    • Once a valid report is submitted and sufficient liquidity is available,
    • Anyone can call handleBatches(n) on the RedeemQueue. The function has no access control, and in practice the curator or a keeper calls it,
    • This action triggers the movement of required assets from the vault (and associated subvaults) to process redemption requests.

​
Function: redeem

  1. Reverts with ZeroValue if shares is zero, or with QueuePaused if the vault has paused the queue.
  2. Locks shares from the caller with shareManager.lock(caller, shares). Locked shares move to the share manager’s own balance and no longer count as the caller’s active shares.
  3. Unless the caller is the fee recipient, computes the redeem fee with feeManager.calculateRedeemFee(shares). The fee is burned from the locked shares, minted to the fee recipient and subtracted from the request.
  4. Adds the remaining shares to the request at the current timestamp and emits RedeemRequested(account, shares, timestamp).
Requests made in the same block are merged into one entry for that timestamp.

​
Function: handleBatches

Settles up to batches priced batches, in order, starting from batchIterator:
  1. Reads available liquidity with vault.getLiquidAssets(), which uses the queue’s redeem hook.
  2. Takes batches while their cumulative assets fit within that liquidity, and stops at the first batch that does not fit.
  3. Calls vault.callHook(demand), so the redeem hook pulls the assets from subvaults and the vault transfers them to the queue.
  4. Decreases the vault balance in the RiskManager and totalDemandAssets, advances batchIterator and emits RedeemRequestsHandled(counter, demand).
Locked shares are burned when an oracle report prices them, not in handleBatches.

​
Scalability Approach

Unlike deposits, redemption requests are never cancelled, which allows for a simplified and gas-efficient tracking model: A prefix sum array is used to efficiently manage cumulative share redemptions over time.

​
Redemption Processing Logic

  • On Redemption: When a user redeems amount of shares at time T, the system logs: prefixSum[T] += amount
  • On Oracle Report: At reportTimestamp, all requests with:
    are priced into a new batch. The batch’s shares are burned from the share manager’s locked balance, and its asset value (shares * 1e18 / priceD18) is added to totalDemandAssets.
  • Post-Processing:
    • The curator ensures the necessary asset liquidity is available,
    • Then anyone, usually the curator or a keeper, calls handleBatches() to finalize processing.
  • User Claim: After requests are processed, users can call:
    to claim assets for their requested vault shares corresponding to each processed timestamp.

​
Storage Layout

All internal state is maintained in RedeemQueueStorage, including:

​
Structs

​
Request

Represents a single redemption request from a user:
  • timestamp: When the request was submitted.
  • shares: Amount of vault shares being redeemed.
  • isClaimable: Set to true after batch is fulfilled.
  • assets: Amount of assets claimable for this request (set after pricing).

​
Batch

Represents a priced redemption batch:
  • assets: Total value fulfilled for the batch (via oracle shares / report.price).
  • shares: Total shares matched in this batch.

​
View Functions

​
requestsOf(account, offset, limit)

Returns paginated redemption request data for the specified account. Each request includes:
  • Timestamp
  • Shares
  • Claimable status
  • Asset amount

​
batchAt(index)

Returns the (assets, shares) for a given redemption batch.

​
getState()

Returns core system state:
  • Current batchIterator (next unfulfilled batch index)
  • Total batches
  • Total demandedAssets still awaiting liquidity
  • Total pendingShares that are not yet claimable

​
State Transition Guarantees

  1. Non-Cancellable Requests
    • Prevents griefing where a user requests redemption, causing curator to pull liquidity, then cancels.
  2. Price Separation
    • Oracle reports must be delayed by at leastredeemInterval seconds from the original request.
  3. Asynchronous Fulfillment
    • Liquidity can be managed independently of oracle report submission.

​
Events

  • RedeemRequested(account, shares, timestamp)
  • RedeemRequestClaimed(account, receiver, assets, timestamp)
  • RedeemRequestsHandled(counter, demand)