@waterx/sdk 3.1.1 → 4.0.0

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 { PythGeneration } 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,21 @@ export interface ClientCreateOptions {
     waterxConfigUrl?: string;
     /** Memoize the fetched config JSON. */
     cache?: boolean;
+    /**
+     * Selects which `PriceUpdateRule` the perp line's `refreshOraclePrices` uses
+     * for the on-chain price-update leg (see `OracleHost.oracleSource`).
+     * Default: `'pyth_rule'`. Perp-line only. 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 the perp line's
+     * `client.perp.pyth` when the config JSON has no explicit `pyth` override:
+     * `'core'` (default) or `'pro'` (post-2026-08-18 Pro-compatible contracts +
+     * Hermes-compatible endpoint; pair with `pyth.api_key`). Perp-line only.
+     * See `PythGeneration` / `PYTH_PRO_DEFAULTS`.
+     */
+    pythGeneration?: PythGeneration;
     /** 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,8 @@ export class WaterXClient {
             grpcUrl: opts.grpcUrl,
             waterxConfigUrl: opts.waterxConfigUrl,
             cache: opts.cache,
+            oracleSource: opts.oracleSource,
+            pythGeneration: opts.pythGeneration,
             ...perpRest,
         });
         const predictClient = await PredictClient.create(resolvedPredictNetwork, {

package/package.json

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