@waterx/sdk 4.0.0 → 4.1.0

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

@@ -17,23 +17,37 @@
  * rules that consume it are separate concerns.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.reimbursePythSponsor = exports.openPythSponsorFund = exports.refreshOraclePrices = exports.aggregateTickerWithConstant = exports.aggregateTickerWithPyth = exports.aggregateTicker = exports.OracleSourceNotImplementedError = exports.LazerApiKeyMissingError = exports.PythLazerRule = exports.PythCoreRule = exports.OracleFeeSourceUnavailableError = exports.updatePythPrices = exports.buildPythPriceUpdateCalls = exports.fetchPriceFeedsUpdateData = exports.PythCache = exports.FetchPolicyError = void 0;
+exports.reimbursePythSponsor = exports.openPythSponsorFund = exports.refreshOraclePrices = exports.aggregateTickerWithConstant = exports.aggregateTickerWithPyth = exports.aggregateTicker = exports.OracleSourceNotImplementedError = exports.parseSignedEnvelope = exports.WaterxRule = exports.LazerApiKeyMissingError = exports.PythLazerRule = exports.PythCoreRule = exports.OracleFeeSourceUnavailableError = exports.MISSING_FEED_MEMO_TTL_MS = exports.HermesEndpointRejectedAllFeedsError = exports.updatePythPrices = exports.buildPythPriceUpdateCalls = exports.probeMissingFeeds = exports.endpointSupportedFeedIds = exports.fetchPriceFeedsUpdateData = exports.PythCache = exports.joinEndpointPath = exports.fetchWithPolicy = exports.FetchPolicyError = void 0;
 // Shared fetch resilience wrapper — `FetchPolicyError` is re-exported (not
 // just the type) so a consumer (e.g. a BE prefetch cache) can `instanceof`
 // it off the failure `fetchPriceFeedsUpdateData` / `PythLazerRule` /
 // `loadConfig` surface, without a deep import of `./update-fetch.ts`.
-// `fetchWithPolicy` itself stays module-internal (no external caller yet).
+// `fetchWithPolicy` + `joinEndpointPath` are exported for consumers that hit
+// Hermes-compatible endpoints THEMSELVES (e.g. the BE's parsed latest-price
+// bootstrap and Pyth schedule readers): one shared Bearer/timeout/retry
+// policy and one base-path-safe URL join, instead of each caller re-rolling
+// them (the hand-rolled copies were how the Pro `/hermes` base path got
+// dropped and the Bearer went missing on sibling fetches).
 var update_fetch_ts_1 = require("./update-fetch.js");
 Object.defineProperty(exports, "FetchPolicyError", { enumerable: true, get: function () { return update_fetch_ts_1.FetchPolicyError; } });
-// Pyth source — `OracleFeeSourceUnavailableError` is re-exported (not just
-// the type) for the same `instanceof` reason as `FetchPolicyError` above: a
-// consumer of `buildPythPriceUpdateCalls` / `updatePythPrices` /
-// `refreshOraclePrices` can branch on the fee-source failure directly.
+Object.defineProperty(exports, "fetchWithPolicy", { enumerable: true, get: function () { return update_fetch_ts_1.fetchWithPolicy; } });
+Object.defineProperty(exports, "joinEndpointPath", { enumerable: true, get: function () { return update_fetch_ts_1.joinEndpointPath; } });
+// Pyth source — `OracleFeeSourceUnavailableError` and
+// `HermesEndpointRejectedAllFeedsError` are re-exported (not just the types)
+// for the same `instanceof` reason as `FetchPolicyError` above: a consumer of
+// `buildPythPriceUpdateCalls` / `updatePythPrices` / `refreshOraclePrices` can
+// branch on the fee-source failure directly, and a consumer of
+// `fetchPriceFeedsUpdateData` / `probeMissingFeeds` can tell a misconfigured
+// or unentitled endpoint apart from feeds that endpoint genuinely lacks.
 var pyth_ts_1 = require("./pyth.js");
 Object.defineProperty(exports, "PythCache", { enumerable: true, get: function () { return pyth_ts_1.PythCache; } });
 Object.defineProperty(exports, "fetchPriceFeedsUpdateData", { enumerable: true, get: function () { return pyth_ts_1.fetchPriceFeedsUpdateData; } });
+Object.defineProperty(exports, "endpointSupportedFeedIds", { enumerable: true, get: function () { return pyth_ts_1.endpointSupportedFeedIds; } });
+Object.defineProperty(exports, "probeMissingFeeds", { enumerable: true, get: function () { return pyth_ts_1.probeMissingFeeds; } });
 Object.defineProperty(exports, "buildPythPriceUpdateCalls", { enumerable: true, get: function () { return pyth_ts_1.buildPythPriceUpdateCalls; } });
 Object.defineProperty(exports, "updatePythPrices", { enumerable: true, get: function () { return pyth_ts_1.updatePythPrices; } });
+Object.defineProperty(exports, "HermesEndpointRejectedAllFeedsError", { enumerable: true, get: function () { return pyth_ts_1.HermesEndpointRejectedAllFeedsError; } });
+Object.defineProperty(exports, "MISSING_FEED_MEMO_TTL_MS", { enumerable: true, get: function () { return pyth_ts_1.MISSING_FEED_MEMO_TTL_MS; } });
 Object.defineProperty(exports, "OracleFeeSourceUnavailableError", { enumerable: true, get: function () { return pyth_ts_1.OracleFeeSourceUnavailableError; } });
 // Pyth Core rule (PriceUpdateRule wrapper over the Pyth source above)
 var pyth_core_rule_ts_1 = require("./rules/pyth-core-rule.js");
@@ -44,6 +58,11 @@ Object.defineProperty(exports, "PythCoreRule", { enumerable: true, get: function
 var pyth_lazer_rule_ts_1 = require("./rules/pyth-lazer-rule.js");
 Object.defineProperty(exports, "PythLazerRule", { enumerable: true, get: function () { return pyth_lazer_rule_ts_1.PythLazerRule; } });
 Object.defineProperty(exports, "LazerApiKeyMissingError", { enumerable: true, get: function () { return pyth_lazer_rule_ts_1.LazerApiKeyMissingError; } });
+// WaterX quote-center rule (first-party ed25519 signed batches; `feedWaterxRule`
+// stays internal to `aggregate.ts`).
+var waterx_rule_ts_1 = require("./rules/waterx-rule.js");
+Object.defineProperty(exports, "WaterxRule", { enumerable: true, get: function () { return waterx_rule_ts_1.WaterxRule; } });
+Object.defineProperty(exports, "parseSignedEnvelope", { enumerable: true, get: function () { return waterx_rule_ts_1.parseSignedEnvelope; } });
 // `resolveOracleRule` (rule-registry.ts) is NOT re-exported here — it has one
 // production consumer (`refreshOraclePrices` below) and no external caller;
 // per repo convention ("no unused exports") it stays module-internal. Tests

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

@@ -24,11 +24,10 @@ export type PriceUpdateRuleKind = "pyth_rule" | "pyth_lazer_rule" | "supra_rule"
  * create option (see `OracleHost.oracleSource`) — i.e. rules that can serve as
  * the on-chain price *update* leg `refreshOraclePrices` runs before aggregating.
  * `supra_rule` and `constant_rule` are auxiliary rules fed alongside whichever
- * source is selected (see `aggregateTicker`), not sources themselves;
- * `waterx_rule` has no `PriceUpdateRule` implementation yet. The SDK never
- * reads `process.env` — consumers resolve their own env var to this type.
+ * source is selected (see `aggregateTicker`), not sources themselves. The SDK
+ * never reads `process.env` — consumers resolve their own env var to this type.
  */
-export type OracleSource = "pyth_rule" | "pyth_lazer_rule";
+export type OracleSource = "pyth_rule" | "pyth_lazer_rule" | "waterx_rule";
 /**
  * Off-chain payload fetched by a rule, tagged by `kind` so a caller holding
  * several rules' results can tell them apart. `payload` is `unknown` here —

package/dist/cjs/src/oracle/pyth.d.ts

@@ -14,6 +14,7 @@
  *   4. hot_potato_vector::destroy
  */
 import type { Transaction, TransactionArgument } from "@mysten/sui/transactions";
+import type { PythFetchPolicy } from "./config.ts";
 import type { OracleHost } from "./host.ts";
 type PriceTableInfo = {
     id: string;
@@ -29,13 +30,74 @@ export declare class PythCache {
     priceTableInfo?: PriceTableInfo;
     priceFeedObjectIdCache: Map<string, string | undefined>;
 }
-export declare function fetchPriceFeedsUpdateData(endpoint: string, priceIds: string[], opts?: {
+type FetchOpts = {
     apiKey?: string;
-    fetch?: {
-        timeoutMs?: number;
-        retries?: number;
-    };
-}): Promise<Uint8Array[]>;
+    fetch?: PythFetchPolicy;
+};
+/**
+ * How long a "this endpoint lacks feed X" verdict stays memoized. The verdict
+ * is a claim about *someone else's* deployment — a feed can be added to the
+ * catalog, an entitlement can be granted, a Pro plan can be upgraded — so it
+ * must expire rather than bind the whole process lifetime. Long enough that a
+ * genuinely-absent feed costs one discovery per window instead of one per
+ * build; short enough that a recovered endpoint self-heals without a restart.
+ */
+export declare const MISSING_FEED_MEMO_TTL_MS: number;
+/**
+ * Thrown when discovery concludes that an endpoint rejects EVERY requested
+ * feed id without a catalog vouching for that verdict. `instanceof`-able
+ * (mirrors `FetchPolicyError` / {@link OracleFeeSourceUnavailableError}).
+ *
+ * "All of them are missing" is the signature of an endpoint/credential fault —
+ * a wrong base path (the Pyth Pro `/hermes` prefix dropped), a changed route,
+ * a revoked or downgraded entitlement — not of N individually-absent feeds.
+ * Memoizing it would convert a loud, fixable misconfiguration into a silent
+ * permanent one: every id marked missing ⇒ `fetchPriceFeedsUpdateData` returns
+ * `[]` ⇒ `buildPythPriceUpdateCalls` throws "Hermes returned empty results",
+ * blaming Hermes for having no data, for the rest of the process's life. So
+ * this case writes NOTHING to the memo and throws instead; the next call
+ * re-probes and recovers on its own once the endpoint does.
+ *
+ * The message keeps the `Hermes price fetch failed: <status>` prefix on its
+ * first line — the documented contract downstream consumers string-match (see
+ * {@link fetchPriceFeedsUpdateData} and the e2e transient detector).
+ */
+export declare class HermesEndpointRejectedAllFeedsError extends Error {
+    readonly endpoint: string;
+    readonly requestedCount: number;
+    constructor(endpoint: string, requestedCount: number, catalogState: "unreadable" | "empty");
+}
+/**
+ * The subset of `feedIds` this `endpoint` is known to serve — i.e. minus any
+ * discovered to be absent within the last {@link MISSING_FEED_MEMO_TTL_MS}
+ * (see {@link fetchPriceFeedsUpdateData}). Callers building a
+ * `{ updates, feedIds }` payload use this to keep `feedIds` aligned with the
+ * feeds the fetch actually returned data for, so `buildPythPriceUpdateCalls`
+ * (one moveCall per feed id) never references a feed the accumulator blob
+ * doesn't cover.
+ *
+ * Expired entries are pruned here rather than on a timer: the memo is only
+ * ever consulted through this function, so a lazy sweep is both sufficient and
+ * free of a dangling interval in a library.
+ */
+export declare function endpointSupportedFeedIds(endpoint: string, feedIds: string[], apiKey?: string): string[];
+/** Test-only: forget everything learned about which feeds an endpoint lacks. */
+export declare function __resetMissingFeedCacheForTest(): void;
+/**
+ * Discovery-only entry for consumers that fetch Hermes THEMSELVES (e.g. a
+ * parsed latest-price reader) and just observed a whole-batch 404: resolves
+ * which ids the endpoint lacks, memoizes them (see {@link
+ * endpointSupportedFeedIds}), fetches NO survivor data. Without this, such a
+ * consumer's only way to populate the memo was calling {@link
+ * fetchPriceFeedsUpdateData} and discarding its accumulator blob — two full
+ * redundant transfers per cold discovery.
+ *
+ * @throws HermesEndpointRejectedAllFeedsError when the rejection looks
+ * endpoint-wide rather than per-feed — the caller's own 404 is then a
+ * misconfiguration to surface, not a set of feeds to quietly drop.
+ */
+export declare function probeMissingFeeds(endpoint: string, ids: string[], opts?: FetchOpts): Promise<void>;
+export declare function fetchPriceFeedsUpdateData(endpoint: string, priceIds: string[], opts?: FetchOpts): Promise<Uint8Array[]>;
 /**
  * Resolved source for the Pyth Core on-chain update fee. Deliberately a
  * closed two-variant union, not a `{ sponsorFund?, allowGasFee? }` pair — a

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

@@ -15,7 +15,10 @@
  *   4. hot_potato_vector::destroy
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OracleFeeSourceUnavailableError = exports.PythCache = void 0;
+exports.OracleFeeSourceUnavailableError = exports.HermesEndpointRejectedAllFeedsError = exports.MISSING_FEED_MEMO_TTL_MS = exports.PythCache = void 0;
+exports.endpointSupportedFeedIds = endpointSupportedFeedIds;
+exports.__resetMissingFeedCacheForTest = __resetMissingFeedCacheForTest;
+exports.probeMissingFeeds = probeMissingFeeds;
 exports.fetchPriceFeedsUpdateData = fetchPriceFeedsUpdateData;
 exports.buildPythPriceUpdateCalls = buildPythPriceUpdateCalls;
 exports.updatePythPrices = updatePythPrices;
@@ -29,33 +32,337 @@ class PythCache {
     priceFeedObjectIdCache = new Map();
 }
 exports.PythCache = PythCache;
-// ============================================================================
-// Hermes REST
-// ============================================================================
+/**
+ * How long a "this endpoint lacks feed X" verdict stays memoized. The verdict
+ * is a claim about *someone else's* deployment — a feed can be added to the
+ * catalog, an entitlement can be granted, a Pro plan can be upgraded — so it
+ * must expire rather than bind the whole process lifetime. Long enough that a
+ * genuinely-absent feed costs one discovery per window instead of one per
+ * build; short enough that a recovered endpoint self-heals without a restart.
+ */
+exports.MISSING_FEED_MEMO_TTL_MS = 15 * 60_000;
+/**
+ * Per-endpoint memo of feed ids this endpoint has rejected as unknown (a 404
+ * on `/v2/updates/price/latest`). The Pyth Pro compat endpoint carries a
+ * SUBSET of Core's feeds — mainnet `WTIUSD`/`BRENTUSD` (Commodities
+ * USOILSPOT/UKOILSPOT) are absent, for example. Pyth 404s the WHOLE batch if
+ * ANY id is unknown, and the body naming the bad ids is NOT reliably delivered
+ * to `fetch` (Cloudflare returns it to curl but `content-length: 0` to node's
+ * undici), so the ids are isolated by catalog read (or bisection) and
+ * remembered here — later batches skip them instead of 404ing every time.
+ *
+ * Entries carry an expiry ({@link MISSING_FEED_MEMO_TTL_MS}); an
+ * endpoint-level fault never lands here at all (see {@link
+ * HermesEndpointRejectedAllFeedsError}).
+ */
+const missingFeedIdsByEndpoint = new Map();
+/**
+ * Thrown when discovery concludes that an endpoint rejects EVERY requested
+ * feed id without a catalog vouching for that verdict. `instanceof`-able
+ * (mirrors `FetchPolicyError` / {@link OracleFeeSourceUnavailableError}).
+ *
+ * "All of them are missing" is the signature of an endpoint/credential fault —
+ * a wrong base path (the Pyth Pro `/hermes` prefix dropped), a changed route,
+ * a revoked or downgraded entitlement — not of N individually-absent feeds.
+ * Memoizing it would convert a loud, fixable misconfiguration into a silent
+ * permanent one: every id marked missing ⇒ `fetchPriceFeedsUpdateData` returns
+ * `[]` ⇒ `buildPythPriceUpdateCalls` throws "Hermes returned empty results",
+ * blaming Hermes for having no data, for the rest of the process's life. So
+ * this case writes NOTHING to the memo and throws instead; the next call
+ * re-probes and recovers on its own once the endpoint does.
+ *
+ * The message keeps the `Hermes price fetch failed: <status>` prefix on its
+ * first line — the documented contract downstream consumers string-match (see
+ * {@link fetchPriceFeedsUpdateData} and the e2e transient detector).
+ */
+class HermesEndpointRejectedAllFeedsError extends Error {
+    endpoint;
+    requestedCount;
+    constructor(endpoint, requestedCount, catalogState) {
+        super(`Hermes price fetch failed: 404 — endpoint rejected ALL ${requestedCount} requested feed id(s) ` +
+            `and its feed catalog was ${catalogState}, so nothing vouches for those feeds being ` +
+            `individually absent. Treating this as an endpoint/credential fault (wrong base path — ` +
+            `e.g. a dropped Pyth Pro '/hermes' prefix — changed route, or revoked entitlement) rather ` +
+            `than caching every feed as missing. Endpoint: ${endpoint}`);
+        this.endpoint = endpoint;
+        this.requestedCount = requestedCount;
+        this.name = "HermesEndpointRejectedAllFeedsError";
+    }
+}
+exports.HermesEndpointRejectedAllFeedsError = HermesEndpointRejectedAllFeedsError;
+/**
+ * Memo key for `(endpoint, credential)` — the same trailing-slash trim
+ * {@link joinEndpointPath} applies to the request URL (shared helper, so the
+ * two can't drift), plus the apiKey: "feed X is missing" is a property of the
+ * endpoint AND the credential (Pyth Pro entitlements are per-key), so two
+ * clients in one process with different keys must not cross-poison each
+ * other's memo. Without the trim, two consumers spelling the same endpoint
+ * differently (`…/hermes` vs `…/hermes/`) would fragment the memo and re-run
+ * the whole 404 discovery despite one of them having already paid for it.
+ */
+function memoKey(endpoint, apiKey) {
+    return `${(0, update_fetch_ts_1.trimTrailingSlashes)(endpoint)}\u0000${apiKey ?? ""}`;
+}
+function recordMissingFeeds(endpoint, feedIds, apiKey) {
+    const key = memoKey(endpoint, apiKey);
+    let entries = missingFeedIdsByEndpoint.get(key);
+    if (!entries) {
+        entries = new Map();
+        missingFeedIdsByEndpoint.set(key, entries);
+    }
+    const expiresAt = Date.now() + exports.MISSING_FEED_MEMO_TTL_MS;
+    // Key on the bare (0x-stripped, lowercased) form — the SAME normalization the
+    // catalog comparison and the in-flight latch use — so a feed can't fragment
+    // the memo across `0xAB`/`ab` spellings and slip back through as unfiltered.
+    for (const feedId of feedIds)
+        entries.set(bareFeedId(feedId), expiresAt);
+}
+/**
+ * The subset of `feedIds` this `endpoint` is known to serve — i.e. minus any
+ * discovered to be absent within the last {@link MISSING_FEED_MEMO_TTL_MS}
+ * (see {@link fetchPriceFeedsUpdateData}). Callers building a
+ * `{ updates, feedIds }` payload use this to keep `feedIds` aligned with the
+ * feeds the fetch actually returned data for, so `buildPythPriceUpdateCalls`
+ * (one moveCall per feed id) never references a feed the accumulator blob
+ * doesn't cover.
+ *
+ * Expired entries are pruned here rather than on a timer: the memo is only
+ * ever consulted through this function, so a lazy sweep is both sufficient and
+ * free of a dangling interval in a library.
+ */
+function endpointSupportedFeedIds(endpoint, feedIds, apiKey) {
+    const key = memoKey(endpoint, apiKey);
+    const entries = missingFeedIdsByEndpoint.get(key);
+    if (!entries)
+        return feedIds;
+    const now = Date.now();
+    for (const [id, expiresAt] of entries) {
+        if (expiresAt <= now)
+            entries.delete(id);
+    }
+    if (entries.size === 0) {
+        missingFeedIdsByEndpoint.delete(key);
+        return feedIds;
+    }
+    return feedIds.filter((id) => !entries.has(bareFeedId(id)));
+}
+/**
+ * Discovery runs currently in flight, keyed by `(endpoint, credential,
+ * requested id set)`. A cold memo plus two concurrent tx-builds asking the
+ * same question ran two full independent discoveries — duplicate catalog reads
+ * (or duplicate bisection probe trees) on the money path, for one answer. The
+ * second caller now joins the first run's promise: each still gets its own
+ * survivor data, but they share the one discovery behind it.
+ */
+const inFlightDiscoveries = new Map();
+/** Test-only: forget everything learned about which feeds an endpoint lacks. */
+function __resetMissingFeedCacheForTest() {
+    missingFeedIdsByEndpoint.clear();
+    inFlightDiscoveries.clear();
+}
+/**
+ * One `GET /v2/price_feeds` — the set of feed ids this endpoint serves for
+ * THIS credential (verified against the Pro compat endpoint: WTI absent from
+ * the catalog AND 404 on latest-price; BTC present AND 200 —
+ * entitlement-filtered per key), normalized to bare lowercase hex.
+ *
+ * Returns `null` when the catalog is unreadable (non-2xx, unparseable, network
+ * error) — the catalog is an optimization, {@link bisectMissingFeeds} remains
+ * the ground truth derived from the money-path fetch itself. Note that "read
+ * fine, served nothing" (`size === 0`) is NOT the same as unreadable: an empty
+ * catalog is an entitlement/route fault in its own right, and the caller
+ * treats it as one.
+ */
+async function readEndpointCatalog(endpoint, opts) {
+    try {
+        const res = await (0, update_fetch_ts_1.fetchWithPolicy)((0, update_fetch_ts_1.joinEndpointPath)(endpoint, "v2/price_feeds").toString(), {}, { apiKey: opts?.apiKey, ...opts?.fetch });
+        if (!res.ok) {
+            void res.body?.cancel().catch(() => { });
+            return null;
+        }
+        const catalog = (await res.json());
+        if (!Array.isArray(catalog))
+            return null;
+        // Catalog ids come WITHOUT the 0x prefix; callers pass either form.
+        return new Set(catalog.map((f) => bareFeedId(f.id)));
+    }
+    catch {
+        return null;
+    }
+}
+/** Feed ids are compared prefix- and case-insensitively (`0xAB` ≡ `ab`). */
+function bareFeedId(feedId) {
+    return feedId.toLowerCase().replace(/^0x/, "");
+}
+async function rawFetch(endpoint, ids, opts) {
+    // joinEndpointPath preserves the endpoint's own base path — `new URL`
+    // with a leading-slash path would discard it (the Pyth Pro `/hermes`
+    // prefix → 404 on EVERY feed); see its doc in update-fetch.ts.
+    const url = (0, update_fetch_ts_1.joinEndpointPath)(endpoint, "v2/updates/price/latest");
+    ids.forEach((id) => url.searchParams.append("ids[]", id));
+    return (0, update_fetch_ts_1.fetchWithPolicy)(url.toString(), {}, { apiKey: opts?.apiKey, ...opts?.fetch });
+}
+/**
+ * Bisect `ids` down to the individual ones this endpoint 404s on — the
+ * response body isn't readable, so a single id that still 404s IS the unknown
+ * one. Data is discarded; this only *reports* (the caller decides whether the
+ * verdict is trustworthy enough to memoize). A non-404 (the subset is fine) or
+ * a network error stops that branch and contributes nothing.
+ *
+ * `known404: true` skips the root probe — the caller has already watched this
+ * exact batch 404, so re-fetching it would only re-learn a fact in hand (a
+ * wasted round trip on the money path during cold discovery). Recursive
+ * half-calls always probe: their status is genuinely unknown.
+ */
+async function bisectMissingFeeds(endpoint, ids, opts, known404 = false) {
+    if (ids.length === 0)
+        return new Set();
+    if (!known404) {
+        let res;
+        try {
+            res = await rawFetch(endpoint, ids, opts);
+        }
+        catch {
+            return new Set(); // transient/network failure — can't classify
+        }
+        void res.body?.cancel().catch(() => { });
+        if (res.status !== 404)
+            return new Set(); // this subset is serveable
+    }
+    if (ids.length === 1)
+        return new Set([ids[0]]);
+    const mid = Math.floor(ids.length / 2);
+    const [lo, hi] = await Promise.all([
+        bisectMissingFeeds(endpoint, ids.slice(0, mid), opts),
+        bisectMissingFeeds(endpoint, ids.slice(mid), opts),
+    ]);
+    return new Set([...lo, ...hi]);
+}
+/**
+ * Work out which of `ids` this endpoint lacks and memoize exactly those.
+ *
+ * Catalog first: one `GET /v2/price_feeds` answers for the whole batch, so a
+ * confirmed 404 costs one extra request instead of O(log n) bisection probes.
+ * The catalog is also the only *authoritative* source here — it says what the
+ * endpoint DOES serve, which is what separates "these two feeds are absent"
+ * from "this endpoint is serving nothing to me". Bisection can only observe
+ * 404s, and a wrong base path 404s identically to an unknown feed.
+ *
+ * Hence the guard: a verdict of "every requested id is missing" is only
+ * committed when a non-empty catalog vouches for it. Otherwise nothing is
+ * written and {@link HermesEndpointRejectedAllFeedsError} is thrown — see its
+ * docblock for why silently memoizing that case is worse than failing.
+ *
+ * Concurrent callers asking the identical question share ONE run (see {@link
+ * inFlightDiscoveries}); the latch is released on failure too, so a blip never
+ * pins later callers to a stale outcome.
+ *
+ * @throws HermesEndpointRejectedAllFeedsError on an endpoint-level rejection.
+ */
+function discoverMissingFeeds(endpoint, ids, opts, known404 = false) {
+    // Same endpoint + credential + requested set ⇒ same answer; anything else
+    // is a different question and runs on its own.
+    const key = `${memoKey(endpoint, opts?.apiKey)}${ids.map(bareFeedId).sort().join(",")}`;
+    const inFlight = inFlightDiscoveries.get(key);
+    if (inFlight)
+        return inFlight;
+    const run = runDiscovery(endpoint, ids, opts, known404).finally(() => {
+        inFlightDiscoveries.delete(key);
+    });
+    inFlightDiscoveries.set(key, run);
+    return run;
+}
+async function runDiscovery(endpoint, ids, opts, known404 = false) {
+    if (ids.length === 0)
+        return;
+    if (!known404) {
+        let res;
+        try {
+            res = await rawFetch(endpoint, ids, opts);
+        }
+        catch {
+            return; // transient/network failure — can't classify; leave the memo untouched
+        }
+        void res.body?.cancel().catch(() => { });
+        if (res.status !== 404)
+            return; // this batch is serveable — nothing to record
+    }
+    const catalog = await readEndpointCatalog(endpoint, opts);
+    if (catalog !== null && catalog.size === 0) {
+        // Read fine, serves nothing: an entitlement/route fault, not N absent feeds.
+        throw new HermesEndpointRejectedAllFeedsError(endpoint, ids.length, "empty");
+    }
+    const missing = catalog !== null
+        ? new Set(ids.filter((id) => !catalog.has(bareFeedId(id))))
+        : await bisectMissingFeeds(endpoint, ids, opts, true);
+    if (missing.size === 0)
+        return;
+    if (catalog === null && missing.size === ids.length) {
+        throw new HermesEndpointRejectedAllFeedsError(endpoint, ids.length, "unreadable");
+    }
+    recordMissingFeeds(endpoint, missing, opts?.apiKey);
+}
+/**
+ * Discovery-only entry for consumers that fetch Hermes THEMSELVES (e.g. a
+ * parsed latest-price reader) and just observed a whole-batch 404: resolves
+ * which ids the endpoint lacks, memoizes them (see {@link
+ * endpointSupportedFeedIds}), fetches NO survivor data. Without this, such a
+ * consumer's only way to populate the memo was calling {@link
+ * fetchPriceFeedsUpdateData} and discarding its accumulator blob — two full
+ * redundant transfers per cold discovery.
+ *
+ * @throws HermesEndpointRejectedAllFeedsError when the rejection looks
+ * endpoint-wide rather than per-feed — the caller's own 404 is then a
+ * misconfiguration to surface, not a set of feeds to quietly drop.
+ */
+function probeMissingFeeds(endpoint, ids, opts) {
+    return discoverMissingFeeds(endpoint, ids, opts, true);
+}
 async function fetchPriceFeedsUpdateData(endpoint, priceIds, opts) {
-    if (priceIds.length === 0)
+    // Skip feeds this endpoint has already told us it doesn't have.
+    const ids = endpointSupportedFeedIds(endpoint, priceIds, opts?.apiKey);
+    if (ids.length === 0)
         return [];
-    const url = new URL("/v2/updates/price/latest", endpoint);
-    priceIds.forEach((id) => url.searchParams.append("ids[]", id));
     let res;
     try {
-        res = await (0, update_fetch_ts_1.fetchWithPolicy)(url.toString(), {}, { apiKey: opts?.apiKey, ...opts?.fetch });
+        res = await rawFetch(endpoint, ids, opts);
     }
     catch (err) {
-        // A retryable status (429/5xx) that never recovered surfaces as a
-        // FetchPolicyError with `status` set — reformat it into this function's
-        // own message shape so callers (and the e2e transient-failure detector,
-        // which keys off "Hermes price fetch failed") see the same text whether
-        // the failure was retried or not. A network-level exhaustion (no status)
-        // has no domain-specific reframing to add — propagate it as-is.
-        if (err instanceof update_fetch_ts_1.FetchPolicyError && err.status !== undefined) {
-            const body = err.bodySnippet ? ` ${err.bodySnippet}` : "";
-            throw new Error(`Hermes price fetch failed: ${err.status}${body} (retries exhausted after ${err.attempts} attempts)`, { cause: err });
+        (0, update_fetch_ts_1.rethrowExhaustedFetch)(err, (e) => `Hermes price fetch failed: ${e.status}${e.bodySnippet ? ` ${e.bodySnippet}` : ""}`);
+    }
+    if (!res.ok) {
+        // Drain the body ONCE, here. A `Response` body can only be read once, and
+        // the 404 branch below finishes with it before the throw is reached — so
+        // reading it inside the throw surfaced `TypeError: Body is unusable`
+        // instead of this function's documented message whenever a 404 fell
+        // through. Reading up front also releases the connection on every path.
+        const body = await res.text().catch(() => "");
+        // Pyth 404s the ENTIRE batch if ANY id is unknown to the endpoint (a Core
+        // feed absent from the Pyth Pro compat endpoint). This is on the money
+        // path of every order/position/WLP tx-build, so instead of failing the
+        // whole refresh: discover the unknown ids (catalog, else bisection — the
+        // body isn't reliably delivered), memoize them, and re-fetch the survivors
+        // as ONE clean batch (a single combined accumulator blob, which
+        // buildPythPriceUpdateCalls requires). A genuinely-absent ticker just
+        // isn't in the payload — its on-chain aggregate abstains/aborts, which is
+        // correct. Steady state: once discovered, survivors are filtered up front
+        // and this never runs. A rejection that looks endpoint-wide instead of
+        // per-feed throws out of here (HermesEndpointRejectedAllFeedsError).
+        if (res.status === 404) {
+            // known404: this exact batch just 404'd above — skip the root re-probe.
+            await discoverMissingFeeds(endpoint, ids, opts, true);
+            const survivors = endpointSupportedFeedIds(endpoint, ids, opts?.apiKey);
+            if (survivors.length === 0)
+                return [];
+            // survivors < ids ⇒ we removed the offender(s); re-fetch cleanly. Equal
+            // ⇒ nothing was recorded (a 404 that wasn't a missing-feed rejection) —
+            // surface it rather than loop.
+            if (survivors.length < ids.length) {
+                return fetchPriceFeedsUpdateData(endpoint, survivors, opts);
+            }
         }
-        throw err;
+        throw new Error(`Hermes price fetch failed: ${res.status}${body ? ` ${body}` : ""}`);
     }
-    if (!res.ok)
-        throw new Error(`Hermes price fetch failed: ${res.status} ${await res.text()}`);
     const json = (await res.json());
     const data = json.binary?.data;
     if (!Array.isArray(data) || data.length === 0) {
@@ -286,9 +593,18 @@ async function buildPythPriceUpdateCalls(tx, host, updates, feedIds, opts) {
 }
 /** All-in-one: fetch from Hermes, append update calls. Returns PriceInfoObject IDs. */
 async function updatePythPrices(tx, host, feedIds, opts) {
-    const updates = await fetchPriceFeedsUpdateData(host.pyth.hermes_endpoint, feedIds, {
+    // `host.pyth` is the Pyth Core infra (fixed per network) plus the caller's
+    // api_key/fetch — endpoint, credential and policy all come from it.
+    const endpoint = host.pyth.hermes_endpoint;
+    const updates = await fetchPriceFeedsUpdateData(endpoint, feedIds, {
         apiKey: host.pyth.api_key,
         fetch: host.pyth.fetch,
     });
-    return buildPythPriceUpdateCalls(tx, host, updates, feedIds, opts);
+    // Align feedIds with the feeds the endpoint actually served — the fetch drops
+    // (and memoizes) any it lacks, and `buildPythPriceUpdateCalls` emits one
+    // update call per feedId, so a dropped feed would reference a PriceInfoObject
+    // the accumulator blob doesn't cover (invalid PTB / on-chain abort). Mirrors
+    // `PythCoreRule.fetchUpdateData`.
+    const servedFeedIds = endpointSupportedFeedIds(endpoint, feedIds, host.pyth.api_key);
+    return buildPythPriceUpdateCalls(tx, host, updates, servedFeedIds, opts);
 }

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

@@ -3,13 +3,18 @@
  * `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`, a client create option) — never by a
- * config JSON `enabled` flag and never by `process.env`.
+ * (ultimately `OracleHost.oracleSource`, the `oracleSource` client create
+ * option) — never by a config JSON `enabled` flag and never by `process.env`.
  *
- * Both sources are registered: `pyth_rule` (`PythCoreRule`, Hermes VAA) and
- * `pyth_lazer_rule` (`PythLazerRule`, Lazer signed updates). Resolving a
- * source with no registered rule throws a clear `OracleSourceNotImplemented`
- * error instead of silently falling back to Pyth Core.
+ * Each source is self-contained: it owns its own infra + config and does NOT
+ * back-stop any other source. Three are registered: `pyth_rule`
+ * (`PythCoreRule`, Hermes VAA), `pyth_lazer_rule` (`PythLazerRule`, Lazer
+ * signed updates), and `waterx_rule` (`WaterxRule`, first-party quote-center
+ * ed25519 signed batches). Resolving a source with no registered rule throws a
+ * clear `OracleSourceNotImplemented` error. There is deliberately no
+ * cross-source fallback and no client-creation config guard: selecting a source
+ * whose feeds are absent is not an error at init — it surfaces at tx-build time
+ * for the specific tickers that source can't serve (see `refreshOraclePrices`).
  */
 import type { OracleSource, PriceUpdateRule } from "./price-update-rule.ts";
 /**

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

@@ -4,19 +4,25 @@
  * `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`, a client create option) — never by a
- * config JSON `enabled` flag and never by `process.env`.
+ * (ultimately `OracleHost.oracleSource`, the `oracleSource` client create
+ * option) — never by a config JSON `enabled` flag and never by `process.env`.
  *
- * Both sources are registered: `pyth_rule` (`PythCoreRule`, Hermes VAA) and
- * `pyth_lazer_rule` (`PythLazerRule`, Lazer signed updates). Resolving a
- * source with no registered rule throws a clear `OracleSourceNotImplemented`
- * error instead of silently falling back to Pyth Core.
+ * Each source is self-contained: it owns its own infra + config and does NOT
+ * back-stop any other source. Three are registered: `pyth_rule`
+ * (`PythCoreRule`, Hermes VAA), `pyth_lazer_rule` (`PythLazerRule`, Lazer
+ * signed updates), and `waterx_rule` (`WaterxRule`, first-party quote-center
+ * ed25519 signed batches). Resolving a source with no registered rule throws a
+ * clear `OracleSourceNotImplemented` error. There is deliberately no
+ * cross-source fallback and no client-creation config guard: selecting a source
+ * whose feeds are absent is not an error at init — it surfaces at tx-build time
+ * for the specific tickers that source can't serve (see `refreshOraclePrices`).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OracleSourceNotImplementedError = void 0;
 exports.resolveOracleRule = resolveOracleRule;
 const pyth_core_rule_ts_1 = require("./rules/pyth-core-rule.js");
 const pyth_lazer_rule_ts_1 = require("./rules/pyth-lazer-rule.js");
+const waterx_rule_ts_1 = require("./rules/waterx-rule.js");
 /**
  * Production registry. Frozen — tests inject a fake rule via
  * `resolveOracleRule`'s `overrides` param instead of mutating this.
@@ -24,6 +30,7 @@ const pyth_lazer_rule_ts_1 = require("./rules/pyth-lazer-rule.js");
 const DEFAULT_RULES = Object.freeze({
     pyth_rule: pyth_core_rule_ts_1.PythCoreRule,
     pyth_lazer_rule: pyth_lazer_rule_ts_1.PythLazerRule,
+    waterx_rule: waterx_rule_ts_1.WaterxRule,
 });
 /**
  * Thrown by {@link resolveOracleRule} when `source` has no `PriceUpdateRule`