@waterx/sdk 4.3.3 → 5.0.0

package/dist/src/oracle/rules/waterx-rule.js

@@ -41,9 +41,12 @@ import { collectBatchLatest, collectSingleWithProof, newBatchItem, newBatchPaylo
 import { ownEntry } from "../../utils/record.js";
 import { assertRuleUpdateData, } from "../price-update-rule.js";
 import { FetchPolicyError, fetchWithPolicy, joinEndpointPath, } from "../update-fetch.js";
-/** Intent the quote-center signs a whole BATCH payload under — exported so
- *  read-plane consumers can mirror the rule's own envelope intent check (a
- *  mispointed endpoint must be rejected by reads exactly as tx-builds reject it). */
+/** Intent the quote-center signs a whole BATCH payload under. Exported to NAME
+ *  the signing scheme only — consumers no longer mirror the intent gate
+ *  themselves: every quote-center pull (tx-build fetch, read executor, BE
+ *  prefetch) goes through {@link fetchWaterxSignedUpdate} /
+ *  {@link fetchWaterxSignedLeaves}, which enforce it, so a mispointed endpoint
+ *  is rejected identically on every path. */
 export const BATCH_PRICE_INTENT = 1;
 /**
  * Intent the quote-center signs a snapshot's Merkle ROOT under
@@ -57,12 +60,11 @@ export const BATCH_PRICE_INTENT = 1;
 export const MERKLE_ROOT_INTENT = 2;
 /**
  * WaterX quote-center external infra — owned by THIS source, by network.
- * Mirrors `PYTH_CORE_INFRA` (oracle/pyth.ts) and `LAZER_INFRA`
- * (rules/pyth-lazer-rule.ts): per-network constants for infrastructure the
- * source's operator runs, co-located with the only rule that reads them — no
- * other oracle source ever touches a quote-center endpoint. Public read (no
- * auth), so there is no api_key. `endpoint` has no trailing slash — the rule
- * appends the path.
+ * Mirrors `LAZER_INFRA` (rules/pyth-lazer-rule.ts): per-network constants for
+ * infrastructure the source's operator runs, co-located with the only rule
+ * that reads them — no other oracle source ever touches a quote-center
+ * endpoint. Public read (no auth), so there is no api_key. `endpoint` has no
+ * trailing slash — the rule appends the path.
  *
  * These are the DEFAULTS behind the caller's `client.waterx` access slice
  * (`waterxEndpoint` / `waterxFetch` create options) — the browser-CORS proxy
@@ -75,34 +77,83 @@ export const WATERX_INFRA = {
 /**
  * The waterx source's quote-center base for `network` — the ONE accessor
  * consumers (BE/FE read planes) use when, and only when, their own
- * `ORACLE_SOURCE` resolves to `'waterx_rule'`. Mirrors
- * `pythCoreHermesEndpoint`. Under any other source the read endpoint is that
- * source's own configuration — never this one.
+ * the config wires `waterx_rule`. Under any other source the
+ * read endpoint is that source's own configuration — never this one.
  */
 export function waterxQuoteCenterEndpoint(network) {
     return WATERX_INFRA[network].endpoint;
 }
+/**
+ * Off-chain mirror of the on-chain `waterx_rule` `FeedConfig.max_age` DEFAULT
+ * (90s): a price older than this ABSTAINS on-chain, so a read plane serving it
+ * as live would show a price no trade could execute against. The single
+ * source of truth for consumers' post-cache freshness filters — import this,
+ * never re-declare the number. (A deployment that overrides `max_age`
+ * per-feed on-chain diverges from this mirror; none does today.)
+ */
+export const WATERX_MAX_PRICE_AGE_MS = 90_000;
+/**
+ * `true` iff a quote-center read entry is still within
+ * {@link WATERX_MAX_PRICE_AGE_MS} of `nowMs` — the freshness predicate
+ * consumers apply to `readQuoteCenterPrices` output (post-cache), matching
+ * the on-chain abstain boundary instead of each inventing a policy.
+ */
+export function isFreshWaterxEntry(entry, nowMs) {
+    const age = nowMs - entry.publishTimeMs;
+    // A FUTURE timestamp is not fresh — it is a broken clock or a malformed
+    // payload, and a bare `age <= MAX` treats it as the freshest possible price.
+    // One tolerance of clock skew is allowed in the other direction, since the
+    // quote-center and the caller keep independent clocks; beyond that, reject.
+    if (age < -WATERX_CLOCK_SKEW_TOLERANCE_MS)
+        return false;
+    return age <= WATERX_MAX_PRICE_AGE_MS;
+}
+/**
+ * How far ahead of the reader's clock a quote-center timestamp may sit before
+ * it is treated as broken rather than merely skewed. Two independent clocks
+ * drift; a price minutes in the future does not.
+ */
+export const WATERX_CLOCK_SKEW_TOLERANCE_MS = 5_000;
+/**
+ * Structural gate for the ENVELOPE payload shape — symmetric with
+ * {@link isWaterxLeafPayloadShape}, which validates every leaf.
+ *
+ * This runs on payloads that never went through {@link parseSignedEnvelope}:
+ * a consumer's `UpdateDataProvider` hands back whatever its cache holds, and a
+ * value revived from JSON can have lost its bigints or been written half-built.
+ * A gate that checked only `signature: string` + `Array.isArray(items)` let
+ * those through, and the failure landed mid-PTB-build inside `newItemArg` —
+ * after legs were already appended to the caller's `tx`. Every item is checked
+ * with the SAME guard the wire door uses.
+ */
 function isWaterxEnvelopePayloadShape(payload) {
     const env = payload?.envelope;
     return (typeof env === "object" &&
         env !== null &&
-        typeof env.signature === "string" &&
+        // ed25519 over the batch — a wrong-length signature is an on-chain abort.
+        isHexOfBytes(env.signature, 64) &&
         typeof env.timestamp_ms === "bigint" &&
-        Array.isArray(env.payload?.items));
+        env.timestamp_ms >= 0n &&
+        Array.isArray(env.payload?.items) &&
+        env.payload.items.every(isBatchItemShape));
 }
 function isWaterxLeafPayloadShape(payload) {
     const leaves = payload?.leaves;
     return Array.isArray(leaves) && leaves.every(isSignedLeafShape);
 }
 /** Every u64 field of a leaf — each one is signed, so each must be present and exact. */
-const LEAF_U64_FIELDS = [
+/**
+ * The signed u64 fields every quote-center ITEM carries — the BCS bytes the
+ * enclave signed over. A leaf adds `signed_timestamp_ms` on top (see
+ * {@link isSignedLeafShape}); the batch envelope's items do not carry it.
+ */
+const BATCH_ITEM_U64_FIELDS = [
     "price_timestamp_ms",
     "price_n",
     "price_scale",
     "confidence_n",
     "confidence_scale",
     "max_source_deviation_bps",
-    "signed_timestamp_ms",
 ];
 /**
  * FULL structural check on a leaf, not just the fields the feed leg happens to
@@ -131,8 +182,15 @@ function isHexOfBytes(hex, bytes) {
     const body = hex.startsWith("0x") ? hex.slice(2) : hex;
     return body.length === bytes * 2 && HEX_ONLY.test(body);
 }
-function isSignedLeafShape(leaf) {
-    const l = leaf;
+/**
+ * The ITEM half — every field the feed leg rebuilds into the BCS the enclave
+ * signed. Shared by BOTH wire doors: a leaf is an item plus its signature and
+ * proof material ({@link isSignedLeafShape}), and the batch envelope's items go
+ * through the same gate ({@link assertBatchItemShape}). One definition, so a
+ * new signed field cannot be validated at one door and waved through the other.
+ */
+function isBatchItemShape(item) {
+    const l = item;
     if (typeof l !== "object" || l === null)
         return false;
     if (typeof l.symbol !== "string" || l.symbol === "")
@@ -163,11 +221,20 @@ function isSignedLeafShape(leaf) {
         return false;
     if (l.sources.some((s) => typeof s !== "bigint" || s < 0n))
         return false;
-    for (const field of LEAF_U64_FIELDS) {
+    for (const field of BATCH_ITEM_U64_FIELDS) {
         const v = l[field];
         if (typeof v !== "bigint" || v < 0n)
             return false;
     }
+    return true;
+}
+function isSignedLeafShape(leaf) {
+    if (!isBatchItemShape(leaf))
+        return false;
+    const l = leaf;
+    const signedAt = l.signed_timestamp_ms;
+    if (typeof signedAt !== "bigint" || signedAt < 0n)
+        return false;
     // ed25519 is always 64 bytes and the root is always a 32-byte keccak256; a
     // wrong-length signature is an on-chain abort, so it is rejected here.
     if (!isHexOfBytes(l.signature, 64))
@@ -243,15 +310,42 @@ export function parseSignedEnvelope(text) {
     if (typeof raw.signature !== "string" || !Array.isArray(raw.payload?.items)) {
         throw new Error("WaterX quote-center returned a malformed signed envelope");
     }
+    // `timestamp_ms` is signed OVER, so defaulting a missing one to `0n` does not
+    // produce a harmless zero — it produces a batch whose signature cannot verify,
+    // surfacing as an opaque on-chain `EInvalidSignature` indistinguishable from a
+    // forgery. Reject it at the door instead, where the message can say what is
+    // actually wrong.
+    if (typeof raw.timestamp_ms !== "bigint") {
+        throw new Error("WaterX quote-center envelope is missing an integer timestamp_ms");
+    }
+    const items = raw.payload.items.map((item) => {
+        // The leaf door is structurally validated; this one was not, so a 200 with
+        // half-built items passed the wire gate and blew up mid-PTB-build inside
+        // `newItemArg` — after commands had already been appended to the caller's
+        // transaction. Both doors now reject before anything is built.
+        assertBatchItemShape(item);
+        return { ...item, num_sources: Number(item.num_sources) };
+    });
     return {
         intent: Number(raw.intent),
-        timestamp_ms: (raw.timestamp_ms ?? 0n),
+        timestamp_ms: raw.timestamp_ms,
         signature: raw.signature,
-        payload: {
-            items: raw.payload.items.map((i) => ({ ...i, num_sources: Number(i.num_sources) })),
-        },
+        payload: { items },
     };
 }
+/**
+ * The envelope door's throwing form of {@link isBatchItemShape} — same gate the
+ * leaf door applies, so neither shape can carry a half-built item into a PTB.
+ */
+function assertBatchItemShape(item) {
+    if (!isBatchItemShape(item)) {
+        const symbol = item?.symbol;
+        const label = typeof symbol === "string" ? symbol : "<unknown symbol>";
+        throw new Error(`WaterX quote-center envelope item ${label} is malformed — expected symbol, ticker, ` +
+            `method, a u8 num_sources, a non-empty u64 sources vector, and integer ` +
+            `${BATCH_ITEM_U64_FIELDS.join(", ")}.`);
+    }
+}
 /**
  * A Merkle proof element must be a 32-byte keccak256 hash, and nothing else.
  *
@@ -346,13 +440,27 @@ async function fetchQuoteCenter(endpoint, path, symbols, what, fetchOpts) {
     }
 }
 /**
- * Pull one enclave-signed batch envelope covering `symbols`. `fellBackFrom`, when
- * set, names the leaf-route failure that sent us here, so a deployment whose
- * quote-center serves NEITHER route reports both statuses instead of only the
- * second one.
+ * Pull one enclave-signed batch envelope covering `symbols` — the fallback
+ * update shape AND the read executor's transport
+ * (`readQuoteCenterPrices` in `../read-prices.ts`). Public seam (WL-2345):
+ * consumers that need the raw envelope (BE prefetch caches, read planes)
+ * call this instead of re-rolling the fetch + intent/shape gate.
+ * `fellBackFrom`, when set, names the leaf-route failure that sent us here,
+ * so a deployment whose quote-center serves NEITHER route reports both
+ * statuses instead of only the second one.
  */
-async function fetchWaterxSignedUpdate(endpoint, symbols, fetchOpts, fellBackFrom) {
+export async function fetchWaterxSignedUpdate(endpoint, symbols, fetchOpts, fellBackFrom) {
     const context = fellBackFrom ? ` (fell back from ${fellBackFrom})` : "";
+    // Unlike leaves, this route cannot be chunked: the response is ONE signature
+    // over the whole batch, so two envelopes are two different snapshots and the
+    // payload shape holds one. Say so explicitly rather than let the enclave
+    // answer a non-retryable 400 that reads as a generic fetch failure.
+    if (symbols.length > WATERX_MAX_BATCH_SYMBOLS) {
+        throw new Error(`WaterX quote-center batch fetch needs ${String(symbols.length)} symbols but the enclave ` +
+            `signs at most ${String(WATERX_MAX_BATCH_SYMBOLS)} per request, and a batch envelope ` +
+            `cannot be split (one signature covers the whole batch). Request fewer tickers, or use ` +
+            `a quote-center that serves the per-symbol leaf route, which IS chunked.${context}`);
+    }
     const res = await fetchQuoteCenter(endpoint, "v1/quotes/update", symbols, "fetch", fetchOpts);
     if (!res.ok) {
         throw new Error(`WaterX quote-center fetch failed: ${res.status} ${await res.text()}${context}`);
@@ -387,8 +495,48 @@ async function fetchWaterxSignedUpdate(endpoint, symbols, fetchOpts, fellBackFro
  * from its feed registry). That is config drift between this SDK's `feeds` and
  * the quote-center's registry, and the fallback surfaces it honestly: the
  * envelope route 404s on the same symbol, and its error names both attempts.
+ *
+ * Public seam (WL-2345): consumers holding per-symbol leaves (BE prefetch
+ * caches) pull through this instead of re-rolling the fetch + parse gate.
  */
-async function fetchWaterxSignedLeaves(endpoint, symbols, fetchOpts) {
+export async function fetchWaterxSignedLeaves(endpoint, symbols, fetchOpts) {
+    // Chunked against the enclave's per-request cap. Leaves are independently
+    // verifiable per symbol — each carries its own proof against a signed root —
+    // so splitting the request changes nothing about what the PTB can do with
+    // them. Unchunked, a universe prefetch or an all-markets refresh takes a
+    // non-retryable 400 the moment a deployment crosses the cap, surfacing as a
+    // bare "leaf fetch failed: 400" with nothing pointing at batch size.
+    const chunks = chunkSymbols(symbols);
+    // Probe with the first chunk: a quote-center with no leaf route answers 404
+    // for every chunk, so there is no point spending the rest to learn it.
+    const first = await fetchLeafChunk(endpoint, chunks[0] ?? [], fetchOpts);
+    if ("unavailable" in first || chunks.length <= 1)
+        return first;
+    const rest = await Promise.all(chunks.slice(1).map((chunk) => fetchLeafChunk(endpoint, chunk, fetchOpts)));
+    const leaves = [...first.leaves];
+    for (const pull of rest) {
+        if ("unavailable" in pull)
+            return pull;
+        leaves.push(...pull.leaves);
+    }
+    return { leaves };
+}
+/**
+ * The quote-center enclave signs at most this many symbols per request
+ * (`MAX_BATCH_SIZE` in `quote-service`). Over the cap it answers a
+ * non-retryable 400.
+ */
+export const WATERX_MAX_BATCH_SYMBOLS = 32;
+function chunkSymbols(symbols) {
+    if (symbols.length <= WATERX_MAX_BATCH_SYMBOLS)
+        return [symbols];
+    const out = [];
+    for (let i = 0; i < symbols.length; i += WATERX_MAX_BATCH_SYMBOLS) {
+        out.push(symbols.slice(i, i + WATERX_MAX_BATCH_SYMBOLS));
+    }
+    return out;
+}
+async function fetchLeafChunk(endpoint, symbols, fetchOpts) {
     const res = await fetchQuoteCenter(endpoint, "v1/quotes/leaves", symbols, "leaf fetch", fetchOpts);
     if (res.status === 404) {
         return { unavailable: `GET /v1/quotes/leaves → 404 ${(await res.text()).trim()}`.trim() };
@@ -547,44 +695,103 @@ export function feedWaterxRule(tx, host, collector, envelope) {
         },
     })(tx);
 }
+/**
+ * THE quote-center route ladder, owned by the rule that owns the protocol:
+ * pull per-symbol Merkle leaves (the default), and fall back to one batch
+ * envelope only when this quote-center has no leaf route (see
+ * {@link fetchWaterxSignedLeaves} for exactly which statuses mean that, and
+ * why nothing else falls back).
+ *
+ * Both the write path ({@link pullWaterxData}, which layers coverage policy on
+ * top) and the READ executor (`readQuoteCenterPrices` in `../read-prices.ts`,
+ * which only decodes prices) go through here, so which route wins, which
+ * status falls back, and how the fallback context is threaded are stated once.
+ * `items` is the flat symbol-bearing view both callers actually want —
+ * `WaterxSignedLeaf extends WaterxBatchItem`, so leaves widen to it for free —
+ * while `payload` keeps the shape-specific form the on-chain feed leg needs.
+ */
+export async function pullWaterxQuotes(endpoint, symbols, fetchOpts) {
+    const pulled = await fetchWaterxSignedLeaves(endpoint, symbols, fetchOpts);
+    if ("leaves" in pulled) {
+        return { route: "leaves", payload: { leaves: pulled.leaves }, items: pulled.leaves };
+    }
+    const envelope = await fetchWaterxSignedUpdate(endpoint, symbols, fetchOpts, pulled.unavailable);
+    return { route: "envelope", payload: { envelope }, items: envelope.payload.items };
+}
+/**
+ * THE quote-center pull — the one pipeline both coverage policies share:
+ * package guard → own-key feeds partition → leaf route (default) → batch
+ * envelope only when this quote-center has no leaf route (see
+ * {@link fetchWaterxSignedLeaves} for exactly which statuses mean that, and
+ * why nothing else falls back).
+ *
+ * `coverage` decides only what a GAP means, never how the pull runs:
+ *
+ * - `"strict"` — every requested ticker must be config-listed AND served, or
+ *   this THROWS (the per-ticker unlisted message, before any network call;
+ *   then {@link assertCoverage} naming the route). `missing` is always `[]`.
+ * - `"partial"` — an unlisted or unserved ticker lands in `missing` and the
+ *   payload covers the rest, narrowed through the rule's own
+ *   {@link WaterxRule.narrowUpdateData} so leaf-vs-envelope divisibility has
+ *   exactly one definition.
+ */
+async function pullWaterxData(host, tickers, coverage) {
+    // Package-level check first: a config without the deployment must say so,
+    // not fail per ticker as if only that feed were missing.
+    const { feeds } = requireWaterxPackage(host);
+    // One partition pass, own-keys-only: a prototype-key ticker ("toString")
+    // must read as unlisted, not pass as an inherited Function and reach the
+    // network.
+    const missing = [];
+    const listed = [];
+    for (const ticker of tickers) {
+        (ownEntry(feeds, ticker) === undefined ? missing : listed).push(ticker);
+    }
+    // Unlisted tickers never reach the network on EITHER policy — the
+    // quote-center 404s a whole batch on one unknown symbol. Strict surfaces
+    // the per-ticker message; partial just records the gap and pulls the rest.
+    if (coverage === "strict" && missing.length > 0) {
+        throw new Error(`No waterx_rule feed listed for ticker: ${missing[0]}`);
+    }
+    if (listed.length === 0)
+        return { data: null, missing };
+    const { endpoint, fetch: fetchOpts } = resolveWaterxInfra(host);
+    const { route, payload, items } = await pullWaterxQuotes(endpoint, listed, fetchOpts);
+    const served = new Set(items.map((item) => item.symbol));
+    if (coverage === "strict") {
+        assertCoverage(route, listed, served);
+        return { data: { kind: "waterx_rule", payload }, missing };
+    }
+    const covered = [];
+    for (const ticker of listed)
+        (served.has(ticker) ? covered : missing).push(ticker);
+    // Divisibility is the rule's own knowledge, so the subset decision is
+    // delegated rather than re-encoded here: leaves subset per symbol, an
+    // envelope is indivisible and passes whole (or `null` when it covers none).
+    return {
+        data: covered.length > 0
+            ? WaterxRule.narrowUpdateData(host, { kind: "waterx_rule", payload }, covered)
+            : null,
+        missing,
+    };
+}
 export const WaterxRule = {
     kind: "waterx_rule",
-    // Verification is an in-Move ed25519 check with no Coin argument — no
-    // update fee — see `PriceUpdateRule.requiresFeeSource`.
-    requiresFeeSource: false,
+    // No credential: the quote-center read surface is public (no `credential`
+    // declared — see `PriceUpdateRule.credential`).
     /** Tickers with a `waterx_rule.feeds` entry (keyed by oracle ticker). */
     supportedTickers(host) {
         return Object.keys(host.config.packages.waterx_rule?.feeds ?? {});
     },
     /**
      * Pulls per-symbol Merkle leaves for `tickers`, falling back to one batch
-     * envelope only when this quote-center has no leaf route (see
-     * {@link fetchWaterxSignedLeaves} for exactly which statuses mean that, and
-     * why nothing else falls back). Either way, returns only what covers ALL of
-     * `tickers` — see {@link assertCoverage}.
+     * envelope only when this quote-center has no leaf route. Returns only what
+     * covers ALL of `tickers` — the strict arm of {@link pullWaterxData}.
      */
     async fetchUpdateData(host, tickers) {
         if (tickers.length === 0)
             return null;
-        // Package-level check first: a config without the deployment must say so,
-        // not fail per ticker as if only that feed were missing.
-        const { feeds } = requireWaterxPackage(host);
-        for (const ticker of tickers) {
-            // ownEntry: a prototype-key ticker ("toString") must throw here as
-            // unlisted, not pass as an inherited Function and reach the network.
-            if (ownEntry(feeds, ticker) === undefined) {
-                throw new Error(`No waterx_rule feed listed for ticker: ${ticker}`);
-            }
-        }
-        const { endpoint, fetch: fetchOpts } = resolveWaterxInfra(host);
-        const pulled = await fetchWaterxSignedLeaves(endpoint, tickers, fetchOpts);
-        if ("leaves" in pulled) {
-            assertCoverage("leaves", tickers, pulled.leaves.map((l) => l.symbol));
-            return { kind: "waterx_rule", payload: { leaves: pulled.leaves } };
-        }
-        const envelope = await fetchWaterxSignedUpdate(endpoint, tickers, fetchOpts, pulled.unavailable);
-        assertCoverage("envelope", tickers, envelope.payload.items.map((i) => i.symbol));
-        return { kind: "waterx_rule", payload: { envelope } };
+        return (await pullWaterxData(host, tickers, "strict")).data;
     },
     /**
      * Divisibility differs by variant, which is the whole reason this method
@@ -627,6 +834,28 @@ export const WaterxRule = {
         }
         return { kind: "waterx_rule", payload: { envelope } };
     },
+    /**
+     * The on-chain F-014 single-use replay key, rule-owned (see
+     * `PriceUpdateRule.updateIdentityBySymbol`): each leaf's identity is its
+     * OWN `signed_timestamp_ms`; an envelope's one `timestamp_ms` is the
+     * identity of EVERY symbol it covers (one batch signature ⇒ one submission
+     * burns the mark for all of them). A consumer's serve-at-most-once cache
+     * keys off this map for BOTH payload shapes — including the leaf-first
+     * default an envelope-only identity check would miss.
+     */
+    updateIdentityBySymbol(data) {
+        // Narrowed ONCE: a serve-at-most-once cache calls this per serve, and the
+        // accessors each re-run the full structural payload validation.
+        const payload = waterxPayloadOf(data);
+        if (!payload)
+            return null;
+        return "leaves" in payload
+            ? new Map(payload.leaves.map((leaf) => [leaf.symbol, leaf.signed_timestamp_ms]))
+            : new Map(payload.envelope.payload.items.map((item) => [
+                item.symbol,
+                payload.envelope.timestamp_ms,
+            ]));
+    },
     /**
      * No shared verify step: both `waterx_rule` collect entries bundle verify AND
      * feed into one per-collector call, appended by
@@ -635,7 +864,36 @@ export const WaterxRule = {
      * reaches the feed leg via `aggregate.ts`'s per-ticker map (built from the
      * group's fetched data), not a `RuleUpdateHandle`.
      */
-    buildUpdateCalls(_tx, _host, _data, _opts) {
+    buildUpdateCalls(_tx, _host, _data) {
         return;
     },
 };
+/**
+ * Coverage-policy seam over the rule's quote-center pull (WL-2345): fetch
+ * signed waterx update data for `tickers` with the caller choosing what a
+ * coverage gap means.
+ *
+ * - `coverage: "strict"` (default) — exactly `WaterxRule.fetchUpdateData`:
+ *   every requested ticker must be config-listed AND served, or the fetch
+ *   THROWS (`assertCoverage`); `missing` is always `[]`. Trade-path semantics
+ *   — `refreshOraclePrices` keeps consuming the rule's own strict fetch, so
+ *   `aggregate.ts`'s uncarried-ticker throw (04117a1) still can't be reached
+ *   by a payload that under-covers its group.
+ * - `coverage: "partial"` — universe-prefetch semantics (a BE cache warming
+ *   every known ticker at once): a ticker with no `waterx_rule.feeds` entry,
+ *   or one the quote-center response does not serve, lands in `missing`
+ *   instead of throwing, and `data` covers the rest. On the leaf route the
+ *   payload is the covering leaf SUBSET; on the envelope route the envelope
+ *   is kept iff it covers ≥1 requested ticker (it is indivisible — an
+ *   envelope serving none is `data: null`). `data: null` + all-missing when
+ *   nothing is servable.
+ *
+ * Consumers must not hand a partial payload to a build for tickers in
+ * `missing` — those tickers are simply not servable by waterx right now (log
+ * the gap; the chain's weight tables decide whether that starves anything).
+ */
+export async function fetchWaterxUpdateData(host, tickers, opts) {
+    if (tickers.length === 0)
+        return { data: null, missing: [] };
+    return pullWaterxData(host, tickers, opts?.coverage ?? "strict");
+}

package/dist/src/oracle/schedule.d.ts

@@ -0,0 +1,109 @@
+/**
+ * `schedule.ts` — Pyth `attributes.schedule` grammar parser + the pure
+ * market-status walker (WL-2345): the ONE implementation both consumers fold
+ * onto (the FE fallback `/api/markets` route and the BE
+ * `PythScheduleService` / markets service carried drifting twins).
+ *
+ * Parser grammar (https://docs.pyth.network/price-feeds/market-hours):
+ *
+ *   {IANA_timezone};{Mon},{Tue},{Wed},{Thu},{Fri},{Sat},{Sun};{holidays_csv}
+ *
+ * Each weekday slot is `Open`/`O`/`open`, `Closed`/`C`/`closed`, one
+ * `HHMM-HHMM` range, `&`-joined ranges (the new multi-session encoding), or
+ * comma-joined ranges (the old encoding — disambiguated from the weekday
+ * separator by lookahead). Holidays are `MMDD` (old) or `MMDD/C` (new; a
+ * `MMDD/HHMM-HHMM` modified-hours entry is NOT a closure and is skipped, as
+ * are non-MMDD sentinels like Pyth's `"0"`). This is the reconciled SUPERSET
+ * of the two prior ports — accepting either era's tokens is what lets one
+ * parser serve the `v1/symbols` catalog and any cached Hermes-era strings.
+ *
+ * Pyth weekday order is Mon=0..Sun=6; `TradingHours.days` uses ISO-ish
+ * Sun=0..Sat=6 (converted in `groupIntoSessions`).
+ *
+ * The schedule catalog itself comes from `fetchPythSymbolCatalog`
+ * (`symbol-catalog.ts`); pairing a record's `schedule` with this parser and
+ * `getMarketStatus` is the whole market-hours pipeline.
+ */
+export interface TradingSession {
+    /** HH:MM (24h) open time in the market's timezone */
+    open: string;
+    /** HH:MM (24h) close time — may be next day (e.g. "17:00" Sunday open to "17:00" Friday) */
+    close: string;
+    /** ISO day-of-week: 0=Sunday … 6=Saturday */
+    days: number[];
+}
+/**
+ * Year-agnostic `(month, day)` pair, matching Pyth's `MMDD` holiday encoding.
+ * The same `{month, day}` matches in *every* year, so moving holidays
+ * (Good Friday, MLK Day, Thanksgiving, etc.) need to be republished by Pyth
+ * each year and picked up by the consumer's next catalog refresh.
+ */
+export interface HolidayDate {
+    /** 1..12, in the schedule's timezone */
+    month: number;
+    /** 1..31, in the schedule's timezone */
+    day: number;
+    /**
+     * MODIFIED hours for this date, in place of the weekly schedule — an early
+     * close (`1224/0930-1300`) or a split session (`1224/0000-1430&1800-2400`).
+     * Absent means a FULL closure, the `MMDD/C` form.
+     *
+     * These were previously discarded, which meant the venue fell back to its
+     * NORMAL weekly hours on an early-close day and reported itself open after it
+     * had shut. They are not an edge case: the live Pyth catalog carries
+     * thousands (`0930-1300` alone appears ~2.5k times).
+     */
+    sessions?: {
+        open: string;
+        close: string;
+    }[];
+}
+export interface TradingHours {
+    /** IANA timezone identifier, e.g. "America/New_York" */
+    timezone: string;
+    sessions: TradingSession[];
+    /**
+     * Days when the venue is fully closed regardless of the weekly schedule.
+     * Optional — many feeds (crypto, FX) have none. Encoded as `(month, day)`
+     * in `timezone`'s local calendar, matching Pyth's `attributes.schedule`
+     * holiday list.
+     */
+    holidays?: HolidayDate[];
+}
+export interface ParsedPythSchedule {
+    tradingHours: TradingHours;
+    /** True iff every weekday is fully open and there are no holidays — callers treat as `tradingHours = null` (24/7, no schedule needed). */
+    alwaysOpen: boolean;
+}
+export declare class PythScheduleParseError extends Error {
+    constructor(message: string);
+}
+/**
+ * Parse a Pyth schedule string. Throws {@link PythScheduleParseError} on
+ * malformed input — callers guard with try/catch so one bad feed does not break
+ * a whole market list.
+ *
+ * DEGRADE CLOSED, not open. The obvious fallback — treat an unparseable
+ * schedule as "no schedule (24/7)" — is the wrong direction: the shapes that
+ * actually fail here are venues WITH sessions (a lunch-break equity schedule in
+ * the legacy comma encoding, an ambiguous weekday fold), and calling those 24/7
+ * reports a closed venue as tradable. That is the failure class this module
+ * exists to prevent. Prefer marking the market unavailable, or reusing the last
+ * schedule that parsed; use 24/7 only where a wrong "open" is harmless.
+ */
+export declare function parsePythSchedule(input: string): ParsedPythSchedule;
+export interface MarketStatusResult {
+    status: "open" | "closed" | "paused";
+    /** Milliseconds until next status change; null for 24/7 or paused. */
+    nextStatusChangeIn: number | null;
+}
+/**
+ * Pure function — calculates market open/closed status from trading hours + now.
+ *
+ * @param tradingHours  null means 24/7 (crypto)
+ * @param paused        forces `paused`, short-circuiting the schedule. Checked
+ *                      BEFORE the 24/7 branch, so an on-chain-paused crypto
+ *                      market (tradingHours === null) still reports paused.
+ * @param now           injectable for testing; defaults to new Date()
+ */
+export declare function getMarketStatus(tradingHours: TradingHours | null, paused: boolean, now?: Date): MarketStatusResult;