@waterx/sdk 3.1.0 → 4.0.0

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

@@ -0,0 +1,180 @@
+/**
+ * `PriceUpdateRule` — the strategy port for one oracle rule generation: fetch
+ * its off-chain update payload and emit the PTB calls that verify/push that
+ * update on-chain (e.g. Pyth's wormhole-verify + price-feed-update block).
+ * Feeding the refreshed price into an oracle `PriceCollector` is a separate
+ * step that stays in `aggregate.ts` — this port covers fetch + verify/push
+ * only (`buildUpdateCalls` may hand the feed step a PTB value via
+ * {@link RuleUpdateHandle}). Implementations: `PythCoreRule` (Hermes VAA) and
+ * `PythLazerRule` (Lazer signed updates), with `WaterxRule` (ed25519) to
+ * follow. `ConstantRule` and `SupraRule` do NOT implement this port — they
+ * remain plain collector-feed helpers wired directly into `aggregate.ts`.
+ *
+ * This file defines the port only — routing IS wired: `aggregate.ts`'s
+ * `refreshOraclePrices` selects the concrete rule per `host.oracleSource` via
+ * `rule-registry.ts`, then drives fetch + `buildUpdateCalls` through this
+ * port; `aggregate.ts` stays the sole orchestrator.
+ */
+import type { Transaction, TransactionArgument } from "@mysten/sui/transactions";
+import type { OracleHost } from "./host.ts";
+import type { OracleFeeSource, PythCache } from "./pyth.ts";
+export type PriceUpdateRuleKind = "pyth_rule" | "pyth_lazer_rule" | "supra_rule" | "constant_rule" | "waterx_rule";
+/**
+ * The subset of `PriceUpdateRuleKind`s selectable via a client's `oracleSource`
+ * create option (see `OracleHost.oracleSource`) — i.e. rules that can serve as
+ * the on-chain price *update* leg `refreshOraclePrices` runs before aggregating.
+ * `supra_rule` and `constant_rule` are auxiliary rules fed alongside whichever
+ * source is selected (see `aggregateTicker`), not sources themselves;
+ * `waterx_rule` has no `PriceUpdateRule` implementation yet. The SDK never
+ * reads `process.env` — consumers resolve their own env var to this type.
+ */
+export type OracleSource = "pyth_rule" | "pyth_lazer_rule";
+/**
+ * Off-chain payload fetched by a rule, tagged by `kind` so a caller holding
+ * several rules' results can tell them apart. `payload` is `unknown` here —
+ * each rule implementation narrows it to its own shape (e.g. `PythCoreRule`'s
+ * `{ updates: Uint8Array[]; feedIds: string[] }`). `null` for rules with no
+ * off-chain fetch (e.g. `ConstantRule`) or when there is nothing to fetch.
+ */
+export type RuleUpdateData = {
+    kind: PriceUpdateRuleKind;
+    payload: unknown;
+} | null;
+/**
+ * Shared null → kind → shape guard ladder for a `PriceUpdateRule.buildUpdateCalls`
+ * payload — every rule's `buildUpdateCalls` needs the exact same three checks,
+ * in the exact same order, before it can trust `data.payload`:
+ *
+ * 1. `data === null` passes straight through as `null` — the no-op case (an
+ *    empty ticker list upstream produced nothing to build).
+ * 2. `data.kind !== kind` throws BEFORE the shape check runs. This order is
+ *    load-bearing, not stylistic: two rules' payloads can share an identical
+ *    shape (e.g. Pyth Core's `{ updates, feedIds }` also satisfies a
+ *    hypothetical same-shaped rule), so checking shape first would let a
+ *    wrong-kind payload silently pass as this rule's own.
+ * 3. `!isShape(data.payload)` throws for a same-`kind` payload whose shape
+ *    doesn't match this rule's own (e.g. a hand-built test double).
+ *
+ * Returns `data.payload` narrowed to `T` once both checks pass.
+ *
+ * @param data - The `RuleUpdateData` handed to `buildUpdateCalls`.
+ * @param kind - This rule's own {@link PriceUpdateRuleKind} — the only `kind`
+ *   `data` may carry past step 2.
+ * @param isShape - Type predicate narrowing `data.payload` to `T`.
+ * @param shapeDescription - Human-readable shape, quoted verbatim into the
+ *   shape-mismatch error (e.g. `"{ updates: Uint8Array[]; feedIds: string[] }"`).
+ */
+export declare function assertRuleUpdateData<T>(data: RuleUpdateData, kind: PriceUpdateRuleKind, isShape: (payload: unknown) => payload is T, shapeDescription: string): T | null;
+/**
+ * PTB value handle a rule's {@link PriceUpdateRule.buildUpdateCalls} may
+ * return when its collector-feed leg needs a value produced by the update leg
+ * *within the same PTB*. Pyth Core needs none (its feed leg reads the shared
+ * `PriceInfoObject` the update leg refreshed), so it returns `void`. The Lazer
+ * rule returns the verified `pyth_lazer::update::Update` result — one
+ * signature verification covers every feed in the payload, and
+ * `pyth_lazer_rule::feed` takes it by reference per ticker (see
+ * `aggregateTicker`'s `lazerUpdate` arg).
+ */
+export type RuleUpdateHandle = {
+    readonly kind: "pyth_lazer_rule";
+    /** Result of `pyth_lazer::parse_and_verify_le_ecdsa_update` in this PTB. */
+    readonly update: TransactionArgument;
+};
+/**
+ * Options for {@link PriceUpdateRule.buildUpdateCalls}. Mirrors
+ * `buildPythPriceUpdateCalls` / `updatePythPrices`'s own opts shape in
+ * `./pyth.ts` — `cache` shares on-chain Pyth state reads across builders;
+ * `feeSource` is the single {@link OracleFeeSource} already resolved by the
+ * caller (see its own doc for where/how). Both fields are Pyth-Core-specific
+ * mechanics; `refreshOraclePrices` passes the same `BuildUpdateOpts` to every
+ * rule uniformly, so a non-Pyth-Core rule (e.g. `PythLazerRule`, which
+ * charges no update fee) simply ignores whichever fields it has no use for.
+ */
+export interface BuildUpdateOpts {
+    readonly cache?: PythCache;
+    readonly feeSource?: OracleFeeSource;
+}
+/**
+ * Injectable update-data cache seam for `refreshOraclePrices` (`aggregate.ts`).
+ * A BE consumer (e.g. a prefetch cache that polls Hermes/Lazer out-of-band and
+ * keeps a hot in-memory/Redis entry per source) implements this and passes it
+ * as `refreshOraclePrices`'s `updateDataProvider` opt; the SDK itself never
+ * implements one. `get` is checked before the rule's own live
+ * `fetchUpdateData` for that group of tickers — a `null` return means "no
+ * cached data, fetch live" (mirrors {@link RuleUpdateData}'s own `null`
+ * variant: there is no separate signal for "the cache legitimately has
+ * nothing" vs "go fetch live", they're the same instruction to the caller).
+ *
+ * A non-null hit MAY be a payload for a WIDER ticker set than `tickers` — a
+ * provider is free to cache one whole-universe payload per source and return
+ * it verbatim; `refreshOraclePrices` narrows it down to exactly the requested
+ * tickers via the rule's {@link PriceUpdateRule.narrowUpdateData} before use,
+ * so an implementer need not (and should not) subset it by hand. The only
+ * hard requirement on a hit is that its `kind` matches the requested
+ * `source`'s rule — a mismatch is a routing bug and throws.
+ */
+export interface UpdateDataProvider {
+    get(source: OracleSource, tickers: string[]): Promise<RuleUpdateData | null>;
+}
+export interface PriceUpdateRule {
+    readonly kind: PriceUpdateRuleKind;
+    /**
+     * `true` when this rule's on-chain update leg charges a per-update fee
+     * that must be paid from either a sponsor fund or `tx.gas` (Pyth Core:
+     * `true`, via `pyth::update_single_price_feed`'s `base_update_fee`).
+     * `false` for a fee-free update leg (Lazer: signature verification only,
+     * no `Coin` argument). `refreshOraclePrices` (`aggregate.ts`) reads this
+     * BEFORE fetching any group's off-chain payload — for every group whose
+     * rule sets it `true`, `opts.feeSource` must already be resolved, or the
+     * whole call throws `OracleFeeSourceUnavailable` before
+     * any group builds (mixed-shape atomicity: a fee-free group ordered
+     * ahead of a fee-charging one in the same PTB must never get to mutate
+     * `tx` while the fee-charging group is left unpayable). A referential
+     * check against a specific rule instance (e.g. `=== PythCoreRule`) would
+     * silently stop protecting a future fee-charging rule, or a test double
+     * standing in for one — this field is the honest, extensible signal.
+     */
+    readonly requiresFeeSource: boolean;
+    /** Tickers this rule can serve in this environment (from config feeds + enabled). */
+    supportedTickers(host: OracleHost): string[];
+    /**
+     * Fetch the off-chain payload for these tickers (no-op rules return null).
+     * `tickers` must already be a subset of {@link supportedTickers} — an
+     * unsupported ticker's feed lookup throws and that throw propagates
+     * uncaught; callers pre-filter via `supportedTickers`, this method does not
+     * re-validate.
+     */
+    fetchUpdateData(host: OracleHost, tickers: string[]): Promise<RuleUpdateData>;
+    /**
+     * Narrow a payload previously produced by {@link fetchUpdateData} — typically
+     * for a superset of tickers (e.g. a consumer's whole-universe prefetch cache)
+     * — down to exactly `tickers`, without any re-fetch. Each rule owns its
+     * payload's divisibility semantics, so consumers must never subset a payload
+     * themselves (that knowledge branching on `kind` in a consumer is exactly the
+     * altitude violation this method removes):
+     *
+     * - A non-null result MUST be valid {@link buildUpdateCalls} input covering
+     *   exactly `tickers` — a divisible payload (Pyth Core's per-feed entries)
+     *   returns a subset; an indivisible payload (Lazer's single signed message)
+     *   returns the whole payload iff every requested ticker is covered.
+     * - A ticker this payload cannot serve → `null` (miss), NEVER a silent
+     *   partial. `null` mirrors {@link UpdateDataProvider.get}'s convention: the
+     *   caller falls back to a live {@link fetchUpdateData} for those tickers.
+     * - An empty `tickers` list → `null`, mirroring {@link fetchUpdateData}'s own
+     *   empty-list convention (nothing to build); `data === null` → `null`.
+     * - `data` must be this rule's own payload: kind/shape are enforced via
+     *   {@link assertRuleUpdateData}, so a wrong-`kind` payload throws (a routing
+     *   bug), it does not miss.
+     */
+    narrowUpdateData(host: OracleHost, data: RuleUpdateData, tickers: string[]): RuleUpdateData;
+    /**
+     * Emit verify/update moveCalls + any per-rule setup into the PTB. Returns a
+     * {@link RuleUpdateHandle} when the rule's collector-feed leg needs a PTB
+     * value from this step (Lazer's verified `Update`); rules whose feed leg
+     * reads shared on-chain objects return `void`. Takes no `tickers` param —
+     * every implementation derives everything it needs from `data.payload`
+     * (the tickers a group covers were already fixed when `fetchUpdateData`
+     * built that payload).
+     */
+    buildUpdateCalls(tx: Transaction, host: OracleHost, data: RuleUpdateData, opts?: BuildUpdateOpts): Promise<RuleUpdateHandle | void> | RuleUpdateHandle | void;
+}

package/dist/src/oracle/price-update-rule.js

@@ -0,0 +1,53 @@
+/**
+ * `PriceUpdateRule` — the strategy port for one oracle rule generation: fetch
+ * its off-chain update payload and emit the PTB calls that verify/push that
+ * update on-chain (e.g. Pyth's wormhole-verify + price-feed-update block).
+ * Feeding the refreshed price into an oracle `PriceCollector` is a separate
+ * step that stays in `aggregate.ts` — this port covers fetch + verify/push
+ * only (`buildUpdateCalls` may hand the feed step a PTB value via
+ * {@link RuleUpdateHandle}). Implementations: `PythCoreRule` (Hermes VAA) and
+ * `PythLazerRule` (Lazer signed updates), with `WaterxRule` (ed25519) to
+ * follow. `ConstantRule` and `SupraRule` do NOT implement this port — they
+ * remain plain collector-feed helpers wired directly into `aggregate.ts`.
+ *
+ * This file defines the port only — routing IS wired: `aggregate.ts`'s
+ * `refreshOraclePrices` selects the concrete rule per `host.oracleSource` via
+ * `rule-registry.ts`, then drives fetch + `buildUpdateCalls` through this
+ * port; `aggregate.ts` stays the sole orchestrator.
+ */
+/**
+ * Shared null → kind → shape guard ladder for a `PriceUpdateRule.buildUpdateCalls`
+ * payload — every rule's `buildUpdateCalls` needs the exact same three checks,
+ * in the exact same order, before it can trust `data.payload`:
+ *
+ * 1. `data === null` passes straight through as `null` — the no-op case (an
+ *    empty ticker list upstream produced nothing to build).
+ * 2. `data.kind !== kind` throws BEFORE the shape check runs. This order is
+ *    load-bearing, not stylistic: two rules' payloads can share an identical
+ *    shape (e.g. Pyth Core's `{ updates, feedIds }` also satisfies a
+ *    hypothetical same-shaped rule), so checking shape first would let a
+ *    wrong-kind payload silently pass as this rule's own.
+ * 3. `!isShape(data.payload)` throws for a same-`kind` payload whose shape
+ *    doesn't match this rule's own (e.g. a hand-built test double).
+ *
+ * Returns `data.payload` narrowed to `T` once both checks pass.
+ *
+ * @param data - The `RuleUpdateData` handed to `buildUpdateCalls`.
+ * @param kind - This rule's own {@link PriceUpdateRuleKind} — the only `kind`
+ *   `data` may carry past step 2.
+ * @param isShape - Type predicate narrowing `data.payload` to `T`.
+ * @param shapeDescription - Human-readable shape, quoted verbatim into the
+ *   shape-mismatch error (e.g. `"{ updates: Uint8Array[]; feedIds: string[] }"`).
+ */
+export function assertRuleUpdateData(data, kind, isShape, shapeDescription) {
+    if (!data)
+        return null;
+    if (data.kind !== kind) {
+        throw new Error(`assertRuleUpdateData: received a payload of kind '${data.kind}', expected '${kind}'`);
+    }
+    if (!isShape(data.payload)) {
+        throw new Error(`assertRuleUpdateData: received a '${kind}' payload with an unexpected shape ` +
+            `(expected ${shapeDescription})`);
+    }
+    return data.payload;
+}

package/dist/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/src/oracle/pyth.js

@@ -15,6 +15,7 @@
  */
 import { fromHex, toHex } from "@mysten/bcs";
 import { bcs } from "@mysten/sui/bcs";
+import { FetchPolicyError, fetchWithPolicy } from "./update-fetch.js";
 export class PythCache {
     pythStateInfo;
     wormholePackageId;
@@ -24,12 +25,28 @@ export class PythCache {
 // ============================================================================
 // Hermes REST
 // ============================================================================
-export async function fetchPriceFeedsUpdateData(endpoint, priceIds) {
+export 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 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 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());
@@ -137,26 +154,72 @@ 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`.
+ */
+export 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";
+    }
+}
 /**
  * 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 async function buildPythPriceUpdateCalls(tx, host, updates, feedIds, cache, sponsorFund) {
+export 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),
@@ -188,10 +251,10 @@ export async function buildPythPriceUpdateCalls(tx, host, updates, feedIds, cach
         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({
@@ -214,7 +277,10 @@ export async function buildPythPriceUpdateCalls(tx, host, updates, feedIds, cach
     return priceInfoObjectIds;
 }
 /** All-in-one: fetch from Hermes, append update calls. Returns PriceInfoObject IDs. */
-export 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);
+export 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/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/src/oracle/rule-registry.js

@@ -0,0 +1,56 @@
+/**
+ * `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 { PythCoreRule } from "./rules/pyth-core-rule.js";
+import { PythLazerRule } from "./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: PythCoreRule,
+    pyth_lazer_rule: 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`.
+ */
+export class OracleSourceNotImplementedError extends Error {
+    /** The unregistered `OracleSource` that was requested. */
+    source;
+    constructor(source) {
+        super(`OracleSourceNotImplemented: ${source}`);
+        this.name = "OracleSourceNotImplementedError";
+        this.source = source;
+    }
+}
+/**
+ * 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 function resolveOracleRule(source, overrides) {
+    const rule = overrides?.[source] ?? DEFAULT_RULES[source];
+    if (!rule) {
+        throw new OracleSourceNotImplementedError(source);
+    }
+    return rule;
+}

package/dist/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;