@waterx/sdk 3.1.1 → 4.0.1

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,24 +30,154 @@ export declare class PythCache {
     priceTableInfo?: PriceTableInfo;
     priceFeedObjectIdCache: Map<string, string | undefined>;
 }
-export declare function fetchPriceFeedsUpdateData(endpoint: string, priceIds: string[]): Promise<Uint8Array[]>;
+type FetchOpts = {
+    apiKey?: string;
+    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
+ * caller can no longer construct the "both supplied" or "neither supplied
+ * but some other truthy flag" shapes that used to require a priority rule to
+ * disambiguate.
+ *
+ * Resolved exactly ONCE, at the edges (`wrapRequestAndExecute` and the WLP
+ * builders' equivalent in `perp/tx-builders/`) from config presence
+ * (`pyth_sponsor_rule` deployed → open a fund → `'sponsor'`) and the
+ * caller's ergonomic `allowGasFee` opt-in (→ `'gas'`), then threaded
+ * verbatim through `refreshOraclePrices` → `BuildUpdateOpts` →
+ * `PythCoreRule` → {@link buildPythPriceUpdateCalls}. The sponsor-beats-gas
+ * priority from the old two-flag design is now structural — whichever edge
+ * resolves this value decides once; no downstream layer re-derives or
+ * re-documents a priority because none of them ever see more than one
+ * candidate source.
+ */
+export type OracleFeeSource = {
+    readonly kind: "sponsor";
+    readonly fund: TransactionArgument;
+    readonly packageId: string;
+} | {
+    readonly kind: "gas";
+};
+/**
+ * Thrown when no {@link OracleFeeSource} is available for the Pyth update fee
+ * — from `buildPythPriceUpdateCalls`'s own per-call guard, or `aggregate.ts`'s
+ * hoisted `refreshOraclePrices` pre-check (see its docblock). `instanceof`-able
+ * (mirrors `FetchPolicyError` in `update-fetch.ts`) so a consumer — e.g. a BE
+ * integration wiring its own `allowGasFee` decision — can branch on the error
+ * type directly instead of string-matching `error.message`.
+ */
+export declare class OracleFeeSourceUnavailableError extends Error {
+    constructor();
+}
 /**
  * Append the on-chain Pyth update PTB block. Returns `PriceInfoObject` IDs
  * (one per `feedIds`, same order). After this you can feed `pyth_rule` per
  * ticker against the matching `PriceInfoObject` (see `rules/pyth-rule.ts`).
  *
- * If `sponsorFund` is provided, the per-feed update fee comes from the
- * sponsor pool (`pyth_sponsor_rule::split`) instead of `tx.gas`. Opening and
- * reimbursing that fund is the sponsor rule's job (`rules/sponsor.ts`); here we
- * only draw a fee coin from the already-open `fund` hot potato.
+ * `opts.feeSource` is resolved BEFORE any PTB mutation and is never silently
+ * defaulted — this function trusts whatever single {@link OracleFeeSource}
+ * it's handed, it does not choose between competing candidates:
+ *   - `{ kind: 'sponsor' }` → the per-feed update fee is drawn from the
+ *     sponsor pool (`pyth_sponsor_rule::split`) instead of `tx.gas`. Opening
+ *     and reimbursing that fund is the caller's job (`rules/sponsor.ts` /
+ *     `wrapRequestAndExecute`, which opens it whenever the client's config
+ *     has `pyth_sponsor_rule` deployed) — this function only draws a fee
+ *     coin from the already-open `fund` hot potato.
+ *   - `{ kind: 'gas' }` → the fee is drawn from `tx.gas` via `tx.splitCoins`.
+ *     Only safe in a non-sponsored context — Enoki-sponsored transactions
+ *     reject any `tx.gas` draw.
+ *   - `undefined` → throws `OracleFeeSourceUnavailable` instead of silently
+ *     drawing from `tx.gas` (the old default), which broke under Enoki and,
+ *     worse, could fail ON-CHAIN when the market's `request_checklist`
+ *     requires the `PythSponsorRule` witness that only a real sponsor fund
+ *     attaches.
+ *
+ * This function's own check runs AFTER `updates`/`feedIds` are already in
+ * hand, so for `updatePythPrices` (which fetches from Hermes, then calls
+ * straight into this function) the off-chain fetch has already completed by
+ * the time this throws — a wasted network call, never a stray PTB command.
+ * `refreshOraclePrices` avoids that waste entirely: it hoists an EQUIVALENT
+ * check ABOVE its off-chain fetch AND its per-group build loop (see its
+ * docblock in `aggregate.ts`), keyed on `PriceUpdateRule.requiresFeeSource`
+ * rather than waiting for a specific rule's fetch to complete — so for that
+ * route neither the network call NOR any PTB command happens before the
+ * throw. This function's own (later, per-call) guard alone could not
+ * provide that "before any group builds" guarantee in a mixed shape (e.g. a
+ * fee-free Lazer group ordered ahead of a Pyth Core fallback group in the
+ * same PTB) — `refreshOraclePrices`'s pre-check is what closes it.
  */
-export declare function buildPythPriceUpdateCalls(tx: Transaction, host: OracleHost, updates: Uint8Array[], feedIds: string[], cache?: PythCache, sponsorFund?: {
-    fund: TransactionArgument;
-    packageId: string;
+export declare function buildPythPriceUpdateCalls(tx: Transaction, host: OracleHost, updates: Uint8Array[], feedIds: string[], opts?: {
+    cache?: PythCache;
+    feeSource?: OracleFeeSource;
 }): Promise<string[]>;
 /** All-in-one: fetch from Hermes, append update calls. Returns PriceInfoObject IDs. */
-export declare function updatePythPrices(tx: Transaction, host: OracleHost, feedIds: string[], cache?: PythCache, sponsorFund?: {
-    fund: TransactionArgument;
-    packageId: string;
+export declare function updatePythPrices(tx: Transaction, host: OracleHost, feedIds: string[], opts?: {
+    cache?: PythCache;
+    feeSource?: OracleFeeSource;
 }): Promise<string[]>;
 export {};

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

@@ -15,12 +15,16 @@
  *   4. hot_potato_vector::destroy
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-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;
 const bcs_1 = require("@mysten/bcs");
 const bcs_2 = require("@mysten/sui/bcs");
+const update_fetch_ts_1 = require("./update-fetch.js");
 class PythCache {
     pythStateInfo;
     wormholePackageId;
@@ -28,17 +32,337 @@ class PythCache {
     priceFeedObjectIdCache = new Map();
 }
 exports.PythCache = PythCache;
-// ============================================================================
-// Hermes REST
-// ============================================================================
-async function fetchPriceFeedsUpdateData(endpoint, priceIds) {
-    if (priceIds.length === 0)
+/**
+ * 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) {
+    // 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));
-    const res = await fetch(url.toString(), { signal: AbortSignal.timeout(15_000) });
-    if (!res.ok)
-        throw new Error(`Hermes price fetch failed: ${res.status} ${await res.text()}`);
+    let res;
+    try {
+        res = await rawFetch(endpoint, ids, opts);
+    }
+    catch (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 new Error(`Hermes price fetch failed: ${res.status}${body ? ` ${body}` : ""}`);
+    }
     const json = (await res.json());
     const data = json.binary?.data;
     if (!Array.isArray(data) || data.length === 0) {
@@ -144,26 +468,73 @@ function extractVaaBytes(accumulatorMessage) {
     const vaaOffset = vaaSizeOffset + 2;
     return accumulatorMessage.subarray(vaaOffset, vaaOffset + vaaSize);
 }
-// ============================================================================
-// Pyth update calls
-// ============================================================================
+/**
+ * Thrown when no {@link OracleFeeSource} is available for the Pyth update fee
+ * — from `buildPythPriceUpdateCalls`'s own per-call guard, or `aggregate.ts`'s
+ * hoisted `refreshOraclePrices` pre-check (see its docblock). `instanceof`-able
+ * (mirrors `FetchPolicyError` in `update-fetch.ts`) so a consumer — e.g. a BE
+ * integration wiring its own `allowGasFee` decision — can branch on the error
+ * type directly instead of string-matching `error.message`.
+ */
+class OracleFeeSourceUnavailableError extends Error {
+    constructor() {
+        super("OracleFeeSourceUnavailable: no fee source available for the Pyth update fee — " +
+            "deploy pyth_sponsor_rule to config so a sponsor fund can be opened (see " +
+            "openPythSponsorFund / wrapRequestAndExecute), or pass allowGasFee: true to draw " +
+            "the fee from tx.gas in a non-sponsored context");
+        this.name = "OracleFeeSourceUnavailableError";
+    }
+}
+exports.OracleFeeSourceUnavailableError = OracleFeeSourceUnavailableError;
 /**
  * Append the on-chain Pyth update PTB block. Returns `PriceInfoObject` IDs
  * (one per `feedIds`, same order). After this you can feed `pyth_rule` per
  * ticker against the matching `PriceInfoObject` (see `rules/pyth-rule.ts`).
  *
- * If `sponsorFund` is provided, the per-feed update fee comes from the
- * sponsor pool (`pyth_sponsor_rule::split`) instead of `tx.gas`. Opening and
- * reimbursing that fund is the sponsor rule's job (`rules/sponsor.ts`); here we
- * only draw a fee coin from the already-open `fund` hot potato.
+ * `opts.feeSource` is resolved BEFORE any PTB mutation and is never silently
+ * defaulted — this function trusts whatever single {@link OracleFeeSource}
+ * it's handed, it does not choose between competing candidates:
+ *   - `{ kind: 'sponsor' }` → the per-feed update fee is drawn from the
+ *     sponsor pool (`pyth_sponsor_rule::split`) instead of `tx.gas`. Opening
+ *     and reimbursing that fund is the caller's job (`rules/sponsor.ts` /
+ *     `wrapRequestAndExecute`, which opens it whenever the client's config
+ *     has `pyth_sponsor_rule` deployed) — this function only draws a fee
+ *     coin from the already-open `fund` hot potato.
+ *   - `{ kind: 'gas' }` → the fee is drawn from `tx.gas` via `tx.splitCoins`.
+ *     Only safe in a non-sponsored context — Enoki-sponsored transactions
+ *     reject any `tx.gas` draw.
+ *   - `undefined` → throws `OracleFeeSourceUnavailable` instead of silently
+ *     drawing from `tx.gas` (the old default), which broke under Enoki and,
+ *     worse, could fail ON-CHAIN when the market's `request_checklist`
+ *     requires the `PythSponsorRule` witness that only a real sponsor fund
+ *     attaches.
+ *
+ * This function's own check runs AFTER `updates`/`feedIds` are already in
+ * hand, so for `updatePythPrices` (which fetches from Hermes, then calls
+ * straight into this function) the off-chain fetch has already completed by
+ * the time this throws — a wasted network call, never a stray PTB command.
+ * `refreshOraclePrices` avoids that waste entirely: it hoists an EQUIVALENT
+ * check ABOVE its off-chain fetch AND its per-group build loop (see its
+ * docblock in `aggregate.ts`), keyed on `PriceUpdateRule.requiresFeeSource`
+ * rather than waiting for a specific rule's fetch to complete — so for that
+ * route neither the network call NOR any PTB command happens before the
+ * throw. This function's own (later, per-call) guard alone could not
+ * provide that "before any group builds" guarantee in a mixed shape (e.g. a
+ * fee-free Lazer group ordered ahead of a Pyth Core fallback group in the
+ * same PTB) — `refreshOraclePrices`'s pre-check is what closes it.
  */
-async function buildPythPriceUpdateCalls(tx, host, updates, feedIds, cache, sponsorFund) {
+async function buildPythPriceUpdateCalls(tx, host, updates, feedIds, opts) {
     if (updates.length === 0) {
         throw new Error("No price update data provided; Hermes returned empty results");
     }
     if (updates.length > 1) {
         throw new Error("Only a single accumulator message is supported per transaction");
     }
+    const feeSource = opts?.feeSource;
+    if (!feeSource) {
+        throw new OracleFeeSourceUnavailableError();
+    }
+    const cache = opts?.cache;
     const pyth = host.pyth;
     const [stateInfo, wormholePackageId, table] = await Promise.all([
         getPythStateInfo(host.grpcClient, pyth.state_id, cache),
@@ -195,10 +566,10 @@ async function buildPythPriceUpdateCalls(tx, host, updates, feedIds, cache, spon
         if (!priceInfoObjectId) {
             throw new Error(`Pyth feed ${feedIds[i]} not registered on-chain in Pyth state`);
         }
-        const feeCoin = sponsorFund
+        const feeCoin = feeSource.kind === "sponsor"
             ? tx.moveCall({
-                target: `${sponsorFund.packageId}::pyth_sponsor_rule::split`,
-                arguments: [sponsorFund.fund],
+                target: `${feeSource.packageId}::pyth_sponsor_rule::split`,
+                arguments: [feeSource.fund],
             })[0]
             : tx.splitCoins(tx.gas, [tx.pure.u64(baseUpdateFee)])[0];
         [hotPotato] = tx.moveCall({
@@ -221,7 +592,19 @@ async function buildPythPriceUpdateCalls(tx, host, updates, feedIds, cache, spon
     return priceInfoObjectIds;
 }
 /** All-in-one: fetch from Hermes, append update calls. Returns PriceInfoObject IDs. */
-async function updatePythPrices(tx, host, feedIds, cache, sponsorFund) {
-    const updates = await fetchPriceFeedsUpdateData(host.pyth.hermes_endpoint, feedIds);
-    return buildPythPriceUpdateCalls(tx, host, updates, feedIds, cache, sponsorFund);
+async function updatePythPrices(tx, host, feedIds, opts) {
+    // `host.pyth` is the Pyth Core infra (fixed per network) plus the caller's
+    // api_key/fetch — endpoint, credential and policy all come from it.
+    const endpoint = host.pyth.hermes_endpoint;
+    const updates = await fetchPriceFeedsUpdateData(endpoint, feedIds, {
+        apiKey: host.pyth.api_key,
+        fetch: host.pyth.fetch,
+    });
+    // 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);
 }