Pinned-basis class: zero-basis-by-construction for arb-pinned wrappers

Written 2026-07-20, approved by Fred. Follow-on to the Dune price-mirror refactor (docs/plans/dune-price-mirror-plan.md, shipped v0.14.0) and a partial resolution of issue #439. Trigger: wallet 0xaf353cb6…3a0b (Morpho sUSDS/USDT, ~22x gross-to-equity) showed entered basis +6.8% of equity, of which ~half was sUSDS feed noise (±15bp 6h swings on a token whose price is pinned by arbitrage) and ~half genuine USDT discount (verified on-chain: Curve 3pool round-trip mid 0.99883 at entry block 25430877).

1. The principle

Some wrappers CANNOT sustain a secondary-market basis: anyone can redeem them instantly, permissionlessly, at the share rate, into an underlying that is itself hard-pegged to the book numeraire (e.g. sUSDS: instant 4626 redemption into USDS, PSM-pinned 1:1 to USDC). Any DEX premium/discount is arbitrage-closed within blocks, so a measured deviation is feed noise, not information. For this class, market mark ≡ redemption mark (basis ≡ 0) by construction — the same doctrinal slot as PT legs' entered-basis-zero (M12).

Blindness trade (must be documented everywhere the class is applied): pinning extends the USD-book par assumption through the wrapper. A depeg of the UNDERLYING (USDS losing its PSM peg) would not appear in the wrapper's basis. This mirrors the known Fluid sUSDe-oracle blindness note; the residual risk is charted (if at all) on the underlying, never the pinned wrapper.

2. Classification criteria (the investigation deliverable)

An asset is pinned ONLY if ALL hold, verified at primary sources (contract code via Herd, on-chain reads, official docs — no vibes):

1. Redemption is instant (same-block), permissionless, at the accrual/share rate, with zero or negligible (<2bp) fee, no cooldown/queue/gate.
2. Redemption capacity is effectively unbounded in normal operation (not liquidity-gated in a way that regularly binds — e.g. a lending-vault share redeemable only from un-borrowed liquidity is NOT automatically pinned; it needs evidence that utilization does not trap exits).
3. The redemption proceeds are the book numeraire or hard-pegged to it by an on-chain 1:1 mechanism (PSM) with real capacity.

Everything else stays market-measured. Prior expectations to be CONFIRMED or REFUTED per-asset with evidence (contract addresses + the exact redemption function/params + fee/cooldown values + capacity source):

• Likely pinned: sUSDS; sDAI (when tracked).
• Likely market (real basis capacity): sUSDe (unstake cooldown), USDe/USDtb (whitelisted mint/redeem only), GHO (NO redemption mechanism at all — its discount history is real), syrupUSDC/syrupUSDT (withdrawal queues), reUSD (investigate), all LST/LRTs (withdrawal queues, days), WBTC/cbBTC (custodial whitelisted), USDC/USDT themselves (par tokens — the deviation IS the signal).
• The 21 MIRROR_EXTRA vault shares (gtUSDC, steakUSDC, eUSDC-2, yoUSD, …): mostly 4626 lending-vault shares — instant-at-rate ONLY up to idle liquidity; classify per criterion 2 with utilization evidence. A pinned classification here has a portfolio-coverage BONUS: these are Dune-unpriced (honest nulls today), and pinned marks would give them redemption-anchored values.

Output: a classification table (asset | verdict | evidence per criterion | confidence) reviewed by the orchestrator BEFORE the registry lands. Border cases default to market-measured (the honest side).

3. Implementation

Registry: extend the basis/token registry entries with basisClass: "pinned" | "market" (default "market"; explicit for every entry; the coverage tests assert every tracked wrapper carries a class). Single source of truth consumed by every surface below.

Surfaces (basis ≡ 0 for pinned, in ALL of):

1. Flow valuation (valueFlows/mirror-prices): pinned asset → market unit price := redemption rate (block-precise, already fetched). No mirror-bar read for the book mark; bars keep syncing for provenance/USD display.
2. Snapshot valuation (loadMarketContext/valueLeg path): same rule, history and now modes.
3. Live tier: pinned assets skip the Kyber mid; live market := current redemption. Entered/current/dislocation for pinned legs are 0 by construction.
4. token_basis refresher: pinned tokens write market_price_usd := redemption_value_usd, basis = 0 go-forward. Historical token_basis rows stay (unread once the modal changes); NO destructive rewrite.
5. Market-depth modal: pinned legs are not charted; they render the pinned note ("price pinned by instant redemption arbitrage; residual risk is the underlying's peg") — same pattern as the never-charted numeraire side. No em-dashes, no help cursor, match existing modal copy tone.
6. Repair: extend the D remark scripts' classifier: pinned rows re-mark value_market := value_redemption (rows missing redemption stay untouched, logged). Same dry-run/execute/idempotency/lock discipline. Acceptance: the defisaver wallet (0xaf353cb6…) re-marked → entered ≈ +$520 (USDT leg only, on-chain-verified real), current ≈ −$250, sUSDS contribution exactly 0.
7. Docs (same PR): metrics.md (the pinned class next to M12's PT rule + the blindness note), data-pipeline.md registry wording, assistant-metrics sync check. Issue #439 gets a comment: pinned class resolves the instant-redemption cohort; the band/stuck-price guard question stays OPEN for market-measured thin tokens (syrupUSDT).

Tests: classifier unit tests per surface (pinned flow mark = redemption; mismatched-bar machinery never consulted for pinned; live tier skip; refresher zero-write; repair re-derivation), adversarial fixtures, magnitude-unique. The phantom-shape regression and all existing suites stay green.

4. Sequencing

1. Investigation agent (classification table w/ evidence) — parallel with 2.
2. Implementation agent: mechanism + tests with sUSDS as the only seeded pinned entry (the one already verified: instant 4626 + PSM, confirmed this morning).
3. Orchestrator reviews the classification table → second commit fills the registry for every wrapper.
4. Adversarial review; staging verify (defisaver wallet acceptance above); ONE PR to staging with evidence; prod repair after merge per the standard gated flow.

Out of scope: the ingest guard for market-measured thin tokens (#439 remains open); any underlying-peg monitoring for pinned wrappers (documented blindness).