@waterx/sdk 3.1.1 → 4.0.0

package/dist/cjs/src/perp/tx-builders/common.d.ts

@@ -4,7 +4,7 @@
  * and the request+execute envelope (optional Pyth-sponsor flow + pre-sweep).
  */
 import { Transaction, type TransactionArgument } from "@mysten/sui/transactions";
-import { PythCache } from "../../oracle/index.ts";
+import { PythCache, type OracleFeeSource, type UpdateDataProvider } from "../../oracle/index.ts";
 import type { PerpClient } from "../client.ts";
 export interface CommonBuildOpts {
     /** Append to an existing PTB instead of creating a new one. */
@@ -14,16 +14,31 @@ export interface CommonBuildOpts {
     /** Share a `PythCache` across builders to avoid redundant pyth_state reads. */
     pythCache?: PythCache;
     /**
-     * Wire the `pyth_sponsor_rule` flow:
-     *   - open a Fund via `pyth_sponsor_rule::request(sponsor)`
-     *   - pay Pyth update fees from the Fund (instead of `tx.gas`)
-     *   - reimburse leftover into the sponsor pool + attach
-     *     `PythSponsorRule` witness to the TradingRequest so markets
-     *     whose `request_checklist` contains `PythSponsorRule` accept it
-     * Default: true (matches the testnet/mainnet checklist config).
-     * Pass `false` only when the market checklist is empty.
+     * @deprecated No longer a fee-source decision. `wrapRequestAndExecute` now
+     * opens (and reimburses) the `pyth_sponsor_rule` Fund purely from config
+     * presence — whenever `client.config.packages.pyth_sponsor_rule` is
+     * deployed, the fund is ALWAYS opened, regardless of this flag (see
+     * `OracleFeeSourceUnavailable` in `oracle/pyth.ts`). This closes the gap
+     * where a market whose checklist required `PythSponsorRule`, or a caller
+     * that mis-set this flag, silently drew from `tx.gas` and failed
+     * ON-CHAIN instead of at build time. Use `allowGasFee` for the
+     * non-sponsored case instead. Kept accepted (as a no-op) only so existing
+     * callers keep compiling; will be removed in a future major version.
      */
     useSponsor?: boolean;
+    /**
+     * Explicit opt-in to draw the Pyth update fee from `tx.gas` when this
+     * client's config has no `pyth_sponsor_rule` deployed. Ignored whenever a
+     * sponsor fund IS available — the sponsor pool always wins over `tx.gas`
+     * when one can be opened (see `useSponsor`'s deprecation note above).
+     * Required for flows with no `TradingRequest` to reimburse a sponsor fund
+     * against (e.g. `buildMintWlpTx` — see its doc comment). Building an
+     * oracle refresh with neither a sponsor fund nor this flag throws
+     * `OracleFeeSourceUnavailable` instead of silently drawing from `tx.gas`
+     * (Enoki-sponsored transactions reject any `tx.gas` draw). Default:
+     * `false`.
+     */
+    allowGasFee?: boolean;
     /**
      * Pre-sweep parked backing assets (USDC, USDsui, …) at the wxa account's
      * address into USD credit, plus any CREDIT coins/funds at the address into
@@ -42,6 +57,15 @@ export interface CommonBuildOpts {
      * {@link buildConsolidateToUsdTx} separately.
      */
     consolidateToUsd?: boolean;
+    /**
+     * BE prefetch-cache seam for the oracle update-data fetch — forwarded
+     * verbatim into `refreshOraclePrices`'s `updateDataProvider` opt (see
+     * `UpdateDataProvider` in `oracle/price-update-rule.ts`). Default: none
+     * (always a live fetch). A caller-supplied provider that misses or throws
+     * still falls back to a live fetch — this option can only make a refresh
+     * faster, never break it.
+     */
+    updateDataProvider?: UpdateDataProvider;
 }
 interface RequestParams {
     ticker: string;
@@ -57,20 +81,33 @@ export declare function newTx(opts?: CommonBuildOpts): Transaction;
  */
 export declare function refreshWlpPoolOracles(tx: Transaction, client: PerpClient, extraTickers: string[], opts: {
     cache?: PythCache;
-    sponsorFund?: {
-        fund: TransactionArgument;
-        packageId: string;
-    };
+    /** Forwarded to `refreshOraclePrices` — already resolved by the caller (see `OracleFeeSource`). */
+    feeSource?: OracleFeeSource;
     lpType?: string;
+    updateDataProvider?: UpdateDataProvider;
 }): Promise<void>;
 /**
- * Build the *Request + execute envelope with optional Pyth sponsor flow:
+ * Build the *Request + execute envelope with the config-driven Pyth sponsor flow:
  *
+ *   [maybeConsolidate(tx)]
  *   [fund = sponsor.request()]
- *   refreshOraclePrices(..., sponsorFund?)
+ *   refreshOraclePrices(..., feeSource?)
  *   req = buildRequest()
  *   [sponsor.reimburse(fund, req)]
  *   trading::execute(req)
+ *
+ * Accepted ordering caveat: `maybeConsolidate` runs FIRST and can itself
+ * append PTB commands (the consolidation sweep) before the fee-source check
+ * inside `refreshOraclePrices` ever runs — so an `OracleFeeSourceUnavailable`
+ * throw here is NOT the "zero commands appended" guarantee
+ * `refreshOraclePrices` gives its own callers (see its docblock in
+ * `aggregate.ts`); `tx` can already carry the sweep. This is the same
+ * discard-tx-on-throw contract every `build*Tx` composer already has for
+ * mid-build on-chain-read failures — not a new hole. It matters only for a
+ * caller that passed in their OWN `opts.tx` (reusing one `Transaction`
+ * across builder calls, e.g. to compose several actions in one PTB); such a
+ * caller must discard the whole `tx` on any throw from this function, not
+ * just retry the failed step.
  */
 export declare function wrapRequestAndExecute(client: PerpClient, tx: Transaction, req: RequestParams & {
     accountId: string;

package/dist/cjs/src/perp/tx-builders/common.js

@@ -29,32 +29,65 @@ async function refreshWlpPoolOracles(tx, client, extraTickers, opts) {
     const oracleTickers = Array.from(new Set([...extraTickers, ...poolTickers]));
     await (0, index_ts_1.refreshOraclePrices)(tx, client, oracleTickers, {
         cache: opts.cache,
-        sponsorFund: opts.sponsorFund,
+        feeSource: opts.feeSource,
+        updateDataProvider: opts.updateDataProvider,
     });
     for (const tokenType of Object.values(client.config.packages.wlp.pool_tokens)) {
         (0, wlp_ts_1.updateTokenValue)(client, tx, { tokenType, lpType: opts.lpType });
     }
 }
 /**
- * Build the *Request + execute envelope with optional Pyth sponsor flow:
+ * Build the *Request + execute envelope with the config-driven Pyth sponsor flow:
  *
+ *   [maybeConsolidate(tx)]
  *   [fund = sponsor.request()]
- *   refreshOraclePrices(..., sponsorFund?)
+ *   refreshOraclePrices(..., feeSource?)
  *   req = buildRequest()
  *   [sponsor.reimburse(fund, req)]
  *   trading::execute(req)
+ *
+ * Accepted ordering caveat: `maybeConsolidate` runs FIRST and can itself
+ * append PTB commands (the consolidation sweep) before the fee-source check
+ * inside `refreshOraclePrices` ever runs — so an `OracleFeeSourceUnavailable`
+ * throw here is NOT the "zero commands appended" guarantee
+ * `refreshOraclePrices` gives its own callers (see its docblock in
+ * `aggregate.ts`); `tx` can already carry the sweep. This is the same
+ * discard-tx-on-throw contract every `build*Tx` composer already has for
+ * mid-build on-chain-read failures — not a new hole. It matters only for a
+ * caller that passed in their OWN `opts.tx` (reusing one `Transaction`
+ * across builder calls, e.g. to compose several actions in one PTB); such a
+ * caller must discard the whole `tx` on any throw from this function, not
+ * just retry the failed step.
  */
 async function wrapRequestAndExecute(client, tx, req, collateralTicker, opts, buildRequest) {
     await maybeConsolidate(client, tx, req.accountId, opts);
-    const useSponsor = opts?.useSponsor ?? true;
+    // Fee source + witness attachment is config-driven, not a caller flag: the
+    // sponsor fund is opened (and later reimbursed) whenever this client's
+    // config has `pyth_sponsor_rule` deployed — regardless of the deprecated
+    // `useSponsor` flag (see its JSDoc). `allowGasFee` is the only caller lever
+    // left, and it only matters when config has NO sponsor rule to open (see
+    // `OracleFeeSourceUnavailable` in `oracle/pyth.ts`).
+    //
+    // `feeSource` is resolved HERE, once, from that same decision — sponsor
+    // beats gas structurally because this is the only branch that ever sees
+    // both candidates; everything downstream (`refreshWlpPoolOracles` →
+    // `refreshOraclePrices` → `BuildUpdateOpts` → `PythCoreRule` →
+    // `buildPythPriceUpdateCalls`) just carries the single resolved value.
     let sponsorFund;
-    if (useSponsor)
+    if (client.config.packages.pyth_sponsor_rule) {
         sponsorFund = (0, index_ts_1.openPythSponsorFund)(tx, client);
+    }
+    const feeSource = sponsorFund
+        ? { kind: "sponsor", ...sponsorFund }
+        : opts?.allowGasFee
+            ? { kind: "gas" }
+            : undefined;
     if (!opts?.skipOraclePriceRefresh) {
         await refreshWlpPoolOracles(tx, client, [req.ticker, collateralTicker], {
             cache: opts?.pythCache,
-            sponsorFund,
+            feeSource,
             lpType: req.lpType,
+            updateDataProvider: opts?.updateDataProvider,
         });
     }
     const tradingReq = buildRequest(sponsorFund);

package/dist/cjs/src/perp/tx-builders/wlp.d.ts

@@ -17,9 +17,15 @@ export interface BuildMintWlpParams extends MintWlpParams, CommonBuildOpts {
  * `last_price_refresh_timestamp` so `assert_prices_fresh` inside
  * `mint_wlp` passes.
  *
- * Does NOT use the pyth_sponsor flow — `mint_wlp` produces no
+ * Never uses the pyth_sponsor flow — `mint_wlp` produces no
  * `TradingRequest`, so there's nothing for the sponsor to attach its
- * witness to. Pyth update fees come from `tx.gas`.
+ * witness to, and `pyth_sponsor_rule::reimburse` cannot consume a Fund
+ * without one. So when `skipOraclePriceRefresh` is `false` (the refresh
+ * actually runs), the caller MUST pass `allowGasFee: true` — the Pyth
+ * update fee is drawn from `tx.gas`, which Enoki-sponsored transactions
+ * reject; a sponsored caller should keep `skipOraclePriceRefresh: true`
+ * instead and rely on freshness from other trade traffic (see
+ * `OracleFeeSourceUnavailable` in `oracle/pyth.ts`).
  */
 export declare function buildMintWlpTx(client: PerpClient, params: BuildMintWlpParams): Promise<Transaction>;
 export interface BuildMintAndStakeWlpParams extends BuildMintWlpParams {
@@ -62,7 +68,9 @@ export interface BuildUnstakeAndRequestRedeemWlpParams extends Omit<RequestRedee
  * Refreshes every WLP pool-token oracle by default — `request_redeem` runs
  * `assert_prices_fresh` internally, so a stale oracle would abort the PTB.
  * Pass `skipOraclePriceRefresh: true` only when the caller is composing this
- * into a larger PTB that already pre-pumps prices.
+ * into a larger PTB that already pre-pumps prices. Like `buildMintWlpTx`,
+ * `request_redeem` produces no `TradingRequest`, so a non-skipped refresh
+ * requires `allowGasFee: true` (see `buildMintWlpTx`'s doc comment).
  */
 export declare function buildUnstakeAndRequestRedeemWlpTx(client: PerpClient, params: BuildUnstakeAndRequestRedeemWlpParams): Promise<Transaction>;
 export interface BuildCancelRedeemAndStakeWlpParams extends CancelRedeemWlpParams, CommonBuildOpts {

package/dist/cjs/src/perp/tx-builders/wlp.js

@@ -18,17 +18,29 @@ const common_ts_1 = require("./common.js");
  * `last_price_refresh_timestamp` so `assert_prices_fresh` inside
  * `mint_wlp` passes.
  *
- * Does NOT use the pyth_sponsor flow — `mint_wlp` produces no
+ * Never uses the pyth_sponsor flow — `mint_wlp` produces no
  * `TradingRequest`, so there's nothing for the sponsor to attach its
- * witness to. Pyth update fees come from `tx.gas`.
+ * witness to, and `pyth_sponsor_rule::reimburse` cannot consume a Fund
+ * without one. So when `skipOraclePriceRefresh` is `false` (the refresh
+ * actually runs), the caller MUST pass `allowGasFee: true` — the Pyth
+ * update fee is drawn from `tx.gas`, which Enoki-sponsored transactions
+ * reject; a sponsored caller should keep `skipOraclePriceRefresh: true`
+ * instead and rely on freshness from other trade traffic (see
+ * `OracleFeeSourceUnavailable` in `oracle/pyth.ts`).
  */
 async function buildMintWlpTx(client, params) {
     const tx = (0, common_ts_1.newTx)(params);
     await (0, common_ts_1.maybeConsolidate)(client, tx, params.accountId, params);
+    // `mint_wlp` has no sponsor flow to resolve against (see the doc comment
+    // above) — the only candidate source at this edge is the caller's
+    // ergonomic `allowGasFee` opt-in.
+    const feeSource = params.allowGasFee ? { kind: "gas" } : undefined;
     if (!params.skipOraclePriceRefresh) {
         await (0, common_ts_1.refreshWlpPoolOracles)(tx, client, [params.depositTicker], {
             cache: params.pythCache,
             lpType: params.lpType,
+            feeSource,
+            updateDataProvider: params.updateDataProvider,
         });
     }
     (0, wlp_ts_1.mintWlp)(client, tx, params);
@@ -46,10 +58,16 @@ async function buildMintWlpTx(client, params) {
 async function buildMintAndStakeWlpTx(client, params) {
     const tx = (0, common_ts_1.newTx)(params);
     await (0, common_ts_1.maybeConsolidate)(client, tx, params.accountId, params);
+    // `mint_wlp` has no sponsor flow to resolve against (see `buildMintWlpTx`'s
+    // doc comment) — the only candidate source at this edge is the caller's
+    // ergonomic `allowGasFee` opt-in.
+    const feeSource = params.allowGasFee ? { kind: "gas" } : undefined;
     if (!params.skipOraclePriceRefresh) {
         await (0, common_ts_1.refreshWlpPoolOracles)(tx, client, [params.depositTicker], {
             cache: params.pythCache,
             lpType: params.lpType,
+            feeSource,
+            updateDataProvider: params.updateDataProvider,
         });
     }
     const stakeAlias = params.stakeAlias ?? "WLP";
@@ -71,16 +89,24 @@ async function buildMintAndStakeWlpTx(client, params) {
  * Refreshes every WLP pool-token oracle by default — `request_redeem` runs
  * `assert_prices_fresh` internally, so a stale oracle would abort the PTB.
  * Pass `skipOraclePriceRefresh: true` only when the caller is composing this
- * into a larger PTB that already pre-pumps prices.
+ * into a larger PTB that already pre-pumps prices. Like `buildMintWlpTx`,
+ * `request_redeem` produces no `TradingRequest`, so a non-skipped refresh
+ * requires `allowGasFee: true` (see `buildMintWlpTx`'s doc comment).
  */
 async function buildUnstakeAndRequestRedeemWlpTx(client, params) {
     const tx = (0, common_ts_1.newTx)(params);
     const stakeAlias = params.stakeAlias ?? "WLP";
     await (0, common_ts_1.maybeConsolidate)(client, tx, params.accountId, params);
+    // `request_redeem` has no sponsor flow to resolve against (see
+    // `buildMintWlpTx`'s doc comment) — the only candidate source at this edge
+    // is the caller's ergonomic `allowGasFee` opt-in.
+    const feeSource = params.allowGasFee ? { kind: "gas" } : undefined;
     if (!params.skipOraclePriceRefresh) {
         await (0, common_ts_1.refreshWlpPoolOracles)(tx, client, [], {
             cache: params.pythCache,
             lpType: params.lpType,
+            feeSource,
+            updateDataProvider: params.updateDataProvider,
         });
     }
     (0, staking_ts_1.unstake)(client, tx, {

package/dist/cjs/src/perp/tx-builders.d.ts

@@ -3,9 +3,9 @@
  *
  * Each `build*Tx` composer creates (or appends to) a `Transaction`, refreshes
  * the on-chain `Oracle` via Pyth, optionally pre-sweeps parked balances
- * (`consolidateToUsd`), wires the `pyth_sponsor_rule` flow when enabled, and
- * calls the matching `*_request` + `execute`. Implementations are split by
- * domain under `tx-builders/`:
+ * (`consolidateToUsd`), wires the `pyth_sponsor_rule` flow when deployed in
+ * config, and calls the matching `*_request` + `execute`. Implementations are
+ * split by domain under `tx-builders/`:
  *
  *   common.ts       CommonBuildOpts + request/execute envelope + oracle refresh
  *   consolidate.ts  parked-balance → wxUSD pre-sweep (appendConsolidate*)

package/dist/cjs/src/perp/tx-builders.js

@@ -4,9 +4,9 @@
  *
  * Each `build*Tx` composer creates (or appends to) a `Transaction`, refreshes
  * the on-chain `Oracle` via Pyth, optionally pre-sweeps parked balances
- * (`consolidateToUsd`), wires the `pyth_sponsor_rule` flow when enabled, and
- * calls the matching `*_request` + `execute`. Implementations are split by
- * domain under `tx-builders/`:
+ * (`consolidateToUsd`), wires the `pyth_sponsor_rule` flow when deployed in
+ * config, and calls the matching `*_request` + `execute`. Implementations are
+ * split by domain under `tx-builders/`:
  *
  *   common.ts       CommonBuildOpts + request/execute envelope + oracle refresh
  *   consolidate.ts  parked-balance → wxUSD pre-sweep (appendConsolidate*)

package/dist/cjs/src/unified-client.d.ts

@@ -32,6 +32,8 @@ import { Transaction } from "@mysten/sui/transactions";
 import * as accountOps from "./account/index.ts";
 import * as perpReferral from "./account/referral.ts";
 import type { Network } from "./constants.ts";
+import type { PythGeneration } from "./oracle/config.ts";
+import type { OracleSource } from "./oracle/price-update-rule.ts";
 import { PerpClient, type CreateClientOptions as PerpCreateOptions } from "./perp/client.ts";
 import * as perpFetch from "./perp/fetch.ts";
 import * as perpTx from "./perp/tx-builders.ts";
@@ -363,6 +365,21 @@ export interface ClientCreateOptions {
     waterxConfigUrl?: string;
     /** Memoize the fetched config JSON. */
     cache?: boolean;
+    /**
+     * Selects which `PriceUpdateRule` the perp line's `refreshOraclePrices` uses
+     * for the on-chain price-update leg (see `OracleHost.oracleSource`).
+     * Default: `'pyth_rule'`. Perp-line only. The SDK never reads `process.env`
+     * — pass this from your own env var (e.g. `ORACLE_SOURCE`).
+     */
+    oracleSource?: OracleSource;
+    /**
+     * Selects which Pyth Core contract generation feeds the perp line's
+     * `client.perp.pyth` when the config JSON has no explicit `pyth` override:
+     * `'core'` (default) or `'pro'` (post-2026-08-18 Pro-compatible contracts +
+     * Hermes-compatible endpoint; pair with `pyth.api_key`). Perp-line only.
+     * See `PythGeneration` / `PYTH_PRO_DEFAULTS`.
+     */
+    pythGeneration?: PythGeneration;
     /** Perp-line overrides (network, grpcUrl, waterxConfigUrl, cache, …). */
     perp?: PerpLineOptions;
     /** Prediction-line overrides (network, grpcUrl, waterxConfigUrl, cache, settlement, …). */

package/dist/cjs/src/unified-client.js

@@ -204,6 +204,8 @@ class WaterXClient {
             grpcUrl: opts.grpcUrl,
             waterxConfigUrl: opts.waterxConfigUrl,
             cache: opts.cache,
+            oracleSource: opts.oracleSource,
+            pythGeneration: opts.pythGeneration,
             ...perpRest,
         });
         const predictClient = await client_ts_2.PredictClient.create(resolvedPredictNetwork, {

package/dist/src/oracle/aggregate.d.ts

@@ -2,40 +2,58 @@
  * Oracle aggregation — the orchestrator that composes rules into the shared
  * `Oracle`. This is the ONE file that knows about every rule: it builds a
  * `PriceCollector`, feeds whichever rules a ticker is configured for
- * (Pyth / Supra / Constant), then `aggregate`s.
+ * (Pyth / Lazer / Supra / Constant), then `aggregate`s.
  *
  * Per ticker:
  *   collector = oracle::new_collector(ticker)
  *   [pyth_rule::feed]       when the ticker has a pyth_rule.feeds entry
+ *   [pyth_lazer_rule::feed] when the update leg produced a verified lazer Update
  *   [supra_rule::feed]      when supra is enabled + wired
  *   [constant_rule::feed]   when the ticker is a constant ticker
  *   oracle::aggregate(oracle, collector)
  *
- * The fed rule set must match the on-chain weighted set for the ticker —
+ * The fed rule set must cover the on-chain weighted set for the ticker —
  * `aggregator::remove_outliers` aborts `EMissingPriceSource` if a weighted rule
- * is missing from the collector.
+ * is missing from the collector (an abstaining feed call counts as present;
+ * a fed-but-unweighted rule is silently dropped).
+ *
+ * `refreshOraclePrices` additionally routes the on-chain price *update* leg
+ * (the fetch + verify/push step, before any of the above feeding) through the
+ * `PriceUpdateRule` selected by `host.oracleSource` — see `rule-registry.ts`.
  */
 import type { Transaction, TransactionArgument } from "@mysten/sui/transactions";
 import type { OracleHost } from "./host.ts";
-import { type PythCache } from "./pyth.ts";
+import type { OracleSource, PriceUpdateRule, UpdateDataProvider } from "./price-update-rule.ts";
+import { type OracleFeeSource, type PythCache } from "./pyth.ts";
 /**
  * Aggregate one ticker's price into the shared `Oracle`: build a collector, feed
  * every rule the ticker is configured for, then `aggregate`.
  *
  * - **Pyth** — fed when `priceInfoObjectId` is supplied (i.e. the ticker has a
- *   `pyth_rule.feeds` entry). Caller must run the Pyth update first so the
- *   `PriceInfoObject` is fresh.
- * - **Supra** — fed alongside Pyth when supra is enabled + wired (abstains
- *   on-chain for symbols it has no pair for).
+ *   `pyth_rule.feeds` entry). When this PTB's update leg refreshed the
+ *   `PriceInfoObject` it contributes a fresh price; when it did not (a
+ *   lazer-routed ticker), the on-chain rule only READS the object and abstains
+ *   if it is stale — it never aborts — so the call stays mandatory while
+ *   `pyth_rule` remains in the ticker's on-chain weighted set
+ *   (`EMissingPriceSource` requires every weighted rule to appear).
+ * - **Lazer** — fed when `lazerUpdate` is supplied: the verified
+ *   `pyth_lazer::update::Update` produced by this PTB's lazer update leg
+ *   (see `PythLazerRule.buildUpdateCalls`). If the ticker's aggregator does
+ *   not (yet) weight `PythLazerRule`, the contribution is silently dropped
+ *   on-chain — feeding ahead of the weight migration is harmless.
+ * - **Supra** — fed alongside Pyth/Lazer when supra is enabled + wired
+ *   (abstains on-chain for symbols it has no pair for).
  * - **Constant** — fed when the ticker is a constant ticker
  *   ({@link OracleHost.isConstantTicker}).
  *
- * "Dual-feed" (Pyth + Constant) and "constant-only" are not special cases — they
- * fall out of which rules the ticker is in. Throws if no rule applies.
+ * "Dual-feed" (Pyth + Constant, or Pyth + Lazer) and "constant-only" are not
+ * special cases — they fall out of which rules the ticker is in. Throws if no
+ * rule applies.
  */
 export declare function aggregateTicker(tx: Transaction, host: OracleHost, args: {
     ticker: string;
     priceInfoObjectId?: string;
+    lazerUpdate?: TransactionArgument;
 }): void;
 /**
  * Thin wrapper over {@link aggregateTicker} for a Pyth-fed ticker. Kept for
@@ -61,14 +79,77 @@ export declare function aggregateTickerWithConstant(tx: Transaction, host: Oracl
 /**
  * Refresh multiple tickers in one PTB. For each ticker {@link aggregateTicker}
  * feeds whichever rules it is configured for (Pyth if it has a `pyth_rule.feeds`
- * entry, Supra when enabled, Constant when it's a constant ticker). Tickers with a
- * Pyth feed are updated on-chain via one shared Pyth accumulator first; the rest
- * (constant-only) skip Pyth entirely.
+ * entry, Lazer if the lazer update leg served it — see below — Supra when
+ * enabled, Constant when it's a constant ticker).
+ *
+ * Before that, the on-chain price *update* leg is routed by `host.oracleSource`
+ * (see `rule-registry.ts`): the selected rule serves every ticker in its
+ * `supportedTickers(host)`; tickers it doesn't cover fall back to `pyth_rule`
+ * (`PythCoreRule`) when THEY support it — so when `oracleSource` IS `'pyth_rule'`
+ * there is exactly one group, identical to the pre-routing behavior. A ticker
+ * supported by neither is simply skipped from this leg (no fetch/build call for
+ * it) — the same way today's non-pyth tickers (e.g. constant-only) always were;
+ * it still gets aggregated below via whichever rule {@link aggregateTicker} finds.
+ *
+ * Each group's fetch + build runs against its own rule, which guarantees
+ * per-rule PTB atomicity (no mixed-generation payload within one rule's calls).
+ * When `oracleSource` isn't `'pyth_rule'`, one PTB may legitimately carry BOTH a
+ * non-Pyth-Core block (selected group) and a Pyth Core block (fallback group) —
+ * each verifies against its own contract objects, so that's fine. A fee-source
+ * pre-check runs first, across every group's `requiresFeeSource` — BEFORE any
+ * off-chain fetch or PTB mutation — so a fee-charging group with no
+ * `opts.feeSource` throws `OracleFeeSourceUnavailable` with zero wasted
+ * network calls and zero stray moveCalls, even in a mixed shape (e.g. a
+ * fee-free Lazer group ordered ahead of a Pyth Core fallback group). Only once
+ * that check passes do all groups' off-chain fetches run concurrently
+ * (`Promise.all`) and complete before any PTB mutation; on-chain reads inside
+ * `buildUpdateCalls` can still fail mid-append for other reasons — callers
+ * discard the tx on any throw.
+ *
+ * **Collector-feed leg is rule-aware:** a lazer-served group's
+ * `buildUpdateCalls` returns the verified `Update` PTB value
+ * ({@link RuleUpdateHandle}), and every ticker in that group is aggregated
+ * with `lazerUpdate` set so {@link aggregateTicker} appends
+ * `pyth_lazer_rule::feed` against it. A lazer-routed ticker that still has a
+ * `pyth_rule.feeds` entry ALSO keeps its `pyth_rule::feed` leg — required
+ * on-chain while `pyth_rule` stays in the ticker's weighted set
+ * (`aggregator::remove_outliers` aborts `EMissingPriceSource` unless every
+ * weighted rule appears in the collector; an abstention counts as
+ * appearing), and safe: `pyth_rule::feed` only READS the `PriceInfoObject`
+ * this PTB never refreshed and abstains when it is stale rather than
+ * aborting. Conversely, a lazer feed call on an aggregator that does not
+ * (yet) weight `PythLazerRule` is silently dropped on-chain — so
+ * lazer-routing a ticker ahead of its on-chain weight migration prices it
+ * from the remaining weighted rules instead of failing.
  */
 export declare function refreshOraclePrices(tx: Transaction, host: OracleHost, tickers: string[], opts?: {
     cache?: PythCache;
-    sponsorFund?: {
-        fund: TransactionArgument;
-        packageId: string;
-    };
+    /**
+     * The single resolved fee source for the Pyth update fee, forwarded
+     * verbatim to each group's `PriceUpdateRule.buildUpdateCalls` as
+     * `BuildUpdateOpts.feeSource`. Already-resolved by the caller (see
+     * {@link OracleFeeSource}'s own doc for where/how) — this function makes
+     * no sponsor-vs-gas decision itself, it only checks whether a source was
+     * resolved at all. Ignored by rules with no update fee (e.g.
+     * `pyth_lazer_rule`). Building with `feeSource` unset throws
+     * `OracleFeeSourceUnavailable` (see `oracle/pyth.ts`) instead of
+     * silently drawing from `tx.gas`.
+     */
+    feeSource?: OracleFeeSource;
+    /**
+     * @internal Test-only: layer fake `PriceUpdateRule`s on top of the
+     * production registry (see `rule-registry.ts`'s `resolveOracleRule`).
+     * Production callers never set this — routing is by `host.oracleSource`
+     * alone.
+     */
+    ruleOverrides?: Partial<Record<OracleSource, PriceUpdateRule>>;
+    /**
+     * BE prefetch-cache seam: checked per group BEFORE that group's live
+     * `rule.fetchUpdateData`. See {@link UpdateDataProvider}. A cache miss
+     * (`null`) or a throw from the provider falls back to the live fetch —
+     * a degraded/broken cache must never break the money path; a
+     * kind-mismatched hit (the provider handed back the wrong rule's
+     * payload) throws instead, since that is a caller bug, not a cache miss.
+     */
+    updateDataProvider?: UpdateDataProvider;
 }): Promise<void>;