@waterx/sdk 4.1.0 → 4.3.1

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,81 @@
+/**
+ * `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 { ownEntry } from "../utils/record.js";
+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": {
+            // 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 = 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) => 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) => ownEntry(feeds, ticker) !== undefined),
+                unreadable: [],
+            };
+        }
+        default: {
+            const exhausted = source;
+            throw new Error(`resolveOracleReadPlan: unhandled OracleSource '${String(exhausted)}'`);
+        }
+    }
+}

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

@@ -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/src/oracle/rules/pyth-core-rule.js

@@ -6,8 +6,9 @@
  * across rules by `kind`. Mechanical wrap only — no on-chain/off-chain logic
  * changes vs `../pyth.ts` / `./pyth-rule.ts`.
  */
+import { ownEntry } from "../../utils/record.js";
 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 +34,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,
@@ -76,7 +77,7 @@ export const 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 = ownEntry(host.config.packages.pyth_rule?.feeds, ticker)?.feed_id;
             if (feedId === undefined || !packedFeedIds.has(feedId))
                 return null;
             feedIds.push(feedId);

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,35 @@
  * `Update` PTB value back through a `RuleUpdateHandle` for the feed calls.
  */
 import { fromHex } from "@mysten/bcs";
-import { LAZER_DEFAULTS } from "../config.js";
+import { ownEntry } from "../../utils/record.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
@@ -137,7 +163,9 @@ export const PythLazerRule = {
         // not fail per ticker as if only that feed were missing.
         const { feeds } = requireLazerPackage(host);
         const feedIds = tickers.map((ticker) => {
-            const feedId = feeds[ticker];
+            // ownEntry: a prototype-key ticker ("toString") must throw here as
+            // unlisted, not turn an inherited Function into a "feed id".
+            const feedId = ownEntry(feeds, ticker);
             if (feedId === undefined) {
                 throw new Error(`No pyth_lazer_rule feed listed for ticker: ${ticker}`);
             }
@@ -147,7 +175,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 } };
     },
     /**
@@ -165,7 +193,7 @@ export const PythLazerRule = {
             return null;
         const packedFeedIds = new Set(payload.feedIds);
         for (const ticker of tickers) {
-            const feedId = host.config.packages.pyth_lazer_rule?.feeds?.[ticker];
+            const feedId = ownEntry(host.config.packages.pyth_lazer_rule?.feeds, ticker);
             if (feedId === undefined || !packedFeedIds.has(feedId))
                 return null;
         }
@@ -184,7 +212,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);

package/dist/src/oracle/rules/waterx-rule.d.ts

@@ -4,7 +4,7 @@
  * `aggregateTicker` appends per waterx-routed ticker. Pulls one enclave-signed
  * batch envelope covering every requested ticker from the quote-center
  * (`GET /v1/quotes/update?symbols=…`, endpoint from `host.waterx` — the
- * `waterxEndpoint`/`waterxFetch` create options — else `WATERX_DEFAULTS`), then —
+ * `waterxEndpoint`/`waterxFetch` create options — else its own `WATERX_INFRA`), then —
  * unlike Pyth Lazer, whose verify is a single shared PTB step — verifies AND
  * feeds in ONE `waterx_rule::collect_batch_latest` call per collector (the Move
  * API bundles the two). So `buildUpdateCalls` emits nothing and the signed
@@ -13,12 +13,47 @@
  * `collect_batch_latest` is the dual-rule path: it feeds the item matching
  * `collector.symbol()` WITHOUT aggregating, so a waterx-routed ticker composes
  * onto the same collector as Pyth/Supra (compose-then-aggregate). On-chain a
- * freshness miss / replayed timestamp ABSTAINS (the other weighted rules
- * cover); a config/integrity mismatch or bad signature aborts.
+ * FRESHNESS miss ABSTAINS (the other weighted rules cover); a config/
+ * integrity mismatch, bad signature, future timestamp — or a REPLAYED signed
+ * timestamp — ABORTS (`EReplayedSignature`, audit F-014: a signed tuple is
+ * single-use per symbol, enforced by a per-symbol high-water mark BEFORE any
+ * weight arbitration). Consequence for concurrent builds: two PTBs carrying
+ * the same envelope for the same symbol cannot both land — the second aborts
+ * even if the rule is unweighted for that ticker. Never share one fetched
+ * envelope across builds that may execute concurrently for the same symbol.
  */
 import type { Transaction, TransactionArgument } from "@mysten/sui/transactions";
+import type { Network } from "../../constants.ts";
 import type { OracleHost } from "../host.ts";
 import { type PriceUpdateRule, type RuleUpdateData } from "../price-update-rule.ts";
+/** The single signing intent the quote-center emits — exported so read-plane
+ *  consumers can mirror the rule's own envelope intent check (a mispointed
+ *  endpoint must be rejected by reads exactly as tx-builds reject it). */
+export declare const BATCH_PRICE_INTENT = 1;
+/**
+ * WaterX quote-center external infra — owned by THIS source, by network.
+ * Mirrors `PYTH_CORE_INFRA` (oracle/pyth.ts) and `LAZER_INFRA`
+ * (rules/pyth-lazer-rule.ts): per-network constants for infrastructure the
+ * source's operator runs, co-located with the only rule that reads them — no
+ * other oracle source ever touches a quote-center endpoint. Public read (no
+ * auth), so there is no api_key. `endpoint` has no trailing slash — the rule
+ * appends the path.
+ *
+ * These are the DEFAULTS behind the caller's `client.waterx` access slice
+ * (`waterxEndpoint` / `waterxFetch` create options) — the browser-CORS proxy
+ * hook, since this is the one source fetched from the page.
+ */
+export declare const WATERX_INFRA: Record<Network, {
+    endpoint: string;
+}>;
+/**
+ * The waterx source's quote-center base for `network` — the ONE accessor
+ * consumers (BE/FE read planes) use when, and only when, their own
+ * `ORACLE_SOURCE` resolves to `'waterx_rule'`. Mirrors
+ * `pythCoreHermesEndpoint`. Under any other source the read endpoint is that
+ * source's own configuration — never this one.
+ */
+export declare function waterxQuoteCenterEndpoint(network: Network): string;
 /**
  * One item inside a signed batch payload, mirroring the quote-center
  * `/v1/quotes/update` JSON 1:1 (snake_case). The u64 integer fields are the
@@ -82,8 +117,10 @@ export declare function waterxEnvelopeOf(data: RuleUpdateData): WaterxSignedEnve
  * per item, the exact shape the enclave signed) and contribute the price for
  * `collector.symbol()` to the collector. One collect call re-verifies the batch
  * signature and picks this collector's symbol out of the batch; on-chain it
- * abstains (records `none`) instead of aborting when the symbol is stale,
- * absent from the batch, or its timestamp was already accepted (replay).
+ * abstains (records `none`) when the symbol is stale or absent from the batch,
+ * but ABORTS `EReplayedSignature` when the symbol's signed timestamp was
+ * already accepted (per-symbol high-water mark, audit F-014) — see the module
+ * header for the concurrent-build consequence.
  */
 export declare function feedWaterxRule(tx: Transaction, host: OracleHost, collector: TransactionArgument, envelope: WaterxSignedEnvelope): void;
 export declare const WaterxRule: PriceUpdateRule;

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

@@ -4,7 +4,7 @@
  * `aggregateTicker` appends per waterx-routed ticker. Pulls one enclave-signed
  * batch envelope covering every requested ticker from the quote-center
  * (`GET /v1/quotes/update?symbols=…`, endpoint from `host.waterx` — the
- * `waterxEndpoint`/`waterxFetch` create options — else `WATERX_DEFAULTS`), then —
+ * `waterxEndpoint`/`waterxFetch` create options — else its own `WATERX_INFRA`), then —
  * unlike Pyth Lazer, whose verify is a single shared PTB step — verifies AND
  * feeds in ONE `waterx_rule::collect_batch_latest` call per collector (the Move
  * API bundles the two). So `buildUpdateCalls` emits nothing and the signed
@@ -13,16 +13,51 @@
  * `collect_batch_latest` is the dual-rule path: it feeds the item matching
  * `collector.symbol()` WITHOUT aggregating, so a waterx-routed ticker composes
  * onto the same collector as Pyth/Supra (compose-then-aggregate). On-chain a
- * freshness miss / replayed timestamp ABSTAINS (the other weighted rules
- * cover); a config/integrity mismatch or bad signature aborts.
+ * FRESHNESS miss ABSTAINS (the other weighted rules cover); a config/
+ * integrity mismatch, bad signature, future timestamp — or a REPLAYED signed
+ * timestamp — ABORTS (`EReplayedSignature`, audit F-014: a signed tuple is
+ * single-use per symbol, enforced by a per-symbol high-water mark BEFORE any
+ * weight arbitration). Consequence for concurrent builds: two PTBs carrying
+ * the same envelope for the same symbol cannot both land — the second aborts
+ * even if the rule is unweighted for that ticker. Never share one fetched
+ * envelope across builds that may execute concurrently for the same symbol.
  */
 import { fromHex } from "@mysten/bcs";
 import { collectBatchLatest, newBatchItem, newBatchPayload, pushBatchItem, } from "../../generated/waterx_rule/waterx_rule.js";
-import { WATERX_DEFAULTS } from "../config.js";
+import { ownEntry } from "../../utils/record.js";
 import { assertRuleUpdateData, } from "../price-update-rule.js";
 import { FetchPolicyError, fetchWithPolicy, joinEndpointPath, } from "../update-fetch.js";
-/** The single signing intent (`BATCH_PRICE_INTENT`) the quote-center emits. */
-const BATCH_PRICE_INTENT = 1;
+/** The single signing intent the quote-center emits — exported so read-plane
+ *  consumers can mirror the rule's own envelope intent check (a mispointed
+ *  endpoint must be rejected by reads exactly as tx-builds reject it). */
+export const BATCH_PRICE_INTENT = 1;
+/**
+ * WaterX quote-center external infra — owned by THIS source, by network.
+ * Mirrors `PYTH_CORE_INFRA` (oracle/pyth.ts) and `LAZER_INFRA`
+ * (rules/pyth-lazer-rule.ts): per-network constants for infrastructure the
+ * source's operator runs, co-located with the only rule that reads them — no
+ * other oracle source ever touches a quote-center endpoint. Public read (no
+ * auth), so there is no api_key. `endpoint` has no trailing slash — the rule
+ * appends the path.
+ *
+ * These are the DEFAULTS behind the caller's `client.waterx` access slice
+ * (`waterxEndpoint` / `waterxFetch` create options) — the browser-CORS proxy
+ * hook, since this is the one source fetched from the page.
+ */
+export const WATERX_INFRA = {
+    MAINNET: { endpoint: "https://quote-center.waterx.app" },
+    TESTNET: { endpoint: "https://quote-center-staging.waterx.app" },
+};
+/**
+ * The waterx source's quote-center base for `network` — the ONE accessor
+ * consumers (BE/FE read planes) use when, and only when, their own
+ * `ORACLE_SOURCE` resolves to `'waterx_rule'`. Mirrors
+ * `pythCoreHermesEndpoint`. Under any other source the read endpoint is that
+ * source's own configuration — never this one.
+ */
+export function waterxQuoteCenterEndpoint(network) {
+    return WATERX_INFRA[network].endpoint;
+}
 /**
  * Shape check ONLY — the `kind` discriminant is checked separately by the
  * caller before this runs (mirrors the other rules' guard split), so a
@@ -84,18 +119,21 @@ function requireWaterxPackage(host) {
     return entry;
 }
 /**
- * Resolve the quote-center infra for this host: the `waterxEndpoint` /
- * `waterxFetch` create options when the client carries them, else the network
- * default. The fetch policy falls back to the shared `pyth.fetch` policy so a
- * consumer that already tuned timeouts/retries once keeps them here.
+ * Resolve the quote-center infra for this host: each field independently from
+ * the caller's `client.waterx` access slice (`waterxEndpoint` / `waterxFetch`
+ * create options) when set, else this source's own `WATERX_INFRA` default /
+ * `fetchWithPolicy`'s built-ins. Deliberately NO fallback onto `pyth.fetch`
+ * or any other source's policy — sources stay fully independent.
  *
  * This is the seam a browser consumer needs: the envelope is fetched FROM THE
  * PAGE, so a front end whose origin the quote-center does not allow (CORS)
  * points `endpoint` at a same-origin proxy, or supplies its own `fetchImpl`.
  */
 function resolveWaterxInfra(host) {
-    const infra = host.waterx ?? WATERX_DEFAULTS[host.network];
-    return { endpoint: infra.endpoint, fetch: infra.fetch ?? host.pyth.fetch };
+    return {
+        endpoint: host.waterx?.endpoint ?? WATERX_INFRA[host.network].endpoint,
+        fetch: host.waterx?.fetch,
+    };
 }
 /**
  * Pull one enclave-signed batch envelope covering `symbols` from the
@@ -151,8 +189,10 @@ function decodeSig(hex) {
  * per item, the exact shape the enclave signed) and contribute the price for
  * `collector.symbol()` to the collector. One collect call re-verifies the batch
  * signature and picks this collector's symbol out of the batch; on-chain it
- * abstains (records `none`) instead of aborting when the symbol is stale,
- * absent from the batch, or its timestamp was already accepted (replay).
+ * abstains (records `none`) when the symbol is stale or absent from the batch,
+ * but ABORTS `EReplayedSignature` when the symbol's signed timestamp was
+ * already accepted (per-symbol high-water mark, audit F-014) — see the module
+ * header for the concurrent-build consequence.
  */
 export function feedWaterxRule(tx, host, collector, envelope) {
     const wr = requireWaterxPackage(host);
@@ -221,7 +261,9 @@ export const WaterxRule = {
         // not fail per ticker as if only that feed were missing.
         const { feeds } = requireWaterxPackage(host);
         for (const ticker of tickers) {
-            if (feeds[ticker] === undefined) {
+            // ownEntry: a prototype-key ticker ("toString") must throw here as
+            // unlisted, not pass as an inherited Function and reach the network.
+            if (ownEntry(feeds, ticker) === undefined) {
                 throw new Error(`No waterx_rule feed listed for ticker: ${ticker}`);
             }
         }

package/dist/src/oracle/source-list.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `source-list.ts` — THE parser for a consumer's `ORACLE_SOURCE` env string
+ * (comma list of `OracleSource` values → the fed set). The FE and BE
+ * previously carried twin hand-written parsers whose semantics drifted once
+ * in review (a trailing comma booted one deployment green and 500'd the
+ * other); this canonical behavior is what both fold onto:
+ *
+ *  - split on `,`, trim entries, DROP empties (trailing/doubled commas are
+ *    the most common env typo, never a boot failure)
+ *  - validate every entry against {@link ORACLE_SOURCES}
+ *  - dedupe, order-preserving (list order is consumer read-plane policy —
+ *    the SDK's own fed-set build treats the list as a set)
+ *  - throw an operator-actionable error on empty/unset/invalid input —
+ *    there is NO default oracle source
+ *
+ * The SDK still never reads `process.env` — callers pass the raw string.
+ *
+ * STRICTER than the consumers' previous `in`-operator checks: a value named
+ * like an `Object.prototype` key (`toString`, `constructor`, …) passed those
+ * and died deep in the stack; `Set.has` rejects it here at parse.
+ *
+ * Zod adopters: this THROWS a plain Error. Inside a zod `.transform()` a
+ * throw escapes `schema.parse()` un-aggregated and masks sibling issues —
+ * wrap it: `try { return parseOracleSourceList(raw); } catch (e) {
+ * ctx.addIssue({ code: "custom", message: (e as Error).message }); return
+ * z.NEVER; }`.
+ */
+import { type OracleSource } from "./price-update-rule.ts";
+/**
+ * THE runtime membership check for {@link ORACLE_SOURCES} — the parser below
+ * and `PerpClient`'s ctor validation both use this one predicate, so the env
+ * parser and the create-option front door can never disagree. `Set.has`,
+ * never `in`/bracket reads (prototype-chain safe by construction).
+ */
+export declare function isOracleSource(value: string): value is OracleSource;
+export declare function parseOracleSourceList(raw: string | null | undefined): OracleSource[];

package/dist/src/oracle/source-list.js

@@ -0,0 +1,53 @@
+/**
+ * `source-list.ts` — THE parser for a consumer's `ORACLE_SOURCE` env string
+ * (comma list of `OracleSource` values → the fed set). The FE and BE
+ * previously carried twin hand-written parsers whose semantics drifted once
+ * in review (a trailing comma booted one deployment green and 500'd the
+ * other); this canonical behavior is what both fold onto:
+ *
+ *  - split on `,`, trim entries, DROP empties (trailing/doubled commas are
+ *    the most common env typo, never a boot failure)
+ *  - validate every entry against {@link ORACLE_SOURCES}
+ *  - dedupe, order-preserving (list order is consumer read-plane policy —
+ *    the SDK's own fed-set build treats the list as a set)
+ *  - throw an operator-actionable error on empty/unset/invalid input —
+ *    there is NO default oracle source
+ *
+ * The SDK still never reads `process.env` — callers pass the raw string.
+ *
+ * STRICTER than the consumers' previous `in`-operator checks: a value named
+ * like an `Object.prototype` key (`toString`, `constructor`, …) passed those
+ * and died deep in the stack; `Set.has` rejects it here at parse.
+ *
+ * Zod adopters: this THROWS a plain Error. Inside a zod `.transform()` a
+ * throw escapes `schema.parse()` un-aggregated and masks sibling issues —
+ * wrap it: `try { return parseOracleSourceList(raw); } catch (e) {
+ * ctx.addIssue({ code: "custom", message: (e as Error).message }); return
+ * z.NEVER; }`.
+ */
+import { ORACLE_SOURCES } from "./price-update-rule.js";
+// Widened-annotation Set (not an assertion) so the type predicate below
+// narrows by CONSTRUCTION rather than by cast.
+const ORACLE_SOURCE_SET = new Set(ORACLE_SOURCES);
+/**
+ * THE runtime membership check for {@link ORACLE_SOURCES} — the parser below
+ * and `PerpClient`'s ctor validation both use this one predicate, so the env
+ * parser and the create-option front door can never disagree. `Set.has`,
+ * never `in`/bracket reads (prototype-chain safe by construction).
+ */
+export function isOracleSource(value) {
+    return ORACLE_SOURCE_SET.has(value);
+}
+export function parseOracleSourceList(raw) {
+    const parts = (raw ?? "")
+        .split(",")
+        .map((part) => part.trim())
+        .filter((part) => part !== "");
+    const sources = parts.filter(isOracleSource);
+    if (parts.length === 0 || sources.length !== parts.length) {
+        const got = raw == null || raw.trim() === "" ? "unset" : `'${raw}'`;
+        throw new Error(`ORACLE_SOURCE must be a comma-separated list of ${ORACLE_SOURCES.join(" | ")} ` +
+            `(got ${got}) — there is NO default oracle source; set it in the deployment's env.`);
+    }
+    return [...new Set(sources)];
+}