@waterx/sdk 3.1.0 → 4.0.0

package/dist/src/oracle/update-fetch.js

@@ -0,0 +1,223 @@
+/**
+ * `fetchWithPolicy` — resilience wrapper around `fetch` for the oracle money
+ * path's off-chain update-data fetches. Every order/position/collateral
+ * tx-build depends on one of these REST calls landing (Hermes VAA for
+ * `pyth_rule`, Lazer signed updates for `pyth_lazer_rule`); a bare `fetch`
+ * with a single attempt and no retry means one Hermes 429/5xx or timeout
+ * fails every trade. `fetchPriceFeedsUpdateData` (`./pyth.ts`),
+ * `PythLazerRule.fetchUpdateData`'s Lazer POST (`./rules/pyth-lazer-rule.ts`),
+ * and `loadConfig` (`../perp/config.ts`) all delegate here instead of calling
+ * `fetch` directly — this is the ONE place a retry/timeout/auth policy is
+ * implemented for these fetches.
+ *
+ * Policy semantics:
+ * - Bearer auth is attached iff `policy.apiKey` is a non-empty string —
+ *   absent/empty is byte-identical to today's keyless request (no
+ *   `Authorization` header at all). This is the Phase-0 invariant of the
+ *   Pyth Pro migration: existing keyless deployments see no behavior change.
+ * - Retries on network errors, HTTP 429, and HTTP 5xx, with exponential
+ *   backoff (`retryDelayMs * 2^attempt`, capped at `MAX_BACKOFF_MS`). Other
+ *   4xx statuses (401/400/403/404/…) are NOT retried — auth/bad-request
+ *   failures are deterministic, so that `Response` (`ok: false`) is handed
+ *   back on the first attempt for the caller to format its own
+ *   domain-specific error, exactly as it did before this wrapper existed.
+ * - `init.body`, if set, MUST be replayable across attempts — a retry
+ *   re-sends the SAME `init` object to `fetch` on every attempt. A string /
+ *   `URLSearchParams` / BCS-serialized `Uint8Array` body (every caller today)
+ *   is fine; a one-shot `ReadableStream` body would not survive a second
+ *   attempt and must not be passed through this function.
+ * - Each attempt gets its own `AbortSignal.timeout(policy.timeoutMs)`
+ *   combined with whichever of `init.signal` / the `externalSignal` param are
+ *   set — ALL of them can end the whole policy (not just the in-flight
+ *   attempt), including a queued backoff sleep, via `AbortSignal.any`
+ *   (runtime floor: Node ≥20.3 / any modern browser — matches this repo's
+ *   `target: ES2023` + `lib: ["dom", "esnext"]`).
+ * - Exhausting retries with no successful/non-retryable response (i.e. every
+ *   attempt was a network error, or the final attempt was still a retryable
+ *   HTTP failure) throws a {@link FetchPolicyError} naming the target's
+ *   `host + pathname` (never the query string — feed ids are off-chain
+ *   noise, not diagnostic value), the attempt count, and whichever of
+ *   `status` (a retryable HTTP failure — plus a truncated response-body
+ *   snippet, when the final attempt's response carried one) or `cause` (a
+ *   network error) the final attempt produced. An INTERMEDIATE (non-final)
+ *   retryable response's body is discarded via `response.body?.cancel()`
+ *   instead of read, so a doomed-to-retry response doesn't pin its
+ *   connection's socket open for no reason.
+ * - Retry worst case: with the defaults (15s timeout × 3 attempts + ~0.75s of
+ *   backoff between them) a FULL outage takes up to ~46s to surface as a
+ *   `FetchPolicyError`, vs ~15s pre-3.2.0's single bare-`fetch` attempt.
+ *   Tunable per client via `config.pyth.fetch.{timeoutMs,retries}`.
+ */
+const DEFAULT_TIMEOUT_MS = 15_000;
+const DEFAULT_RETRIES = 2;
+const DEFAULT_RETRY_DELAY_MS = 250;
+const MAX_BACKOFF_MS = 2_000;
+/** Final-error diagnostic only — not a protocol limit. */
+const MAX_BODY_SNIPPET_LENGTH = 200;
+/** Thrown by {@link fetchWithPolicy} when every attempt failed. */
+export class FetchPolicyError extends Error {
+    /** HTTP status of the final attempt, when it got a (retryable-but-failing) response. */
+    status;
+    /** Truncated (~200 char) body of the final attempt's response, when one was readable. */
+    bodySnippet;
+    /** Total attempts made (first try + retries actually used). */
+    attempts;
+    constructor(message, opts) {
+        super(message, opts.cause !== undefined ? { cause: opts.cause } : undefined);
+        this.name = "FetchPolicyError";
+        this.status = opts.status;
+        this.bodySnippet = opts.bodySnippet;
+        this.attempts = opts.attempts;
+    }
+}
+function isRetryableStatus(status) {
+    return status === 429 || status >= 500;
+}
+function backoffMs(retryDelayMs, attempt) {
+    return Math.min(retryDelayMs * 2 ** attempt, MAX_BACKOFF_MS);
+}
+/** `host + pathname` only — never the query string (feed ids are noise, not diagnostic). */
+function describeTarget(url) {
+    const parsed = new URL(url);
+    return `${parsed.host}${parsed.pathname}`;
+}
+function causeMessage(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+}
+/**
+ * Best-effort, truncated body text for the FINAL failed attempt's error
+ * message — restores the diagnostic a plain `if (!res.ok) throw new
+ * Error(...res.status, await res.text())` had before this wrapper existed.
+ * Swallows any read failure (missing/consumed body, a test double with no
+ * `.text()`, …) — a diagnostic snippet is never worth failing the request
+ * differently than the status/cause already dictate.
+ */
+async function readBodySnippet(response) {
+    try {
+        const text = await response.text();
+        return text.length > MAX_BODY_SNIPPET_LENGTH
+            ? `${text.slice(0, MAX_BODY_SNIPPET_LENGTH)}…`
+            : text;
+    }
+    catch {
+        return "";
+    }
+}
+/** Resolves after `ms`, or rejects immediately (with `signal.reason`) if `signal` fires first. */
+function sleep(ms, signal) {
+    if (!signal)
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    const abortSignal = signal;
+    if (abortSignal.aborted)
+        return Promise.reject(abortSignal.reason);
+    return new Promise((resolve, reject) => {
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(abortSignal.reason);
+        };
+        const timer = setTimeout(() => {
+            abortSignal.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        abortSignal.addEventListener("abort", onAbort, { once: true });
+    });
+}
+/** `undefined` if none are set; the lone signal if exactly one is; `AbortSignal.any(...)` otherwise. */
+function combineSignals(signals) {
+    const present = signals.filter((s) => s != null);
+    if (present.length === 0)
+        return undefined;
+    if (present.length === 1)
+        return present[0];
+    return AbortSignal.any(present);
+}
+/**
+ * Merge `Authorization: Bearer <apiKey>` into `base` iff `apiKey` is
+ * non-empty; `base` is returned UNTOUCHED otherwise (byte-identical to
+ * today's keyless requests — no header, whatever shape the caller passed).
+ * Always builds a plain object (never a `Headers` instance) so callers that
+ * assert on the exact `init` they handed `fetch` keep working unchanged.
+ */
+function withBearerAuth(base, apiKey) {
+    if (!apiKey)
+        return base;
+    const merged = {};
+    if (base instanceof Headers) {
+        base.forEach((value, key) => {
+            merged[key] = value;
+        });
+    }
+    else if (Array.isArray(base)) {
+        for (const [key, value] of base)
+            merged[key] = value;
+    }
+    else if (base) {
+        Object.assign(merged, base);
+    }
+    merged.Authorization = `Bearer ${apiKey}`;
+    return merged;
+}
+/**
+ * `fetch` with per-attempt timeout, bounded retry + backoff, and optional
+ * Bearer auth. See the module header for the full policy. Both `init.signal`
+ * (if the caller set one) AND the separate `externalSignal` param cancel the
+ * WHOLE policy — in-flight attempts AND queued backoff sleeps — not just a
+ * single attempt.
+ */
+export async function fetchWithPolicy(url, init = {}, policy = {}, externalSignal) {
+    const timeoutMs = policy.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const retries = policy.retries ?? DEFAULT_RETRIES;
+    const retryDelayMs = policy.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS;
+    const doFetch = policy.fetchImpl ?? fetch;
+    const headers = withBearerAuth(init.headers, policy.apiKey);
+    // init.signal is folded in here (not spread through per-attempt below) so
+    // it gates retries/backoff exactly like externalSignal, instead of being
+    // silently dropped by the `{ ...init, signal }` override per attempt.
+    const combinedExternalSignal = combineSignals([externalSignal, init.signal]);
+    for (let attempt = 0; attempt <= retries; attempt++) {
+        const timeoutSignal = AbortSignal.timeout(timeoutMs);
+        const signal = combinedExternalSignal
+            ? AbortSignal.any([timeoutSignal, combinedExternalSignal])
+            : timeoutSignal;
+        let status;
+        let bodySnippet;
+        let cause;
+        try {
+            const response = await doFetch(url, { ...init, headers, signal });
+            if (response.ok || !isRetryableStatus(response.status))
+                return response;
+            status = response.status;
+            if (attempt === retries) {
+                bodySnippet = await readBodySnippet(response);
+            }
+            else {
+                // Doomed to be retried — discard rather than read, so this
+                // response's connection/socket isn't held open for a body nobody
+                // will consume. `.catch()` is mandatory here: an errored stream's
+                // `cancel()` returns a REJECTED promise, and a bare `void` on that
+                // is an unhandled rejection — process-fatal in Node — triggered by
+                // exactly the degraded-upstream condition this wrapper exists to
+                // survive.
+                void response.body?.cancel().catch(() => { });
+            }
+        }
+        catch (err) {
+            if (combinedExternalSignal?.aborted)
+                throw err;
+            cause = err;
+        }
+        if (attempt === retries) {
+            const statusDetail = status !== undefined
+                ? `last status ${status}${bodySnippet ? ` — ${bodySnippet}` : ""}`
+                : undefined;
+            const detail = statusDetail ?? causeMessage(cause);
+            throw new FetchPolicyError(`fetchWithPolicy: ${describeTarget(url)} failed after ${attempt + 1} attempt(s) — ${detail}`, { status, bodySnippet, cause, attempts: attempt + 1 });
+        }
+        await sleep(backoffMs(retryDelayMs, attempt), combinedExternalSignal);
+    }
+    // Unreachable: the loop above always returns or throws on its final
+    // (attempt === retries) iteration — this satisfies the compiler only.
+    throw new FetchPolicyError(`fetchWithPolicy: ${describeTarget(url)} exhausted retries`, {
+        attempts: retries + 1,
+    });
+}

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

@@ -11,20 +11,41 @@
  * {@link PerpConfigView}. This class is just the wiring + factory between them.
  */
 import { BaseLineClient } from "../base-client.ts";
-import { type LoadConfigOptions, type PythInfraConfig, type WaterXConfig, type WormholeInfraConfig } from "./config.ts";
+import type { OracleSource } from "../oracle/price-update-rule.ts";
+import { type LoadConfigOptions, type PythGeneration, type PythInfraConfig, type WaterXConfig, type WormholeInfraConfig } from "./config.ts";
 import type { Network } from "./constants.ts";
 export interface CreateClientOptions extends LoadConfigOptions {
     grpcUrl?: string;
+    /**
+     * Selects which `PriceUpdateRule` `refreshOraclePrices` uses for the
+     * on-chain price-update leg (see `OracleHost.oracleSource`). Default:
+     * `'pyth_rule'`. The SDK never reads `process.env` — pass this from your
+     * own env var (e.g. `ORACLE_SOURCE`).
+     */
+    oracleSource?: OracleSource;
+    /**
+     * Selects which Pyth Core contract generation feeds `client.pyth` when the
+     * config JSON has no explicit `pyth` override: `'core'` (default,
+     * `PYTH_DEFAULTS`) or `'pro'` (`PYTH_PRO_DEFAULTS` — the post-2026-08-18
+     * Pro-compatible contracts + Hermes-compatible endpoint; pair with
+     * `pyth.api_key`). Orthogonal to `oracleSource`. An explicit `config.pyth`
+     * always wins wholesale (see `PythGeneration`).
+     */
+    pythGeneration?: PythGeneration;
 }
 export declare class PerpClient extends BaseLineClient<WaterXConfig> {
     /** Pyth infra (network defaults unless overridden in JSON). */
     pyth: PythInfraConfig;
     /** Wormhole infra for the credit bridge (network defaults unless overridden). */
     wormhole: WormholeInfraConfig;
+    /** Selected oracle rule source (client option, resolved at creation; default `'pyth_rule'`). See `OracleHost.oracleSource`. */
+    readonly oracleSource: OracleSource;
     /** Canonical-schema lookups (delegated to below); no transport. */
     private readonly view;
     constructor(network: Network, config: WaterXConfig, opts?: {
         grpcUrl?: string;
+        oracleSource?: OracleSource;
+        pythGeneration?: PythGeneration;
     });
     /**
      * Async factory: fetches the deployment config for `network` and returns

package/dist/src/perp/client.js

@@ -12,18 +12,23 @@
  */
 import { BaseLineClient } from "../base-client.js";
 import { PerpConfigView } from "./config-view.js";
-import { loadConfig, PYTH_DEFAULTS, WORMHOLE_DEFAULTS, } from "./config.js";
+import { loadConfig, PYTH_DEFAULTS, PYTH_PRO_DEFAULTS, WORMHOLE_DEFAULTS, } from "./config.js";
 export class PerpClient extends BaseLineClient {
     /** Pyth infra (network defaults unless overridden in JSON). */
     pyth;
     /** Wormhole infra for the credit bridge (network defaults unless overridden). */
     wormhole;
+    /** Selected oracle rule source (client option, resolved at creation; default `'pyth_rule'`). See `OracleHost.oracleSource`. */
+    oracleSource;
     /** Canonical-schema lookups (delegated to below); no transport. */
     view;
     constructor(network, config, opts = {}) {
         super(network, config, opts);
-        this.pyth = config.pyth ?? PYTH_DEFAULTS[network];
+        // Precedence: explicit config.pyth override > generation constants.
+        this.pyth =
+            config.pyth ?? (opts.pythGeneration === "pro" ? PYTH_PRO_DEFAULTS : PYTH_DEFAULTS)[network];
         this.wormhole = config.wormhole ?? WORMHOLE_DEFAULTS[network];
+        this.oracleSource = opts.oracleSource ?? "pyth_rule";
         this.view = new PerpConfigView(() => this.config, () => this.wormhole);
     }
     /**
@@ -32,7 +37,11 @@ export class PerpClient extends BaseLineClient {
      */
     static async create(network, opts = {}) {
         const config = await loadConfig(network, opts);
-        return new PerpClient(network, config, { grpcUrl: opts.grpcUrl });
+        return new PerpClient(network, config, {
+            grpcUrl: opts.grpcUrl,
+            oracleSource: opts.oracleSource,
+            pythGeneration: opts.pythGeneration,
+        });
     }
     static mainnet(opts = {}) {
         return PerpClient.create("MAINNET", opts);

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

@@ -12,8 +12,8 @@ import type { AccountPackages, BasePackageEntry, WormholeInfraConfig } from "../
 import type { OraclePackages, PythInfraConfig } from "../oracle/config.ts";
 import type { Network } from "./constants.ts";
 export type { AccountConfig, AccountPackages, BasePackageEntry, NativeCustodyAsset, NativeCustodyPackage, TrustedEmitterRow, WaterxCreditPackage, WaterxReferralPackage, WithdrawalQueuePackage, WormholeBridgePackage, WormholeInfraConfig, WxaAccountPackage, } from "../account/config.ts";
-export type { ConstantFeedEntry, OracleConfig, OraclePackages, PythInfraConfig, PythRulePackage, PythSponsorRulePackage, SupraFeedEntry, SupraRulePackage, WaterxConstantRulePackage, WaterxOraclePackage, } from "../oracle/config.ts";
-export { PYTH_DEFAULTS } from "../oracle/config.ts";
+export type { ConstantFeedEntry, OracleConfig, OraclePackages, PythGeneration, PythInfraConfig, PythLazerRulePackage, PythRulePackage, PythSponsorRulePackage, SupraFeedEntry, SupraRulePackage, WaterxConstantRulePackage, WaterxOraclePackage, } from "../oracle/config.ts";
+export { PYTH_DEFAULTS, PYTH_PRO_DEFAULTS } from "../oracle/config.ts";
 export interface WaterxPerpMarketEntry {
     market: string;
     config: string;
@@ -95,32 +95,27 @@ export interface WaterXConfig {
 }
 export interface LoadConfigOptions {
     /**
-     * Override the default config URL. Use this to point at a staging branch
-     * (`?ref=staging`) or a local mirror during development. Takes precedence
-     * over {@link configRef}.
+     * Canonical `waterx-config` JSON URL to fetch, **as-is** (no `<network>.json`
+     * / git ref appended). Required — {@link loadConfig} reads the URL only from
+     * this option (there is no env-var fallback and no built-in default) and
+     * throws when it is unset. Point it at a staging deployment or local mirror
+     * as needed.
      */
-    configUrl?: string;
-    /**
-     * Pin the canonical config to a specific git ref — a commit SHA, branch,
-     * or tag — instead of the default `main` branch. Resolves to
-     * `https://raw.githubusercontent.com/WaterXProtocol/waterx-config/<ref>/<network>.json`.
-     * Ignored when {@link configUrl} is set.
-     */
-    configRef?: string;
+    waterxConfigUrl?: string;
     /**
      * Reuse a previously-fetched config from the in-memory cache (keyed by
-     * the effective URL). Default: false (always fetch fresh).
+     * network + the effective URL). Default: false (always fetch fresh).
      */
     cache?: boolean;
     /** Optional fetch implementation (for tests or environments without global `fetch`). */
     fetchImpl?: typeof fetch;
-    /** Optional request timeout in ms. Default 10_000. */
+    /**
+     * Optional PER-ATTEMPT timeout in ms. Default 10_000. {@link loadConfig}
+     * retries a transient failure (network error / 429 / 5xx) via
+     * `fetchWithPolicy` (2 retries, exponential backoff) before falling back to
+     * the last successfully-validated config for this network+URL, if one exists.
+     */
     timeoutMs?: number;
 }
-/**
- * Build the canonical config URL for `network`, optionally pinned to a
- * specific git `ref` (commit SHA, branch, or tag). Defaults to `main`.
- */
-export declare function defaultConfigUrl(network: Network, ref?: string): string;
 export declare function clearConfigCache(): void;
 export declare function loadConfig(network: Network, opts?: LoadConfigOptions): Promise<WaterXConfig>;

package/dist/src/perp/config.js

@@ -8,7 +8,8 @@
  * **not** in the JSON — it lives in `PYTH_DEFAULTS` / `WORMHOLE_DEFAULTS`
  * below, keyed by network.
  */
-export { PYTH_DEFAULTS } from "../oracle/config.js";
+import { FetchPolicyError, fetchWithPolicy } from "../oracle/update-fetch.js";
+export { PYTH_DEFAULTS, PYTH_PRO_DEFAULTS } from "../oracle/config.js";
 // ============================================================================
 // Wormhole / Hermes — external chain infra, defaults by network
 // ============================================================================
@@ -33,45 +34,97 @@ export const WORMHOLE_DEFAULTS = {
         wormholescan_api: "https://api.testnet.wormholescan.io/api/v1",
     },
 };
-const CONFIG_REPO_RAW_BASE = "https://raw.githubusercontent.com/WaterXProtocol/waterx-config";
-/** Default git ref for the canonical config when none is pinned. */
-const DEFAULT_CONFIG_REF = "main";
-/**
- * Build the canonical config URL for `network`, optionally pinned to a
- * specific git `ref` (commit SHA, branch, or tag). Defaults to `main`.
- */
-export function defaultConfigUrl(network, ref = DEFAULT_CONFIG_REF) {
-    return `${CONFIG_REPO_RAW_BASE}/${ref}/${network.toLowerCase()}.json`;
-}
-const cache = new Map();
+// Last successfully-validated config per `${network}:${url}` — the ONE module
+// map, written UNCONDITIONALLY on every successful load regardless of
+// `opts.cache`. It serves two roles at once: the resilience fallback for a
+// refresh failure (see `loadConfig` below) AND the opt-in fast-path read
+// `opts.cache: true` gates at the top of `loadConfig`. `opts.cache` therefore
+// only gates whether a call *reads* this map early (skipping the fetch
+// entirely) — it never gates whether a call *writes* it; every successful
+// load writes here. The network prefix keeps one network's snapshot from ever
+// satisfying another's request (see the cache-key note in `loadConfig`).
+//
+// Deliberate (benign) semantic refinement from the prior two-map design: a
+// `cache: true` call can now hit an entry that was populated by an earlier
+// `cache: false` call for the SAME network+url. That's fine — it's still that
+// key's latest successfully-validated fetch, strictly FRESHER than any
+// fallback read would have been, so a `cache: true` caller never observes
+// staler data than before; it can only observe MORE-recent data sooner.
+const configCache = new Map();
 export function clearConfigCache() {
-    cache.clear();
+    configCache.clear();
 }
 export async function loadConfig(network, opts = {}) {
-    const url = opts.configUrl ?? defaultConfigUrl(network, opts.configRef);
-    if (opts.cache && cache.has(url)) {
-        return cache.get(url);
+    const url = opts.waterxConfigUrl;
+    if (!url) {
+        throw new Error("loadConfig: no config URL — pass opts.waterxConfigUrl");
+    }
+    // Key by network AND url, never url alone: the same url can legitimately be
+    // requested for two networks (and `validateConfig` enforces network/url
+    // coherence on the success path), so a url-only key would let a testnet
+    // snapshot satisfy a mainnet request — both on this fast-path read and on
+    // the resilience fallback below — handing back wrong-CHAIN object ids to
+    // build transactions against. A wrong-network request simply misses here
+    // and fetches fresh.
+    const cacheKey = `${network}:${url}`;
+    if (opts.cache && configCache.has(cacheKey)) {
+        return configCache.get(cacheKey);
     }
     const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
     if (!fetchImpl) {
         throw new Error("loadConfig: no global `fetch` available; pass opts.fetchImpl");
     }
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? 10_000);
-    let response;
+    // Same resilience policy as the oracle money-path fetches (see
+    // `fetchWithPolicy`): bounded retry with backoff instead of one bare
+    // attempt. A refresh failure (network exhaustion, a non-ok response, OR a
+    // 200 response that fails to parse/validate — see below) falls back to the
+    // last successfully-validated config for this network+URL when one exists — a
+    // config-endpoint blip must not crash a long-running process that already
+    // has a working deployment snapshot. First load (nothing cached yet) has
+    // no fallback and still throws. Intentionally no log line on the fallback
+    // path — the SDK never logs (see every other oracle error in this
+    // codebase); a caller that cares can tell it got a stale snapshot by
+    // re-deriving staleness itself if it needs to.
+    //
+    // Deliberate limitation (not fixed here — a follow-up): this treats EVERY
+    // failure mode identically, including a DETERMINISTIC one (404/403 — the
+    // URL moved, or access was revoked) once a `configCache` snapshot exists.
+    // Unlike a transient blip, a deterministic failure will never self-heal on
+    // the next retry, so a long-running process with a stale snapshot will
+    // keep serving it FOREVER and silently mask what is actually a permanent
+    // deployment problem. Disambiguating "blip" from "moved/revoked" (e.g. via
+    // a max-staleness budget, or treating non-retryable 4xx specially) is
+    // intentionally deferred rather than folded into this change.
+    //
+    // fetch → ok-check → parse → validate all run in ONE try, so any failure
+    // along that chain (network exhaustion, a non-ok response, malformed JSON,
+    // or a `validateConfig` rejection) lands in the same catch and takes the
+    // same single last-known-good lookup below.
+    let raw;
     try {
-        response = await fetchImpl(url, { signal: controller.signal });
-    }
-    finally {
-        clearTimeout(timer);
+        const response = await fetchWithPolicy(url, {}, { timeoutMs: opts.timeoutMs ?? 10_000, retries: 2, fetchImpl });
+        if (!response.ok) {
+            throw new Error(`loadConfig: HTTP ${response.status} fetching ${url}`);
+        }
+        raw = (await response.json());
+        validateConfig(raw, network, url);
     }
-    if (!response.ok) {
-        throw new Error(`loadConfig: HTTP ${response.status} fetching ${url}`);
+    catch (err) {
+        const stale = configCache.get(cacheKey);
+        if (stale)
+            return stale;
+        // Reformat a status-carrying FetchPolicyError (retries exhausted on a
+        // retryable status) into this function's own message shape, mirroring
+        // the non-retried `!response.ok` throw above. A network-level
+        // exhaustion (no status), a `!response.ok` throw, or a JSON parse /
+        // `validateConfig` failure has no domain-specific reframing to add —
+        // propagate that error's own message as-is.
+        if (err instanceof FetchPolicyError && err.status !== undefined) {
+            throw new Error(`loadConfig: HTTP ${err.status} fetching ${url} (retries exhausted after ${err.attempts} attempts)`, { cause: err });
+        }
+        throw err;
     }
-    const raw = (await response.json());
-    validateConfig(raw, network, url);
-    if (opts.cache)
-        cache.set(url, raw);
+    configCache.set(cacheKey, raw);
     return raw;
 }
 function validateConfig(cfg, expected, url) {
@@ -89,6 +142,9 @@ function validateConfig(cfg, expected, url) {
     };
     // Validate by deployment kind. A perp config must carry the perp set; a
     // credit config the credit set. `waterx_account` is common to both.
+    // `pyth_lazer_rule` is intentionally NOT required (and never will be by
+    // presence alone) — it's an optional/experimental package selected only via
+    // a client's `oracleSource` option, never by its presence in the config.
     const isPerp = "waterx_perp" in cfg.packages;
     const isCredit = "waterx_credit" in cfg.packages || "wormhole_bridge" in cfg.packages;
     const required = isPerp

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

@@ -1,7 +1,7 @@
 export { PerpClient } from "./client.ts";
 export type { CreateClientOptions } from "./client.ts";
-export { PYTH_DEFAULTS, WORMHOLE_DEFAULTS, clearConfigCache, defaultConfigUrl, loadConfig, } from "./config.ts";
-export type { BasePackageEntry, ConstantFeedEntry, WaterxReferralPackage, LoadConfigOptions, NativeCustodyAsset, NativeCustodyPackage, PythInfraConfig, PythRulePackage, PythSponsorRulePackage, SupraFeedEntry, SupraRulePackage, TestnetFaucetPackage, TrustedEmitterRow, WaterXConfig, WaterXPackages, WaterxCreditPackage, WaterxOraclePackage, WaterxPerpMarketEntry, WaterxPerpPackage, WaterxStakingPackage, WithdrawalQueuePackage, WlpPackage, WormholeBridgePackage, WormholeInfraConfig, WxaAccountPackage, } from "./config.ts";
+export { PYTH_DEFAULTS, PYTH_PRO_DEFAULTS, WORMHOLE_DEFAULTS, clearConfigCache, loadConfig, } from "./config.ts";
+export type { BasePackageEntry, ConstantFeedEntry, WaterxReferralPackage, LoadConfigOptions, NativeCustodyAsset, NativeCustodyPackage, PythGeneration, PythInfraConfig, PythLazerRulePackage, PythRulePackage, PythSponsorRulePackage, SupraFeedEntry, SupraRulePackage, TestnetFaucetPackage, TrustedEmitterRow, WaterXConfig, WaterXPackages, WaterxCreditPackage, WaterxOraclePackage, WaterxPerpMarketEntry, WaterxPerpPackage, WaterxStakingPackage, WithdrawalQueuePackage, WlpPackage, WormholeBridgePackage, WormholeInfraConfig, WxaAccountPackage, } from "./config.ts";
 export { ACTION_ADD_PRE_ORDER, ACTION_CANCEL_ORDER, ACTION_CANCEL_PRE_ORDER, ACTION_CLOSE_POSITION, ACTION_DECREASE_POSITION, ACTION_DEPOSIT_COLLATERAL, ACTION_INCREASE_POSITION, ACTION_LIQUIDATE, ACTION_OPEN_POSITION, ACTION_PLACE_ORDER, ACTION_UPDATE_ORDER, ACTION_WITHDRAW_COLLATERAL, BPS_SCALE, CRYPTO_FEE_RATE, DOUBLE_SCALE, DRY_RUN_SENDER, FLOAT_SCALE, MAINTENANCE_MARGIN_RATE, ORDER_LIMIT_BUY, ORDER_LIMIT_SELL, ORDER_STOP_BUY, ORDER_STOP_SELL, ORDER_TAG_WILDCARD, PERM_ALL, PERM_ALL_TRADING, PERM_CANCEL_ORDER, PERM_CLOSE_POSITION, PERM_DECREASE_POSITION, PERM_DEPOSIT_COLLATERAL, PERM_INCREASE_POSITION, PERM_MINT_WLP, PERM_OPEN_POSITION, PERM_PLACE_ORDER, PERM_REDEEM_WLP, PERM_WITHDRAW_COLLATERAL, STAKING_PERM_DEPOSIT_STAKE, STAKING_PERM_REDEEM_STAKE, STAKING_PERM_CLAIM_REWARD, STAKING_PERM_ALL, STOCK_FEE_RATE, MS_PER_YEAR, SUI_DECIMALS, WLP_DECIMALS, COLLATERAL_DECIMALS, TOKEN_DECIMALS, } from "./constants.ts";
 export type { Network } from "./constants.ts";
 export { getMarketTickers, getCollateralAssets } from "../utils/config.ts";
@@ -9,7 +9,8 @@ export { annualizedApyFromRatio, annualizeFundingRate, calcBorrowRate, calcBorro
 export * from "./user/index.ts";
 export * from "./tx-builders.ts";
 export * from "./fetch.ts";
-export { PythCache, aggregateTicker, aggregateTickerWithConstant, aggregateTickerWithPyth, buildPythPriceUpdateCalls, fetchPriceFeedsUpdateData, refreshOraclePrices, updatePythPrices, } from "../oracle/index.ts";
+export { FetchPolicyError, LazerApiKeyMissingError, OracleFeeSourceUnavailableError, OracleSourceNotImplementedError, PythCache, aggregateTicker, aggregateTickerWithConstant, aggregateTickerWithPyth, buildPythPriceUpdateCalls, fetchPriceFeedsUpdateData, refreshOraclePrices, updatePythPrices, } from "../oracle/index.ts";
+export type { FetchPolicy, OracleFeeSource, OracleSource, UpdateDataProvider, } from "../oracle/index.ts";
 export { fetchDepositVaa, fetchVaa, listBridgeWithdrawalVaas, listVaasByEmitter, padEvmEmitter, toWormholescanEmitter, vaaBase64ToBytes, vaaBase64ToHex, vaaBytesToBase64, waitForVaa, } from "../account/funding/wormhole.ts";
 export type { VaaListItem, VaaResponse, WormholescanOptions } from "../account/funding/wormhole.ts";
 export { AccountData as AccountDataBcs, GlobalConfigData as GlobalConfigDataBcs, MarketData as MarketDataBcs, OrderData as OrderDataBcs, PoolData as PoolDataBcs, PositionData as PositionDataBcs, RedeemRequestData as RedeemRequestDataBcs, TokenPoolData as TokenPoolDataBcs, } from "../generated/waterx_perp_view/view.ts";

package/dist/src/perp/index.js

@@ -1,6 +1,6 @@
 // ======== Core ========
 export { PerpClient } from "./client.js";
-export { PYTH_DEFAULTS, WORMHOLE_DEFAULTS, clearConfigCache, defaultConfigUrl, loadConfig, } from "./config.js";
+export { PYTH_DEFAULTS, PYTH_PRO_DEFAULTS, WORMHOLE_DEFAULTS, clearConfigCache, loadConfig, } from "./config.js";
 // ======== Constants & enums ========
 export { ACTION_ADD_PRE_ORDER, ACTION_CANCEL_ORDER, ACTION_CANCEL_PRE_ORDER, ACTION_CLOSE_POSITION, ACTION_DECREASE_POSITION, ACTION_DEPOSIT_COLLATERAL, ACTION_INCREASE_POSITION, ACTION_LIQUIDATE, ACTION_OPEN_POSITION, ACTION_PLACE_ORDER, ACTION_UPDATE_ORDER, ACTION_WITHDRAW_COLLATERAL, BPS_SCALE, CRYPTO_FEE_RATE, DOUBLE_SCALE, DRY_RUN_SENDER, FLOAT_SCALE, MAINTENANCE_MARGIN_RATE, ORDER_LIMIT_BUY, ORDER_LIMIT_SELL, ORDER_STOP_BUY, ORDER_STOP_SELL, ORDER_TAG_WILDCARD, PERM_ALL, PERM_ALL_TRADING, PERM_CANCEL_ORDER, PERM_CLOSE_POSITION, PERM_DECREASE_POSITION, PERM_DEPOSIT_COLLATERAL, PERM_INCREASE_POSITION, PERM_MINT_WLP, PERM_OPEN_POSITION, PERM_PLACE_ORDER, PERM_REDEEM_WLP, PERM_WITHDRAW_COLLATERAL, STAKING_PERM_DEPOSIT_STAKE, STAKING_PERM_REDEEM_STAKE, STAKING_PERM_CLAIM_REWARD, STAKING_PERM_ALL, STOCK_FEE_RATE, MS_PER_YEAR, SUI_DECIMALS, WLP_DECIMALS, COLLATERAL_DECIMALS, TOKEN_DECIMALS, } from "./constants.js";
 // ======== Utilities ========
@@ -13,7 +13,7 @@ export * from "./tx-builders.js";
 // ======== Read-only queries ========
 export * from "./fetch.js";
 // ======== Oracle utilities (Pyth source + rule aggregation) ========
-export { PythCache, aggregateTicker, aggregateTickerWithConstant, aggregateTickerWithPyth, buildPythPriceUpdateCalls, fetchPriceFeedsUpdateData, refreshOraclePrices, updatePythPrices, } from "../oracle/index.js";
+export { FetchPolicyError, LazerApiKeyMissingError, OracleFeeSourceUnavailableError, OracleSourceNotImplementedError, PythCache, aggregateTicker, aggregateTickerWithConstant, aggregateTickerWithPyth, buildPythPriceUpdateCalls, fetchPriceFeedsUpdateData, refreshOraclePrices, updatePythPrices, } from "../oracle/index.js";
 // ======== Wormhole / Wormholescan utilities (credit bridge) ========
 export { fetchDepositVaa, fetchVaa, listBridgeWithdrawalVaas, listVaasByEmitter, padEvmEmitter, toWormholescanEmitter, vaaBase64ToBytes, vaaBase64ToHex, vaaBytesToBase64, waitForVaa, } from "../account/funding/wormhole.js";
 // ======== Generated BCS types (sui-ts-codegen) ========