@waterx/sdk 4.3.2 → 5.0.0

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

@@ -1,51 +1,85 @@
 "use strict";
 /**
  * `WaterxRule` — `PriceUpdateRule` for the first-party WaterX quote-center
- * (Nautilus-TEE, ed25519), plus `feedWaterxRule`, the collector-feed leg
- * `aggregateTicker` appends per waterx-routed ticker. Pulls one enclave-signed
- * batch envelope covering every requested ticker from the quote-center
- * (`GET /v1/quotes/update?symbols=…`, endpoint from `host.waterx` — the
- * `waterxEndpoint`/`waterxFetch` create options — else its own `WATERX_INFRA`), then —
- * unlike Pyth Lazer, whose verify is a single shared PTB step — verifies AND
- * feeds in ONE `waterx_rule::collect_batch_latest` call per collector (the Move
- * API bundles the two). So `buildUpdateCalls` emits nothing and the signed
- * envelope is handed straight to the per-ticker feed leg.
+ * (Nautilus-TEE, ed25519), plus the collector-feed legs `aggregateTicker`
+ * appends per waterx-routed ticker. Endpoint comes from `host.waterx` (the
+ * `waterxEndpoint`/`waterxFetch` create options), else this source's own
+ * `WATERX_INFRA`. Unlike Pyth Lazer, whose verify is a single shared PTB step,
+ * the Move API bundles verify AND feed into ONE call per collector, so
+ * `buildUpdateCalls` emits nothing and the signed data is handed straight to
+ * the per-ticker feed leg.
  *
- * `collect_batch_latest` is the dual-rule path: it feeds the item matching
- * `collector.symbol()` WITHOUT aggregating, so a waterx-routed ticker composes
- * onto the same collector as Pyth/Supra (compose-then-aggregate). On-chain a
- * FRESHNESS miss ABSTAINS (the other weighted rules cover); a config/
- * integrity mismatch, bad signature, future timestamp — or a REPLAYED signed
- * timestamp — ABORTS (`EReplayedSignature`, audit F-014: a signed tuple is
- * single-use per symbol, enforced by a per-symbol high-water mark BEFORE any
- * weight arbitration). Consequence for concurrent builds: two PTBs carrying
- * the same envelope for the same symbol cannot both land — the second aborts
- * even if the rule is unweighted for that ticker. Never share one fetched
- * envelope across builds that may execute concurrently for the same symbol.
+ * TWO wire shapes carry the same prices, and this rule prefers the first:
+ *
+ * 1. **Merkle leaves** (default) — `GET /v1/quotes/leaves?symbols=…` returns one
+ *    `SignedLeaf` per symbol: the price fields, a Merkle `proof`, and the
+ *    enclave's signature over the snapshot ROOT (`MERKLE_ROOT_INTENT`). Fed via
+ *    {@link feedWaterxRuleWithProof} → `waterx_rule::collect_single_with_proof`,
+ *    which re-derives the root from the leaf + proof. One symbol costs ONE
+ *    `new_batch_item` plus ~log2(n) 32-byte proof hashes.
+ * 2. **Batch envelope** (fallback) — `GET /v1/quotes/update?symbols=…` returns
+ *    ONE signature over the whole item vector (`BATCH_PRICE_INTENT`). It is
+ *    indivisible: {@link feedWaterxRule} must rebuild EVERY item in-PTB for
+ *    `waterx_rule::collect_batch_latest` to re-verify, even to use one symbol's
+ *    price. With the 29-feed mainnet registry that is 58 extra moveCalls and
+ *    ~320 extra pure inputs on every trade, which is why it is no longer the
+ *    default. Used only when the quote-center has no leaf route yet (404),
+ *    and by callers that still push whole batches.
+ *
+ * Both collect entries are the dual-rule path: they feed `collector.symbol()`
+ * WITHOUT aggregating, so a waterx-routed ticker composes onto the same
+ * collector as Pyth/Supra (compose-then-aggregate). Their abort-vs-abstain
+ * disposition is identical: a config/integrity mismatch, a bad signature or a
+ * signed timestamp AHEAD of the on-chain `Clock` ABORTS; a freshness miss
+ * ABSTAINS so the other weighted rules cover a lagging TEE, and so does a
+ * REPLAYED signed timestamp (the per-symbol high-water mark of audit F-014 —
+ * already-recorded means the chain holds a price at least this fresh, so two
+ * PTBs carrying the same snapshot for the same symbol no longer kill each
+ * other; only the single-rule `feed_*` entries abort on a replay).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WaterxRule = exports.WATERX_INFRA = exports.BATCH_PRICE_INTENT = void 0;
+exports.WaterxRule = exports.WATERX_MAX_BATCH_SYMBOLS = exports.WATERX_CLOCK_SKEW_TOLERANCE_MS = exports.WATERX_MAX_PRICE_AGE_MS = exports.WATERX_INFRA = exports.MERKLE_ROOT_INTENT = exports.BATCH_PRICE_INTENT = void 0;
 exports.waterxQuoteCenterEndpoint = waterxQuoteCenterEndpoint;
+exports.isFreshWaterxEntry = isFreshWaterxEntry;
 exports.parseSignedEnvelope = parseSignedEnvelope;
+exports.parseSignedLeaves = parseSignedLeaves;
+exports.fetchWaterxSignedUpdate = fetchWaterxSignedUpdate;
+exports.fetchWaterxSignedLeaves = fetchWaterxSignedLeaves;
+exports.waterxLeavesOf = waterxLeavesOf;
 exports.waterxEnvelopeOf = waterxEnvelopeOf;
+exports.feedWaterxRuleWithProof = feedWaterxRuleWithProof;
 exports.feedWaterxRule = feedWaterxRule;
+exports.pullWaterxQuotes = pullWaterxQuotes;
+exports.fetchWaterxUpdateData = fetchWaterxUpdateData;
 const bcs_1 = require("@mysten/bcs");
 const waterx_rule_ts_1 = require("../../generated/waterx_rule/waterx_rule.js");
 const record_ts_1 = require("../../utils/record.js");
 const price_update_rule_ts_1 = require("../price-update-rule.js");
 const update_fetch_ts_1 = require("../update-fetch.js");
-/** The single signing intent the quote-center emits — 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. */
 exports.BATCH_PRICE_INTENT = 1;
+/**
+ * Intent the quote-center signs a snapshot's Merkle ROOT under
+ * (`waterx_rule::MERKLE_ROOT_INTENT`). Distinct from
+ * {@link BATCH_PRICE_INTENT} on purpose: the intent byte is the first field of
+ * the signed `IntentMessage`, so a batch signature can never be replayed as a
+ * root signature or vice versa. Leaves carry no `intent` field of their own —
+ * they are only ever submitted through `collect_single_with_proof`, which pins
+ * the intent on-chain — so this exists to name the scheme, not to gate a parse.
+ */
+exports.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
@@ -58,65 +92,316 @@ exports.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.
  */
 function waterxQuoteCenterEndpoint(network) {
     return exports.WATERX_INFRA[network].endpoint;
 }
 /**
- * Shape check ONLY — the `kind` discriminant is checked separately by the
- * caller before this runs (mirrors the other rules' guard split), so a
- * same-shaped payload from a different rule can never silently pass.
+ * 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.)
  */
-function isWaterxUpdatePayloadShape(payload) {
+exports.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.
+ */
+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 < -exports.WATERX_CLOCK_SKEW_TOLERANCE_MS)
+        return false;
+    return age <= exports.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.
+ */
+exports.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. */
 /**
- * Parse a quote-center `/v1/quotes/update` response body into a
- * {@link WaterxSignedEnvelope} with the u64 fields decoded as `bigint`, exact.
+ * 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",
+];
+/**
+ * FULL structural check on a leaf, not just the fields the feed leg happens to
+ * touch first.
  *
- * The signature is over `BCS(IntentMessage<BatchPricePayload>)`, so every u64
- * the SDK rebuilds in-PTB must equal the enclave's byte-for-byte or
- * `collect_batch_latest` aborts the whole trade PTB (bad signature — not an
- * abstain). A plain `JSON.parse` yields IEEE-754 doubles that lose precision
- * above 2^53, so instead we recover each integer's exact source literal via the
- * ES2023 reviver `context.source` (Node 21+ / modern browsers) and `BigInt()`
- * it. On an older runtime that passes no `context`, a value within 2^53 is
- * still exact (`BigInt(number)`); a value ABOVE it throws loudly here rather
- * than silently corrupting the payload into an on-chain abort. `num_sources`
- * (u8) and `intent` are coerced back to `number` — both are tiny.
+ * Every field here is either part of the BCS bytes the enclave signed (so a
+ * missing one means the rebuilt item cannot match) or the signature/proof
+ * material itself. A partial guard let a 200 that omitted, say, `ticker` pass as
+ * a valid leaf and fail LATER, mid-PTB-build, as `Parameter ticker is required`
+ * — after `assertCoverage` had already declared the response good, and while the
+ * caller's `tx` was already being mutated. `parseSignedLeaves` promises to reject
+ * a malformed leaf before any PTB is touched; this is what makes that true.
  */
-function parseSignedEnvelope(text) {
-    const raw = JSON.parse(text, (_key, value, context) => {
-        if (typeof value !== "number" || !Number.isInteger(value))
+/** Hex characters only. Length is checked separately — see {@link isHexOfBytes}. */
+const HEX_ONLY = /^[0-9a-fA-F]*$/;
+/**
+ * `true` iff `hex` (± `0x`) is exactly `bytes` bytes of hex.
+ *
+ * A static pattern plus an explicit length compare, deliberately not a computed
+ * `new RegExp(`…{${bytes * 2}}`)`: that recompiles on every call and semgrep
+ * blocks it as `detect-non-literal-regexp`.
+ */
+function isHexOfBytes(hex, bytes) {
+    if (typeof hex !== "string")
+        return false;
+    const body = hex.startsWith("0x") ? hex.slice(2) : hex;
+    return body.length === bytes * 2 && HEX_ONLY.test(body);
+}
+/**
+ * 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 === "")
+        return false;
+    if (typeof l.ticker !== "string" || l.ticker === "")
+        return false;
+    if (typeof l.method !== "string" || l.method === "")
+        return false;
+    // `num_sources` is a u8, and this guard runs at TWO stages: on the freshly
+    // revived object (where every JSON integer, including this one, is a bigint)
+    // and again on a normalized payload from `narrowUpdateData` / a consumer cache
+    // (where `parseSignedLeaves` has coerced it to a number). Both are valid here;
+    // only the domain matters.
+    const n = l.num_sources;
+    if (typeof n === "bigint") {
+        if (n < 0n || n > 255n)
+            return false;
+    }
+    else if (typeof n === "number") {
+        if (!Number.isInteger(n) || n < 0 || n > 255)
+            return false;
+    }
+    else {
+        return false;
+    }
+    // `sources` is a vector<u64>: exact bigints, like every other signed integer.
+    if (!Array.isArray(l.sources) || l.sources.length === 0)
+        return false;
+    if (l.sources.some((s) => typeof s !== "bigint" || s < 0n))
+        return false;
+    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))
+        return false;
+    if (!isHexOfBytes(l.root, 32))
+        return false;
+    if (!Array.isArray(l.proof) || l.proof.some((p) => typeof p !== "string"))
+        return false;
+    return true;
+}
+/**
+ * Shape check ONLY — the `kind` discriminant is checked separately by the
+ * caller before this runs (mirrors the other rules' guard split), so a
+ * same-shaped payload from a different rule can never silently pass. Accepts
+ * either variant; the accessors below pick one out.
+ */
+function isWaterxUpdatePayloadShape(payload) {
+    return isWaterxLeafPayloadShape(payload) || isWaterxEnvelopePayloadShape(payload);
+}
+/** A JSON number token that is lexically an integer: no `.`, no `e`/`E`. */
+const INTEGER_TOKEN = /^-?\d+$/;
+/**
+ * `JSON.parse` with every integer decoded as an exact `bigint`.
+ *
+ * The signature is over `BCS(IntentMessage<…>)`, so every u64 the SDK rebuilds
+ * in-PTB must equal the enclave's byte-for-byte or the on-chain verify fails and
+ * ABORTS the whole trade PTB (a bad signature is not an abstain). A plain
+ * `JSON.parse` yields IEEE-754 doubles that lose precision above 2^53, so
+ * instead we recover each integer's exact source literal via the ES2023 reviver
+ * `context.source` (Node 21+ / modern browsers) and `BigInt()` it. On an older
+ * runtime that passes no `context`, a value within 2^53 is still exact
+ * (`BigInt(number)`); a value ABOVE it throws loudly here rather than silently
+ * corrupting the payload into an on-chain abort.
+ *
+ * Integrality is decided from the SOURCE TOKEN, never from the parsed value: a
+ * display float can be lexically `0.0` while `JSON.parse` hands back the number
+ * `0`, which `Number.isInteger` accepts — and `BigInt("0.0")` throws
+ * `SyntaxError`. The leaf endpoint really does emit that (Rust `f64` serializes
+ * a whole number as `0.0`), so keying off the value crashed every fetch that
+ * included, say, a `confidence: 0.0` leaf. Exponent tokens (`1e3`) throw the
+ * same way. Only `-?\d+` becomes a `bigint`; every other numeric token stays a
+ * number, which is right for the display-only `price` / `confidence` fields —
+ * they are not part of any signed byte string.
+ */
+function parseWithExactIntegers(text, what) {
+    return JSON.parse(text, (_key, value, context) => {
+        if (typeof value !== "number")
+            return value;
+        const token = context?.source;
+        if (token !== undefined) {
+            return INTEGER_TOKEN.test(token) ? BigInt(token) : value;
+        }
+        // No JSON source access on this runtime: fall back to the parsed value.
+        // A display float that happens to be whole (`0.0` → `0`) becomes a bigint
+        // here, which is harmless — no signed field is read off those two.
+        if (!Number.isInteger(value))
             return value;
-        if (context?.source !== undefined)
-            return BigInt(context.source);
         if (!Number.isSafeInteger(value)) {
-            throw new Error("waterx envelope carries an integer above 2^53 and this runtime lacks JSON " +
+            throw new Error(`waterx ${what} carries an integer above 2^53 and this runtime lacks JSON ` +
                 "source access — cannot preserve u64 precision for the signed payload");
         }
         return BigInt(value);
     });
+}
+/**
+ * Parse a quote-center `/v1/quotes/update` response body into a
+ * {@link WaterxSignedEnvelope} with the u64 fields decoded as `bigint`, exact
+ * (see {@link parseWithExactIntegers}). `num_sources` (u8) and `intent` are
+ * coerced back to `number` — both are tiny.
+ */
+function parseSignedEnvelope(text) {
+    const raw = parseWithExactIntegers(text, "envelope");
     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.
+ *
+ * The chain would only reject a malformed one at SUBMISSION, and opaquely: a
+ * short/long/garbage sibling folds to a root the enclave never signed, which
+ * surfaces as `EInvalidSignature` from `verify_merkle_root` — at that point
+ * indistinguishable from a genuinely forged signature. So it is checked twice,
+ * at both doors a leaf can come through: on the wire ({@link parseSignedLeaves})
+ * and again in the feed leg ({@link feedWaterxRuleWithProof}), which is the last
+ * gate for a leaf handed in by a consumer's prefetch cache instead of parsed
+ * here. Same reason the keeper's Rust builder checks the length.
+ */
+function assertHash32(symbol, sibling) {
+    if (!isHexOfBytes(sibling, 32)) {
+        throw new Error(`WaterX leaf for ${symbol} carries a proof element that is not a 32-byte hex hash: ` +
+            `'${sibling}'`);
+    }
+}
+/**
+ * Parse a quote-center `/v1/quotes/leaves` response body (`{ leaves: [...] }`)
+ * into {@link WaterxSignedLeaf}s, u64s exact as `bigint`, rejecting a malformed
+ * leaf or proof element on the wire — before any PTB is touched.
+ */
+function parseSignedLeaves(text) {
+    const raw = parseWithExactIntegers(text, "leaf");
+    if (!Array.isArray(raw.leaves)) {
+        throw new Error("WaterX quote-center returned a malformed leaf response (expected { leaves })");
+    }
+    return raw.leaves.map((leaf, i) => {
+        if (!isSignedLeafShape(leaf)) {
+            // Name the leaf when it carried a usable symbol — a coverage gap and a
+            // malformed field read very differently to whoever is paging through this.
+            const named = leaf?.symbol;
+            const which = typeof named === "string" && named !== "" ? `'${named}'` : `at index ${i}`;
+            throw new Error(`WaterX quote-center returned a malformed signed leaf ${which}`);
+        }
+        for (const sibling of leaf.proof)
+            assertHash32(leaf.symbol, sibling);
+        return { ...leaf, num_sources: Number(leaf.num_sources) };
+    });
+}
 /** The `waterx_rule` deployment entry; throws when the config carries none. */
 function requireWaterxPackage(host) {
     const entry = host.config.packages.waterx_rule;
@@ -155,75 +440,261 @@ function resolveWaterxInfra(host) {
  * `https://app.example/v1/quotes/update`, bypassing the proxy). Same footgun
  * that 404'd every Pyth Pro feed by dropping its `/hermes` prefix.
  */
-async function fetchWaterxSignedUpdate(endpoint, symbols, fetchOpts) {
-    const url = (0, update_fetch_ts_1.joinEndpointPath)(endpoint, "v1/quotes/update");
+async function fetchQuoteCenter(endpoint, path, symbols, what, fetchOpts) {
+    const url = (0, update_fetch_ts_1.joinEndpointPath)(endpoint, path);
     url.searchParams.set("symbols", symbols.join(","));
-    let res;
     try {
-        res = await (0, update_fetch_ts_1.fetchWithPolicy)(url.toString(), { method: "GET" }, { ...fetchOpts });
+        return await (0, update_fetch_ts_1.fetchWithPolicy)(url.toString(), { method: "GET" }, { ...fetchOpts });
     }
     catch (err) {
         if (err instanceof update_fetch_ts_1.FetchPolicyError && err.status !== undefined) {
             const body = err.bodySnippet ? ` ${err.bodySnippet}` : "";
-            throw new Error(`WaterX quote-center fetch failed: ${err.status}${body} (retries exhausted after ${err.attempts} attempts)`, { cause: err });
+            throw new Error(`WaterX quote-center ${what} failed: ${err.status}${body} (retries exhausted after ${err.attempts} attempts)`, { cause: err });
         }
         throw err;
     }
+}
+/**
+ * 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) {
+    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 > exports.WATERX_MAX_BATCH_SYMBOLS) {
+        throw new Error(`WaterX quote-center batch fetch needs ${String(symbols.length)} symbols but the enclave ` +
+            `signs at most ${String(exports.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()}`);
+        throw new Error(`WaterX quote-center fetch failed: ${res.status} ${await res.text()}${context}`);
     }
     // Parse from raw text (not res.json()) so the u64 fields are decoded exact as
     // bigint — see parseSignedEnvelope. Malformed-shape check lives there.
     const envelope = parseSignedEnvelope(await res.text());
     if (envelope.intent !== exports.BATCH_PRICE_INTENT) {
-        throw new Error(`WaterX quote-center returned intent ${envelope.intent}, expected BATCH_PRICE_INTENT ${exports.BATCH_PRICE_INTENT}`);
+        throw new Error(`WaterX quote-center returned intent ${envelope.intent}, expected BATCH_PRICE_INTENT ${exports.BATCH_PRICE_INTENT}${context}`);
     }
     return envelope;
 }
-/** Narrow a `RuleUpdateData` to its `WaterxSignedEnvelope`, or `null`. */
+/**
+ * Pull per-symbol signed Merkle leaves — the DEFAULT update-data shape (see the
+ * module header for why it beats the indivisible batch envelope on a trade path).
+ *
+ * Returns `{ unavailable }` on `404` — and ONLY on 404, the one status that
+ * means "this route isn't here": a quote-center older than `/v1/quotes/leaves`
+ * has no handler registered for the path. That is the version-skew case the
+ * caller answers by falling back to the batch envelope, so the SDK and the
+ * quote-center can be deployed in either order.
+ *
+ * Everything else THROWS rather than falling back, INCLUDING 5xx (`501` among
+ * them — `fetchWithPolicy` classifies every 5xx as retryable and has already
+ * spent its retry budget by the time one surfaces here). A degraded or
+ * unreachable quote-center would fail the envelope route the same way — same
+ * service, same enclave behind it — so falling back would only double the
+ * latency of an already-failing money-path build, and would report an outage as
+ * a version skew.
+ *
+ * A 404 can ALSO mean "unknown symbol" (the quote-center 404s a symbol missing
+ * 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) {
+    // 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.
+ */
+exports.WATERX_MAX_BATCH_SYMBOLS = 32;
+function chunkSymbols(symbols) {
+    if (symbols.length <= exports.WATERX_MAX_BATCH_SYMBOLS)
+        return [symbols];
+    const out = [];
+    for (let i = 0; i < symbols.length; i += exports.WATERX_MAX_BATCH_SYMBOLS) {
+        out.push(symbols.slice(i, i + exports.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() };
+    }
+    if (!res.ok) {
+        throw new Error(`WaterX quote-center leaf fetch failed: ${res.status} ${await res.text()}`);
+    }
+    // Raw text, not res.json(): u64s must survive as exact bigints.
+    return { leaves: parseSignedLeaves(await res.text()) };
+}
+/**
+ * Every requested ticker must be covered by what came back. A 200 whose items
+ * omit a requested symbol is a valid, well-signed response — nothing downstream
+ * would reject it, and the build would emit a collect call that abstains for the
+ * missing symbol, surfacing as an on-chain `EMissingPriceSource` (or a silently
+ * thinner weighted set) much later. Same coverage rule
+ * {@link WaterxRule.narrowUpdateData} enforces on a cached payload; the
+ * difference is disposition — a cache miss falls back to a live fetch, whereas
+ * the live source itself coming up short has no fallback left, so it throws.
+ */
+function assertCoverage(what, tickers, covered) {
+    const have = new Set(covered);
+    const missing = tickers.filter((t) => !have.has(t));
+    if (missing.length > 0) {
+        throw new Error(`WaterX quote-center ${what} does not cover ticker(s): ${missing.join(", ")} ` +
+            `(requested ${tickers.join(", ")}; served ${[...have].join(", ") || "none"})`);
+    }
+}
+/**
+ * Narrow a `RuleUpdateData` to this rule's payload (either variant), or `null`.
+ * Kind/shape mismatches throw — see {@link assertRuleUpdateData}.
+ */
+function waterxPayloadOf(data) {
+    return (0, price_update_rule_ts_1.assertRuleUpdateData)(data, "waterx_rule", isWaterxUpdatePayloadShape, "{ leaves: [...] } or { envelope: { intent, timestamp_ms, payload: { items }, signature } }");
+}
+/**
+ * Narrow a `RuleUpdateData` to its per-symbol {@link WaterxSignedLeaf}s, or
+ * `null` when it carries a batch envelope instead (the fallback shape).
+ */
+function waterxLeavesOf(data) {
+    const payload = waterxPayloadOf(data);
+    return payload && "leaves" in payload ? payload.leaves : null;
+}
+/**
+ * Narrow a `RuleUpdateData` to its `WaterxSignedEnvelope`, or `null` when it
+ * carries per-symbol leaves instead (the default shape).
+ */
 function waterxEnvelopeOf(data) {
-    const payload = (0, price_update_rule_ts_1.assertRuleUpdateData)(data, "waterx_rule", isWaterxUpdatePayloadShape, "{ envelope: { intent, timestamp_ms, payload: { items }, signature } }");
-    return payload?.envelope ?? null;
+    const payload = waterxPayloadOf(data);
+    return payload && "envelope" in payload ? payload.envelope : null;
 }
 /** Strip an optional `0x` prefix, then decode hex → bytes. */
-function decodeSig(hex) {
+function decodeHex(hex) {
     return (0, bcs_1.fromHex)(hex.startsWith("0x") ? hex.slice(2) : hex);
 }
+/**
+ * `new_batch_item` with the item fields passed through VERBATIM: the u64s are
+ * already exact bigints (see {@link parseWithExactIntegers}), so the BCS the
+ * chain rebuilds matches the bytes the enclave signed — whether it re-verifies
+ * them as one item of a batch payload or as a Merkle leaf.
+ */
+function newItemArg(tx, pkg, item) {
+    return (0, waterx_rule_ts_1.newBatchItem)({
+        package: pkg,
+        arguments: {
+            symbol: item.symbol,
+            ticker: item.ticker,
+            sources: item.sources,
+            method: item.method,
+            priceTimestampMs: item.price_timestamp_ms,
+            priceN: item.price_n,
+            priceScale: item.price_scale,
+            confidenceN: item.confidence_n,
+            confidenceScale: item.confidence_scale,
+            maxSourceDeviationBps: item.max_source_deviation_bps,
+            numSources: item.num_sources,
+        },
+    })(tx);
+}
+/**
+ * `waterx_rule::collect_single_with_proof(collector, config, clock,
+ * enclave_config, enclave, timestamp_ms, item, proof, sig)` — the DEFAULT feed
+ * leg. Rebuilds ONE item in-PTB and hands it over with its Merkle proof; on-chain
+ * the leaf is hashed, folded through the proof, and the enclave's signature over
+ * the resulting root is verified before the price reaches the collector.
+ *
+ * Cost is what makes this the default: one item + `proof.length` 32-byte hashes
+ * (~log2 of the snapshot width — 4 to 5 for the 29-feed mainnet registry),
+ * against {@link feedWaterxRule}'s obligation to rebuild every item the batch
+ * signature covers.
+ *
+ * Abort vs abstain is identical to the batch path (see the module header): a
+ * mismatched root, a bad signature, a future signed timestamp, or a config
+ * mismatch ABORTS; a freshness miss or a replayed signed timestamp abstains. One
+ * extra abort of its own — `ECollectorSymbolMismatch` if the leaf's symbol isn't
+ * the collector's — which `aggregateTicker` prevents by construction, since it
+ * looks the leaf up BY the ticker it just built the collector for.
+ */
+function feedWaterxRuleWithProof(tx, host, collector, leaf) {
+    const wr = requireWaterxPackage(host);
+    const pkg = wr.published_at;
+    const item = newItemArg(tx, pkg, leaf);
+    (0, waterx_rule_ts_1.collectSingleWithProof)({
+        package: pkg,
+        arguments: {
+            collector,
+            config: tx.object(wr.config),
+            enclaveConfig: tx.object(wr.enclave_config),
+            enclave: tx.object(wr.enclave),
+            timestampMs: leaf.signed_timestamp_ms,
+            item,
+            // vector<vector<u8>>: sibling hashes in fold order, each re-checked as a
+            // 32-byte hash (see assertHash32 — a cached leaf never passed the parser).
+            proof: leaf.proof.map((sibling) => {
+                assertHash32(leaf.symbol, sibling);
+                return Array.from(decodeHex(sibling));
+            }),
+            sig: Array.from(decodeHex(leaf.signature)),
+        },
+    })(tx);
+}
 /**
  * `waterx_rule::collect_batch_latest(collector, config, clock, enclave_config,
- * enclave, timestamp_ms, payload, sig)` — rebuild the enclave-signed batch
- * payload in-PTB (`new_batch_payload` + one `new_batch_item`/`push_batch_item`
- * per item, the exact shape the enclave signed) and contribute the price for
- * `collector.symbol()` to the collector. One collect call re-verifies the batch
- * signature and picks this collector's symbol out of the batch; on-chain it
- * abstains (records `none`) when the symbol is stale or absent from the batch,
- * but ABORTS `EReplayedSignature` when the symbol's signed timestamp was
- * already accepted (per-symbol high-water mark, audit F-014) — see the module
- * header for the concurrent-build consequence.
+ * enclave, timestamp_ms, payload, sig)` — the FALLBACK feed leg, for a
+ * quote-center with no leaf route (and for callers that hold a whole batch).
+ * Rebuilds the enclave-signed batch payload in-PTB (`new_batch_payload` + one
+ * `new_batch_item`/`push_batch_item` per item, the exact shape the enclave
+ * signed) and contributes the price for `collector.symbol()` to the collector.
+ *
+ * Every item must be rebuilt, not just this collector's: the signature covers
+ * `BCS(IntentMessage)` over the whole vector, so a missing item is a failed
+ * verify. That is the cost {@link feedWaterxRuleWithProof} exists to avoid.
+ *
+ * On-chain it abstains (records `none`) when the symbol is stale, absent from the
+ * batch, or already recorded at this signed timestamp; it ABORTS on a bad
+ * signature, a signed timestamp ahead of the `Clock`, or a config mismatch.
  */
 function feedWaterxRule(tx, host, collector, envelope) {
     const wr = requireWaterxPackage(host);
     const pkg = wr.published_at;
     const payload = (0, waterx_rule_ts_1.newBatchPayload)({ package: pkg })(tx);
     for (const item of envelope.payload.items) {
-        // u64 fields are already exact bigints (see parseSignedEnvelope) — passed
-        // through verbatim so the rebuilt BCS matches the enclave's signed bytes.
-        const itemArg = (0, waterx_rule_ts_1.newBatchItem)({
-            package: pkg,
-            arguments: {
-                symbol: item.symbol,
-                ticker: item.ticker,
-                sources: item.sources,
-                method: item.method,
-                priceTimestampMs: item.price_timestamp_ms,
-                priceN: item.price_n,
-                priceScale: item.price_scale,
-                confidenceN: item.confidence_n,
-                confidenceScale: item.confidence_scale,
-                maxSourceDeviationBps: item.max_source_deviation_bps,
-                numSources: item.num_sources,
-            },
-        })(tx);
+        const itemArg = newItemArg(tx, pkg, item);
         (0, waterx_rule_ts_1.pushBatchItem)({ package: pkg, arguments: { payload, item: itemArg } })(tx);
     }
     (0, waterx_rule_ts_1.collectBatchLatest)({
@@ -235,65 +706,141 @@ function feedWaterxRule(tx, host, collector, envelope) {
             enclave: tx.object(wr.enclave),
             timestampMs: envelope.timestamp_ms,
             payload,
-            sig: Array.from(decodeSig(envelope.signature)),
+            sig: Array.from(decodeHex(envelope.signature)),
         },
     })(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.
+ */
+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) {
+        ((0, record_ts_1.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
+            ? exports.WaterxRule.narrowUpdateData(host, { kind: "waterx_rule", payload }, covered)
+            : null,
+        missing,
+    };
+}
 exports.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 one enclave-signed batch envelope covering `tickers` from the
-     * quote-center, and only returns it when it actually covers ALL of them.
-     *
-     * A 200 whose `items` omit a requested symbol is a valid, well-signed
-     * envelope — nothing downstream would reject it, and the build would emit a
-     * `collect_batch_latest` that abstains for the missing symbol, surfacing as
-     * an on-chain `EMissingPriceSource` (or a silently thinner weighted set) much
-     * later. Same coverage rule the cached path enforces in
-     * {@link WaterxRule.narrowUpdateData}; the difference is disposition — a
-     * cache miss falls back to this live fetch, whereas the live source itself
-     * coming up short has no fallback left, so it throws deterministically here.
+     * Pulls per-symbol Merkle leaves for `tickers`, falling back to one batch
+     * 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 ((0, record_ts_1.ownEntry)(feeds, ticker) === undefined) {
-                throw new Error(`No waterx_rule feed listed for ticker: ${ticker}`);
-            }
-        }
-        const { endpoint, fetch: fetchOpts } = resolveWaterxInfra(host);
-        const envelope = await fetchWaterxSignedUpdate(endpoint, tickers, fetchOpts);
-        const covered = new Set(envelope.payload.items.map((i) => i.symbol));
-        const missing = tickers.filter((t) => !covered.has(t));
-        if (missing.length > 0) {
-            throw new Error(`WaterX quote-center envelope does not cover ticker(s): ${missing.join(", ")} ` +
-                `(requested ${tickers.join(", ")}; served ${[...covered].join(", ") || "none"})`);
-        }
-        return { kind: "waterx_rule", payload: { envelope } };
+        return (await pullWaterxData(host, tickers, "strict")).data;
     },
     /**
-     * One signed batch envelope carries a single ed25519 signature over its whole
-     * `payload` — it is indivisible: it can only be served whole (re-verified from
-     * the full item set). Returns the whole payload iff every requested ticker's
-     * item is present in THIS envelope; any coverage gap → `null` (miss), never a
+     * Divisibility differs by variant, which is the whole reason this method
+     * belongs to the rule and not to its consumers:
+     *
+     * - **Leaves** are per-symbol and independently verifiable (each carries its
+     *   own proof + root signature), so a wider payload — e.g. a whole-universe
+     *   prefetch cache — is SUBSET to exactly `tickers`. A trade then carries one
+     *   leaf instead of the whole cached snapshot.
+     * - **A batch envelope** carries a single signature over its whole `payload`
+     *   and is indivisible: it is returned whole, or not at all.
+     *
+     * Either way a ticker this payload cannot serve → `null` (miss), never a
      * silent partial.
      */
     narrowUpdateData(_host, data, tickers) {
+        if (tickers.length === 0)
+            return null;
+        const leaves = waterxLeavesOf(data);
+        if (leaves) {
+            // Indexed by symbol, then walked in REQUESTED order: a `filter` would let
+            // a payload that repeats one symbol and omits another pass on count alone.
+            const bySymbol = new Map(leaves.map((l) => [l.symbol, l]));
+            const subset = [];
+            for (const ticker of tickers) {
+                const leaf = bySymbol.get(ticker);
+                if (!leaf)
+                    return null;
+                subset.push(leaf);
+            }
+            return { kind: "waterx_rule", payload: { leaves: subset } };
+        }
         const envelope = waterxEnvelopeOf(data);
-        if (!envelope || tickers.length === 0)
+        if (!envelope)
             return null;
         const covered = new Set(envelope.payload.items.map((i) => i.symbol));
         for (const ticker of tickers) {
@@ -303,13 +850,65 @@ exports.WaterxRule = {
         return { kind: "waterx_rule", payload: { envelope } };
     },
     /**
-     * No shared verify step: `waterx_rule::collect_batch_latest` bundles verify
-     * AND feed into one per-collector call, appended by {@link feedWaterxRule} in
-     * the per-ticker aggregate leg. So this emits nothing and returns `void` — the
-     * signed envelope reaches the feed leg via `aggregate.ts`'s per-ticker map
-     * (built from the group's fetched data), not a `RuleUpdateHandle`.
+     * 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
+     * {@link feedWaterxRuleWithProof} / {@link feedWaterxRule} in the per-ticker
+     * aggregate leg. So this emits nothing and returns `void` — the signed data
+     * 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).
+ */
+async function fetchWaterxUpdateData(host, tickers, opts) {
+    if (tickers.length === 0)
+        return { data: null, missing: [] };
+    return pullWaterxData(host, tickers, opts?.coverage ?? "strict");
+}