@waterx/sdk 3.1.1 → 4.0.1

package/dist/cjs/src/oracle/rule-registry.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `rule-registry.ts` — maps a client-selected `OracleSource` to its concrete
+ * `PriceUpdateRule` implementation. `refreshOraclePrices` (`aggregate.ts`) is
+ * the only production caller; this is the one place `OracleSource` values are
+ * wired to a rule instance. Selection is driven purely by the value passed in
+ * (ultimately `OracleHost.oracleSource`, the `oracleSource` client create
+ * option) — never by a config JSON `enabled` flag and never by `process.env`.
+ *
+ * Each source is self-contained: it owns its own infra + config and does NOT
+ * back-stop any other source. Both are registered: `pyth_rule` (`PythCoreRule`,
+ * Hermes VAA) and `pyth_lazer_rule` (`PythLazerRule`, Lazer signed updates).
+ * Resolving a source with no registered rule throws a clear
+ * `OracleSourceNotImplemented` error. There is deliberately no cross-source
+ * fallback and no client-creation config guard: selecting a source whose feeds
+ * are absent is not an error at init — it surfaces at tx-build time for the
+ * specific tickers that source can't serve (see `refreshOraclePrices`).
+ */
+import type { OracleSource, PriceUpdateRule } from "./price-update-rule.ts";
+/**
+ * Thrown by {@link resolveOracleRule} when `source` has no `PriceUpdateRule`
+ * registered in either the production registry or a test's `overrides` map.
+ * `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 OracleSourceNotImplementedError extends Error {
+    /** The unregistered `OracleSource` that was requested. */
+    readonly source: OracleSource;
+    constructor(source: OracleSource);
+}
+/**
+ * Resolve the `PriceUpdateRule` registered for `source`.
+ *
+ * `overrides` — test-only — layers on top of the production registry so a
+ * spec can inject a fake rule (e.g. a stub `pyth_lazer_rule`) without
+ * touching {@link DEFAULT_RULES}; production callers never pass it.
+ *
+ * Throws {@link OracleSourceNotImplementedError} (`OracleSourceNotImplemented:
+ * <source>`) when nothing is registered for `source` in either map.
+ */
+export declare function resolveOracleRule(source: OracleSource, overrides?: Partial<Record<OracleSource, PriceUpdateRule>>): PriceUpdateRule;

package/dist/cjs/src/oracle/rule-registry.js

@@ -0,0 +1,65 @@
+"use strict";
+/**
+ * `rule-registry.ts` — maps a client-selected `OracleSource` to its concrete
+ * `PriceUpdateRule` implementation. `refreshOraclePrices` (`aggregate.ts`) is
+ * the only production caller; this is the one place `OracleSource` values are
+ * wired to a rule instance. Selection is driven purely by the value passed in
+ * (ultimately `OracleHost.oracleSource`, the `oracleSource` client create
+ * option) — never by a config JSON `enabled` flag and never by `process.env`.
+ *
+ * Each source is self-contained: it owns its own infra + config and does NOT
+ * back-stop any other source. Both are registered: `pyth_rule` (`PythCoreRule`,
+ * Hermes VAA) and `pyth_lazer_rule` (`PythLazerRule`, Lazer signed updates).
+ * Resolving a source with no registered rule throws a clear
+ * `OracleSourceNotImplemented` error. There is deliberately no cross-source
+ * fallback and no client-creation config guard: selecting a source whose feeds
+ * are absent is not an error at init — it surfaces at tx-build time for the
+ * specific tickers that source can't serve (see `refreshOraclePrices`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OracleSourceNotImplementedError = void 0;
+exports.resolveOracleRule = resolveOracleRule;
+const pyth_core_rule_ts_1 = require("./rules/pyth-core-rule.js");
+const pyth_lazer_rule_ts_1 = require("./rules/pyth-lazer-rule.js");
+/**
+ * Production registry. Frozen — tests inject a fake rule via
+ * `resolveOracleRule`'s `overrides` param instead of mutating this.
+ */
+const DEFAULT_RULES = Object.freeze({
+    pyth_rule: pyth_core_rule_ts_1.PythCoreRule,
+    pyth_lazer_rule: pyth_lazer_rule_ts_1.PythLazerRule,
+});
+/**
+ * Thrown by {@link resolveOracleRule} when `source` has no `PriceUpdateRule`
+ * registered in either the production registry or a test's `overrides` map.
+ * `instanceof`-able (mirrors `OracleFeeSourceUnavailableError` in `pyth.ts`)
+ * so a consumer can branch on the failure type directly instead of
+ * string-matching `error.message`.
+ */
+class OracleSourceNotImplementedError extends Error {
+    /** The unregistered `OracleSource` that was requested. */
+    source;
+    constructor(source) {
+        super(`OracleSourceNotImplemented: ${source}`);
+        this.name = "OracleSourceNotImplementedError";
+        this.source = source;
+    }
+}
+exports.OracleSourceNotImplementedError = OracleSourceNotImplementedError;
+/**
+ * Resolve the `PriceUpdateRule` registered for `source`.
+ *
+ * `overrides` — test-only — layers on top of the production registry so a
+ * spec can inject a fake rule (e.g. a stub `pyth_lazer_rule`) without
+ * touching {@link DEFAULT_RULES}; production callers never pass it.
+ *
+ * Throws {@link OracleSourceNotImplementedError} (`OracleSourceNotImplemented:
+ * <source>`) when nothing is registered for `source` in either map.
+ */
+function resolveOracleRule(source, overrides) {
+    const rule = overrides?.[source] ?? DEFAULT_RULES[source];
+    if (!rule) {
+        throw new OracleSourceNotImplementedError(source);
+    }
+    return rule;
+}

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

@@ -0,0 +1,15 @@
+/**
+ * `PythCoreRule` — `PriceUpdateRule` wrapper around the existing Pyth Core
+ * (Hermes VAA) source in `../pyth.ts`. Delegates to `fetchPriceFeedsUpdateData`
+ * / `buildPythPriceUpdateCalls` verbatim; this file only adapts them to the
+ * `PriceUpdateRule` port shape (fetch → build) so a future router can select
+ * across rules by `kind`. Mechanical wrap only — no on-chain/off-chain logic
+ * changes vs `../pyth.ts` / `./pyth-rule.ts`.
+ */
+import { type PriceUpdateRule } from "../price-update-rule.ts";
+/** `pyth_rule`'s narrowed `RuleUpdateData.payload` shape. */
+export interface PythCoreUpdatePayload {
+    readonly updates: Uint8Array[];
+    readonly feedIds: string[];
+}
+export declare const PythCoreRule: PriceUpdateRule;

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

@@ -0,0 +1,99 @@
+"use strict";
+/**
+ * `PythCoreRule` — `PriceUpdateRule` wrapper around the existing Pyth Core
+ * (Hermes VAA) source in `../pyth.ts`. Delegates to `fetchPriceFeedsUpdateData`
+ * / `buildPythPriceUpdateCalls` verbatim; this file only adapts them to the
+ * `PriceUpdateRule` port shape (fetch → build) so a future router can select
+ * across rules by `kind`. Mechanical wrap only — no on-chain/off-chain logic
+ * changes vs `../pyth.ts` / `./pyth-rule.ts`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PythCoreRule = void 0;
+const price_update_rule_ts_1 = require("../price-update-rule.js");
+const pyth_ts_1 = require("../pyth.js");
+/**
+ * Shape check ONLY — the `kind` discriminant is checked separately by the
+ * caller before this runs, since a same-shaped payload from a different rule
+ * (e.g. a hypothetical Lazer payload also carrying `updates`/`feedIds`) must
+ * not silently pass as a Pyth Core VAA block.
+ */
+function isPythCoreUpdatePayloadShape(payload) {
+    return (typeof payload === "object" &&
+        payload !== null &&
+        Array.isArray(payload.updates) &&
+        Array.isArray(payload.feedIds));
+}
+exports.PythCoreRule = {
+    kind: "pyth_rule",
+    // Charges a per-feed `base_update_fee` via `pyth::update_single_price_feed` —
+    // see `PriceUpdateRule.requiresFeeSource`.
+    requiresFeeSource: true,
+    /** Tickers with a `pyth_rule.feeds` entry (mirrors `refreshOraclePrices`'s filter). */
+    supportedTickers(host) {
+        return Object.keys(host.config.packages.pyth_rule?.feeds ?? {});
+    },
+    /** Resolves feed ids for `tickers`, then fetches their Hermes accumulator update. */
+    async fetchUpdateData(host, tickers) {
+        if (tickers.length === 0)
+            return null;
+        // `host.pyth` is this source's own infra — the fixed per-network Core
+        // Pyth block plus the caller's api_key/fetch. Endpoint, credential and
+        // retry/timeout policy all come from it.
+        const endpoint = host.pyth.hermes_endpoint;
+        const feedIds = tickers.map((ticker) => host.getPythFeed(ticker).feed_id);
+        const updates = await (0, pyth_ts_1.fetchPriceFeedsUpdateData)(endpoint, feedIds, {
+            apiKey: host.pyth.api_key,
+            fetch: host.pyth.fetch,
+        });
+        // `updates` covers only the feeds this endpoint actually served — the fetch
+        // drops (and memoizes) any it lacks, e.g. Core feeds absent from Pyth Pro
+        // (WTIUSD/BRENTUSD). Align `feedIds` with them: buildPythPriceUpdateCalls
+        // emits one moveCall per feedId and must not reference a feed the
+        // accumulator blob doesn't cover.
+        return {
+            kind: "pyth_rule",
+            payload: {
+                updates,
+                feedIds: (0, pyth_ts_1.endpointSupportedFeedIds)(endpoint, feedIds, host.pyth.api_key),
+            },
+        };
+    },
+    /**
+     * Subsets a (typically whole-universe) payload from {@link fetchUpdateData}
+     * down to exactly `tickers`. Pyth Core charges a per-feed update fee (one
+     * `update_single_price_feed` moveCall per `feedIds` entry — see
+     * `buildPythPriceUpdateCalls`), so serving a full all-registry payload for a
+     * 2-ticker build would multiply both the fee and the PTB size ~N× — a
+     * per-feed subset is valid input by construction. Narrows `feedIds` only:
+     * the single combined Hermes accumulator blob in `updates` already covers
+     * every packed feed and needs no re-slicing. A ticker with no
+     * `pyth_rule.feeds` entry, or whose feed id is not packed in THIS payload's
+     * `feedIds`, is a coverage gap → `null` (miss), never a silent partial.
+     */
+    narrowUpdateData(host, data, tickers) {
+        const payload = (0, price_update_rule_ts_1.assertRuleUpdateData)(data, "pyth_rule", isPythCoreUpdatePayloadShape, "{ updates: Uint8Array[]; feedIds: string[] }");
+        if (!payload || tickers.length === 0)
+            return null;
+        const packedFeedIds = new Set(payload.feedIds);
+        const feedIds = [];
+        for (const ticker of tickers) {
+            // Same lookup as `host.getPythFeed(ticker)` minus its throw — an
+            // unlisted ticker is a miss here, not an error.
+            const feedId = host.config.packages.pyth_rule?.feeds?.[ticker]?.feed_id;
+            if (feedId === undefined || !packedFeedIds.has(feedId))
+                return null;
+            feedIds.push(feedId);
+        }
+        return { kind: "pyth_rule", payload: { updates: payload.updates, feedIds } };
+    },
+    /** Appends the wormhole/pyth update PTB block for the payload from {@link fetchUpdateData}. */
+    async buildUpdateCalls(tx, host, data, opts) {
+        const payload = (0, price_update_rule_ts_1.assertRuleUpdateData)(data, "pyth_rule", isPythCoreUpdatePayloadShape, "{ updates: Uint8Array[]; feedIds: string[] }");
+        if (!payload)
+            return;
+        await (0, pyth_ts_1.buildPythPriceUpdateCalls)(tx, host, payload.updates, payload.feedIds, {
+            cache: opts?.cache,
+            feeSource: opts?.feeSource,
+        });
+    },
+};

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

@@ -0,0 +1,41 @@
+/**
+ * `PythLazerRule` — `PriceUpdateRule` for Pyth Lazer (Pyth Pro) signed
+ * 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 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 type { Transaction, TransactionArgument } from "@mysten/sui/transactions";
+import type { OracleHost } from "../host.ts";
+import { type PriceUpdateRule } from "../price-update-rule.ts";
+/** `pyth_lazer_rule`'s narrowed `RuleUpdateData.payload` shape. */
+export interface PythLazerUpdatePayload {
+    /** One signed `leEcdsa` message carrying every requested feed. */
+    readonly update: Uint8Array;
+    /** Integer Lazer feed ids the update was requested for (debug/audit trail). */
+    readonly feedIds: number[];
+}
+/**
+ * Thrown by {@link PythLazerRule.fetchUpdateData} when `pyth_lazer_rule` is
+ * 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();
+}
+/**
+ * `pyth_lazer_rule::feed(collector, config, clock, &update)` — contribute the
+ * verified Lazer price for `collector.symbol()` to the collector. `update` is
+ * the `RuleUpdateHandle` value from {@link PythLazerRule.buildUpdateCalls} in
+ * the SAME PTB; one verified update serves every ticker's feed call. On-chain
+ * the rule abstains (records `none`) instead of aborting when the symbol is
+ * unconfigured, the feed is absent from the update, the value is degenerate,
+ * or the Lazer timestamp is stale.
+ */
+export declare function feedLazerRule(tx: Transaction, host: OracleHost, collector: TransactionArgument, update: TransactionArgument): void;
+export declare const PythLazerRule: PriceUpdateRule;

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

@@ -0,0 +1,197 @@
+"use strict";
+/**
+ * `PythLazerRule` — `PriceUpdateRule` for Pyth Lazer (Pyth Pro) signed
+ * 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 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PythLazerRule = exports.LazerApiKeyMissingError = void 0;
+exports.feedLazerRule = feedLazerRule;
+const bcs_1 = require("@mysten/bcs");
+const config_ts_1 = require("../config.js");
+const price_update_rule_ts_1 = require("../price-update-rule.js");
+const update_fetch_ts_1 = require("../update-fetch.js");
+/**
+ * Signed-update request pins, mirroring what the on-chain rule consumes:
+ * - `properties` — `price` + `exponent` are REQUIRED by
+ *   `pyth_lazer_rule::price_or_abstain` (a missing exponent abstains);
+ *   `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` — `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.
+ */
+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
+ * caller before this runs (mirrors `PythCoreRule`'s guard split), so a
+ * same-shaped payload from a different rule can never silently pass.
+ */
+function isPythLazerUpdatePayloadShape(payload) {
+    return (typeof payload === "object" &&
+        payload !== null &&
+        payload.update instanceof Uint8Array &&
+        Array.isArray(payload.feedIds));
+}
+/**
+ * Thrown by {@link PythLazerRule.fetchUpdateData} when `pyth_lazer_rule` is
+ * 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`.
+ */
+class LazerApiKeyMissingError extends Error {
+    constructor() {
+        super("LazerApiKeyMissing: pyth_lazer_rule requires a Pyth Lazer access token — " +
+            "pass `pythApiKey` when creating the client (the SDK never reads process.env)");
+        this.name = "LazerApiKeyMissingError";
+    }
+}
+exports.LazerApiKeyMissingError = LazerApiKeyMissingError;
+/** The `pyth_lazer_rule` deployment entry; throws when the config carries none. */
+function requireLazerPackage(host) {
+    const entry = host.config.packages.pyth_lazer_rule;
+    if (!entry) {
+        throw new Error("pyth_lazer_rule package is not deployed in this config");
+    }
+    return entry;
+}
+/**
+ * Fetch one signed `leEcdsa` update for `feedIds` from the Lazer HTTP API.
+ * Goes through the shared `fetchWithPolicy` (`../update-fetch.ts`) — same
+ * 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) {
+    // 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 = (0, update_fetch_ts_1.joinEndpointPath)(endpoint, "v1/latest_price");
+    let res;
+    try {
+        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 }),
+        }, { apiKey, ...fetchOpts });
+    }
+    catch (err) {
+        (0, update_fetch_ts_1.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()}`);
+    const json = (await res.json());
+    const hex = json.leEcdsa?.data;
+    if (typeof hex !== "string" || hex.length === 0) {
+        throw new Error("Lazer returned no leEcdsa update data");
+    }
+    return (0, bcs_1.fromHex)(hex);
+}
+/**
+ * `pyth_lazer_rule::feed(collector, config, clock, &update)` — contribute the
+ * verified Lazer price for `collector.symbol()` to the collector. `update` is
+ * the `RuleUpdateHandle` value from {@link PythLazerRule.buildUpdateCalls} in
+ * the SAME PTB; one verified update serves every ticker's feed call. On-chain
+ * the rule abstains (records `none`) instead of aborting when the symbol is
+ * unconfigured, the feed is absent from the update, the value is degenerate,
+ * or the Lazer timestamp is stale.
+ */
+function feedLazerRule(tx, host, collector, update) {
+    const lazer = requireLazerPackage(host);
+    tx.moveCall({
+        target: `${lazer.published_at}::pyth_lazer_rule::feed`,
+        arguments: [collector, tx.object(lazer.config), tx.object.clock(), update],
+    });
+}
+exports.PythLazerRule = {
+    kind: "pyth_lazer_rule",
+    // Verification is a flat signature check with no Coin argument — no
+    // update fee — see `PriceUpdateRule.requiresFeeSource`.
+    requiresFeeSource: false,
+    /** Tickers with a `pyth_lazer_rule.feeds` entry (integer Lazer feed ids). */
+    supportedTickers(host) {
+        return Object.keys(host.config.packages.pyth_lazer_rule?.feeds ?? {});
+    },
+    /** Resolves integer feed ids for `tickers`, then fetches one signed `leEcdsa` update. */
+    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 } = requireLazerPackage(host);
+        const feedIds = tickers.map((ticker) => {
+            const feedId = feeds[ticker];
+            if (feedId === undefined) {
+                throw new Error(`No pyth_lazer_rule feed listed for ticker: ${ticker}`);
+            }
+            return feedId;
+        });
+        const apiKey = host.pyth.api_key;
+        if (!apiKey) {
+            throw new LazerApiKeyMissingError();
+        }
+        const update = await fetchLazerSignedUpdate(config_ts_1.LAZER_DEFAULTS[host.network].endpoint, 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
+     * 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
+     * payload does not carry) → `null` (miss), never a silent partial.
+     */
+    narrowUpdateData(host, data, tickers) {
+        const payload = (0, price_update_rule_ts_1.assertRuleUpdateData)(data, "pyth_lazer_rule", isPythLazerUpdatePayloadShape, "{ update: Uint8Array; feedIds: number[] }");
+        if (!payload || tickers.length === 0)
+            return null;
+        const packedFeedIds = new Set(payload.feedIds);
+        for (const ticker of tickers) {
+            const feedId = host.config.packages.pyth_lazer_rule?.feeds?.[ticker];
+            if (feedId === undefined || !packedFeedIds.has(feedId))
+                return null;
+        }
+        return { kind: "pyth_lazer_rule", payload };
+    },
+    /**
+     * 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).
+     */
+    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 [update] = tx.moveCall({
+            target: `${config_ts_1.LAZER_DEFAULTS[host.network].verifier_package}::pyth_lazer::parse_and_verify_le_ecdsa_update`,
+            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/pyth-rule.js

@@ -16,6 +16,11 @@ 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/cjs/src/oracle/rules/sponsor.d.ts

@@ -3,17 +3,21 @@
  * attach the `PythSponsorRule` witness to a `TradingRequest`. Required when the
  * market's `request_checklist` contains `PythSponsorRule`.
  *
- * Flow: {@link openPythSponsorFund} opens a `Fund` hot potato; pass the returned
- * `{ fund, packageId }` to the Pyth update path as its `sponsorFund` (it draws
- * per-feed fees via `pyth_sponsor_rule::split`); then {@link reimbursePythSponsor}
- * consumes the `Fund`, returns leftover SUI, and attaches the witness.
+ * Flow: {@link openPythSponsorFund} opens a `Fund` hot potato; the caller wraps
+ * the returned `{ fund, packageId }` into an `OracleFeeSource` (`{ kind:
+ * 'sponsor', fund, packageId }`) and passes that to the Pyth update path (it
+ * draws per-feed fees via `pyth_sponsor_rule::split`); then
+ * {@link reimbursePythSponsor} consumes the `Fund`, returns leftover SUI, and
+ * attaches the witness.
  */
 import type { Transaction, TransactionArgument } from "@mysten/sui/transactions";
 import type { OracleHost } from "../host.ts";
 /**
- * Opens a `Fund` hot potato from the shared PythSponsor pool. Pass the returned
- * `{ fund, packageId }` straight to `refreshOraclePrices` as `sponsorFund`, then
- * {@link reimbursePythSponsor} once the TradingRequest is built.
+ * Opens a `Fund` hot potato from the shared PythSponsor pool. Wrap the
+ * returned `{ fund, packageId }` into an `OracleFeeSource`
+ * (`{ kind: 'sponsor', fund, packageId }`) and pass that to
+ * `refreshOraclePrices` as `feeSource`, then {@link reimbursePythSponsor} once
+ * the TradingRequest is built.
  */
 export declare function openPythSponsorFund(tx: Transaction, host: OracleHost): {
     fund: TransactionArgument;

package/dist/cjs/src/oracle/rules/sponsor.js

@@ -4,19 +4,23 @@
  * attach the `PythSponsorRule` witness to a `TradingRequest`. Required when the
  * market's `request_checklist` contains `PythSponsorRule`.
  *
- * Flow: {@link openPythSponsorFund} opens a `Fund` hot potato; pass the returned
- * `{ fund, packageId }` to the Pyth update path as its `sponsorFund` (it draws
- * per-feed fees via `pyth_sponsor_rule::split`); then {@link reimbursePythSponsor}
- * consumes the `Fund`, returns leftover SUI, and attaches the witness.
+ * Flow: {@link openPythSponsorFund} opens a `Fund` hot potato; the caller wraps
+ * the returned `{ fund, packageId }` into an `OracleFeeSource` (`{ kind:
+ * 'sponsor', fund, packageId }`) and passes that to the Pyth update path (it
+ * draws per-feed fees via `pyth_sponsor_rule::split`); then
+ * {@link reimbursePythSponsor} consumes the `Fund`, returns leftover SUI, and
+ * attaches the witness.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.openPythSponsorFund = openPythSponsorFund;
 exports.reimbursePythSponsor = reimbursePythSponsor;
 const pyth_sponsor_rule_ts_1 = require("../../generated/pyth_sponsor_rule/pyth_sponsor_rule.js");
 /**
- * Opens a `Fund` hot potato from the shared PythSponsor pool. Pass the returned
- * `{ fund, packageId }` straight to `refreshOraclePrices` as `sponsorFund`, then
- * {@link reimbursePythSponsor} once the TradingRequest is built.
+ * Opens a `Fund` hot potato from the shared PythSponsor pool. Wrap the
+ * returned `{ fund, packageId }` into an `OracleFeeSource`
+ * (`{ kind: 'sponsor', fund, packageId }`) and pass that to
+ * `refreshOraclePrices` as `feeSource`, then {@link reimbursePythSponsor} once
+ * the TradingRequest is built.
  */
 function openPythSponsorFund(tx, host) {
     const entry = host.config.packages.pyth_sponsor_rule;

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

@@ -0,0 +1,115 @@
+/**
+ * `fetchWithPolicy` — resilience wrapper around `fetch` for the oracle money
+ * path's off-chain update-data fetches. Every order/position/collateral
+ * tx-build depends on one of these REST calls landing (Hermes VAA for
+ * `pyth_rule`, Lazer signed updates for `pyth_lazer_rule`); a bare `fetch`
+ * with a single attempt and no retry means one Hermes 429/5xx or timeout
+ * fails every trade. `fetchPriceFeedsUpdateData` (`./pyth.ts`),
+ * `PythLazerRule.fetchUpdateData`'s Lazer POST (`./rules/pyth-lazer-rule.ts`),
+ * and `loadConfig` (`../perp/config.ts`) all delegate here instead of calling
+ * `fetch` directly — this is the ONE place a retry/timeout/auth policy is
+ * implemented for these fetches.
+ *
+ * Policy semantics:
+ * - Bearer auth is attached iff `policy.apiKey` is a non-empty string —
+ *   absent/empty is byte-identical to today's keyless request (no
+ *   `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`). 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
+ *   domain-specific error, exactly as it did before this wrapper existed.
+ * - `init.body`, if set, MUST be replayable across attempts — a retry
+ *   re-sends the SAME `init` object to `fetch` on every attempt. A string /
+ *   `URLSearchParams` / BCS-serialized `Uint8Array` body (every caller today)
+ *   is fine; a one-shot `ReadableStream` body would not survive a second
+ *   attempt and must not be passed through this function.
+ * - Each attempt gets its own `AbortSignal.timeout(policy.timeoutMs)`
+ *   combined with whichever of `init.signal` / the `externalSignal` param are
+ *   set — ALL of them can end the whole policy (not just the in-flight
+ *   attempt), including a queued backoff sleep, via `AbortSignal.any`
+ *   (runtime floor: Node ≥20.3 / any modern browser — matches this repo's
+ *   `target: ES2023` + `lib: ["dom", "esnext"]`).
+ * - Exhausting retries with no successful/non-retryable response (i.e. every
+ *   attempt was a network error, or the final attempt was still a retryable
+ *   HTTP failure) throws a {@link FetchPolicyError} naming the target's
+ *   `host + pathname` (never the query string — feed ids are off-chain
+ *   noise, not diagnostic value), the attempt count, and whichever of
+ *   `status` (a retryable HTTP failure — plus a truncated response-body
+ *   snippet, when the final attempt's response carried one) or `cause` (a
+ *   network error) the final attempt produced. An INTERMEDIATE (non-final)
+ *   retryable response's body is discarded via `response.body?.cancel()`
+ *   instead of read, so a doomed-to-retry response doesn't pin its
+ *   connection's socket open for no reason.
+ * - 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 the `pythFetch` create option (`{timeoutMs,retries}`).
+ */
+export interface FetchPolicy {
+    /** Per-attempt timeout (ms). Default 15_000. */
+    readonly timeoutMs?: number;
+    /** Retry attempts AFTER the first try — `retries: 2` ⇒ 3 attempts total. Default 2. */
+    readonly retries?: number;
+    /** Base backoff (ms); doubled per attempt, capped at 2_000ms. Default 250. */
+    readonly retryDelayMs?: number;
+    /** Bearer token. Attached iff non-empty; empty/missing ⇒ no `Authorization` header. */
+    readonly apiKey?: string;
+    /** Override the fetch implementation (tests / non-global-`fetch` environments). Default: global `fetch`. */
+    readonly fetchImpl?: typeof fetch;
+}
+/** Thrown by {@link fetchWithPolicy} when every attempt failed. */
+export declare class FetchPolicyError extends Error {
+    /** HTTP status of the final attempt, when it got a (retryable-but-failing) response. */
+    readonly status?: number;
+    /** Truncated (~200 char) body of the final attempt's response, when one was readable. */
+    readonly bodySnippet?: string;
+    /** Total attempts made (first try + retries actually used). */
+    readonly attempts: number;
+    constructor(message: string, opts: {
+        status?: number;
+        bodySnippet?: string;
+        cause?: unknown;
+        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`
+ * (if the caller set one) AND the separate `externalSignal` param cancel the
+ * WHOLE policy — in-flight attempts AND queued backoff sleeps — not just a
+ * single attempt.
+ */
+export declare function fetchWithPolicy(url: string, init?: RequestInit, policy?: FetchPolicy, externalSignal?: AbortSignal): Promise<Response>;