An upgradeable (UUPS), yield-accruing vault token denominated in an underlying asset (e.g., USDC) that holds its liquidity in an ERC-4626 savings sleeve (e.g., spUSDC), featuring asynchronous FIFO queues for deposits, deposit cancellations, and redemptions in capacity- and liquidity-constrained environments.
totalAssets() (totalSupply * chi) is the value owed to share holders at the administered rate, not the assets held by the vault. The vault's savings share balance also backs pending deposits and cancellations, and TAKER_ROLE can move it out for external allocation, so it does not track totalAssets().
The vault token is a standard ERC-20 (with EIP-2612-style permit, supporting both EOA and ERC-1271 signatures) whose decimals match the underlying asset. Transfers to the zero address or to the vault itself are rejected.
Warning
THIS VAULT IS INTENDED TO BE USED WITH spark-vaults-v2@v1.0.1 AS THE savings VAULT. ANY OTHER savings IMPLEMENTATION SHOULD BE REVIEWED FROM FIRST PRINCIPLES.
If another vault is used, it must AT LEAST adhere to these standards:
Savings vault
redeem(shares, receiver, owner)succeeds for any amount, including zero shares, or shares that round to zero assets. This is because processing the redeem and cancellation queues can callredeemwith 0 or dust amounts that are worth zero assets.maxWithdraw(address(this))andmaxRedeem(address(this))return amounts that aredeemin the same block will honour in full.- No deposit or exit fee.
convertToAssets,convertToShares, and the executed amounts agree up to rounding, and the full asset amount reaches the receiver. - The share price never decreases.
- Redemptions are synchronous and pay out to an arbitrary receiver.
depositaccepts the vault as both caller and receiver.
Underlying asset
transfersucceeds for any amount, including zero.
- Yield accrues continuously via the Vault Savings Rate (
vsr), a per-second compounding factor (ray). drip()(public) compounds accumulated interest into the accumulatorchi. It is also invoked bysetVSR,impair,requestDeposit,requestRedeem, and allprocess*functions.requestDepositCancellationdoes not drip.- Share-to-asset conversion:
assets = shares * nowChi() / RAY, wherenowChi()is the up-to-datechiwithout writing state. - Initialized with
chi = vsr = minVSR = maxVSR = RAY(0% yield) until the admin sets bounds andOPERATOR_ROLEsets a rate. vsrmust stay within[minVSR, maxVSR]. Bounds are configured byDEFAULT_ADMIN_ROLEwithminVSR >= RAYandmaxVSR <= MAX_VSR(100% APY).- Loss Realization: While paused,
LOSS_MANAGER_ROLEcan callimpair(assets_)to settle the pending drip and rewritechiso thattotalAssetsis decremented byassets_. Pausing first blocks deposit and redeem requests and their processing so they cannot front-run the impairment; deposit cancellations remain available while paused.assets_must be nonzero and at mosttotalAssets, andtotalSupplymust be non-zero. Impairing the fulltotalAssetssetschito zero and bricks every conversion until an upgrade. Gains are not booked on-chain; yield reaches holders only through the VSR.
Deposits are two-step: the user's assets go to the savings sleeve immediately, and vault shares are minted once there is capacity.
- Request:
requestDeposit(assets, recipient, referral)pullsassetsfrom the caller, deposits them into the savings vault (spUSDC) and queues a request denominated in savings shares. Requiresassets >= minDepositand thatrecipientis neither the zero address nor the vault. EmitsReferral(with the integrator'sreferralcode) andDepositRequest. - Instant Fill: If the new request is the only pending deposit (nothing queued ahead of it) and capacity is available, it is processed within the same transaction.
- Queueing: Otherwise the request waits in the FIFO
_depositRequestsqueue. Queued depositors keep earning savings yield while waiting, since the vault holds their savings shares. - Capacity: Fills are bounded by
availableCapacity() = maxCapacity - totalSupply(floored at 0), converted to savings shares. - Processing:
OPERATOR_ROLEcallsprocessPendingDeposits(maxSavingsShares, maxRequests). Savings shares are converted to assets and then minted asspPrimeto each request'srecipientat the currentchi. Requests can be partially filled; a partially filled request stays at the head of the queue. - Updating the recipient: The request
ownercan callupdateDepositRecipient(requestId, recipient)to change who receives the minted shares.
- Request: The request
owner(only) callsrequestDepositCancellation(requestId, recipient, savingsShares)on a still-pending deposit.recipientmust be neither the zero address nor the vault.savingsSharesmust be at leastminDepositCancellationand at most the request's unfilled savings shares; they move to the FIFO_depositCancellationRequestsqueue. - Partial cancellation: If all unfilled savings shares are cancelled, the deposit request is removed. Otherwise it keeps the rest and its position in the deposit queue.
- Cleanup: Fully cancelled entries (zero shares) stay in the deposit queue until
processPendingDeposits(or an instant fill) skips over them, which happens even when there is no available capacity. An instant fill is still possible behind cancelled entries, since it depends onpendingDepositSavingsSharesrather than the queue length. - Processing:
OPERATOR_ROLEcallsprocessPendingDepositCancellations(maxSavingsShares, maxRequests), which redeems the savings shares for the underlying asset and sends it to therecipient. Bounded by what the savings vault can redeem (maxRedeem). Because the refund is made from the queued savings shares, it includes all savings yield accrued while queued. Partial fills are supported. - Updating the recipient: The
ownercan callupdateDepositCancellationRecipient(requestId, recipient).
Redemptions are always asynchronous (there is no instant fill).
- Request:
requestRedeem(shares, recipient)transferssharesfrom the caller into the vault, requiresshares >= minRedeem(checked before the fee) and thatrecipientis neither the zero address nor the vault. - Redeem Fee: The fee is taken upfront in shares:
fee = ceil(shares * redeemFeeRate / WAD)is burned immediately, and onlyshares - feeis queued. The rate is locked in at request time. EmitsRedeemRequest(requestId, owner, recipient, sharesToBurn, feeSharesBurned). - Queueing: Queued shares are escrowed in the vault (counted in
pendingRedeemShares) and keep earning vault yield until processed. - Processing:
OPERATOR_ROLEcallsprocessPendingRedeems(maxShares, maxRequests). Bounded byavailableLiquidAssets()(the savings vault'smaxWithdrawfor the vault). For each fill, the escrowed shares are burned, their value is converted to savings shares (rounding down, so rounding stays with the vault), and those savings shares are redeemed from the savings vault straight to therecipient. Partial fills are supported. - Updating the recipient: The
ownercan callupdateRedeemRecipient(requestId, recipient).
- Assets are paid out to recipients by the savings vault directly. If the redemption of savings shares to a recipient fails, the assets are instead redeemed to the vault and credited to
claimableAssetsOf[recipient], so a failing request cannot block the queue. EmitsClaimableAssetsIncreased. claim(recipient)is permissionless and always sends the assets torecipient; it reverts while transferring the assets to the recipient fails.- If the fallback redemption to the vault also fails (e.g. the savings vault is reverted for some reason or the vault itself cannot receive), the whole
process*call reverts.
take(savingsShares): TheTAKER_ROLEcan transfer any savings shares (e.g.,spUSDC) held by the vault, including those backing pending deposits and cancellations, to itself for external allocation. Reverts if the amount exceeds the vault's balance. EmitsTake.
- All three queues (deposit, deposit cancellation, redeem) are FIFO and are processed with
maxRequestsbounding the number of entries visited per call, so processing can be batched. - Each queue's head is tracked by a processed counter (
processedDepositCount,processedDepositCancellationCount,processedRedeemCount); fully filled entries are deleted and the head advances past them. - Aggregate pending amounts are tracked in
pendingDepositSavingsShares,pendingCancelledDepositSavingsShares, andpendingRedeemShares.totalClaimabletracks the sum ofclaimableAssetsOf. - Pending requests can be inspected with
pending{Deposit,DepositCancellation,Redeem}RequestsLength(),getPending{Deposit,DepositCancellation,Redeem}Request(requestId)(reverts withInvalidRequestIdif outside the pending range),pending*Requests()(full pending list; the deposit list can include fully cancelled entries with zero shares), orgetPending*Requests(startId, length). The ranged getter reverts ifstartIdis before the queue head (StartIdTooSmall) or greater than the queue length (StartIdTooLarge);lengthis clamped to the entries available, so overshooting or alengthof zero returns a shorter or empty array rather than reverting.
PAUSER_ROLEcanpause;UNPAUSER_ROLEcanunpause.- While paused,
requestDeposit,requestRedeem,processPendingDeposits, andprocessPendingRedeemsrevert. - Deposit cancellations stay available so depositors can always exit:
requestDepositCancellationandprocessPendingDepositCancellationswork while paused. Recipient updates,claim,take,drip, and ERC-20 transfers/approvals also remain available. impaircan only be called while paused.
The vault is designed for Spark Vault V2 savings vaults (e.g., spUSDC) and relies on the following:
- Deposits from the vault are accepted:
requestDepositdeposits into the savings vault with the vault as caller and receiver. It reverts if the vault holds the savings vault'sTAKER_ROLE(Spark Vault V2 rejects deposits from takers) or if the deposit would exceed the savings vault's deposit cap. - No fees:
convertToShares/convertToAssetsare used for pricing, so deposits and redemptions must not charge fees. - Share price never falls: savings shares are worth at least as many assets over time.
maxRedeem/maxWithdraware honoured: amounts within these bounds can be redeemed in the same transaction (maxWithdrawsizes redeem fills,maxRedeemsizes cancellation fills).- Synchronous payout:
redeemdelivers assets in the same call. - Zero amounts succeed:
redeemof zero (or of dust that converts to zero assets) does not revert, and the asset accepts zero-value transfers. Queue remainders can produce such calls.
| Parameter | Setter (role) | Notes |
|---|---|---|
maxCapacity |
setCapacity (OPERATOR_ROLE) |
Max totalSupply used to size deposit fills. At most uint128 max. |
minDeposit |
setMinDeposit (DEFAULT_ADMIN_ROLE) |
Minimum assets per requestDeposit. Nonzero. |
minDepositCancellation |
setMinDepositCancellation (DEFAULT_ADMIN_ROLE) |
Minimum savings shares per requestDepositCancellation. Nonzero. |
minRedeem |
setMinRedeem (DEFAULT_ADMIN_ROLE) |
Minimum shares per requestRedeem. Nonzero. |
minVSR/maxVSR |
setVSRBounds (DEFAULT_ADMIN_ROLE) |
RAY <= minVSR <= maxVSR <= MAX_VSR. |
vsr |
setVSR (OPERATOR_ROLE) |
Must be within [minVSR, maxVSR]; drips before updating. |
maxRedeemFeeRate |
setMaxRedeemFeeRate (DEFAULT_ADMIN_ROLE) |
Wad; capped by the MAX_REDEEM_FEE constant (1%). |
redeemFeeRate |
setRedeemFeeRate (REDEEM_FEE_SETTER_ROLE) |
Wad; must be <= maxRedeemFeeRate. |
| Role | Permitted Actions | Description |
|---|---|---|
DEFAULT_ADMIN_ROLE |
setMaxRedeemFeeRate, setMinDeposit, setMinDepositCancellation, setMinRedeem, setVSRBounds, upgradeToAndCall (_authorizeUpgrade) |
Governs vault parameters, bounds, and contract upgrades. |
LOSS_MANAGER_ROLE |
impair |
Writes down totalAssets (and by extension chi) to realize a loss (only while paused). Cannot increase chi. |
OPERATOR_ROLE |
setCapacity, setVSR |
Sets the deposit capacity and the Vault Savings Rate within configured bounds ([minVSR, maxVSR]). |
OPERATOR_ROLE |
processPendingDeposits, processPendingDepositCancellations, processPendingRedeems |
Settles the deposit, deposit-cancellation, and redeem queues (deposits and redeems only while unpaused). |
TAKER_ROLE |
take |
Withdraws any savings shares held by the vault, including those backing pending deposits and cancellations, for portfolio allocation. |
REDEEM_FEE_SETTER_ROLE |
setRedeemFeeRate |
Configures the redemption fee rate (≤ maxRedeemFeeRate). |
PAUSER_ROLE |
pause |
Emergency pause of deposit/redeem requests and their processing (deposit cancellations stay available). |
UNPAUSER_ROLE |
unpause |
Unpause of requests and queue processing. |
| Request owner | requestDepositCancellation, updateDepositRecipient, updateDepositCancellationRecipient, updateRedeemRecipient |
Only the owner of a request can cancel it or change its recipient. |
| Public / Permissionless | requestDeposit, requestRedeem, claim, drip, ERC-20 (approve, transfer, transferFrom), permit, view functions |
Standard user interactions, rate accrual, and claiming assets owed to recipients whose requests failed at process-time. |
AccessControlEnumerable is used, so role members can be enumerated on-chain.