@waterx/sdk 3.1.1 → 4.0.0

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

@@ -15,12 +15,13 @@
  *   4. hot_potato_vector::destroy
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PythCache = void 0;
+exports.OracleFeeSourceUnavailableError = exports.PythCache = void 0;
 exports.fetchPriceFeedsUpdateData = fetchPriceFeedsUpdateData;
 exports.buildPythPriceUpdateCalls = buildPythPriceUpdateCalls;
 exports.updatePythPrices = updatePythPrices;
 const bcs_1 = require("@mysten/bcs");
 const bcs_2 = require("@mysten/sui/bcs");
+const update_fetch_ts_1 = require("./update-fetch.js");
 class PythCache {
     pythStateInfo;
     wormholePackageId;
@@ -31,12 +32,28 @@ exports.PythCache = PythCache;
 // ============================================================================
 // Hermes REST
 // ============================================================================
-async function fetchPriceFeedsUpdateData(endpoint, priceIds) {
+async function fetchPriceFeedsUpdateData(endpoint, priceIds, opts) {
     if (priceIds.length === 0)
         return [];
     const url = new URL("/v2/updates/price/latest", endpoint);
     priceIds.forEach((id) => url.searchParams.append("ids[]", id));
-    const res = await fetch(url.toString(), { signal: AbortSignal.timeout(15_000) });
+    let res;
+    try {
+        res = await (0, update_fetch_ts_1.fetchWithPolicy)(url.toString(), {}, { apiKey: opts?.apiKey, ...opts?.fetch });
+    }
+    catch (err) {
+        // A retryable status (429/5xx) that never recovered surfaces as a
+        // FetchPolicyError with `status` set — reformat it into this function's
+        // own message shape so callers (and the e2e transient-failure detector,
+        // which keys off "Hermes price fetch failed") see the same text whether
+        // the failure was retried or not. A network-level exhaustion (no status)
+        // has no domain-specific reframing to add — propagate it as-is.
+        if (err instanceof update_fetch_ts_1.FetchPolicyError && err.status !== undefined) {
+            const body = err.bodySnippet ? ` ${err.bodySnippet}` : "";
+            throw new Error(`Hermes price fetch failed: ${err.status}${body} (retries exhausted after ${err.attempts} attempts)`, { cause: err });
+        }
+        throw err;
+    }
     if (!res.ok)
         throw new Error(`Hermes price fetch failed: ${res.status} ${await res.text()}`);
     const json = (await res.json());
@@ -144,26 +161,73 @@ function extractVaaBytes(accumulatorMessage) {
     const vaaOffset = vaaSizeOffset + 2;
     return accumulatorMessage.subarray(vaaOffset, vaaOffset + vaaSize);
 }
-// ============================================================================
-// Pyth update calls
-// ============================================================================
+/**
+ * Thrown when no {@link OracleFeeSource} is available for the Pyth update fee
+ * — from `buildPythPriceUpdateCalls`'s own per-call guard, or `aggregate.ts`'s
+ * hoisted `refreshOraclePrices` pre-check (see its docblock). `instanceof`-able
+ * (mirrors `FetchPolicyError` in `update-fetch.ts`) so a consumer — e.g. a BE
+ * integration wiring its own `allowGasFee` decision — can branch on the error
+ * type directly instead of string-matching `error.message`.
+ */
+class OracleFeeSourceUnavailableError extends Error {
+    constructor() {
+        super("OracleFeeSourceUnavailable: no fee source available for the Pyth update fee — " +
+            "deploy pyth_sponsor_rule to config so a sponsor fund can be opened (see " +
+            "openPythSponsorFund / wrapRequestAndExecute), or pass allowGasFee: true to draw " +
+            "the fee from tx.gas in a non-sponsored context");
+        this.name = "OracleFeeSourceUnavailableError";
+    }
+}
+exports.OracleFeeSourceUnavailableError = OracleFeeSourceUnavailableError;
 /**
  * Append the on-chain Pyth update PTB block. Returns `PriceInfoObject` IDs
  * (one per `feedIds`, same order). After this you can feed `pyth_rule` per
  * ticker against the matching `PriceInfoObject` (see `rules/pyth-rule.ts`).
  *
- * If `sponsorFund` is provided, the per-feed update fee comes from the
- * sponsor pool (`pyth_sponsor_rule::split`) instead of `tx.gas`. Opening and
- * reimbursing that fund is the sponsor rule's job (`rules/sponsor.ts`); here we
- * only draw a fee coin from the already-open `fund` hot potato.
+ * `opts.feeSource` is resolved BEFORE any PTB mutation and is never silently
+ * defaulted — this function trusts whatever single {@link OracleFeeSource}
+ * it's handed, it does not choose between competing candidates:
+ *   - `{ kind: 'sponsor' }` → the per-feed update fee is drawn from the
+ *     sponsor pool (`pyth_sponsor_rule::split`) instead of `tx.gas`. Opening
+ *     and reimbursing that fund is the caller's job (`rules/sponsor.ts` /
+ *     `wrapRequestAndExecute`, which opens it whenever the client's config
+ *     has `pyth_sponsor_rule` deployed) — this function only draws a fee
+ *     coin from the already-open `fund` hot potato.
+ *   - `{ kind: 'gas' }` → the fee is drawn from `tx.gas` via `tx.splitCoins`.
+ *     Only safe in a non-sponsored context — Enoki-sponsored transactions
+ *     reject any `tx.gas` draw.
+ *   - `undefined` → throws `OracleFeeSourceUnavailable` instead of silently
+ *     drawing from `tx.gas` (the old default), which broke under Enoki and,
+ *     worse, could fail ON-CHAIN when the market's `request_checklist`
+ *     requires the `PythSponsorRule` witness that only a real sponsor fund
+ *     attaches.
+ *
+ * This function's own check runs AFTER `updates`/`feedIds` are already in
+ * hand, so for `updatePythPrices` (which fetches from Hermes, then calls
+ * straight into this function) the off-chain fetch has already completed by
+ * the time this throws — a wasted network call, never a stray PTB command.
+ * `refreshOraclePrices` avoids that waste entirely: it hoists an EQUIVALENT
+ * check ABOVE its off-chain fetch AND its per-group build loop (see its
+ * docblock in `aggregate.ts`), keyed on `PriceUpdateRule.requiresFeeSource`
+ * rather than waiting for a specific rule's fetch to complete — so for that
+ * route neither the network call NOR any PTB command happens before the
+ * throw. This function's own (later, per-call) guard alone could not
+ * provide that "before any group builds" guarantee in a mixed shape (e.g. a
+ * fee-free Lazer group ordered ahead of a Pyth Core fallback group in the
+ * same PTB) — `refreshOraclePrices`'s pre-check is what closes it.
  */
-async function buildPythPriceUpdateCalls(tx, host, updates, feedIds, cache, sponsorFund) {
+async function buildPythPriceUpdateCalls(tx, host, updates, feedIds, opts) {
     if (updates.length === 0) {
         throw new Error("No price update data provided; Hermes returned empty results");
     }
     if (updates.length > 1) {
         throw new Error("Only a single accumulator message is supported per transaction");
     }
+    const feeSource = opts?.feeSource;
+    if (!feeSource) {
+        throw new OracleFeeSourceUnavailableError();
+    }
+    const cache = opts?.cache;
     const pyth = host.pyth;
     const [stateInfo, wormholePackageId, table] = await Promise.all([
         getPythStateInfo(host.grpcClient, pyth.state_id, cache),
@@ -195,10 +259,10 @@ async function buildPythPriceUpdateCalls(tx, host, updates, feedIds, cache, spon
         if (!priceInfoObjectId) {
             throw new Error(`Pyth feed ${feedIds[i]} not registered on-chain in Pyth state`);
         }
-        const feeCoin = sponsorFund
+        const feeCoin = feeSource.kind === "sponsor"
             ? tx.moveCall({
-                target: `${sponsorFund.packageId}::pyth_sponsor_rule::split`,
-                arguments: [sponsorFund.fund],
+                target: `${feeSource.packageId}::pyth_sponsor_rule::split`,
+                arguments: [feeSource.fund],
             })[0]
             : tx.splitCoins(tx.gas, [tx.pure.u64(baseUpdateFee)])[0];
         [hotPotato] = tx.moveCall({
@@ -221,7 +285,10 @@ async function buildPythPriceUpdateCalls(tx, host, updates, feedIds, cache, spon
     return priceInfoObjectIds;
 }
 /** All-in-one: fetch from Hermes, append update calls. Returns PriceInfoObject IDs. */
-async function updatePythPrices(tx, host, feedIds, cache, sponsorFund) {
-    const updates = await fetchPriceFeedsUpdateData(host.pyth.hermes_endpoint, feedIds);
-    return buildPythPriceUpdateCalls(tx, host, updates, feedIds, cache, sponsorFund);
+async function updatePythPrices(tx, host, feedIds, opts) {
+    const updates = await fetchPriceFeedsUpdateData(host.pyth.hermes_endpoint, feedIds, {
+        apiKey: host.pyth.api_key,
+        fetch: host.pyth.fetch,
+    });
+    return buildPythPriceUpdateCalls(tx, host, updates, feedIds, opts);
 }

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

@@ -0,0 +1,37 @@
+/**
+ * `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`, a client create option) — never by a
+ * config JSON `enabled` flag and never by `process.env`.
+ *
+ * Both sources 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 instead of silently falling back to Pyth Core.
+ */
+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,61 @@
+"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`, a client create option) — never by a
+ * config JSON `enabled` flag and never by `process.env`.
+ *
+ * Both sources 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 instead of silently falling back to Pyth Core.
+ */
+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,84 @@
+"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;
+        const feedIds = tickers.map((ticker) => host.getPythFeed(ticker).feed_id);
+        const updates = await (0, pyth_ts_1.fetchPriceFeedsUpdateData)(host.pyth.hermes_endpoint, feedIds, {
+            apiKey: host.pyth.api_key,
+            fetch: host.pyth.fetch,
+        });
+        return { kind: "pyth_rule", payload: { updates, feedIds } };
+    },
+    /**
+     * 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 `config.pyth.api_key`), 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 `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`.
+ */
+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,194 @@
+"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 `config.pyth.api_key`), 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` — `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.
+ * - `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: "real_time",
+};
+/**
+ * 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 `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`.
+ */
+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)");
+        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) {
+    const url = new URL("/v1/latest_price", endpoint);
+    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) {
+        // 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 update_fetch_ts_1.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;
+    }
+    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/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;