Desk

The Desk pools USDG to take COUPON exposure within allocation limits. Depositors bear the underlying note risks and may have to wait for deployed capital to become available for withdrawal.

Purpose

A series is only useful if both legs fill. The Desk pools USDG and subscribes through the configured fill policy when SHIELD demand exceeds COUPON demand and the policy and caps permit a fill. Desk depositors earn the coupons (and take the note-buyer’s risk) on the notional the Desk fills.

Structure

fact Desk is an ERC-4626 vault over USDG (reconciled with contracts/src/token/Desk.sol).

fact Structure Calculation

utilisationBps feeds the bond discount: when the Desk is heavily deployed, bonds cheapen to raise Treasury reserves.

Net Asset Value

totalAssets = idleAssets + marked deployed principal + held Stock Token value + retained leg value + keeper reward owed. idleAssets is the USDG balance less totalClaimable (filled requests not yet claimed). The keeper reward the Desk has earned on NoteCore but not yet claimed (keeperOwed) is part of NAV; claiming it moves the amount into idle without changing NAV or the share price, and queue fills price it in.

Held stock is valued at the Treasury feed; when the Treasury cannot value a token it is carried at lastStockMark(token), the last good value of 1e18 base units, refreshed on every state-changing call (StockMarkStale(token, lastMark) is emitted when the fallback is used), for at most maxFeedStaleness after the mark was taken (lastStockMarkAt(token)), and at zero once the mark is older than that (StockMarkExpired(token, lastMark, markedAt)), when setStockWriteOff(token, true) has been applied or when the token was never marked.

Legs kept after a failed redemption (RedemptionFailed) stay in NAV at the Treasury leg value (retainedLegValue(), LegsRetained / LegsReleased) until a later harvest redeems them or the series is written off; the Desk records the units it held at the moment of retention (retainedUnits(seriesId)) and values min(balance, retainedUnits), so legs donated to the Desk after retention do not inflate NAV until a later successful harvest books them as cash.

While the Desk holds a stock whose feed is stale beyond the mark window and that is not written off, maxDeposit and maxMint return 0 and deposits revert, because NAV would understate the stock and dilute existing holders; exits, the queue, harvest and the owner write-off keep working, and deposits reopen when the feed returns or the stock is written off. paused() stays false in this state, so integrators read maxDeposit(user) rather than paused() to know whether deposits are open. totalAssets never reverts on a held-stock feed failure; a stale feed behind a Live or Matured series makes the Treasury leg factor, and with it totalAssets, revert StaleFeed until the feed prints again

Worked Example

illustrative Desk totalAssets 4,000,000 USDG (2,300,000 idle, 1,500,000 deployed, 200,000 held stock). NVDA series: SHIELD 900,000, COUPON 500,000. The Desk already holds 200,000 in another NVDA series.

After filling, D = 900,000 = S, the series matches fully at strike (subject to notionalCap), the Desk holds 400,000,000,000 raw COUPON units, representing 400,000 USDG notional, deployed = 1,900,000 and utilisation is 47.5%.

Withdrawal Queue

1. maxWithdraw(owner) is bounded by idle USDG net of the value of shares escrowed in open requests (previewRedeem(escrowedShares)). Withdrawing up to that amount is a normal ERC-4626 withdraw/redeem, subject to the exit gates below.
2. Beyond that, requestWithdraw(shares, receiver) escrows the shares in the vault and appends a request (WithdrawRequested). The shares must be worth at least minRequestQuote() at the current NAV (default 1 USDG; the owner may set any value from 1 raw unit to 1,000 USDG via setMinRequestQuote, MinRequestQuoteOutOfBounds otherwise), and smaller requests revert RequestTooSmall(assets, minimum). Shares received after a request never join the request. The request is subject to the same exit gates as a direct withdrawal: it reverts ExitBlocked(owner) while the owner is inside minHold or while any settled position is waiting for harvest. cancelWithdrawRequest(id) returns the escrowed shares to the owner.
3. Anyone may call processQueue(n) to walk up to n queue entries in FIFO order (n is clamped to MAX_QUEUE_PROCESS = 50; every visited entry counts, including cancelled or filled ones, and the head is persisted past closed entries). The hold is checked once, at request time; only the harvest gate is checked again at fill: nothing fills while hasUnharvestedSettled() is true. A transfer to a requester after the request re-stamps only the owner’s free balance and never touches the queued entry, so a gift of shares cannot make the head skip and let the next entry take the idle USDG. A request fills only when previewRedeem(shares) fits in idleAssets(); the escrowed shares are burnt at the share price of that moment, WithdrawRequestFilled is emitted, and the USDG is credited to claimable[receiver] (summed in totalClaimable). No token leaves the vault during processing.
4. The receiver calls claim(to) to transfer the whole claimable balance (WithdrawClaimed; NothingToClaim when zero). Claimable USDG is excluded from idleAssets and therefore from NAV.

harvest and fillCoupon also process up to queueProcessLimit entries (constructor default 10, setQueueProcessLimit reverts QueueLimitTooHigh above 50). Governance may clear an open request that is at least REQUEST_CANCEL_GRACE = 7 days old with cancelRequestFor(id); the shares return to the request owner (WithdrawRequestCancelledFor) and an earlier call reverts RequestTooRecent(id). Withdrawals, queue processing and claims are not pausable; maxDeposit/maxMint return zero while paused.

Hold Period

minHold (default 1 day, setMinHold bounded to 1 second to 7 days, MinHoldUpdated) runs from lastDeposit[owner]. Mints stamp the current time.

A transfer carries the sender’s clock to the receiver as a weighted average of the receiver’s existing clock and the incoming one, weighted by the receiver’s whole position (free plus escrowed shares) against the incoming amount and rounded toward the receiver’s existing clock, so moving shares to a fresh address does not shorten the wait and a dust transfer cannot move an established clock in either direction.

Before averaging, the receiver’s previous stamp is clamped to no earlier than now − minHold, which bounds how far an unsolicited transfer can push out a direct exit: a gift of weight w against a position B delays the receiver’s direct withdrawal by at most minHold × w / (B + w).

For a 100,000 USDG position and a one-day hold, a one-hour delay costs the sender about 4,350 USDG worth of shares, which then belong to the receiver. Queued requests are unaffected (the hold is checked at request time only). Escrow moves into and out of the vault for queue requests do not change the clock.

Shared pools of dNOTE such as the Desk gauge are registered by governance with setPoolHolder(account, true) (PoolHolderSet): a registered pool is never stamped and is not a stamp source, so shares coming out of it keep the receiver’s own clock (a receiver that never held dNOTE is stamped with the current time), and staking fresh shares into an aged pool cannot shorten the hold.

Unwound Series

A series in status Unwound counts as settled: harvest(seriesId) calls the core’s withdrawUnwound for the Desk position and releases the principal.

If the core exit is not available, governance may call writeOffSeries(seriesId, legsTo) (allowed for any settled status: Autocalled, Matured, Cancelled or Unwound, NotTerminal otherwise): the position is settled where the core still allows it, the Desk’s COUPON legs are moved to legsTo when non-zero, the deployed principal for the series is released and SeriesWrittenOff(seriesId, principal, legsTo, units) is emitted, so the series no longer blocks exits.

Anything the core still books to the Desk for that series remains collectable through a later harvest.

Redemption That Cannot Pay

When a series has Autocalled or Matured and the core redemption reverts (for example the stock token refuses the transfer), harvest does not fail: it emits RedemptionFailed(seriesId, units, reason), releases the principal at zero recovery so the series leaves the active set and exits reopen, and keeps the COUPON legs in the Desk. A later harvest retries the redemption and books whatever it recovers; governance can also move the legs out with writeOffSeries(seriesId, legsTo).

Risk to Desk Depositors

The Desk is a note buyer. It earns coupons while the barrier holds and receives stock at s0 if the barrier breaks at maturity, at which point NAV reflects the feed value of that stock. Depositors bear market risk on the underlyings the Desk has filled, concentration risk bounded by the caps, and liquidity risk when most assets are deployed. Desk shares are not NOTE and carry no governance rights.

The Desk never buys SHIELD and never fills a series above its notionalCap.

Governance Surface

Gauge-steered Caps

fact The governed Caps.perUnderlyingCapBps is a ceiling. Each week GaugeController.syncCaps writes a per-underlying value derived from the series-gauge vote, and effectivePerUnderlyingCapBps(underlying) returns the lower of the governed cap and the gauge value (min). fillCoupon uses the effective value; an underlying with no gauge, or one that has not been synced yet, keeps the governed cap. The mechanics and a worked example are under Gauges.

The module is a UUPS proxy whose implementation can only be replaced by the 7-day upgrade governance; see Upgradeability and recovery.

Exit Guard and Marked NAV

fact Share price is computed from a marked NAV: deployed principal is valued at the Treasury’s live mark for each series (par for series not yet live) plus coupons accrued but not yet harvested, so depositing just before a harvest or withdrawing just before a mark-down no longer transfers value between holders. Direct withdraw/redeem and requestWithdraw require the shares to have been held for minHold (default 1 day, governance-settable up to 7 days) and are refused while a settled series is waiting to be harvested; queued requests are checked against the harvest gate again when they fill (the hold applies at request time only). Open requests reserve their shares, valued at the current NAV, against the idle USDG available to direct exits. Bonds read the Desk’s utilisation as of the previous block (laggedUtilisationBps).