@waterx/sdk 4.0.0 → 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,39 +100,38 @@ const predict = await PredictClient.create("TESTNET", { waterxConfigUrl }); // o
 
 Read-only queries use gRPC `simulateTransaction` (no signer) — the `getX` view helpers, e.g. `await perp.simulate(tx)` or `getMarketData(perp, …)`.
 
-## Oracle sources & the Pyth Pro migration
+## 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:
 
-Two independent client create options control oracle behavior. The SDK **never reads `process.env`** — each consumer wires them from its own env vars, so every environment runs the **same SDK version** and differs only by env:
+| Option         | Values                                         | What it 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`. |
 
-| Option | Values | What it flips |
-|--------|--------|---------------|
-| `oracleSource` | `'pyth_rule'` (default) \| `'pyth_lazer_rule'` | Which `PriceUpdateRule` `refreshOraclePrices` uses for the on-chain price-update leg. |
-| `pythGeneration` | `'core'` (default) \| `'pro'` | Which Pyth infra constants feed `client.pyth` when the config JSON has no explicit `pyth` block: `PYTH_DEFAULTS` (original contracts, keyless `hermes.pyth.network`) or `PYTH_PRO_DEFAULTS` (post-2026-08-18 Pro-compatible contracts + the Hermes-compatible `https://pyth.dourolabs.app/hermes`, auth-first). |
+**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.
 
-They are orthogonal: `pythGeneration` moves the Pyth **Core** state ids + endpoint; `oracleSource` picks the **rule** (Core VAA vs Lazer signed updates). An explicit `pyth` block in the config JSON always overrides the generation constants wholesale.
+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 vars, not the SDK:
+// 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
-  pythGeneration: process.env.PYTH_GENERATION as PythGeneration | undefined, // e.g. staging: pro
+  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'
 });
-// After the 2026-08-18 cutover, Pro-generation Hermes requires a key:
-perp.pyth = { ...perp.pyth, api_key: process.env.PYTH_API_KEY };
 ```
 
-This is the staging-Pro / prod-Core rollout pattern: staging sets `ORACLE_SOURCE=pyth_lazer_rule` and/or `PYTH_GENERATION=pro` while production leaves both unset (Core defaults) — flipping an environment is an env-var change, never an SDK release. After August 18, 2026 (the Core-upgrade cutover — see https://docs.pyth.network/price-feeds/core/upgrade), consumers set `pythGeneration: 'pro'` + `pyth.api_key`.
+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 rule generation plugs in the same way — routing is driven **only** by the client's `oracleSource` option (never a config `enabled` flag, never `process.env`):
+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` / `PYTH_PRO_DEFAULTS`.
-5. **Consumers flip `ORACLE_SOURCE`** per environment — no consumer code change, no SDK re-release.
+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.
 
@@ -147,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

@@ -83,28 +83,26 @@ export declare function aggregateTickerWithConstant(tx: Transaction, host: Oracl
  * 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.
+ * (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.
  *
- * 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.
+ * 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

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

@@ -165,28 +165,26 @@ function aggregateTickerWithConstant(tx, host, args) {
  * 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.
+ * (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.
  *
- * 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.
+ * 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
@@ -213,59 +211,49 @@ async function refreshOraclePrices(tx, host, tickers, opts = {}) {
     const pythTickers = tickers.filter((t) => host.config.packages.pyth_rule?.feeds?.[t] !== undefined);
     const priceInfoByTicker = new Map();
     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.
+    // 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));
-    const selectedGroup = tickers.filter((t) => selectedSupported.has(t));
-    const groups = [];
-    if (selectedGroup.length > 0) {
-        groups.push({ source: host.oracleSource, rule: selectedRule, tickers: selectedGroup });
-    }
-    if (host.oracleSource !== "pyth_rule") {
-        const fallbackRule = (0, rule_registry_ts_1.resolveOracleRule)("pyth_rule", opts.ruleOverrides);
-        const fallbackSupported = new Set(fallbackRule.supportedTickers(host));
-        const fallbackGroup = tickers.filter((t) => !selectedSupported.has(t) && fallbackSupported.has(t));
-        if (fallbackGroup.length > 0) {
-            groups.push({ source: "pyth_rule", rule: fallbackRule, tickers: fallbackGroup });
-        }
+    // 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.`);
     }
-    // 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)) {
+    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();
     }
-    // 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.
+    // 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();
-    for (const group of groupsWithData) {
-        const handle = (await group.rule.buildUpdateCalls(tx, host, group.data, {
+    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;
@@ -273,7 +261,7 @@ async function refreshOraclePrices(tx, host, tickers, opts = {}) {
         // 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)
+            for (const ticker of selectedGroup)
                 lazerUpdateByTicker.set(ticker, handle.update);
         }
     }

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

@@ -101,6 +101,29 @@ export interface OraclePackages {
     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;
@@ -109,8 +132,8 @@ export interface PythInfraConfig {
      * 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 →
+     * 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
@@ -119,57 +142,16 @@ export interface PythInfraConfig {
      */
     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.
+     * 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?: {
-        timeoutMs?: number;
-        retries?: number;
-    };
+    fetch?: PythFetchPolicy;
 }
 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
@@ -197,6 +179,4 @@ export declare const LAZER_DEFAULTS: Record<Network, {
  */
 export interface OracleConfig extends BaseLineConfig {
     packages: OraclePackages;
-    /** Pyth infra override (defaults from {@link PYTH_DEFAULTS}). */
-    pyth?: PythInfraConfig;
 }

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

@@ -11,7 +11,7 @@
  * mirrors the earlier account-config hoist.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LAZER_DEFAULTS = exports.PYTH_PRO_DEFAULTS = exports.PYTH_DEFAULTS = void 0;
+exports.LAZER_DEFAULTS = exports.PYTH_DEFAULTS = void 0;
 exports.PYTH_DEFAULTS = {
     MAINNET: {
         state_id: "0x1f9310238ee9298fb703c3419030b35b22bb1cc37113e3bb5007c99aec79e5b8",
@@ -24,40 +24,6 @@ exports.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}.
- */
-exports.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
 // ============================================================================

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

@@ -16,7 +16,7 @@ export interface OracleHost {
     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;

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

@@ -16,9 +16,9 @@
  * rules that consume it are separate concerns.
  */
 export type { OracleHost } from "./host.ts";
-export { FetchPolicyError } from "./update-fetch.ts";
+export { FetchPolicyError, fetchWithPolicy, joinEndpointPath } from "./update-fetch.ts";
 export type { FetchPolicy } from "./update-fetch.ts";
-export { PythCache, fetchPriceFeedsUpdateData, buildPythPriceUpdateCalls, updatePythPrices, OracleFeeSourceUnavailableError, } from "./pyth.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";

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

@@ -17,23 +17,37 @@
  * rules that consume it are separate concerns.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.reimbursePythSponsor = exports.openPythSponsorFund = exports.refreshOraclePrices = exports.aggregateTickerWithConstant = exports.aggregateTickerWithPyth = exports.aggregateTicker = exports.OracleSourceNotImplementedError = exports.LazerApiKeyMissingError = exports.PythLazerRule = exports.PythCoreRule = exports.OracleFeeSourceUnavailableError = exports.updatePythPrices = exports.buildPythPriceUpdateCalls = exports.fetchPriceFeedsUpdateData = exports.PythCache = exports.FetchPolicyError = void 0;
+exports.reimbursePythSponsor = exports.openPythSponsorFund = exports.refreshOraclePrices = exports.aggregateTickerWithConstant = exports.aggregateTickerWithPyth = exports.aggregateTicker = exports.OracleSourceNotImplementedError = exports.LazerApiKeyMissingError = exports.PythLazerRule = exports.PythCoreRule = exports.OracleFeeSourceUnavailableError = exports.MISSING_FEED_MEMO_TTL_MS = exports.HermesEndpointRejectedAllFeedsError = exports.updatePythPrices = exports.buildPythPriceUpdateCalls = exports.probeMissingFeeds = exports.endpointSupportedFeedIds = exports.fetchPriceFeedsUpdateData = exports.PythCache = exports.joinEndpointPath = exports.fetchWithPolicy = exports.FetchPolicyError = void 0;
 // 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).
+// `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).
 var update_fetch_ts_1 = require("./update-fetch.js");
 Object.defineProperty(exports, "FetchPolicyError", { enumerable: true, get: function () { return update_fetch_ts_1.FetchPolicyError; } });
-// 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.
+Object.defineProperty(exports, "fetchWithPolicy", { enumerable: true, get: function () { return update_fetch_ts_1.fetchWithPolicy; } });
+Object.defineProperty(exports, "joinEndpointPath", { enumerable: true, get: function () { return update_fetch_ts_1.joinEndpointPath; } });
+// 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.
 var pyth_ts_1 = require("./pyth.js");
 Object.defineProperty(exports, "PythCache", { enumerable: true, get: function () { return pyth_ts_1.PythCache; } });
 Object.defineProperty(exports, "fetchPriceFeedsUpdateData", { enumerable: true, get: function () { return pyth_ts_1.fetchPriceFeedsUpdateData; } });
+Object.defineProperty(exports, "endpointSupportedFeedIds", { enumerable: true, get: function () { return pyth_ts_1.endpointSupportedFeedIds; } });
+Object.defineProperty(exports, "probeMissingFeeds", { enumerable: true, get: function () { return pyth_ts_1.probeMissingFeeds; } });
 Object.defineProperty(exports, "buildPythPriceUpdateCalls", { enumerable: true, get: function () { return pyth_ts_1.buildPythPriceUpdateCalls; } });
 Object.defineProperty(exports, "updatePythPrices", { enumerable: true, get: function () { return pyth_ts_1.updatePythPrices; } });
+Object.defineProperty(exports, "HermesEndpointRejectedAllFeedsError", { enumerable: true, get: function () { return pyth_ts_1.HermesEndpointRejectedAllFeedsError; } });
+Object.defineProperty(exports, "MISSING_FEED_MEMO_TTL_MS", { enumerable: true, get: function () { return pyth_ts_1.MISSING_FEED_MEMO_TTL_MS; } });
 Object.defineProperty(exports, "OracleFeeSourceUnavailableError", { enumerable: true, get: function () { return pyth_ts_1.OracleFeeSourceUnavailableError; } });
 // Pyth Core rule (PriceUpdateRule wrapper over the Pyth source above)
 var pyth_core_rule_ts_1 = require("./rules/pyth-core-rule.js");