@waterx/sdk 4.1.0 → 4.3.1

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

@@ -11,7 +11,6 @@
  */
 import type { BasePackageEntry } from "../account/config.ts";
 import type { BaseLineConfig } from "../base-client.ts";
-import type { Network } from "../constants.ts";
 import type { FetchPolicy } from "./update-fetch.ts";
 export interface PythRulePackage extends BasePackageEntry {
     config: string;
@@ -31,7 +30,7 @@ export interface PythSponsorRulePackage extends BasePackageEntry {
  *
  * `enabled` mirrors the JSON field verbatim but MUST NOT be read for routing —
  * which rule prices a ticker is decided solely by the client's `oracleSource`
- * create option (see `OracleHost.oracleSource`), never by this flag or any
+ * create option (see `OracleHost.oracleSources`), never by this flag or any
  * other config value.
  */
 export interface PythLazerRulePackage extends BasePackageEntry {
@@ -99,11 +98,12 @@ export interface WaterxRuleFeedEntry {
  * Read by `WaterxRule` (`rules/waterx-rule.ts`): `feeds` for ticker support,
  * `config`/`enclave_config`/`enclave` for the `collect_batch_latest` call,
  * `published_at` for the package address. The off-chain signed price is pulled
- * from the quote-center (endpoint from {@link WATERX_DEFAULTS}), not this JSON.
+ * from the quote-center (endpoint from the rule-owned `WATERX_INFRA` table in
+ * `rules/waterx-rule.ts`), not this JSON.
  *
  * `enabled` mirrors the JSON field verbatim but MUST NOT be read for routing —
  * which rule prices a ticker is decided solely by the client's `oracleSource`
- * create option (see `OracleHost.oracleSource`), mirroring `pyth_lazer_rule`.
+ * create option (see `OracleHost.oracleSources`), mirroring `pyth_lazer_rule`.
  */
 export interface WaterxRulePackage extends BasePackageEntry {
     /** Shared `waterx_rule::Config` (per-symbol on-chain feed_config). */
@@ -137,17 +137,6 @@ export interface OraclePackages {
     waterx_rule?: WaterxRulePackage;
     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
@@ -160,18 +149,24 @@ export type PythFetchPolicy = {
     timeoutMs?: number;
     retries?: number;
 };
-export interface PythInfraConfig {
-    state_id: string;
-    wormhole_state_id: string;
-    hermes_endpoint: string;
+/**
+ * `client.pyth` — ONLY the caller-supplied Pyth credential + fetch policy,
+ * shared by the Pyth-family rules (`pyth_rule`, `pyth_lazer_rule`). It carries
+ * NO endpoints and NO on-chain object ids: every oracle source owns its own
+ * infra, co-located with its rule (`PYTH_CORE_INFRA` in `oracle/pyth.ts`;
+ * the Lazer constants inside `rules/pyth-lazer-rule.ts`). A non-Pyth source
+ * never reads this slice.
+ * Nothing here is sourced from the canonical `waterx-config` JSON — a Bearer
+ * secret has no place in a public CDN document.
+ */
+export interface PythAccessConfig {
     /**
-     * Pyth Pro / Lazer access token (`Authorization: Bearer …`) for
+     * Pyth access token (`Authorization: Bearer …`). Required by
      * `PythLazerRule`'s signed-update fetch — Lazer is auth-first, so there is
-     * no keyless default. Optional: Pyth-Core-only deployments never need it.
-     * Supplied via the `pythApiKey` create option (the SDK never reads
-     * `process.env` or the config JSON). Absent when a lazer-routed fetch runs →
-     * `LazerApiKeyMissing` is thrown at fetch time. As of the Pyth Pro
-     * migration (post-2026-08-18, per
+     * no keyless default; absent when a lazer-routed fetch runs →
+     * `LazerApiKeyMissing` is thrown at fetch time. Supplied via the
+     * `pythApiKey` create option (the SDK never reads `process.env` or the
+     * config JSON). As of the Pyth Pro migration (post-2026-08-18, per
      * https://docs.pyth.network/price-feeds/core/upgrade) this is ALSO required
      * for `pyth_rule`'s Hermes fetch (`fetchPriceFeedsUpdateData`) — see
      * `fetch` below.
@@ -187,66 +182,37 @@ export interface PythInfraConfig {
      */
     fetch?: PythFetchPolicy;
 }
-export declare const PYTH_DEFAULTS: Record<Network, PythInfraConfig>;
-/**
- * Pyth Lazer (Pyth Pro) external infra the `PythLazerRule` needs, by network.
- * Mirrors {@link PYTH_DEFAULTS}: per-network constants for infrastructure Pyth
- * operates (not part of the `waterx-config` JSON). A fuller `PYTH_INFRA`
- * restructure is deferred — this stays a minimal map until then.
- *
- * - `endpoint` — Lazer HTTP API base; signed updates come from
- *   `POST /v1/latest_price` (Bearer-authenticated). The service is
- *   network-agnostic (one signed payload verifies on any chain that trusts the
- *   Lazer signers), so both networks share the production host.
- * - `verifier_package` — the Sui package carrying
- *   `pyth_lazer::parse_and_verify_le_ecdsa_update`. Per-network: testnet is
- *   still the original v1 publish; mainnet is the v2-upgraded package (which
- *   still exposes the v1 entry `pyth_lazer_rule` binds). Values mirror the
- *   contract repo's `pyth_lazer_rule/Move.toml` published-at pins.
- */
-export declare const LAZER_DEFAULTS: Record<Network, {
-    endpoint: string;
-    verifier_package: string;
-}>;
 /**
- * Resolved WaterX quote-center infra for `WaterxRule` — the network default
- * from {@link WATERX_DEFAULTS}, with both fields overridable at client init
- * (`waterxEndpoint` / `waterxFetch`).
+ * `client.waterx` — ONLY the caller-supplied quote-center overrides for
+ * `WaterxRule`, mirroring {@link PythAccessConfig}: no resolved infra lives on
+ * the client. When a field is unset the rule resolves it against its OWN
+ * per-network table (`WATERX_INFRA` in `rules/waterx-rule.ts`) — no other
+ * source's endpoint or policy is ever consulted.
  *
- * The override exists because this is the one oracle source a BROWSER fetches
- * itself: the rule pulls the signed envelope from the page, so it is subject to
- * the quote-center deployment's CORS allowlist. A front end whose origin is not
- * on that list — or one that must route egress through its own backend — points
- * `endpoint` at a same-origin proxy (or supplies `fetch.fetchImpl`) instead of
- * being locked to the hardcoded host.
+ * The endpoint override exists because this is the one oracle source a BROWSER
+ * fetches itself: the rule pulls the signed envelope from the page, so it is
+ * subject to the quote-center deployment's CORS allowlist. A front end whose
+ * origin is not on that list — or one that must route egress through its own
+ * backend — points `endpoint` at a same-origin proxy (or supplies
+ * `fetch.fetchImpl`) instead of being locked to the default host.
  */
-export interface WaterxInfraConfig {
+export interface WaterxAccessConfig {
     /**
-     * Quote-center base URL. A base PATH is preserved — the rule appends via
-     * `joinEndpointPath`, so `https://app.example/api/quote-center` resolves to
+     * Quote-center base URL override (`waterxEndpoint` create option). A base
+     * PATH is preserved — the rule appends via `joinEndpointPath`, so
+     * `https://app.example/api/quote-center` resolves to
      * `…/api/quote-center/v1/quotes/update` and a proxy route is not rewritten
      * away. A trailing slash is trimmed.
      */
-    endpoint: string;
+    endpoint?: string;
     /**
      * Retry/timeout policy (and `fetchImpl`) for the quote-center fetch — see
      * `fetchWithPolicy` (`./update-fetch.ts`). Supplied via the `waterxFetch`
-     * create option. When unset the rule falls back to the shared `pyth.fetch`
-     * policy, then to `fetchWithPolicy`'s defaults (15s timeout, 2 retries).
+     * create option. Falls back to `fetchWithPolicy`'s built-in defaults (15s
+     * timeout, 2 retries) when unset — never to another source's policy.
      */
     fetch?: FetchPolicy;
 }
-/**
- * WaterX quote-center base URL by network — the first-party TEE-signed price
- * hub `WaterxRule` pulls from (`GET /v1/quotes/update?symbols=…`). Mirrors
- * {@link LAZER_DEFAULTS}: infra WaterX operates, not part of the `waterx-config`
- * JSON. Public read (no auth), so there is no api_key. `endpoint` has no
- * trailing slash — the rule appends the path.
- *
- * These are DEFAULTS, not a hard pin: a consumer overrides them per client via
- * `waterxEndpoint` / `waterxFetch` (resolved onto `client.waterx`).
- */
-export declare const WATERX_DEFAULTS: Record<Network, WaterxInfraConfig>;
 /**
  * The narrow config shape the oracle/refresh code needs. `WaterXConfig`
  * (the perp line's full config) is assignable to this, so `PerpClient` satisfies

package/dist/src/oracle/config.js

@@ -9,58 +9,4 @@
  * depends on this shared schema instead of the perp line's full config —
  * mirrors the earlier account-config hoist.
  */
-export const PYTH_DEFAULTS = {
-    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",
-    },
-};
-// ============================================================================
-// Pyth Lazer — external infra, defaults by network
-// ============================================================================
-/**
- * Pyth Lazer (Pyth Pro) external infra the `PythLazerRule` needs, by network.
- * Mirrors {@link PYTH_DEFAULTS}: per-network constants for infrastructure Pyth
- * operates (not part of the `waterx-config` JSON). A fuller `PYTH_INFRA`
- * restructure is deferred — this stays a minimal map until then.
- *
- * - `endpoint` — Lazer HTTP API base; signed updates come from
- *   `POST /v1/latest_price` (Bearer-authenticated). The service is
- *   network-agnostic (one signed payload verifies on any chain that trusts the
- *   Lazer signers), so both networks share the production host.
- * - `verifier_package` — the Sui package carrying
- *   `pyth_lazer::parse_and_verify_le_ecdsa_update`. Per-network: testnet is
- *   still the original v1 publish; mainnet is the v2-upgraded package (which
- *   still exposes the v1 entry `pyth_lazer_rule` binds). Values mirror the
- *   contract repo's `pyth_lazer_rule/Move.toml` published-at pins.
- */
-export const LAZER_DEFAULTS = {
-    MAINNET: {
-        endpoint: "https://pyth-lazer.dourolabs.app",
-        verifier_package: "0xefbfd064480777699fd9c557a5804d72ace7bc82661fdc8d1f1a44ea6d92ee10",
-    },
-    TESTNET: {
-        endpoint: "https://pyth-lazer.dourolabs.app",
-        verifier_package: "0xf5bd2141967507050a91b58de3d95e77c432cd90d1799ee46effc27430a68c21",
-    },
-};
-/**
- * WaterX quote-center base URL by network — the first-party TEE-signed price
- * hub `WaterxRule` pulls from (`GET /v1/quotes/update?symbols=…`). Mirrors
- * {@link LAZER_DEFAULTS}: infra WaterX operates, not part of the `waterx-config`
- * JSON. Public read (no auth), so there is no api_key. `endpoint` has no
- * trailing slash — the rule appends the path.
- *
- * These are DEFAULTS, not a hard pin: a consumer overrides them per client via
- * `waterxEndpoint` / `waterxFetch` (resolved onto `client.waterx`).
- */
-export const WATERX_DEFAULTS = {
-    MAINNET: { endpoint: "https://quote-center.waterx.app" },
-    TESTNET: { endpoint: "https://quote-center-staging.waterx.app" },
-};
+export {};

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

@@ -9,37 +9,41 @@
  */
 import type { SuiGrpcClient } from "@mysten/sui/grpc";
 import type { Network } from "../constants.ts";
-import type { OracleConfig, PythInfraConfig, WaterxInfraConfig } from "./config.ts";
+import type { OracleConfig, PythAccessConfig, WaterxAccessConfig } from "./config.ts";
 import type { OracleSource } from "./price-update-rule.ts";
 export interface OracleHost {
-    /** Sui network this client targets — selects per-network external-infra defaults (e.g. `LAZER_DEFAULTS`). */
+    /** Sui network this client targets — each rule keys its OWN infra table by it (`PYTH_CORE_INFRA`, `LAZER_INFRA`). */
     readonly network: Network;
     /** Oracle slice of the canonical `waterx-config` JSON (rule packages + per-ticker feeds). */
     readonly config: OracleConfig;
-    /** External Pyth/Wormhole/Hermes infra — fixed per `(network, generation)`; api_key/fetch layered from create options. */
-    readonly pyth: PythInfraConfig;
+    /** Caller-supplied Pyth credential + fetch policy (create options) — NO endpoints, NO object ids. */
+    readonly pyth: PythAccessConfig;
     /**
-     * WaterX quote-center infra for `WaterxRule` — endpoint + fetch policy,
-     * resolved from the `waterxEndpoint` / `waterxFetch` create options.
-     *
-     * OPTIONAL so an existing host stays a valid `OracleHost`: when absent the
-     * rule falls back to `WATERX_DEFAULTS[network]`. This is the hook a browser
-     * consumer uses to route the quote-center fetch through a same-origin proxy
-     * (`endpoint`) or its own transport (`fetch.fetchImpl`) — that request is
-     * made from the page, so it is bound by the quote-center's CORS allowlist.
+     * Caller-supplied WaterX quote-center overrides for `WaterxRule`
+     * (`waterxEndpoint` / `waterxFetch` create options) — access-only, mirroring
+     * `pyth` above. OPTIONAL so an existing host stays a valid `OracleHost`;
+     * unset fields resolve against the rule's own `WATERX_INFRA[network]` table.
+     * This is the hook a browser consumer uses to route the quote-center fetch
+     * through a same-origin proxy (`endpoint`) or its own transport
+     * (`fetch.fetchImpl`) — that request is made from the page, so it is bound
+     * by the quote-center's CORS allowlist.
      */
-    readonly waterx?: WaterxInfraConfig;
+    readonly waterx?: WaterxAccessConfig;
     /** gRPC client for the on-chain reads the Pyth update path needs. */
     readonly grpcClient: SuiGrpcClient;
     /**
-     * Client-selected oracle rule source for `refreshOraclePrices`'s on-chain
-     * update leg — resolved at client creation from the `oracleSource` create
-     * option (default `'pyth_rule'`). Routing is driven by this value ALONE:
-     * never by a config JSON `enabled` flag (e.g. a future `pyth_lazer_rule.enabled`)
-     * and never by `process.env` — the SDK never reads it; consumers (BE/FE) wire
-     * this option from their own env var.
+     * The FED SET for `refreshOraclePrices`'s update legs — the REQUIRED
+     * `oracleSource` create option normalized to a non-empty, deduped list.
+     * Every listed source's data is fetched and fed in one build; the chain's
+     * per-ticker weight tables decide which contributions count (feeding an
+     * unweighted rule is dropped on-chain; starving a weighted one aborts), so
+     * during weight migrations the list stays a SUPERSET of every ticker's
+     * weighted set. Routing is driven by this value ALONE: never by a config
+     * JSON `enabled` flag and never by `process.env` — the SDK never reads it;
+     * consumers (BE/FE) wire this option from their own env var
+     * (`ORACLE_SOURCE`, comma-separated).
      */
-    readonly oracleSource: OracleSource;
+    readonly oracleSources: readonly OracleSource[];
     /** True when `ticker` is priced by `constant_rule`. */
     isConstantTicker(ticker: string): boolean;
     /** The `supra_rule` config when deployed, enabled, and fully wired; else `undefined`. */

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

@@ -18,15 +18,19 @@
 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 { ORACLE_SOURCES } from "./price-update-rule.ts";
+export { isOracleSource, parseOracleSourceList } from "./source-list.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 { WaterxRule, parseSignedEnvelope } from "./rules/waterx-rule.ts";
+export { WaterxRule, parseSignedEnvelope, BATCH_PRICE_INTENT, WATERX_INFRA, waterxQuoteCenterEndpoint, waterxEnvelopeOf, } from "./rules/waterx-rule.ts";
 export type { WaterxUpdatePayload, WaterxSignedEnvelope, WaterxBatchItem, } from "./rules/waterx-rule.ts";
-export { OracleSourceNotImplementedError } from "./rule-registry.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,24 +33,46 @@ 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";
+// Canonical OracleSource value list + THE env-string parser consumers fold
+// onto — semantics and rationale in `source-list.ts`'s header.
+export { ORACLE_SOURCES } from "./price-update-rule.js";
+export { isOracleSource, parseOracleSourceList } from "./source-list.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";
+// `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 } from "./rules/waterx-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";
+export { WaterxRule, parseSignedEnvelope, BATCH_PRICE_INTENT, WATERX_INFRA, waterxQuoteCenterEndpoint, 
+// Rule-owned payload accessor (kind-check + unwrap in one place) — never
+// hand-cast the payload shape.
+waterxEnvelopeOf, } 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,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/src/oracle/price-update-rule.js

@@ -11,10 +11,29 @@
  * 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.
  */
+/**
+ * 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 const 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/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,