feat(zswap-da): show reference rate, offset and sponsorship threshold from /v1/quote and /v1/prices

[acedward]

What

The Swap and Market screens now show the reference conversion rate, the maker's offset from it, the sponsorship threshold, and where the reference came from and how old it is. A batcher/node refusal is shown as its reason instead of a generic error.

Template-only (templates/zswap-da), additive, no dependency changes — it cherry-picks onto midnight-1 unchanged.

Part C of project 00005 (token price service). Parts A and B add the kernel side in zswap-offerfiles-kernel: GET /v1/prices, source/threshold fields on GET /v1/quote, and a 422 NOT_SPONSORED on POST /v1/offers.

Why

A maker could not tell why an offer would or would not be sponsored to Celestia:

• the market rate was hidden whenever "Auto Market Price" was on
• "−x% vs market" carried no threshold, so 1% and 3% looked equally fine
• nothing said whether the "market" was a real price or the node's deterministic demo price
• a refusal from the batcher surfaced as an internal error

Screens

Swap (both price modes now):

Your rate · 1 WBTC = 31.526 WETH                        −2.5% vs reference
Reference · 1 WBTC = 32.3351 WETH   sponsored at ≥ 2.5% below reference
Reference: CoinGecko · 3 h ago
[ Celestia fee sponsored. Good trades get filled fast. ]

At 1% below reference:

! This price is only 1.0% below reference; sponsorship needs ≥ 2.5%.  Apply best price

For a pair the node cannot price (test tokens), the warning is suppressed — the batcher sponsors unpriced tokens — and the line reads:

Demo rate — no market price for TESTTOKENA and TESTTOKENB; test tokens are sponsored regardless

Market header gains two stats: Reference 1 WBTC = 32.335 WETH (with the source and age underneath) and Mid vs reference −3.5%; both read no reference when either token is demo-priced.

How

• services/api.ts — getPrices(tokens) (per-pair: builds GET /v1/prices?tokens=a,b, refuses an empty list or more than 50 colours before any request — the node requires tokens and has no unfiltered form) plus the /v1/prices types; Quote gains sponsor_discount, from_source, to_source, prices_updated_at.
  These four are optional on purpose: a node that predates the price service omits them, so this build stays correct against the current preprod API and shows "no reference known" rather than reading undefined.
• state/format.ts — isMarketSource, pct1, fmtOffsetPct, fmtAge.
• state/reference.ts (new) — describeQuote() and referenceRate(): every string the two screens render is derived here, pure and unit-tested, so the screens hold no formatting logic that can drift.
• state/usePrices.ts (new) — /v1/prices?tokens= behind a 60 s module cache keyed by the sorted colour set, one shared in-flight request per key; Market asks only for the selected pair and fetches nothing with no pair open; a 400/404 resolves to null ("no reference"). Per-pair lookups landed in 43f0ea36 + 689c326c (Q-11: the price table is unbounded in principle, so no consumer pulls it whole).
• screens/Swap.tsx, screens/Market.tsx — rendering only.

The 422 NOT_SPONSORED path needed no code change: parse() already builds an ApiError whose message is the node's reason with the numbers on .data, and createOffer rethrows it untouched. services/api.test.ts now pins that so it cannot regress, and the Swap error area gains the same "Apply best price" action for it.

Testing

• bun test → 176 pass / 0 fail / 375 expect() across 12 files (35 new: format.test.ts, reference.test.ts, api.test.ts)
• bunx tsc -b clean, bun run build green (including the compact contract prebuild)
• Manual walkthrough in the browser against a throwaway stub serving the frozen API fixtures (the kernel routes are not merged yet): auto mode, manual price 1% below, a test-token pair, and both Market cases render exactly the strings above. Posting an offer and seeing the 422 in the UI needs the Lace wallet and is verified on preprod once the kernel side is deployed.

Not breaking

Additive. Against a node without the new fields the screens fall back to the pre-existing top-level source and show the rate and offset with no source line and no threshold — never a fabricated number.

[acedward]

Scale amendment applied — /v1/prices is now a per-pair lookup (43f0ea36)

Follow-up to a review point on this PR: fetching the whole price table is fine for six tokens and wrong for thousands of mapped or short-lived ones. The kernel endpoint (PR effectstream/zswap-offerfiles-kernel#54) now requires ?tokens=<color>[,<color>…] — 1–50 lower-case 64-hex colours — and answers 400 VALIDATION without it. There is no unfiltered form any more, and this branch was the last unfiltered caller.

What changed

File	Change
src/services/api.ts	getPrices(tokens: string[]) builds ?tokens=a,b from a trimmed, lower-cased, de-duplicated list; an empty list (or more than 50) is refused client-side with a clear Error, so the unfiltered form can never be sent by accident. New exported normalizeColors() / MAX_PRICE_TOKENS. Doc comment rewritten: per-pair lookup, unknown colours are silently absent, and a 400 now joins 404 as "no reference available".
src/state/usePrices.ts	Cache and shared in-flight request are keyed by the sorted colour set (60 s TTL per key): {a,b} and {b,a} are one entry, a different pair is a different entry that does not evict the first, and an empty key fetches nothing. New pure pricesKey() / loadPrices() carry the whole contract, so it is testable without a renderer.
src/screens/Market.tsx	Passes [baseColor, quoteColor]; with no pair selected nothing is fetched. No visual change.
src/state/reference.ts	tokenPriceOf matches a colour case-insensitively — the query that produced the rows was lower-cased.

Gates on 43f0ea36 (from templates/zswap-da): bun test 189 pass / 0 fail / 411 expect() across 13 files (was 176/375/12 — +13: query building, lower-case + dedupe, refused empty list, refused >50, 400 reason, the eight cache-key cases, case-insensitive lookup); bunx tsc -b exit 0; bun run build ✓ 9.85 s incl. the Compact prebuild.

Still not breaking, still no dependency change. The same commit is cherry-picked onto #916 for midnight-1.

[acedward]

Follow-up on the amendment above: 689c326c fixes a display-continuity regression the keyed cache introduced. The response was held on its own, so the hook cleared it on every effect run and a Refresh past the 60 s TTL blinked the Market header through "no reference" before the new body arrived — something the unkeyed version never did. The response is now held together with the key it answers, and what to show is derived: the held body while its key still matches, that key's cached body otherwise, and null — honestly "no reference" — when a newly selected pair has nothing cached yet.

Gates on 689c326c unchanged: bun test 189 pass / 0 fail / 411 expect() across 13 files, bunx tsc -b exit 0, bun run build ✓ 9.31 s. Picked onto #916 as 7bb826df (same patch id cd00d137…).