@waterx/sdk 3.1.0 → 4.0.0

package/dist/src/oracle/aggregate.js

@@ -2,38 +2,98 @@
  * 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 { aggregate as aggregateCall, newCollector } from "../generated/waterx_oracle/oracle.js";
-import { updatePythPrices } from "./pyth.js";
+import { OracleFeeSourceUnavailableError } from "./pyth.js";
+import { resolveOracleRule } from "./rule-registry.js";
 import { feedConstantRule } from "./rules/constant-rule.js";
+import { feedLazerRule } from "./rules/pyth-lazer-rule.js";
 import { feedPythRule } from "./rules/pyth-rule.js";
 import { maybeFeedSupra } from "./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.
  */
 export function aggregateTicker(tx, host, args) {
     const oraclePkg = host.config.packages.waterx_oracle.published_at;
@@ -44,16 +104,22 @@ export function aggregateTicker(tx, host, args) {
     let fed = false;
     if (args.priceInfoObjectId) {
         feedPythRule(tx, host, collector, args.priceInfoObjectId);
+        fed = true;
+    }
+    if (args.lazerUpdate !== undefined) {
+        feedLazerRule(tx, host, collector, args.lazerUpdate);
+        fed = true;
+    }
+    if (fed) {
         // Supra rides on the same collector when enabled (abstains on-chain otherwise).
         maybeFeedSupra(tx, host, collector);
-        fed = true;
     }
     if (host.isConstantTicker(args.ticker)) {
         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)`);
     }
     aggregateCall({
         package: oraclePkg,
@@ -89,24 +155,128 @@ export 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.
  */
 export 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 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 = 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 = 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 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/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

package/dist/src/oracle/config.js

@@ -21,3 +21,66 @@ export const PYTH_DEFAULTS = {
         hermes_endpoint: "https://hermes-beta.pyth.network",
     },
 };
+/**
+ * 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 const PYTH_PRO_DEFAULTS = {
+    MAINNET: {
+        state_id: "0x03719fae774ddab3cfcaa53bbc046f0cbe21410019b6280811bf3f9f4b05839d",
+        wormhole_state_id: "0xdbca52b9fb4f712e25f61f974586d93ac541bcf8389564f0323bb07215168b5c",
+        hermes_endpoint: "https://pyth.dourolabs.app/hermes",
+    },
+    TESTNET: {
+        state_id: "0x3c48fe392912de6c18087a2b3f5fdbfbfdb4598e180947feff1f12f8e9ea073e",
+        wormhole_state_id: "0x750da8e6d16b6a363a39fe2eaa8295ac224a1e6fce4e47b58845e2e8746164f0",
+        hermes_endpoint: "https://pyth.dourolabs.app/hermes",
+    },
+};
+// ============================================================================
+// Pyth Lazer — external infra, defaults by network
+// ============================================================================
+/**
+ * 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 const LAZER_DEFAULTS = {
+    MAINNET: {
+        endpoint: "https://pyth-lazer.dourolabs.app",
+        verifier_package: "0xefbfd064480777699fd9c557a5804d72ace7bc82661fdc8d1f1a44ea6d92ee10",
+    },
+    TESTNET: {
+        endpoint: "https://pyth-lazer.dourolabs.app",
+        verifier_package: "0xf5bd2141967507050a91b58de3d95e77c432cd90d1799ee46effc27430a68c21",
+    },
+};

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

@@ -8,14 +8,27 @@
  * clause, and a future `PredictClient` (or a test double) can too.
  */
 import type { SuiGrpcClient } from "@mysten/sui/grpc";
+import type { Network } from "../constants.ts";
 import type { OracleConfig, PythInfraConfig } from "./config.ts";
+import type { OracleSource } from "./price-update-rule.ts";
 export interface OracleHost {
+    /** Sui network this client targets — selects per-network external-infra defaults (e.g. `LAZER_DEFAULTS`). */
+    readonly network: Network;
     /** Oracle slice of the canonical `waterx-config` JSON (rule packages + per-ticker feeds). */
     readonly config: OracleConfig;
     /** External Pyth/Wormhole/Hermes infra (network default, overridable via config). */
     readonly pyth: PythInfraConfig;
     /** gRPC client for the on-chain reads the Pyth update path needs. */
     readonly grpcClient: SuiGrpcClient;
+    /**
+     * Client-selected oracle rule source for `refreshOraclePrices`'s on-chain
+     * update leg — resolved at client creation from the `oracleSource` create
+     * option (default `'pyth_rule'`). Routing is driven by this value ALONE:
+     * never by a config JSON `enabled` flag (e.g. a future `pyth_lazer_rule.enabled`)
+     * and never by `process.env` — the SDK never reads it; consumers (BE/FE) wire
+     * this option from their own env var.
+     */
+    readonly oracleSource: OracleSource;
     /** True when `ticker` is priced by `constant_rule`. */
     isConstantTicker(ticker: string): boolean;
     /** The `supra_rule` config when deployed, enabled, and fully wired; else `undefined`. */

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

@@ -2,15 +2,29 @@
  * Oracle module — the single source of truth for price freshness.
  *
  * Layering (no cross-imports between siblings except via `aggregate.ts`):
- *   - `host.ts`     — `OracleHost`, the narrow client slice this module reads.
- *   - `pyth.ts`     — Pyth as a price source: Hermes REST + on-chain update PTB.
- *   - `rules/*`     — one file per oracle rule (pyth / supra / constant / sponsor).
- *   - `aggregate.ts`— the orchestrator that feeds rules into a collector + aggregates.
+ *   - `host.ts`             — `OracleHost`, the narrow client slice this module reads.
+ *   - `update-fetch.ts`     — `fetchWithPolicy`, the shared retry/timeout/Bearer resilience
+ *                             wrapper every off-chain oracle (and config) fetch goes through.
+ *   - `pyth.ts`             — Pyth as a price source: Hermes REST + on-chain update PTB.
+ *   - `price-update-rule.ts`— `PriceUpdateRule`, the fetch/build strategy port a rule
+ *                             implements; `rule-registry.ts` + `aggregate.ts` wire
+ *                             routing across rules.
+ *   - `rules/*`             — one file per oracle rule (pyth / supra / constant / sponsor).
+ *   - `aggregate.ts`        — the orchestrator that feeds rules into a collector + aggregates.
  *
  * `pyth.ts` deliberately imports NO rule package — Pyth-the-source and the
  * rules that consume it are separate concerns.
  */
 export type { OracleHost } from "./host.ts";
-export { PythCache, fetchPriceFeedsUpdateData, buildPythPriceUpdateCalls, updatePythPrices, } from "./pyth.ts";
+export { FetchPolicyError } from "./update-fetch.ts";
+export type { FetchPolicy } from "./update-fetch.ts";
+export { PythCache, fetchPriceFeedsUpdateData, buildPythPriceUpdateCalls, updatePythPrices, OracleFeeSourceUnavailableError, } from "./pyth.ts";
+export type { OracleFeeSource } from "./pyth.ts";
+export type { PriceUpdateRule, PriceUpdateRuleKind, RuleUpdateData, RuleUpdateHandle, BuildUpdateOpts, OracleSource, UpdateDataProvider, } from "./price-update-rule.ts";
+export { PythCoreRule } from "./rules/pyth-core-rule.ts";
+export type { PythCoreUpdatePayload } from "./rules/pyth-core-rule.ts";
+export { PythLazerRule, LazerApiKeyMissingError } from "./rules/pyth-lazer-rule.ts";
+export type { PythLazerUpdatePayload } from "./rules/pyth-lazer-rule.ts";
+export { OracleSourceNotImplementedError } from "./rule-registry.ts";
 export { aggregateTicker, aggregateTickerWithPyth, aggregateTickerWithConstant, refreshOraclePrices, } from "./aggregate.ts";
 export { openPythSponsorFund, reimbursePythSponsor } from "./rules/sponsor.ts";

package/dist/src/oracle/index.js

@@ -2,16 +2,44 @@
  * Oracle module — the single source of truth for price freshness.
  *
  * Layering (no cross-imports between siblings except via `aggregate.ts`):
- *   - `host.ts`     — `OracleHost`, the narrow client slice this module reads.
- *   - `pyth.ts`     — Pyth as a price source: Hermes REST + on-chain update PTB.
- *   - `rules/*`     — one file per oracle rule (pyth / supra / constant / sponsor).
- *   - `aggregate.ts`— the orchestrator that feeds rules into a collector + aggregates.
+ *   - `host.ts`             — `OracleHost`, the narrow client slice this module reads.
+ *   - `update-fetch.ts`     — `fetchWithPolicy`, the shared retry/timeout/Bearer resilience
+ *                             wrapper every off-chain oracle (and config) fetch goes through.
+ *   - `pyth.ts`             — Pyth as a price source: Hermes REST + on-chain update PTB.
+ *   - `price-update-rule.ts`— `PriceUpdateRule`, the fetch/build strategy port a rule
+ *                             implements; `rule-registry.ts` + `aggregate.ts` wire
+ *                             routing across rules.
+ *   - `rules/*`             — one file per oracle rule (pyth / supra / constant / sponsor).
+ *   - `aggregate.ts`        — the orchestrator that feeds rules into a collector + aggregates.
  *
  * `pyth.ts` deliberately imports NO rule package — Pyth-the-source and the
  * rules that consume it are separate concerns.
  */
-// Pyth source
-export { PythCache, fetchPriceFeedsUpdateData, buildPythPriceUpdateCalls, updatePythPrices, } from "./pyth.js";
+// Shared fetch resilience wrapper — `FetchPolicyError` is re-exported (not
+// just the type) so a consumer (e.g. a BE prefetch cache) can `instanceof`
+// it off the failure `fetchPriceFeedsUpdateData` / `PythLazerRule` /
+// `loadConfig` surface, without a deep import of `./update-fetch.ts`.
+// `fetchWithPolicy` itself stays module-internal (no external caller yet).
+export { FetchPolicyError } from "./update-fetch.js";
+// Pyth source — `OracleFeeSourceUnavailableError` is re-exported (not just
+// the type) for the same `instanceof` reason as `FetchPolicyError` above: a
+// consumer of `buildPythPriceUpdateCalls` / `updatePythPrices` /
+// `refreshOraclePrices` can branch on the fee-source failure directly.
+export { PythCache, fetchPriceFeedsUpdateData, buildPythPriceUpdateCalls, updatePythPrices, OracleFeeSourceUnavailableError, } from "./pyth.js";
+// Pyth Core rule (PriceUpdateRule wrapper over the Pyth source above)
+export { PythCoreRule } from "./rules/pyth-core-rule.js";
+// Pyth Lazer rule (signed-update generation; `feedLazerRule` stays internal to `aggregate.ts`)
+// `LazerApiKeyMissingError` is re-exported (not just the type) for the same
+// `instanceof` reason as `OracleFeeSourceUnavailableError` above.
+export { PythLazerRule, LazerApiKeyMissingError } from "./rules/pyth-lazer-rule.js";
+// `resolveOracleRule` (rule-registry.ts) is NOT re-exported here — it has one
+// production consumer (`refreshOraclePrices` below) and no external caller;
+// per repo convention ("no unused exports") it stays module-internal. Tests
+// import it directly from `./rule-registry.ts`. `OracleSourceNotImplementedError`
+// IS re-exported (the same `instanceof` reason as `OracleFeeSourceUnavailableError`
+// above) — a consumer of `refreshOraclePrices` can catch it without importing
+// `resolveOracleRule` itself.
+export { OracleSourceNotImplementedError } from "./rule-registry.js";
 // Aggregation orchestrator
 export { aggregateTicker, aggregateTickerWithPyth, aggregateTickerWithConstant, refreshOraclePrices, } from "./aggregate.js";
 // Sponsor rule (fund open / reimburse + witness attach)