@waterx/sdk 4.0.1 → 4.3.0

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

@@ -0,0 +1,126 @@
+/**
+ * `WaterxRule` — `PriceUpdateRule` for the first-party WaterX quote-center
+ * (Nautilus-TEE, ed25519), plus `feedWaterxRule`, the collector-feed leg
+ * `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 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
+ * envelope is handed straight to the per-ticker feed leg.
+ *
+ * `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 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
+ * EXACT values the enclave signed over BCS — `collect_batch_latest` rebuilds
+ * the payload on-chain and re-verifies, so they must round-trip byte-for-byte.
+ * They are `bigint` (not `number`): {@link parseSignedEnvelope} decodes them
+ * from the raw JSON integer literals so a value above `Number.MAX_SAFE_INTEGER`
+ * (2^53) can never lose precision and silently abort the on-chain signature
+ * check. `num_sources` is a `u8` (≤ 255) and stays a `number`.
+ */
+export interface WaterxBatchItem {
+    symbol: string;
+    ticker: string;
+    sources: bigint[];
+    method: string;
+    price_timestamp_ms: bigint;
+    price_n: bigint;
+    price_scale: bigint;
+    confidence_n: bigint;
+    confidence_scale: bigint;
+    max_source_deviation_bps: bigint;
+    num_sources: number;
+}
+/** The enclave-signed batch envelope from `GET /v1/quotes/update`. */
+export interface WaterxSignedEnvelope {
+    intent: number;
+    /** Enclave signing timestamp (ms) — the on-chain `timestamp_ms` argument. */
+    timestamp_ms: bigint;
+    payload: {
+        items: WaterxBatchItem[];
+    };
+    /** ed25519 signature over `BCS(IntentMessage<BatchPricePayload>)`, hex (± `0x`). */
+    signature: string;
+}
+/** `waterx_rule`'s narrowed `RuleUpdateData.payload` shape. */
+export interface WaterxUpdatePayload {
+    readonly envelope: WaterxSignedEnvelope;
+}
+/**
+ * Parse a quote-center `/v1/quotes/update` response body into a
+ * {@link WaterxSignedEnvelope} with the u64 fields decoded as `bigint`, exact.
+ *
+ * The signature is over `BCS(IntentMessage<BatchPricePayload>)`, so every u64
+ * the SDK rebuilds in-PTB must equal the enclave's byte-for-byte or
+ * `collect_batch_latest` aborts the whole trade PTB (bad signature — not an
+ * abstain). A plain `JSON.parse` yields IEEE-754 doubles that lose precision
+ * above 2^53, so instead we recover each integer's exact source literal via the
+ * ES2023 reviver `context.source` (Node 21+ / modern browsers) and `BigInt()`
+ * it. On an older runtime that passes no `context`, a value within 2^53 is
+ * still exact (`BigInt(number)`); a value ABOVE it throws loudly here rather
+ * than silently corrupting the payload into an on-chain abort. `num_sources`
+ * (u8) and `intent` are coerced back to `number` — both are tiny.
+ */
+export declare function parseSignedEnvelope(text: string): WaterxSignedEnvelope;
+/** Narrow a `RuleUpdateData` to its `WaterxSignedEnvelope`, or `null`. */
+export declare function waterxEnvelopeOf(data: RuleUpdateData): WaterxSignedEnvelope | null;
+/**
+ * `waterx_rule::collect_batch_latest(collector, config, clock, enclave_config,
+ * enclave, timestamp_ms, payload, sig)` — rebuild the enclave-signed batch
+ * payload in-PTB (`new_batch_payload` + one `new_batch_item`/`push_batch_item`
+ * 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`) 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

@@ -0,0 +1,305 @@
+/**
+ * `WaterxRule` — `PriceUpdateRule` for the first-party WaterX quote-center
+ * (Nautilus-TEE, ed25519), plus `feedWaterxRule`, the collector-feed leg
+ * `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 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
+ * envelope is handed straight to the per-ticker feed leg.
+ *
+ * `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 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 { assertRuleUpdateData, } from "../price-update-rule.js";
+import { FetchPolicyError, fetchWithPolicy, joinEndpointPath, } from "../update-fetch.js";
+/** 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
+ * same-shaped payload from a different rule can never silently pass.
+ */
+function isWaterxUpdatePayloadShape(payload) {
+    const env = payload?.envelope;
+    return (typeof env === "object" &&
+        env !== null &&
+        typeof env.signature === "string" &&
+        typeof env.timestamp_ms === "bigint" &&
+        Array.isArray(env.payload?.items));
+}
+/**
+ * Parse a quote-center `/v1/quotes/update` response body into a
+ * {@link WaterxSignedEnvelope} with the u64 fields decoded as `bigint`, exact.
+ *
+ * The signature is over `BCS(IntentMessage<BatchPricePayload>)`, so every u64
+ * the SDK rebuilds in-PTB must equal the enclave's byte-for-byte or
+ * `collect_batch_latest` aborts the whole trade PTB (bad signature — not an
+ * abstain). A plain `JSON.parse` yields IEEE-754 doubles that lose precision
+ * above 2^53, so instead we recover each integer's exact source literal via the
+ * ES2023 reviver `context.source` (Node 21+ / modern browsers) and `BigInt()`
+ * it. On an older runtime that passes no `context`, a value within 2^53 is
+ * still exact (`BigInt(number)`); a value ABOVE it throws loudly here rather
+ * than silently corrupting the payload into an on-chain abort. `num_sources`
+ * (u8) and `intent` are coerced back to `number` — both are tiny.
+ */
+export function parseSignedEnvelope(text) {
+    const raw = JSON.parse(text, (_key, value, context) => {
+        if (typeof value !== "number" || !Number.isInteger(value))
+            return value;
+        if (context?.source !== undefined)
+            return BigInt(context.source);
+        if (!Number.isSafeInteger(value)) {
+            throw new Error("waterx envelope carries an integer above 2^53 and this runtime lacks JSON " +
+                "source access — cannot preserve u64 precision for the signed payload");
+        }
+        return BigInt(value);
+    });
+    if (typeof raw.signature !== "string" || !Array.isArray(raw.payload?.items)) {
+        throw new Error("WaterX quote-center returned a malformed signed envelope");
+    }
+    return {
+        intent: Number(raw.intent),
+        timestamp_ms: (raw.timestamp_ms ?? 0n),
+        signature: raw.signature,
+        payload: {
+            items: raw.payload.items.map((i) => ({ ...i, num_sources: Number(i.num_sources) })),
+        },
+    };
+}
+/** The `waterx_rule` deployment entry; throws when the config carries none. */
+function requireWaterxPackage(host) {
+    const entry = host.config.packages.waterx_rule;
+    if (!entry) {
+        throw new Error("waterx_rule package is not deployed in this config");
+    }
+    return entry;
+}
+/**
+ * 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) {
+    return {
+        endpoint: host.waterx?.endpoint ?? WATERX_INFRA[host.network].endpoint,
+        fetch: host.waterx?.fetch,
+    };
+}
+/**
+ * Pull one enclave-signed batch envelope covering `symbols` from the
+ * quote-center. Goes through the shared `fetchWithPolicy` (`../update-fetch.ts`)
+ * — same retry/timeout policy as the Pyth/Lazer fetches. No auth: the
+ * quote-center read surface is public.
+ *
+ * The URL is built with `joinEndpointPath`, not `new URL(path, endpoint)`: a
+ * leading-slash path is ABSOLUTE and silently drops the endpoint's own base
+ * path, which is exactly what a `waterxEndpoint` proxy route is (a
+ * `https://app.example/api/quote-center` override would have been rewritten to
+ * `https://app.example/v1/quotes/update`, bypassing the proxy). Same footgun
+ * that 404'd every Pyth Pro feed by dropping its `/hermes` prefix.
+ */
+async function fetchWaterxSignedUpdate(endpoint, symbols, fetchOpts) {
+    const url = joinEndpointPath(endpoint, "v1/quotes/update");
+    url.searchParams.set("symbols", symbols.join(","));
+    let res;
+    try {
+        res = await fetchWithPolicy(url.toString(), { method: "GET" }, { ...fetchOpts });
+    }
+    catch (err) {
+        if (err instanceof FetchPolicyError && err.status !== undefined) {
+            const body = err.bodySnippet ? ` ${err.bodySnippet}` : "";
+            throw new Error(`WaterX quote-center fetch failed: ${err.status}${body} (retries exhausted after ${err.attempts} attempts)`, { cause: err });
+        }
+        throw err;
+    }
+    if (!res.ok) {
+        throw new Error(`WaterX quote-center fetch failed: ${res.status} ${await res.text()}`);
+    }
+    // Parse from raw text (not res.json()) so the u64 fields are decoded exact as
+    // bigint — see parseSignedEnvelope. Malformed-shape check lives there.
+    const envelope = parseSignedEnvelope(await res.text());
+    if (envelope.intent !== BATCH_PRICE_INTENT) {
+        throw new Error(`WaterX quote-center returned intent ${envelope.intent}, expected BATCH_PRICE_INTENT ${BATCH_PRICE_INTENT}`);
+    }
+    return envelope;
+}
+/** Narrow a `RuleUpdateData` to its `WaterxSignedEnvelope`, or `null`. */
+export function waterxEnvelopeOf(data) {
+    const payload = assertRuleUpdateData(data, "waterx_rule", isWaterxUpdatePayloadShape, "{ envelope: { intent, timestamp_ms, payload: { items }, signature } }");
+    return payload?.envelope ?? null;
+}
+/** Strip an optional `0x` prefix, then decode hex → bytes. */
+function decodeSig(hex) {
+    return fromHex(hex.startsWith("0x") ? hex.slice(2) : hex);
+}
+/**
+ * `waterx_rule::collect_batch_latest(collector, config, clock, enclave_config,
+ * enclave, timestamp_ms, payload, sig)` — rebuild the enclave-signed batch
+ * payload in-PTB (`new_batch_payload` + one `new_batch_item`/`push_batch_item`
+ * 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`) 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);
+    const pkg = wr.published_at;
+    const payload = newBatchPayload({ package: pkg })(tx);
+    for (const item of envelope.payload.items) {
+        // u64 fields are already exact bigints (see parseSignedEnvelope) — passed
+        // through verbatim so the rebuilt BCS matches the enclave's signed bytes.
+        const itemArg = newBatchItem({
+            package: pkg,
+            arguments: {
+                symbol: item.symbol,
+                ticker: item.ticker,
+                sources: item.sources,
+                method: item.method,
+                priceTimestampMs: item.price_timestamp_ms,
+                priceN: item.price_n,
+                priceScale: item.price_scale,
+                confidenceN: item.confidence_n,
+                confidenceScale: item.confidence_scale,
+                maxSourceDeviationBps: item.max_source_deviation_bps,
+                numSources: item.num_sources,
+            },
+        })(tx);
+        pushBatchItem({ package: pkg, arguments: { payload, item: itemArg } })(tx);
+    }
+    collectBatchLatest({
+        package: pkg,
+        arguments: {
+            collector,
+            config: tx.object(wr.config),
+            enclaveConfig: tx.object(wr.enclave_config),
+            enclave: tx.object(wr.enclave),
+            timestampMs: envelope.timestamp_ms,
+            payload,
+            sig: Array.from(decodeSig(envelope.signature)),
+        },
+    })(tx);
+}
+export const WaterxRule = {
+    kind: "waterx_rule",
+    // Verification is an in-Move ed25519 check with no Coin argument — no
+    // update fee — see `PriceUpdateRule.requiresFeeSource`.
+    requiresFeeSource: false,
+    /** Tickers with a `waterx_rule.feeds` entry (keyed by oracle ticker). */
+    supportedTickers(host) {
+        return Object.keys(host.config.packages.waterx_rule?.feeds ?? {});
+    },
+    /**
+     * Pulls one enclave-signed batch envelope covering `tickers` from the
+     * quote-center, and only returns it when it actually covers ALL of them.
+     *
+     * A 200 whose `items` omit a requested symbol is a valid, well-signed
+     * envelope — nothing downstream would reject it, and the build would emit a
+     * `collect_batch_latest` that abstains for the missing symbol, surfacing as
+     * an on-chain `EMissingPriceSource` (or a silently thinner weighted set) much
+     * later. Same coverage rule the cached path enforces in
+     * {@link WaterxRule.narrowUpdateData}; the difference is disposition — a
+     * cache miss falls back to this live fetch, whereas the live source itself
+     * coming up short has no fallback left, so it throws deterministically here.
+     */
+    async fetchUpdateData(host, tickers) {
+        if (tickers.length === 0)
+            return null;
+        // Package-level check first: a config without the deployment must say so,
+        // not fail per ticker as if only that feed were missing.
+        const { feeds } = requireWaterxPackage(host);
+        for (const ticker of tickers) {
+            if (feeds[ticker] === undefined) {
+                throw new Error(`No waterx_rule feed listed for ticker: ${ticker}`);
+            }
+        }
+        const { endpoint, fetch: fetchOpts } = resolveWaterxInfra(host);
+        const envelope = await fetchWaterxSignedUpdate(endpoint, tickers, fetchOpts);
+        const covered = new Set(envelope.payload.items.map((i) => i.symbol));
+        const missing = tickers.filter((t) => !covered.has(t));
+        if (missing.length > 0) {
+            throw new Error(`WaterX quote-center envelope does not cover ticker(s): ${missing.join(", ")} ` +
+                `(requested ${tickers.join(", ")}; served ${[...covered].join(", ") || "none"})`);
+        }
+        return { kind: "waterx_rule", payload: { envelope } };
+    },
+    /**
+     * One signed batch envelope carries a single ed25519 signature over its whole
+     * `payload` — it is indivisible: it can only be served whole (re-verified from
+     * the full item set). Returns the whole payload iff every requested ticker's
+     * item is present in THIS envelope; any coverage gap → `null` (miss), never a
+     * silent partial.
+     */
+    narrowUpdateData(_host, data, tickers) {
+        const envelope = waterxEnvelopeOf(data);
+        if (!envelope || tickers.length === 0)
+            return null;
+        const covered = new Set(envelope.payload.items.map((i) => i.symbol));
+        for (const ticker of tickers) {
+            if (!covered.has(ticker))
+                return null;
+        }
+        return { kind: "waterx_rule", payload: { envelope } };
+    },
+    /**
+     * No shared verify step: `waterx_rule::collect_batch_latest` bundles verify
+     * AND feed into one per-collector call, appended by {@link feedWaterxRule} in
+     * the per-ticker aggregate leg. So this emits nothing and returns `void` — the
+     * signed envelope reaches the feed leg via `aggregate.ts`'s per-ticker map
+     * (built from the group's fetched data), not a `RuleUpdateHandle`.
+     */
+    buildUpdateCalls(_tx, _host, _data, _opts) {
+        return;
+    },
+};

package/dist/src/perp/client.d.ts

@@ -12,27 +12,49 @@
  */
 import { BaseLineClient } from "../base-client.ts";
 import type { OracleSource } from "../oracle/price-update-rule.ts";
-import { type LoadConfigOptions, type PythFetchPolicy, type PythInfraConfig, type WaterXConfig, type WormholeInfraConfig } from "./config.ts";
+import type { FetchPolicy } from "../oracle/update-fetch.ts";
+import { type LoadConfigOptions, type PythAccessConfig, type PythFetchPolicy, type WaterxAccessConfig, type WaterXConfig, type WormholeInfraConfig } from "./config.ts";
 import type { Network } from "./constants.ts";
 export interface CreateClientOptions extends LoadConfigOptions {
     grpcUrl?: string;
     /**
-     * Which oracle price-update source drives `refreshOraclePrices`. Each source
-     * is self-contained (own infra + config) with NO cross-source fallback:
+     * Which oracle price-update source drives `refreshOraclePrices`. REQUIRED —
+     * there is NO default source: every deployment names its source explicitly
+     * (wire it from your own env var, e.g. `ORACLE_SOURCE`). Each source is
+     * self-contained (own infra, own endpoints, own config) with NO cross-source
+     * fallback:
      *
-     * - `'pyth_rule'` (default) — Pyth Core `pyth_rule` updates (Hermes VAA +
-     *   per-feed update fees), Core state + keyless Core Hermes.
+     * - `'pyth_rule'` — Pyth Core `pyth_rule` updates (Hermes VAA + per-feed
+     *   update fees); Core state + Hermes endpoint live in the source's own
+     *   `PYTH_CORE_INFRA` table.
      * - `'pyth_lazer_rule'` — Pyth Lazer signed updates (ONE `leEcdsa` verify
      *   per PTB, no per-feed fees); needs `packages.pyth_lazer_rule` with feeds
-     *   and a `pythApiKey` (Lazer is auth-first).
+     *   and a `pythApiKey` (Lazer is auth-first); Lazer infra lives in the
+     *   source's own `LAZER_INFRA` table.
+     * - `'waterx_rule'` — the first-party WaterX quote-center (Nautilus-TEE,
+     *   ed25519-signed batches): ONE envelope covering the build's tickers,
+     *   verified AND fed by a single `collect_batch_latest` per collector. No
+     *   credential and no per-update fee; needs `packages.waterx_rule` with
+     *   feeds. Quote-center infra lives in the source's own `WATERX_INFRA`
+     *   table; endpoint/transport overridable via
+     *   {@link CreateClientOptions.waterxEndpoint} /
+     *   {@link CreateClientOptions.waterxFetch} — the browser-CORS proxy hook,
+     *   since this is the one source fetched from the page.
      *
-     * A source-neutral name on purpose — a future source need not be Pyth.
-     * Selecting a source whose feed for a requested ticker is absent is NOT an
-     * error at client creation: it fails at tx-build time for exactly those
-     * tickers (see `refreshOraclePrices`). The Pyth Core infra is fixed per
-     * network by `PYTH_DEFAULTS` and is not deployment-overridable.
+     * The name is source-neutral on purpose — a source need not be Pyth (as
+     * `'waterx_rule'` shows). Selecting a source whose feed for a requested
+     * ticker is absent is NOT an error at client creation: it fails at tx-build
+     * time for exactly those tickers (see `refreshOraclePrices`).
+     *
+     * Accepts a SINGLE source or a LIST. A list means every listed source's
+     * data is fetched and fed in one build — required whenever the on-chain
+     * weight tables have more than one rule weighted (e.g. a Core→Pro or
+     * Pro+Waterx coexistence window): the chain drops unweighted contributions
+     * (harmless) but aborts on a starved weighted rule, so the list must stay a
+     * SUPERSET of every ticker's weighted set. Order is meaningful to consumers
+     * (read-plane priority), not to the on-chain build.
      */
-    oracleSource?: OracleSource;
+    oracleSource: OracleSource | OracleSource[];
     /**
      * Pyth Lazer access token (`Authorization: Bearer …`). Required under
      * `oracleSource: 'pyth_lazer_rule'` (Lazer is auth-first) and unused by
@@ -46,17 +68,46 @@ export interface CreateClientOptions extends LoadConfigOptions {
      * `fetchWithPolicy`). Optional — defaults to 15s timeout, 2 retries.
      */
     pythFetch?: PythFetchPolicy;
+    /**
+     * Quote-center base URL for `oracleSource: 'waterx_rule'` — overrides the
+     * source's own per-network `WATERX_INFRA` default.
+     *
+     * This is the one source a BROWSER fetches itself (the signed envelope is
+     * pulled from the page), so it is bound by the quote-center deployment's CORS
+     * allowlist. A front end whose origin is not allowed — or one that must route
+     * egress through its own backend — points this at a same-origin proxy that
+     * forwards `GET /v1/quotes/update`. Unused by the Pyth sources.
+     *
+     * An absolute URL. Any base PATH is preserved (`joinEndpointPath`), so
+     * `https://app.example/api/quote-center` fetches
+     * `https://app.example/api/quote-center/v1/quotes/update` — a proxy route
+     * survives instead of being rewritten to the origin root.
+     */
+    waterxEndpoint?: string;
+    /**
+     * Retry/timeout policy — and `fetchImpl` — for the quote-center fetch (see
+     * `fetchWithPolicy`). Optional: falls back to the built-in defaults — never
+     * to `pythFetch` (sources stay independent). Supply `fetchImpl` to route the request through your own
+     * transport (a proxying `fetch` wrapper, a non-global `fetch`, a test double).
+     */
+    waterxFetch?: FetchPolicy;
 }
 export declare class PerpClient extends BaseLineClient<WaterXConfig> {
-    /** Pyth Core infra (fixed per network) plus the caller-supplied credential/policy. */
-    pyth: PythInfraConfig;
+    /** Caller-supplied Pyth credential + fetch policy — NO infra; each source owns its own tables. */
+    pyth: PythAccessConfig;
+    /**
+     * Caller-supplied quote-center overrides for `oracleSource: 'waterx_rule'`
+     * (`waterxEndpoint` / `waterxFetch` create options) — access-only, mirroring
+     * `pyth` above; unset fields resolve against the rule's own `WATERX_INFRA`.
+     */
+    waterx: WaterxAccessConfig;
     /** Wormhole infra for the credit bridge (network defaults unless overridden). */
     wormhole: WormholeInfraConfig;
-    /** Selected oracle price-update source (`oracleSource` create option; default `'pyth_rule'`). */
-    readonly oracleSource: OracleSource;
+    /** The fed set: `oracleSource` create option normalized to a non-empty, deduped list. */
+    readonly oracleSources: readonly OracleSource[];
     /** Canonical-schema lookups (delegated to below); no transport. */
     private readonly view;
-    constructor(network: Network, config: WaterXConfig, opts?: CreateClientOptions);
+    constructor(network: Network, config: WaterXConfig, opts: CreateClientOptions);
     /**
      * Async factory: fetches the deployment config for `network` and returns
      * a ready-to-use client. Pass `opts.cache=true` to memoize the JSON.
@@ -65,9 +116,9 @@ export declare class PerpClient extends BaseLineClient<WaterXConfig> {
      * not an error at init — it surfaces at tx-build time for the specific
      * tickers that source can't serve (see `refreshOraclePrices`).
      */
-    static create(network: Network, opts?: CreateClientOptions): Promise<PerpClient>;
-    static mainnet(opts?: CreateClientOptions): Promise<PerpClient>;
-    static testnet(opts?: CreateClientOptions): Promise<PerpClient>;
+    static create(network: Network, opts: CreateClientOptions): Promise<PerpClient>;
+    static mainnet(opts: CreateClientOptions): Promise<PerpClient>;
+    static testnet(opts: CreateClientOptions): Promise<PerpClient>;
     /** @see PerpConfigView.getMarket */
     getMarket(ticker: string): import("./config.ts").WaterxPerpMarketEntry;
     /** @see PerpConfigView.getAggregator */

package/dist/src/perp/client.js

@@ -12,29 +12,51 @@
  */
 import { BaseLineClient } from "../base-client.js";
 import { PerpConfigView } from "./config-view.js";
-import { loadConfig, PYTH_DEFAULTS, WORMHOLE_DEFAULTS, } from "./config.js";
+import { loadConfig, WORMHOLE_DEFAULTS, } from "./config.js";
 export class PerpClient extends BaseLineClient {
-    /** Pyth Core infra (fixed per network) plus the caller-supplied credential/policy. */
+    /** Caller-supplied Pyth credential + fetch policy — NO infra; each source owns its own tables. */
     pyth;
+    /**
+     * Caller-supplied quote-center overrides for `oracleSource: 'waterx_rule'`
+     * (`waterxEndpoint` / `waterxFetch` create options) — access-only, mirroring
+     * `pyth` above; unset fields resolve against the rule's own `WATERX_INFRA`.
+     */
+    waterx;
     /** Wormhole infra for the credit bridge (network defaults unless overridden). */
     wormhole;
-    /** Selected oracle price-update source (`oracleSource` create option; default `'pyth_rule'`). */
-    oracleSource;
+    /** The fed set: `oracleSource` create option normalized to a non-empty, deduped list. */
+    oracleSources;
     /** Canonical-schema lookups (delegated to below); no transport. */
     view;
-    constructor(network, config, opts = {}) {
+    constructor(network, config, opts) {
         super(network, config, opts);
-        // Pyth Core infra is fixed per network — NOT deployment-overridable and
-        // NOT source-dependent (the pyth_lazer_rule source reads only api_key/fetch
-        // from here). The api_key + fetch policy are caller-supplied at init: a
-        // secret has no place in the canonical waterx-config JSON.
+        // Access-only slice: the api_key + fetch policy are caller-supplied at
+        // init (a secret has no place in the canonical waterx-config JSON). All
+        // endpoint/object-id infra is per-source, owned by the rule modules —
+        // nothing infra-shaped lives on the client.
         this.pyth = {
-            ...PYTH_DEFAULTS[network],
             ...(opts.pythApiKey !== undefined ? { api_key: opts.pythApiKey } : {}),
             ...(opts.pythFetch !== undefined ? { fetch: opts.pythFetch } : {}),
         };
         this.wormhole = config.wormhole ?? WORMHOLE_DEFAULTS[network];
-        this.oracleSource = opts.oracleSource ?? "pyth_rule";
+        // Quote-center access slice: overrides only — a browser blocked by the
+        // quote-center's CORS allowlist swaps `endpoint` for a same-origin proxy;
+        // unset fields resolve inside the rule against WATERX_INFRA[network].
+        this.waterx = {
+            ...(opts.waterxEndpoint !== undefined ? { endpoint: opts.waterxEndpoint } : {}),
+            ...(opts.waterxFetch !== undefined ? { fetch: opts.waterxFetch } : {}),
+        };
+        // Normalize single-or-list to a deduped, order-preserving list. An empty
+        // list — or a nullish/empty entry, the shape an untyped caller produces
+        // by omitting the REQUIRED option — is a caller bug, not "no oracle":
+        // fail construction loudly instead of booting green and surfacing as
+        // `OracleSourceNotImplemented: undefined` at the first tx-build.
+        const sources = Array.isArray(opts.oracleSource) ? opts.oracleSource : [opts.oracleSource];
+        this.oracleSources = [...new Set(sources)];
+        if (this.oracleSources.length === 0 ||
+            this.oracleSources.some((source) => typeof source !== "string" || source.length === 0)) {
+            throw new Error(`oracleSource is REQUIRED and must name at least one source (got ${JSON.stringify(sources)})`);
+        }
         this.view = new PerpConfigView(() => this.config, () => this.wormhole);
     }
     /**
@@ -45,14 +67,14 @@ export class PerpClient extends BaseLineClient {
      * not an error at init — it surfaces at tx-build time for the specific
      * tickers that source can't serve (see `refreshOraclePrices`).
      */
-    static async create(network, opts = {}) {
+    static async create(network, opts) {
         const config = await loadConfig(network, opts);
         return new PerpClient(network, config, opts);
     }
-    static mainnet(opts = {}) {
+    static mainnet(opts) {
         return PerpClient.create("MAINNET", opts);
     }
-    static testnet(opts = {}) {
+    static testnet(opts) {
         return PerpClient.create("TESTNET", opts);
     }
     // ========================================================