@waterx/sdk 3.1.1 → 4.0.0

package/README.md

@@ -99,6 +99,42 @@ const predict = await PredictClient.create("TESTNET", { waterxConfigUrl }); // o
 
 Read-only queries use gRPC `simulateTransaction` (no signer) — the `getX` view helpers, e.g. `await perp.simulate(tx)` or `getMarketData(perp, …)`.
 
+## Oracle sources & the Pyth Pro migration
+
+Two independent client create options control oracle behavior. The SDK **never reads `process.env`** — each consumer wires them from its own env vars, so every environment runs the **same SDK version** and differs only by env:
+
+| Option | Values | What it flips |
+|--------|--------|---------------|
+| `oracleSource` | `'pyth_rule'` (default) \| `'pyth_lazer_rule'` | Which `PriceUpdateRule` `refreshOraclePrices` uses for the on-chain price-update leg. |
+| `pythGeneration` | `'core'` (default) \| `'pro'` | Which Pyth infra constants feed `client.pyth` when the config JSON has no explicit `pyth` block: `PYTH_DEFAULTS` (original contracts, keyless `hermes.pyth.network`) or `PYTH_PRO_DEFAULTS` (post-2026-08-18 Pro-compatible contracts + the Hermes-compatible `https://pyth.dourolabs.app/hermes`, auth-first). |
+
+They are orthogonal: `pythGeneration` moves the Pyth **Core** state ids + endpoint; `oracleSource` picks the **rule** (Core VAA vs Lazer signed updates). An explicit `pyth` block in the config JSON always overrides the generation constants wholesale.
+
+```ts
+// Per-environment wiring — the consumer owns the env vars, not the SDK:
+const perp = await PerpClient.create(network, {
+  waterxConfigUrl,
+  oracleSource: process.env.ORACLE_SOURCE as OracleSource | undefined, // e.g. staging: pyth_lazer_rule
+  pythGeneration: process.env.PYTH_GENERATION as PythGeneration | undefined, // e.g. staging: pro
+});
+// After the 2026-08-18 cutover, Pro-generation Hermes requires a key:
+perp.pyth = { ...perp.pyth, api_key: process.env.PYTH_API_KEY };
+```
+
+This is the staging-Pro / prod-Core rollout pattern: staging sets `ORACLE_SOURCE=pyth_lazer_rule` and/or `PYTH_GENERATION=pro` while production leaves both unset (Core defaults) — flipping an environment is an env-var change, never an SDK release. After August 18, 2026 (the Core-upgrade cutover — see https://docs.pyth.network/price-feeds/core/upgrade), consumers set `pythGeneration: 'pro'` + `pyth.api_key`.
+
+### Adding an oracle source (runbook)
+
+Every rule generation plugs in the same way — routing is driven **only** by the client's `oracleSource` option (never a config `enabled` flag, never `process.env`):
+
+1. **Implement `PriceUpdateRule`** in `src/oracle/rules/<name>-rule.ts` — all port fields (`src/oracle/price-update-rule.ts`): `kind`, `requiresFeeSource` (`true` iff the on-chain verify draws a per-update fee — gates the fail-fast fee-source check), `supportedTickers`, `fetchUpdateData`, `narrowUpdateData` (subset a cached whole-universe payload to one build's tickers — a divisible payload returns a per-feed subset, an indivisible one returns itself whole iff fully covered; uncovered ticker → `null` miss), `buildUpdateCalls`.
+2. **Register it** in `src/oracle/rule-registry.ts` (`DEFAULT_RULES`) under a new `OracleSource` value (added to the union in `price-update-rule.ts`).
+3. **Publish the on-chain rule package** — its config entry (package ids, per-ticker `feeds`) arrives via the normal `waterx-config` deploy pipeline; type it in `OraclePackages` (`src/oracle/config.ts`).
+4. **Add SDK infra constants** if the source needs external infra that is not part of the config JSON (API endpoints, verifier packages, state objects) — a per-network map in `src/oracle/config.ts`, mirroring `LAZER_DEFAULTS` / `PYTH_PRO_DEFAULTS`.
+5. **Consumers flip `ORACLE_SOURCE`** per environment — no consumer code change, no SDK re-release.
+
+The in-house `waterx_rule` (ed25519 enclave-signed CEX prices) follows exactly this path when it lands.
+
 ## Recipes & full surface
 
 To avoid doc drift, per-action usage lives in maintained, lint-checked code rather than this README:

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

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

@@ -3,18 +3,24 @@
  * 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`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.aggregateTicker = aggregateTicker;
@@ -23,23 +29,77 @@ exports.aggregateTickerWithConstant = aggregateTickerWithConstant;
 exports.refreshOraclePrices = refreshOraclePrices;
 const oracle_ts_1 = require("../generated/waterx_oracle/oracle.js");
 const pyth_ts_1 = require("./pyth.js");
+const rule_registry_ts_1 = require("./rule-registry.js");
 const constant_rule_ts_1 = require("./rules/constant-rule.js");
+const pyth_lazer_rule_ts_1 = require("./rules/pyth-lazer-rule.js");
 const pyth_rule_ts_1 = require("./rules/pyth-rule.js");
 const supra_rule_ts_1 = require("./rules/supra-rule.js");
+/**
+ * Resolve one group's off-chain update payload for {@link refreshOraclePrices}:
+ * try `provider.get(source, tickers)` first (when a provider is configured),
+ * falling back to the group's own live `rule.fetchUpdateData` on a cache miss
+ * (`null`) or a throw from the provider — a broken/degraded cache must never
+ * break the money path.
+ *
+ * A cache HIT is treated as a payload for a POSSIBLY-WIDER ticker set (a
+ * provider commonly caches one whole-universe payload per source — see
+ * {@link UpdateDataProvider}), so it is narrowed to exactly `group.tickers`
+ * via `rule.narrowUpdateData` before use. This is load-bearing, not
+ * defensive: without it a Pyth Core hit would emit an
+ * `update_single_price_feed` — and charge its fee — for every cached feed
+ * instead of just this group's, and a payload that cannot cover the group
+ * (`narrowUpdateData` → `null`) would never reach the live-fetch fallback.
+ * Each rule owns its own subsetting (Core subsets per-feed entries; Lazer's
+ * indivisible payload passes whole iff fully covered), so the orchestrator
+ * never branches on `kind` here. A hit whose `kind` doesn't match the
+ * group's rule is a caller bug (the provider handed back a different rule's
+ * payload), so that throws — via `narrowUpdateData`'s own
+ * `assertRuleUpdateData` guard — instead of silently falling back.
+ */
+async function resolveGroupUpdateData(host, group, provider) {
+    if (provider) {
+        let cached = null;
+        try {
+            cached = await provider.get(group.source, group.tickers);
+        }
+        catch {
+            // Provider errors must never break the money path — fall through to
+            // the live fetch below exactly as a cache miss (`null`) would.
+        }
+        if (cached !== null) {
+            // Wrong-kind hit throws inside narrowUpdateData (assertRuleUpdateData);
+            // a hit that can't cover the group narrows to null → live-fetch below.
+            const narrowed = group.rule.narrowUpdateData(host, cached, group.tickers);
+            if (narrowed !== null)
+                return narrowed;
+        }
+    }
+    return group.rule.fetchUpdateData(host, group.tickers);
+}
 /**
  * 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.
  */
 function aggregateTicker(tx, host, args) {
     const oraclePkg = host.config.packages.waterx_oracle.published_at;
@@ -50,16 +110,22 @@ function aggregateTicker(tx, host, args) {
     let fed = false;
     if (args.priceInfoObjectId) {
         (0, pyth_rule_ts_1.feedPythRule)(tx, host, collector, args.priceInfoObjectId);
+        fed = true;
+    }
+    if (args.lazerUpdate !== undefined) {
+        (0, pyth_lazer_rule_ts_1.feedLazerRule)(tx, host, collector, args.lazerUpdate);
+        fed = true;
+    }
+    if (fed) {
         // Supra rides on the same collector when enabled (abstains on-chain otherwise).
         (0, supra_rule_ts_1.maybeFeedSupra)(tx, host, collector);
-        fed = true;
     }
     if (host.isConstantTicker(args.ticker)) {
         (0, constant_rule_ts_1.feedConstantRule)(tx, host, collector);
         fed = true;
     }
     if (!fed) {
-        throw new Error(`no oracle rule configured for ticker '${args.ticker}' (no pyth feed, not a constant ticker)`);
+        throw new Error(`no oracle rule configured for ticker '${args.ticker}' (no pyth feed, no lazer update, not a constant ticker)`);
     }
     (0, oracle_ts_1.aggregate)({
         package: oraclePkg,
@@ -95,24 +161,128 @@ function aggregateTickerWithConstant(tx, host, args) {
 /**
  * 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.
  */
 async function refreshOraclePrices(tx, host, tickers, opts = {}) {
     if (tickers.length === 0)
         return;
-    // Every ticker with a pyth_rule.feeds entry needs the on-chain Pyth update
-    // first (one shared accumulator). Constant-only tickers (no pyth feed) skip it.
+    // price_info_object lookup for every ticker with a pyth_rule.feeds entry —
+    // needed by aggregateTicker's (unchanged) Pyth feed step below regardless of
+    // which rule performed the on-chain update for that ticker.
     const pythTickers = tickers.filter((t) => host.config.packages.pyth_rule?.feeds?.[t] !== undefined);
     const priceInfoByTicker = new Map();
-    if (pythTickers.length > 0) {
-        const entries = pythTickers.map((t) => host.getPythFeed(t));
-        await (0, pyth_ts_1.updatePythPrices)(tx, host, entries.map((e) => e.feed_id), opts.cache, opts.sponsorFund);
-        pythTickers.forEach((t, i) => priceInfoByTicker.set(t, entries[i].price_info_object));
+    pythTickers.forEach((t) => priceInfoByTicker.set(t, host.getPythFeed(t).price_info_object));
+    // Group tickers for the on-chain update leg: selected rule first, then the
+    // pyth_rule fallback for whatever the selected rule doesn't cover. `source`
+    // is tracked alongside each group (rather than read back off `rule.kind`,
+    // which is typed as the broader PriceUpdateRuleKind) so the provider lookup
+    // below has an OracleSource to key on without a cast.
+    const selectedRule = (0, rule_registry_ts_1.resolveOracleRule)(host.oracleSource, opts.ruleOverrides);
+    const selectedSupported = new Set(selectedRule.supportedTickers(host));
+    const selectedGroup = tickers.filter((t) => selectedSupported.has(t));
+    const groups = [];
+    if (selectedGroup.length > 0) {
+        groups.push({ source: host.oracleSource, rule: selectedRule, tickers: selectedGroup });
+    }
+    if (host.oracleSource !== "pyth_rule") {
+        const fallbackRule = (0, rule_registry_ts_1.resolveOracleRule)("pyth_rule", opts.ruleOverrides);
+        const fallbackSupported = new Set(fallbackRule.supportedTickers(host));
+        const fallbackGroup = tickers.filter((t) => !selectedSupported.has(t) && fallbackSupported.has(t));
+        if (fallbackGroup.length > 0) {
+            groups.push({ source: "pyth_rule", rule: fallbackRule, tickers: fallbackGroup });
+        }
+    }
+    // Fee-source pre-check, hoisted ABOVE both the off-chain fetch below AND
+    // the per-group build loop further down. The condition only consults
+    // `group.rule.requiresFeeSource` — known the moment `groups` is built,
+    // before any fetch or PTB mutation — so this throws with ZERO wasted
+    // network calls and zero PTB commands. A per-call guard inside
+    // `buildPythPriceUpdateCalls` alone would not be early enough: in a mixed
+    // shape (e.g. a lazer-selected `oracleSource` with a `pyth_rule` fallback
+    // group for tickers Lazer doesn't cover), the build loop runs each
+    // group's `buildUpdateCalls` in sequence — a fee-free group ordered ahead
+    // of a fee-charging one would already have appended its verify/feed
+    // moveCalls to the shared `tx` by the time the fee-charging group's own
+    // guard fired, breaking the "throw before any PTB mutation" guarantee.
+    // Checking every group's `requiresFeeSource` up front — before ANY group
+    // fetches or builds — closes that gap, and (unlike a referential check
+    // against a specific rule instance) keeps protecting a future
+    // fee-charging rule or a test double standing in for one.
+    if (!opts.feeSource && groups.some((group) => group.rule.requiresFeeSource)) {
+        throw new pyth_ts_1.OracleFeeSourceUnavailableError();
+    }
+    // Fetch every group's off-chain payload concurrently (independent network
+    // calls — no reason to serialize) and let ALL of them settle before the
+    // first PTB mutation below, so a later group's fetch failure can never
+    // leave an earlier group's moveCalls stranded in a caller-owned tx.
+    const groupsWithData = await Promise.all(groups.map(async (group) => ({
+        rule: group.rule,
+        tickers: group.tickers,
+        data: await resolveGroupUpdateData(host, group, opts.updateDataProvider),
+    })));
+    // Verified-`Update` handle per lazer-served ticker (one shared PTB value per
+    // group) — consumed by the collector-feed leg below.
+    const lazerUpdateByTicker = new Map();
+    for (const group of groupsWithData) {
+        const handle = (await group.rule.buildUpdateCalls(tx, host, group.data, {
+            cache: opts.cache,
+            feeSource: opts.feeSource,
+        })) ?? undefined;
+        // Route by the handle's kind discriminant — the one site the tag exists to
+        // protect: a future non-lazer handle (e.g. a WaterxRule value) must never
+        // be silently fed into pyth_lazer_rule::feed.
+        if (handle?.kind === "pyth_lazer_rule") {
+            for (const ticker of group.tickers)
+                lazerUpdateByTicker.set(ticker, handle.update);
+        }
     }
     // Aggregate each ticker, feeding whichever rules it is configured for.
     for (const ticker of tickers) {
-        aggregateTicker(tx, host, { ticker, priceInfoObjectId: priceInfoByTicker.get(ticker) });
+        aggregateTicker(tx, host, {
+            ticker,
+            priceInfoObjectId: priceInfoByTicker.get(ticker),
+            lazerUpdate: lazerUpdateByTicker.get(ticker),
+        });
     }
 }

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

@@ -22,6 +22,24 @@ export interface PythRulePackage extends BasePackageEntry {
 export interface PythSponsorRulePackage extends BasePackageEntry {
     pyth_sponsor: string;
 }
+/**
+ * `pyth_lazer_rule` deployment entry — present in the deployed testnet
+ * `waterx-config` JSON. Read by `PythLazerRule` (`rules/pyth-lazer-rule.ts`):
+ * `feeds` for ticker support + integer feed-id resolution, `state` for the
+ * verify call, `published_at`/`config` for the per-ticker feed call.
+ *
+ * `enabled` mirrors the JSON field verbatim but MUST NOT be read for routing —
+ * which rule prices a ticker is decided solely by the client's `oracleSource`
+ * create option (see `OracleHost.oracleSource`), never by this flag or any
+ * other config value.
+ */
+export interface PythLazerRulePackage extends BasePackageEntry {
+    config: string;
+    state: string;
+    enabled?: boolean;
+    /** Oracle ticker → integer Pyth Lazer feed id (distinct id scheme from `pyth_rule`'s hex `feed_id`). */
+    feeds: Record<string, number>;
+}
 /** Per-ticker `constant_rule` feed entry (mirrors the `pyth_rule.feeds` shape). */
 export interface ConstantFeedEntry {
     /**
@@ -77,6 +95,8 @@ export interface WaterxOraclePackage extends BasePackageEntry {
 export interface OraclePackages {
     pyth_rule: PythRulePackage;
     pyth_sponsor_rule?: PythSponsorRulePackage;
+    /** See {@link PythLazerRulePackage} — typed only, not read for routing. */
+    pyth_lazer_rule?: PythLazerRulePackage;
     constant_rule?: WaterxConstantRulePackage;
     supra_rule?: SupraRulePackage;
     waterx_oracle: WaterxOraclePackage;
@@ -85,8 +105,91 @@ export interface PythInfraConfig {
     state_id: string;
     wormhole_state_id: string;
     hermes_endpoint: string;
+    /**
+     * Pyth Pro / Lazer access token (`Authorization: Bearer …`) for
+     * `PythLazerRule`'s signed-update fetch — Lazer is auth-first, so there is
+     * no keyless default. Optional: Pyth-Core-only deployments never need it.
+     * Consumers pass it through client config (`config.pyth`); the SDK never
+     * reads `process.env`. Absent when a lazer-routed fetch runs →
+     * `LazerApiKeyMissing` is thrown at fetch time. As of the Pyth Pro
+     * migration (post-2026-08-18, per
+     * https://docs.pyth.network/price-feeds/core/upgrade) this is ALSO required
+     * for `pyth_rule`'s Hermes fetch (`fetchPriceFeedsUpdateData`) — see
+     * `fetch` below.
+     */
+    api_key?: string;
+    /**
+     * Retry/timeout policy override for the Hermes (`fetchPriceFeedsUpdateData`)
+     * and Lazer (`PythLazerRule`) off-chain update fetches — see
+     * `fetchWithPolicy` (`./update-fetch.ts`) for the full policy (backoff,
+     * which statuses retry, Bearer attachment). Optional: both fetches default
+     * to `fetchWithPolicy`'s built-in defaults (15s timeout, 2 retries) when
+     * unset.
+     */
+    fetch?: {
+        timeoutMs?: number;
+        retries?: number;
+    };
 }
 export declare const PYTH_DEFAULTS: Record<Network, PythInfraConfig>;
+/**
+ * Which Pyth Core contract generation feeds `host.pyth` when the config JSON
+ * carries no explicit `pyth` override:
+ *
+ * - `'core'` (default) — the original contracts + keyless Hermes
+ *   ({@link PYTH_DEFAULTS}).
+ * - `'pro'` — the Pro-compatible upgraded contracts + the Hermes-compatible
+ *   endpoint ({@link PYTH_PRO_DEFAULTS}); pair with `pyth.api_key` after the
+ *   2026-08-18 cutover.
+ *
+ * Resolved once at client creation from the `pythGeneration` create option.
+ * Orthogonal to `oracleSource` — this flips the Pyth-Core *infra* (state ids
+ * + endpoint), not which `PriceUpdateRule` routes tickers.
+ */
+export type PythGeneration = "core" | "pro";
+/**
+ * Pyth **Pro-generation** Core-compatible infra — the post-2026-08-18
+ * contracts (cutover date per
+ * https://docs.pyth.network/price-feeds/core/upgrade) from Pyth's Core-Upgrade
+ * docs
+ * (https://docs.pyth.network/price-feeds/core/upgrade/contracts, Sui section;
+ * package revs `sui-pro-compatible-contract-mainnet` /
+ * `sui-pro-compatible-contract-testnet`). Selected via the client's
+ * `pythGeneration: 'pro'` create option; `config.pyth` still overrides
+ * wholesale (see `PerpClient`). All four state ids were verified on-chain
+ * (shared `state::State` objects under the docs' upgraded package ids).
+ *
+ * Kept as a second flat map beside {@link PYTH_DEFAULTS} rather than a nested
+ * `PYTH_INFRA[network][generation]` — `PYTH_DEFAULTS` is a published export
+ * with external consumers, so the smallest honest surface is an additive
+ * sibling (same deferral note as {@link LAZER_DEFAULTS}).
+ *
+ * The Hermes-compatible endpoint (`pyth.dourolabs.app/hermes`) serves the
+ * same REST surface as `hermes.pyth.network` but requires `pyth.api_key`
+ * (`Authorization: Bearer …`) after the cutover — see
+ * {@link PythInfraConfig.api_key}.
+ */
+export declare const PYTH_PRO_DEFAULTS: Record<Network, PythInfraConfig>;
+/**
+ * Pyth Lazer (Pyth Pro) external infra the `PythLazerRule` needs, by network.
+ * Mirrors {@link PYTH_DEFAULTS}: per-network constants for infrastructure Pyth
+ * operates (not part of the `waterx-config` JSON). A fuller `PYTH_INFRA`
+ * restructure is deferred — this stays a minimal map until then.
+ *
+ * - `endpoint` — Lazer HTTP API base; signed updates come from
+ *   `POST /v1/latest_price` (Bearer-authenticated). The service is
+ *   network-agnostic (one signed payload verifies on any chain that trusts the
+ *   Lazer signers), so both networks share the production host.
+ * - `verifier_package` — the Sui package carrying
+ *   `pyth_lazer::parse_and_verify_le_ecdsa_update`. Per-network: testnet is
+ *   still the original v1 publish; mainnet is the v2-upgraded package (which
+ *   still exposes the v1 entry `pyth_lazer_rule` binds). Values mirror the
+ *   contract repo's `pyth_lazer_rule/Move.toml` published-at pins.
+ */
+export declare const LAZER_DEFAULTS: Record<Network, {
+    endpoint: string;
+    verifier_package: string;
+}>;
 /**
  * The narrow config shape the oracle/refresh code needs. `WaterXConfig`
  * (the perp line's full config) is assignable to this, so `PerpClient` satisfies