@waterx/sdk 4.0.0 → 4.1.0

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

@@ -3,7 +3,7 @@
  * updates, plus `feedLazerRule`, the collector-feed leg `aggregateTicker`
  * appends per lazer-routed ticker. Fetches one `leEcdsa` payload for all
  * requested integer feed ids from the Lazer HTTP API (Bearer-authenticated
- * via `config.pyth.api_key`), verifies it ONCE on-chain via
+ * 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.
  */
@@ -19,11 +19,11 @@ export interface PythLazerUpdatePayload {
 }
 /**
  * Thrown by {@link PythLazerRule.fetchUpdateData} when `pyth_lazer_rule` is
- * deployed in config but no `pyth.api_key` is set — the Lazer HTTP API
- * requires a Bearer token and the SDK never reads `process.env` to find one.
- * `instanceof`-able (mirrors `OracleFeeSourceUnavailableError` in `pyth.ts`)
- * so a consumer can branch on the failure type directly instead of
- * string-matching `error.message`.
+ * deployed in config but no `pythApiKey` was supplied at client init — the
+ * Lazer HTTP API requires a Bearer token and the SDK never reads
+ * `process.env` to find one. `instanceof`-able (mirrors
+ * `OracleFeeSourceUnavailableError` in `pyth.ts`) so a consumer can branch on
+ * the failure type directly instead of string-matching `error.message`.
  */
 export declare class LazerApiKeyMissingError extends Error {
     constructor();

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

@@ -3,14 +3,14 @@
  * updates, plus `feedLazerRule`, the collector-feed leg `aggregateTicker`
  * appends per lazer-routed ticker. Fetches one `leEcdsa` payload for all
  * requested integer feed ids from the Lazer HTTP API (Bearer-authenticated
- * via `config.pyth.api_key`), verifies it ONCE on-chain via
+ * 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.
  */
 import { fromHex } from "@mysten/bcs";
 import { LAZER_DEFAULTS } from "../config.js";
 import { assertRuleUpdateData, } from "../price-update-rule.js";
-import { FetchPolicyError, fetchWithPolicy } from "../update-fetch.js";
+import { fetchWithPolicy, joinEndpointPath, rethrowExhaustedFetch } from "../update-fetch.js";
 /**
  * Signed-update request pins, mirroring what the on-chain rule consumes:
  * - `properties` — `price` + `exponent` are REQUIRED by
@@ -18,10 +18,17 @@ import { FetchPolicyError, fetchWithPolicy } from "../update-fetch.js";
  *   `confidence` is optional on-chain but requested so the rule's
  *   fail-closed confidence gate actually engages (a payload without
  *   confidence passes the gate unchecked).
- * - `channel` — `real_time`: the deployed rule binds the v1 Lazer API, whose
- *   `channel::from_u8` aborts on the 1000ms fixed-rate channel; real_time /
- *   50ms / 200ms are the safe subscriptions, and for an on-demand pull
- *   real_time is the freshest.
+ * - `channel` — `fixed_rate@200ms`, NOT `real_time`: Lazer rejects a request
+ *   whose channel is faster than ANY requested feed's `min_channel`, and it
+ *   rejects the WHOLE batch (`400 Feeds do not support channel …`). Only the
+ *   majors (BTC/ETH/SOL/USDC/DOGE/XRP/BNB/HYPE + EUR/JPY FX) publish
+ *   `real_time`; the other 19 of the 29 configured feeds — including SUIUSD
+ *   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).
  * - `formats: leEcdsa` + `jsonBinaryEncoding: hex` — the Sui verifier takes
  *   the `leEcdsa` framing; hex matches `fromHex` below.
  */
@@ -29,7 +36,7 @@ const LAZER_LATEST_PRICE_REQUEST = {
     properties: ["price", "exponent", "confidence"],
     formats: ["leEcdsa"],
     jsonBinaryEncoding: "hex",
-    channel: "real_time",
+    channel: "fixed_rate@200ms",
 };
 /**
  * Shape check ONLY — the `kind` discriminant is checked separately by the
@@ -44,16 +51,16 @@ function isPythLazerUpdatePayloadShape(payload) {
 }
 /**
  * Thrown by {@link PythLazerRule.fetchUpdateData} when `pyth_lazer_rule` is
- * deployed in config but no `pyth.api_key` is set — the Lazer HTTP API
- * requires a Bearer token and the SDK never reads `process.env` to find one.
- * `instanceof`-able (mirrors `OracleFeeSourceUnavailableError` in `pyth.ts`)
- * so a consumer can branch on the failure type directly instead of
- * string-matching `error.message`.
+ * deployed in config but no `pythApiKey` was supplied at client init — the
+ * Lazer HTTP API requires a Bearer token and the SDK never reads
+ * `process.env` to find one. `instanceof`-able (mirrors
+ * `OracleFeeSourceUnavailableError` in `pyth.ts`) so a consumer can branch on
+ * the failure type directly instead of string-matching `error.message`.
  */
 export class LazerApiKeyMissingError extends Error {
     constructor() {
         super("LazerApiKeyMissing: pyth_lazer_rule requires a Pyth Lazer access token — " +
-            "set `pyth.api_key` in the client config (the SDK never reads process.env)");
+            "pass `pythApiKey` when creating the client (the SDK never reads process.env)");
         this.name = "LazerApiKeyMissingError";
     }
 }
@@ -72,7 +79,11 @@ function requireLazerPackage(host) {
  * both oracle sources fail the same way under upstream degradation.
  */
 async function fetchLazerSignedUpdate(endpoint, apiKey, feedIds, fetchOpts) {
-    const url = new URL("/v1/latest_price", endpoint);
+    // 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
+    // Lazer endpoint has no base path, but a config override may.
+    const url = joinEndpointPath(endpoint, "v1/latest_price");
     let res;
     try {
         res = await fetchWithPolicy(url.toString(), {
@@ -82,15 +93,7 @@ async function fetchLazerSignedUpdate(endpoint, apiKey, feedIds, fetchOpts) {
         }, { apiKey, ...fetchOpts });
     }
     catch (err) {
-        // Mirrors fetchPriceFeedsUpdateData's reframing: a retryable status that
-        // never recovered carries `status` on the FetchPolicyError — reformat
-        // into this function's own message shape; a network-level exhaustion
-        // (no status) propagates as-is.
-        if (err instanceof FetchPolicyError && err.status !== undefined) {
-            const body = err.bodySnippet ? ` ${err.bodySnippet}` : "";
-            throw new Error(`Lazer price fetch failed: ${err.status}${body} (retries exhausted after ${err.attempts} attempts)`, { cause: err });
-        }
-        throw err;
+        rethrowExhaustedFetch(err, (e) => `Lazer price fetch failed: ${e.status}${e.bodySnippet ? ` ${e.bodySnippet}` : ""}`);
     }
     if (!res.ok)
         throw new Error(`Lazer price fetch failed: ${res.status} ${await res.text()}`);

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

@@ -13,6 +13,11 @@ export function feedPythRule(tx, host, collector, priceInfoObjectId) {
         arguments: {
             collector,
             config: tx.object(host.config.packages.pyth_rule.config),
+            // The deployed pyth_rule package is compiled against the Core pyth
+            // dependency, so its `&PythState` parameter is the Core-package-qualified
+            // type and `host.pyth` (the fixed per-network Core infra) is always the
+            // right state to pass. The config's price_info_object entries are Core
+            // objects to match.
             pythState: tx.object(host.pyth.state_id),
             pythPriceInfo: tx.object(priceInfoObjectId),
         },

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

@@ -0,0 +1,89 @@
+/**
+ * `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 `WATERX_DEFAULTS`), 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.
+ *
+ * `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 / replayed timestamp ABSTAINS (the other weighted rules
+ * cover); a config/integrity mismatch or bad signature aborts.
+ */
+import type { Transaction, TransactionArgument } from "@mysten/sui/transactions";
+import type { OracleHost } from "../host.ts";
+import { type PriceUpdateRule, type RuleUpdateData } from "../price-update-rule.ts";
+/**
+ * One item inside a signed batch payload, mirroring the quote-center
+ * `/v1/quotes/update` JSON 1:1 (snake_case). The u64 integer fields are the
+ * EXACT values the enclave signed over BCS — `collect_batch_latest` rebuilds
+ * the payload on-chain and re-verifies, so they must round-trip byte-for-byte.
+ * They are `bigint` (not `number`): {@link parseSignedEnvelope} decodes them
+ * from the raw JSON integer literals so a value above `Number.MAX_SAFE_INTEGER`
+ * (2^53) can never lose precision and silently abort the on-chain signature
+ * check. `num_sources` is a `u8` (≤ 255) and stays a `number`.
+ */
+export interface WaterxBatchItem {
+    symbol: string;
+    ticker: string;
+    sources: bigint[];
+    method: string;
+    price_timestamp_ms: bigint;
+    price_n: bigint;
+    price_scale: bigint;
+    confidence_n: bigint;
+    confidence_scale: bigint;
+    max_source_deviation_bps: bigint;
+    num_sources: number;
+}
+/** The enclave-signed batch envelope from `GET /v1/quotes/update`. */
+export interface WaterxSignedEnvelope {
+    intent: number;
+    /** Enclave signing timestamp (ms) — the on-chain `timestamp_ms` argument. */
+    timestamp_ms: bigint;
+    payload: {
+        items: WaterxBatchItem[];
+    };
+    /** ed25519 signature over `BCS(IntentMessage<BatchPricePayload>)`, hex (± `0x`). */
+    signature: string;
+}
+/** `waterx_rule`'s narrowed `RuleUpdateData.payload` shape. */
+export interface WaterxUpdatePayload {
+    readonly envelope: WaterxSignedEnvelope;
+}
+/**
+ * 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.
+ */
+export declare function parseSignedEnvelope(text: string): WaterxSignedEnvelope;
+/** Narrow a `RuleUpdateData` to its `WaterxSignedEnvelope`, or `null`. */
+export declare function waterxEnvelopeOf(data: RuleUpdateData): WaterxSignedEnvelope | null;
+/**
+ * `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`) instead of aborting when the symbol is stale,
+ * absent from the batch, or its timestamp was already accepted (replay).
+ */
+export declare function feedWaterxRule(tx: Transaction, host: OracleHost, collector: TransactionArgument, envelope: WaterxSignedEnvelope): void;
+export declare const WaterxRule: PriceUpdateRule;

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

@@ -0,0 +1,266 @@
+/**
+ * `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 `WATERX_DEFAULTS`), 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.
+ *
+ * `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 / replayed timestamp ABSTAINS (the other weighted rules
+ * cover); a config/integrity mismatch or bad signature aborts.
+ */
+import { fromHex } from "@mysten/bcs";
+import { collectBatchLatest, newBatchItem, newBatchPayload, pushBatchItem, } from "../../generated/waterx_rule/waterx_rule.js";
+import { WATERX_DEFAULTS } from "../config.js";
+import { assertRuleUpdateData, } from "../price-update-rule.js";
+import { FetchPolicyError, fetchWithPolicy, joinEndpointPath, } from "../update-fetch.js";
+/** The single signing intent (`BATCH_PRICE_INTENT`) the quote-center emits. */
+const BATCH_PRICE_INTENT = 1;
+/**
+ * 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.
+ */
+function isWaterxUpdatePayloadShape(payload) {
+    const env = payload?.envelope;
+    return (typeof env === "object" &&
+        env !== null &&
+        typeof env.signature === "string" &&
+        typeof env.timestamp_ms === "bigint" &&
+        Array.isArray(env.payload?.items));
+}
+/**
+ * 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.
+ */
+export function parseSignedEnvelope(text) {
+    const raw = JSON.parse(text, (_key, value, context) => {
+        if (typeof value !== "number" || !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 " +
+                "source access — cannot preserve u64 precision for the signed payload");
+        }
+        return BigInt(value);
+    });
+    if (typeof raw.signature !== "string" || !Array.isArray(raw.payload?.items)) {
+        throw new Error("WaterX quote-center returned a malformed signed envelope");
+    }
+    return {
+        intent: Number(raw.intent),
+        timestamp_ms: (raw.timestamp_ms ?? 0n),
+        signature: raw.signature,
+        payload: {
+            items: raw.payload.items.map((i) => ({ ...i, num_sources: Number(i.num_sources) })),
+        },
+    };
+}
+/** The `waterx_rule` deployment entry; throws when the config carries none. */
+function requireWaterxPackage(host) {
+    const entry = host.config.packages.waterx_rule;
+    if (!entry) {
+        throw new Error("waterx_rule package is not deployed in this config");
+    }
+    return entry;
+}
+/**
+ * Resolve the quote-center infra for this host: the `waterxEndpoint` /
+ * `waterxFetch` create options when the client carries them, else the network
+ * default. The fetch policy falls back to the shared `pyth.fetch` policy so a
+ * consumer that already tuned timeouts/retries once keeps them here.
+ *
+ * This is the seam a browser consumer needs: the envelope is fetched FROM THE
+ * PAGE, so a front end whose origin the quote-center does not allow (CORS)
+ * points `endpoint` at a same-origin proxy, or supplies its own `fetchImpl`.
+ */
+function resolveWaterxInfra(host) {
+    const infra = host.waterx ?? WATERX_DEFAULTS[host.network];
+    return { endpoint: infra.endpoint, fetch: infra.fetch ?? host.pyth.fetch };
+}
+/**
+ * Pull one enclave-signed batch envelope covering `symbols` from the
+ * quote-center. Goes through the shared `fetchWithPolicy` (`../update-fetch.ts`)
+ * — same retry/timeout policy as the Pyth/Lazer fetches. No auth: the
+ * quote-center read surface is public.
+ *
+ * The URL is built with `joinEndpointPath`, not `new URL(path, endpoint)`: a
+ * leading-slash path is ABSOLUTE and silently drops the endpoint's own base
+ * path, which is exactly what a `waterxEndpoint` proxy route is (a
+ * `https://app.example/api/quote-center` override would have been rewritten to
+ * `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 = joinEndpointPath(endpoint, "v1/quotes/update");
+    url.searchParams.set("symbols", symbols.join(","));
+    let res;
+    try {
+        res = await fetchWithPolicy(url.toString(), { method: "GET" }, { ...fetchOpts });
+    }
+    catch (err) {
+        if (err instanceof 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 err;
+    }
+    if (!res.ok) {
+        throw new Error(`WaterX quote-center fetch failed: ${res.status} ${await res.text()}`);
+    }
+    // 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 !== BATCH_PRICE_INTENT) {
+        throw new Error(`WaterX quote-center returned intent ${envelope.intent}, expected BATCH_PRICE_INTENT ${BATCH_PRICE_INTENT}`);
+    }
+    return envelope;
+}
+/** Narrow a `RuleUpdateData` to its `WaterxSignedEnvelope`, or `null`. */
+export function waterxEnvelopeOf(data) {
+    const payload = assertRuleUpdateData(data, "waterx_rule", isWaterxUpdatePayloadShape, "{ envelope: { intent, timestamp_ms, payload: { items }, signature } }");
+    return payload?.envelope ?? null;
+}
+/** Strip an optional `0x` prefix, then decode hex → bytes. */
+function decodeSig(hex) {
+    return fromHex(hex.startsWith("0x") ? hex.slice(2) : hex);
+}
+/**
+ * `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`) instead of aborting when the symbol is stale,
+ * absent from the batch, or its timestamp was already accepted (replay).
+ */
+export function feedWaterxRule(tx, host, collector, envelope) {
+    const wr = requireWaterxPackage(host);
+    const pkg = wr.published_at;
+    const payload = 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 = 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);
+        pushBatchItem({ package: pkg, arguments: { payload, item: itemArg } })(tx);
+    }
+    collectBatchLatest({
+        package: pkg,
+        arguments: {
+            collector,
+            config: tx.object(wr.config),
+            enclaveConfig: tx.object(wr.enclave_config),
+            enclave: tx.object(wr.enclave),
+            timestampMs: envelope.timestamp_ms,
+            payload,
+            sig: Array.from(decodeSig(envelope.signature)),
+        },
+    })(tx);
+}
+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,
+    /** 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.
+     */
+    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) {
+            if (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 } };
+    },
+    /**
+     * 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
+     * silent partial.
+     */
+    narrowUpdateData(_host, data, tickers) {
+        const envelope = waterxEnvelopeOf(data);
+        if (!envelope || tickers.length === 0)
+            return null;
+        const covered = new Set(envelope.payload.items.map((i) => i.symbol));
+        for (const ticker of tickers) {
+            if (!covered.has(ticker))
+                return null;
+        }
+        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`.
+     */
+    buildUpdateCalls(_tx, _host, _data, _opts) {
+        return;
+    },
+};

package/dist/src/oracle/update-fetch.d.ts

@@ -16,7 +16,11 @@
  *   `Authorization` header at all). This is the Phase-0 invariant of the
  *   Pyth Pro migration: existing keyless deployments see no behavior change.
  * - Retries on network errors, HTTP 429, and HTTP 5xx, with exponential
- *   backoff (`retryDelayMs * 2^attempt`, capped at `MAX_BACKOFF_MS`). Other
+ *   backoff (`retryDelayMs * 2^attempt`, capped at `MAX_BACKOFF_MS`). A 429
+ *   carrying a numeric `Retry-After` header uses the SERVER'S delay instead,
+ *   when it fits under the same cap — a longer ask degrades to normal
+ *   backoff rather than stalling a money-path build for tens of seconds.
+ *   Other
  *   4xx statuses (401/400/403/404/…) are NOT retried — auth/bad-request
  *   failures are deterministic, so that `Response` (`ok: false`) is handed
  *   back on the first attempt for the caller to format its own
@@ -46,7 +50,7 @@
  * - Retry worst case: with the defaults (15s timeout × 3 attempts + ~0.75s of
  *   backoff between them) a FULL outage takes up to ~46s to surface as a
  *   `FetchPolicyError`, vs ~15s pre-3.2.0's single bare-`fetch` attempt.
- *   Tunable per client via `config.pyth.fetch.{timeoutMs,retries}`.
+ *   Tunable per client via the `pythFetch` create option (`{timeoutMs,retries}`).
  */
 export interface FetchPolicy {
     /** Per-attempt timeout (ms). Default 15_000. */
@@ -75,6 +79,32 @@ export declare class FetchPolicyError extends Error {
         attempts: number;
     });
 }
+/**
+ * Rethrow a `catch`-ed {@link fetchWithPolicy} failure. When it is a
+ * status-carrying `FetchPolicyError` — a retryable status (429/5xx) that never
+ * recovered — throw a new Error `${describe(err)} (retries exhausted after N
+ * attempts)` with the original as `cause`; otherwise (a network-level
+ * exhaustion with no status, or any non-`FetchPolicyError`) rethrow it verbatim,
+ * since there is no domain reframing to add. `describe` builds the
+ * status-bearing prefix so each caller keeps its own message shape (the e2e
+ * transient detector keys off those prefixes) while the guard, the `retries
+ * exhausted` suffix, and the `cause` wrapping live in one place. `: never` so a
+ * caller's `catch` block is understood not to fall through.
+ */
+export declare function rethrowExhaustedFetch(err: unknown, describe: (err: FetchPolicyError) => string): never;
+/**
+ * Join an API `path` onto an `endpoint` PRESERVING the endpoint's own base
+ * path. `new URL(path, endpoint)` is the footgun this replaces: a
+ * leading-slash path is *absolute* and silently discards the endpoint's path
+ * — harmless for a bare-origin endpoint (`https://hermes.pyth.network`) but
+ * it dropped the `/hermes` prefix of the Pyth Pro compat endpoint and 404'd
+ * every feed (see `fetchPriceFeedsUpdateData`). Every oracle fetch that
+ * targets `<endpoint><fixed path>` must build its URL here.
+ */
+/** One canonical trailing-slash trim — `joinEndpointPath` (URL building) and
+ * `pyth.ts`'s `memoKey` (endpoint identity) must never drift apart on it. */
+export declare function trimTrailingSlashes(endpoint: string): string;
+export declare function joinEndpointPath(endpoint: string, path: string): URL;
 /**
  * `fetch` with per-attempt timeout, bounded retry + backoff, and optional
  * Bearer auth. See the module header for the full policy. Both `init.signal`

package/dist/src/oracle/update-fetch.js

@@ -16,7 +16,11 @@
  *   `Authorization` header at all). This is the Phase-0 invariant of the
  *   Pyth Pro migration: existing keyless deployments see no behavior change.
  * - Retries on network errors, HTTP 429, and HTTP 5xx, with exponential
- *   backoff (`retryDelayMs * 2^attempt`, capped at `MAX_BACKOFF_MS`). Other
+ *   backoff (`retryDelayMs * 2^attempt`, capped at `MAX_BACKOFF_MS`). A 429
+ *   carrying a numeric `Retry-After` header uses the SERVER'S delay instead,
+ *   when it fits under the same cap — a longer ask degrades to normal
+ *   backoff rather than stalling a money-path build for tens of seconds.
+ *   Other
  *   4xx statuses (401/400/403/404/…) are NOT retried — auth/bad-request
  *   failures are deterministic, so that `Response` (`ok: false`) is handed
  *   back on the first attempt for the caller to format its own
@@ -46,7 +50,7 @@
  * - Retry worst case: with the defaults (15s timeout × 3 attempts + ~0.75s of
  *   backoff between them) a FULL outage takes up to ~46s to surface as a
  *   `FetchPolicyError`, vs ~15s pre-3.2.0's single bare-`fetch` attempt.
- *   Tunable per client via `config.pyth.fetch.{timeoutMs,retries}`.
+ *   Tunable per client via the `pythFetch` create option (`{timeoutMs,retries}`).
  */
 const DEFAULT_TIMEOUT_MS = 15_000;
 const DEFAULT_RETRIES = 2;
@@ -70,12 +74,60 @@ export class FetchPolicyError extends Error {
         this.attempts = opts.attempts;
     }
 }
+/**
+ * Rethrow a `catch`-ed {@link fetchWithPolicy} failure. When it is a
+ * status-carrying `FetchPolicyError` — a retryable status (429/5xx) that never
+ * recovered — throw a new Error `${describe(err)} (retries exhausted after N
+ * attempts)` with the original as `cause`; otherwise (a network-level
+ * exhaustion with no status, or any non-`FetchPolicyError`) rethrow it verbatim,
+ * since there is no domain reframing to add. `describe` builds the
+ * status-bearing prefix so each caller keeps its own message shape (the e2e
+ * transient detector keys off those prefixes) while the guard, the `retries
+ * exhausted` suffix, and the `cause` wrapping live in one place. `: never` so a
+ * caller's `catch` block is understood not to fall through.
+ */
+export function rethrowExhaustedFetch(err, describe) {
+    if (err instanceof FetchPolicyError && err.status !== undefined) {
+        throw new Error(`${describe(err)} (retries exhausted after ${err.attempts} attempts)`, {
+            cause: err,
+        });
+    }
+    throw err;
+}
+/**
+ * Join an API `path` onto an `endpoint` PRESERVING the endpoint's own base
+ * path. `new URL(path, endpoint)` is the footgun this replaces: a
+ * leading-slash path is *absolute* and silently discards the endpoint's path
+ * — harmless for a bare-origin endpoint (`https://hermes.pyth.network`) but
+ * it dropped the `/hermes` prefix of the Pyth Pro compat endpoint and 404'd
+ * every feed (see `fetchPriceFeedsUpdateData`). Every oracle fetch that
+ * targets `<endpoint><fixed path>` must build its URL here.
+ */
+/** One canonical trailing-slash trim — `joinEndpointPath` (URL building) and
+ * `pyth.ts`'s `memoKey` (endpoint identity) must never drift apart on it. */
+export function trimTrailingSlashes(endpoint) {
+    return endpoint.replace(/\/+$/, "");
+}
+export function joinEndpointPath(endpoint, path) {
+    return new URL(`${trimTrailingSlashes(endpoint)}/${path.replace(/^\/+/, "")}`);
+}
 function isRetryableStatus(status) {
     return status === 429 || status >= 500;
 }
 function backoffMs(retryDelayMs, attempt) {
     return Math.min(retryDelayMs * 2 ** attempt, MAX_BACKOFF_MS);
 }
+/**
+ * The server's own `Retry-After` (numeric-seconds form only), when present
+ * and within `MAX_BACKOFF_MS` — `undefined` otherwise (absent, HTTP-date
+ * form, zero/garbage, or an ask too long to honor inside a build path).
+ */
+function retryAfterMs(response) {
+    // Optional-chained: minimal test doubles (and some fetch shims) carry no
+    // `headers` — a missing header must read as "no hint", never throw.
+    const ms = Number(response.headers?.get?.("retry-after")) * 1_000;
+    return ms > 0 && ms <= MAX_BACKOFF_MS ? ms : undefined;
+}
 /** `host + pathname` only — never the query string (feed ids are noise, not diagnostic). */
 function describeTarget(url) {
     const parsed = new URL(url);
@@ -182,11 +234,13 @@ export async function fetchWithPolicy(url, init = {}, policy = {}, externalSigna
         let status;
         let bodySnippet;
         let cause;
+        let serverRetryDelay;
         try {
             const response = await doFetch(url, { ...init, headers, signal });
             if (response.ok || !isRetryableStatus(response.status))
                 return response;
             status = response.status;
+            serverRetryDelay = retryAfterMs(response);
             if (attempt === retries) {
                 bodySnippet = await readBodySnippet(response);
             }
@@ -213,7 +267,7 @@ export async function fetchWithPolicy(url, init = {}, policy = {}, externalSigna
             const detail = statusDetail ?? causeMessage(cause);
             throw new FetchPolicyError(`fetchWithPolicy: ${describeTarget(url)} failed after ${attempt + 1} attempt(s) — ${detail}`, { status, bodySnippet, cause, attempts: attempt + 1 });
         }
-        await sleep(backoffMs(retryDelayMs, attempt), combinedExternalSignal);
+        await sleep(serverRetryDelay ?? backoffMs(retryDelayMs, attempt), combinedExternalSignal);
     }
     // Unreachable: the loop above always returns or throws on its final
     // (attempt === retries) iteration — this satisfies the compiler only.