@waterx/sdk 3.1.0 → 4.0.0

package/dist/cjs/src/oracle/pyth.d.ts

@@ -29,24 +29,93 @@ export declare class PythCache {
     priceTableInfo?: PriceTableInfo;
     priceFeedObjectIdCache: Map<string, string | undefined>;
 }
-export declare function fetchPriceFeedsUpdateData(endpoint: string, priceIds: string[]): Promise<Uint8Array[]>;
+export declare function fetchPriceFeedsUpdateData(endpoint: string, priceIds: string[], opts?: {
+    apiKey?: string;
+    fetch?: {
+        timeoutMs?: number;
+        retries?: number;
+    };
+}): Promise<Uint8Array[]>;
+/**
+ * Resolved source for the Pyth Core on-chain update fee. Deliberately a
+ * closed two-variant union, not a `{ sponsorFund?, allowGasFee? }` pair — a
+ * caller can no longer construct the "both supplied" or "neither supplied
+ * but some other truthy flag" shapes that used to require a priority rule to
+ * disambiguate.
+ *
+ * Resolved exactly ONCE, at the edges (`wrapRequestAndExecute` and the WLP
+ * builders' equivalent in `perp/tx-builders/`) from config presence
+ * (`pyth_sponsor_rule` deployed → open a fund → `'sponsor'`) and the
+ * caller's ergonomic `allowGasFee` opt-in (→ `'gas'`), then threaded
+ * verbatim through `refreshOraclePrices` → `BuildUpdateOpts` →
+ * `PythCoreRule` → {@link buildPythPriceUpdateCalls}. The sponsor-beats-gas
+ * priority from the old two-flag design is now structural — whichever edge
+ * resolves this value decides once; no downstream layer re-derives or
+ * re-documents a priority because none of them ever see more than one
+ * candidate source.
+ */
+export type OracleFeeSource = {
+    readonly kind: "sponsor";
+    readonly fund: TransactionArgument;
+    readonly packageId: string;
+} | {
+    readonly kind: "gas";
+};
+/**
+ * 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`.
+ */
+export declare class OracleFeeSourceUnavailableError extends Error {
+    constructor();
+}
 /**
  * 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.
  */
-export declare function buildPythPriceUpdateCalls(tx: Transaction, host: OracleHost, updates: Uint8Array[], feedIds: string[], cache?: PythCache, sponsorFund?: {
-    fund: TransactionArgument;
-    packageId: string;
+export declare function buildPythPriceUpdateCalls(tx: Transaction, host: OracleHost, updates: Uint8Array[], feedIds: string[], opts?: {
+    cache?: PythCache;
+    feeSource?: OracleFeeSource;
 }): Promise<string[]>;
 /** All-in-one: fetch from Hermes, append update calls. Returns PriceInfoObject IDs. */
-export declare function updatePythPrices(tx: Transaction, host: OracleHost, feedIds: string[], cache?: PythCache, sponsorFund?: {
-    fund: TransactionArgument;
-    packageId: string;
+export declare function updatePythPrices(tx: Transaction, host: OracleHost, feedIds: string[], opts?: {
+    cache?: PythCache;
+    feeSource?: OracleFeeSource;
 }): Promise<string[]>;
 export {};

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;