@waterx/sdk 4.0.1 → 4.3.0

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

@@ -3,17 +3,17 @@
  * `waterx-config` repo (default: GitHub raw).
  *
  * The schema mirrors the canonical JSON layout one-to-one (each package
- * groups its own object IDs + per-ticker maps). External chain infra
- * (Pyth state, Wormhole state/core, Hermes & Wormholescan endpoints) is
- * **not** in the JSON — it lives in `PYTH_DEFAULTS` / `WORMHOLE_DEFAULTS`
- * below, keyed by network.
+ * groups its own object IDs + per-ticker maps). External chain infra is
+ * **not** in the JSON — each oracle source owns its own per-network table
+ * (`PYTH_CORE_INFRA` in `oracle/pyth.ts`, `LAZER_INFRA` in
+ * `oracle/rules/pyth-lazer-rule.ts`); Wormhole bridge infra lives in
+ * `WORMHOLE_DEFAULTS` below.
  */
 import type { AccountPackages, BasePackageEntry, WormholeInfraConfig } from "../account/config.ts";
 import type { OraclePackages } from "../oracle/config.ts";
 import type { Network } from "./constants.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, WaterxOraclePackage, } from "../oracle/config.ts";
-export { PYTH_DEFAULTS } from "../oracle/config.ts";
+export type { ConstantFeedEntry, OracleConfig, OraclePackages, PythAccessConfig, PythFetchPolicy, PythLazerRulePackage, PythRulePackage, PythSponsorRulePackage, SupraFeedEntry, SupraRulePackage, WaterxConstantRulePackage, WaterxAccessConfig, WaterxOraclePackage, WaterxRulePackage, } 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>;

package/dist/src/perp/config.js

@@ -3,23 +3,25 @@
  * `waterx-config` repo (default: GitHub raw).
  *
  * The schema mirrors the canonical JSON layout one-to-one (each package
- * groups its own object IDs + per-ticker maps). External chain infra
- * (Pyth state, Wormhole state/core, Hermes & Wormholescan endpoints) is
- * **not** in the JSON — it lives in `PYTH_DEFAULTS` / `WORMHOLE_DEFAULTS`
- * below, keyed by network.
+ * groups its own object IDs + per-ticker maps). External chain infra is
+ * **not** in the JSON — each oracle source owns its own per-network table
+ * (`PYTH_CORE_INFRA` in `oracle/pyth.ts`, `LAZER_INFRA` in
+ * `oracle/rules/pyth-lazer-rule.ts`); Wormhole bridge infra lives in
+ * `WORMHOLE_DEFAULTS` below.
  */
 import { fetchWithPolicy, rethrowExhaustedFetch } from "../oracle/update-fetch.js";
-export { PYTH_DEFAULTS } from "../oracle/config.js";
 // ============================================================================
-// Wormhole / Hermes — external chain infra, defaults by network
+// Wormhole — external chain infra, defaults by network
 // ============================================================================
 //
-// `PythInfraConfig` + `PYTH_DEFAULTS` live in `oracle/config.ts` (shared infra)
-// and are re-exported at the top of this file.
+// Oracle-source infra lives with each source (`PYTH_CORE_INFRA` in
+// `oracle/pyth.ts`, `LAZER_INFRA` in `oracle/rules/pyth-lazer-rule.ts`);
+// `client.pyth` is the caller-supplied access slice only (`PythAccessConfig`,
+// re-exported at the top of this file).
 // `WormholeInfraConfig` is defined in `account/config.ts` (funding base) and
 // re-exported at the top of this file. `state_id` is the same shared Sui
 // Wormhole `State` object Pyth uses (kept in sync with
-// `PYTH_DEFAULTS[*].wormhole_state_id`).
+// `PYTH_CORE_INFRA[*].wormhole_state_id`).
 export const WORMHOLE_DEFAULTS = {
     MAINNET: {
         state_id: "0xaeab97f96cf9877fee2883315d459552b2b921edc16d7ceac6eab944dd88919c",

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,15 +1,19 @@
 export { PerpClient } from "./client.ts";
 export type { CreateClientOptions } from "./client.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, 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 { WORMHOLE_DEFAULTS, clearConfigCache, loadConfig } from "./config.ts";
+export type { BasePackageEntry, ConstantFeedEntry, WaterxReferralPackage, LoadConfigOptions, NativeCustodyAsset, NativeCustodyPackage, PythAccessConfig, PythFetchPolicy, 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";
-export { FetchPolicyError, LazerApiKeyMissingError, OracleFeeSourceUnavailableError, OracleSourceNotImplementedError, PythCache, aggregateTicker, aggregateTickerWithConstant, aggregateTickerWithPyth, buildPythPriceUpdateCalls, fetchPriceFeedsUpdateData, refreshOraclePrices, updatePythPrices, } from "../oracle/index.ts";
+export { FetchPolicyError, LazerApiKeyMissingError, OracleFeeSourceUnavailableError, OracleSourceNotImplementedError, PythCache, aggregateTicker, aggregateTickerWithConstant, aggregateTickerWithPyth, buildPythPriceUpdateCalls, fetchPriceFeedsUpdateData, pythCoreHermesEndpoint, pythProHermesEndpoint, resolveHermesReadEndpoint, waterxQuoteCenterEndpoint, refreshOraclePrices, updatePythPrices, } from "../oracle/index.ts";
 export type { FetchPolicy, OracleFeeSource, OracleSource, UpdateDataProvider, } from "../oracle/index.ts";
 export { fetchDepositVaa, fetchVaa, listBridgeWithdrawalVaas, listVaasByEmitter, padEvmEmitter, toWormholescanEmitter, vaaBase64ToBytes, vaaBase64ToHex, vaaBytesToBase64, waitForVaa, } from "../account/funding/wormhole.ts";
 export type { VaaListItem, VaaResponse, WormholescanOptions } from "../account/funding/wormhole.ts";

package/dist/src/perp/index.js

@@ -1,11 +1,13 @@
 // ======== Core ========
 export { PerpClient } from "./client.js";
-export { PYTH_DEFAULTS, WORMHOLE_DEFAULTS, clearConfigCache, loadConfig } from "./config.js";
+export { 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 ========
@@ -13,7 +15,7 @@ export * from "./tx-builders.js";
 // ======== Read-only queries ========
 export * from "./fetch.js";
 // ======== Oracle utilities (Pyth source + rule aggregation) ========
-export { FetchPolicyError, LazerApiKeyMissingError, OracleFeeSourceUnavailableError, OracleSourceNotImplementedError, PythCache, aggregateTicker, aggregateTickerWithConstant, aggregateTickerWithPyth, buildPythPriceUpdateCalls, fetchPriceFeedsUpdateData, refreshOraclePrices, updatePythPrices, } from "../oracle/index.js";
+export { FetchPolicyError, LazerApiKeyMissingError, OracleFeeSourceUnavailableError, OracleSourceNotImplementedError, PythCache, aggregateTicker, aggregateTickerWithConstant, aggregateTickerWithPyth, buildPythPriceUpdateCalls, fetchPriceFeedsUpdateData, pythCoreHermesEndpoint, pythProHermesEndpoint, resolveHermesReadEndpoint, waterxQuoteCenterEndpoint, refreshOraclePrices, updatePythPrices, } from "../oracle/index.js";
 // ======== Wormhole / Wormholescan utilities (credit bridge) ========
 export { fetchDepositVaa, fetchVaa, listBridgeWithdrawalVaas, listVaasByEmitter, padEvmEmitter, toWormholescanEmitter, vaaBase64ToBytes, vaaBase64ToHex, vaaBytesToBase64, waitForVaa, } from "../account/funding/wormhole.js";
 // ======== Generated BCS types (sui-ts-codegen) ========

package/dist/src/perp/liq-view.d.ts

@@ -0,0 +1,64 @@
+/**
+ * View→raw adapter for the canonical liquidation-price estimate.
+ *
+ * `calcEstLiqPriceRaw` (`utils/math.ts`) takes the twelve RAW on-chain values
+ * the Move view takes, so every consumer that already holds a fetched
+ * `PositionDataView` row had to hand-map nine of them 1:1 off the row (the
+ * other three are the probe prices + maintenance margin, which the row does not
+ * carry) — and hand-carry the price invariant below in prose. That mapping is
+ * the SDK's job, so it lives here.
+ *
+ * ## Why perp-side and not in `utils/math.ts`
+ *
+ * `PositionDataView` is a perp read type (`perp/fetch/positions.ts`, decoded
+ * from the `waterx_perp_view` BCS struct). `utils/` is the shared base that
+ * `perp/` imports FROM — pulling a perp view type down into `utils/math.ts`
+ * would invert that direction and couple the line-agnostic math to the perp
+ * read layer. So the pure math stays in `utils/`, and the adapter that knows
+ * the perp row shape sits here, one layer up. Kept out of
+ * `perp/fetch/positions.ts` too: that module is transport (build PTB →
+ * simulate → decode), this is a pure field mapping with no client.
+ */
+import type { PositionDataView } from "./fetch/positions.ts";
+/**
+ * Probe prices the position row was READ AT — see the invariant on
+ * {@link calcEstLiqPriceRawFromView}. Whole-dollar u64, exactly as passed to
+ * the `perp/fetch` read (`WholeDollarUsdPrice`), plus the market's maintenance
+ * margin, which lives on `MarketData`, not on the position row.
+ */
+export type EstLiqPriceViewOpts = {
+    /** `MarketData.maintenance_margin` — raw 1e9-scaled Float value. */
+    maintenanceMarginRaw: bigint;
+    /** The SAME `basePriceUsd` passed to the read that produced `position`. */
+    basePriceUsd: bigint;
+    /** The SAME `collateralPriceUsd` passed to the read that produced `position`. */
+    collateralPriceUsd: bigint;
+};
+/**
+ * Estimated liquidation price from a fetched `PositionDataView` row —
+ * bit-identical to that row's `est_liq_price`.
+ *
+ * Maps the row's nine raw fields onto {@link calcEstLiqPriceRaw} (the op-for-op
+ * mirror of `view.move::calculate_est_liq_price`) and takes the remaining
+ * three — the two probe prices plus the market's maintenance margin — from
+ * `opts`. Returns the raw 1e9-scaled u128 price; `0n` = already liquidatable /
+ * zero size.
+ *
+ * ## INVARIANT — the prices must be the ones the row was READ AT
+ *
+ * `opts.basePriceUsd` / `opts.collateralPriceUsd` MUST be the same whole-dollar
+ * values you passed to the `perp/fetch` read that produced `position`
+ * (`getPosition`, `getMarketPositions`, `getAccountPositions`, …).
+ *
+ * `PositionDataView` does NOT carry the probe prices it was computed at, so
+ * NOTHING — not this adapter, not the type system — can check this for you.
+ * Feed different prices and the row's fee / notional-derived fields were
+ * computed against one price while the estimate is computed against another:
+ * the result is a plausible-looking number that silently disagrees with
+ * `position.est_liq_price`. Thread the prices through from the read call site;
+ * never re-fetch or re-guess them here.
+ *
+ * @throws RangeError via `calcEstLiqPriceRaw` when any raw value is negative or
+ *   `collateral_decimal` is outside `[0, 19]`.
+ */
+export declare function calcEstLiqPriceRawFromView(position: PositionDataView, opts: EstLiqPriceViewOpts): bigint;

package/dist/src/perp/liq-view.js

@@ -0,0 +1,71 @@
+/**
+ * View→raw adapter for the canonical liquidation-price estimate.
+ *
+ * `calcEstLiqPriceRaw` (`utils/math.ts`) takes the twelve RAW on-chain values
+ * the Move view takes, so every consumer that already holds a fetched
+ * `PositionDataView` row had to hand-map nine of them 1:1 off the row (the
+ * other three are the probe prices + maintenance margin, which the row does not
+ * carry) — and hand-carry the price invariant below in prose. That mapping is
+ * the SDK's job, so it lives here.
+ *
+ * ## Why perp-side and not in `utils/math.ts`
+ *
+ * `PositionDataView` is a perp read type (`perp/fetch/positions.ts`, decoded
+ * from the `waterx_perp_view` BCS struct). `utils/` is the shared base that
+ * `perp/` imports FROM — pulling a perp view type down into `utils/math.ts`
+ * would invert that direction and couple the line-agnostic math to the perp
+ * read layer. So the pure math stays in `utils/`, and the adapter that knows
+ * the perp row shape sits here, one layer up. Kept out of
+ * `perp/fetch/positions.ts` too: that module is transport (build PTB →
+ * simulate → decode), this is a pure field mapping with no client.
+ */
+import { calcEstLiqPriceRaw } from "../utils/math.js";
+/**
+ * Estimated liquidation price from a fetched `PositionDataView` row —
+ * bit-identical to that row's `est_liq_price`.
+ *
+ * Maps the row's nine raw fields onto {@link calcEstLiqPriceRaw} (the op-for-op
+ * mirror of `view.move::calculate_est_liq_price`) and takes the remaining
+ * three — the two probe prices plus the market's maintenance margin — from
+ * `opts`. Returns the raw 1e9-scaled u128 price; `0n` = already liquidatable /
+ * zero size.
+ *
+ * ## INVARIANT — the prices must be the ones the row was READ AT
+ *
+ * `opts.basePriceUsd` / `opts.collateralPriceUsd` MUST be the same whole-dollar
+ * values you passed to the `perp/fetch` read that produced `position`
+ * (`getPosition`, `getMarketPositions`, `getAccountPositions`, …).
+ *
+ * `PositionDataView` does NOT carry the probe prices it was computed at, so
+ * NOTHING — not this adapter, not the type system — can check this for you.
+ * Feed different prices and the row's fee / notional-derived fields were
+ * computed against one price while the estimate is computed against another:
+ * the result is a plausible-looking number that silently disagrees with
+ * `position.est_liq_price`. Thread the prices through from the read call site;
+ * never re-fetch or re-guess them here.
+ *
+ * @throws RangeError via `calcEstLiqPriceRaw` when any raw value is negative or
+ *   `collateral_decimal` is outside `[0, 19]`.
+ */
+export function calcEstLiqPriceRawFromView(position, opts) {
+    return calcEstLiqPriceRaw({
+        isLong: position.is_long,
+        sizeRaw: BigInt(position.size),
+        avgPriceRaw: BigInt(position.average_price),
+        collateralAmountRaw: BigInt(position.collateral_amount),
+        collateralDecimal: position.collateral_decimal,
+        basePriceUsd: opts.basePriceUsd,
+        collateralPriceUsd: opts.collateralPriceUsd,
+        maintenanceMarginRaw: opts.maintenanceMarginRaw,
+        // The view pre-combines accrued + unrealized into `borrow_fee` / `funding_fee`
+        // — take those, NOT the `unrealized_*` pair, which would UNDER-count:
+        // `view.move` sets `borrow_fee = calculate_borrow_fee(cumul) +
+        // unrealized_borrow_fee`, and `position.move::calculate_funding_fee` returns
+        // the unrealized leg combined with the current period's, so the row's
+        // `unrealized_*` fields are strict SUBSETS of the combined pair.
+        borrowFeeRaw: BigInt(position.borrow_fee),
+        fundingSign: position.funding_fee_positive,
+        fundingFeeRaw: BigInt(position.funding_fee),
+        tradingFeeRaw: BigInt(position.unrealized_trading_fee),
+    });
+}

package/dist/src/perp/user/order.d.ts

@@ -7,6 +7,19 @@
  *
  * 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 type { Transaction, TransactionArgument } from "@mysten/sui/transactions";
 import type { PerpClient } from "../client.ts";