@waterx/sdk 3.1.1 → 4.0.1

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,116 @@ 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 ONE selected source serves every ticker in its
+ * `supportedTickers(host)`. There is **no cross-source fallback** — a requested
+ * ticker the selected source does not serve, and that is not a constant-only
+ * ticker (which needs no price-update leg), fails the build immediately with a
+ * clear error naming the ticker and source. That is the deliberate "fail the
+ * tx-build, don't silently reroute" contract: a wrong-but-present feed id is
+ * NOT validated here (it surfaces on-chain at dry-run); a MISSING feed for the
+ * selected source is caught here. When the selected source's feed exists but is
+ * wrong, this function does nothing special — the on-chain aggregate aborts at
+ * dry-run, which is correct.
+ *
+ * The selected source's fetch + build runs against its own infra, guaranteeing
+ * per-rule PTB atomicity. A fee-source pre-check runs first (the source's
+ * `requiresFeeSource`) BEFORE any off-chain fetch or PTB mutation — so a
+ * fee-charging source with no `opts.feeSource` throws
+ * `OracleFeeSourceUnavailable` with zero wasted network calls and zero stray
+ * moveCalls. Only once that check passes does the off-chain fetch run 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));
+    // ONE source, no fallback. The selected source serves the tickers in its
+    // `supportedTickers(host)`; `source` is tracked alongside the group (rather
+    // than read back off `rule.kind`, 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));
+    // Fail the tx-build (NOT client init, NOT a silent reroute) when the selected
+    // source has no feed for a requested ticker that actually needs a price
+    // update. Only a CONSTANT-ONLY ticker is exempt — priced entirely by
+    // `constant_rule`, it needs no update leg from any source. A DUAL-FEED ticker
+    // (constant AND pyth) still needs its Pyth leg refreshed, so `isConstantTicker`
+    // alone must NOT exempt it: under a source that can't serve it, with no
+    // fallback, feeding an unrefreshed Pyth leg would price it stale (or abort on a
+    // missing weighted source). `priceInfoByTicker.has(t)` ⇔ the ticker has a
+    // `pyth_rule.feeds` entry, so `constant && !hasPyth` is exactly constant-only.
+    // This catches a MISSING feed; a present-but-WRONG feed id is deliberately not
+    // validated here (it aborts on-chain at dry-run).
+    const isConstantOnly = (t) => host.isConstantTicker(t) && !priceInfoByTicker.has(t);
+    const unservable = tickers.filter((t) => !selectedSupported.has(t) && !isConstantOnly(t));
+    if (unservable.length > 0) {
+        throw new Error(`oracleSource '${host.oracleSource}' has no feed configured for ticker(s): ` +
+            `${unservable.join(", ")}. Sources are self-contained with no fallback — add ` +
+            `${host.oracleSource} feeds for them, or select a source that serves them.`);
+    }
+    const selectedGroup = tickers.filter((t) => selectedSupported.has(t));
+    // Fee-source pre-check, hoisted ABOVE the off-chain fetch and PTB build below.
+    // It consults only `rule.requiresFeeSource` — known before any fetch or PTB
+    // mutation — so a fee-charging source with no `feeSource` throws with ZERO
+    // wasted network calls and zero PTB commands, rather than waiting for
+    // `buildPythPriceUpdateCalls`'s own per-call guard to fire after the off-chain
+    // fetch already ran.
+    if (selectedGroup.length > 0 && !opts.feeSource && selectedRule.requiresFeeSource) {
+        throw new OracleFeeSourceUnavailableError();
+    }
+    // Resolve + build the selected source's update leg. The off-chain fetch
+    // settles before the first PTB mutation, so a fetch failure never strands
+    // moveCalls in a caller-owned tx. Map each lazer-served ticker to the one
+    // verified `Update` PTB value for the collector-feed leg below.
+    const lazerUpdateByTicker = new Map();
+    if (selectedGroup.length > 0) {
+        const group = { source: host.oracleSource, rule: selectedRule, tickers: selectedGroup };
+        const data = await resolveGroupUpdateData(host, group, opts.updateDataProvider);
+        const handle = (await selectedRule.buildUpdateCalls(tx, host, 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 selectedGroup)
+                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,16 +95,83 @@ 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;
 }
+/**
+ * Resolved Pyth Core infra as it lives on `client.pyth` — NOT a config-JSON
+ * shape. `state_id` / `wormhole_state_id` / `hermes_endpoint` come verbatim
+ * from the fixed per-network constant ({@link PYTH_DEFAULTS}); `api_key` /
+ * `fetch` are layered on from the caller's `pythApiKey` / `pythFetch` create
+ * options. None of it is sourced from the canonical `waterx-config` JSON — the
+ * SDK never reads a `pyth` block there (a Bearer secret has no place in a
+ * public CDN document). The infra is the same for every `oracleSource`; the
+ * `pyth_lazer_rule` source reads only the `api_key` / `fetch` from here and
+ * gets its on-chain infra from {@link LAZER_DEFAULTS} + config instead.
+ */
+/**
+ * The caller-tunable subset of `fetchWithPolicy`'s policy exposed on the
+ * `pythFetch` create option and `client.pyth.fetch` — the retry/timeout budget
+ * for the off-chain Hermes (`fetchPriceFeedsUpdateData`) and Lazer
+ * (`PythLazerRule`) update fetches. Deliberately narrower than the internal
+ * `FetchPolicy` (no `retryDelayMs` / `apiKey` / `fetchImpl`). Both fetches fall
+ * back to `fetchWithPolicy`'s defaults (15s timeout, 2 retries) when unset.
+ */
+export type PythFetchPolicy = {
+    timeoutMs?: number;
+    retries?: number;
+};
 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.
+     * Supplied via the `pythApiKey` create option (the SDK never reads
+     * `process.env` or the config JSON). 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 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). Supplied via the `pythFetch` create option. Optional:
+     * both fetches default to `fetchWithPolicy`'s built-in defaults (15s
+     * timeout, 2 retries) when unset.
+     */
+    fetch?: PythFetchPolicy;
 }
 export declare const PYTH_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
@@ -94,6 +179,4 @@ export declare const PYTH_DEFAULTS: Record<Network, PythInfraConfig>;
  */
 export interface OracleConfig extends BaseLineConfig {
     packages: OraclePackages;
-    /** Pyth infra override (defaults from {@link PYTH_DEFAULTS}). */
-    pyth?: PythInfraConfig;
 }

package/dist/src/oracle/config.js

@@ -21,3 +21,32 @@ export const PYTH_DEFAULTS = {
         hermes_endpoint: "https://hermes-beta.pyth.network",
     },
 };
+// ============================================================================
+// 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). */
+    /** External Pyth/Wormhole/Hermes infra — fixed per `(network, generation)`; api_key/fetch layered from create options. */
     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, fetchWithPolicy, joinEndpointPath } from "./update-fetch.ts";
+export type { FetchPolicy } from "./update-fetch.ts";
+export { PythCache, fetchPriceFeedsUpdateData, endpointSupportedFeedIds, probeMissingFeeds, buildPythPriceUpdateCalls, updatePythPrices, HermesEndpointRejectedAllFeedsError, MISSING_FEED_MEMO_TTL_MS, 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,52 @@
  * 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` + `joinEndpointPath` are exported for consumers that hit
+// Hermes-compatible endpoints THEMSELVES (e.g. the BE's parsed latest-price
+// bootstrap and Pyth schedule readers): one shared Bearer/timeout/retry
+// policy and one base-path-safe URL join, instead of each caller re-rolling
+// them (the hand-rolled copies were how the Pro `/hermes` base path got
+// dropped and the Bearer went missing on sibling fetches).
+export { FetchPolicyError, fetchWithPolicy, joinEndpointPath } from "./update-fetch.js";
+// Pyth source — `OracleFeeSourceUnavailableError` and
+// `HermesEndpointRejectedAllFeedsError` are re-exported (not just the types)
+// for the same `instanceof` reason as `FetchPolicyError` above: a consumer of
+// `buildPythPriceUpdateCalls` / `updatePythPrices` / `refreshOraclePrices` can
+// branch on the fee-source failure directly, and a consumer of
+// `fetchPriceFeedsUpdateData` / `probeMissingFeeds` can tell a misconfigured
+// or unentitled endpoint apart from feeds that endpoint genuinely lacks.
+export { PythCache, fetchPriceFeedsUpdateData, endpointSupportedFeedIds, probeMissingFeeds, buildPythPriceUpdateCalls, updatePythPrices, HermesEndpointRejectedAllFeedsError, MISSING_FEED_MEMO_TTL_MS, 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)