@waterx/sdk 3.1.1 → 4.0.0

package/dist/cjs/src/oracle/update-fetch.d.ts

@@ -0,0 +1,85 @@
+/**
+ * `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}`.
+ */
+export interface FetchPolicy {
+    /** Per-attempt timeout (ms). Default 15_000. */
+    readonly timeoutMs?: number;
+    /** Retry attempts AFTER the first try — `retries: 2` ⇒ 3 attempts total. Default 2. */
+    readonly retries?: number;
+    /** Base backoff (ms); doubled per attempt, capped at 2_000ms. Default 250. */
+    readonly retryDelayMs?: number;
+    /** Bearer token. Attached iff non-empty; empty/missing ⇒ no `Authorization` header. */
+    readonly apiKey?: string;
+    /** Override the fetch implementation (tests / non-global-`fetch` environments). Default: global `fetch`. */
+    readonly fetchImpl?: typeof fetch;
+}
+/** Thrown by {@link fetchWithPolicy} when every attempt failed. */
+export declare class FetchPolicyError extends Error {
+    /** HTTP status of the final attempt, when it got a (retryable-but-failing) response. */
+    readonly status?: number;
+    /** Truncated (~200 char) body of the final attempt's response, when one was readable. */
+    readonly bodySnippet?: string;
+    /** Total attempts made (first try + retries actually used). */
+    readonly attempts: number;
+    constructor(message: string, opts: {
+        status?: number;
+        bodySnippet?: string;
+        cause?: unknown;
+        attempts: number;
+    });
+}
+/**
+ * `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 declare function fetchWithPolicy(url: string, init?: RequestInit, policy?: FetchPolicy, externalSignal?: AbortSignal): Promise<Response>;

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

@@ -0,0 +1,228 @@
+"use strict";
+/**
+ * `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}`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FetchPolicyError = void 0;
+exports.fetchWithPolicy = fetchWithPolicy;
+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. */
+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;
+    }
+}
+exports.FetchPolicyError = FetchPolicyError;
+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.
+ */
+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/cjs/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/cjs/src/perp/client.js

@@ -21,12 +21,17 @@ class PerpClient extends base_client_ts_1.BaseLineClient {
     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 ?? config_ts_1.PYTH_DEFAULTS[network];
+        // Precedence: explicit config.pyth override > generation constants.
+        this.pyth =
+            config.pyth ?? (opts.pythGeneration === "pro" ? config_ts_1.PYTH_PRO_DEFAULTS : config_ts_1.PYTH_DEFAULTS)[network];
         this.wormhole = config.wormhole ?? config_ts_1.WORMHOLE_DEFAULTS[network];
+        this.oracleSource = opts.oracleSource ?? "pyth_rule";
         this.view = new config_view_ts_1.PerpConfigView(() => this.config, () => this.wormhole);
     }
     /**
@@ -35,7 +40,11 @@ class PerpClient extends base_client_ts_1.BaseLineClient {
      */
     static async create(network, opts = {}) {
         const config = await (0, config_ts_1.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/cjs/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;
@@ -104,12 +104,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/cjs/src/perp/config.js

@@ -10,11 +10,13 @@
  * below, keyed by network.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WORMHOLE_DEFAULTS = exports.PYTH_DEFAULTS = void 0;
+exports.WORMHOLE_DEFAULTS = exports.PYTH_PRO_DEFAULTS = exports.PYTH_DEFAULTS = void 0;
 exports.clearConfigCache = clearConfigCache;
 exports.loadConfig = loadConfig;
+const update_fetch_ts_1 = require("../oracle/update-fetch.js");
 var config_ts_1 = require("../oracle/config.js");
 Object.defineProperty(exports, "PYTH_DEFAULTS", { enumerable: true, get: function () { return config_ts_1.PYTH_DEFAULTS; } });
+Object.defineProperty(exports, "PYTH_PRO_DEFAULTS", { enumerable: true, get: function () { return config_ts_1.PYTH_PRO_DEFAULTS; } });
 // ============================================================================
 // Wormhole / Hermes — external chain infra, defaults by network
 // ============================================================================
@@ -39,38 +41,97 @@ exports.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();
 function clearConfigCache() {
-    cache.clear();
+    configCache.clear();
 }
 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 (0, update_fetch_ts_1.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 update_fetch_ts_1.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) {
@@ -88,6 +149,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/cjs/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 { 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/cjs/src/perp/index.js

@@ -36,14 +36,15 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TOKEN_DECIMALS = exports.COLLATERAL_DECIMALS = exports.WLP_DECIMALS = exports.SUI_DECIMALS = exports.MS_PER_YEAR = exports.STOCK_FEE_RATE = exports.STAKING_PERM_ALL = exports.STAKING_PERM_CLAIM_REWARD = exports.STAKING_PERM_REDEEM_STAKE = exports.STAKING_PERM_DEPOSIT_STAKE = exports.PERM_WITHDRAW_COLLATERAL = exports.PERM_REDEEM_WLP = exports.PERM_PLACE_ORDER = exports.PERM_OPEN_POSITION = exports.PERM_MINT_WLP = exports.PERM_INCREASE_POSITION = exports.PERM_DEPOSIT_COLLATERAL = exports.PERM_DECREASE_POSITION = exports.PERM_CLOSE_POSITION = exports.PERM_CANCEL_ORDER = exports.PERM_ALL_TRADING = exports.PERM_ALL = exports.ORDER_TAG_WILDCARD = exports.ORDER_STOP_SELL = exports.ORDER_STOP_BUY = exports.ORDER_LIMIT_SELL = exports.ORDER_LIMIT_BUY = exports.MAINTENANCE_MARGIN_RATE = exports.FLOAT_SCALE = exports.DRY_RUN_SENDER = exports.DOUBLE_SCALE = exports.CRYPTO_FEE_RATE = exports.BPS_SCALE = exports.ACTION_WITHDRAW_COLLATERAL = exports.ACTION_UPDATE_ORDER = exports.ACTION_PLACE_ORDER = exports.ACTION_OPEN_POSITION = exports.ACTION_LIQUIDATE = exports.ACTION_INCREASE_POSITION = exports.ACTION_DEPOSIT_COLLATERAL = exports.ACTION_DECREASE_POSITION = exports.ACTION_CLOSE_POSITION = exports.ACTION_CANCEL_PRE_ORDER = exports.ACTION_CANCEL_ORDER = exports.ACTION_ADD_PRE_ORDER = exports.loadConfig = exports.clearConfigCache = exports.WORMHOLE_DEFAULTS = exports.PYTH_DEFAULTS = exports.PerpClient = void 0;
-exports.PositionDataBcs = exports.PoolDataBcs = exports.OrderDataBcs = exports.MarketDataBcs = exports.GlobalConfigDataBcs = exports.AccountDataBcs = exports.waitForVaa = exports.vaaBytesToBase64 = exports.vaaBase64ToHex = exports.vaaBase64ToBytes = exports.toWormholescanEmitter = exports.padEvmEmitter = exports.listVaasByEmitter = exports.listBridgeWithdrawalVaas = exports.fetchVaa = exports.fetchDepositVaa = exports.updatePythPrices = exports.refreshOraclePrices = exports.fetchPriceFeedsUpdateData = exports.buildPythPriceUpdateCalls = exports.aggregateTickerWithPyth = exports.aggregateTickerWithConstant = exports.aggregateTicker = exports.PythCache = exports.rawPrice = exports.decodeFundingIndexDelta = exports.calcWlpRedeemOut = exports.calcWlpPrice = exports.calcWlpMintOut = exports.calcWlpIncentiveApy = exports.calcUnrealizedPnl = exports.calcTotalTradingFeeRate = exports.calcTokenUtilizationBps = exports.calcPositionBorrowFee = exports.calcNotional = exports.calcMaxReducibleCollateralUsd = exports.calcLeverage = exports.calcImpactFeeRate = exports.calcFundingRate = exports.calcFundingFeeUsd = exports.calcFee = exports.calcEstLiqPrice = exports.calcEffectiveCollateralUsd = exports.calcDynamicFeeBps = exports.calcBorrowRateAccrual = exports.calcBorrowRate = exports.annualizeFundingRate = exports.annualizedApyFromRatio = exports.getCollateralAssets = exports.getMarketTickers = void 0;
-exports.withdrawalQueueCalls = exports.nativeCustodyCalls = exports.referralCalls = exports.pythSponsorRuleCalls = exports.pythRuleCalls = exports.oracleCalls = exports.stakingCalls = exports.wxaAccountCalls = exports.viewCalls = exports.lpPoolCalls = exports.tradingCalls = exports.MarketConfigBcs = exports.MarketBcs = exports.OrderBcs = exports.PositionBcs = exports.TokenPoolDataBcs = exports.RedeemRequestDataBcs = void 0;
+exports.COLLATERAL_DECIMALS = exports.WLP_DECIMALS = exports.SUI_DECIMALS = exports.MS_PER_YEAR = exports.STOCK_FEE_RATE = exports.STAKING_PERM_ALL = exports.STAKING_PERM_CLAIM_REWARD = exports.STAKING_PERM_REDEEM_STAKE = exports.STAKING_PERM_DEPOSIT_STAKE = exports.PERM_WITHDRAW_COLLATERAL = exports.PERM_REDEEM_WLP = exports.PERM_PLACE_ORDER = exports.PERM_OPEN_POSITION = exports.PERM_MINT_WLP = exports.PERM_INCREASE_POSITION = exports.PERM_DEPOSIT_COLLATERAL = exports.PERM_DECREASE_POSITION = exports.PERM_CLOSE_POSITION = exports.PERM_CANCEL_ORDER = exports.PERM_ALL_TRADING = exports.PERM_ALL = exports.ORDER_TAG_WILDCARD = exports.ORDER_STOP_SELL = exports.ORDER_STOP_BUY = exports.ORDER_LIMIT_SELL = exports.ORDER_LIMIT_BUY = exports.MAINTENANCE_MARGIN_RATE = exports.FLOAT_SCALE = exports.DRY_RUN_SENDER = exports.DOUBLE_SCALE = exports.CRYPTO_FEE_RATE = exports.BPS_SCALE = exports.ACTION_WITHDRAW_COLLATERAL = exports.ACTION_UPDATE_ORDER = exports.ACTION_PLACE_ORDER = exports.ACTION_OPEN_POSITION = exports.ACTION_LIQUIDATE = exports.ACTION_INCREASE_POSITION = exports.ACTION_DEPOSIT_COLLATERAL = exports.ACTION_DECREASE_POSITION = exports.ACTION_CLOSE_POSITION = exports.ACTION_CANCEL_PRE_ORDER = exports.ACTION_CANCEL_ORDER = exports.ACTION_ADD_PRE_ORDER = exports.loadConfig = exports.clearConfigCache = exports.WORMHOLE_DEFAULTS = exports.PYTH_PRO_DEFAULTS = exports.PYTH_DEFAULTS = exports.PerpClient = void 0;
+exports.AccountDataBcs = exports.waitForVaa = exports.vaaBytesToBase64 = exports.vaaBase64ToHex = exports.vaaBase64ToBytes = exports.toWormholescanEmitter = exports.padEvmEmitter = exports.listVaasByEmitter = exports.listBridgeWithdrawalVaas = exports.fetchVaa = exports.fetchDepositVaa = exports.updatePythPrices = exports.refreshOraclePrices = exports.fetchPriceFeedsUpdateData = exports.buildPythPriceUpdateCalls = exports.aggregateTickerWithPyth = exports.aggregateTickerWithConstant = exports.aggregateTicker = exports.PythCache = exports.OracleSourceNotImplementedError = exports.OracleFeeSourceUnavailableError = exports.LazerApiKeyMissingError = exports.FetchPolicyError = exports.rawPrice = exports.decodeFundingIndexDelta = exports.calcWlpRedeemOut = exports.calcWlpPrice = exports.calcWlpMintOut = exports.calcWlpIncentiveApy = exports.calcUnrealizedPnl = exports.calcTotalTradingFeeRate = exports.calcTokenUtilizationBps = exports.calcPositionBorrowFee = exports.calcNotional = exports.calcMaxReducibleCollateralUsd = exports.calcLeverage = exports.calcImpactFeeRate = exports.calcFundingRate = exports.calcFundingFeeUsd = exports.calcFee = exports.calcEstLiqPrice = exports.calcEffectiveCollateralUsd = exports.calcDynamicFeeBps = exports.calcBorrowRateAccrual = exports.calcBorrowRate = exports.annualizeFundingRate = exports.annualizedApyFromRatio = exports.getCollateralAssets = exports.getMarketTickers = exports.TOKEN_DECIMALS = void 0;
+exports.withdrawalQueueCalls = exports.nativeCustodyCalls = exports.referralCalls = exports.pythSponsorRuleCalls = exports.pythRuleCalls = exports.oracleCalls = exports.stakingCalls = exports.wxaAccountCalls = exports.viewCalls = exports.lpPoolCalls = exports.tradingCalls = exports.MarketConfigBcs = exports.MarketBcs = exports.OrderBcs = exports.PositionBcs = exports.TokenPoolDataBcs = exports.RedeemRequestDataBcs = exports.PositionDataBcs = exports.PoolDataBcs = exports.OrderDataBcs = exports.MarketDataBcs = exports.GlobalConfigDataBcs = void 0;
 // ======== Core ========
 var client_ts_1 = require("./client.js");
 Object.defineProperty(exports, "PerpClient", { enumerable: true, get: function () { return client_ts_1.PerpClient; } });
 var config_ts_1 = require("./config.js");
 Object.defineProperty(exports, "PYTH_DEFAULTS", { enumerable: true, get: function () { return config_ts_1.PYTH_DEFAULTS; } });
+Object.defineProperty(exports, "PYTH_PRO_DEFAULTS", { enumerable: true, get: function () { return config_ts_1.PYTH_PRO_DEFAULTS; } });
 Object.defineProperty(exports, "WORMHOLE_DEFAULTS", { enumerable: true, get: function () { return config_ts_1.WORMHOLE_DEFAULTS; } });
 Object.defineProperty(exports, "clearConfigCache", { enumerable: true, get: function () { return config_ts_1.clearConfigCache; } });
 Object.defineProperty(exports, "loadConfig", { enumerable: true, get: function () { return config_ts_1.loadConfig; } });
@@ -131,6 +132,10 @@ __exportStar(require("./tx-builders.js"), exports);
 __exportStar(require("./fetch.js"), exports);
 // ======== Oracle utilities (Pyth source + rule aggregation) ========
 var index_ts_1 = require("../oracle/index.js");
+Object.defineProperty(exports, "FetchPolicyError", { enumerable: true, get: function () { return index_ts_1.FetchPolicyError; } });
+Object.defineProperty(exports, "LazerApiKeyMissingError", { enumerable: true, get: function () { return index_ts_1.LazerApiKeyMissingError; } });
+Object.defineProperty(exports, "OracleFeeSourceUnavailableError", { enumerable: true, get: function () { return index_ts_1.OracleFeeSourceUnavailableError; } });
+Object.defineProperty(exports, "OracleSourceNotImplementedError", { enumerable: true, get: function () { return index_ts_1.OracleSourceNotImplementedError; } });
 Object.defineProperty(exports, "PythCache", { enumerable: true, get: function () { return index_ts_1.PythCache; } });
 Object.defineProperty(exports, "aggregateTicker", { enumerable: true, get: function () { return index_ts_1.aggregateTicker; } });
 Object.defineProperty(exports, "aggregateTickerWithConstant", { enumerable: true, get: function () { return index_ts_1.aggregateTickerWithConstant; } });