@waterx/sdk 3.1.1 → 4.0.1

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

@@ -0,0 +1,277 @@
+/**
+ * `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`). A 429
+ *   carrying a numeric `Retry-After` header uses the SERVER'S delay instead,
+ *   when it fits under the same cap — a longer ask degrades to normal
+ *   backoff rather than stalling a money-path build for tens of seconds.
+ *   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 the `pythFetch` create option (`{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;
+    }
+}
+/**
+ * Rethrow a `catch`-ed {@link fetchWithPolicy} failure. When it is a
+ * status-carrying `FetchPolicyError` — a retryable status (429/5xx) that never
+ * recovered — throw a new Error `${describe(err)} (retries exhausted after N
+ * attempts)` with the original as `cause`; otherwise (a network-level
+ * exhaustion with no status, or any non-`FetchPolicyError`) rethrow it verbatim,
+ * since there is no domain reframing to add. `describe` builds the
+ * status-bearing prefix so each caller keeps its own message shape (the e2e
+ * transient detector keys off those prefixes) while the guard, the `retries
+ * exhausted` suffix, and the `cause` wrapping live in one place. `: never` so a
+ * caller's `catch` block is understood not to fall through.
+ */
+export function rethrowExhaustedFetch(err, describe) {
+    if (err instanceof FetchPolicyError && err.status !== undefined) {
+        throw new Error(`${describe(err)} (retries exhausted after ${err.attempts} attempts)`, {
+            cause: err,
+        });
+    }
+    throw err;
+}
+/**
+ * Join an API `path` onto an `endpoint` PRESERVING the endpoint's own base
+ * path. `new URL(path, endpoint)` is the footgun this replaces: a
+ * leading-slash path is *absolute* and silently discards the endpoint's path
+ * — harmless for a bare-origin endpoint (`https://hermes.pyth.network`) but
+ * it dropped the `/hermes` prefix of the Pyth Pro compat endpoint and 404'd
+ * every feed (see `fetchPriceFeedsUpdateData`). Every oracle fetch that
+ * targets `<endpoint><fixed path>` must build its URL here.
+ */
+/** One canonical trailing-slash trim — `joinEndpointPath` (URL building) and
+ * `pyth.ts`'s `memoKey` (endpoint identity) must never drift apart on it. */
+export function trimTrailingSlashes(endpoint) {
+    return endpoint.replace(/\/+$/, "");
+}
+export function joinEndpointPath(endpoint, path) {
+    return new URL(`${trimTrailingSlashes(endpoint)}/${path.replace(/^\/+/, "")}`);
+}
+function isRetryableStatus(status) {
+    return status === 429 || status >= 500;
+}
+function backoffMs(retryDelayMs, attempt) {
+    return Math.min(retryDelayMs * 2 ** attempt, MAX_BACKOFF_MS);
+}
+/**
+ * The server's own `Retry-After` (numeric-seconds form only), when present
+ * and within `MAX_BACKOFF_MS` — `undefined` otherwise (absent, HTTP-date
+ * form, zero/garbage, or an ask too long to honor inside a build path).
+ */
+function retryAfterMs(response) {
+    // Optional-chained: minimal test doubles (and some fetch shims) carry no
+    // `headers` — a missing header must read as "no hint", never throw.
+    const ms = Number(response.headers?.get?.("retry-after")) * 1_000;
+    return ms > 0 && ms <= MAX_BACKOFF_MS ? ms : undefined;
+}
+/** `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;
+        let serverRetryDelay;
+        try {
+            const response = await doFetch(url, { ...init, headers, signal });
+            if (response.ok || !isRetryableStatus(response.status))
+                return response;
+            status = response.status;
+            serverRetryDelay = retryAfterMs(response);
+            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(serverRetryDelay ?? 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,24 +11,59 @@
  * {@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 PythFetchPolicy, type PythInfraConfig, type WaterXConfig, type WormholeInfraConfig } from "./config.ts";
 import type { Network } from "./constants.ts";
 export interface CreateClientOptions extends LoadConfigOptions {
     grpcUrl?: string;
+    /**
+     * Which oracle price-update source drives `refreshOraclePrices`. Each source
+     * is self-contained (own infra + config) with NO cross-source fallback:
+     *
+     * - `'pyth_rule'` (default) — Pyth Core `pyth_rule` updates (Hermes VAA +
+     *   per-feed update fees), Core state + keyless Core Hermes.
+     * - `'pyth_lazer_rule'` — Pyth Lazer signed updates (ONE `leEcdsa` verify
+     *   per PTB, no per-feed fees); needs `packages.pyth_lazer_rule` with feeds
+     *   and a `pythApiKey` (Lazer is auth-first).
+     *
+     * A source-neutral name on purpose — a future source need not be Pyth.
+     * Selecting a source whose feed for a requested ticker is absent is NOT an
+     * error at client creation: it fails at tx-build time for exactly those
+     * tickers (see `refreshOraclePrices`). The Pyth Core infra is fixed per
+     * network by `PYTH_DEFAULTS` and is not deployment-overridable.
+     */
+    oracleSource?: OracleSource;
+    /**
+     * Pyth Lazer access token (`Authorization: Bearer …`). Required under
+     * `oracleSource: 'pyth_lazer_rule'` (Lazer is auth-first) and unused by
+     * `'pyth_rule'` (keyless Core Hermes). This is a SECRET and never belongs in
+     * the canonical `waterx-config` JSON — pass it at client init from your own
+     * env var (e.g. `PYTH_API_KEY`); the SDK never reads `process.env`.
+     */
+    pythApiKey?: string;
+    /**
+     * Retry/timeout policy for the off-chain Hermes / Lazer update fetches (see
+     * `fetchWithPolicy`). Optional — defaults to 15s timeout, 2 retries.
+     */
+    pythFetch?: PythFetchPolicy;
 }
 export declare class PerpClient extends BaseLineClient<WaterXConfig> {
-    /** Pyth infra (network defaults unless overridden in JSON). */
+    /** Pyth Core infra (fixed per network) plus the caller-supplied credential/policy. */
     pyth: PythInfraConfig;
     /** Wormhole infra for the credit bridge (network defaults unless overridden). */
     wormhole: WormholeInfraConfig;
+    /** Selected oracle price-update source (`oracleSource` create option; default `'pyth_rule'`). */
+    readonly oracleSource: OracleSource;
     /** Canonical-schema lookups (delegated to below); no transport. */
     private readonly view;
-    constructor(network: Network, config: WaterXConfig, opts?: {
-        grpcUrl?: string;
-    });
+    constructor(network: Network, config: WaterXConfig, opts?: CreateClientOptions);
     /**
      * Async factory: fetches the deployment config for `network` and returns
      * a ready-to-use client. Pass `opts.cache=true` to memoize the JSON.
+     *
+     * No oracle-config guard here: selecting a source whose feeds are absent is
+     * not an error at init — it surfaces at tx-build time for the specific
+     * tickers that source can't serve (see `refreshOraclePrices`).
      */
     static create(network: Network, opts?: CreateClientOptions): Promise<PerpClient>;
     static mainnet(opts?: CreateClientOptions): Promise<PerpClient>;

package/dist/src/perp/client.js

@@ -14,25 +14,40 @@ import { BaseLineClient } from "../base-client.js";
 import { PerpConfigView } from "./config-view.js";
 import { loadConfig, PYTH_DEFAULTS, WORMHOLE_DEFAULTS, } from "./config.js";
 export class PerpClient extends BaseLineClient {
-    /** Pyth infra (network defaults unless overridden in JSON). */
+    /** Pyth Core infra (fixed per network) plus the caller-supplied credential/policy. */
     pyth;
     /** Wormhole infra for the credit bridge (network defaults unless overridden). */
     wormhole;
+    /** Selected oracle price-update source (`oracleSource` create option; default `'pyth_rule'`). */
+    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];
+        // Pyth Core infra is fixed per network — NOT deployment-overridable and
+        // NOT source-dependent (the pyth_lazer_rule source reads only api_key/fetch
+        // from here). The api_key + fetch policy are caller-supplied at init: a
+        // secret has no place in the canonical waterx-config JSON.
+        this.pyth = {
+            ...PYTH_DEFAULTS[network],
+            ...(opts.pythApiKey !== undefined ? { api_key: opts.pythApiKey } : {}),
+            ...(opts.pythFetch !== undefined ? { fetch: opts.pythFetch } : {}),
+        };
         this.wormhole = config.wormhole ?? WORMHOLE_DEFAULTS[network];
+        this.oracleSource = opts.oracleSource ?? "pyth_rule";
         this.view = new PerpConfigView(() => this.config, () => this.wormhole);
     }
     /**
      * Async factory: fetches the deployment config for `network` and returns
      * a ready-to-use client. Pass `opts.cache=true` to memoize the JSON.
+     *
+     * No oracle-config guard here: selecting a source whose feeds are absent is
+     * not an error at init — it surfaces at tx-build time for the specific
+     * tickers that source can't serve (see `refreshOraclePrices`).
      */
     static async create(network, opts = {}) {
         const config = await loadConfig(network, opts);
-        return new PerpClient(network, config, { grpcUrl: opts.grpcUrl });
+        return new PerpClient(network, config, opts);
     }
     static mainnet(opts = {}) {
         return PerpClient.create("MAINNET", opts);

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

@@ -9,10 +9,10 @@
  * below, keyed by network.
  */
 import type { AccountPackages, BasePackageEntry, WormholeInfraConfig } from "../account/config.ts";
-import type { OraclePackages, PythInfraConfig } from "../oracle/config.ts";
+import type { OraclePackages } 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 type { AccountConfig, AccountPackages, BasePackageEntry, NativeCustodyAsset, NativeCustodyPackage, WaterxCreditPackage, WaterxReferralPackage, WithdrawalQueuePackage, WormholeBridgePackage, WormholeInfraConfig, WxaAccountPackage, } from "../account/config.ts";
+export type { ConstantFeedEntry, OracleConfig, OraclePackages, PythFetchPolicy, PythInfraConfig, PythLazerRulePackage, PythRulePackage, PythSponsorRulePackage, SupraFeedEntry, SupraRulePackage, WaterxConstantRulePackage, WaterxOraclePackage, } from "../oracle/config.ts";
 export { PYTH_DEFAULTS } from "../oracle/config.ts";
 export interface WaterxPerpMarketEntry {
     market: string;
@@ -82,8 +82,6 @@ export interface WaterXConfig {
     /** Sui gRPC base URL (default: public Mysten fullnode for the network). */
     grpcUrl?: string;
     packages: WaterXPackages;
-    /** Pyth infra override (defaults from `PYTH_DEFAULTS[network]`). */
-    pyth?: PythInfraConfig;
     /** Wormhole infra override (defaults from `WORMHOLE_DEFAULTS[network]`). */
     wormhole?: WormholeInfraConfig;
     /** Sui `CoinRegistry` shared object (credit deployments). */
@@ -104,12 +102,17 @@ export interface LoadConfigOptions {
     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;
 }
 export declare function clearConfigCache(): void;

package/dist/src/perp/config.js

@@ -8,6 +8,7 @@
  * **not** in the JSON — it lives in `PYTH_DEFAULTS` / `WORMHOLE_DEFAULTS`
  * below, keyed by network.
  */
+import { fetchWithPolicy, rethrowExhaustedFetch } from "../oracle/update-fetch.js";
 export { PYTH_DEFAULTS } from "../oracle/config.js";
 // ============================================================================
 // Wormhole / Hermes — external chain infra, defaults by network
@@ -33,38 +34,94 @@ export const WORMHOLE_DEFAULTS = {
         wormholescan_api: "https://api.testnet.wormholescan.io/api/v1",
     },
 };
-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.waterxConfigUrl;
     if (!url) {
         throw new Error("loadConfig: no config URL — pass opts.waterxConfigUrl");
     }
-    if (opts.cache && cache.has(url)) {
-        return cache.get(url);
+    // 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;
+        // Reframe a status-carrying FetchPolicyError into this function's own
+        // message shape, mirroring the non-retried `!response.ok` throw above and
+        // carrying the URL (the key datum for a config-fetch failure). A
+        // network-level exhaustion (no status), a `!response.ok` throw, or a JSON
+        // parse / `validateConfig` failure has no reframing to add — the helper
+        // propagates those verbatim.
+        rethrowExhaustedFetch(err, (e) => `loadConfig: HTTP ${e.status} fetching ${url}`);
     }
-    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) {
@@ -82,6 +139,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, 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 type { BasePackageEntry, ConstantFeedEntry, WaterxReferralPackage, LoadConfigOptions, NativeCustodyAsset, NativeCustodyPackage, PythFetchPolicy, PythInfraConfig, PythLazerRulePackage, PythRulePackage, PythSponsorRulePackage, SupraFeedEntry, SupraRulePackage, TestnetFaucetPackage, 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

@@ -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) ========