@waterx/sdk 4.0.0 → 4.0.1

package/dist/src/oracle/aggregate.d.ts

@@ -83,28 +83,26 @@ export declare function aggregateTickerWithConstant(tx: Transaction, host: Oracl
  * enabled, Constant when it's a constant ticker).
  *
  * Before that, the on-chain price *update* leg is routed by `host.oracleSource`
- * (see `rule-registry.ts`): the selected rule serves every ticker in its
- * `supportedTickers(host)`; tickers it doesn't cover fall back to `pyth_rule`
- * (`PythCoreRule`) when THEY support it — so when `oracleSource` IS `'pyth_rule'`
- * there is exactly one group, identical to the pre-routing behavior. A ticker
- * supported by neither is simply skipped from this leg (no fetch/build call for
- * it) — the same way today's non-pyth tickers (e.g. constant-only) always were;
- * it still gets aggregated below via whichever rule {@link aggregateTicker} finds.
+ * (see `rule-registry.ts`): the ONE selected source serves every ticker in its
+ * `supportedTickers(host)`. There is **no cross-source fallback** — a requested
+ * ticker the selected source does not serve, and that is not a constant-only
+ * ticker (which needs no price-update leg), fails the build immediately with a
+ * clear error naming the ticker and source. That is the deliberate "fail the
+ * tx-build, don't silently reroute" contract: a wrong-but-present feed id is
+ * NOT validated here (it surfaces on-chain at dry-run); a MISSING feed for the
+ * selected source is caught here. When the selected source's feed exists but is
+ * wrong, this function does nothing special — the on-chain aggregate aborts at
+ * dry-run, which is correct.
  *
- * Each group's fetch + build runs against its own rule, which guarantees
- * per-rule PTB atomicity (no mixed-generation payload within one rule's calls).
- * When `oracleSource` isn't `'pyth_rule'`, one PTB may legitimately carry BOTH a
- * non-Pyth-Core block (selected group) and a Pyth Core block (fallback group) —
- * each verifies against its own contract objects, so that's fine. A fee-source
- * pre-check runs first, across every group's `requiresFeeSource` — BEFORE any
- * off-chain fetch or PTB mutation — so a fee-charging group with no
- * `opts.feeSource` throws `OracleFeeSourceUnavailable` with zero wasted
- * network calls and zero stray moveCalls, even in a mixed shape (e.g. a
- * fee-free Lazer group ordered ahead of a Pyth Core fallback group). Only once
- * that check passes do all groups' off-chain fetches run concurrently
- * (`Promise.all`) and complete before any PTB mutation; on-chain reads inside
- * `buildUpdateCalls` can still fail mid-append for other reasons — callers
- * discard the tx on any throw.
+ * The selected source's fetch + build runs against its own infra, guaranteeing
+ * per-rule PTB atomicity. A fee-source pre-check runs first (the source's
+ * `requiresFeeSource`) BEFORE any off-chain fetch or PTB mutation — so a
+ * fee-charging source with no `opts.feeSource` throws
+ * `OracleFeeSourceUnavailable` with zero wasted network calls and zero stray
+ * moveCalls. Only once that check passes does the off-chain fetch run and
+ * complete before any PTB mutation; on-chain reads inside `buildUpdateCalls`
+ * can still fail mid-append for other reasons — callers discard the tx on any
+ * throw.
  *
  * **Collector-feed leg is rule-aware:** a lazer-served group's
  * `buildUpdateCalls` returns the verified `Update` PTB value

package/dist/src/oracle/aggregate.js

@@ -159,28 +159,26 @@ export function aggregateTickerWithConstant(tx, host, args) {
  * enabled, Constant when it's a constant ticker).
  *
  * Before that, the on-chain price *update* leg is routed by `host.oracleSource`
- * (see `rule-registry.ts`): the selected rule serves every ticker in its
- * `supportedTickers(host)`; tickers it doesn't cover fall back to `pyth_rule`
- * (`PythCoreRule`) when THEY support it — so when `oracleSource` IS `'pyth_rule'`
- * there is exactly one group, identical to the pre-routing behavior. A ticker
- * supported by neither is simply skipped from this leg (no fetch/build call for
- * it) — the same way today's non-pyth tickers (e.g. constant-only) always were;
- * it still gets aggregated below via whichever rule {@link aggregateTicker} finds.
+ * (see `rule-registry.ts`): the ONE selected source serves every ticker in its
+ * `supportedTickers(host)`. There is **no cross-source fallback** — a requested
+ * ticker the selected source does not serve, and that is not a constant-only
+ * ticker (which needs no price-update leg), fails the build immediately with a
+ * clear error naming the ticker and source. That is the deliberate "fail the
+ * tx-build, don't silently reroute" contract: a wrong-but-present feed id is
+ * NOT validated here (it surfaces on-chain at dry-run); a MISSING feed for the
+ * selected source is caught here. When the selected source's feed exists but is
+ * wrong, this function does nothing special — the on-chain aggregate aborts at
+ * dry-run, which is correct.
  *
- * Each group's fetch + build runs against its own rule, which guarantees
- * per-rule PTB atomicity (no mixed-generation payload within one rule's calls).
- * When `oracleSource` isn't `'pyth_rule'`, one PTB may legitimately carry BOTH a
- * non-Pyth-Core block (selected group) and a Pyth Core block (fallback group) —
- * each verifies against its own contract objects, so that's fine. A fee-source
- * pre-check runs first, across every group's `requiresFeeSource` — BEFORE any
- * off-chain fetch or PTB mutation — so a fee-charging group with no
- * `opts.feeSource` throws `OracleFeeSourceUnavailable` with zero wasted
- * network calls and zero stray moveCalls, even in a mixed shape (e.g. a
- * fee-free Lazer group ordered ahead of a Pyth Core fallback group). Only once
- * that check passes do all groups' off-chain fetches run concurrently
- * (`Promise.all`) and complete before any PTB mutation; on-chain reads inside
- * `buildUpdateCalls` can still fail mid-append for other reasons — callers
- * discard the tx on any throw.
+ * The selected source's fetch + build runs against its own infra, guaranteeing
+ * per-rule PTB atomicity. A fee-source pre-check runs first (the source's
+ * `requiresFeeSource`) BEFORE any off-chain fetch or PTB mutation — so a
+ * fee-charging source with no `opts.feeSource` throws
+ * `OracleFeeSourceUnavailable` with zero wasted network calls and zero stray
+ * moveCalls. Only once that check passes does the off-chain fetch run and
+ * complete before any PTB mutation; on-chain reads inside `buildUpdateCalls`
+ * can still fail mid-append for other reasons — callers discard the tx on any
+ * throw.
  *
  * **Collector-feed leg is rule-aware:** a lazer-served group's
  * `buildUpdateCalls` returns the verified `Update` PTB value
@@ -207,59 +205,49 @@ export async function refreshOraclePrices(tx, host, tickers, opts = {}) {
     const pythTickers = tickers.filter((t) => host.config.packages.pyth_rule?.feeds?.[t] !== undefined);
     const priceInfoByTicker = new Map();
     pythTickers.forEach((t) => priceInfoByTicker.set(t, host.getPythFeed(t).price_info_object));
-    // Group tickers for the on-chain update leg: selected rule first, then the
-    // pyth_rule fallback for whatever the selected rule doesn't cover. `source`
-    // is tracked alongside each group (rather than read back off `rule.kind`,
-    // which is typed as the broader PriceUpdateRuleKind) so the provider lookup
-    // below has an OracleSource to key on without a cast.
+    // ONE source, no fallback. The selected source serves the tickers in its
+    // `supportedTickers(host)`; `source` is tracked alongside the group (rather
+    // than read back off `rule.kind`, typed as the broader PriceUpdateRuleKind)
+    // so the provider lookup below has an OracleSource to key on without a cast.
     const selectedRule = resolveOracleRule(host.oracleSource, opts.ruleOverrides);
     const selectedSupported = new Set(selectedRule.supportedTickers(host));
-    const selectedGroup = tickers.filter((t) => selectedSupported.has(t));
-    const groups = [];
-    if (selectedGroup.length > 0) {
-        groups.push({ source: host.oracleSource, rule: selectedRule, tickers: selectedGroup });
-    }
-    if (host.oracleSource !== "pyth_rule") {
-        const fallbackRule = resolveOracleRule("pyth_rule", opts.ruleOverrides);
-        const fallbackSupported = new Set(fallbackRule.supportedTickers(host));
-        const fallbackGroup = tickers.filter((t) => !selectedSupported.has(t) && fallbackSupported.has(t));
-        if (fallbackGroup.length > 0) {
-            groups.push({ source: "pyth_rule", rule: fallbackRule, tickers: fallbackGroup });
-        }
+    // Fail the tx-build (NOT client init, NOT a silent reroute) when the selected
+    // source has no feed for a requested ticker that actually needs a price
+    // update. Only a CONSTANT-ONLY ticker is exempt — priced entirely by
+    // `constant_rule`, it needs no update leg from any source. A DUAL-FEED ticker
+    // (constant AND pyth) still needs its Pyth leg refreshed, so `isConstantTicker`
+    // alone must NOT exempt it: under a source that can't serve it, with no
+    // fallback, feeding an unrefreshed Pyth leg would price it stale (or abort on a
+    // missing weighted source). `priceInfoByTicker.has(t)` ⇔ the ticker has a
+    // `pyth_rule.feeds` entry, so `constant && !hasPyth` is exactly constant-only.
+    // This catches a MISSING feed; a present-but-WRONG feed id is deliberately not
+    // validated here (it aborts on-chain at dry-run).
+    const isConstantOnly = (t) => host.isConstantTicker(t) && !priceInfoByTicker.has(t);
+    const unservable = tickers.filter((t) => !selectedSupported.has(t) && !isConstantOnly(t));
+    if (unservable.length > 0) {
+        throw new Error(`oracleSource '${host.oracleSource}' has no feed configured for ticker(s): ` +
+            `${unservable.join(", ")}. Sources are self-contained with no fallback — add ` +
+            `${host.oracleSource} feeds for them, or select a source that serves them.`);
     }
-    // Fee-source pre-check, hoisted ABOVE both the off-chain fetch below AND
-    // the per-group build loop further down. The condition only consults
-    // `group.rule.requiresFeeSource` — known the moment `groups` is built,
-    // before any fetch or PTB mutation — so this throws with ZERO wasted
-    // network calls and zero PTB commands. A per-call guard inside
-    // `buildPythPriceUpdateCalls` alone would not be early enough: in a mixed
-    // shape (e.g. a lazer-selected `oracleSource` with a `pyth_rule` fallback
-    // group for tickers Lazer doesn't cover), the build loop runs each
-    // group's `buildUpdateCalls` in sequence — a fee-free group ordered ahead
-    // of a fee-charging one would already have appended its verify/feed
-    // moveCalls to the shared `tx` by the time the fee-charging group's own
-    // guard fired, breaking the "throw before any PTB mutation" guarantee.
-    // Checking every group's `requiresFeeSource` up front — before ANY group
-    // fetches or builds — closes that gap, and (unlike a referential check
-    // against a specific rule instance) keeps protecting a future
-    // fee-charging rule or a test double standing in for one.
-    if (!opts.feeSource && groups.some((group) => group.rule.requiresFeeSource)) {
+    const selectedGroup = tickers.filter((t) => selectedSupported.has(t));
+    // Fee-source pre-check, hoisted ABOVE the off-chain fetch and PTB build below.
+    // It consults only `rule.requiresFeeSource` — known before any fetch or PTB
+    // mutation — so a fee-charging source with no `feeSource` throws with ZERO
+    // wasted network calls and zero PTB commands, rather than waiting for
+    // `buildPythPriceUpdateCalls`'s own per-call guard to fire after the off-chain
+    // fetch already ran.
+    if (selectedGroup.length > 0 && !opts.feeSource && selectedRule.requiresFeeSource) {
         throw new OracleFeeSourceUnavailableError();
     }
-    // Fetch every group's off-chain payload concurrently (independent network
-    // calls — no reason to serialize) and let ALL of them settle before the
-    // first PTB mutation below, so a later group's fetch failure can never
-    // leave an earlier group's moveCalls stranded in a caller-owned tx.
-    const groupsWithData = await Promise.all(groups.map(async (group) => ({
-        rule: group.rule,
-        tickers: group.tickers,
-        data: await resolveGroupUpdateData(host, group, opts.updateDataProvider),
-    })));
-    // Verified-`Update` handle per lazer-served ticker (one shared PTB value per
-    // group) — consumed by the collector-feed leg below.
+    // Resolve + build the selected source's update leg. The off-chain fetch
+    // settles before the first PTB mutation, so a fetch failure never strands
+    // moveCalls in a caller-owned tx. Map each lazer-served ticker to the one
+    // verified `Update` PTB value for the collector-feed leg below.
     const lazerUpdateByTicker = new Map();
-    for (const group of groupsWithData) {
-        const handle = (await group.rule.buildUpdateCalls(tx, host, group.data, {
+    if (selectedGroup.length > 0) {
+        const group = { source: host.oracleSource, rule: selectedRule, tickers: selectedGroup };
+        const data = await resolveGroupUpdateData(host, group, opts.updateDataProvider);
+        const handle = (await selectedRule.buildUpdateCalls(tx, host, data, {
             cache: opts.cache,
             feeSource: opts.feeSource,
         })) ?? undefined;
@@ -267,7 +255,7 @@ export async function refreshOraclePrices(tx, host, tickers, opts = {}) {
         // protect: a future non-lazer handle (e.g. a WaterxRule value) must never
         // be silently fed into pyth_lazer_rule::feed.
         if (handle?.kind === "pyth_lazer_rule") {
-            for (const ticker of group.tickers)
+            for (const ticker of selectedGroup)
                 lazerUpdateByTicker.set(ticker, handle.update);
         }
     }

package/dist/src/oracle/config.d.ts

@@ -101,6 +101,29 @@ export interface OraclePackages {
     supra_rule?: SupraRulePackage;
     waterx_oracle: WaterxOraclePackage;
 }
+/**
+ * Resolved Pyth Core infra as it lives on `client.pyth` — NOT a config-JSON
+ * shape. `state_id` / `wormhole_state_id` / `hermes_endpoint` come verbatim
+ * from the fixed per-network constant ({@link PYTH_DEFAULTS}); `api_key` /
+ * `fetch` are layered on from the caller's `pythApiKey` / `pythFetch` create
+ * options. None of it is sourced from the canonical `waterx-config` JSON — the
+ * SDK never reads a `pyth` block there (a Bearer secret has no place in a
+ * public CDN document). The infra is the same for every `oracleSource`; the
+ * `pyth_lazer_rule` source reads only the `api_key` / `fetch` from here and
+ * gets its on-chain infra from {@link LAZER_DEFAULTS} + config instead.
+ */
+/**
+ * The caller-tunable subset of `fetchWithPolicy`'s policy exposed on the
+ * `pythFetch` create option and `client.pyth.fetch` — the retry/timeout budget
+ * for the off-chain Hermes (`fetchPriceFeedsUpdateData`) and Lazer
+ * (`PythLazerRule`) update fetches. Deliberately narrower than the internal
+ * `FetchPolicy` (no `retryDelayMs` / `apiKey` / `fetchImpl`). Both fetches fall
+ * back to `fetchWithPolicy`'s defaults (15s timeout, 2 retries) when unset.
+ */
+export type PythFetchPolicy = {
+    timeoutMs?: number;
+    retries?: number;
+};
 export interface PythInfraConfig {
     state_id: string;
     wormhole_state_id: string;
@@ -109,8 +132,8 @@ export interface PythInfraConfig {
      * Pyth Pro / Lazer access token (`Authorization: Bearer …`) for
      * `PythLazerRule`'s signed-update fetch — Lazer is auth-first, so there is
      * no keyless default. Optional: Pyth-Core-only deployments never need it.
-     * Consumers pass it through client config (`config.pyth`); the SDK never
-     * reads `process.env`. Absent when a lazer-routed fetch runs →
+     * Supplied via the `pythApiKey` create option (the SDK never reads
+     * `process.env` or the config JSON). Absent when a lazer-routed fetch runs →
      * `LazerApiKeyMissing` is thrown at fetch time. As of the Pyth Pro
      * migration (post-2026-08-18, per
      * https://docs.pyth.network/price-feeds/core/upgrade) this is ALSO required
@@ -119,57 +142,16 @@ export interface PythInfraConfig {
      */
     api_key?: string;
     /**
-     * Retry/timeout policy override for the Hermes (`fetchPriceFeedsUpdateData`)
-     * and Lazer (`PythLazerRule`) off-chain update fetches — see
-     * `fetchWithPolicy` (`./update-fetch.ts`) for the full policy (backoff,
-     * which statuses retry, Bearer attachment). Optional: both fetches default
-     * to `fetchWithPolicy`'s built-in defaults (15s timeout, 2 retries) when
-     * unset.
+     * Retry/timeout policy for the Hermes (`fetchPriceFeedsUpdateData`) and
+     * Lazer (`PythLazerRule`) off-chain update fetches — see `fetchWithPolicy`
+     * (`./update-fetch.ts`) for the full policy (backoff, which statuses retry,
+     * Bearer attachment). Supplied via the `pythFetch` create option. Optional:
+     * both fetches default to `fetchWithPolicy`'s built-in defaults (15s
+     * timeout, 2 retries) when unset.
      */
-    fetch?: {
-        timeoutMs?: number;
-        retries?: number;
-    };
+    fetch?: PythFetchPolicy;
 }
 export declare const PYTH_DEFAULTS: Record<Network, PythInfraConfig>;
-/**
- * Which Pyth Core contract generation feeds `host.pyth` when the config JSON
- * carries no explicit `pyth` override:
- *
- * - `'core'` (default) — the original contracts + keyless Hermes
- *   ({@link PYTH_DEFAULTS}).
- * - `'pro'` — the Pro-compatible upgraded contracts + the Hermes-compatible
- *   endpoint ({@link PYTH_PRO_DEFAULTS}); pair with `pyth.api_key` after the
- *   2026-08-18 cutover.
- *
- * Resolved once at client creation from the `pythGeneration` create option.
- * Orthogonal to `oracleSource` — this flips the Pyth-Core *infra* (state ids
- * + endpoint), not which `PriceUpdateRule` routes tickers.
- */
-export type PythGeneration = "core" | "pro";
-/**
- * Pyth **Pro-generation** Core-compatible infra — the post-2026-08-18
- * contracts (cutover date per
- * https://docs.pyth.network/price-feeds/core/upgrade) from Pyth's Core-Upgrade
- * docs
- * (https://docs.pyth.network/price-feeds/core/upgrade/contracts, Sui section;
- * package revs `sui-pro-compatible-contract-mainnet` /
- * `sui-pro-compatible-contract-testnet`). Selected via the client's
- * `pythGeneration: 'pro'` create option; `config.pyth` still overrides
- * wholesale (see `PerpClient`). All four state ids were verified on-chain
- * (shared `state::State` objects under the docs' upgraded package ids).
- *
- * Kept as a second flat map beside {@link PYTH_DEFAULTS} rather than a nested
- * `PYTH_INFRA[network][generation]` — `PYTH_DEFAULTS` is a published export
- * with external consumers, so the smallest honest surface is an additive
- * sibling (same deferral note as {@link LAZER_DEFAULTS}).
- *
- * The Hermes-compatible endpoint (`pyth.dourolabs.app/hermes`) serves the
- * same REST surface as `hermes.pyth.network` but requires `pyth.api_key`
- * (`Authorization: Bearer …`) after the cutover — see
- * {@link PythInfraConfig.api_key}.
- */
-export declare const PYTH_PRO_DEFAULTS: Record<Network, PythInfraConfig>;
 /**
  * Pyth Lazer (Pyth Pro) external infra the `PythLazerRule` needs, by network.
  * Mirrors {@link PYTH_DEFAULTS}: per-network constants for infrastructure Pyth
@@ -197,6 +179,4 @@ export declare const LAZER_DEFAULTS: Record<Network, {
  */
 export interface OracleConfig extends BaseLineConfig {
     packages: OraclePackages;
-    /** Pyth infra override (defaults from {@link PYTH_DEFAULTS}). */
-    pyth?: PythInfraConfig;
 }

package/dist/src/oracle/config.js

@@ -21,40 +21,6 @@ export const PYTH_DEFAULTS = {
         hermes_endpoint: "https://hermes-beta.pyth.network",
     },
 };
-/**
- * Pyth **Pro-generation** Core-compatible infra — the post-2026-08-18
- * contracts (cutover date per
- * https://docs.pyth.network/price-feeds/core/upgrade) from Pyth's Core-Upgrade
- * docs
- * (https://docs.pyth.network/price-feeds/core/upgrade/contracts, Sui section;
- * package revs `sui-pro-compatible-contract-mainnet` /
- * `sui-pro-compatible-contract-testnet`). Selected via the client's
- * `pythGeneration: 'pro'` create option; `config.pyth` still overrides
- * wholesale (see `PerpClient`). All four state ids were verified on-chain
- * (shared `state::State` objects under the docs' upgraded package ids).
- *
- * Kept as a second flat map beside {@link PYTH_DEFAULTS} rather than a nested
- * `PYTH_INFRA[network][generation]` — `PYTH_DEFAULTS` is a published export
- * with external consumers, so the smallest honest surface is an additive
- * sibling (same deferral note as {@link LAZER_DEFAULTS}).
- *
- * The Hermes-compatible endpoint (`pyth.dourolabs.app/hermes`) serves the
- * same REST surface as `hermes.pyth.network` but requires `pyth.api_key`
- * (`Authorization: Bearer …`) after the cutover — see
- * {@link PythInfraConfig.api_key}.
- */
-export const PYTH_PRO_DEFAULTS = {
-    MAINNET: {
-        state_id: "0x03719fae774ddab3cfcaa53bbc046f0cbe21410019b6280811bf3f9f4b05839d",
-        wormhole_state_id: "0xdbca52b9fb4f712e25f61f974586d93ac541bcf8389564f0323bb07215168b5c",
-        hermes_endpoint: "https://pyth.dourolabs.app/hermes",
-    },
-    TESTNET: {
-        state_id: "0x3c48fe392912de6c18087a2b3f5fdbfbfdb4598e180947feff1f12f8e9ea073e",
-        wormhole_state_id: "0x750da8e6d16b6a363a39fe2eaa8295ac224a1e6fce4e47b58845e2e8746164f0",
-        hermes_endpoint: "https://pyth.dourolabs.app/hermes",
-    },
-};
 // ============================================================================
 // Pyth Lazer — external infra, defaults by network
 // ============================================================================

package/dist/src/oracle/host.d.ts

@@ -16,7 +16,7 @@ export interface OracleHost {
     readonly network: Network;
     /** Oracle slice of the canonical `waterx-config` JSON (rule packages + per-ticker feeds). */
     readonly config: OracleConfig;
-    /** External Pyth/Wormhole/Hermes infra (network default, overridable via config). */
+    /** External Pyth/Wormhole/Hermes infra — fixed per `(network, generation)`; api_key/fetch layered from create options. */
     readonly pyth: PythInfraConfig;
     /** gRPC client for the on-chain reads the Pyth update path needs. */
     readonly grpcClient: SuiGrpcClient;

package/dist/src/oracle/index.d.ts

@@ -16,9 +16,9 @@
  * rules that consume it are separate concerns.
  */
 export type { OracleHost } from "./host.ts";
-export { FetchPolicyError } from "./update-fetch.ts";
+export { FetchPolicyError, fetchWithPolicy, joinEndpointPath } from "./update-fetch.ts";
 export type { FetchPolicy } from "./update-fetch.ts";
-export { PythCache, fetchPriceFeedsUpdateData, buildPythPriceUpdateCalls, updatePythPrices, OracleFeeSourceUnavailableError, } from "./pyth.ts";
+export { PythCache, fetchPriceFeedsUpdateData, endpointSupportedFeedIds, probeMissingFeeds, buildPythPriceUpdateCalls, updatePythPrices, HermesEndpointRejectedAllFeedsError, MISSING_FEED_MEMO_TTL_MS, OracleFeeSourceUnavailableError, } from "./pyth.ts";
 export type { OracleFeeSource } from "./pyth.ts";
 export type { PriceUpdateRule, PriceUpdateRuleKind, RuleUpdateData, RuleUpdateHandle, BuildUpdateOpts, OracleSource, UpdateDataProvider, } from "./price-update-rule.ts";
 export { PythCoreRule } from "./rules/pyth-core-rule.ts";

package/dist/src/oracle/index.js

@@ -19,13 +19,21 @@
 // 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).
-export { FetchPolicyError } from "./update-fetch.js";
-// 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.
-export { PythCache, fetchPriceFeedsUpdateData, buildPythPriceUpdateCalls, updatePythPrices, OracleFeeSourceUnavailableError, } from "./pyth.js";
+// `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).
+export { FetchPolicyError, fetchWithPolicy, joinEndpointPath } from "./update-fetch.js";
+// 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.
+export { PythCache, fetchPriceFeedsUpdateData, endpointSupportedFeedIds, probeMissingFeeds, buildPythPriceUpdateCalls, updatePythPrices, HermesEndpointRejectedAllFeedsError, MISSING_FEED_MEMO_TTL_MS, OracleFeeSourceUnavailableError, } from "./pyth.js";
 // Pyth Core rule (PriceUpdateRule wrapper over the Pyth source above)
 export { PythCoreRule } from "./rules/pyth-core-rule.js";
 // Pyth Lazer rule (signed-update generation; `feedLazerRule` stays internal to `aggregate.ts`)

package/dist/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