@waterx/sdk 2.4.0 → 3.0.0

package/dist/src/{client.js → perp/config-view.js}

@@ -1,100 +1,28 @@
 /**
- * WaterX Protocol client.
+ * Perp config-schema views — read-only lookups over the parsed `waterx-config`
+ * JSON, with no transport dependency.
  *
- * Initialization is async — config is fetched from the canonical
- * `waterx-config` JSON (default: GitHub raw). See `WaterXClient.create()`.
+ * Split off the transport client (`PerpClient`) so the two responsibilities stay
+ * separate: `BaseLineClient` owns the gRPC half, this class owns the
+ * canonical-schema half. `PerpClient` composes one of these and delegates, so
+ * callers keep calling `client.getMarket(...)` / `client.wlpType()` unchanged.
+ * Tested in isolation against a plain config object — no network needed.
  */
-import { SuiGrpcClient } from "@mysten/sui/grpc";
-import { loadConfig, PYTH_DEFAULTS, WORMHOLE_DEFAULTS, } from "./config.js";
-// ======== gRPC base URLs by network ========
-const DEFAULT_GRPC_URLS = {
-    MAINNET: "https://fullnode.mainnet.sui.io:443",
-    TESTNET: "https://fullnode.testnet.sui.io:443",
-};
-export class WaterXClient {
-    /** gRPC client — all RPC including `simulateTransaction`. */
-    grpcClient;
-    /** Network identifier in upper case (`MAINNET` / `TESTNET`). */
-    network;
-    /** Parsed canonical `waterx-config` JSON. */
-    config;
-    /** Pyth infra (network defaults unless overridden in JSON). */
-    pyth;
-    /** Wormhole infra for the credit bridge (network defaults unless overridden). */
-    wormhole;
-    constructor(network, config, opts = {}) {
-        this.network = network;
-        this.config = config;
-        this.pyth = config.pyth ?? PYTH_DEFAULTS[network];
-        this.wormhole = config.wormhole ?? WORMHOLE_DEFAULTS[network];
-        const grpcUrl = opts.grpcUrl ?? config.grpcUrl ?? DEFAULT_GRPC_URLS[network];
-        this.grpcClient = new SuiGrpcClient({
-            baseUrl: grpcUrl,
-            network: network.toLowerCase(),
-        });
-    }
-    /**
-     * Async factory: fetches the deployment config for `network` and returns
-     * a ready-to-use client. Pass `opts.cache=true` to memoize the JSON.
-     */
-    static async create(network, opts = {}) {
-        const config = await loadConfig(network, opts);
-        return new WaterXClient(network, config, { grpcUrl: opts.grpcUrl });
-    }
-    static mainnet(opts = {}) {
-        return WaterXClient.create("MAINNET", opts);
-    }
-    static testnet(opts = {}) {
-        return WaterXClient.create("TESTNET", opts);
-    }
-    // ========================================================
-    // gRPC convenience wrappers
-    // ========================================================
-    getObject(objectId) {
-        return this.grpcClient.getObject({ objectId });
-    }
-    getObjects(objectIds) {
-        return this.grpcClient.getObjects({ objectIds });
-    }
-    listOwnedObjects(owner) {
-        return this.grpcClient.listOwnedObjects({ owner });
-    }
-    listCoins(params) {
-        return this.grpcClient.listCoins(params);
-    }
-    getBalance(params) {
-        return this.grpcClient.getBalance(params);
-    }
-    listDynamicFields(parentId) {
-        return this.grpcClient.listDynamicFields({ parentId });
-    }
-    getDynamicField(parentId, name) {
-        return this.grpcClient.getDynamicField({ parentId, name });
-    }
-    waitForTransaction(digest) {
-        return this.grpcClient.waitForTransaction({ digest });
-    }
-    async simulate(tx) {
-        return this.grpcClient.simulateTransaction({
-            transaction: tx,
-            include: { commandResults: true },
-        });
-    }
-    async signAndExecuteTransaction(params) {
-        return this.grpcClient.signAndExecuteTransaction(params);
-    }
-    // ========================================================
-    // Shorthand accessors (canonical-schema lookups)
-    // ========================================================
-    /** All package IDs (`published_at`) keyed by package name. */
-    packageIds() {
-        const out = {};
-        for (const [name, pkg] of Object.entries(this.config.packages)) {
-            if (pkg && typeof pkg === "object" && "published_at" in pkg && pkg.published_at) {
-                out[name] = pkg.published_at;
-            }
-        }
-        return out;
+export class PerpConfigView {
+    getConfig;
+    getWormhole;
+    // Config/wormhole are read through providers, not captured by value, so a later
+    // `client.config = …` reassignment stays live (matches the pre-split behaviour
+    // where every lookup read `this.config` fresh).
+    constructor(getConfig, getWormhole) {
+        this.getConfig = getConfig;
+        this.getWormhole = getWormhole;
+    }
+    get config() {
+        return this.getConfig();
+    }
+    get wormhole() {
+        return this.getWormhole();
     }
     /** `waterx_perp.markets[ticker]`, throws if unknown. */
     getMarket(ticker) {
@@ -224,7 +152,7 @@ export class WaterXClient {
     }
     /**
      * Sui Wormhole `State` object id — prefers the per-deployment
-     * `wormhole_bridge.wormhole_state`, falls back to `client.wormhole`.
+     * `wormhole_bridge.wormhole_state`, falls back to the line's `wormhole` infra.
      */
     wormholeStateId() {
         return this.config.packages.wormhole_bridge?.wormhole_state ?? this.wormhole.state_id;

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

@@ -0,0 +1,126 @@
+/**
+ * WaterX deployment config — fetched at client init from the canonical
+ * `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.
+ */
+import type { AccountPackages, BasePackageEntry, WormholeInfraConfig } from "../account/config.ts";
+import type { OraclePackages, PythInfraConfig } 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, PythInfraConfig, PythRulePackage, PythSponsorRulePackage, SupraFeedEntry, SupraRulePackage, WaterxConstantRulePackage, WaterxOraclePackage, } from "../oracle/config.ts";
+export { PYTH_DEFAULTS } from "../oracle/config.ts";
+export interface WaterxPerpMarketEntry {
+    market: string;
+    config: string;
+}
+export interface WaterxPerpPackage extends BasePackageEntry {
+    admin_cap: string;
+    global_config: string;
+    market_registry_wlp: string;
+    markets: Record<string, WaterxPerpMarketEntry>;
+}
+export interface RewarderEntry {
+    /** `Rewarder<STAKE, R>` shared object ID. */
+    rewarder_id: string;
+    /** Fully-qualified reward coin Move type (e.g. `0x2::sui::SUI`). */
+    coin_type: string;
+    /** Reward coin display decimals. */
+    decimals: number;
+}
+export interface WaterxStakingPackage extends BasePackageEntry {
+    admin_cap?: string;
+    /** Map of stake-type alias (e.g. `"WLP"`) → `StakingPool<STAKE>` shared object ID. */
+    pools?: Record<string, string>;
+    /**
+     * Map of stake-type alias → reward-token alias → rewarder metadata.
+     * Reward-token alias is display-only (e.g. `"SUI"`, `"MOCK_SUI"`); the
+     * fully-qualified coin Move type lives on the {@link RewarderEntry}.
+     */
+    rewarders?: Record<string, Record<string, RewarderEntry>>;
+}
+export interface WlpPackage extends BasePackageEntry {
+    metadata_cap?: string;
+    currency?: string;
+    wlp_pool: string;
+    /** Optional `WlpAum<LP>` shared object; required by `mint_wlp` / `settle_redeem`. */
+    wlp_aum?: string;
+    /** Map of oracle ticker → fully-qualified Move type registered via `lp_pool::add_token`. */
+    pool_tokens: Record<string, string>;
+}
+export interface MockCoinPackage extends BasePackageEntry {
+    currency?: string;
+    treasury_cap?: string;
+    metadata_cap?: string;
+}
+export interface TestnetFaucetPackage {
+    published_at: string;
+    whitelist?: string[];
+    faucet?: string;
+}
+export interface WaterXPackages extends AccountPackages, OraclePackages {
+    waterx_perp: WaterxPerpPackage;
+    waterx_perp_view: BasePackageEntry;
+    waterx_staking?: WaterxStakingPackage;
+    wlp: WlpPackage;
+    testnet_faucet?: TestnetFaucetPackage;
+    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>;
+export interface WaterXConfig {
+    /** Absent on credit-only deployment files. */
+    network?: "mainnet" | "testnet";
+    chain_id?: string | number | null;
+    /** 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). */
+    coin_registry?: string;
+    /** Per-module credit supply caps (credit deployments). */
+    credit_caps?: Record<string, string>;
+    /** Deploy-script phase completion flags (credit deployments). */
+    done?: Record<string, boolean>;
+}
+export interface LoadConfigOptions {
+    /**
+     * Override the default config URL. Use this to point at a staging branch
+     * (`?ref=staging`) or a local mirror during development. Takes precedence
+     * over {@link configRef}.
+     */
+    configUrl?: string;
+    /**
+     * Pin the canonical config to a specific git ref — a commit SHA, branch,
+     * or tag — instead of the default `main` branch. Resolves to
+     * `https://raw.githubusercontent.com/WaterXProtocol/waterx-config/<ref>/<network>.json`.
+     * Ignored when {@link configUrl} is set.
+     */
+    configRef?: string;
+    /**
+     * Reuse a previously-fetched config from the in-memory cache (keyed by
+     * the effective URL). Default: false (always fetch fresh).
+     */
+    cache?: boolean;
+    /** Optional fetch implementation (for tests or environments without global `fetch`). */
+    fetchImpl?: typeof fetch;
+    /** Optional request timeout in ms. Default 10_000. */
+    timeoutMs?: number;
+}
+/**
+ * Build the canonical config URL for `network`, optionally pinned to a
+ * specific git `ref` (commit SHA, branch, or tag). Defaults to `main`.
+ */
+export declare function defaultConfigUrl(network: Network, ref?: string): string;
+export declare function clearConfigCache(): void;
+export declare function loadConfig(network: Network, opts?: LoadConfigOptions): Promise<WaterXConfig>;

package/dist/src/{config.js → perp/config.js}

@@ -8,18 +8,17 @@
  * **not** in the JSON — it lives in `PYTH_DEFAULTS` / `WORMHOLE_DEFAULTS`
  * below, keyed by network.
  */
-export const PYTH_DEFAULTS = {
-    MAINNET: {
-        state_id: "0x1f9310238ee9298fb703c3419030b35b22bb1cc37113e3bb5007c99aec79e5b8",
-        wormhole_state_id: "0xaeab97f96cf9877fee2883315d459552b2b921edc16d7ceac6eab944dd88919c",
-        hermes_endpoint: "https://hermes.pyth.network",
-    },
-    TESTNET: {
-        state_id: "0x243759059f4c3111179da5878c12f68d612c21a8d54d85edc86164bb18be1c7c",
-        wormhole_state_id: "0x31358d198147da50db32eda2562951d53973a0c0ad5ed738e9b17d88b213d790",
-        hermes_endpoint: "https://hermes-beta.pyth.network",
-    },
-};
+export { PYTH_DEFAULTS } from "../oracle/config.js";
+// ============================================================================
+// Wormhole / Hermes — 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.
+// `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`).
 export const WORMHOLE_DEFAULTS = {
     MAINNET: {
         state_id: "0xaeab97f96cf9877fee2883315d459552b2b921edc16d7ceac6eab944dd88919c",

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

@@ -0,0 +1,49 @@
+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;
+export declare const PERM_DECREASE_POSITION = 8;
+export declare const PERM_PLACE_ORDER = 16;
+export declare const PERM_CANCEL_ORDER = 32;
+export declare const PERM_DEPOSIT_COLLATERAL = 64;
+export declare const PERM_WITHDRAW_COLLATERAL = 128;
+export declare const PERM_MINT_WLP = 256;
+export declare const PERM_REDEEM_WLP = 512;
+export declare const PERM_ALL_TRADING = 255;
+export declare const PERM_ALL = 65535;
+export declare const STAKING_PERM_DEPOSIT_STAKE: number;
+export declare const STAKING_PERM_REDEEM_STAKE: number;
+export declare const STAKING_PERM_CLAIM_REWARD: number;
+export declare const STAKING_PERM_ALL: number;
+export declare const ORDER_LIMIT_BUY = 0;
+export declare const ORDER_LIMIT_SELL = 1;
+export declare const ORDER_STOP_BUY = 2;
+export declare const ORDER_STOP_SELL = 3;
+/** Wildcard tag accepted by `cancel_order_request` — scans all 4 books. */
+export declare const ORDER_TAG_WILDCARD = 255;
+export declare const ACTION_OPEN_POSITION = 0;
+export declare const ACTION_CLOSE_POSITION = 1;
+export declare const ACTION_PLACE_ORDER = 2;
+export declare const ACTION_CANCEL_ORDER = 3;
+export declare const ACTION_DEPOSIT_COLLATERAL = 4;
+export declare const ACTION_WITHDRAW_COLLATERAL = 5;
+export declare const ACTION_LIQUIDATE = 6;
+export declare const ACTION_INCREASE_POSITION = 7;
+export declare const ACTION_DECREASE_POSITION = 8;
+export declare const ACTION_UPDATE_ORDER = 9;
+export declare const ACTION_CANCEL_PRE_ORDER = 10;
+export declare const ACTION_ADD_PRE_ORDER = 11;
+/**
+ * Well-known address of Sui's native funds-accumulator root shared object
+ * (`@0xacc` in the framework). Pass this to `request_deposit_from_funds<T>`
+ * to drain `Balance<T>` parked at an account's address. Defined in
+ * `account/constants.ts` (account-framework constant); re-exported here for
+ * back-compat.
+ */
+export { ACCUMULATOR_ROOT } from "../account/constants.ts";

package/dist/src/perp/constants.js

@@ -0,0 +1,61 @@
+// Perp-line domain constants (trading permissions / order tags / action codes /
+// fee rates / 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.
+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;
+export const PERM_INCREASE_POSITION = 4;
+export const PERM_DECREASE_POSITION = 8;
+export const PERM_PLACE_ORDER = 16;
+export const PERM_CANCEL_ORDER = 32;
+export const PERM_DEPOSIT_COLLATERAL = 64;
+export const PERM_WITHDRAW_COLLATERAL = 128;
+export const PERM_MINT_WLP = 256;
+export const PERM_REDEEM_WLP = 512;
+export const PERM_ALL_TRADING = 0xff;
+export const PERM_ALL = 0xffff;
+// ======== Staking Permission Bitmasks (matches waterx_staking.move) ========
+export const STAKING_PERM_DEPOSIT_STAKE = 1 << 0;
+export const STAKING_PERM_REDEEM_STAKE = 1 << 1;
+export const STAKING_PERM_CLAIM_REWARD = 1 << 2;
+export const STAKING_PERM_ALL = STAKING_PERM_DEPOSIT_STAKE | STAKING_PERM_REDEEM_STAKE | STAKING_PERM_CLAIM_REWARD;
+// ======== Order Type Tags ========
+export const ORDER_LIMIT_BUY = 0;
+export const ORDER_LIMIT_SELL = 1;
+export const ORDER_STOP_BUY = 2;
+export const ORDER_STOP_SELL = 3;
+/** Wildcard tag accepted by `cancel_order_request` — scans all 4 books. */
+export const ORDER_TAG_WILDCARD = 255;
+// ======== Action Type Constants (request.move) ========
+export const ACTION_OPEN_POSITION = 0;
+export const ACTION_CLOSE_POSITION = 1;
+export const ACTION_PLACE_ORDER = 2;
+export const ACTION_CANCEL_ORDER = 3;
+export const ACTION_DEPOSIT_COLLATERAL = 4;
+export const ACTION_WITHDRAW_COLLATERAL = 5;
+export const ACTION_LIQUIDATE = 6;
+export const ACTION_INCREASE_POSITION = 7;
+export const ACTION_DECREASE_POSITION = 8;
+export const ACTION_UPDATE_ORDER = 9;
+export const ACTION_CANCEL_PRE_ORDER = 10;
+export const ACTION_ADD_PRE_ORDER = 11;
+// ======== Misc ========
+// `DRY_RUN_SENDER` (zero-address simulate sender) is a shared primitive defined
+// in `../constants.ts` and re-exported via the `export *` above.
+/**
+ * Well-known address of Sui's native funds-accumulator root shared object
+ * (`@0xacc` in the framework). Pass this to `request_deposit_from_funds<T>`
+ * to drain `Balance<T>` parked at an account's address. Defined in
+ * `account/constants.ts` (account-framework constant); re-exported here for
+ * back-compat.
+ */
+export { ACCUMULATOR_ROOT } from "../account/constants.js";

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

@@ -0,0 +1,43 @@
+/**
+ * wxa account reads (`waterx_account`) — work on credit-only deployments
+ * (which have no `waterx_perp_view`). Plus the inclusive spendable-credit read.
+ */
+import { type ParkedBackingAssetBalance } from "../../account/funding/balance.ts";
+import type { PerpClient } from "../client.ts";
+/**
+ * List the wxa account IDs owned by `owner` (`account::account_ids`).
+ * Returns `[]` when the owner has never created an account. Use this to
+ * resolve the `account_id` a cross-chain deposit must target before
+ * filling the EVM `suiRecipient` field.
+ */
+export declare function getAccountsByOwner(client: PerpClient, owner: string): Promise<string[]>;
+/**
+ * A wxa account's stored `Balance<T>` (`account::account_balance<T>`).
+ * `coinType` defaults to the deployment's CREDIT type — i.e. the bridged
+ * balance available to withdraw. Returns `0n` for an unknown coin type.
+ */
+export declare function getAccountBalance(client: PerpClient, accountId: string, coinType?: string): Promise<bigint>;
+/**
+ * Inclusive wxUSD credit an account can spend after the default async tx-builder
+ * pre-sweep (`appendConsolidateForSpend`).
+ *
+ * - `internalRaw` — stored `Balance<CREDIT>` (`getAccountBalance`).
+ * - `pendingBackingRaw` — native-custody backing assets (USDC, USDSUI, …)
+ *   parked at the account's Sui address, rescaled to CREDIT decimals at the
+ *   1:1 PSM peg (same probe as `appendConsolidateToUsd`).
+ * - `pendingCreditAtAddressRaw` — CREDIT at the account address (accumulator +
+ *   owned coins). Swept into the internal slot by `appendConsolidateAddressCredit`
+ *   via `consumeDepositDirect`.
+ * - `totalRaw` — sum of the three components; matches post-
+ *   `appendConsolidateForSpend` spendable balance for predict / perp
+ *   builders with `consolidateToUsd: true` (default).
+ */
+export interface SpendableCreditBalance {
+    internalRaw: bigint;
+    pendingBackingRaw: bigint;
+    pendingCreditAtAddressRaw: bigint;
+    totalRaw: bigint;
+    /** Per-asset breakdown for the backing-asset probe (empty when nothing parked). */
+    parkedBacking: ParkedBackingAssetBalance[];
+}
+export declare function getSpendableCreditBalance(client: PerpClient, accountId: string): Promise<SpendableCreditBalance>;

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

@@ -0,0 +1,64 @@
+/**
+ * wxa account reads (`waterx_account`) — work on credit-only deployments
+ * (which have no `waterx_perp_view`). Plus the inclusive spendable-credit read.
+ */
+import { bcs } from "@mysten/sui/bcs";
+import { Transaction } from "@mysten/sui/transactions";
+import { probeAddressCreditBalance, probeParkedBackingAssets, sumParkedBackingAsCreditRaw, } from "../../account/funding/balance.js";
+import { accountBalance as accountBalanceCall, accountIds as accountIdsCall, } from "../../generated/waterx_account/account.js";
+import { COLLATERAL_DECIMALS } from "../constants.js";
+import { simulateAndExtract } from "./simulate.js";
+/**
+ * List the wxa account IDs owned by `owner` (`account::account_ids`).
+ * Returns `[]` when the owner has never created an account. Use this to
+ * resolve the `account_id` a cross-chain deposit must target before
+ * filling the EVM `suiRecipient` field.
+ */
+export async function getAccountsByOwner(client, owner) {
+    const tx = new Transaction();
+    accountIdsCall({
+        package: client.config.packages.waterx_account.published_at,
+        arguments: {
+            registry: tx.object(client.config.packages.waterx_account.account_registry),
+            owner,
+        },
+    })(tx);
+    const bytes = await simulateAndExtract(client, tx);
+    return bcs.vector(bcs.Address).parse(bytes);
+}
+/**
+ * A wxa account's stored `Balance<T>` (`account::account_balance<T>`).
+ * `coinType` defaults to the deployment's CREDIT type — i.e. the bridged
+ * balance available to withdraw. Returns `0n` for an unknown coin type.
+ */
+export async function getAccountBalance(client, accountId, coinType) {
+    const tx = new Transaction();
+    accountBalanceCall({
+        package: client.config.packages.waterx_account.published_at,
+        arguments: {
+            registry: tx.object(client.config.packages.waterx_account.account_registry),
+            accountId,
+        },
+        typeArguments: [coinType ?? client.creditType()],
+    })(tx);
+    const bytes = await simulateAndExtract(client, tx);
+    return BigInt(bcs.u64().parse(bytes));
+}
+export async function getSpendableCreditBalance(client, accountId) {
+    const creditType = client.creditType();
+    const [internalRaw, parkedBacking, addressCredit] = await Promise.all([
+        getAccountBalance(client, accountId, creditType),
+        probeParkedBackingAssets(client, accountId),
+        probeAddressCreditBalance(client, accountId),
+    ]);
+    const pendingBackingRaw = sumParkedBackingAsCreditRaw(parkedBacking, COLLATERAL_DECIMALS);
+    const pendingCreditAtAddressRaw = addressCredit.fundsRaw + addressCredit.coinsRaw;
+    const totalRaw = internalRaw + pendingBackingRaw + pendingCreditAtAddressRaw;
+    return {
+        internalRaw,
+        pendingBackingRaw,
+        pendingCreditAtAddressRaw,
+        totalRaw,
+        parkedBacking,
+    };
+}

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

@@ -0,0 +1,90 @@
+/**
+ * Bridge reads: `wormhole_bridge` rate-limit / cap snapshot and the
+ * `withdrawal_queue` (Sui → EVM) fee estimate.
+ */
+import type { PerpClient } from "../client.ts";
+/**
+ * Live rate-limit / cap snapshot read from the `wormhole_bridge::Bridge`
+ * shared object. All amounts are raw base units of the bridged credit coin.
+ *
+ * `dailyMinted` / `dailyBurned` are the sliding-window sums as the on-chain
+ * `daily_minted` / `daily_burned` views report them — buckets that rotated
+ * out of the trailing window are evicted lazily on the next mint/burn, so
+ * these can read slightly high until then (conservative).
+ */
+export interface BridgeLimitsView {
+    paused: boolean;
+    dailyMintLimit: bigint;
+    dailyMinted: bigint;
+    maxMintPerTx: bigint;
+    dailyBurnLimit: bigint;
+    dailyBurned: bigint;
+    maxBurnPerTx: bigint;
+    /** Per-account 24h burn cap; 0n means the gate is disabled. */
+    personalBurnCapAmount: bigint;
+    /** Present only when `accountId` is supplied — burn counted in that
+     *  account's current window (the per-account cap key is the account id). */
+    personalBurned?: bigint;
+    /** Present only when `backing` is supplied — `minted_for(chainId, token)`,
+     *  the amount currently withdrawable to that EVM (chain, token). */
+    backingMinted?: bigint;
+}
+export interface BridgeLimitsArgs {
+    /** wxa trading account id — enables the per-account `personalBurned` read. */
+    accountId?: string;
+    /** Wormhole destination chain id + 20-byte EVM token — enables the
+     *  `mintedFor` backing read. */
+    backing?: {
+        wormholeChainId: number;
+        token: Uint8Array | number[];
+    };
+}
+/**
+ * Batched read of the bridge's rate-limit / cap state in a single simulate.
+ * Pass `accountId` to also fetch the per-account burn usage, and `backing`
+ * to also fetch the destination-chain backing (`minted_for`).
+ *
+ * Throws if `wormhole_bridge` (or its `Bridge` object id) is absent from the
+ * canonical config — e.g. on a network where the Sui bridge isn't published.
+ */
+export declare function getBridgeLimits(client: PerpClient, args?: BridgeLimitsArgs): Promise<BridgeLimitsView>;
+export interface BridgeFeeView {
+    /** Raw fee charged on a wormhole (Sui → EVM) exit of `amount`:
+     *  `max(ceil(effectiveRate * amount), effectiveMinFee)`. */
+    feeAmount: bigint;
+    /** Whether the exit clears the on-chain net-zero guard — i.e. a strictly
+     *  positive amount remains after the fee. Gate "estimated fee" UI on THIS,
+     *  not `feeAmount` alone: a dust `amount`, or a min-fee floor ≥ `amount`,
+     *  makes `feeAmount >= amount` and the exit would abort (audit L1). */
+    wouldExecute: boolean;
+    /** Effective % rate for the chain (per-chain override → default → 0),
+     *  1e9-scaled (the `Float`-as-`u128` ABI convention). */
+    effectiveRate: bigint;
+    /** Effective minimum-fee floor for the chain (override → default → 0),
+     *  in CREDIT base units. */
+    effectiveMinFee: bigint;
+    /** Net CREDIT the recipient receives after the fee; `0n` when the exit
+     *  wouldn't execute (`wouldExecute === false`). */
+    netAmount: bigint;
+}
+/**
+ * Estimate the bridge fee for a wormhole (Sui → EVM) CREDIT exit of `amount`
+ * to `evmDestinationChain`, read in a single simulate from the on-chain
+ * `withdrawal_queue` views. The charged fee is
+ * `max(ceil(effectiveRate * amount), effectiveMinFee)`.
+ *
+ * Surface UI off `wouldExecute`, NOT `feeAmount` alone — `feeAmount` is the raw
+ * fee and can equal/exceed `amount` (ceil rounding on a dust entry, or a min-fee
+ * floor larger than the entry), in which case the on-chain exit aborts its
+ * net-zero guard (audit L1). `netAmount` is `0n` whenever `wouldExecute` is
+ * false.
+ *
+ * @param args.amount             CREDIT base units (the bridged coin's smallest unit).
+ * @param args.evmDestinationChain WORMHOLE chain id of the destination EVM.
+ * @param args.creditType         CREDIT coin type; defaults to `client.creditType()`.
+ */
+export declare function getBridgeFee(client: PerpClient, args: {
+    evmDestinationChain: number;
+    amount: bigint | number;
+    creditType?: string;
+}): Promise<BridgeFeeView>;