@waterx/sdk 4.0.1 → 4.3.0

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

@@ -18,13 +18,17 @@
 export type { OracleHost } from "./host.ts";
 export { FetchPolicyError, fetchWithPolicy, joinEndpointPath } from "./update-fetch.ts";
 export type { FetchPolicy } from "./update-fetch.ts";
-export { PythCache, fetchPriceFeedsUpdateData, endpointSupportedFeedIds, probeMissingFeeds, buildPythPriceUpdateCalls, updatePythPrices, HermesEndpointRejectedAllFeedsError, MISSING_FEED_MEMO_TTL_MS, OracleFeeSourceUnavailableError, } from "./pyth.ts";
+export { PythCache, fetchPriceFeedsUpdateData, endpointSupportedFeedIds, probeMissingFeeds, buildPythPriceUpdateCalls, pythCoreHermesEndpoint, pythProHermesEndpoint, PYTH_PRO_HERMES_ENDPOINT, 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 { resolveOracleReadPlan, resolveHermesReadEndpoint } from "./read-plane.ts";
+export type { OracleReadPlan } from "./read-plane.ts";
 export { PythCoreRule } from "./rules/pyth-core-rule.ts";
 export type { PythCoreUpdatePayload } from "./rules/pyth-core-rule.ts";
 export { PythLazerRule, LazerApiKeyMissingError } from "./rules/pyth-lazer-rule.ts";
 export type { PythLazerUpdatePayload } from "./rules/pyth-lazer-rule.ts";
-export { OracleSourceNotImplementedError } from "./rule-registry.ts";
+export { WaterxRule, parseSignedEnvelope, BATCH_PRICE_INTENT, WATERX_INFRA, waterxQuoteCenterEndpoint, } from "./rules/waterx-rule.ts";
+export type { WaterxUpdatePayload, WaterxSignedEnvelope, WaterxBatchItem, } from "./rules/waterx-rule.ts";
+export { OracleSourceNotImplementedError, resolveOracleRule } from "./rule-registry.ts";
 export { aggregateTicker, aggregateTickerWithPyth, aggregateTickerWithConstant, refreshOraclePrices, } from "./aggregate.ts";
 export { openPythSponsorFund, reimbursePythSponsor } from "./rules/sponsor.ts";

package/dist/src/oracle/index.js

@@ -33,21 +33,39 @@ export { FetchPolicyError, fetchWithPolicy, joinEndpointPath } from "./update-fe
 // branch on the fee-source failure directly, and a consumer of
 // `fetchPriceFeedsUpdateData` / `probeMissingFeeds` can tell a misconfigured
 // or unentitled endpoint apart from feeds that endpoint genuinely lacks.
-export { PythCache, fetchPriceFeedsUpdateData, endpointSupportedFeedIds, probeMissingFeeds, buildPythPriceUpdateCalls, updatePythPrices, HermesEndpointRejectedAllFeedsError, MISSING_FEED_MEMO_TTL_MS, OracleFeeSourceUnavailableError, } from "./pyth.js";
+export { PythCache, fetchPriceFeedsUpdateData, endpointSupportedFeedIds, probeMissingFeeds, 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.
+pythCoreHermesEndpoint, pythProHermesEndpoint, PYTH_PRO_HERMES_ENDPOINT, updatePythPrices, HermesEndpointRejectedAllFeedsError, MISSING_FEED_MEMO_TTL_MS, OracleFeeSourceUnavailableError, } from "./pyth.js";
+// 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.
+export { resolveOracleReadPlan, resolveHermesReadEndpoint } from "./read-plane.js";
 // Pyth Core rule (PriceUpdateRule wrapper over the Pyth source above)
 export { PythCoreRule } from "./rules/pyth-core-rule.js";
 // Pyth Lazer rule (signed-update generation; `feedLazerRule` stays internal to `aggregate.ts`)
 // `LazerApiKeyMissingError` is re-exported (not just the type) for the same
 // `instanceof` reason as `OracleFeeSourceUnavailableError` above.
 export { PythLazerRule, LazerApiKeyMissingError } from "./rules/pyth-lazer-rule.js";
-// `resolveOracleRule` (rule-registry.ts) is NOT re-exported here — it has one
-// production consumer (`refreshOraclePrices` below) and no external caller;
-// per repo convention ("no unused exports") it stays module-internal. Tests
-// import it directly from `./rule-registry.ts`. `OracleSourceNotImplementedError`
-// IS re-exported (the same `instanceof` reason as `OracleFeeSourceUnavailableError`
-// above) — a consumer of `refreshOraclePrices` can catch it without importing
-// `resolveOracleRule` itself.
-export { OracleSourceNotImplementedError } from "./rule-registry.js";
+// `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`).
+export { WaterxRule, parseSignedEnvelope, BATCH_PRICE_INTENT, WATERX_INFRA, waterxQuoteCenterEndpoint, } from "./rules/waterx-rule.js";
+// `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).
+export { OracleSourceNotImplementedError, resolveOracleRule } from "./rule-registry.js";
 // Aggregation orchestrator
 export { aggregateTicker, aggregateTickerWithPyth, aggregateTickerWithConstant, refreshOraclePrices, } from "./aggregate.js";
 // Sponsor rule (fund open / reimburse + witness attach)

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

@@ -11,24 +11,23 @@
  * 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 subset of `PriceUpdateRuleKind`s 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.
  * `supra_rule` and `constant_rule` are auxiliary rules fed alongside whichever
- * source is selected (see `aggregateTicker`), not sources themselves;
- * `waterx_rule` has no `PriceUpdateRule` implementation yet. The SDK never
- * reads `process.env` — consumers resolve their own env var to this type.
+ * source is selected (see `aggregateTicker`), not sources themselves. The SDK
+ * never reads `process.env` — consumers resolve their own env var to this type.
  */
-export type OracleSource = "pyth_rule" | "pyth_lazer_rule";
+export type OracleSource = "pyth_rule" | "pyth_lazer_rule" | "waterx_rule";
 /**
  * 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 —
@@ -117,7 +116,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/src/oracle/price-update-rule.js

@@ -11,9 +11,9 @@
  * 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.
  */
 /**
  * Shared null → kind → shape guard ladder for a `PriceUpdateRule.buildUpdateCalls`

package/dist/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/src/oracle/pyth.js

@@ -16,6 +16,44 @@
 import { fromHex, toHex } from "@mysten/bcs";
 import { bcs } from "@mysten/sui/bcs";
 import { fetchWithPolicy, joinEndpointPath, rethrowExhaustedFetch, trimTrailingSlashes, } from "./update-fetch.js";
+export const 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.
+ */
+export function pythCoreHermesEndpoint(network) {
+    return 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.
+ */
+export const PYTH_PRO_HERMES_ENDPOINT = "https://pyth.dourolabs.app/hermes";
+/** Accessor mirror of {@link pythCoreHermesEndpoint} for the Pro base. */
+export function pythProHermesEndpoint() {
+    return PYTH_PRO_HERMES_ENDPOINT;
+}
 export class PythCache {
     pythStateInfo;
     wormholePackageId;
@@ -428,7 +466,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);
     }
@@ -523,7 +561,9 @@ export 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 = 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),
@@ -581,9 +621,9 @@ export async function buildPythPriceUpdateCalls(tx, host, updates, feedIds, opts
 }
 /** All-in-one: fetch from Hermes, append update calls. Returns PriceInfoObject IDs. */
 export 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 = PYTH_CORE_INFRA[host.network].hermes_endpoint;
     const updates = await fetchPriceFeedsUpdateData(endpoint, feedIds, {
         apiKey: host.pyth.api_key,
         fetch: host.pyth.fetch,

package/dist/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/src/oracle/read-plane.js

@@ -0,0 +1,74 @@
+/**
+ * `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 { pythCoreHermesEndpoint, pythProHermesEndpoint } from "./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.
+ */
+export function resolveHermesReadEndpoint(network, sources, override) {
+    if (sources.includes("pyth_rule"))
+        return pythCoreHermesEndpoint(network);
+    return override ?? pythProHermesEndpoint();
+}
+export function resolveOracleReadPlan(host, source, tickers) {
+    switch (source) {
+        case "pyth_rule":
+        case "pyth_lazer_rule": {
+            const hexFeeds = host.config.packages.pyth_rule?.feeds;
+            const feedIdByTicker = new Map();
+            for (const ticker of tickers) {
+                const feedId = 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) => 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.
+            const feeds = host.config.packages.waterx_rule?.feeds;
+            return {
+                plane: "quote_center",
+                tickers: feeds ? tickers.filter((ticker) => ticker in feeds) : [],
+                unreadable: [],
+            };
+        }
+        default: {
+            const exhausted = source;
+            throw new Error(`resolveOracleReadPlan: unhandled OracleSource '${String(exhausted)}'`);
+        }
+    }
+}

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

@@ -1,19 +1,22 @@
 /**
  * `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
- * back-stop any other source. Both are registered: `pyth_rule` (`PythCoreRule`,
- * Hermes VAA) and `pyth_lazer_rule` (`PythLazerRule`, Lazer signed updates).
- * Resolving a source with no registered rule throws a clear
- * `OracleSourceNotImplemented` error. There is deliberately no cross-source
- * fallback and no client-creation config guard: selecting a source whose feeds
- * are absent is not an error at init — it surfaces at tx-build time for the
- * specific tickers that source can't serve (see `refreshOraclePrices`).
+ * back-stop any other source. Three are registered: `pyth_rule`
+ * (`PythCoreRule`, Hermes VAA), `pyth_lazer_rule` (`PythLazerRule`, Lazer
+ * signed updates), and `waterx_rule` (`WaterxRule`, first-party quote-center
+ * ed25519 signed batches). Resolving a source with no registered rule throws a
+ * clear `OracleSourceNotImplemented` error. There is deliberately no
+ * cross-source fallback and no client-creation config guard: selecting a source
+ * whose feeds are absent is not an error at init — it surfaces at tx-build time
+ * for the specific tickers that source can't serve (see `refreshOraclePrices`).
  */
 import type { OracleSource, PriceUpdateRule } from "./price-update-rule.ts";
 /**

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

@@ -1,22 +1,26 @@
 /**
  * `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
- * back-stop any other source. Both are registered: `pyth_rule` (`PythCoreRule`,
- * Hermes VAA) and `pyth_lazer_rule` (`PythLazerRule`, Lazer signed updates).
- * Resolving a source with no registered rule throws a clear
- * `OracleSourceNotImplemented` error. There is deliberately no cross-source
- * fallback and no client-creation config guard: selecting a source whose feeds
- * are absent is not an error at init — it surfaces at tx-build time for the
- * specific tickers that source can't serve (see `refreshOraclePrices`).
+ * back-stop any other source. Three are registered: `pyth_rule`
+ * (`PythCoreRule`, Hermes VAA), `pyth_lazer_rule` (`PythLazerRule`, Lazer
+ * signed updates), and `waterx_rule` (`WaterxRule`, first-party quote-center
+ * ed25519 signed batches). Resolving a source with no registered rule throws a
+ * clear `OracleSourceNotImplemented` error. There is deliberately no
+ * cross-source fallback and no client-creation config guard: selecting a source
+ * whose feeds are absent is not an error at init — it surfaces at tx-build time
+ * for the specific tickers that source can't serve (see `refreshOraclePrices`).
  */
 import { PythCoreRule } from "./rules/pyth-core-rule.js";
 import { PythLazerRule } from "./rules/pyth-lazer-rule.js";
+import { WaterxRule } from "./rules/waterx-rule.js";
 /**
  * Production registry. Frozen — tests inject a fake rule via
  * `resolveOracleRule`'s `overrides` param instead of mutating this.
@@ -24,6 +28,7 @@ import { PythLazerRule } from "./rules/pyth-lazer-rule.js";
 const DEFAULT_RULES = Object.freeze({
     pyth_rule: PythCoreRule,
     pyth_lazer_rule: PythLazerRule,
+    waterx_rule: WaterxRule,
 });
 /**
  * Thrown by {@link resolveOracleRule} when `source` has no `PriceUpdateRule`

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

@@ -7,7 +7,7 @@
  * changes vs `../pyth.ts` / `./pyth-rule.ts`.
  */
 import { assertRuleUpdateData, } from "../price-update-rule.js";
-import { buildPythPriceUpdateCalls, endpointSupportedFeedIds, fetchPriceFeedsUpdateData, } from "../pyth.js";
+import { buildPythPriceUpdateCalls, endpointSupportedFeedIds, fetchPriceFeedsUpdateData, pythCoreHermesEndpoint, } from "../pyth.js";
 /**
  * Shape check ONLY — the `kind` discriminant is checked separately by the
  * caller before this runs, since a same-shaped payload from a different rule
@@ -33,10 +33,10 @@ export const 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 = pythCoreHermesEndpoint(host.network);
         const feedIds = tickers.map((ticker) => host.getPythFeed(ticker).feed_id);
         const updates = await fetchPriceFeedsUpdateData(endpoint, feedIds, {
             apiKey: host.pyth.api_key,

package/dist/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. */

package/dist/src/oracle/rules/pyth-lazer-rule.js

@@ -8,9 +8,34 @@
  * `Update` PTB value back through a `RuleUpdateHandle` for the feed calls.
  */
 import { fromHex } from "@mysten/bcs";
-import { LAZER_DEFAULTS } from "../config.js";
 import { assertRuleUpdateData, } from "../price-update-rule.js";
 import { fetchWithPolicy, joinEndpointPath, rethrowExhaustedFetch } from "../update-fetch.js";
+/**
+ * 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 const LAZER_INFRA = {
+    MAINNET: {
+        endpoint: "https://pyth-lazer.dourolabs.app",
+        verifier_package: "0xefbfd064480777699fd9c557a5804d72ace7bc82661fdc8d1f1a44ea6d92ee10",
+    },
+    TESTNET: {
+        endpoint: "https://pyth-lazer.dourolabs.app",
+        verifier_package: "0xf5bd2141967507050a91b58de3d95e77c432cd90d1799ee46effc27430a68c21",
+    },
+};
 /**
  * Signed-update request pins, mirroring what the on-chain rule consumes:
  * - `properties` — `price` + `exponent` are REQUIRED by
@@ -147,7 +172,7 @@ export const PythLazerRule = {
         if (!apiKey) {
             throw new LazerApiKeyMissingError();
         }
-        const update = await fetchLazerSignedUpdate(LAZER_DEFAULTS[host.network].endpoint, apiKey, feedIds, host.pyth.fetch);
+        const update = await fetchLazerSignedUpdate(LAZER_INFRA[host.network].endpoint, apiKey, feedIds, host.pyth.fetch);
         return { kind: "pyth_lazer_rule", payload: { update, feedIds } };
     },
     /**
@@ -184,7 +209,7 @@ export const PythLazerRule = {
             return undefined;
         const lazer = requireLazerPackage(host);
         const [update] = tx.moveCall({
-            target: `${LAZER_DEFAULTS[host.network].verifier_package}::pyth_lazer::parse_and_verify_le_ecdsa_update`,
+            target: `${LAZER_INFRA[host.network].verifier_package}::pyth_lazer::parse_and_verify_le_ecdsa_update`,
             arguments: [tx.object(lazer.state), tx.object.clock(), tx.pure.vector("u8", payload.update)],
         });
         return { kind: "pyth_lazer_rule", update };

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

@@ -7,6 +7,7 @@
  * `PriceInfoObject` is fresh.
  */
 import { feed as pythRuleFeed } from "../../generated/waterx_pyth_rule/pyth_rule.js";
+import { PYTH_CORE_INFRA } from "../pyth.js";
 export function feedPythRule(tx, host, collector, priceInfoObjectId) {
     pythRuleFeed({
         package: host.config.packages.pyth_rule.published_at,
@@ -15,10 +16,10 @@ export function feedPythRule(tx, host, collector, priceInfoObjectId) {
             config: tx.object(host.config.packages.pyth_rule.config),
             // The deployed pyth_rule package is compiled against the Core pyth
             // dependency, so its `&PythState` parameter is the Core-package-qualified
-            // type and `host.pyth` (the fixed per-network Core infra) is always the
-            // right state to pass. The config's price_info_object entries are Core
-            // objects to match.
-            pythState: tx.object(host.pyth.state_id),
+            // type and the Core source's own per-network state (`PYTH_CORE_INFRA`)
+            // is always the right state to pass. The config's price_info_object
+            // entries are Core objects to match.
+            pythState: tx.object(PYTH_CORE_INFRA[host.network].state_id),
             pythPriceInfo: tx.object(priceInfoObjectId),
         },
     })(tx);