The oracle and pricing

Three prices

Chainlink reports the stock's USD price from off-chain venues. It sets the band and the swap floor on deposits and exits, and it is one of the two prices that value a share. Deploy swaps floor at the TWAP instead. Chainlink is the slowest of the three, with a 24 hour heartbeat, so it can lag a fast move.

The pool TWAP is the average tick of the Stock Token / USDG pool over at least 10 minutes. It says what the pool itself believes the price is, and it cannot be moved by a single block. The spot price is the pool's current tick. It is the most current and the least trustworthy, which is why it is checked but never used alone.

The gate's six checks

A single read produces one status. The checks run in order and the first failure is returned, while everything readable is still returned alongside it. A caller that only needs to know whether it may proceed reads the status.

What each path trusts

The gate is not applied uniformly. The paths that hand the vault a price need it; the path that hands back the actual tokens does not.

Why NAV takes the lower price

The vault holds Stock Token and USDG. The Stock Token side is already in the unit of account. The USDG side has to be converted, and the choice of price changes what a share is worth.

If the feed says $200 and the pool says $190, valuing USDG at $200 credits each USDG with fewer Stock Tokens than the pool would give for it. A depositor would buy shares below their redeemable value, and the difference would accrue to existing holders. Taking the minimum of the two closes that gap.

function _navPrice(Snapshot memory s) private view returns (uint256) {
    return Math.min(s.price, _sqrtToUsd(s.sqrtTwap));
}

The TWAP, not spot, is the pool side of that comparison, so a same-block push cannot move total assets. New shares are priced one step more conservatively, on the lowest of Chainlink, the TWAP and spot. The same two-way price converts fee value before the treasury cut is taken.

The 10 minute TWAP

The window is stored as twapWindow, at least 600 seconds and at most one day. The vault calls pool.observe for the window and divides the tick accumulator difference by the elapsed seconds, rounding towards negative infinity so the average is never above the true one.

A long enough window is what makes the average expensive to manipulate. It also means a pool that has just launched cannot serve it: the observe call reverts and the status is TwapUnavailable until the pool has the history.

Staleness and deviation

The feed's heartbeat is 24 hours. The deployed staleness limit is 25 hours, which leaves an hour of grace for a late update and still catches a feed that has stopped. The keeper's send-time guard is 87,000 seconds, tighter than the contract's 90,000, so it stops a transaction before the vault would reject it. Its universe filter is looser, allowing a feed up to 346,200 seconds old so a pool stays eligible through a long weekend.

Deviation is bounded at 100 bps on both the TWAP and spot comparisons. That is tight on purpose: the vault only needs to know that the pool is trading near the feed at the moment it prices a deposit or a rebalance. A wider gap is not a better price, it is a broken market.

Reading health

health() is the one call that reports the gate without reverting. It returns the status, the feed price, the feed timestamp, and the three square-root prices the decision was made from.

const [status, price, updatedAt, sqrtOracle, sqrtTwap, sqrtSpot] =
  await client.readContract({
    address: vault,
    abi: stockVaultAbi,
    functionName: "health",
  });

if (status !== 0) throw new Error(`oracle status ${status}`);

A front end can show the status, the age of the answer and the three prices before a user signs anything. The transaction still runs the gate for itself; the read is a preview, not a permission.

The exit buffer

previewRedeem returns fair value less 30 bps, and previewWithdraw grosses the requested amount up by the same factor. The buffer covers the swap that turns the USDG leg into the Stock Token on the way out, so the preview is a floor rather than an optimistic estimate. The actual payout is what the swap produces.