@waterx/sdk 4.0.0 → 4.1.0

package/dist/src/perp/client.d.ts

@@ -12,44 +12,96 @@
  */
 import { BaseLineClient } from "../base-client.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 { FetchPolicy } from "../oracle/update-fetch.ts";
+import { type LoadConfigOptions, type PythFetchPolicy, type PythInfraConfig, type WaterXConfig, type WaterxInfraConfig, 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`).
+     * Which oracle price-update source drives `refreshOraclePrices`. Each source
+     * is self-contained (own infra + config) with NO cross-source fallback:
+     *
+     * - `'pyth_rule'` (default) — Pyth Core `pyth_rule` updates (Hermes VAA +
+     *   per-feed update fees), Core state + keyless Core Hermes.
+     * - `'pyth_lazer_rule'` — Pyth Lazer signed updates (ONE `leEcdsa` verify
+     *   per PTB, no per-feed fees); needs `packages.pyth_lazer_rule` with feeds
+     *   and a `pythApiKey` (Lazer is auth-first).
+     * - `'waterx_rule'` — the first-party WaterX quote-center (Nautilus-TEE,
+     *   ed25519-signed batches): ONE envelope covering the build's tickers,
+     *   verified AND fed by a single `collect_batch_latest` per collector. No
+     *   credential and no per-update fee; needs `packages.waterx_rule` with
+     *   feeds. Endpoint/transport via {@link CreateClientOptions.waterxEndpoint}
+     *   / {@link CreateClientOptions.waterxFetch} — the browser-CORS proxy hook,
+     *   since this is the one source fetched from the page.
+     *
+     * The name is source-neutral on purpose — a source need not be Pyth (as
+     * `'waterx_rule'` shows). Selecting a source whose feed for a requested
+     * ticker is absent is NOT an error at client creation: it fails at tx-build
+     * time for exactly those tickers (see `refreshOraclePrices`). The Pyth Core
+     * infra is fixed per network by `PYTH_DEFAULTS` and is not
+     * deployment-overridable.
      */
     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`).
+     * Pyth Lazer access token (`Authorization: Bearer …`). Required under
+     * `oracleSource: 'pyth_lazer_rule'` (Lazer is auth-first) and unused by
+     * `'pyth_rule'` (keyless Core Hermes). This is a SECRET and never belongs in
+     * the canonical `waterx-config` JSON — pass it at client init from your own
+     * env var (e.g. `PYTH_API_KEY`); the SDK never reads `process.env`.
      */
-    pythGeneration?: PythGeneration;
+    pythApiKey?: string;
+    /**
+     * Retry/timeout policy for the off-chain Hermes / Lazer update fetches (see
+     * `fetchWithPolicy`). Optional — defaults to 15s timeout, 2 retries.
+     */
+    pythFetch?: PythFetchPolicy;
+    /**
+     * Quote-center base URL for `oracleSource: 'waterx_rule'` — overrides the
+     * per-network {@link WATERX_DEFAULTS} host.
+     *
+     * This is the one source a BROWSER fetches itself (the signed envelope is
+     * pulled from the page), so it is bound by the quote-center deployment's CORS
+     * allowlist. A front end whose origin is not allowed — or one that must route
+     * egress through its own backend — points this at a same-origin proxy that
+     * forwards `GET /v1/quotes/update`. Unused by the Pyth sources.
+     *
+     * An absolute URL. Any base PATH is preserved (`joinEndpointPath`), so
+     * `https://app.example/api/quote-center` fetches
+     * `https://app.example/api/quote-center/v1/quotes/update` — a proxy route
+     * survives instead of being rewritten to the origin root.
+     */
+    waterxEndpoint?: string;
+    /**
+     * Retry/timeout policy — and `fetchImpl` — for the quote-center fetch (see
+     * `fetchWithPolicy`). Optional: falls back to `pythFetch`, then to the
+     * built-in defaults. Supply `fetchImpl` to route the request through your own
+     * transport (a proxying `fetch` wrapper, a non-global `fetch`, a test double).
+     */
+    waterxFetch?: FetchPolicy;
 }
 export declare class PerpClient extends BaseLineClient<WaterXConfig> {
-    /** Pyth infra (network defaults unless overridden in JSON). */
+    /** Pyth Core infra (fixed per network) plus the caller-supplied credential/policy. */
     pyth: PythInfraConfig;
+    /**
+     * WaterX quote-center infra for `oracleSource: 'waterx_rule'` — the network
+     * default, overridden by the `waterxEndpoint` / `waterxFetch` create options
+     * (a same-origin proxy or a custom `fetchImpl` for browser consumers).
+     */
+    waterx: WaterxInfraConfig;
     /** 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`. */
+    /** Selected oracle price-update source (`oracleSource` create option; default `'pyth_rule'`). */
     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;
-    });
+    constructor(network: Network, config: WaterXConfig, opts?: CreateClientOptions);
     /**
      * Async factory: fetches the deployment config for `network` and returns
      * a ready-to-use client. Pass `opts.cache=true` to memoize the JSON.
+     *
+     * No oracle-config guard here: selecting a source whose feeds are absent is
+     * not an error at init — it surfaces at tx-build time for the specific
+     * tickers that source can't serve (see `refreshOraclePrices`).
      */
     static create(network: Network, opts?: CreateClientOptions): Promise<PerpClient>;
     static mainnet(opts?: CreateClientOptions): Promise<PerpClient>;

package/dist/src/perp/client.js

@@ -12,36 +12,56 @@
  */
 import { BaseLineClient } from "../base-client.js";
 import { PerpConfigView } from "./config-view.js";
-import { loadConfig, PYTH_DEFAULTS, PYTH_PRO_DEFAULTS, WORMHOLE_DEFAULTS, } from "./config.js";
+import { loadConfig, PYTH_DEFAULTS, WATERX_DEFAULTS, WORMHOLE_DEFAULTS, } from "./config.js";
 export class PerpClient extends BaseLineClient {
-    /** Pyth infra (network defaults unless overridden in JSON). */
+    /** Pyth Core infra (fixed per network) plus the caller-supplied credential/policy. */
     pyth;
+    /**
+     * WaterX quote-center infra for `oracleSource: 'waterx_rule'` — the network
+     * default, overridden by the `waterxEndpoint` / `waterxFetch` create options
+     * (a same-origin proxy or a custom `fetchImpl` for browser consumers).
+     */
+    waterx;
     /** 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`. */
+    /** Selected oracle price-update source (`oracleSource` create option; default `'pyth_rule'`). */
     oracleSource;
     /** Canonical-schema lookups (delegated to below); no transport. */
     view;
     constructor(network, config, opts = {}) {
         super(network, config, opts);
-        // Precedence: explicit config.pyth override > generation constants.
-        this.pyth =
-            config.pyth ?? (opts.pythGeneration === "pro" ? PYTH_PRO_DEFAULTS : PYTH_DEFAULTS)[network];
+        // Pyth Core infra is fixed per network — NOT deployment-overridable and
+        // NOT source-dependent (the pyth_lazer_rule source reads only api_key/fetch
+        // from here). The api_key + fetch policy are caller-supplied at init: a
+        // secret has no place in the canonical waterx-config JSON.
+        this.pyth = {
+            ...PYTH_DEFAULTS[network],
+            ...(opts.pythApiKey !== undefined ? { api_key: opts.pythApiKey } : {}),
+            ...(opts.pythFetch !== undefined ? { fetch: opts.pythFetch } : {}),
+        };
         this.wormhole = config.wormhole ?? WORMHOLE_DEFAULTS[network];
+        // Quote-center infra: network default, each field independently overridable
+        // — a browser blocked by the quote-center's CORS allowlist swaps `endpoint`
+        // for a same-origin proxy without touching anything else.
+        this.waterx = {
+            ...WATERX_DEFAULTS[network],
+            ...(opts.waterxEndpoint !== undefined ? { endpoint: opts.waterxEndpoint } : {}),
+            ...(opts.waterxFetch !== undefined ? { fetch: opts.waterxFetch } : {}),
+        };
         this.oracleSource = opts.oracleSource ?? "pyth_rule";
         this.view = new PerpConfigView(() => this.config, () => this.wormhole);
     }
     /**
      * Async factory: fetches the deployment config for `network` and returns
      * a ready-to-use client. Pass `opts.cache=true` to memoize the JSON.
+     *
+     * No oracle-config guard here: selecting a source whose feeds are absent is
+     * not an error at init — it surfaces at tx-build time for the specific
+     * tickers that source can't serve (see `refreshOraclePrices`).
      */
     static async create(network, opts = {}) {
         const config = await loadConfig(network, opts);
-        return new PerpClient(network, config, {
-            grpcUrl: opts.grpcUrl,
-            oracleSource: opts.oracleSource,
-            pythGeneration: opts.pythGeneration,
-        });
+        return new PerpClient(network, config, opts);
     }
     static mainnet(opts = {}) {
         return PerpClient.create("MAINNET", opts);

package/dist/src/perp/config.d.ts

@@ -9,11 +9,11 @@
  * below, keyed by network.
  */
 import type { AccountPackages, BasePackageEntry, WormholeInfraConfig } from "../account/config.ts";
-import type { OraclePackages, PythInfraConfig } from "../oracle/config.ts";
+import type { OraclePackages } from "../oracle/config.ts";
 import type { Network } from "./constants.ts";
-export type { AccountConfig, AccountPackages, BasePackageEntry, NativeCustodyAsset, NativeCustodyPackage, TrustedEmitterRow, WaterxCreditPackage, WaterxReferralPackage, WithdrawalQueuePackage, WormholeBridgePackage, WormholeInfraConfig, WxaAccountPackage, } from "../account/config.ts";
-export type { ConstantFeedEntry, OracleConfig, OraclePackages, PythGeneration, PythInfraConfig, PythLazerRulePackage, PythRulePackage, PythSponsorRulePackage, SupraFeedEntry, SupraRulePackage, WaterxConstantRulePackage, WaterxOraclePackage, } from "../oracle/config.ts";
-export { PYTH_DEFAULTS, PYTH_PRO_DEFAULTS } from "../oracle/config.ts";
+export type { AccountConfig, AccountPackages, BasePackageEntry, NativeCustodyAsset, NativeCustodyPackage, WaterxCreditPackage, WaterxReferralPackage, WithdrawalQueuePackage, WormholeBridgePackage, WormholeInfraConfig, WxaAccountPackage, } from "../account/config.ts";
+export type { ConstantFeedEntry, OracleConfig, OraclePackages, PythFetchPolicy, PythInfraConfig, PythLazerRulePackage, PythRulePackage, PythSponsorRulePackage, SupraFeedEntry, SupraRulePackage, WaterxConstantRulePackage, WaterxInfraConfig, WaterxOraclePackage, WaterxRulePackage, } from "../oracle/config.ts";
+export { PYTH_DEFAULTS, WATERX_DEFAULTS } from "../oracle/config.ts";
 export interface WaterxPerpMarketEntry {
     market: string;
     config: string;
@@ -71,7 +71,6 @@ export interface WaterXPackages extends AccountPackages, OraclePackages {
     mock_usdc?: MockCoinPackage;
     mock_usdsui?: MockCoinPackage;
     mock_sui?: MockCoinPackage;
-    waterx_rule?: BasePackageEntry;
     waterx_rule_nautilus_enclave?: BasePackageEntry;
 }
 export declare const WORMHOLE_DEFAULTS: Record<Network, WormholeInfraConfig>;
@@ -82,8 +81,6 @@ export interface WaterXConfig {
     /** Sui gRPC base URL (default: public Mysten fullnode for the network). */
     grpcUrl?: string;
     packages: WaterXPackages;
-    /** Pyth infra override (defaults from `PYTH_DEFAULTS[network]`). */
-    pyth?: PythInfraConfig;
     /** Wormhole infra override (defaults from `WORMHOLE_DEFAULTS[network]`). */
     wormhole?: WormholeInfraConfig;
     /** Sui `CoinRegistry` shared object (credit deployments). */

package/dist/src/perp/config.js

@@ -8,8 +8,8 @@
  * **not** in the JSON — it lives in `PYTH_DEFAULTS` / `WORMHOLE_DEFAULTS`
  * below, keyed by network.
  */
-import { FetchPolicyError, fetchWithPolicy } from "../oracle/update-fetch.js";
-export { PYTH_DEFAULTS, PYTH_PRO_DEFAULTS } from "../oracle/config.js";
+import { fetchWithPolicy, rethrowExhaustedFetch } from "../oracle/update-fetch.js";
+export { PYTH_DEFAULTS, WATERX_DEFAULTS } from "../oracle/config.js";
 // ============================================================================
 // Wormhole / Hermes — external chain infra, defaults by network
 // ============================================================================
@@ -113,16 +113,13 @@ export async function loadConfig(network, opts = {}) {
         const stale = configCache.get(cacheKey);
         if (stale)
             return stale;
-        // Reformat a status-carrying FetchPolicyError (retries exhausted on a
-        // retryable status) into this function's own message shape, mirroring
-        // the non-retried `!response.ok` throw above. A network-level
-        // exhaustion (no status), a `!response.ok` throw, or a JSON parse /
-        // `validateConfig` failure has no domain-specific reframing to add —
-        // propagate that error's own message as-is.
-        if (err instanceof FetchPolicyError && err.status !== undefined) {
-            throw new Error(`loadConfig: HTTP ${err.status} fetching ${url} (retries exhausted after ${err.attempts} attempts)`, { cause: err });
-        }
-        throw err;
+        // Reframe a status-carrying FetchPolicyError into this function's own
+        // message shape, mirroring the non-retried `!response.ok` throw above and
+        // carrying the URL (the key datum for a config-fetch failure). A
+        // network-level exhaustion (no status), a `!response.ok` throw, or a JSON
+        // parse / `validateConfig` failure has no reframing to add — the helper
+        // propagates those verbatim.
+        rethrowExhaustedFetch(err, (e) => `loadConfig: HTTP ${e.status} fetching ${url}`);
     }
     configCache.set(cacheKey, raw);
     return raw;

package/dist/src/perp/constants.d.ts

@@ -1,10 +1,4 @@
 export * from "../constants.ts";
-/** Default crypto market trading fee rate (3 bps). Per-market value lives in MarketConfig. */
-export declare const CRYPTO_FEE_RATE = 0.0003;
-/** Default stock / commodity market trading fee rate (5 bps). Per-market value lives in MarketConfig. */
-export declare const STOCK_FEE_RATE = 0.0005;
-/** Default maintenance margin rate (150 bps = 1.5%). Per-market value lives in MarketConfig. */
-export declare const MAINTENANCE_MARGIN_RATE = 0.015;
 export declare const PERM_OPEN_POSITION = 1;
 export declare const PERM_CLOSE_POSITION = 2;
 export declare const PERM_INCREASE_POSITION = 4;

package/dist/src/perp/constants.js

@@ -1,15 +1,17 @@
 // Perp-line domain constants (trading permissions / order tags / action codes /
-// fee rates / well-known addresses). Re-exports the shared primitives from
+// well-known addresses). Re-exports the shared primitives from
 // `../constants.ts` so perp code and the `./perp` barrel get the full set from
 // a single import.
+//
+// NOTE: there are deliberately NO fee-rate / maintenance-margin constants here.
+// `CRYPTO_FEE_RATE` / `STOCK_FEE_RATE` / `MAINTENANCE_MARGIN_RATE` were removed
+// — they were defaults masquerading as truth; per-market `MarketConfig` on
+// chain is the only source for fee and margin parameters (real MMRs span
+// 0.5%–5%; the flat 1.5% understated AAPLX-class risk >3x — mainnet incident
+// 2026-07-28: shorts displayed liq ~$364 but were liquidated at ~$343). When
+// the market rate is unavailable, treat the value as NOT estimable and fail
+// safe — never substitute a flat default.
 export * from "../constants.js";
-// ======== Fee rates & risk parameters ========
-/** Default crypto market trading fee rate (3 bps). Per-market value lives in MarketConfig. */
-export const CRYPTO_FEE_RATE = 0.0003;
-/** Default stock / commodity market trading fee rate (5 bps). Per-market value lives in MarketConfig. */
-export const STOCK_FEE_RATE = 0.0005;
-/** Default maintenance margin rate (150 bps = 1.5%). Per-market value lives in MarketConfig. */
-export const MAINTENANCE_MARGIN_RATE = 0.015;
 // ======== Permission Bitmasks (matches account_data.move) ========
 export const PERM_OPEN_POSITION = 1;
 export const PERM_CLOSE_POSITION = 2;

package/dist/src/perp/fetch/account.js

@@ -51,6 +51,9 @@ export async function getSpendableCreditBalance(client, accountId) {
         probeParkedBackingAssets(client, accountId),
         probeAddressCreditBalance(client, accountId),
     ]);
+    // COLLATERAL_DECIMALS here is the CREDIT/wxUSD *target* scale (collateral-typed;
+    // 6 on all current deployments — config carries no credit decimal). The
+    // per-asset backing decimals come from config via each row's `decimals`.
     const pendingBackingRaw = sumParkedBackingAsCreditRaw(parkedBacking, COLLATERAL_DECIMALS);
     const pendingCreditAtAddressRaw = addressCredit.fundsRaw + addressCredit.coinsRaw;
     const totalRaw = internalRaw + pendingBackingRaw + pendingCreditAtAddressRaw;

package/dist/src/perp/fetch/bridge.js

@@ -6,6 +6,7 @@ import { bcs } from "@mysten/sui/bcs";
 import { Transaction } from "@mysten/sui/transactions";
 import { bridgeFeeAmount as bridgeFeeAmountCall, bridgeFeeRate as bridgeFeeRateCall, bridgeMinFee as bridgeMinFeeCall, wouldExecuteWormhole as wouldExecuteWormholeCall, } from "../../generated/withdrawal_queue/withdrawal_queue.js";
 import { dailyBurned as dailyBurnedCall, dailyBurnLimit as dailyBurnLimitCall, dailyMinted as dailyMintedCall, dailyMintLimit as dailyMintLimitCall, maxBurnPerTx as maxBurnPerTxCall, maxMintPerTx as maxMintPerTxCall, mintedFor as mintedForCall, paused as pausedCall, personalBurnCapAmount as personalBurnCapAmountCall, personalBurned as personalBurnedCall, } from "../../generated/wormhole_bridge/wormhole_bridge.js";
+import { toU64 } from "../../utils/validate.js";
 import { extractAt, simulateRaw } from "./simulate.js";
 /**
  * Batched read of the bridge's rate-limit / cap state in a single simulate.
@@ -96,7 +97,7 @@ function requireWithdrawalQueue(client) {
  */
 export async function getBridgeFee(client, args) {
     const { pkg, queue } = requireWithdrawalQueue(client);
-    const amount = BigInt(args.amount);
+    const amount = toU64(args.amount, "amount");
     const common = {
         package: pkg,
         typeArguments: [args.creditType ?? client.creditType()],

package/dist/src/perp/fetch/market.js

@@ -5,6 +5,7 @@
 import { bcs } from "@mysten/sui/bcs";
 import { Transaction } from "@mysten/sui/transactions";
 import { AccountData, accountData as accountDataCall, GlobalConfigData, globalConfigData as globalConfigDataCall, MarketData, marketData as marketDataCall, PoolData, poolData as poolDataCall, TokenPoolData, tokenPoolData as tokenPoolDataCall, } from "../../generated/waterx_perp_view/view.js";
+import { toU64 } from "../../utils/validate.js";
 import { simulateAndExtract, withLp } from "./simulate.js";
 /**
  * Look up the registered AccountData for a given wxa account ID.
@@ -52,7 +53,7 @@ export async function getTokenPoolData(client, args) {
         package: client.config.packages.waterx_perp_view.published_at,
         arguments: {
             pool: tx.object(client.config.packages.wlp.wlp_pool),
-            tokenIndex: args.tokenIndex,
+            tokenIndex: toU64(args.tokenIndex, "tokenIndex"),
         },
         typeArguments: [withLp(client, args.lpType)],
     })(tx);

package/dist/src/perp/fetch/positions.d.ts

@@ -3,7 +3,9 @@
  * list (`waterx_perp_view`).
  */
 import { OrderData, PositionData, RedeemRequestData } from "../../generated/waterx_perp_view/view.ts";
+import { parseWholeDollarU64, type WholeDollarUsdPrice } from "../../utils/validate.ts";
 import type { PerpClient } from "../client.ts";
+export { parseWholeDollarU64, type WholeDollarUsdPrice };
 export type PositionDataView = ReturnType<typeof PositionData.parse>;
 export declare function positionExists(client: PerpClient, args: {
     ticker: string;
@@ -13,9 +15,8 @@ export declare function positionExists(client: PerpClient, args: {
 export declare function getPosition(client: PerpClient, args: {
     ticker: string;
     positionId: bigint | number;
-    /** Human-readable USD prices for Pnl / liq price calc; pass 0n if unsure. */
-    basePriceUsd: bigint | number;
-    collateralPriceUsd: bigint | number;
+    basePriceUsd: WholeDollarUsdPrice;
+    collateralPriceUsd: WholeDollarUsdPrice;
     lpType?: string;
 }): Promise<PositionDataView>;
 export type OrderDataView = ReturnType<typeof OrderData.parse>;
@@ -23,8 +24,9 @@ export declare function getOrder(client: PerpClient, args: {
     ticker: string;
     orderId: bigint | number;
     orderTypeTag: number;
+    /** Raw 1e9-scaled u128 order-book key — same scale as tx-build `rawPrice()`. */
     triggerPrice: bigint | number;
-    basePriceUsd: bigint | number;
+    basePriceUsd: WholeDollarUsdPrice;
     lpType?: string;
 }): Promise<OrderDataView>;
 export interface PageOpts {
@@ -33,7 +35,8 @@ export interface PageOpts {
 }
 export declare function getMarketOrders(client: PerpClient, args: {
     ticker: string;
-    basePriceUsd?: bigint | number;
+    /** Defaults to `0n`. */
+    basePriceUsd?: WholeDollarUsdPrice;
     lpType?: string;
 } & PageOpts): Promise<{
     orders: OrderDataView[];
@@ -41,8 +44,9 @@ export declare function getMarketOrders(client: PerpClient, args: {
 }>;
 export declare function getMarketPositions(client: PerpClient, args: {
     ticker: string;
-    basePriceUsd: bigint | number;
-    collateralPriceUsd?: bigint | number;
+    basePriceUsd: WholeDollarUsdPrice;
+    /** Defaults to `0n`. */
+    collateralPriceUsd?: WholeDollarUsdPrice;
     lpType?: string;
 } & PageOpts): Promise<{
     positions: PositionDataView[];
@@ -51,14 +55,16 @@ export declare function getMarketPositions(client: PerpClient, args: {
 export declare function getAccountPositions(client: PerpClient, args: {
     ticker: string;
     accountObjectAddress: string;
-    basePriceUsd: bigint | number;
-    collateralPriceUsd?: bigint | number;
+    basePriceUsd: WholeDollarUsdPrice;
+    /** Defaults to `0n`. */
+    collateralPriceUsd?: WholeDollarUsdPrice;
     lpType?: string;
 }): Promise<PositionDataView[]>;
 export declare function getAccountOrders(client: PerpClient, args: {
     ticker: string;
     accountObjectAddress: string;
-    basePriceUsd?: bigint | number;
+    /** Defaults to `0n`. */
+    basePriceUsd?: WholeDollarUsdPrice;
     lpType?: string;
 }): Promise<OrderDataView[]>;
 export type RedeemRequestDataView = ReturnType<typeof RedeemRequestData.parse>;

package/dist/src/perp/fetch/positions.js

@@ -5,8 +5,16 @@
 import { bcs } from "@mysten/sui/bcs";
 import { Transaction } from "@mysten/sui/transactions";
 import { getAccountOrders as getAccountOrdersCall, getAccountPositions as getAccountPositionsCall, getMarketOrders as getMarketOrdersCall, getMarketPositions as getMarketPositionsCall, getRedeemRequests as getRedeemRequestsCall, OrderData, orderData as orderDataCall, PositionData, positionData as positionDataCall, positionExists as positionExistsCall, RedeemRequestData, } from "../../generated/waterx_perp_view/view.js";
+import { parseWholeDollarU64, toU8, toU64, toU128, } from "../../utils/validate.js";
 import { DRY_RUN_SENDER } from "../constants.js";
 import { simulateAndExtract, toBytes, withLp } from "./simulate.js";
+// The whole-dollar USD price domain is a pure numeric guard with no chain/fetch
+// dependency, so it lives with the rest of that vocabulary in
+// `utils/validate.ts`. It is re-exported HERE — unchanged — because this module
+// is its published home: `perp/fetch` → `@waterx/sdk`. Every read param below
+// is typed `WholeDollarUsdPrice`, so the type and its parser stay one hop from
+// the functions that consume them.
+export { parseWholeDollarU64 };
 export async function positionExists(client, args) {
     const tx = new Transaction();
     positionExistsCall({
@@ -14,7 +22,7 @@ export async function positionExists(client, args) {
         arguments: {
             marketRegistry: tx.object(client.config.packages.waterx_perp.market_registry_wlp),
             ticker: args.ticker,
-            positionId: args.positionId,
+            positionId: toU64(args.positionId, "positionId"),
         },
         typeArguments: [withLp(client, args.lpType)],
     })(tx);
@@ -29,9 +37,9 @@ export async function getPosition(client, args) {
             marketRegistry: tx.object(client.config.packages.waterx_perp.market_registry_wlp),
             ticker: args.ticker,
             pool: tx.object(client.config.packages.wlp.wlp_pool),
-            basePriceUsd: args.basePriceUsd,
-            collateralPriceUsd: args.collateralPriceUsd,
-            positionId: args.positionId,
+            basePriceUsd: toU64(args.basePriceUsd, "basePriceUsd"),
+            collateralPriceUsd: toU64(args.collateralPriceUsd, "collateralPriceUsd"),
+            positionId: toU64(args.positionId, "positionId"),
         },
         typeArguments: [withLp(client, args.lpType)],
     })(tx);
@@ -44,10 +52,10 @@ export async function getOrder(client, args) {
         arguments: {
             marketRegistry: tx.object(client.config.packages.waterx_perp.market_registry_wlp),
             ticker: args.ticker,
-            basePriceUsd: args.basePriceUsd,
-            orderTypeTag: args.orderTypeTag,
-            triggerPrice: args.triggerPrice,
-            orderId: args.orderId,
+            basePriceUsd: toU64(args.basePriceUsd, "basePriceUsd"),
+            orderTypeTag: toU8(args.orderTypeTag, "orderTypeTag"),
+            triggerPrice: toU128(args.triggerPrice, "triggerPrice"),
+            orderId: toU64(args.orderId, "orderId"),
         },
         typeArguments: [withLp(client, args.lpType)],
     })(tx);
@@ -60,9 +68,9 @@ export async function getMarketOrders(client, args) {
         arguments: {
             marketRegistry: tx.object(client.config.packages.waterx_perp.market_registry_wlp),
             ticker: args.ticker,
-            basePriceUsd: args.basePriceUsd ?? 0n,
-            cursor: args.cursor ?? 0n,
-            pageSize: args.pageSize ?? 100n,
+            basePriceUsd: toU64(args.basePriceUsd ?? 0n, "basePriceUsd"),
+            cursor: toU64(args.cursor ?? 0n, "cursor"),
+            pageSize: toU64(args.pageSize ?? 100n, "pageSize"),
         },
         typeArguments: [withLp(client, args.lpType)],
     })(tx);
@@ -94,10 +102,10 @@ export async function getMarketPositions(client, args) {
             marketRegistry: tx.object(client.config.packages.waterx_perp.market_registry_wlp),
             ticker: args.ticker,
             pool: tx.object(client.config.packages.wlp.wlp_pool),
-            basePriceUsd: args.basePriceUsd,
-            collateralPriceUsd: args.collateralPriceUsd ?? 0n,
-            cursor: args.cursor ?? 0n,
-            pageSize: args.pageSize ?? 100n,
+            basePriceUsd: toU64(args.basePriceUsd, "basePriceUsd"),
+            collateralPriceUsd: toU64(args.collateralPriceUsd ?? 0n, "collateralPriceUsd"),
+            cursor: toU64(args.cursor ?? 0n, "cursor"),
+            pageSize: toU64(args.pageSize ?? 100n, "pageSize"),
         },
         typeArguments: [withLp(client, args.lpType)],
     })(tx);
@@ -130,8 +138,8 @@ export async function getAccountPositions(client, args) {
             ticker: args.ticker,
             pool: tx.object(client.config.packages.wlp.wlp_pool),
             wxaRegistry: tx.object(client.config.packages.waterx_account.account_registry),
-            basePriceUsd: args.basePriceUsd,
-            collateralPriceUsd: args.collateralPriceUsd ?? 0n,
+            basePriceUsd: toU64(args.basePriceUsd, "basePriceUsd"),
+            collateralPriceUsd: toU64(args.collateralPriceUsd ?? 0n, "collateralPriceUsd"),
             accountObjectAddress: args.accountObjectAddress,
         },
         typeArguments: [withLp(client, args.lpType)],
@@ -145,7 +153,7 @@ export async function getAccountOrders(client, args) {
         arguments: {
             marketRegistry: tx.object(client.config.packages.waterx_perp.market_registry_wlp),
             ticker: args.ticker,
-            basePriceUsd: args.basePriceUsd ?? 0n,
+            basePriceUsd: toU64(args.basePriceUsd ?? 0n, "basePriceUsd"),
             accountObjectAddress: args.accountObjectAddress,
         },
         typeArguments: [withLp(client, args.lpType)],
@@ -158,8 +166,8 @@ export async function getRedeemRequests(client, args = {}) {
         package: client.config.packages.waterx_perp_view.published_at,
         arguments: {
             pool: tx.object(client.config.packages.wlp.wlp_pool),
-            cursor: args.cursor ?? 0n,
-            pageSize: args.pageSize ?? 100n,
+            cursor: toU64(args.cursor ?? 0n, "cursor"),
+            pageSize: toU64(args.pageSize ?? 100n, "pageSize"),
         },
         typeArguments: [withLp(client, args.lpType)],
     })(tx);

package/dist/src/perp/index.d.ts

@@ -1,11 +1,15 @@
 export { PerpClient } from "./client.ts";
 export type { CreateClientOptions } from "./client.ts";
-export { PYTH_DEFAULTS, PYTH_PRO_DEFAULTS, WORMHOLE_DEFAULTS, clearConfigCache, loadConfig, } from "./config.ts";
-export type { BasePackageEntry, ConstantFeedEntry, WaterxReferralPackage, LoadConfigOptions, NativeCustodyAsset, NativeCustodyPackage, PythGeneration, PythInfraConfig, PythLazerRulePackage, PythRulePackage, PythSponsorRulePackage, SupraFeedEntry, SupraRulePackage, TestnetFaucetPackage, TrustedEmitterRow, WaterXConfig, WaterXPackages, WaterxCreditPackage, WaterxOraclePackage, WaterxPerpMarketEntry, WaterxPerpPackage, WaterxStakingPackage, WithdrawalQueuePackage, WlpPackage, WormholeBridgePackage, WormholeInfraConfig, WxaAccountPackage, } from "./config.ts";
-export { ACTION_ADD_PRE_ORDER, ACTION_CANCEL_ORDER, ACTION_CANCEL_PRE_ORDER, ACTION_CLOSE_POSITION, ACTION_DECREASE_POSITION, ACTION_DEPOSIT_COLLATERAL, ACTION_INCREASE_POSITION, ACTION_LIQUIDATE, ACTION_OPEN_POSITION, ACTION_PLACE_ORDER, ACTION_UPDATE_ORDER, ACTION_WITHDRAW_COLLATERAL, BPS_SCALE, CRYPTO_FEE_RATE, DOUBLE_SCALE, DRY_RUN_SENDER, FLOAT_SCALE, MAINTENANCE_MARGIN_RATE, ORDER_LIMIT_BUY, ORDER_LIMIT_SELL, ORDER_STOP_BUY, ORDER_STOP_SELL, ORDER_TAG_WILDCARD, PERM_ALL, PERM_ALL_TRADING, PERM_CANCEL_ORDER, PERM_CLOSE_POSITION, PERM_DECREASE_POSITION, PERM_DEPOSIT_COLLATERAL, PERM_INCREASE_POSITION, PERM_MINT_WLP, PERM_OPEN_POSITION, PERM_PLACE_ORDER, PERM_REDEEM_WLP, PERM_WITHDRAW_COLLATERAL, STAKING_PERM_DEPOSIT_STAKE, STAKING_PERM_REDEEM_STAKE, STAKING_PERM_CLAIM_REWARD, STAKING_PERM_ALL, STOCK_FEE_RATE, MS_PER_YEAR, SUI_DECIMALS, WLP_DECIMALS, COLLATERAL_DECIMALS, TOKEN_DECIMALS, } from "./constants.ts";
+export { PYTH_DEFAULTS, WORMHOLE_DEFAULTS, clearConfigCache, loadConfig } from "./config.ts";
+export type { BasePackageEntry, ConstantFeedEntry, WaterxReferralPackage, LoadConfigOptions, NativeCustodyAsset, NativeCustodyPackage, PythFetchPolicy, PythInfraConfig, PythLazerRulePackage, PythRulePackage, PythSponsorRulePackage, SupraFeedEntry, SupraRulePackage, TestnetFaucetPackage, WaterXConfig, WaterXPackages, WaterxCreditPackage, WaterxOraclePackage, WaterxPerpMarketEntry, WaterxPerpPackage, WaterxStakingPackage, WithdrawalQueuePackage, WlpPackage, WormholeBridgePackage, WormholeInfraConfig, WxaAccountPackage, } from "./config.ts";
+export { ACTION_ADD_PRE_ORDER, ACTION_CANCEL_ORDER, ACTION_CANCEL_PRE_ORDER, ACTION_CLOSE_POSITION, ACTION_DECREASE_POSITION, ACTION_DEPOSIT_COLLATERAL, ACTION_INCREASE_POSITION, ACTION_LIQUIDATE, ACTION_OPEN_POSITION, ACTION_PLACE_ORDER, ACTION_UPDATE_ORDER, ACTION_WITHDRAW_COLLATERAL, BPS_SCALE, DOUBLE_SCALE, DRY_RUN_SENDER, FLOAT_SCALE, ORDER_LIMIT_BUY, ORDER_LIMIT_SELL, ORDER_STOP_BUY, ORDER_STOP_SELL, ORDER_TAG_WILDCARD, PERM_ALL, PERM_ALL_TRADING, PERM_CANCEL_ORDER, PERM_CLOSE_POSITION, PERM_DECREASE_POSITION, PERM_DEPOSIT_COLLATERAL, PERM_INCREASE_POSITION, PERM_MINT_WLP, PERM_OPEN_POSITION, PERM_PLACE_ORDER, PERM_REDEEM_WLP, PERM_WITHDRAW_COLLATERAL, STAKING_PERM_DEPOSIT_STAKE, STAKING_PERM_REDEEM_STAKE, STAKING_PERM_CLAIM_REWARD, STAKING_PERM_ALL, MS_PER_MINUTE, MS_PER_HOUR, MS_PER_YEAR, SUI_DECIMALS, WLP_DECIMALS, COLLATERAL_DECIMALS, TOKEN_DECIMALS, } from "./constants.ts";
 export type { Network } from "./constants.ts";
 export { getMarketTickers, getCollateralAssets } from "../utils/config.ts";
-export { annualizedApyFromRatio, annualizeFundingRate, calcBorrowRate, calcBorrowRateAccrual, calcDynamicFeeBps, calcEffectiveCollateralUsd, calcEstLiqPrice, calcFee, calcFundingFeeUsd, calcFundingRate, calcImpactFeeRate, calcLeverage, calcMaxReducibleCollateralUsd, calcNotional, calcPositionBorrowFee, calcTokenUtilizationBps, calcTotalTradingFeeRate, calcUnrealizedPnl, calcWlpIncentiveApy, calcWlpMintOut, calcWlpPrice, calcWlpRedeemOut, decodeFundingIndexDelta, rawPrice, } from "../utils/math.ts";
+export { annualizedApyFromRatio, annualizeFundingRate, calcBorrowRate, calcBorrowRateAccrual, calcDynamicFeeBps, calcEffectiveCollateralUsd, calcEstLiqPrice, calcEstLiqPriceRaw, calcFee, calcFundingFeeUsd, calcFundingRate, calcImpactFeeRate, calcLeverage, calcMaxReducibleCollateralUsd, calcNotional, calcPositionBorrowFee, calcRealLiqNetCostUsd, calcTokenUtilizationBps, calcTotalTradingFeeRate, calcUnrealizedPnl, calcViewEstLiqFeesUsd, calcWlpIncentiveApy, calcWlpMintOut, calcWlpPrice, calcWlpRedeemOut, decodeFundingIndexDelta, rawPrice, } from "../utils/math.ts";
+export type { ExactDecimalUsd, LiqFeeBundle, RawPriceInput } from "../utils/math.ts";
+export { formatFundingInterval } from "../utils/format.ts";
+export { calcEstLiqPriceRawFromView } from "./liq-view.ts";
+export type { EstLiqPriceViewOpts } from "./liq-view.ts";
 export * from "./user/index.ts";
 export * from "./tx-builders.ts";
 export * from "./fetch.ts";

package/dist/src/perp/index.js

@@ -1,11 +1,13 @@
 // ======== Core ========
 export { PerpClient } from "./client.js";
-export { PYTH_DEFAULTS, PYTH_PRO_DEFAULTS, WORMHOLE_DEFAULTS, clearConfigCache, loadConfig, } from "./config.js";
+export { PYTH_DEFAULTS, WORMHOLE_DEFAULTS, clearConfigCache, loadConfig } from "./config.js";
 // ======== Constants & enums ========
-export { ACTION_ADD_PRE_ORDER, ACTION_CANCEL_ORDER, ACTION_CANCEL_PRE_ORDER, ACTION_CLOSE_POSITION, ACTION_DECREASE_POSITION, ACTION_DEPOSIT_COLLATERAL, ACTION_INCREASE_POSITION, ACTION_LIQUIDATE, ACTION_OPEN_POSITION, ACTION_PLACE_ORDER, ACTION_UPDATE_ORDER, ACTION_WITHDRAW_COLLATERAL, BPS_SCALE, CRYPTO_FEE_RATE, DOUBLE_SCALE, DRY_RUN_SENDER, FLOAT_SCALE, MAINTENANCE_MARGIN_RATE, ORDER_LIMIT_BUY, ORDER_LIMIT_SELL, ORDER_STOP_BUY, ORDER_STOP_SELL, ORDER_TAG_WILDCARD, PERM_ALL, PERM_ALL_TRADING, PERM_CANCEL_ORDER, PERM_CLOSE_POSITION, PERM_DECREASE_POSITION, PERM_DEPOSIT_COLLATERAL, PERM_INCREASE_POSITION, PERM_MINT_WLP, PERM_OPEN_POSITION, PERM_PLACE_ORDER, PERM_REDEEM_WLP, PERM_WITHDRAW_COLLATERAL, STAKING_PERM_DEPOSIT_STAKE, STAKING_PERM_REDEEM_STAKE, STAKING_PERM_CLAIM_REWARD, STAKING_PERM_ALL, STOCK_FEE_RATE, MS_PER_YEAR, SUI_DECIMALS, WLP_DECIMALS, COLLATERAL_DECIMALS, TOKEN_DECIMALS, } from "./constants.js";
+export { ACTION_ADD_PRE_ORDER, ACTION_CANCEL_ORDER, ACTION_CANCEL_PRE_ORDER, ACTION_CLOSE_POSITION, ACTION_DECREASE_POSITION, ACTION_DEPOSIT_COLLATERAL, ACTION_INCREASE_POSITION, ACTION_LIQUIDATE, ACTION_OPEN_POSITION, ACTION_PLACE_ORDER, ACTION_UPDATE_ORDER, ACTION_WITHDRAW_COLLATERAL, BPS_SCALE, DOUBLE_SCALE, DRY_RUN_SENDER, FLOAT_SCALE, ORDER_LIMIT_BUY, ORDER_LIMIT_SELL, ORDER_STOP_BUY, ORDER_STOP_SELL, ORDER_TAG_WILDCARD, PERM_ALL, PERM_ALL_TRADING, PERM_CANCEL_ORDER, PERM_CLOSE_POSITION, PERM_DECREASE_POSITION, PERM_DEPOSIT_COLLATERAL, PERM_INCREASE_POSITION, PERM_MINT_WLP, PERM_OPEN_POSITION, PERM_PLACE_ORDER, PERM_REDEEM_WLP, PERM_WITHDRAW_COLLATERAL, STAKING_PERM_DEPOSIT_STAKE, STAKING_PERM_REDEEM_STAKE, STAKING_PERM_CLAIM_REWARD, STAKING_PERM_ALL, MS_PER_MINUTE, MS_PER_HOUR, MS_PER_YEAR, SUI_DECIMALS, WLP_DECIMALS, COLLATERAL_DECIMALS, TOKEN_DECIMALS, } from "./constants.js";
 // ======== Utilities ========
 export { getMarketTickers, getCollateralAssets } from "../utils/config.js";
-export { annualizedApyFromRatio, annualizeFundingRate, calcBorrowRate, calcBorrowRateAccrual, calcDynamicFeeBps, calcEffectiveCollateralUsd, calcEstLiqPrice, calcFee, calcFundingFeeUsd, calcFundingRate, calcImpactFeeRate, calcLeverage, calcMaxReducibleCollateralUsd, calcNotional, calcPositionBorrowFee, calcTokenUtilizationBps, calcTotalTradingFeeRate, calcUnrealizedPnl, calcWlpIncentiveApy, calcWlpMintOut, calcWlpPrice, calcWlpRedeemOut, decodeFundingIndexDelta, rawPrice, } from "../utils/math.js";
+export { annualizedApyFromRatio, annualizeFundingRate, calcBorrowRate, calcBorrowRateAccrual, calcDynamicFeeBps, calcEffectiveCollateralUsd, calcEstLiqPrice, calcEstLiqPriceRaw, calcFee, calcFundingFeeUsd, calcFundingRate, calcImpactFeeRate, calcLeverage, calcMaxReducibleCollateralUsd, calcNotional, calcPositionBorrowFee, calcRealLiqNetCostUsd, calcTokenUtilizationBps, calcTotalTradingFeeRate, calcUnrealizedPnl, calcViewEstLiqFeesUsd, calcWlpIncentiveApy, calcWlpMintOut, calcWlpPrice, calcWlpRedeemOut, decodeFundingIndexDelta, rawPrice, } from "../utils/math.js";
+export { formatFundingInterval } from "../utils/format.js";
+export { calcEstLiqPriceRawFromView } from "./liq-view.js";
 // ======== Transaction builders (user-side) ========
 export * from "./user/index.js";
 // ======== High-level Tx builders ========