@waterx/sdk 3.1.1 → 4.0.1

package/README.md

@@ -14,11 +14,12 @@ import { WaterXClient } from "@waterx/sdk";
 // waterxConfigUrl is REQUIRED — the SDK has no built-in default and never reads env.
 const client = await WaterXClient.create({
   network: "TESTNET",
-  waterxConfigUrl: "https://raw.githubusercontent.com/WaterXProtocol/waterx-config/main/testnet.json",
+  waterxConfigUrl:
+    "https://raw.githubusercontent.com/WaterXProtocol/waterx-config/main/testnet.json",
 });
-client.account.createAccount(tx, { alias });  // shared waterx_account + funding (credit/custody)
-client.perp.buildPlaceOrderTx(params);        // perpetuals
-client.predict.placeOrder(tx, params);        // prediction markets
+client.account.createAccount(tx, { alias }); // shared waterx_account + funding (credit/custody)
+client.perp.buildPlaceOrderTx(params); // perpetuals
+client.predict.placeOrder(tx, params); // prediction markets
 // client.perp / client.predict ARE the line clients — sign/execute on them directly:
 //   await client.perp.signAndExecuteTransaction({ transaction: tx, signer })
 // each line can target a different network + URL:
@@ -29,11 +30,11 @@ client.predict.placeOrder(tx, params);        // prediction markets
 
 Import surfaces:
 
-| Import | What |
-|--------|------|
-| `@waterx/sdk` | `WaterXClient` (umbrella) + `perp` / `prediction` namespaces. Perp's API is also re-exported flat here (**deprecated** — prefer `client.perp` or the `perp` namespace; removed next major). |
-| `@waterx/sdk/perp` | Perp line: `PerpClient`, builders, fetch, Pyth/Wormhole utils. |
-| `@waterx/sdk/prediction` | Prediction line: `PredictClient`, builders, fetch, utils. |
+| Import                   | What                                                                                                                                                                                        |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@waterx/sdk`            | `WaterXClient` (umbrella) + `perp` / `prediction` namespaces. Perp's API is also re-exported flat here (**deprecated** — prefer `client.perp` or the `perp` namespace; removed next major). |
+| `@waterx/sdk/perp`       | Perp line: `PerpClient`, builders, fetch, Pyth/Wormhole utils.                                                                                                                              |
+| `@waterx/sdk/prediction` | Prediction line: `PredictClient`, builders, fetch, utils.                                                                                                                                   |
 
 ## Install
 
@@ -99,6 +100,41 @@ 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
+
+ONE client create option, `oracleSource`, selects the price-update source. Each source is **self-contained** — it owns its own infra + config and does **not** back-stop any other source. The name is source-neutral on purpose: a future source need not be Pyth. The SDK **never reads `process.env`** — each consumer wires it from its own env var, so every environment runs the **same SDK version** and differs only by env:
+
+| Option         | Values                                         | What it selects                                                                                                                                                                                                                                                                           |
+| -------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `oracleSource` | `'pyth_rule'` (default) \| `'pyth_lazer_rule'` | The price-update source. `'pyth_rule'` = Pyth Core updates (Hermes VAA + per-feed update fees, keyless `hermes.pyth.network`). `'pyth_lazer_rule'` = Pyth Lazer signed updates (ONE `leEcdsa` verify per PTB, no per-feed fees); needs `packages.pyth_lazer_rule` feeds + a `pythApiKey`. |
+
+**No cross-source fallback, no init guard.** Selecting a source whose feed for a requested ticker is absent is **not** an error at client creation — it fails at **tx-build** for exactly those tickers (constant-only tickers, which need no price update, are exempt). A present-but-wrong feed id is not validated by the SDK; it aborts on-chain at dry-run.
+
+The Pyth Core infra (`client.pyth`: state ids + Hermes endpoint) is **fixed per network** by `PYTH_DEFAULTS` and is **not** deployment-overridable — the canonical `waterx-config` JSON carries no `pyth` block. The `pyth_lazer_rule` source reads only the credential/policy (`api_key`/`fetch`) from `client.pyth`; its on-chain infra comes from `LAZER_DEFAULTS` + config. The credential and fetch policy are passed at client init (`pythApiKey` / `pythFetch`), never through the JSON.
+
+```ts
+// Per-environment wiring — the consumer owns the env var, not the SDK:
+const perp = await PerpClient.create(network, {
+  waterxConfigUrl,
+  oracleSource: process.env.ORACLE_SOURCE as OracleSource | undefined, // e.g. staging: 'pyth_lazer_rule'
+  pythApiKey: process.env.PYTH_API_KEY, // Lazer is auth-first; unused by 'pyth_rule'
+});
+```
+
+This is the staging-Lazer / prod-Core rollout pattern: staging sets `ORACLE_SOURCE=pyth_lazer_rule` (+ `PYTH_API_KEY`) while production leaves it unset — flipping an environment is an env-var change, never an SDK release.
+
+### Adding an oracle source (runbook)
+
+Every source 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`.
+5. **Consumers flip `oracleSource`** 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:
@@ -111,14 +147,14 @@ Perp `build*Tx` helpers are Pyth-backed (`async`; they refresh feeds before the
 
 ## Development
 
-| Command | Use |
-| --- | --- |
-| `pnpm typecheck` | Typecheck the whole tree |
-| `pnpm test` / `pnpm test:unit` | Unit tests (perp + prediction) |
-| `pnpm test:e2e` | Testnet simulate e2e (perp + prediction) |
-| `pnpm test:integration` | On-chain integration (needs `SUI_PRIVATE_KEY`; local-only) |
-| `pnpm lint` / `pnpm format` | ESLint + Prettier |
-| `pnpm codegen` | Regenerate `src/generated` from Move |
-| `pnpm seed:testnet` | Seed prediction testnet fixtures (needs `SUI_PRIVATE_KEY`) |
+| Command                        | Use                                                        |
+| ------------------------------ | ---------------------------------------------------------- |
+| `pnpm typecheck`               | Typecheck the whole tree                                   |
+| `pnpm test` / `pnpm test:unit` | Unit tests (perp + prediction)                             |
+| `pnpm test:e2e`                | Testnet simulate e2e (perp + prediction)                   |
+| `pnpm test:integration`        | On-chain integration (needs `SUI_PRIVATE_KEY`; local-only) |
+| `pnpm lint` / `pnpm format`    | ESLint + Prettier                                          |
+| `pnpm codegen`                 | Regenerate `src/generated` from Move                       |
+| `pnpm seed:testnet`            | Seed prediction testnet fixtures (needs `SUI_PRIVATE_KEY`) |
 
 Tests are split per line under `test/perp/` and `test/prediction/`, each with `unit` / `e2e` / `integration` tiers. See the per-line `README.md` in each.

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

@@ -48,28 +48,12 @@ export interface NativeCustodyPackage {
     /** Backing assets registered via `add_asset` (array, identified by `type`). */
     assets: NativeCustodyAsset[];
 }
-export interface TrustedEmitterRow {
-    /** Source EVM chain's Wormhole chain id (e.g. 10002 = Sepolia). */
-    chain_id: number;
-    /** 32-byte left-padded EVM bridge address (0x form). */
-    evm_bridge_address_32b: string;
-    /** Whitelisted 20-byte EVM token addresses (0x form). */
-    evm_tokens_20b: string[];
-}
 export interface WormholeBridgePackage {
     published_at: string;
     /** Shared Sui Wormhole `State` object id for this deployment. */
     wormhole_state: string;
-    hourly_mint_limit?: string;
     max_mint_per_tx?: string;
-    hourly_burn_limit?: string;
     max_burn_per_tx?: string;
-    /**
-     * @deprecated EVM emitter↔token config now lives solely under `evm.bridge.chains`
-     * (deposit_vault = emitter, wormhole_chain_id = chain key). The runtime allowlist is
-     * read from the on-chain `Bridge` object, not from config. Kept optional for back-compat.
-     */
-    trusted_emitters?: TrustedEmitterRow[];
     /** Shared `Bridge` (phase-5 output). */
     bridge?: string;
     /**

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,75 @@ 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 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 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,116 @@ 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.
  */
 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));
+    // 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 = (0, rule_registry_ts_1.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 pyth_ts_1.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),
+        });
     }
 }