@waterx/sdk 4.3.1 → 4.3.3

package/dist/cjs/src/oracle/index.js

@@ -17,7 +17,7 @@
  * rules that consume it are separate concerns.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.reimbursePythSponsor = exports.openPythSponsorFund = exports.refreshOraclePrices = exports.aggregateTickerWithConstant = exports.aggregateTickerWithPyth = exports.aggregateTicker = exports.resolveOracleRule = exports.OracleSourceNotImplementedError = exports.waterxEnvelopeOf = exports.waterxQuoteCenterEndpoint = exports.WATERX_INFRA = exports.BATCH_PRICE_INTENT = exports.parseSignedEnvelope = exports.WaterxRule = exports.LazerApiKeyMissingError = exports.PythLazerRule = exports.PythCoreRule = exports.resolveHermesReadEndpoint = exports.resolveOracleReadPlan = exports.parseOracleSourceList = exports.isOracleSource = exports.ORACLE_SOURCES = exports.OracleFeeSourceUnavailableError = exports.MISSING_FEED_MEMO_TTL_MS = exports.HermesEndpointRejectedAllFeedsError = exports.updatePythPrices = exports.PYTH_PRO_HERMES_ENDPOINT = exports.pythProHermesEndpoint = exports.pythCoreHermesEndpoint = exports.buildPythPriceUpdateCalls = exports.probeMissingFeeds = exports.endpointSupportedFeedIds = exports.fetchPriceFeedsUpdateData = exports.PythCache = exports.joinEndpointPath = exports.fetchWithPolicy = exports.FetchPolicyError = void 0;
+exports.reimbursePythSponsor = exports.openPythSponsorFund = exports.refreshOraclePrices = exports.aggregateTickerWithConstant = exports.aggregateTickerWithPyth = exports.aggregateTicker = exports.resolveOracleRule = exports.OracleSourceNotImplementedError = exports.waterxEnvelopeOf = exports.waterxLeavesOf = exports.waterxQuoteCenterEndpoint = exports.WATERX_INFRA = exports.MERKLE_ROOT_INTENT = exports.BATCH_PRICE_INTENT = exports.parseSignedLeaves = exports.parseSignedEnvelope = exports.WaterxRule = exports.LazerApiKeyMissingError = exports.PythLazerRule = exports.PythCoreRule = exports.resolveHermesReadEndpoint = exports.resolveOracleReadPlan = exports.parseOracleSourceList = exports.isOracleSource = exports.ORACLE_SOURCES = exports.OracleFeeSourceUnavailableError = exports.MISSING_FEED_MEMO_TTL_MS = exports.HermesEndpointRejectedAllFeedsError = exports.updatePythPrices = exports.PYTH_PRO_HERMES_ENDPOINT = exports.pythProHermesEndpoint = exports.pythCoreHermesEndpoint = exports.buildPythPriceUpdateCalls = exports.probeMissingFeeds = exports.endpointSupportedFeedIds = exports.fetchPriceFeedsUpdateData = exports.PythCache = exports.joinEndpointPath = exports.fetchWithPolicy = exports.FetchPolicyError = void 0;
 // Shared fetch resilience wrapper — `FetchPolicyError` is re-exported (not
 // just the type) so a consumer (e.g. a BE prefetch cache) can `instanceof`
 // it off the failure `fetchPriceFeedsUpdateData` / `PythLazerRule` /
@@ -85,16 +85,21 @@ Object.defineProperty(exports, "PythLazerRule", { enumerable: true, get: functio
 Object.defineProperty(exports, "LazerApiKeyMissingError", { enumerable: true, get: function () { return pyth_lazer_rule_ts_1.LazerApiKeyMissingError; } });
 // `WATERX_INFRA` / `waterxQuoteCenterEndpoint` are the source's own infra table +
 // read-plane accessor (mirrors `pythCoreHermesEndpoint`).
-// WaterX quote-center rule (first-party ed25519 signed batches; `feedWaterxRule`
-// stays internal to `aggregate.ts`).
+// WaterX quote-center rule (first-party ed25519 signed prices; the `feedWaterxRule*`
+// legs stay internal to `aggregate.ts`). Both wire shapes are exported because a
+// BE prefetch cache holds whichever one its quote-center serves: per-symbol
+// Merkle leaves (default) or one indivisible batch envelope (fallback).
 var waterx_rule_ts_1 = require("./rules/waterx-rule.js");
 Object.defineProperty(exports, "WaterxRule", { enumerable: true, get: function () { return waterx_rule_ts_1.WaterxRule; } });
 Object.defineProperty(exports, "parseSignedEnvelope", { enumerable: true, get: function () { return waterx_rule_ts_1.parseSignedEnvelope; } });
+Object.defineProperty(exports, "parseSignedLeaves", { enumerable: true, get: function () { return waterx_rule_ts_1.parseSignedLeaves; } });
 Object.defineProperty(exports, "BATCH_PRICE_INTENT", { enumerable: true, get: function () { return waterx_rule_ts_1.BATCH_PRICE_INTENT; } });
+Object.defineProperty(exports, "MERKLE_ROOT_INTENT", { enumerable: true, get: function () { return waterx_rule_ts_1.MERKLE_ROOT_INTENT; } });
 Object.defineProperty(exports, "WATERX_INFRA", { enumerable: true, get: function () { return waterx_rule_ts_1.WATERX_INFRA; } });
 Object.defineProperty(exports, "waterxQuoteCenterEndpoint", { enumerable: true, get: function () { return waterx_rule_ts_1.waterxQuoteCenterEndpoint; } });
-// Rule-owned payload accessor (kind-check + unwrap in one place) — never
-// hand-cast the payload shape.
+// Rule-owned payload accessors (kind-check + unwrap in one place) — never
+// hand-cast the payload shape, and never assume which variant it is.
+Object.defineProperty(exports, "waterxLeavesOf", { enumerable: true, get: function () { return waterx_rule_ts_1.waterxLeavesOf; } });
 Object.defineProperty(exports, "waterxEnvelopeOf", { enumerable: true, get: function () { return waterx_rule_ts_1.waterxEnvelopeOf; } });
 // `resolveOracleRule` is the ONE source→rule registry — exported so external
 // consumers (e.g. a BE prefetch cache that keys per source and needs each

package/dist/cjs/src/oracle/price-update-rule.d.ts

@@ -83,14 +83,22 @@ export declare function assertRuleUpdateData<T>(data: RuleUpdateData, kind: Pric
  * return when its collector-feed leg needs a value produced by the update leg
  * *within the same PTB*. Pyth Core needs none (its feed leg reads the shared
  * `PriceInfoObject` the update leg refreshed), so it returns `void`. The Lazer
- * rule returns the verified `pyth_lazer::update::Update` result — one
+ * rule returns the verified-update result of its network's verify entry — one
  * signature verification covers every feed in the payload, and
  * `pyth_lazer_rule::feed` takes it by reference per ticker (see
  * `aggregateTicker`'s `lazerUpdate` arg).
  */
 export type RuleUpdateHandle = {
     readonly kind: "pyth_lazer_rule";
-    /** Result of `pyth_lazer::parse_and_verify_le_ecdsa_update` in this PTB. */
+    /**
+     * Opaque result of this network's `LAZER_INFRA.verify_entry` in this PTB,
+     * passed straight to `pyth_lazer_rule::feed`. The Move type is
+     * network-dependent and never named here: mainnet's
+     * `pyth_lazer::parse_and_verify_le_ecdsa_update_v2` yields
+     * `pyth_lazer::update_v2::Update`, testnet's v1
+     * `…_le_ecdsa_update` yields `pyth_lazer::update::Update`, and each
+     * network's `pyth_lazer_rule` is published bound to the matching one.
+     */
     readonly update: TransactionArgument;
 };
 /**

package/dist/cjs/src/oracle/rules/pyth-lazer-rule.d.ts

@@ -4,8 +4,9 @@
  * appends per lazer-routed ticker. Fetches one `leEcdsa` payload for all
  * requested integer feed ids from the Lazer HTTP API (Bearer-authenticated
  * via the `pythApiKey` create option), verifies it ONCE on-chain via
- * `pyth_lazer::parse_and_verify_le_ecdsa_update`, and hands the resulting
- * `Update` PTB value back through a `RuleUpdateHandle` for the feed calls.
+ * `pyth_lazer`'s verify entry for that network (see `LAZER_INFRA`), and hands the
+ * resulting `Update` PTB value back through a `RuleUpdateHandle` for the feed
+ * calls.
  */
 import type { Transaction, TransactionArgument } from "@mysten/sui/transactions";
 import type { Network } from "../../constants.ts";
@@ -21,16 +22,33 @@ import { type PriceUpdateRule } from "../price-update-rule.ts";
  *   `POST /v1/latest_price` (Bearer-authenticated). The service is
  *   network-agnostic (one signed payload verifies on any chain that trusts the
  *   Lazer signers), so both networks share the production host.
- * - `verifier_package` — the Sui package carrying
- *   `pyth_lazer::parse_and_verify_le_ecdsa_update`. Per-network: testnet is
- *   still the original v1 publish; mainnet is the v2-upgraded package (which
- *   still exposes the v1 entry `pyth_lazer_rule` binds). Values mirror the
- *   contract repo's `pyth_lazer_rule/Move.toml` published-at pins.
+ * - `verifier_package` / `verify_entry` — the Sui package carrying the verify
+ *   call, and which entry to call. These track what `pyth_lazer_rule` binds on
+ *   that network, so they move together:
+ *   - **mainnet** — the v2 package `0xefbfd064…` and the **v2** entry. The rule
+ *     was republished v2-bound after a 2026-08-05 mainnet probe: the ORIGINAL
+ *     package `0x7b502c…` now aborts `EDifferentVersion` (`state::current_cap`)
+ *     for any payload — the shared `State` has been migrated past that code —
+ *     and its v1 entry aborts `EInvalidChannel` on `fixed_rate@1000ms`, the only
+ *     channel WaterX's Pyth Pro grant permits.
+ *   - **testnet** — still the original v1 publish, which has no `update_v2`
+ *     module at all, so the v1 entry is the only one that exists there.
+ *   Both entries take `(state, clock, bytes)` and accept the same `leEcdsa`
+ *   payload. Values mirror the contract repo's `pyth_lazer_rule/Move.toml`
+ *   published-at pins.
  */
 export declare const LAZER_INFRA: Record<Network, {
     endpoint: string;
     verifier_package: string;
+    verify_entry: LazerVerifyEntry;
+    channel: string;
 }>;
+/**
+ * The `pyth_lazer` verify entry a network's deployed rule consumes. `_v2`
+ * returns `update_v2::Update`; the v1 entry returns `update::Update`, and the
+ * two are NOT interchangeable — the rule's `feed` takes one concrete type.
+ */
+export type LazerVerifyEntry = "parse_and_verify_le_ecdsa_update" | "parse_and_verify_le_ecdsa_update_v2";
 /** `pyth_lazer_rule`'s narrowed `RuleUpdateData.payload` shape. */
 export interface PythLazerUpdatePayload {
     /** One signed `leEcdsa` message carrying every requested feed. */

package/dist/cjs/src/oracle/rules/pyth-lazer-rule.js

@@ -5,8 +5,9 @@
  * appends per lazer-routed ticker. Fetches one `leEcdsa` payload for all
  * requested integer feed ids from the Lazer HTTP API (Bearer-authenticated
  * via the `pythApiKey` create option), verifies it ONCE on-chain via
- * `pyth_lazer::parse_and_verify_le_ecdsa_update`, and hands the resulting
- * `Update` PTB value back through a `RuleUpdateHandle` for the feed calls.
+ * `pyth_lazer`'s verify entry for that network (see `LAZER_INFRA`), and hands the
+ * resulting `Update` PTB value back through a `RuleUpdateHandle` for the feed
+ * calls.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PythLazerRule = exports.LazerApiKeyMissingError = exports.LAZER_INFRA = void 0;
@@ -25,20 +26,33 @@ const update_fetch_ts_1 = require("../update-fetch.js");
  *   `POST /v1/latest_price` (Bearer-authenticated). The service is
  *   network-agnostic (one signed payload verifies on any chain that trusts the
  *   Lazer signers), so both networks share the production host.
- * - `verifier_package` — the Sui package carrying
- *   `pyth_lazer::parse_and_verify_le_ecdsa_update`. Per-network: testnet is
- *   still the original v1 publish; mainnet is the v2-upgraded package (which
- *   still exposes the v1 entry `pyth_lazer_rule` binds). Values mirror the
- *   contract repo's `pyth_lazer_rule/Move.toml` published-at pins.
+ * - `verifier_package` / `verify_entry` — the Sui package carrying the verify
+ *   call, and which entry to call. These track what `pyth_lazer_rule` binds on
+ *   that network, so they move together:
+ *   - **mainnet** — the v2 package `0xefbfd064…` and the **v2** entry. The rule
+ *     was republished v2-bound after a 2026-08-05 mainnet probe: the ORIGINAL
+ *     package `0x7b502c…` now aborts `EDifferentVersion` (`state::current_cap`)
+ *     for any payload — the shared `State` has been migrated past that code —
+ *     and its v1 entry aborts `EInvalidChannel` on `fixed_rate@1000ms`, the only
+ *     channel WaterX's Pyth Pro grant permits.
+ *   - **testnet** — still the original v1 publish, which has no `update_v2`
+ *     module at all, so the v1 entry is the only one that exists there.
+ *   Both entries take `(state, clock, bytes)` and accept the same `leEcdsa`
+ *   payload. Values mirror the contract repo's `pyth_lazer_rule/Move.toml`
+ *   published-at pins.
  */
 exports.LAZER_INFRA = {
     MAINNET: {
         endpoint: "https://pyth-lazer.dourolabs.app",
         verifier_package: "0xefbfd064480777699fd9c557a5804d72ace7bc82661fdc8d1f1a44ea6d92ee10",
+        verify_entry: "parse_and_verify_le_ecdsa_update_v2",
+        channel: "fixed_rate@1000ms",
     },
     TESTNET: {
         endpoint: "https://pyth-lazer.dourolabs.app",
         verifier_package: "0xf5bd2141967507050a91b58de3d95e77c432cd90d1799ee46effc27430a68c21",
+        verify_entry: "parse_and_verify_le_ecdsa_update",
+        channel: "fixed_rate@200ms",
     },
 };
 /**
@@ -56,9 +70,15 @@ exports.LAZER_INFRA = {
  *   and every xStock — are `min_channel: fixed_rate@200ms` (Lazer symbol
  *   registry, verified 2026-07-22: the same 29-feed batch 400s at
  *   `real_time`/`50ms` and serves 200 with the leEcdsa blob at `200ms`).
- *   200ms is the fastest channel every configured feed supports, and the
- *   deployed rule accepts it: the v1 on-chain `channel::from_u8` aborts only
- *   on the 1000ms fixed-rate channel (real_time / 50ms / 200ms are safe).
+ *   The channel is therefore per-network (`LAZER_INFRA[network].channel`), and
+ *   it is bounded from BOTH sides — by what the feeds publish and by what the
+ *   grant allows:
+ *   - **mainnet: `fixed_rate@1000ms`.** WaterX's Pyth Pro grant no longer
+ *     permits anything faster ("Channel fixed_rate@200ms violates rate limit.
+ *     Minimum allowed channel is 1000ms", measured 2026-08-05), and the
+ *     mainnet rule is v2-bound, so it accepts that channel.
+ *   - **testnet: `fixed_rate@200ms`.** Its rule is still v1-bound, and the v1
+ *     on-chain `channel::from_u8` aborts on the 1000ms channel.
  * - `formats: leEcdsa` + `jsonBinaryEncoding: hex` — the Sui verifier takes
  *   the `leEcdsa` framing; hex matches `fromHex` below.
  */
@@ -66,7 +86,6 @@ const LAZER_LATEST_PRICE_REQUEST = {
     properties: ["price", "exponent", "confidence"],
     formats: ["leEcdsa"],
     jsonBinaryEncoding: "hex",
-    channel: "fixed_rate@200ms",
 };
 /**
  * Shape check ONLY — the `kind` discriminant is checked separately by the
@@ -109,7 +128,7 @@ function requireLazerPackage(host) {
  * retry/timeout/Bearer policy as `fetchPriceFeedsUpdateData`, unified so
  * both oracle sources fail the same way under upstream degradation.
  */
-async function fetchLazerSignedUpdate(endpoint, apiKey, feedIds, fetchOpts) {
+async function fetchLazerSignedUpdate(endpoint, channel, apiKey, feedIds, fetchOpts) {
     // joinEndpointPath preserves any base path on the endpoint — the same
     // leading-slash `new URL` footgun that 404'd every feed on the Pyth Pro
     // Hermes endpoint (see update-fetch.ts). Defensive here: the default
@@ -120,7 +139,7 @@ async function fetchLazerSignedUpdate(endpoint, apiKey, feedIds, fetchOpts) {
         res = await (0, update_fetch_ts_1.fetchWithPolicy)(url.toString(), {
             method: "POST",
             headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({ priceFeedIds: feedIds, ...LAZER_LATEST_PRICE_REQUEST }),
+            body: JSON.stringify({ priceFeedIds: feedIds, ...LAZER_LATEST_PRICE_REQUEST, channel }),
         }, { apiKey, ...fetchOpts });
     }
     catch (err) {
@@ -180,13 +199,13 @@ exports.PythLazerRule = {
         if (!apiKey) {
             throw new LazerApiKeyMissingError();
         }
-        const update = await fetchLazerSignedUpdate(exports.LAZER_INFRA[host.network].endpoint, apiKey, feedIds, host.pyth.fetch);
+        const update = await fetchLazerSignedUpdate(exports.LAZER_INFRA[host.network].endpoint, exports.LAZER_INFRA[host.network].channel, apiKey, feedIds, host.pyth.fetch);
         return { kind: "pyth_lazer_rule", payload: { update, feedIds } };
     },
     /**
      * A Lazer payload is ONE signed `leEcdsa` message covering every feed it was
      * fetched for — verification is a single flat signature check over the whole
-     * message (`parse_and_verify_le_ecdsa_update`, no per-feed cost), so the
+     * message (one `parse_and_verify_le_ecdsa_update*` call, no per-feed cost), so the
      * payload is indivisible: it can only be served whole. Returns the whole
      * payload iff every requested ticker's integer feed id is packed in THIS
      * payload's `feedIds`; any coverage gap (unlisted ticker, or a feed this
@@ -205,19 +224,24 @@ exports.PythLazerRule = {
         return { kind: "pyth_lazer_rule", payload };
     },
     /**
-     * Appends the single `parse_and_verify_le_ecdsa_update(state, clock, bytes)`
+     * Appends the single `parse_and_verify_le_ecdsa_update*(state, clock, bytes)`
      * call — one secp256k1 signature check covering every feed in the payload —
      * and returns its `Update` result as the handle the per-ticker feed leg
      * consumes. `opts.cache` / `opts.feeSource` are Pyth-Core-specific and
      * ignored (Lazer verification charges no update fee).
+     *
+     * The entry name comes from `LAZER_INFRA[network].verify_entry`: mainnet's
+     * rule binds `update_v2`, testnet's is still the v1 publish. Both take
+     * `(state, clock, bytes)` and accept the same `leEcdsa` payload.
      */
     buildUpdateCalls(tx, host, data, _opts) {
         const payload = (0, price_update_rule_ts_1.assertRuleUpdateData)(data, "pyth_lazer_rule", isPythLazerUpdatePayloadShape, "{ update: Uint8Array; feedIds: number[] }");
         if (!payload)
             return undefined;
         const lazer = requireLazerPackage(host);
+        const infra = exports.LAZER_INFRA[host.network];
         const [update] = tx.moveCall({
-            target: `${exports.LAZER_INFRA[host.network].verifier_package}::pyth_lazer::parse_and_verify_le_ecdsa_update`,
+            target: `${infra.verifier_package}::pyth_lazer::${infra.verify_entry}`,
             arguments: [tx.object(lazer.state), tx.object.clock(), tx.pure.vector("u8", payload.update)],
         });
         return { kind: "pyth_lazer_rule", update };

package/dist/cjs/src/oracle/rules/waterx-rule.d.ts

@@ -1,35 +1,59 @@
 /**
  * `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).
  */
 import type { Transaction, TransactionArgument } from "@mysten/sui/transactions";
 import type { Network } from "../../constants.ts";
 import type { OracleHost } from "../host.ts";
 import { type PriceUpdateRule, type RuleUpdateData } from "../price-update-rule.ts";
-/** 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 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). */
 export declare const 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.
+ */
+export declare 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`
@@ -88,39 +112,104 @@ export interface WaterxSignedEnvelope {
     /** ed25519 signature over `BCS(IntentMessage<BatchPricePayload>)`, hex (± `0x`). */
     signature: string;
 }
-/** `waterx_rule`'s narrowed `RuleUpdateData.payload` shape. */
-export interface WaterxUpdatePayload {
+/**
+ * One enclave-signed Merkle leaf from `GET /v1/quotes/leaves` — identical shape
+ * to the `/v1/quote/stream/signed` SSE/WS events (quote-center serves both from
+ * one conversion), so a leaf from either transport submits the same way.
+ *
+ * It is the batch item's fields PLUS its membership proof: on-chain,
+ * `collect_single_with_proof` recomputes `keccak256(0x00 || BCS(item))`, folds
+ * it through `proof` (sorted pairs, no direction flags), and verifies the
+ * enclave's signature over THAT root — so every item field must round-trip
+ * byte-for-byte, exactly as for the batch path.
+ */
+export interface WaterxSignedLeaf extends WaterxBatchItem {
+    /**
+     * Enclave signing timestamp of the SNAPSHOT ROOT (ms) — the on-chain
+     * `timestamp_ms` argument. Shared by every leaf of one snapshot, and distinct
+     * from `price_timestamp_ms` (when the price itself was observed).
+     */
+    signed_timestamp_ms: bigint;
+    /** keccak256 Merkle root (hex). Diagnostic only — the chain re-derives it. */
+    root: string;
+    /** Sibling hashes (hex, 32 bytes each) folding this leaf to `root`. Empty for a one-leaf snapshot. */
+    proof: string[];
+    /** ed25519 signature over `BCS(IntentMessage<MerkleRoot>)`, hex (± `0x`). */
+    signature: string;
+}
+/** Leaf variant of `waterx_rule`'s `RuleUpdateData.payload` — the default path. */
+export interface WaterxLeafPayload {
+    readonly leaves: readonly WaterxSignedLeaf[];
+}
+/** Batch-envelope variant of `waterx_rule`'s `RuleUpdateData.payload` — the fallback path. */
+export interface WaterxEnvelopePayload {
     readonly envelope: WaterxSignedEnvelope;
 }
+/**
+ * `waterx_rule`'s narrowed `RuleUpdateData.payload` shape: a per-symbol leaf set
+ * OR one indivisible batch envelope. The variant a payload carries decides which
+ * on-chain entry the feed leg emits, so consumers must route on it via
+ * {@link waterxLeavesOf} / {@link waterxEnvelopeOf} rather than assuming either.
+ */
+export type WaterxUpdatePayload = WaterxLeafPayload | WaterxEnvelopePayload;
 /**
  * Parse a quote-center `/v1/quotes/update` response body into a
- * {@link WaterxSignedEnvelope} with the u64 fields decoded as `bigint`, exact.
- *
- * 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.
+ * {@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.
  */
 export declare function parseSignedEnvelope(text: string): WaterxSignedEnvelope;
-/** Narrow a `RuleUpdateData` to its `WaterxSignedEnvelope`, or `null`. */
+/**
+ * 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.
+ */
+export declare function parseSignedLeaves(text: string): WaterxSignedLeaf[];
+/**
+ * Narrow a `RuleUpdateData` to its per-symbol {@link WaterxSignedLeaf}s, or
+ * `null` when it carries a batch envelope instead (the fallback shape).
+ */
+export declare function waterxLeavesOf(data: RuleUpdateData): readonly WaterxSignedLeaf[] | null;
+/**
+ * Narrow a `RuleUpdateData` to its `WaterxSignedEnvelope`, or `null` when it
+ * carries per-symbol leaves instead (the default shape).
+ */
 export declare function waterxEnvelopeOf(data: RuleUpdateData): WaterxSignedEnvelope | null;
+/**
+ * `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.
+ */
+export declare function feedWaterxRuleWithProof(tx: Transaction, host: OracleHost, collector: TransactionArgument, leaf: WaterxSignedLeaf): void;
 /**
  * `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.
  */
 export declare function feedWaterxRule(tx: Transaction, host: OracleHost, collector: TransactionArgument, envelope: WaterxSignedEnvelope): void;
 export declare const WaterxRule: PriceUpdateRule;