@waterx/sdk 3.1.0 → 4.0.0

package/dist/cjs/src/oracle/rules/pyth-lazer-rule.js

@@ -0,0 +1,194 @@
+"use strict";
+/**
+ * `PythLazerRule` — `PriceUpdateRule` for Pyth Lazer (Pyth Pro) signed
+ * updates, plus `feedLazerRule`, the collector-feed leg `aggregateTicker`
+ * appends per lazer-routed ticker. Fetches one `leEcdsa` payload for all
+ * requested integer feed ids from the Lazer HTTP API (Bearer-authenticated
+ * via `config.pyth.api_key`), verifies it ONCE on-chain via
+ * `pyth_lazer::parse_and_verify_le_ecdsa_update`, and hands the resulting
+ * `Update` PTB value back through a `RuleUpdateHandle` for the feed calls.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PythLazerRule = exports.LazerApiKeyMissingError = void 0;
+exports.feedLazerRule = feedLazerRule;
+const bcs_1 = require("@mysten/bcs");
+const config_ts_1 = require("../config.js");
+const price_update_rule_ts_1 = require("../price-update-rule.js");
+const update_fetch_ts_1 = require("../update-fetch.js");
+/**
+ * Signed-update request pins, mirroring what the on-chain rule consumes:
+ * - `properties` — `price` + `exponent` are REQUIRED by
+ *   `pyth_lazer_rule::price_or_abstain` (a missing exponent abstains);
+ *   `confidence` is optional on-chain but requested so the rule's
+ *   fail-closed confidence gate actually engages (a payload without
+ *   confidence passes the gate unchecked).
+ * - `channel` — `real_time`: the deployed rule binds the v1 Lazer API, whose
+ *   `channel::from_u8` aborts on the 1000ms fixed-rate channel; real_time /
+ *   50ms / 200ms are the safe subscriptions, and for an on-demand pull
+ *   real_time is the freshest.
+ * - `formats: leEcdsa` + `jsonBinaryEncoding: hex` — the Sui verifier takes
+ *   the `leEcdsa` framing; hex matches `fromHex` below.
+ */
+const LAZER_LATEST_PRICE_REQUEST = {
+    properties: ["price", "exponent", "confidence"],
+    formats: ["leEcdsa"],
+    jsonBinaryEncoding: "hex",
+    channel: "real_time",
+};
+/**
+ * Shape check ONLY — the `kind` discriminant is checked separately by the
+ * caller before this runs (mirrors `PythCoreRule`'s guard split), so a
+ * same-shaped payload from a different rule can never silently pass.
+ */
+function isPythLazerUpdatePayloadShape(payload) {
+    return (typeof payload === "object" &&
+        payload !== null &&
+        payload.update instanceof Uint8Array &&
+        Array.isArray(payload.feedIds));
+}
+/**
+ * Thrown by {@link PythLazerRule.fetchUpdateData} when `pyth_lazer_rule` is
+ * deployed in config but no `pyth.api_key` is set — the Lazer HTTP API
+ * requires a Bearer token and the SDK never reads `process.env` to find one.
+ * `instanceof`-able (mirrors `OracleFeeSourceUnavailableError` in `pyth.ts`)
+ * so a consumer can branch on the failure type directly instead of
+ * string-matching `error.message`.
+ */
+class LazerApiKeyMissingError extends Error {
+    constructor() {
+        super("LazerApiKeyMissing: pyth_lazer_rule requires a Pyth Lazer access token — " +
+            "set `pyth.api_key` in the client config (the SDK never reads process.env)");
+        this.name = "LazerApiKeyMissingError";
+    }
+}
+exports.LazerApiKeyMissingError = LazerApiKeyMissingError;
+/** The `pyth_lazer_rule` deployment entry; throws when the config carries none. */
+function requireLazerPackage(host) {
+    const entry = host.config.packages.pyth_lazer_rule;
+    if (!entry) {
+        throw new Error("pyth_lazer_rule package is not deployed in this config");
+    }
+    return entry;
+}
+/**
+ * Fetch one signed `leEcdsa` update for `feedIds` from the Lazer HTTP API.
+ * Goes through the shared `fetchWithPolicy` (`../update-fetch.ts`) — same
+ * retry/timeout/Bearer policy as `fetchPriceFeedsUpdateData`, unified so
+ * both oracle sources fail the same way under upstream degradation.
+ */
+async function fetchLazerSignedUpdate(endpoint, apiKey, feedIds, fetchOpts) {
+    const url = new URL("/v1/latest_price", endpoint);
+    let res;
+    try {
+        res = await (0, update_fetch_ts_1.fetchWithPolicy)(url.toString(), {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ priceFeedIds: feedIds, ...LAZER_LATEST_PRICE_REQUEST }),
+        }, { apiKey, ...fetchOpts });
+    }
+    catch (err) {
+        // Mirrors fetchPriceFeedsUpdateData's reframing: a retryable status that
+        // never recovered carries `status` on the FetchPolicyError — reformat
+        // into this function's own message shape; a network-level exhaustion
+        // (no status) propagates as-is.
+        if (err instanceof update_fetch_ts_1.FetchPolicyError && err.status !== undefined) {
+            const body = err.bodySnippet ? ` ${err.bodySnippet}` : "";
+            throw new Error(`Lazer price fetch failed: ${err.status}${body} (retries exhausted after ${err.attempts} attempts)`, { cause: err });
+        }
+        throw err;
+    }
+    if (!res.ok)
+        throw new Error(`Lazer price fetch failed: ${res.status} ${await res.text()}`);
+    const json = (await res.json());
+    const hex = json.leEcdsa?.data;
+    if (typeof hex !== "string" || hex.length === 0) {
+        throw new Error("Lazer returned no leEcdsa update data");
+    }
+    return (0, bcs_1.fromHex)(hex);
+}
+/**
+ * `pyth_lazer_rule::feed(collector, config, clock, &update)` — contribute the
+ * verified Lazer price for `collector.symbol()` to the collector. `update` is
+ * the `RuleUpdateHandle` value from {@link PythLazerRule.buildUpdateCalls} in
+ * the SAME PTB; one verified update serves every ticker's feed call. On-chain
+ * the rule abstains (records `none`) instead of aborting when the symbol is
+ * unconfigured, the feed is absent from the update, the value is degenerate,
+ * or the Lazer timestamp is stale.
+ */
+function feedLazerRule(tx, host, collector, update) {
+    const lazer = requireLazerPackage(host);
+    tx.moveCall({
+        target: `${lazer.published_at}::pyth_lazer_rule::feed`,
+        arguments: [collector, tx.object(lazer.config), tx.object.clock(), update],
+    });
+}
+exports.PythLazerRule = {
+    kind: "pyth_lazer_rule",
+    // Verification is a flat signature check with no Coin argument — no
+    // update fee — see `PriceUpdateRule.requiresFeeSource`.
+    requiresFeeSource: false,
+    /** Tickers with a `pyth_lazer_rule.feeds` entry (integer Lazer feed ids). */
+    supportedTickers(host) {
+        return Object.keys(host.config.packages.pyth_lazer_rule?.feeds ?? {});
+    },
+    /** Resolves integer feed ids for `tickers`, then fetches one signed `leEcdsa` update. */
+    async fetchUpdateData(host, tickers) {
+        if (tickers.length === 0)
+            return null;
+        // Package-level check first: a config without the deployment must say so,
+        // not fail per ticker as if only that feed were missing.
+        const { feeds } = requireLazerPackage(host);
+        const feedIds = tickers.map((ticker) => {
+            const feedId = feeds[ticker];
+            if (feedId === undefined) {
+                throw new Error(`No pyth_lazer_rule feed listed for ticker: ${ticker}`);
+            }
+            return feedId;
+        });
+        const apiKey = host.pyth.api_key;
+        if (!apiKey) {
+            throw new LazerApiKeyMissingError();
+        }
+        const update = await fetchLazerSignedUpdate(config_ts_1.LAZER_DEFAULTS[host.network].endpoint, apiKey, feedIds, host.pyth.fetch);
+        return { kind: "pyth_lazer_rule", payload: { update, feedIds } };
+    },
+    /**
+     * A Lazer payload is ONE signed `leEcdsa` message covering every feed it was
+     * fetched for — verification is a single flat signature check over the whole
+     * message (`parse_and_verify_le_ecdsa_update`, no per-feed cost), so the
+     * payload is indivisible: it can only be served whole. Returns the whole
+     * payload iff every requested ticker's integer feed id is packed in THIS
+     * payload's `feedIds`; any coverage gap (unlisted ticker, or a feed this
+     * payload does not carry) → `null` (miss), never a silent partial.
+     */
+    narrowUpdateData(host, data, tickers) {
+        const payload = (0, price_update_rule_ts_1.assertRuleUpdateData)(data, "pyth_lazer_rule", isPythLazerUpdatePayloadShape, "{ update: Uint8Array; feedIds: number[] }");
+        if (!payload || tickers.length === 0)
+            return null;
+        const packedFeedIds = new Set(payload.feedIds);
+        for (const ticker of tickers) {
+            const feedId = host.config.packages.pyth_lazer_rule?.feeds?.[ticker];
+            if (feedId === undefined || !packedFeedIds.has(feedId))
+                return null;
+        }
+        return { kind: "pyth_lazer_rule", payload };
+    },
+    /**
+     * Appends the single `parse_and_verify_le_ecdsa_update(state, clock, bytes)`
+     * call — one secp256k1 signature check covering every feed in the payload —
+     * and returns its `Update` result as the handle the per-ticker feed leg
+     * consumes. `opts.cache` / `opts.feeSource` are Pyth-Core-specific and
+     * ignored (Lazer verification charges no update fee).
+     */
+    buildUpdateCalls(tx, host, data, _opts) {
+        const payload = (0, price_update_rule_ts_1.assertRuleUpdateData)(data, "pyth_lazer_rule", isPythLazerUpdatePayloadShape, "{ update: Uint8Array; feedIds: number[] }");
+        if (!payload)
+            return undefined;
+        const lazer = requireLazerPackage(host);
+        const [update] = tx.moveCall({
+            target: `${config_ts_1.LAZER_DEFAULTS[host.network].verifier_package}::pyth_lazer::parse_and_verify_le_ecdsa_update`,
+            arguments: [tx.object(lazer.state), tx.object.clock(), tx.pure.vector("u8", payload.update)],
+        });
+        return { kind: "pyth_lazer_rule", update };
+    },
+};

package/dist/cjs/src/oracle/rules/sponsor.d.ts

@@ -3,17 +3,21 @@
  * attach the `PythSponsorRule` witness to a `TradingRequest`. Required when the
  * market's `request_checklist` contains `PythSponsorRule`.
  *
- * Flow: {@link openPythSponsorFund} opens a `Fund` hot potato; pass the returned
- * `{ fund, packageId }` to the Pyth update path as its `sponsorFund` (it draws
- * per-feed fees via `pyth_sponsor_rule::split`); then {@link reimbursePythSponsor}
- * consumes the `Fund`, returns leftover SUI, and attaches the witness.
+ * Flow: {@link openPythSponsorFund} opens a `Fund` hot potato; the caller wraps
+ * the returned `{ fund, packageId }` into an `OracleFeeSource` (`{ kind:
+ * 'sponsor', fund, packageId }`) and passes that to the Pyth update path (it
+ * draws per-feed fees via `pyth_sponsor_rule::split`); then
+ * {@link reimbursePythSponsor} consumes the `Fund`, returns leftover SUI, and
+ * attaches the witness.
  */
 import type { Transaction, TransactionArgument } from "@mysten/sui/transactions";
 import type { OracleHost } from "../host.ts";
 /**
- * Opens a `Fund` hot potato from the shared PythSponsor pool. Pass the returned
- * `{ fund, packageId }` straight to `refreshOraclePrices` as `sponsorFund`, then
- * {@link reimbursePythSponsor} once the TradingRequest is built.
+ * Opens a `Fund` hot potato from the shared PythSponsor pool. Wrap the
+ * returned `{ fund, packageId }` into an `OracleFeeSource`
+ * (`{ kind: 'sponsor', fund, packageId }`) and pass that to
+ * `refreshOraclePrices` as `feeSource`, then {@link reimbursePythSponsor} once
+ * the TradingRequest is built.
  */
 export declare function openPythSponsorFund(tx: Transaction, host: OracleHost): {
     fund: TransactionArgument;

package/dist/cjs/src/oracle/rules/sponsor.js

@@ -4,19 +4,23 @@
  * attach the `PythSponsorRule` witness to a `TradingRequest`. Required when the
  * market's `request_checklist` contains `PythSponsorRule`.
  *
- * Flow: {@link openPythSponsorFund} opens a `Fund` hot potato; pass the returned
- * `{ fund, packageId }` to the Pyth update path as its `sponsorFund` (it draws
- * per-feed fees via `pyth_sponsor_rule::split`); then {@link reimbursePythSponsor}
- * consumes the `Fund`, returns leftover SUI, and attaches the witness.
+ * Flow: {@link openPythSponsorFund} opens a `Fund` hot potato; the caller wraps
+ * the returned `{ fund, packageId }` into an `OracleFeeSource` (`{ kind:
+ * 'sponsor', fund, packageId }`) and passes that to the Pyth update path (it
+ * draws per-feed fees via `pyth_sponsor_rule::split`); then
+ * {@link reimbursePythSponsor} consumes the `Fund`, returns leftover SUI, and
+ * attaches the witness.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.openPythSponsorFund = openPythSponsorFund;
 exports.reimbursePythSponsor = reimbursePythSponsor;
 const pyth_sponsor_rule_ts_1 = require("../../generated/pyth_sponsor_rule/pyth_sponsor_rule.js");
 /**
- * Opens a `Fund` hot potato from the shared PythSponsor pool. Pass the returned
- * `{ fund, packageId }` straight to `refreshOraclePrices` as `sponsorFund`, then
- * {@link reimbursePythSponsor} once the TradingRequest is built.
+ * Opens a `Fund` hot potato from the shared PythSponsor pool. Wrap the
+ * returned `{ fund, packageId }` into an `OracleFeeSource`
+ * (`{ kind: 'sponsor', fund, packageId }`) and pass that to
+ * `refreshOraclePrices` as `feeSource`, then {@link reimbursePythSponsor} once
+ * the TradingRequest is built.
  */
 function openPythSponsorFund(tx, host) {
     const entry = host.config.packages.pyth_sponsor_rule;

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);