@waterx/sdk 3.1.1 → 4.0.1

package/dist/src/perp/tx-builders/common.d.ts

@@ -4,7 +4,7 @@
  * and the request+execute envelope (optional Pyth-sponsor flow + pre-sweep).
  */
 import { Transaction, type TransactionArgument } from "@mysten/sui/transactions";
-import { PythCache } from "../../oracle/index.ts";
+import { PythCache, type OracleFeeSource, type UpdateDataProvider } from "../../oracle/index.ts";
 import type { PerpClient } from "../client.ts";
 export interface CommonBuildOpts {
     /** Append to an existing PTB instead of creating a new one. */
@@ -14,16 +14,31 @@ export interface CommonBuildOpts {
     /** Share a `PythCache` across builders to avoid redundant pyth_state reads. */
     pythCache?: PythCache;
     /**
-     * Wire the `pyth_sponsor_rule` flow:
-     *   - open a Fund via `pyth_sponsor_rule::request(sponsor)`
-     *   - pay Pyth update fees from the Fund (instead of `tx.gas`)
-     *   - reimburse leftover into the sponsor pool + attach
-     *     `PythSponsorRule` witness to the TradingRequest so markets
-     *     whose `request_checklist` contains `PythSponsorRule` accept it
-     * Default: true (matches the testnet/mainnet checklist config).
-     * Pass `false` only when the market checklist is empty.
+     * @deprecated No longer a fee-source decision. `wrapRequestAndExecute` now
+     * opens (and reimburses) the `pyth_sponsor_rule` Fund purely from config
+     * presence — whenever `client.config.packages.pyth_sponsor_rule` is
+     * deployed, the fund is ALWAYS opened, regardless of this flag (see
+     * `OracleFeeSourceUnavailable` in `oracle/pyth.ts`). This closes the gap
+     * where a market whose checklist required `PythSponsorRule`, or a caller
+     * that mis-set this flag, silently drew from `tx.gas` and failed
+     * ON-CHAIN instead of at build time. Use `allowGasFee` for the
+     * non-sponsored case instead. Kept accepted (as a no-op) only so existing
+     * callers keep compiling; will be removed in a future major version.
      */
     useSponsor?: boolean;
+    /**
+     * Explicit opt-in to draw the Pyth update fee from `tx.gas` when this
+     * client's config has no `pyth_sponsor_rule` deployed. Ignored whenever a
+     * sponsor fund IS available — the sponsor pool always wins over `tx.gas`
+     * when one can be opened (see `useSponsor`'s deprecation note above).
+     * Required for flows with no `TradingRequest` to reimburse a sponsor fund
+     * against (e.g. `buildMintWlpTx` — see its doc comment). Building an
+     * oracle refresh with neither a sponsor fund nor this flag throws
+     * `OracleFeeSourceUnavailable` instead of silently drawing from `tx.gas`
+     * (Enoki-sponsored transactions reject any `tx.gas` draw). Default:
+     * `false`.
+     */
+    allowGasFee?: boolean;
     /**
      * Pre-sweep parked backing assets (USDC, USDsui, …) at the wxa account's
      * address into USD credit, plus any CREDIT coins/funds at the address into
@@ -42,6 +57,15 @@ export interface CommonBuildOpts {
      * {@link buildConsolidateToUsdTx} separately.
      */
     consolidateToUsd?: boolean;
+    /**
+     * BE prefetch-cache seam for the oracle update-data fetch — forwarded
+     * verbatim into `refreshOraclePrices`'s `updateDataProvider` opt (see
+     * `UpdateDataProvider` in `oracle/price-update-rule.ts`). Default: none
+     * (always a live fetch). A caller-supplied provider that misses or throws
+     * still falls back to a live fetch — this option can only make a refresh
+     * faster, never break it.
+     */
+    updateDataProvider?: UpdateDataProvider;
 }
 interface RequestParams {
     ticker: string;
@@ -57,20 +81,33 @@ export declare function newTx(opts?: CommonBuildOpts): Transaction;
  */
 export declare function refreshWlpPoolOracles(tx: Transaction, client: PerpClient, extraTickers: string[], opts: {
     cache?: PythCache;
-    sponsorFund?: {
-        fund: TransactionArgument;
-        packageId: string;
-    };
+    /** Forwarded to `refreshOraclePrices` — already resolved by the caller (see `OracleFeeSource`). */
+    feeSource?: OracleFeeSource;
     lpType?: string;
+    updateDataProvider?: UpdateDataProvider;
 }): Promise<void>;
 /**
- * Build the *Request + execute envelope with optional Pyth sponsor flow:
+ * Build the *Request + execute envelope with the config-driven Pyth sponsor flow:
  *
+ *   [maybeConsolidate(tx)]
  *   [fund = sponsor.request()]
- *   refreshOraclePrices(..., sponsorFund?)
+ *   refreshOraclePrices(..., feeSource?)
  *   req = buildRequest()
  *   [sponsor.reimburse(fund, req)]
  *   trading::execute(req)
+ *
+ * Accepted ordering caveat: `maybeConsolidate` runs FIRST and can itself
+ * append PTB commands (the consolidation sweep) before the fee-source check
+ * inside `refreshOraclePrices` ever runs — so an `OracleFeeSourceUnavailable`
+ * throw here is NOT the "zero commands appended" guarantee
+ * `refreshOraclePrices` gives its own callers (see its docblock in
+ * `aggregate.ts`); `tx` can already carry the sweep. This is the same
+ * discard-tx-on-throw contract every `build*Tx` composer already has for
+ * mid-build on-chain-read failures — not a new hole. It matters only for a
+ * caller that passed in their OWN `opts.tx` (reusing one `Transaction`
+ * across builder calls, e.g. to compose several actions in one PTB); such a
+ * caller must discard the whole `tx` on any throw from this function, not
+ * just retry the failed step.
  */
 export declare function wrapRequestAndExecute(client: PerpClient, tx: Transaction, req: RequestParams & {
     accountId: string;

package/dist/src/perp/tx-builders/common.js

@@ -23,32 +23,65 @@ export async function refreshWlpPoolOracles(tx, client, extraTickers, opts) {
     const oracleTickers = Array.from(new Set([...extraTickers, ...poolTickers]));
     await refreshOraclePrices(tx, client, oracleTickers, {
         cache: opts.cache,
-        sponsorFund: opts.sponsorFund,
+        feeSource: opts.feeSource,
+        updateDataProvider: opts.updateDataProvider,
     });
     for (const tokenType of Object.values(client.config.packages.wlp.pool_tokens)) {
         updateTokenValue(client, tx, { tokenType, lpType: opts.lpType });
     }
 }
 /**
- * Build the *Request + execute envelope with optional Pyth sponsor flow:
+ * Build the *Request + execute envelope with the config-driven Pyth sponsor flow:
  *
+ *   [maybeConsolidate(tx)]
  *   [fund = sponsor.request()]
- *   refreshOraclePrices(..., sponsorFund?)
+ *   refreshOraclePrices(..., feeSource?)
  *   req = buildRequest()
  *   [sponsor.reimburse(fund, req)]
  *   trading::execute(req)
+ *
+ * Accepted ordering caveat: `maybeConsolidate` runs FIRST and can itself
+ * append PTB commands (the consolidation sweep) before the fee-source check
+ * inside `refreshOraclePrices` ever runs — so an `OracleFeeSourceUnavailable`
+ * throw here is NOT the "zero commands appended" guarantee
+ * `refreshOraclePrices` gives its own callers (see its docblock in
+ * `aggregate.ts`); `tx` can already carry the sweep. This is the same
+ * discard-tx-on-throw contract every `build*Tx` composer already has for
+ * mid-build on-chain-read failures — not a new hole. It matters only for a
+ * caller that passed in their OWN `opts.tx` (reusing one `Transaction`
+ * across builder calls, e.g. to compose several actions in one PTB); such a
+ * caller must discard the whole `tx` on any throw from this function, not
+ * just retry the failed step.
  */
 export async function wrapRequestAndExecute(client, tx, req, collateralTicker, opts, buildRequest) {
     await maybeConsolidate(client, tx, req.accountId, opts);
-    const useSponsor = opts?.useSponsor ?? true;
+    // Fee source + witness attachment is config-driven, not a caller flag: the
+    // sponsor fund is opened (and later reimbursed) whenever this client's
+    // config has `pyth_sponsor_rule` deployed — regardless of the deprecated
+    // `useSponsor` flag (see its JSDoc). `allowGasFee` is the only caller lever
+    // left, and it only matters when config has NO sponsor rule to open (see
+    // `OracleFeeSourceUnavailable` in `oracle/pyth.ts`).
+    //
+    // `feeSource` is resolved HERE, once, from that same decision — sponsor
+    // beats gas structurally because this is the only branch that ever sees
+    // both candidates; everything downstream (`refreshWlpPoolOracles` →
+    // `refreshOraclePrices` → `BuildUpdateOpts` → `PythCoreRule` →
+    // `buildPythPriceUpdateCalls`) just carries the single resolved value.
     let sponsorFund;
-    if (useSponsor)
+    if (client.config.packages.pyth_sponsor_rule) {
         sponsorFund = openPythSponsorFund(tx, client);
+    }
+    const feeSource = sponsorFund
+        ? { kind: "sponsor", ...sponsorFund }
+        : opts?.allowGasFee
+            ? { kind: "gas" }
+            : undefined;
     if (!opts?.skipOraclePriceRefresh) {
         await refreshWlpPoolOracles(tx, client, [req.ticker, collateralTicker], {
             cache: opts?.pythCache,
-            sponsorFund,
+            feeSource,
             lpType: req.lpType,
+            updateDataProvider: opts?.updateDataProvider,
         });
     }
     const tradingReq = buildRequest(sponsorFund);

package/dist/src/perp/tx-builders/wlp.d.ts

@@ -17,9 +17,15 @@ export interface BuildMintWlpParams extends MintWlpParams, CommonBuildOpts {
  * `last_price_refresh_timestamp` so `assert_prices_fresh` inside
  * `mint_wlp` passes.
  *
- * Does NOT use the pyth_sponsor flow — `mint_wlp` produces no
+ * Never uses the pyth_sponsor flow — `mint_wlp` produces no
  * `TradingRequest`, so there's nothing for the sponsor to attach its
- * witness to. Pyth update fees come from `tx.gas`.
+ * witness to, and `pyth_sponsor_rule::reimburse` cannot consume a Fund
+ * without one. So when `skipOraclePriceRefresh` is `false` (the refresh
+ * actually runs), the caller MUST pass `allowGasFee: true` — the Pyth
+ * update fee is drawn from `tx.gas`, which Enoki-sponsored transactions
+ * reject; a sponsored caller should keep `skipOraclePriceRefresh: true`
+ * instead and rely on freshness from other trade traffic (see
+ * `OracleFeeSourceUnavailable` in `oracle/pyth.ts`).
  */
 export declare function buildMintWlpTx(client: PerpClient, params: BuildMintWlpParams): Promise<Transaction>;
 export interface BuildMintAndStakeWlpParams extends BuildMintWlpParams {
@@ -62,7 +68,9 @@ export interface BuildUnstakeAndRequestRedeemWlpParams extends Omit<RequestRedee
  * Refreshes every WLP pool-token oracle by default — `request_redeem` runs
  * `assert_prices_fresh` internally, so a stale oracle would abort the PTB.
  * Pass `skipOraclePriceRefresh: true` only when the caller is composing this
- * into a larger PTB that already pre-pumps prices.
+ * into a larger PTB that already pre-pumps prices. Like `buildMintWlpTx`,
+ * `request_redeem` produces no `TradingRequest`, so a non-skipped refresh
+ * requires `allowGasFee: true` (see `buildMintWlpTx`'s doc comment).
  */
 export declare function buildUnstakeAndRequestRedeemWlpTx(client: PerpClient, params: BuildUnstakeAndRequestRedeemWlpParams): Promise<Transaction>;
 export interface BuildCancelRedeemAndStakeWlpParams extends CancelRedeemWlpParams, CommonBuildOpts {

package/dist/src/perp/tx-builders/wlp.js

@@ -12,17 +12,29 @@ import { maybeConsolidate, newTx, refreshWlpPoolOracles } from "./common.js";
  * `last_price_refresh_timestamp` so `assert_prices_fresh` inside
  * `mint_wlp` passes.
  *
- * Does NOT use the pyth_sponsor flow — `mint_wlp` produces no
+ * Never uses the pyth_sponsor flow — `mint_wlp` produces no
  * `TradingRequest`, so there's nothing for the sponsor to attach its
- * witness to. Pyth update fees come from `tx.gas`.
+ * witness to, and `pyth_sponsor_rule::reimburse` cannot consume a Fund
+ * without one. So when `skipOraclePriceRefresh` is `false` (the refresh
+ * actually runs), the caller MUST pass `allowGasFee: true` — the Pyth
+ * update fee is drawn from `tx.gas`, which Enoki-sponsored transactions
+ * reject; a sponsored caller should keep `skipOraclePriceRefresh: true`
+ * instead and rely on freshness from other trade traffic (see
+ * `OracleFeeSourceUnavailable` in `oracle/pyth.ts`).
  */
 export async function buildMintWlpTx(client, params) {
     const tx = newTx(params);
     await maybeConsolidate(client, tx, params.accountId, params);
+    // `mint_wlp` has no sponsor flow to resolve against (see the doc comment
+    // above) — the only candidate source at this edge is the caller's
+    // ergonomic `allowGasFee` opt-in.
+    const feeSource = params.allowGasFee ? { kind: "gas" } : undefined;
     if (!params.skipOraclePriceRefresh) {
         await refreshWlpPoolOracles(tx, client, [params.depositTicker], {
             cache: params.pythCache,
             lpType: params.lpType,
+            feeSource,
+            updateDataProvider: params.updateDataProvider,
         });
     }
     mintWlp(client, tx, params);
@@ -40,10 +52,16 @@ export async function buildMintWlpTx(client, params) {
 export async function buildMintAndStakeWlpTx(client, params) {
     const tx = newTx(params);
     await maybeConsolidate(client, tx, params.accountId, params);
+    // `mint_wlp` has no sponsor flow to resolve against (see `buildMintWlpTx`'s
+    // doc comment) — the only candidate source at this edge is the caller's
+    // ergonomic `allowGasFee` opt-in.
+    const feeSource = params.allowGasFee ? { kind: "gas" } : undefined;
     if (!params.skipOraclePriceRefresh) {
         await refreshWlpPoolOracles(tx, client, [params.depositTicker], {
             cache: params.pythCache,
             lpType: params.lpType,
+            feeSource,
+            updateDataProvider: params.updateDataProvider,
         });
     }
     const stakeAlias = params.stakeAlias ?? "WLP";
@@ -65,16 +83,24 @@ export async function buildMintAndStakeWlpTx(client, params) {
  * Refreshes every WLP pool-token oracle by default — `request_redeem` runs
  * `assert_prices_fresh` internally, so a stale oracle would abort the PTB.
  * Pass `skipOraclePriceRefresh: true` only when the caller is composing this
- * into a larger PTB that already pre-pumps prices.
+ * into a larger PTB that already pre-pumps prices. Like `buildMintWlpTx`,
+ * `request_redeem` produces no `TradingRequest`, so a non-skipped refresh
+ * requires `allowGasFee: true` (see `buildMintWlpTx`'s doc comment).
  */
 export async function buildUnstakeAndRequestRedeemWlpTx(client, params) {
     const tx = newTx(params);
     const stakeAlias = params.stakeAlias ?? "WLP";
     await maybeConsolidate(client, tx, params.accountId, params);
+    // `request_redeem` has no sponsor flow to resolve against (see
+    // `buildMintWlpTx`'s doc comment) — the only candidate source at this edge
+    // is the caller's ergonomic `allowGasFee` opt-in.
+    const feeSource = params.allowGasFee ? { kind: "gas" } : undefined;
     if (!params.skipOraclePriceRefresh) {
         await refreshWlpPoolOracles(tx, client, [], {
             cache: params.pythCache,
             lpType: params.lpType,
+            feeSource,
+            updateDataProvider: params.updateDataProvider,
         });
     }
     unstake(client, tx, {

package/dist/src/perp/tx-builders.d.ts

@@ -3,9 +3,9 @@
  *
  * Each `build*Tx` composer creates (or appends to) a `Transaction`, refreshes
  * the on-chain `Oracle` via Pyth, optionally pre-sweeps parked balances
- * (`consolidateToUsd`), wires the `pyth_sponsor_rule` flow when enabled, and
- * calls the matching `*_request` + `execute`. Implementations are split by
- * domain under `tx-builders/`:
+ * (`consolidateToUsd`), wires the `pyth_sponsor_rule` flow when deployed in
+ * config, and calls the matching `*_request` + `execute`. Implementations are
+ * split by domain under `tx-builders/`:
  *
  *   common.ts       CommonBuildOpts + request/execute envelope + oracle refresh
  *   consolidate.ts  parked-balance → wxUSD pre-sweep (appendConsolidate*)

package/dist/src/perp/tx-builders.js

@@ -3,9 +3,9 @@
  *
  * Each `build*Tx` composer creates (or appends to) a `Transaction`, refreshes
  * the on-chain `Oracle` via Pyth, optionally pre-sweeps parked balances
- * (`consolidateToUsd`), wires the `pyth_sponsor_rule` flow when enabled, and
- * calls the matching `*_request` + `execute`. Implementations are split by
- * domain under `tx-builders/`:
+ * (`consolidateToUsd`), wires the `pyth_sponsor_rule` flow when deployed in
+ * config, and calls the matching `*_request` + `execute`. Implementations are
+ * split by domain under `tx-builders/`:
  *
  *   common.ts       CommonBuildOpts + request/execute envelope + oracle refresh
  *   consolidate.ts  parked-balance → wxUSD pre-sweep (appendConsolidate*)

package/dist/src/unified-client.d.ts

@@ -32,6 +32,8 @@ import { Transaction } from "@mysten/sui/transactions";
 import * as accountOps from "./account/index.ts";
 import * as perpReferral from "./account/referral.ts";
 import type { Network } from "./constants.ts";
+import type { PythFetchPolicy } from "./oracle/config.ts";
+import type { OracleSource } from "./oracle/price-update-rule.ts";
 import { PerpClient, type CreateClientOptions as PerpCreateOptions } from "./perp/client.ts";
 import * as perpFetch from "./perp/fetch.ts";
 import * as perpTx from "./perp/tx-builders.ts";
@@ -363,6 +365,29 @@ export interface ClientCreateOptions {
     waterxConfigUrl?: string;
     /** Memoize the fetched config JSON. */
     cache?: boolean;
+    /**
+     * The perp line's oracle price-update source (perp-line only — the
+     * prediction line has no oracle leg), forwarded to `PerpClient.create`.
+     * Source-neutral by design: a future source need not be Pyth.
+     *
+     * - `'pyth_rule'` (default) — Pyth Core updates on Core infra.
+     * - `'pyth_lazer_rule'` — Pyth Lazer signed updates (pair with `pythApiKey`
+     *   and a config carrying `packages.pyth_lazer_rule`).
+     *
+     * Each source is self-contained with no cross-source fallback; selecting a
+     * source whose feed for a ticker is absent fails at tx-build (not at init).
+     * See perp `CreateClientOptions.oracleSource` for the full note.
+     */
+    oracleSource?: OracleSource;
+    /**
+     * Pyth Lazer access token, forwarded to the perp line. Required under
+     * `oracleSource: 'pyth_lazer_rule'`, unused by `'pyth_rule'`. A SECRET —
+     * pass it at init from your own env var; it is never read from the config
+     * JSON or `process.env`.
+     */
+    pythApiKey?: string;
+    /** Retry/timeout policy for the perp line's off-chain oracle fetches. */
+    pythFetch?: PythFetchPolicy;
     /** Perp-line overrides (network, grpcUrl, waterxConfigUrl, cache, …). */
     perp?: PerpLineOptions;
     /** Prediction-line overrides (network, grpcUrl, waterxConfigUrl, cache, settlement, …). */

package/dist/src/unified-client.js

@@ -168,6 +168,9 @@ export class WaterXClient {
             grpcUrl: opts.grpcUrl,
             waterxConfigUrl: opts.waterxConfigUrl,
             cache: opts.cache,
+            oracleSource: opts.oracleSource,
+            pythApiKey: opts.pythApiKey,
+            pythFetch: opts.pythFetch,
             ...perpRest,
         });
         const predictClient = await PredictClient.create(resolvedPredictNetwork, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waterx/sdk",
-  "version": "3.1.1",
+  "version": "4.0.1",
   "description": "WaterX SDK — perpetuals and prediction markets on Sui",
   "license": "MIT",
   "author": "WaterX",