@waterx/sdk 4.1.0 → 4.3.1

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

@@ -17,7 +17,7 @@
  * 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.parseSignedEnvelope = exports.WaterxRule = 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;
+exports.reimbursePythSponsor = exports.openPythSponsorFund = exports.refreshOraclePrices = exports.aggregateTickerWithConstant = exports.aggregateTickerWithPyth = exports.aggregateTicker = exports.resolveOracleRule = exports.OracleSourceNotImplementedError = exports.waterxEnvelopeOf = exports.waterxQuoteCenterEndpoint = exports.WATERX_INFRA = exports.BATCH_PRICE_INTENT = exports.parseSignedEnvelope = exports.WaterxRule = exports.LazerApiKeyMissingError = exports.PythLazerRule = exports.PythCoreRule = exports.resolveHermesReadEndpoint = exports.resolveOracleReadPlan = exports.parseOracleSourceList = exports.isOracleSource = exports.ORACLE_SOURCES = exports.OracleFeeSourceUnavailableError = exports.MISSING_FEED_MEMO_TTL_MS = exports.HermesEndpointRejectedAllFeedsError = exports.updatePythPrices = exports.PYTH_PRO_HERMES_ENDPOINT = exports.pythProHermesEndpoint = exports.pythCoreHermesEndpoint = 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` /
@@ -45,10 +45,35 @@ Object.defineProperty(exports, "fetchPriceFeedsUpdateData", { enumerable: true,
 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; } });
+// The pyth read-plane endpoint accessors — Core (keyless, per network) and
+// Pro (the documented fixed base; auth via the caller's Bearer key). There
+// is no client-level endpoint field: consumers pick via
+// `resolveHermesReadEndpoint` (pyth_rule listed → Core, else override ??
+// Pro) — never a hand-rolled branch, never a cross-source fallback.
+Object.defineProperty(exports, "pythCoreHermesEndpoint", { enumerable: true, get: function () { return pyth_ts_1.pythCoreHermesEndpoint; } });
+Object.defineProperty(exports, "pythProHermesEndpoint", { enumerable: true, get: function () { return pyth_ts_1.pythProHermesEndpoint; } });
+Object.defineProperty(exports, "PYTH_PRO_HERMES_ENDPOINT", { enumerable: true, get: function () { return pyth_ts_1.PYTH_PRO_HERMES_ENDPOINT; } });
 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; } });
+// Canonical OracleSource value list + THE env-string parser consumers fold
+// onto — semantics and rationale in `source-list.ts`'s header.
+var price_update_rule_ts_1 = require("./price-update-rule.js");
+Object.defineProperty(exports, "ORACLE_SOURCES", { enumerable: true, get: function () { return price_update_rule_ts_1.ORACLE_SOURCES; } });
+var source_list_ts_1 = require("./source-list.js");
+Object.defineProperty(exports, "isOracleSource", { enumerable: true, get: function () { return source_list_ts_1.isOracleSource; } });
+Object.defineProperty(exports, "parseOracleSourceList", { enumerable: true, get: function () { return source_list_ts_1.parseOracleSourceList; } });
+// Per-source READ-plane resolution — which tickers a source can price
+// off-chain and with which ids (`resolveOracleReadPlan`), and which
+// Hermes-compatible base the hermes plans execute against
+// (`resolveHermesReadEndpoint`: pyth_rule listed → Core, else override ??
+// the documented Pyth Pro base). The one place the "lazer reads through
+// `pyth_rule.feeds` hex ids" invariant lives; consumers resolve through
+// this instead of hardcoding namespace sharing or endpoint branching.
+var read_plane_ts_1 = require("./read-plane.js");
+Object.defineProperty(exports, "resolveOracleReadPlan", { enumerable: true, get: function () { return read_plane_ts_1.resolveOracleReadPlan; } });
+Object.defineProperty(exports, "resolveHermesReadEndpoint", { enumerable: true, get: function () { return read_plane_ts_1.resolveHermesReadEndpoint; } });
 // Pyth Core rule (PriceUpdateRule wrapper over the Pyth source above)
 var pyth_core_rule_ts_1 = require("./rules/pyth-core-rule.js");
 Object.defineProperty(exports, "PythCoreRule", { enumerable: true, get: function () { return pyth_core_rule_ts_1.PythCoreRule; } });
@@ -58,20 +83,28 @@ Object.defineProperty(exports, "PythCoreRule", { enumerable: true, get: function
 var pyth_lazer_rule_ts_1 = require("./rules/pyth-lazer-rule.js");
 Object.defineProperty(exports, "PythLazerRule", { enumerable: true, get: function () { return pyth_lazer_rule_ts_1.PythLazerRule; } });
 Object.defineProperty(exports, "LazerApiKeyMissingError", { enumerable: true, get: function () { return pyth_lazer_rule_ts_1.LazerApiKeyMissingError; } });
+// `WATERX_INFRA` / `waterxQuoteCenterEndpoint` are the source's own infra table +
+// read-plane accessor (mirrors `pythCoreHermesEndpoint`).
 // WaterX quote-center rule (first-party ed25519 signed batches; `feedWaterxRule`
 // stays internal to `aggregate.ts`).
 var waterx_rule_ts_1 = require("./rules/waterx-rule.js");
 Object.defineProperty(exports, "WaterxRule", { enumerable: true, get: function () { return waterx_rule_ts_1.WaterxRule; } });
 Object.defineProperty(exports, "parseSignedEnvelope", { enumerable: true, get: function () { return waterx_rule_ts_1.parseSignedEnvelope; } });
-// `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.
+Object.defineProperty(exports, "BATCH_PRICE_INTENT", { enumerable: true, get: function () { return waterx_rule_ts_1.BATCH_PRICE_INTENT; } });
+Object.defineProperty(exports, "WATERX_INFRA", { enumerable: true, get: function () { return waterx_rule_ts_1.WATERX_INFRA; } });
+Object.defineProperty(exports, "waterxQuoteCenterEndpoint", { enumerable: true, get: function () { return waterx_rule_ts_1.waterxQuoteCenterEndpoint; } });
+// Rule-owned payload accessor (kind-check + unwrap in one place) — never
+// hand-cast the payload shape.
+Object.defineProperty(exports, "waterxEnvelopeOf", { enumerable: true, get: function () { return waterx_rule_ts_1.waterxEnvelopeOf; } });
+// `resolveOracleRule` is the ONE source→rule registry — exported so external
+// consumers (e.g. a BE prefetch cache that keys per source and needs each
+// source's `supportedTickers`/`fetchUpdateData`) resolve through it instead of
+// hand-mirroring the map and drifting. `OracleSourceNotImplementedError` is
+// its `instanceof`-able failure (same reason as `OracleFeeSourceUnavailableError`
+// above).
 var rule_registry_ts_1 = require("./rule-registry.js");
 Object.defineProperty(exports, "OracleSourceNotImplementedError", { enumerable: true, get: function () { return rule_registry_ts_1.OracleSourceNotImplementedError; } });
+Object.defineProperty(exports, "resolveOracleRule", { enumerable: true, get: function () { return rule_registry_ts_1.resolveOracleRule; } });
 // Aggregation orchestrator
 var aggregate_ts_1 = require("./aggregate.js");
 Object.defineProperty(exports, "aggregateTicker", { enumerable: true, get: function () { return aggregate_ts_1.aggregateTicker; } });

package/dist/cjs/src/oracle/price-update-rule.d.ts

@@ -11,23 +11,37 @@
  * remain plain collector-feed helpers wired directly into `aggregate.ts`.
  *
  * This file defines the port only — routing IS wired: `aggregate.ts`'s
- * `refreshOraclePrices` selects the concrete rule per `host.oracleSource` via
- * `rule-registry.ts`, then drives fetch + `buildUpdateCalls` through this
- * port; `aggregate.ts` stays the sole orchestrator.
+ * `refreshOraclePrices` resolves a concrete rule per `host.oracleSources`
+ * entry via `rule-registry.ts`, then drives fetch + `buildUpdateCalls`
+ * through this port; `aggregate.ts` stays the sole orchestrator.
  */
 import type { Transaction, TransactionArgument } from "@mysten/sui/transactions";
 import type { OracleHost } from "./host.ts";
 import type { OracleFeeSource, PythCache } from "./pyth.ts";
 export type PriceUpdateRuleKind = "pyth_rule" | "pyth_lazer_rule" | "supra_rule" | "constant_rule" | "waterx_rule";
 /**
- * The subset of `PriceUpdateRuleKind`s selectable via a client's `oracleSource`
- * create option (see `OracleHost.oracleSource`) — i.e. rules that can serve as
- * the on-chain price *update* leg `refreshOraclePrices` runs before aggregating.
- * `supra_rule` and `constant_rule` are auxiliary rules fed alongside whichever
- * source is selected (see `aggregateTicker`), not sources themselves. The SDK
- * never reads `process.env` — consumers resolve their own env var to this type.
+ * The canonical list of selectable oracle sources — the SINGLE authority the
+ * {@link OracleSource} union derives from (the value-list→union derive
+ * idiom of `unified-client.ts`'s `NON_CLIENT_FIRST`, plus `Object.freeze`
+ * so the immutability is RUNTIME truth: `as const` alone would let a JS
+ * consumer push into the array and desync the membership Set built from it
+ * in `source-list.ts`). Runtime membership checks and the `ORACLE_SOURCE`
+ * env parser live there, on `isOracleSource` / `parseOracleSourceList`.
+ * Only sources belong here: `supra_rule` and `constant_rule` are auxiliary
+ * rules fed alongside whichever sources are selected (see
+ * `aggregateTicker`), not sources themselves — the `satisfies` keeps
+ * entries inside `PriceUpdateRuleKind` but adding an auxiliary rule to this
+ * list is an (incorrect) editorial decision this comment exists to prevent.
  */
-export type OracleSource = "pyth_rule" | "pyth_lazer_rule" | "waterx_rule";
+export declare const ORACLE_SOURCES: readonly ["pyth_rule", "pyth_lazer_rule", "waterx_rule"];
+/**
+ * The kinds listable in a client's `oracleSource` create option (see
+ * `OracleHost.oracleSources`) — i.e. rules that can serve as the on-chain
+ * price *update* leg `refreshOraclePrices` runs before aggregating. Derived
+ * from {@link ORACLE_SOURCES}. The SDK never reads `process.env` — consumers
+ * resolve their own env var to this type.
+ */
+export type OracleSource = (typeof ORACLE_SOURCES)[number];
 /**
  * Off-chain payload fetched by a rule, tagged by `kind` so a caller holding
  * several rules' results can tell them apart. `payload` is `unknown` here —
@@ -116,7 +130,14 @@ export interface UpdateDataProvider {
     get(source: OracleSource, tickers: string[]): Promise<RuleUpdateData | null>;
 }
 export interface PriceUpdateRule {
-    readonly kind: PriceUpdateRuleKind;
+    /**
+     * `OracleSource`, not the wider `PriceUpdateRuleKind`: only selectable
+     * sources implement this port (`supra_rule`/`constant_rule` are plain
+     * collector-feed helpers), and the narrower type is what lets
+     * `refreshOraclePrices`'s per-source carry step switch exhaustively —
+     * adding a source without deciding its carry becomes a compile error.
+     */
+    readonly kind: OracleSource;
     /**
      * `true` when this rule's on-chain update leg charges a per-update fee
      * that must be paid from either a sponsor fund or `tx.gas` (Pyth Core:

package/dist/cjs/src/oracle/price-update-rule.js

@@ -12,12 +12,32 @@
  * remain plain collector-feed helpers wired directly into `aggregate.ts`.
  *
  * This file defines the port only — routing IS wired: `aggregate.ts`'s
- * `refreshOraclePrices` selects the concrete rule per `host.oracleSource` via
- * `rule-registry.ts`, then drives fetch + `buildUpdateCalls` through this
- * port; `aggregate.ts` stays the sole orchestrator.
+ * `refreshOraclePrices` resolves a concrete rule per `host.oracleSources`
+ * entry via `rule-registry.ts`, then drives fetch + `buildUpdateCalls`
+ * through this port; `aggregate.ts` stays the sole orchestrator.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.ORACLE_SOURCES = void 0;
 exports.assertRuleUpdateData = assertRuleUpdateData;
+/**
+ * The canonical list of selectable oracle sources — the SINGLE authority the
+ * {@link OracleSource} union derives from (the value-list→union derive
+ * idiom of `unified-client.ts`'s `NON_CLIENT_FIRST`, plus `Object.freeze`
+ * so the immutability is RUNTIME truth: `as const` alone would let a JS
+ * consumer push into the array and desync the membership Set built from it
+ * in `source-list.ts`). Runtime membership checks and the `ORACLE_SOURCE`
+ * env parser live there, on `isOracleSource` / `parseOracleSourceList`.
+ * Only sources belong here: `supra_rule` and `constant_rule` are auxiliary
+ * rules fed alongside whichever sources are selected (see
+ * `aggregateTicker`), not sources themselves — the `satisfies` keeps
+ * entries inside `PriceUpdateRuleKind` but adding an auxiliary rule to this
+ * list is an (incorrect) editorial decision this comment exists to prevent.
+ */
+exports.ORACLE_SOURCES = Object.freeze([
+    "pyth_rule",
+    "pyth_lazer_rule",
+    "waterx_rule",
+]);
 /**
  * Shared null → kind → shape guard ladder for a `PriceUpdateRule.buildUpdateCalls`
  * payload — every rule's `buildUpdateCalls` needs the exact same three checks,

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

@@ -14,8 +14,52 @@
  *   4. hot_potato_vector::destroy
  */
 import type { Transaction, TransactionArgument } from "@mysten/sui/transactions";
+import type { Network } from "../constants.ts";
 import type { PythFetchPolicy } from "./config.ts";
 import type { OracleHost } from "./host.ts";
+/**
+ * Everything the Core source needs that is not in the canonical
+ * `waterx-config` JSON lives HERE, in the source that consumes it —
+ * `client.pyth` carries only the caller's credential/fetch policy
+ * (see `PythAccessConfig`). No other oracle source reads this table:
+ * selecting `pyth_lazer_rule` (or any future source) must never touch a Core
+ * endpoint or Core state object, so nothing Core-shaped stays on the shared
+ * client to leak across sources.
+ *
+ * - `state_id` / `wormhole_state_id` — the Core Pyth + Wormhole state objects
+ *   the on-chain update PTB reads (below).
+ * - `hermes_endpoint` — the Core Hermes REST base for
+ *   `fetchPriceFeedsUpdateData`. Keyless today; auth-first after the Pyth Pro
+ *   migration (post-2026-08-18) via `client.pyth.api_key`.
+ */
+export interface PythCoreInfra {
+    state_id: string;
+    wormhole_state_id: string;
+    hermes_endpoint: string;
+}
+export declare const PYTH_CORE_INFRA: Record<Network, PythCoreInfra>;
+/**
+ * The Core source's Hermes REST base for `network` — for consumers (BE/FE
+ * read planes) whose `ORACLE_SOURCE` fed set includes `'pyth_rule'`. A fed
+ * set WITHOUT `pyth_rule` reads the keyed Pyth Pro base instead — resolve
+ * through `resolveHermesReadEndpoint` (`oracle/read-plane.ts`) rather than
+ * branching by hand.
+ */
+export declare function pythCoreHermesEndpoint(network: Network): string;
+/**
+ * The Pyth Pro Hermes-compatible REST base — the documented drop-in
+ * replacement for the Core endpoint (`https://pyth.dourolabs.app/hermes/…`),
+ * IDENTICAL for every subscriber: only the `Authorization: Bearer` key
+ * (`client.pyth.api_key` / the `pythApiKey` create option) is
+ * account-specific, so the URL is SDK infra, not deployment config. One base
+ * for both networks — Pro has no testnet variant (Pyth feed ids are
+ * chain-agnostic; `hermes-beta` is a Core-testnet concern). Consumers with a
+ * proxy/self-hosted mirror override it per deployment via
+ * `resolveHermesReadEndpoint`'s `override` param.
+ */
+export declare const PYTH_PRO_HERMES_ENDPOINT = "https://pyth.dourolabs.app/hermes";
+/** Accessor mirror of {@link pythCoreHermesEndpoint} for the Pro base. */
+export declare function pythProHermesEndpoint(): string;
 type PriceTableInfo = {
     id: string;
     fieldType: string;

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

@@ -15,7 +15,9 @@
  *   4. hot_potato_vector::destroy
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OracleFeeSourceUnavailableError = exports.HermesEndpointRejectedAllFeedsError = exports.MISSING_FEED_MEMO_TTL_MS = exports.PythCache = void 0;
+exports.OracleFeeSourceUnavailableError = exports.HermesEndpointRejectedAllFeedsError = exports.MISSING_FEED_MEMO_TTL_MS = exports.PythCache = exports.PYTH_PRO_HERMES_ENDPOINT = exports.PYTH_CORE_INFRA = void 0;
+exports.pythCoreHermesEndpoint = pythCoreHermesEndpoint;
+exports.pythProHermesEndpoint = pythProHermesEndpoint;
 exports.endpointSupportedFeedIds = endpointSupportedFeedIds;
 exports.__resetMissingFeedCacheForTest = __resetMissingFeedCacheForTest;
 exports.probeMissingFeeds = probeMissingFeeds;
@@ -25,6 +27,44 @@ exports.updatePythPrices = updatePythPrices;
 const bcs_1 = require("@mysten/bcs");
 const bcs_2 = require("@mysten/sui/bcs");
 const update_fetch_ts_1 = require("./update-fetch.js");
+exports.PYTH_CORE_INFRA = {
+    MAINNET: {
+        state_id: "0x1f9310238ee9298fb703c3419030b35b22bb1cc37113e3bb5007c99aec79e5b8",
+        wormhole_state_id: "0xaeab97f96cf9877fee2883315d459552b2b921edc16d7ceac6eab944dd88919c",
+        hermes_endpoint: "https://hermes.pyth.network",
+    },
+    TESTNET: {
+        state_id: "0x243759059f4c3111179da5878c12f68d612c21a8d54d85edc86164bb18be1c7c",
+        wormhole_state_id: "0x31358d198147da50db32eda2562951d53973a0c0ad5ed738e9b17d88b213d790",
+        hermes_endpoint: "https://hermes-beta.pyth.network",
+    },
+};
+/**
+ * The Core source's Hermes REST base for `network` — for consumers (BE/FE
+ * read planes) whose `ORACLE_SOURCE` fed set includes `'pyth_rule'`. A fed
+ * set WITHOUT `pyth_rule` reads the keyed Pyth Pro base instead — resolve
+ * through `resolveHermesReadEndpoint` (`oracle/read-plane.ts`) rather than
+ * branching by hand.
+ */
+function pythCoreHermesEndpoint(network) {
+    return exports.PYTH_CORE_INFRA[network].hermes_endpoint;
+}
+/**
+ * The Pyth Pro Hermes-compatible REST base — the documented drop-in
+ * replacement for the Core endpoint (`https://pyth.dourolabs.app/hermes/…`),
+ * IDENTICAL for every subscriber: only the `Authorization: Bearer` key
+ * (`client.pyth.api_key` / the `pythApiKey` create option) is
+ * account-specific, so the URL is SDK infra, not deployment config. One base
+ * for both networks — Pro has no testnet variant (Pyth feed ids are
+ * chain-agnostic; `hermes-beta` is a Core-testnet concern). Consumers with a
+ * proxy/self-hosted mirror override it per deployment via
+ * `resolveHermesReadEndpoint`'s `override` param.
+ */
+exports.PYTH_PRO_HERMES_ENDPOINT = "https://pyth.dourolabs.app/hermes";
+/** Accessor mirror of {@link pythCoreHermesEndpoint} for the Pro base. */
+function pythProHermesEndpoint() {
+    return exports.PYTH_PRO_HERMES_ENDPOINT;
+}
 class PythCache {
     pythStateInfo;
     wormholePackageId;
@@ -439,7 +479,7 @@ async function getPriceTableInfo(client, pythStateId, cache) {
 }
 async function getPriceFeedObjectId(client, table, feedId, cache, pythStateId) {
     const normalized = feedId.replace(/^0x/, "");
-    const cacheKey = pythStateId ? `${pythStateId}:${normalized}` : normalized;
+    const cacheKey = `${pythStateId}:${normalized}`;
     if (cache?.priceFeedObjectIdCache.has(cacheKey)) {
         return cache.priceFeedObjectIdCache.get(cacheKey);
     }
@@ -535,7 +575,9 @@ async function buildPythPriceUpdateCalls(tx, host, updates, feedIds, opts) {
         throw new OracleFeeSourceUnavailableError();
     }
     const cache = opts?.cache;
-    const pyth = host.pyth;
+    // Core on-chain infra is the `pyth_rule` source's own table, keyed by the
+    // host's network — `client.pyth` carries only the caller's credential/policy.
+    const pyth = exports.PYTH_CORE_INFRA[host.network];
     const [stateInfo, wormholePackageId, table] = await Promise.all([
         getPythStateInfo(host.grpcClient, pyth.state_id, cache),
         getWormholePackageId(host.grpcClient, pyth.wormhole_state_id, cache),
@@ -593,9 +635,9 @@ async function buildPythPriceUpdateCalls(tx, host, updates, feedIds, opts) {
 }
 /** All-in-one: fetch from Hermes, append update calls. Returns PriceInfoObject IDs. */
 async function updatePythPrices(tx, host, feedIds, opts) {
-    // `host.pyth` is the Pyth Core infra (fixed per network) plus the caller's
-    // api_key/fetch — endpoint, credential and policy all come from it.
-    const endpoint = host.pyth.hermes_endpoint;
+    // The Core source's own Hermes endpoint (per-network, rule-owned table);
+    // credential + fetch policy are the caller-supplied `client.pyth` slice.
+    const endpoint = exports.PYTH_CORE_INFRA[host.network].hermes_endpoint;
     const updates = await fetchPriceFeedsUpdateData(endpoint, feedIds, {
         apiKey: host.pyth.api_key,
         fetch: host.pyth.fetch,

package/dist/cjs/src/oracle/read-plane.d.ts

@@ -0,0 +1,70 @@
+/**
+ * `read-plane.ts` — per-source READ-plane resolution: which of a caller's
+ * tickers a source can PRICE off-chain, and with which ids. The write plane
+ * (`PriceUpdateRule` + each source's `feeds` block) and the read plane are
+ * DIFFERENT namespaces for the pyth sources: Lazer WRITES with the integer
+ * ids in `pyth_lazer_rule.feeds`, but every Hermes-compatible price READ is
+ * keyed by the hex ids only `pyth_rule.feeds` carries. That cross-block
+ * dependency is a config invariant ("a lazer-fed ticker must also carry a
+ * Core hex entry to be read-visible"), and it lives HERE, once — consumers
+ * (FE/BE price facades) resolve through this instead of hardcoding which
+ * sources share which feeds namespace.
+ */
+import type { Network } from "../constants.ts";
+import type { OracleHost } from "./host.ts";
+import type { OracleSource } from "./price-update-rule.ts";
+/**
+ * One source's read plan for a requested ticker set.
+ *
+ * - `plane: "hermes"` (pyth sources) — price via a Hermes-compatible REST
+ *   endpoint, one entry per servable ticker mapped to its HEX feed id. The
+ *   endpoint to execute against is {@link resolveHermesReadEndpoint} — the
+ *   plan (ids) plus that resolver (host) is the complete read contract.
+ * - `plane: "quote_center"` (waterx) — price via the quote-center symbols
+ *   api, keyed by ticker; served set = the `waterx_rule.feeds` block. An
+ *   ABSENT block (source listed, package missing from the loaded config)
+ *   serves NOTHING: claiming tickers would silently reroute reads to the
+ *   quote-center — it happily serves symbols regardless of on-chain config —
+ *   and swallow tickers a later-listed source could price. The
+ *   misconfiguration is caught loudly by the consumer's feeds assert at
+ *   client creation instead.
+ * - `unreadable` — requested tickers this source WRITES on-chain (its update
+ *   leg serves them) but its read plane cannot price: the silent-invisibility
+ *   trap (e.g. a lazer-fed ticker with no `pyth_rule.feeds` hex entry).
+ *   Callers should surface these loudly; empty for sources whose write and
+ *   read namespaces coincide.
+ */
+export type OracleReadPlan = {
+    unreadable: string[];
+} & ({
+    plane: "hermes";
+    feedIdByTicker: Map<string, string>;
+} | {
+    plane: "quote_center";
+    tickers: string[];
+});
+/**
+ * Resolve `source`'s read plan for `tickers`. Pure config lookup — no
+ * network, no endpoint resolution (endpoints come from
+ * `pythCoreHermesEndpoint` / `waterxQuoteCenterEndpoint` / the deployment's
+ * own env). A ticker absent from the returned plan is simply not servable by
+ * THIS source's read plane — callers decide how to degrade (typically: ask
+ * the next source in their `ORACLE_SOURCE` list, then omit).
+ */
+/**
+ * The Hermes-compatible REST base a deployment's hermes-plane read plans
+ * execute against — the endpoint half of the read contract
+ * ({@link resolveOracleReadPlan} is the ids half):
+ *
+ * - `pyth_rule` in the fed set → the Core source's own keyless endpoint
+ *   (`pythCoreHermesEndpoint(network)`).
+ * - otherwise → `override` when the deployment set one (a proxy or
+ *   self-hosted mirror), else the documented Pyth Pro base
+ *   (`pythProHermesEndpoint()` — identical for every subscriber; auth is the
+ *   caller's `pythApiKey` Bearer, not a per-deployment URL).
+ *
+ * Total — never throws, never falls back Core-ward: a fed set without
+ * `pyth_rule` reads Pro (or the override), full stop.
+ */
+export declare function resolveHermesReadEndpoint(network: Network, sources: readonly OracleSource[], override?: string): string;
+export declare function resolveOracleReadPlan(host: OracleHost, source: OracleSource, tickers: string[]): OracleReadPlan;

package/dist/cjs/src/oracle/read-plane.js

@@ -0,0 +1,85 @@
+"use strict";
+/**
+ * `read-plane.ts` — per-source READ-plane resolution: which of a caller's
+ * tickers a source can PRICE off-chain, and with which ids. The write plane
+ * (`PriceUpdateRule` + each source's `feeds` block) and the read plane are
+ * DIFFERENT namespaces for the pyth sources: Lazer WRITES with the integer
+ * ids in `pyth_lazer_rule.feeds`, but every Hermes-compatible price READ is
+ * keyed by the hex ids only `pyth_rule.feeds` carries. That cross-block
+ * dependency is a config invariant ("a lazer-fed ticker must also carry a
+ * Core hex entry to be read-visible"), and it lives HERE, once — consumers
+ * (FE/BE price facades) resolve through this instead of hardcoding which
+ * sources share which feeds namespace.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveHermesReadEndpoint = resolveHermesReadEndpoint;
+exports.resolveOracleReadPlan = resolveOracleReadPlan;
+const record_ts_1 = require("../utils/record.js");
+const pyth_ts_1 = require("./pyth.js");
+/**
+ * Resolve `source`'s read plan for `tickers`. Pure config lookup — no
+ * network, no endpoint resolution (endpoints come from
+ * `pythCoreHermesEndpoint` / `waterxQuoteCenterEndpoint` / the deployment's
+ * own env). A ticker absent from the returned plan is simply not servable by
+ * THIS source's read plane — callers decide how to degrade (typically: ask
+ * the next source in their `ORACLE_SOURCE` list, then omit).
+ */
+/**
+ * The Hermes-compatible REST base a deployment's hermes-plane read plans
+ * execute against — the endpoint half of the read contract
+ * ({@link resolveOracleReadPlan} is the ids half):
+ *
+ * - `pyth_rule` in the fed set → the Core source's own keyless endpoint
+ *   (`pythCoreHermesEndpoint(network)`).
+ * - otherwise → `override` when the deployment set one (a proxy or
+ *   self-hosted mirror), else the documented Pyth Pro base
+ *   (`pythProHermesEndpoint()` — identical for every subscriber; auth is the
+ *   caller's `pythApiKey` Bearer, not a per-deployment URL).
+ *
+ * Total — never throws, never falls back Core-ward: a fed set without
+ * `pyth_rule` reads Pro (or the override), full stop.
+ */
+function resolveHermesReadEndpoint(network, sources, override) {
+    if (sources.includes("pyth_rule"))
+        return (0, pyth_ts_1.pythCoreHermesEndpoint)(network);
+    return override ?? (0, pyth_ts_1.pythProHermesEndpoint)();
+}
+function resolveOracleReadPlan(host, source, tickers) {
+    switch (source) {
+        case "pyth_rule":
+        case "pyth_lazer_rule": {
+            // All ticker lookups go through `ownEntry` (own-keys-only): a ticker
+            // named like an Object.prototype key ("toString", "constructor", …)
+            // must read as not-listed, not as an inherited Function.
+            const hexFeeds = host.config.packages.pyth_rule?.feeds;
+            const feedIdByTicker = new Map();
+            for (const ticker of tickers) {
+                const feedId = (0, record_ts_1.ownEntry)(hexFeeds, ticker)?.feed_id;
+                if (feedId !== undefined)
+                    feedIdByTicker.set(ticker, feedId);
+            }
+            // For pyth_rule the write and read namespaces coincide, so `unreadable`
+            // is always empty; for lazer it is exactly the hex-entry gap.
+            const writeFeeds = source === "pyth_lazer_rule" ? host.config.packages.pyth_lazer_rule?.feeds : hexFeeds;
+            const unreadable = tickers.filter((ticker) => (0, record_ts_1.ownEntry)(writeFeeds, ticker) !== undefined && !feedIdByTicker.has(ticker));
+            return { plane: "hermes", feedIdByTicker, unreadable };
+        }
+        case "waterx_rule": {
+            // Absent feeds block ⇒ serves nothing (see the OracleReadPlan doc) —
+            // never claim tickers the config doesn't name. `ownEntry` (own-keys-
+            // only, never the `in` operator or a bare bracket read) so a
+            // prototype-key ticker can't count as feeds-listed and poison the
+            // quote-center batch (which 404s whole batches on unknown symbols).
+            const feeds = host.config.packages.waterx_rule?.feeds;
+            return {
+                plane: "quote_center",
+                tickers: tickers.filter((ticker) => (0, record_ts_1.ownEntry)(feeds, ticker) !== undefined),
+                unreadable: [],
+            };
+        }
+        default: {
+            const exhausted = source;
+            throw new Error(`resolveOracleReadPlan: unhandled OracleSource '${String(exhausted)}'`);
+        }
+    }
+}

package/dist/cjs/src/oracle/rule-registry.d.ts

@@ -1,9 +1,11 @@
 /**
  * `rule-registry.ts` — maps a client-selected `OracleSource` to its concrete
- * `PriceUpdateRule` implementation. `refreshOraclePrices` (`aggregate.ts`) is
- * the only production caller; this is the one place `OracleSource` values are
- * wired to a rule instance. Selection is driven purely by the value passed in
- * (ultimately `OracleHost.oracleSource`, the `oracleSource` client create
+ * `PriceUpdateRule` implementation; the ONE place `OracleSource` values are
+ * wired to a rule instance. `refreshOraclePrices` (`aggregate.ts`) resolves
+ * every `host.oracleSources` entry through it, and consumers (e.g. a BE
+ * prefetch cache keying per source) import `resolveOracleRule` rather than
+ * hand-mirroring this map. Selection is driven purely by the value passed in
+ * (ultimately `OracleHost.oracleSources`, the `oracleSource` client create
  * option) — never by a config JSON `enabled` flag and never by `process.env`.
  *
  * Each source is self-contained: it owns its own infra + config and does NOT

package/dist/cjs/src/oracle/rule-registry.js

@@ -1,10 +1,12 @@
 "use strict";
 /**
  * `rule-registry.ts` — maps a client-selected `OracleSource` to its concrete
- * `PriceUpdateRule` implementation. `refreshOraclePrices` (`aggregate.ts`) is
- * the only production caller; this is the one place `OracleSource` values are
- * wired to a rule instance. Selection is driven purely by the value passed in
- * (ultimately `OracleHost.oracleSource`, the `oracleSource` client create
+ * `PriceUpdateRule` implementation; the ONE place `OracleSource` values are
+ * wired to a rule instance. `refreshOraclePrices` (`aggregate.ts`) resolves
+ * every `host.oracleSources` entry through it, and consumers (e.g. a BE
+ * prefetch cache keying per source) import `resolveOracleRule` rather than
+ * hand-mirroring this map. Selection is driven purely by the value passed in
+ * (ultimately `OracleHost.oracleSources`, the `oracleSource` client create
  * option) — never by a config JSON `enabled` flag and never by `process.env`.
  *
  * Each source is self-contained: it owns its own infra + config and does NOT

package/dist/cjs/src/oracle/rules/pyth-core-rule.js

@@ -9,6 +9,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PythCoreRule = void 0;
+const record_ts_1 = require("../../utils/record.js");
 const price_update_rule_ts_1 = require("../price-update-rule.js");
 const pyth_ts_1 = require("../pyth.js");
 /**
@@ -36,10 +37,10 @@ exports.PythCoreRule = {
     async fetchUpdateData(host, tickers) {
         if (tickers.length === 0)
             return null;
-        // `host.pyth` is this source's own infra — the fixed per-network Core
-        // Pyth block plus the caller's api_key/fetch. Endpoint, credential and
-        // retry/timeout policy all come from it.
-        const endpoint = host.pyth.hermes_endpoint;
+        // Endpoint is this source's own per-network infra (`PYTH_CORE_INFRA`);
+        // credential + retry/timeout policy are the caller-supplied `client.pyth`
+        // access slice.
+        const endpoint = (0, pyth_ts_1.pythCoreHermesEndpoint)(host.network);
         const feedIds = tickers.map((ticker) => host.getPythFeed(ticker).feed_id);
         const updates = await (0, pyth_ts_1.fetchPriceFeedsUpdateData)(endpoint, feedIds, {
             apiKey: host.pyth.api_key,
@@ -79,7 +80,7 @@ exports.PythCoreRule = {
         for (const ticker of tickers) {
             // Same lookup as `host.getPythFeed(ticker)` minus its throw — an
             // unlisted ticker is a miss here, not an error.
-            const feedId = host.config.packages.pyth_rule?.feeds?.[ticker]?.feed_id;
+            const feedId = (0, record_ts_1.ownEntry)(host.config.packages.pyth_rule?.feeds, ticker)?.feed_id;
             if (feedId === undefined || !packedFeedIds.has(feedId))
                 return null;
             feedIds.push(feedId);

package/dist/cjs/src/oracle/rules/pyth-lazer-rule.d.ts

@@ -8,8 +8,29 @@
  * `Update` PTB value back through a `RuleUpdateHandle` for the feed calls.
  */
 import type { Transaction, TransactionArgument } from "@mysten/sui/transactions";
+import type { Network } from "../../constants.ts";
 import type { OracleHost } from "../host.ts";
 import { type PriceUpdateRule } from "../price-update-rule.ts";
+/**
+ * Pyth Lazer (Pyth Pro) external infra — owned by THIS source, by network.
+ * Per-network constants for infrastructure Pyth operates (not part of the
+ * `waterx-config` JSON), co-located with the only rule that reads them —
+ * no other oracle source ever touches a Lazer endpoint or verifier.
+ *
+ * - `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_INFRA: Record<Network, {
+    endpoint: string;
+    verifier_package: string;
+}>;
 /** `pyth_lazer_rule`'s narrowed `RuleUpdateData.payload` shape. */
 export interface PythLazerUpdatePayload {
     /** One signed `leEcdsa` message carrying every requested feed. */