@waterx/sdk 4.0.1 → 4.3.0

package/dist/src/perp/user/order.js

@@ -7,10 +7,24 @@
  *
  * Use `triggerPrice === undefined` (market form) to park an order at
  * tick 0 in the limit book; a keeper picks it up via `match_orders`.
+ *
+ * ## Trigger prices are exact order-book KEYS
+ *
+ * Every `triggerPrice` / `currentTriggerPrice` / `newTriggerPrice` below is the
+ * raw 1e9-scaled value the book is keyed by — off by a single 1e-9 unit and the
+ * lookup silently finds nothing. Build them with `rawPrice` in its EXACT mode
+ * (`rawPrice("95000.5")`, an `ExactDecimalUsd` string); the `number` mode
+ * round-trips through f64 and is exact only below ≈ $9,007,199.
+ *
+ * The params stay `bigint | number` (the RAW scaled value, not USD): both are
+ * legitimate raw inputs, `toU128` already rejects a non-safe-integer `number`
+ * before it can serialize wrong, and dropping `number` would break published
+ * call shapes. The mode choice belongs one level up, at `rawPrice`.
  */
 import { makeSenderRequest } from "../../account/account-request.js";
 import { newPlaceOrderArgument } from "../../generated/waterx_perp/request.js";
 import * as trading from "../../generated/waterx_perp/trading.js";
+import { toU8, toU64, toU64OrNull, toU128, toU128OrNull } from "../../utils/validate.js";
 import { ORDER_TAG_WILDCARD } from "../constants.js";
 /** Build a `request::PlaceOrderArgument` Move struct in the PTB. */
 export function buildPlaceOrderArgument(client, tx, p) {
@@ -20,11 +34,11 @@ export function buildPlaceOrderArgument(client, tx, p) {
             isLong: p.isLong,
             isStopOrder: p.isStopOrder,
             reduceOnly: p.reduceOnly,
-            size: p.size,
-            triggerPrice: p.triggerPrice ?? null,
-            linkedPositionId: p.linkedPositionId ?? null,
-            acceptablePrice: p.acceptablePrice ?? null,
-            collateralAmount: p.collateralAmount,
+            size: toU128(p.size, "size"),
+            triggerPrice: toU128OrNull(p.triggerPrice, "triggerPrice"),
+            linkedPositionId: toU64OrNull(p.linkedPositionId, "linkedPositionId"),
+            acceptablePrice: toU64OrNull(p.acceptablePrice, "acceptablePrice"),
+            collateralAmount: toU64(p.collateralAmount, "collateralAmount"),
         },
     })(tx);
     return arg;
@@ -66,9 +80,9 @@ export function cancelOrderRequest(client, tx, params) {
             ticker: params.ticker,
             senderRequest: req,
             accountId: params.accountId,
-            orderId: params.orderId,
-            triggerPrice: params.triggerPrice ?? 0n,
-            orderTypeTag: params.orderTypeTag ?? ORDER_TAG_WILDCARD,
+            orderId: toU64(params.orderId, "orderId"),
+            triggerPrice: toU128(params.triggerPrice ?? 0n, "triggerPrice"),
+            orderTypeTag: toU8(params.orderTypeTag ?? ORDER_TAG_WILDCARD, "orderTypeTag"),
         },
         typeArguments: [params.collateralType, params.lpType ?? client.wlpType()],
     })(tx);
@@ -85,11 +99,11 @@ export function updateOrderRequest(client, tx, params) {
             ticker: params.ticker,
             senderRequest: req,
             accountId: params.accountId,
-            orderId: params.orderId,
-            currentTriggerPrice: params.currentTriggerPrice,
-            orderTypeTag: params.orderTypeTag,
-            newSize: params.newSize,
-            newTriggerPrice: params.newTriggerPrice,
+            orderId: toU64(params.orderId, "orderId"),
+            currentTriggerPrice: toU128(params.currentTriggerPrice, "currentTriggerPrice"),
+            orderTypeTag: toU8(params.orderTypeTag, "orderTypeTag"),
+            newSize: toU128(params.newSize, "newSize"),
+            newTriggerPrice: toU128(params.newTriggerPrice, "newTriggerPrice"),
         },
         typeArguments: [params.collateralType, params.lpType ?? client.wlpType()],
     })(tx);
@@ -106,8 +120,8 @@ export function cancelPreOrderRequest(client, tx, params) {
             ticker: params.ticker,
             senderRequest: req,
             accountId: params.accountId,
-            mainOrderId: params.mainOrderId,
-            preOrderId: params.preOrderId,
+            mainOrderId: toU64(params.mainOrderId, "mainOrderId"),
+            preOrderId: toU64(params.preOrderId, "preOrderId"),
         },
         typeArguments: [params.collateralType, params.lpType ?? client.wlpType()],
     })(tx);
@@ -125,7 +139,7 @@ export function addPreOrderRequest(client, tx, params) {
             ticker: params.ticker,
             senderRequest: req,
             accountId: params.accountId,
-            mainOrderId: params.mainOrderId,
+            mainOrderId: toU64(params.mainOrderId, "mainOrderId"),
             preOrder: preArg,
         },
         typeArguments: [params.collateralType, params.lpType ?? client.wlpType()],

package/dist/src/perp/user/staking.js

@@ -17,6 +17,7 @@
  */
 import { makeSenderRequest } from "../../account/account-request.js";
 import * as staking from "../../generated/waterx_staking/waterx_staking.js";
+import { toU64Arg } from "../../utils/validate.js";
 function pool(client, stakeAlias) {
     const id = client.config.packages.waterx_staking?.pools?.[stakeAlias];
     if (!id) {
@@ -41,7 +42,7 @@ export function stake(client, tx, params) {
             wxaRegistry: tx.object(client.config.packages.waterx_account.account_registry),
             accountId: params.accountId,
             accReq: req,
-            stakeAmount: params.stakeAmount,
+            stakeAmount: toU64Arg(params.stakeAmount, "stakeAmount"),
         },
         typeArguments: [params.stakeType],
     })(tx);
@@ -72,7 +73,7 @@ export function unstake(client, tx, params) {
             wxaRegistry: tx.object(client.config.packages.waterx_account.account_registry),
             accountId: params.accountId,
             accReq: req,
-            withdrawalAmount: params.withdrawalAmount,
+            withdrawalAmount: toU64Arg(params.withdrawalAmount, "withdrawalAmount"),
         },
         typeArguments: [params.stakeType],
     })(tx);

package/dist/src/perp/user/trading.js

@@ -12,6 +12,7 @@
  */
 import { makeSenderRequest } from "../../account/account-request.js";
 import * as trading from "../../generated/waterx_perp/trading.js";
+import { toU8, toU64, toU64OrNull, toU128 } from "../../utils/validate.js";
 import { ORDER_TAG_WILDCARD } from "../constants.js";
 function typeArgs(client, t) {
     return [t.collateralType, t.lpType ?? client.wlpType()];
@@ -39,8 +40,8 @@ export function closePositionRequest(client, tx, params) {
             ticker: params.ticker,
             senderRequest: req,
             accountId: params.accountId,
-            positionId: params.positionId,
-            acceptablePrice: params.acceptablePrice,
+            positionId: toU64(params.positionId, "positionId"),
+            acceptablePrice: toU64(params.acceptablePrice, "acceptablePrice"),
         },
         typeArguments: typeArgs(client, params),
     })(tx);
@@ -58,11 +59,11 @@ export function increasePositionRequest(client, tx, params) {
             ticker: params.ticker,
             senderRequest: req,
             accountId: params.accountId,
-            orderId: params.orderId ?? null,
-            positionId: params.positionId,
-            collateralAmount: params.collateralAmount,
-            size: params.size,
-            acceptablePrice: params.acceptablePrice,
+            orderId: toU64OrNull(params.orderId, "orderId"),
+            positionId: toU64(params.positionId, "positionId"),
+            collateralAmount: toU64(params.collateralAmount, "collateralAmount"),
+            size: toU128(params.size, "size"),
+            acceptablePrice: toU64(params.acceptablePrice, "acceptablePrice"),
         },
         typeArguments: typeArgs(client, params),
     })(tx);
@@ -80,9 +81,9 @@ export function decreasePositionRequest(client, tx, params) {
             ticker: params.ticker,
             senderRequest: req,
             accountId: params.accountId,
-            positionId: params.positionId,
-            size: params.size,
-            acceptablePrice: params.acceptablePrice,
+            positionId: toU64(params.positionId, "positionId"),
+            size: toU128(params.size, "size"),
+            acceptablePrice: toU64(params.acceptablePrice, "acceptablePrice"),
         },
         typeArguments: typeArgs(client, params),
     })(tx);
@@ -100,8 +101,8 @@ export function depositCollateralRequest(client, tx, params) {
             ticker: params.ticker,
             senderRequest: req,
             accountId: params.accountId,
-            positionId: params.positionId,
-            collateralAmount: params.collateralAmount,
+            positionId: toU64(params.positionId, "positionId"),
+            collateralAmount: toU64(params.collateralAmount, "collateralAmount"),
         },
         typeArguments: typeArgs(client, params),
     })(tx);
@@ -119,8 +120,8 @@ export function withdrawCollateralRequest(client, tx, params) {
             ticker: params.ticker,
             senderRequest: req,
             accountId: params.accountId,
-            positionId: params.positionId,
-            amount: params.amount,
+            positionId: toU64(params.positionId, "positionId"),
+            amount: toU64(params.amount, "amount"),
         },
         typeArguments: typeArgs(client, params),
     })(tx);
@@ -154,7 +155,7 @@ export function liquidate(client, tx, params) {
             ticker: params.ticker,
             pool: tx.object(obj.wlpPool),
             senderRequest: req,
-            positionId: params.positionId,
+            positionId: toU64(params.positionId, "positionId"),
             oracle: tx.object(obj.oracle),
         },
         typeArguments: typeArgs(client, params),
@@ -173,8 +174,8 @@ export function batchLiquidate(client, tx, params) {
             pool: tx.object(obj.wlpPool),
             senderRequest: req,
             oracle: tx.object(obj.oracle),
-            pageSize: params.pageSize,
-            pageIndex: params.pageIndex,
+            pageSize: toU64(params.pageSize, "pageSize"),
+            pageIndex: toU64(params.pageIndex, "pageIndex"),
         },
         typeArguments: typeArgs(client, params),
     })(tx);
@@ -192,9 +193,9 @@ export function matchOrders(client, tx, params) {
             pool: tx.object(obj.wlpPool),
             senderRequest: req,
             oracle: tx.object(obj.oracle),
-            orderTypeTag: params.orderTypeTag,
-            triggerPrice: params.triggerPrice,
-            maxFills: params.maxFills,
+            orderTypeTag: toU8(params.orderTypeTag, "orderTypeTag"),
+            triggerPrice: toU128(params.triggerPrice, "triggerPrice"),
+            maxFills: toU64(params.maxFills, "maxFills"),
         },
         typeArguments: typeArgs(client, params),
     })(tx);
@@ -230,8 +231,8 @@ export function openPositionByKeeper(client, tx, params) {
             accountObjectAddress: params.accountObjectAddress,
             collateralCoin: params.collateralCoin,
             isLong: params.isLong,
-            size: params.size,
-            acceptablePrice: params.acceptablePrice,
+            size: toU128(params.size, "size"),
+            acceptablePrice: toU64(params.acceptablePrice, "acceptablePrice"),
             oracle: tx.object(obj.oracle),
         },
         typeArguments: typeArgs(client, params),
@@ -249,8 +250,8 @@ export function closePositionByKeeper(client, tx, params) {
             ticker: params.ticker,
             pool: tx.object(obj.wlpPool),
             keeperRequest: req,
-            positionId: params.positionId,
-            acceptablePrice: params.acceptablePrice,
+            positionId: toU64(params.positionId, "positionId"),
+            acceptablePrice: toU64(params.acceptablePrice, "acceptablePrice"),
             oracle: tx.object(obj.oracle),
         },
         typeArguments: typeArgs(client, params),

package/dist/src/perp/user/wlp.js

@@ -11,6 +11,7 @@
  */
 import { makeSenderRequest } from "../../account/account-request.js";
 import * as lp from "../../generated/waterx_perp/lp_pool.js";
+import { toU64 } from "../../utils/validate.js";
 /** Returns the minted `lp_amount` so it can be chained into e.g. `stake`. */
 export function mintWlp(client, tx, params) {
     const req = makeSenderRequest(client, tx, params.bucketAccount);
@@ -23,8 +24,8 @@ export function mintWlp(client, tx, params) {
             aum: tx.object(requireWlpAum(client)),
             senderRequest: req,
             accountId: params.accountId,
-            depositAmount: params.depositAmount,
-            minLpAmount: params.minLpAmount,
+            depositAmount: toU64(params.depositAmount, "depositAmount"),
+            minLpAmount: toU64(params.minLpAmount, "minLpAmount"),
             oracle: tx.object(client.config.packages.waterx_oracle.oracle),
         },
         typeArguments: [params.lpType ?? client.wlpType(), params.depositTokenType],
@@ -48,7 +49,7 @@ export function requestRedeemWlp(client, tx, params) {
             wxaRegistry: tx.object(client.config.packages.waterx_account.account_registry),
             senderRequest: req,
             accountId: params.accountId,
-            lpAmount: params.lpAmount,
+            lpAmount: toU64(params.lpAmount, "lpAmount"),
         },
         typeArguments: [params.lpType ?? client.wlpType(), params.redeemTokenType],
     })(tx);
@@ -62,7 +63,7 @@ export function cancelRedeemWlp(client, tx, params) {
             globalConfig: tx.object(client.config.packages.waterx_perp.global_config),
             wxaRegistry: tx.object(client.config.packages.waterx_account.account_registry),
             senderRequest: req,
-            requestId: params.requestId,
+            requestId: toU64(params.requestId, "requestId"),
         },
         typeArguments: [params.lpType ?? client.wlpType()],
     })(tx);
@@ -77,7 +78,7 @@ export function settleRedeemWlp(client, tx, params) {
             wxaRegistry: tx.object(client.config.packages.waterx_account.account_registry),
             operatorRequest: req,
             aum: tx.object(requireWlpAum(client)),
-            requestId: params.requestId,
+            requestId: toU64(params.requestId, "requestId"),
             oracle: tx.object(client.config.packages.waterx_oracle.oracle),
         },
         typeArguments: [params.lpType ?? client.wlpType(), params.redeemTokenType],

package/dist/src/prediction/utils.d.ts

@@ -10,8 +10,17 @@ export declare function resolveSettlementCoinType(client: PredictClient, coinTyp
 export declare function resolveMarketRegistry(client: PredictClient, marketRegistry?: string): string;
 export declare function resolveAccountRegistry(client: PredictClient, accountRegistry?: string): string;
 export declare function resolveGlobalConfig(client: PredictClient, globalConfig?: string): string;
-/** Ensures `value` is a valid unsigned 64-bit integer. */
-export declare function assertU64(value: bigint, name?: string): bigint;
+/**
+ * Ensures `value` is a valid unsigned 64-bit integer.
+ *
+ * Thin alias for the shared `utils/validate.toU64` — the u64 domain rule
+ * (bigint range check; a `number` must be a NON-NEGATIVE SAFE integer, since
+ * `2^53 + 2` passes `isInteger` yet has already lost f64 precision and would
+ * BCS-encode a silently-wrong value) is authored ONCE there for both product
+ * lines. Throws `RangeError` (a subclass of `Error`) naming the parameter.
+ */
+export declare function assertU64(value: bigint | number, name?: string): bigint;
+/** Normalize a u64-ish input (bigint / number / decimal string) to a checked `bigint`. */
 export declare function toBigInt(value: bigint | number | string): bigint;
 export declare function objectArg(tx: Transaction, value: ObjectArgument): TransactionArgument;
 export declare function idArg(tx: Transaction, value: IdArgument): TransactionArgument;

package/dist/src/prediction/utils.js

@@ -1,7 +1,8 @@
+import { toU64 } from "../utils/validate.js";
 import { CLOCK_OBJECT_ID } from "./constants.js";
 const SELECTIONS = ["YES", "NO"];
 const OUTCOMES = ["YES", "NO", "INVALID"];
-const U64_MAX = (1n << 64n) - 1n;
+const DECIMAL_INT_RE = /^\d+$/;
 export function assertSelection(value) {
     if (SELECTIONS.includes(value))
         return value;
@@ -45,32 +46,31 @@ export function resolveAccountRegistry(client, accountRegistry) {
 export function resolveGlobalConfig(client, globalConfig) {
     return globalConfig === undefined || globalConfig === "" ? client.globalConfigId() : globalConfig;
 }
-/** Ensures `value` is a valid unsigned 64-bit integer. */
+/**
+ * Ensures `value` is a valid unsigned 64-bit integer.
+ *
+ * Thin alias for the shared `utils/validate.toU64` — the u64 domain rule
+ * (bigint range check; a `number` must be a NON-NEGATIVE SAFE integer, since
+ * `2^53 + 2` passes `isInteger` yet has already lost f64 precision and would
+ * BCS-encode a silently-wrong value) is authored ONCE there for both product
+ * lines. Throws `RangeError` (a subclass of `Error`) naming the parameter.
+ */
 export function assertU64(value, name = "value") {
-    if (value < 0n) {
-        throw new Error(`${name} must be non-negative, got ${value}`);
-    }
-    if (value > U64_MAX) {
-        throw new Error(`${name} exceeds u64 max (${U64_MAX}), got ${value}`);
-    }
-    return value;
+    return toU64(value, name);
 }
+/** Normalize a u64-ish input (bigint / number / decimal string) to a checked `bigint`. */
 export function toBigInt(value) {
-    if (typeof value === "bigint") {
+    if (typeof value !== "string")
         return assertU64(value);
-    }
-    if (typeof value === "number") {
-        if (!Number.isInteger(value)) {
-            throw new Error(`Invalid integer: ${value}`);
-        }
-        return assertU64(BigInt(value));
-    }
+    // String is the one form the shared guard does not cover: digits parse exactly
+    // past the 2^53 f64 cliff, so the shape check lives here and the numeric
+    // domain still funnels through assertU64.
     const trimmed = value.trim();
     if (trimmed === "") {
-        throw new Error("Invalid integer: empty string");
+        throw new RangeError("Invalid integer: empty string");
     }
-    if (!/^\d+$/.test(trimmed)) {
-        throw new Error(`Invalid integer: ${JSON.stringify(value)}`);
+    if (!DECIMAL_INT_RE.test(trimmed)) {
+        throw new RangeError(`Invalid integer: ${JSON.stringify(value)}`);
     }
     return assertU64(BigInt(trimmed));
 }
@@ -161,8 +161,8 @@ export function optionU64(value) {
 function formatObjectVersion(version) {
     if (typeof version === "string") {
         const trimmed = version.trim();
-        if (trimmed === "" || !/^\d+$/.test(trimmed)) {
-            throw new Error(`Invalid object version: ${JSON.stringify(version)}`);
+        if (trimmed === "" || !DECIMAL_INT_RE.test(trimmed)) {
+            throw new RangeError(`Invalid object version: ${JSON.stringify(version)}`);
         }
         return trimmed;
     }

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

@@ -3,7 +3,7 @@
  *
  * Exposes three namespaces over the two product-line sub-clients:
  *
- *   const client = await WaterXClient.create({ network: "TESTNET" });
+ *   const client = await WaterXClient.create({ network: "TESTNET", oracleSource: "pyth_rule" });
  *   client.account.createAccount(tx, { alias });   // -> shared waterx_account + funding
  *   client.perp.placeOrderRequest(tx, params);     // -> perp builder
  *   client.predict.placeOrder(tx, params);         // -> prediction builder
@@ -34,6 +34,7 @@ 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 type { FetchPolicy } from "./oracle/update-fetch.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";
@@ -90,8 +91,8 @@ declare const perpOps: {
     getPosition(client: PerpClient, args: {
         ticker: string;
         positionId: bigint | number;
-        basePriceUsd: bigint | number;
-        collateralPriceUsd: bigint | number;
+        basePriceUsd: perpFetch.WholeDollarUsdPrice;
+        collateralPriceUsd: perpFetch.WholeDollarUsdPrice;
         lpType?: string;
     }): Promise<perpFetch.PositionDataView>;
     getOrder(client: PerpClient, args: {
@@ -99,12 +100,12 @@ declare const perpOps: {
         orderId: bigint | number;
         orderTypeTag: number;
         triggerPrice: bigint | number;
-        basePriceUsd: bigint | number;
+        basePriceUsd: perpFetch.WholeDollarUsdPrice;
         lpType?: string;
     }): Promise<perpFetch.OrderDataView>;
     getMarketOrders(client: PerpClient, args: {
         ticker: string;
-        basePriceUsd?: bigint | number;
+        basePriceUsd?: perpFetch.WholeDollarUsdPrice;
         lpType?: string;
     } & perpFetch.PageOpts): Promise<{
         orders: perpFetch.OrderDataView[];
@@ -112,8 +113,8 @@ declare const perpOps: {
     }>;
     getMarketPositions(client: PerpClient, args: {
         ticker: string;
-        basePriceUsd: bigint | number;
-        collateralPriceUsd?: bigint | number;
+        basePriceUsd: perpFetch.WholeDollarUsdPrice;
+        collateralPriceUsd?: perpFetch.WholeDollarUsdPrice;
         lpType?: string;
     } & perpFetch.PageOpts): Promise<{
         positions: perpFetch.PositionDataView[];
@@ -122,14 +123,14 @@ declare const perpOps: {
     getAccountPositions(client: PerpClient, args: {
         ticker: string;
         accountObjectAddress: string;
-        basePriceUsd: bigint | number;
-        collateralPriceUsd?: bigint | number;
+        basePriceUsd: perpFetch.WholeDollarUsdPrice;
+        collateralPriceUsd?: perpFetch.WholeDollarUsdPrice;
         lpType?: string;
     }): Promise<perpFetch.PositionDataView[]>;
     getAccountOrders(client: PerpClient, args: {
         ticker: string;
         accountObjectAddress: string;
-        basePriceUsd?: bigint | number;
+        basePriceUsd?: perpFetch.WholeDollarUsdPrice;
         lpType?: string;
     }): Promise<perpFetch.OrderDataView[]>;
     getRedeemRequests(client: PerpClient, args?: {
@@ -138,6 +139,7 @@ declare const perpOps: {
         requests: perpFetch.RedeemRequestDataView[];
         nextCursor?: bigint;
     }>;
+    parseWholeDollarU64: typeof perpFetch.parseWholeDollarU64;
     getAccountsByOwner(client: PerpClient, owner: string): Promise<string[]>;
     getAccountBalance(client: PerpClient, accountId: string, coinType?: string): Promise<bigint>;
     getSpendableCreditBalance(client: PerpClient, accountId: string): Promise<perpFetch.SpendableCreditBalance>;
@@ -368,17 +370,25 @@ export interface ClientCreateOptions {
     /**
      * 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.
+     * REQUIRED — there is NO default source: every deployment names its source
+     * explicitly (wire it from your own env var, e.g. `ORACLE_SOURCE`).
+     * Source-neutral by design: a source need not be Pyth (see `'waterx_rule'`).
      *
-     * - `'pyth_rule'` (default) — Pyth Core updates on Core infra.
+     * - `'pyth_rule'` — Pyth Core updates; infra in the source's own
+     *   `PYTH_CORE_INFRA` table.
      * - `'pyth_lazer_rule'` — Pyth Lazer signed updates (pair with `pythApiKey`
-     *   and a config carrying `packages.pyth_lazer_rule`).
+     *   and a config carrying `packages.pyth_lazer_rule`); infra in the
+     *   source's own `LAZER_INFRA` table.
+     * - `'waterx_rule'` — the first-party WaterX quote-center (Nautilus-TEE,
+     *   ed25519 signed batches; no credential, no per-update fee); infra in the
+     *   source's own `WATERX_INFRA` table. Pair with `waterxEndpoint` /
+     *   `waterxFetch` when the browser needs a proxy.
      *
      * 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;
+    oracleSource: OracleSource | OracleSource[];
     /**
      * Pyth Lazer access token, forwarded to the perp line. Required under
      * `oracleSource: 'pyth_lazer_rule'`, unused by `'pyth_rule'`. A SECRET —
@@ -388,6 +398,22 @@ export interface ClientCreateOptions {
     pythApiKey?: string;
     /** Retry/timeout policy for the perp line's off-chain oracle fetches. */
     pythFetch?: PythFetchPolicy;
+    /**
+     * Quote-center base URL for `oracleSource: 'waterx_rule'`, forwarded to the
+     * perp line — overrides the source's own per-network `WATERX_INFRA` default.
+     *
+     * `waterx_rule` is the one source a BROWSER fetches itself, so it is bound by
+     * the quote-center deployment's CORS allowlist: a front end whose origin is
+     * not allowed points this at its own same-origin proxy. An absolute URL whose
+     * base PATH is preserved — `https://app.example/api/quote-center` fetches
+     * `…/api/quote-center/v1/quotes/update`. Unused by the Pyth sources.
+     */
+    waterxEndpoint?: string;
+    /**
+     * Retry/timeout policy — and `fetchImpl` — for the perp line's quote-center
+     * fetch. Falls back to the built-in defaults — never to `pythFetch`.
+     */
+    waterxFetch?: FetchPolicy;
     /** Perp-line overrides (network, grpcUrl, waterxConfigUrl, cache, …). */
     perp?: PerpLineOptions;
     /** Prediction-line overrides (network, grpcUrl, waterxConfigUrl, cache, settlement, …). */
@@ -427,6 +453,6 @@ export declare class WaterXClient {
      * `waterx-config` JSON) and returns a ready client. Each line can target a
      * different network via `opts.perp.network` / `opts.predict.network`.
      */
-    static create(opts?: ClientCreateOptions): Promise<WaterXClient>;
+    static create(opts: ClientCreateOptions): Promise<WaterXClient>;
 }
 export {};

package/dist/src/unified-client.js

@@ -3,7 +3,7 @@
  *
  * Exposes three namespaces over the two product-line sub-clients:
  *
- *   const client = await WaterXClient.create({ network: "TESTNET" });
+ *   const client = await WaterXClient.create({ network: "TESTNET", oracleSource: "pyth_rule" });
  *   client.account.createAccount(tx, { alias });   // -> shared waterx_account + funding
  *   client.perp.placeOrderRequest(tx, params);     // -> perp builder
  *   client.predict.placeOrder(tx, params);         // -> prediction builder
@@ -150,7 +150,7 @@ export class WaterXClient {
      * `waterx-config` JSON) and returns a ready client. Each line can target a
      * different network via `opts.perp.network` / `opts.predict.network`.
      */
-    static async create(opts = {}) {
+    static async create(opts) {
         const baseNetwork = opts.network ?? "TESTNET";
         const { network: perpNetwork, ...perpRest } = opts.perp ?? {};
         const { network: predictNetwork, ...predictRest } = opts.predict ?? {};
@@ -171,6 +171,8 @@ export class WaterXClient {
             oracleSource: opts.oracleSource,
             pythApiKey: opts.pythApiKey,
             pythFetch: opts.pythFetch,
+            waterxEndpoint: opts.waterxEndpoint,
+            waterxFetch: opts.waterxFetch,
             ...perpRest,
         });
         const predictClient = await PredictClient.create(resolvedPredictNetwork, {

package/dist/src/utils/format.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Funding-interval label from milliseconds: hour-based at or above one hour,
+ * minute-based below. Non-integer hours are kept as-is:
+ *
+ *   3_600_000  → "1H"
+ *   28_800_000 → "8H"
+ *   5_400_000  → "1.5H"
+ *   1_800_000  → "30M"
+ *
+ * Single source for the label the BE tickers payload emits and the FE reader
+ * must reproduce byte-identically (output-identical port of bucket-backend-mono
+ * `apps/waterx/src/core/utils/funding.ts::formatFundingInterval`).
+ */
+export declare function formatFundingInterval(intervalMs: number): string;

package/dist/src/utils/format.js

@@ -0,0 +1,21 @@
+// Display-label formatters that must be byte-identical wherever the same wire
+// field is rendered. Hosted in the SDK so FE and BE share one implementation
+// instead of hand-mirroring each other.
+import { MS_PER_HOUR, MS_PER_MINUTE } from "../constants.js";
+/**
+ * Funding-interval label from milliseconds: hour-based at or above one hour,
+ * minute-based below. Non-integer hours are kept as-is:
+ *
+ *   3_600_000  → "1H"
+ *   28_800_000 → "8H"
+ *   5_400_000  → "1.5H"
+ *   1_800_000  → "30M"
+ *
+ * Single source for the label the BE tickers payload emits and the FE reader
+ * must reproduce byte-identically (output-identical port of bucket-backend-mono
+ * `apps/waterx/src/core/utils/funding.ts::formatFundingInterval`).
+ */
+export function formatFundingInterval(intervalMs) {
+    const hours = intervalMs / MS_PER_HOUR;
+    return hours >= 1 ? `${hours}H` : `${intervalMs / MS_PER_MINUTE}M`;
+}