@waterx/sdk 4.3.2 → 5.0.0

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

@@ -0,0 +1,185 @@
+"use strict";
+/**
+ * `validate.ts` — boot-time oracle-deployment asserts consumers (FE/BE) fold
+ * onto instead of each hand-rolling them:
+ *
+ * - {@link assertOracleWriteCoverage} — the "this fed set can actually price
+ *   the tickers I care about" guard. Because every source reads through its
+ *   own feeds namespace, write set == read set — passing this ALSO validates
+ *   the read plane (there is deliberately no separate read-coverage assert).
+ * - {@link missingOracleCredentials} — the env-shaped credential audit: which
+ *   listed sources cannot run with the credentials this deployment supplied.
+ *   Boot-time mirror of `refreshOraclePrices`'s own per-build credential
+ *   pre-check (`aggregate.ts`), keyed off the same rule-owned
+ *   `credential` declaration so the two can never disagree.
+ *
+ * Deliberately NOT called by `PerpClient` itself: client creation stays
+ * guard-free (a source with absent feeds surfaces at tx-build for exactly the
+ * tickers it can't serve). These are for consumers whose deployment policy is
+ * "fail the BOOT, not the first trade".
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OracleTickerUnservedError = void 0;
+exports.assertOracleWriteCoverage = assertOracleWriteCoverage;
+exports.partitionServableTickers = partitionServableTickers;
+exports.servableTickers = servableTickers;
+exports.missingOracleCredentials = missingOracleCredentials;
+const price_update_rule_ts_1 = require("./price-update-rule.js");
+const rule_registry_ts_1 = require("./rule-registry.js");
+/**
+ * A build depends on a ticker this client's fed set cannot price.
+ *
+ * Raised from two places, deliberately the same type: the per-BUILD composers
+ * (`refreshOraclePrices` skipped the ticker by design — see
+ * `OracleRefreshSummary` — and the composer decided it was load-bearing for
+ * the action) and the boot-time {@link assertOracleWriteCoverage}. One error
+ * for one question: "this fed set cannot price these tickers".
+ */
+class OracleTickerUnservedError extends Error {
+    tickers;
+    sources;
+    constructor(tickers, sources, why) {
+        super(`fed set [${sources.join(", ")}] has no feed for ticker(s): ${tickers.join(", ")}. ` +
+            (why ?? "This build depends on their prices, so it cannot proceed. ") +
+            "Add feeds under a listed source, list a source that serves them, or pass " +
+            "allowUnrefreshedPrices: true to build anyway against whatever price the " +
+            "chain already holds.");
+        this.name = "OracleTickerUnservedError";
+        this.tickers = tickers;
+        this.sources = sources;
+    }
+}
+exports.OracleTickerUnservedError = OracleTickerUnservedError;
+/**
+ * Assert this deployment's fed set can price every ticker in `tickers`.
+ *
+ * Throws {@link OracleTickerUnservedError} naming ALL the unservable ones (not
+ * just the first — an operator fixing a config wants the whole list).
+ *
+ * This is the boot-time twin of the per-build behaviour, and it guards the gap
+ * that per-build handling deliberately leaves open: `refreshOraclePrices`
+ * SKIPS a ticker no source serves, and only a composer that happens to depend
+ * on that ticker turns the skip into an error. A market nobody trades today
+ * would therefore stay silently unpriceable until someone did. Pass the ticker
+ * set your deployment cares about (typically every market) and find out at
+ * boot instead.
+ *
+ * It does NOT check "every listed source has feeds" any more: the fed set is
+ * derived from exactly that condition (see `deriveOracleSources`), so that
+ * assert became unreachable for any real client — it could only fire for a
+ * config mutated after construction, which is a test fixture, not a
+ * deployment. Write set == read set by construction (each source reads its own
+ * feeds), so this single assert still covers both planes.
+ */
+function assertOracleWriteCoverage(host, tickers) {
+    const { unservable } = partitionServableTickers(host, tickers);
+    if (unservable.length > 0) {
+        throw new OracleTickerUnservedError(unservable, host.oracleSources);
+    }
+}
+/** Tickers the client's LISTED sources carry a feed for. */
+function fedSetTickers(host) {
+    return new Set(host.oracleSources.flatMap((source) => (0, rule_registry_ts_1.resolveOracleRule)(source).supportedTickers(host)));
+}
+/**
+ * Tickers ANY rule in this config carries a feed for — listed or not.
+ *
+ * The fed set answers "can THIS client price it"; this answers "does the chain
+ * plausibly weight a price-update rule for it", which is what decides whether
+ * a constant leg alone is the whole picture. `supra_rule` counts (it is a
+ * weighted leg even though it is not an `OracleSource`) but only when it is
+ * actually wired — an unwired block's feeds map is documented as
+ * informational, and honouring a stale one would strand constant-only tickers
+ * for no benefit.
+ */
+function tickersWithAnySourceFeed(host) {
+    const out = new Set();
+    for (const source of price_update_rule_ts_1.ORACLE_SOURCES) {
+        // Skip a source the deployment DISABLED — routing already honours
+        // `enabled: false` (`deriveOracleSources`), and applying it in one place
+        // but not the other meant a disabled block's informational feeds
+        // disqualified a constant-only ticker that nothing would ever feed. The
+        // predicate has to match what actually gets emitted.
+        if (host.config.packages[source]?.enabled === false)
+            continue;
+        for (const ticker of (0, rule_registry_ts_1.resolveOracleRule)(source).supportedTickers(host))
+            out.add(ticker);
+    }
+    // `getSupraRule()` already requires `enabled` — see `config-view.ts`.
+    if (host.getSupraRule() !== undefined) {
+        for (const ticker of Object.keys(host.config.packages.supra_rule?.feeds ?? {}))
+            out.add(ticker);
+    }
+    return out;
+}
+/**
+ * THE acceptance predicate, in partition form — the single definition of
+ * "will `refreshOraclePrices` put a price on chain for this ticker".
+ *
+ * A ticker is servable when some LISTED source's feeds carry it, or when it is
+ * CONSTANT-ONLY: `constant_rule` pins it and no other rule in the config feeds
+ * it. The stricter constant test matters — a constant-pinned ticker that some
+ * other rule also feeds gets aggregated from a constant-only collector, and if
+ * the chain weights that other rule the aggregate aborts `EMissingPriceSource`.
+ * (`aggregateTicker` only appends a supra leg when a price-update source
+ * already fed the collector, so a constant-only collector can never carry one.)
+ *
+ * `covered` lets a caller that has ALREADY resolved which of its tickers its
+ * fed set serves — `refreshOraclePrices`, off its rule groups — pass that in
+ * rather than have it recomputed. Both callers therefore share one rule, which
+ * is the point: a consumer pre-filtering with {@link servableTickers} cannot
+ * hand the build a ticker it will silently skip.
+ *
+ * Order-preserving. The `anyFeed` set is built at most once per call, and only
+ * when a constant-pinned ticker actually needs it.
+ */
+function partitionServableTickers(host, tickers, covered) {
+    const fed = covered ?? fedSetTickers(host);
+    const servable = [];
+    const unservable = [];
+    let anyFeed;
+    for (const ticker of tickers) {
+        if (fed.has(ticker)) {
+            servable.push(ticker);
+        }
+        else if (host.isConstantTicker(ticker)) {
+            anyFeed ??= tickersWithAnySourceFeed(host);
+            (anyFeed.has(ticker) ? unservable : servable).push(ticker);
+        }
+        else {
+            unservable.push(ticker);
+        }
+    }
+    return { servable, unservable };
+}
+/**
+ * The subset of `tickers` this deployment's fed set can actually price — the
+ * servable half of {@link partitionServableTickers}, which is literally the
+ * rule `refreshOraclePrices` applies.
+ */
+function servableTickers(host, tickers) {
+    return partitionServableTickers(host, tickers).servable;
+}
+/**
+ * Which of `sources` cannot run with the supplied credentials — one row per
+ * (source, missing credential). Empty array ⇒ the fed set is fully
+ * credentialed. Pure and env-shaped on purpose: consumers call it from their
+ * boot-time env asserts (zod superRefine, config validators) BEFORE any
+ * client exists, passing the raw values their env resolved. The per-build
+ * enforcement twin — `refreshOraclePrices`'s credential pre-check — reads the
+ * same rule-owned `credential` declaration, so a deployment this function passes
+ * cannot later trip that check for a listed source.
+ */
+function missingOracleCredentials(sources, creds) {
+    // The env-shaped bag, normalized to the kind-keyed shape ONCE — the check
+    // below then never mentions a specific kind.
+    const supplied = { pyth_api_key: creds.pythApiKey };
+    const missing = [];
+    for (const source of sources) {
+        const required = (0, rule_registry_ts_1.resolveOracleRule)(source).credential?.kind;
+        if (required !== undefined && !supplied[required]) {
+            missing.push({ source, credential: required });
+        }
+    }
+    return missing;
+}

package/dist/cjs/src/oracle/weight-coverage.d.ts

@@ -0,0 +1,79 @@
+/**
+ * `weight-coverage.ts` — the ON-CHAIN half of "can this deployment price these
+ * tickers", and the only place the fed-set invariant is actually enforced.
+ *
+ * Everything in `validate.ts` reasons from config alone: it answers "does some
+ * listed source carry a feed for this ticker". That is necessary and not
+ * sufficient, because the aggregator decides which contributions COUNT. The
+ * dangerous shape is a ticker that is servable by config yet weighted to a rule
+ * the fed set cannot supply: `refreshOraclePrices` happily aggregates it from a
+ * source the chain does not weight, `remove_outliers` finds no weighted
+ * contribution, and the abort takes down the WHOLE PTB — every other ticker in
+ * the same build with it.
+ *
+ * The mirror-image shape is just as dangerous and less obvious: a ticker
+ * weighted to a rule this client DOES list, but whose feed that source does not
+ * carry. Being in the fed set buys nothing per ticker — `refreshOraclePrices`
+ * groups a ticker under a source only when that source's feeds have it — so the
+ * leg never appears and the weighted rule is starved just the same.
+ *
+ * That is live on mainnet today, not hypothetical. `XAGUSD` / `WTIUSD` /
+ * `BRENTUSD` are in `waterx_rule.feeds` (so: servable) while their aggregators
+ * still weight the retired `PythRule@1`, which 5.0.0 cannot feed at all. The
+ * config-only asserts wave all three through; only reading the weights catches
+ * them.
+ *
+ * Async and chain-reading, so it is NOT on the build path — it belongs in a
+ * deployment's boot sequence or a pre-release check, next to
+ * `assertOracleWriteCoverage`.
+ */
+import type { OracleHost } from "./host.ts";
+/**
+ * Auxiliary witnesses — fed alongside a source rather than being one.
+ *
+ * Their emission is CONDITIONAL, per ticker, so they cannot be treated as
+ * globally available (which certified a ticker clean that then aborted):
+ *
+ * - `ConstantRule` rides only when `host.isConstantTicker(ticker)`.
+ * - `SupraRule` rides only when the deployment has supra wired AND a price
+ *   -update source already fed that collector — `aggregateTicker` puts the
+ *   supra leg inside `if (fed)`, so a ticker no listed source serves never
+ *   gets one, constant-only tickers included.
+ */
+/** One ticker's on-chain weighting, as far as fed-set coverage is concerned. */
+export interface TickerWeightCoverage {
+    ticker: string;
+    /** Weighted rule witness names, as the aggregator holds them. */
+    weighted: string[];
+    /** Weighted rules this client's fed set cannot feed (retired, or unlisted). */
+    unsuppliable: string[];
+}
+/** Raised by {@link assertOracleWeightCoverage}; `rows` names every offender. */
+export declare class OracleWeightCoverageError extends Error {
+    readonly rows: TickerWeightCoverage[];
+    constructor(rows: TickerWeightCoverage[]);
+}
+/** Raised when an aggregator object cannot be decoded — see `readOracleWeightCoverage`. */
+export declare class OracleWeightUnreadableError extends Error {
+    readonly ticker: string;
+    constructor(ticker: string, aggregatorId: string, why: string);
+}
+/**
+ * Read each ticker's aggregator and report which weighted rules this fed set
+ * cannot supply.
+ *
+ * Tickers with no aggregator entry in the config are skipped, not failed: an
+ * unlisted aggregator means the deployment does not price that ticker on chain
+ * at all, which {@link assertOracleWriteCoverage} is the right check for.
+ */
+export declare function readOracleWeightCoverage(host: OracleHost, tickers: readonly string[]): Promise<TickerWeightCoverage[]>;
+/**
+ * Throw {@link OracleWeightCoverageError} when any of `tickers` is weighted to
+ * a rule this fed set cannot feed.
+ *
+ * The chain-reading twin of `assertOracleWriteCoverage`: that one catches a
+ * ticker NO source serves (loud at build anyway), this one catches the quieter
+ * and more damaging case — a ticker every config check passes, which aborts the
+ * entire transaction on chain.
+ */
+export declare function assertOracleWeightCoverage(host: OracleHost, tickers: readonly string[]): Promise<void>;

package/dist/cjs/src/oracle/weight-coverage.js

@@ -0,0 +1,173 @@
+"use strict";
+/**
+ * `weight-coverage.ts` — the ON-CHAIN half of "can this deployment price these
+ * tickers", and the only place the fed-set invariant is actually enforced.
+ *
+ * Everything in `validate.ts` reasons from config alone: it answers "does some
+ * listed source carry a feed for this ticker". That is necessary and not
+ * sufficient, because the aggregator decides which contributions COUNT. The
+ * dangerous shape is a ticker that is servable by config yet weighted to a rule
+ * the fed set cannot supply: `refreshOraclePrices` happily aggregates it from a
+ * source the chain does not weight, `remove_outliers` finds no weighted
+ * contribution, and the abort takes down the WHOLE PTB — every other ticker in
+ * the same build with it.
+ *
+ * The mirror-image shape is just as dangerous and less obvious: a ticker
+ * weighted to a rule this client DOES list, but whose feed that source does not
+ * carry. Being in the fed set buys nothing per ticker — `refreshOraclePrices`
+ * groups a ticker under a source only when that source's feeds have it — so the
+ * leg never appears and the weighted rule is starved just the same.
+ *
+ * That is live on mainnet today, not hypothetical. `XAGUSD` / `WTIUSD` /
+ * `BRENTUSD` are in `waterx_rule.feeds` (so: servable) while their aggregators
+ * still weight the retired `PythRule@1`, which 5.0.0 cannot feed at all. The
+ * config-only asserts wave all three through; only reading the weights catches
+ * them.
+ *
+ * Async and chain-reading, so it is NOT on the build path — it belongs in a
+ * deployment's boot sequence or a pre-release check, next to
+ * `assertOracleWriteCoverage`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OracleWeightUnreadableError = exports.OracleWeightCoverageError = void 0;
+exports.readOracleWeightCoverage = readOracleWeightCoverage;
+exports.assertOracleWeightCoverage = assertOracleWeightCoverage;
+const rule_registry_ts_1 = require("./rule-registry.js");
+/**
+ * The on-chain witness struct each SDK source feeds. The aggregator's weight
+ * table is keyed by these type names, so this is the join between what the
+ * chain requires and what the fed set can supply.
+ *
+ * `ConstantRule` and `SupraRule` are auxiliary legs rather than sources — the
+ * SDK feeds them alongside whichever source ran, so a ticker weighted only to
+ * them needs no source. Anything NOT in this map (notably the retired
+ * `PythRule`) cannot be supplied by this SDK at any fed set.
+ */
+const WITNESS_TO_SOURCE = Object.freeze({
+    PythLazerRule: "pyth_lazer_rule",
+    WaterxRule: "waterx_rule",
+});
+/** Raised by {@link assertOracleWeightCoverage}; `rows` names every offender. */
+class OracleWeightCoverageError extends Error {
+    rows;
+    constructor(rows) {
+        const detail = rows.map((r) => `${r.ticker} weights ${r.unsuppliable.join(" + ")}`).join("; ");
+        super(`on-chain aggregator weights name rule(s) this fed set cannot supply: ${detail}. ` +
+            `Aggregating such a ticker emits a collector with no WEIGHTED contribution, so ` +
+            `remove_outliers aborts EMissingPriceSource and takes the whole PTB down — every ` +
+            `other ticker in the same build with it. Fix by migrating the on-chain weight to a ` +
+            `rule this deployment feeds, or by not requesting these tickers.`);
+        this.name = "OracleWeightCoverageError";
+        this.rows = rows;
+    }
+}
+exports.OracleWeightCoverageError = OracleWeightCoverageError;
+/** Raised when an aggregator object cannot be decoded — see `readOracleWeightCoverage`. */
+class OracleWeightUnreadableError extends Error {
+    ticker;
+    constructor(ticker, aggregatorId, why) {
+        super(`cannot read aggregator ${aggregatorId} for ${ticker}: ${why}. This check exists to fail ` +
+            `CLOSED, so an undecodable weight table is an error rather than an empty one — treating ` +
+            `it as "no weights" would certify every ticker clean without verifying anything.`);
+        this.name = "OracleWeightUnreadableError";
+        this.ticker = ticker;
+    }
+}
+exports.OracleWeightUnreadableError = OracleWeightUnreadableError;
+/** `0x…::aggregator::PythRule` → `PythRule`; already-short names pass through. */
+function witnessName(raw) {
+    const s = typeof raw === "string" ? raw : String(raw?.name ?? raw);
+    return s.split("::").pop() ?? s;
+}
+/**
+ * Read each ticker's aggregator and report which weighted rules this fed set
+ * cannot supply.
+ *
+ * Tickers with no aggregator entry in the config are skipped, not failed: an
+ * unlisted aggregator means the deployment does not price that ticker on chain
+ * at all, which {@link assertOracleWriteCoverage} is the right check for.
+ */
+async function readOracleWeightCoverage(host, tickers) {
+    const aggregators = host.config.packages.waterx_oracle.aggregators;
+    // Which tickers each LISTED source actually feeds — per source, not merged.
+    //
+    // Being in the fed set is not enough: `refreshOraclePrices` groups a ticker
+    // under a source only when that source's feeds carry it, so a lazer-weighted
+    // ticker that only WaterX feeds gets no lazer leg no matter that lazer is
+    // listed. Treating a listed source as suppliable for EVERY ticker passed
+    // exactly that case, which then aborts `EMissingPriceSource` on chain.
+    const feedsByWitness = new Map();
+    for (const [witness, source] of Object.entries(WITNESS_TO_SOURCE)) {
+        if (host.oracleSources.includes(source)) {
+            feedsByWitness.set(witness, new Set((0, rule_registry_ts_1.resolveOracleRule)(source).supportedTickers(host)));
+        }
+    }
+    const supraWired = host.getSupraRule() !== undefined;
+    /** Some listed source feeds this ticker, so a collector gets fed at all. */
+    const anySourceFeeds = (ticker) => {
+        for (const served of feedsByWitness.values())
+            if (served.has(ticker))
+                return true;
+        return false;
+    };
+    const suppliableFor = (ticker, witness) => {
+        const served = feedsByWitness.get(witness);
+        // A source witness: suppliable only where that source has THIS ticker's feed.
+        if (served !== undefined)
+            return served.has(ticker);
+        if (witness === "ConstantRule")
+            return host.isConstantTicker(ticker);
+        // Supra rides on a collector a SOURCE already fed — never on its own, and
+        // never on a constant-only collector.
+        if (witness === "SupraRule")
+            return supraWired && anySourceFeeds(ticker);
+        return false;
+    };
+    const wanted = tickers.filter((t) => Object.hasOwn(aggregators, t));
+    // Independent reads — one round trip each would make a 30-market boot assert
+    // needlessly serial.
+    const objects = await Promise.all(wanted.map((t) => 
+    // Explicit field mask: the client's `getObject` wrapper requests none, so
+    // `json` would come back undefined and every aggregator would look
+    // weightless — an assert that passes exactly where it must fail.
+    host.grpcClient.getObject({ objectId: aggregators[t], include: { json: true } })));
+    return wanted.map((ticker, i) => {
+        // FAIL CLOSED on anything undecodable. Defaulting a missing object / JSON /
+        // weights map to an empty list made the assert succeed without verifying a
+        // single weight — the exact fail-open shape this gate exists to prevent.
+        const id = aggregators[ticker];
+        const json = objects[i]?.object?.json;
+        if (json === undefined || json === null || typeof json !== "object") {
+            throw new OracleWeightUnreadableError(ticker, id, "no JSON payload in the object read");
+        }
+        const raw = json.weights;
+        const entries = Array.isArray(raw) ? raw : raw?.contents;
+        if (!Array.isArray(entries)) {
+            throw new OracleWeightUnreadableError(ticker, id, "no decodable `weights` table");
+        }
+        const weighted = entries.map((e) => witnessName(e.key));
+        if (weighted.some((w) => w === "" || w === "undefined")) {
+            throw new OracleWeightUnreadableError(ticker, id, "a weight entry has no rule type name");
+        }
+        return {
+            ticker,
+            weighted,
+            unsuppliable: weighted.filter((w) => !suppliableFor(ticker, w)),
+        };
+    });
+}
+/**
+ * Throw {@link OracleWeightCoverageError} when any of `tickers` is weighted to
+ * a rule this fed set cannot feed.
+ *
+ * The chain-reading twin of `assertOracleWriteCoverage`: that one catches a
+ * ticker NO source serves (loud at build anyway), this one catches the quieter
+ * and more damaging case — a ticker every config check passes, which aborts the
+ * entire transaction on chain.
+ */
+async function assertOracleWeightCoverage(host, tickers) {
+    const rows = await readOracleWeightCoverage(host, tickers);
+    const bad = rows.filter((r) => r.unsuppliable.length > 0);
+    if (bad.length > 0)
+        throw new OracleWeightCoverageError(bad);
+}

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

@@ -17,70 +17,33 @@ import { type LoadConfigOptions, type PythAccessConfig, type PythFetchPolicy, ty
 import type { Network } from "./constants.ts";
 export interface CreateClientOptions extends LoadConfigOptions {
     grpcUrl?: string;
-    /**
-     * 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'` — 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); 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.
-     *
-     * 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[];
     /**
      * Pyth Lazer access token (`Authorization: Bearer …`). Required under
-     * `oracleSource: 'pyth_lazer_rule'` (Lazer is auth-first) and unused by
-     * `'pyth_rule'` (keyless Core Hermes). This is a SECRET and never belongs in
-     * the canonical `waterx-config` JSON — pass it at client init from your own
-     * env var (e.g. `PYTH_API_KEY`); the SDK never reads `process.env`.
+     * a config that wires `pyth_lazer_rule` (Lazer is auth-first) and unused by
+     * `waterx_rule` (public quote-center). This is a SECRET and never belongs
+     * in the canonical `waterx-config` JSON — pass it at client init from your
+     * own env var (e.g. `PYTH_API_KEY`); the SDK never reads `process.env`.
      */
     pythApiKey?: string;
     /**
-     * Retry/timeout policy for the off-chain Hermes / Lazer update fetches (see
+     * Retry/timeout policy for the off-chain Lazer update fetch (see
      * `fetchWithPolicy`). Optional — defaults to 15s timeout, 2 retries.
      */
     pythFetch?: PythFetchPolicy;
     /**
-     * Quote-center base URL for `oracleSource: 'waterx_rule'` — overrides the
+     * Quote-center base URL for `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
+     * This is the one source a BROWSER fetches itself (the signed price 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.
+     * forwards `GET /v1/quotes/leaves` (and `GET /v1/quotes/update`, the fallback
+     * route). 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
+     * `https://app.example/api/quote-center/v1/quotes/leaves` — a proxy route
      * survives instead of being rewritten to the origin root.
      */
     waterxEndpoint?: string;
@@ -96,14 +59,14 @@ export declare class PerpClient extends BaseLineClient<WaterXConfig> {
     /** 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'`
+     * Caller-supplied quote-center overrides for `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;
-    /** The fed set: `oracleSource` create option normalized to a non-empty, deduped list. */
+    /** The fed set, derived from the config — see {@link deriveOracleSources}. */
     readonly oracleSources: readonly OracleSource[];
     /** Canonical-schema lookups (delegated to below); no transport. */
     private readonly view;
@@ -123,11 +86,33 @@ export declare class PerpClient extends BaseLineClient<WaterXConfig> {
     getMarket(ticker: string): import("./config.ts").WaterxPerpMarketEntry;
     /** @see PerpConfigView.getAggregator */
     getAggregator(ticker: string): string;
-    /** @see PerpConfigView.getPythFeed */
-    getPythFeed(ticker: string): {
-        feed_id: string;
-        price_info_object: string;
-    };
+    /**
+     * WLP pool-token tickers THIS client's fed set can actually price — the
+     * ticker set the WLP builders refresh before `assert_prices_fresh`.
+     *
+     * Filtered, not raw `Object.keys(pool_tokens)`: a token only an UNLISTED
+     * source serves is not priceable by this client. The predicate is
+     * `refreshOraclePrices`'s own (`servableTickers`), so this list is exactly
+     * what a refresh would accept.
+     *
+     * NOTE this is a QUERY, not what the WLP builders use — they deliberately
+     * refresh and bump the WHOLE pool, because dropping an unpriceable asset
+     * from both halves is silent (see `assertWlpPoolRefreshed`).
+     */
+    pricedPoolTickers(): string[];
+    /**
+     * {@link pricedPoolTickers} already joined to each token's Move type.
+     *
+     * A query, not a build primitive: the WLP builders deliberately refresh and
+     * bump the WHOLE pool (`refreshWlpPoolOracles`), because pre-filtering to
+     * what this client can price silently drops an asset from both halves. Use
+     * this to ASK what a fed set covers — e.g. a dashboard, or a boot assert
+     * pairing it with `assertOracleWriteCoverage`.
+     */
+    pricedPoolTokens(): {
+        ticker: string;
+        tokenType: string;
+    }[];
     /** @see PerpConfigView.isConstantTicker */
     isConstantTicker(ticker: string): boolean;
     /** @see PerpConfigView.getSupraRule */