@waterx/sdk 2.4.0 → 3.0.0

package/dist/src/{utils/consolidate-balance.d.ts → account/funding/balance.d.ts}

@@ -1,9 +1,4 @@
-/**
- * Shared probe helpers for {@link appendConsolidateToUsd} and
- * {@link getSpendableCreditBalance} — one asset list, one gRPC read pattern,
- * so display totals match what the next async tx-builder would sweep.
- */
-import type { WaterXClient } from "../client.ts";
+import type { AccountClientLike } from "../client.ts";
 /** CREDIT parked at a wxa account's Sui address (funds accumulator + owned coins). */
 export interface AddressCreditBalance {
     /** `getBalance.addressBalance` — funds accumulator path. */
@@ -27,11 +22,11 @@ export declare function rescaleRawAmount(raw: bigint, fromDecimals: number, toDe
  * parked at `accountId`'s Sui address. Matches the pre-tx scan inside
  * {@link appendConsolidateToUsd}.
  */
-export declare function probeParkedBackingAssets(client: WaterXClient, accountId: string): Promise<ParkedBackingAssetBalance[]>;
+export declare function probeParkedBackingAssets(client: AccountClientLike, accountId: string): Promise<ParkedBackingAssetBalance[]>;
 /**
  * Probe non-zero CREDIT parked at `accountId`'s Sui address. Matches the
  * address-CREDIT legs inside {@link appendConsolidateAddressCredit}.
  */
-export declare function probeAddressCreditBalance(client: WaterXClient, accountId: string): Promise<AddressCreditBalance>;
+export declare function probeAddressCreditBalance(client: AccountClientLike, accountId: string): Promise<AddressCreditBalance>;
 /** Sum parked backing assets into CREDIT base units at the 1:1 PSM peg. */
 export declare function sumParkedBackingAsCreditRaw(parked: readonly ParkedBackingAssetBalance[], creditDecimals?: number): bigint;

package/dist/src/{utils/consolidate-balance.js → account/funding/balance.js}

@@ -1,4 +1,9 @@
-import { COLLATERAL_DECIMALS } from "../constants.js";
+/**
+ * Shared probe helpers for {@link appendConsolidateToUsd} and
+ * {@link getSpendableCreditBalance} — one asset list, one gRPC read pattern,
+ * so display totals match what the next async tx-builder would sweep.
+ */
+import { COLLATERAL_DECIMALS } from "../../constants.js";
 /** Rescale a u64 raw amount between token decimal precisions (truncates on downscale). */
 export function rescaleRawAmount(raw, fromDecimals, toDecimals = COLLATERAL_DECIMALS) {
     if (fromDecimals === toDecimals)

package/dist/src/account/funding/consolidate.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Consolidate parked backing assets → USD credit (pre-action sweep).
+ *
+ * Drains every backing asset (and address-owned CREDIT) parked at a wxa
+ * account's address into spendable wxUSD, so the subsequent trading / WLP /
+ * predict action can debit the internal slot. Empty buckets are skipped via
+ * gRPC probes, so the sweep is safe to run on any account.
+ */
+import { Transaction } from "@mysten/sui/transactions";
+import type { AccountClientLike } from "../client.ts";
+/**
+ * For every backing asset registered on `native_custody`, append two drain
+ * legs to `tx`:
+ *
+ *   `requestDepositFromFunds<T>`      → `mintCreditFromRequest<T, USD>` → `consumeDepositDirect<USD>`
+ *   `requestDepositFromReceivings<T>` → `mintCreditFromRequest<T, USD>` → `consumeDepositDirect<USD>`
+ *
+ * Empty legs are skipped — the on-chain `mint` rejects zero-amount deposits.
+ * Returns the number of drain legs added (useful for logging / early-out).
+ *
+ * Silently no-ops when `native_custody` / `waterx_credit` aren't configured
+ * for the loaded deployment.
+ */
+export declare function appendConsolidateToUsd(client: AccountClientLike, tx: Transaction, accountId: string): Promise<number>;
+/**
+ * Drain CREDIT parked at `accountId`'s Sui address (funds accumulator +
+ * owned `Coin<CREDIT>`) into the wxa internal slot via
+ * `consumeDepositDirect<CREDIT>`. Complements {@link appendConsolidateToUsd}
+ * for address-owned wxUSD that predict / perp actions debit from the internal
+ * balance.
+ */
+export declare function appendConsolidateAddressCredit(client: AccountClientLike, tx: Transaction, accountId: string): Promise<number>;
+/**
+ * Full pre-action sweep: backing assets → wxUSD credit (PSM) plus address
+ * CREDIT → internal slot. Used by async tx-builders when `consolidateToUsd`
+ * is enabled (default).
+ */
+export declare function appendConsolidateForSpend(client: AccountClientLike, tx: Transaction, accountId: string): Promise<number>;
+/**
+ * Standalone PTB that drains every backing asset parked at the account's
+ * address into USD credit under the account — see {@link appendConsolidateToUsd}.
+ *
+ * Returns an empty `Transaction` when nothing is parked. Callers can
+ * `client.simulate(tx)` to detect a no-op before submitting.
+ */
+export declare function buildConsolidateToUsdTx(client: AccountClientLike, accountId: string, tx?: Transaction): Promise<Transaction>;

package/dist/src/account/funding/consolidate.js

@@ -0,0 +1,137 @@
+/**
+ * Consolidate parked backing assets → USD credit (pre-action sweep).
+ *
+ * Drains every backing asset (and address-owned CREDIT) parked at a wxa
+ * account's address into spendable wxUSD, so the subsequent trading / WLP /
+ * predict action can debit the internal slot. Empty buckets are skipped via
+ * gRPC probes, so the sweep is safe to run on any account.
+ */
+import { Transaction } from "@mysten/sui/transactions";
+import { consumeDepositDirect } from "../../generated/waterx_account/direct_rule.js";
+import { requestDepositFromFunds, requestDepositFromReceivings } from "../account.js";
+import { probeAddressCreditBalance, probeParkedBackingAssets } from "./balance.js";
+import { mintCreditFromRequest } from "./custody.js";
+/**
+ * For every backing asset registered on `native_custody`, append two drain
+ * legs to `tx`:
+ *
+ *   `requestDepositFromFunds<T>`      → `mintCreditFromRequest<T, USD>` → `consumeDepositDirect<USD>`
+ *   `requestDepositFromReceivings<T>` → `mintCreditFromRequest<T, USD>` → `consumeDepositDirect<USD>`
+ *
+ * Empty legs are skipped — the on-chain `mint` rejects zero-amount deposits.
+ * Returns the number of drain legs added (useful for logging / early-out).
+ *
+ * Silently no-ops when `native_custody` / `waterx_credit` aren't configured
+ * for the loaded deployment.
+ */
+export async function appendConsolidateToUsd(client, tx, accountId) {
+    const parked = await probeParkedBackingAssets(client, accountId);
+    let legs = 0;
+    for (const row of parked) {
+        if (row.fundsRaw > 0n) {
+            const fromFunds = requestDepositFromFunds(client, tx, {
+                accountId,
+                coinType: row.assetType,
+            });
+            foldDepositRequestToUsd(client, tx, fromFunds, row.assetType);
+            legs += 1;
+        }
+        if (row.coinsRaw > 0n) {
+            const coins = (await client.listCoins({
+                owner: accountId,
+                coinType: row.assetType,
+            }));
+            const refs = (coins.objects ?? []).filter((c) => !!c.objectId && !!c.version && !!c.digest);
+            if (refs.length === 0)
+                continue;
+            const receivings = refs.map((c) => tx.receivingRef({ objectId: c.objectId, version: c.version, digest: c.digest }));
+            const fromReceivings = requestDepositFromReceivings(client, tx, {
+                accountId,
+                coinType: row.assetType,
+                receivings,
+            });
+            foldDepositRequestToUsd(client, tx, fromReceivings, row.assetType);
+            legs += 1;
+        }
+    }
+    return legs;
+}
+/**
+ * Drain CREDIT parked at `accountId`'s Sui address (funds accumulator +
+ * owned `Coin<CREDIT>`) into the wxa internal slot via
+ * `consumeDepositDirect<CREDIT>`. Complements {@link appendConsolidateToUsd}
+ * for address-owned wxUSD that predict / perp actions debit from the internal
+ * balance.
+ */
+export async function appendConsolidateAddressCredit(client, tx, accountId) {
+    if (!client.config.packages.waterx_credit?.credit_type)
+        return 0;
+    const creditType = client.creditType();
+    const { fundsRaw, coinsRaw } = await probeAddressCreditBalance(client, accountId);
+    let legs = 0;
+    if (fundsRaw > 0n) {
+        const fromFunds = requestDepositFromFunds(client, tx, {
+            accountId,
+            coinType: creditType,
+        });
+        consumeDepositRequest(client, tx, fromFunds, creditType);
+        legs += 1;
+    }
+    if (coinsRaw > 0n) {
+        const coins = (await client.listCoins({
+            owner: accountId,
+            coinType: creditType,
+        }));
+        const refs = (coins.objects ?? []).filter((c) => !!c.objectId && !!c.version && !!c.digest);
+        if (refs.length > 0) {
+            const receivings = refs.map((c) => tx.receivingRef({ objectId: c.objectId, version: c.version, digest: c.digest }));
+            const fromReceivings = requestDepositFromReceivings(client, tx, {
+                accountId,
+                coinType: creditType,
+                receivings,
+            });
+            consumeDepositRequest(client, tx, fromReceivings, creditType);
+            legs += 1;
+        }
+    }
+    return legs;
+}
+/**
+ * Full pre-action sweep: backing assets → wxUSD credit (PSM) plus address
+ * CREDIT → internal slot. Used by async tx-builders when `consolidateToUsd`
+ * is enabled (default).
+ */
+export async function appendConsolidateForSpend(client, tx, accountId) {
+    const backingLegs = await appendConsolidateToUsd(client, tx, accountId);
+    const creditLegs = await appendConsolidateAddressCredit(client, tx, accountId);
+    return backingLegs + creditLegs;
+}
+function consumeDepositRequest(client, tx, depositRequest, coinType) {
+    consumeDepositDirect({
+        package: client.config.packages.waterx_account.published_at,
+        arguments: {
+            registry: tx.object(client.config.packages.waterx_account.account_registry),
+            req: depositRequest,
+        },
+        typeArguments: [coinType],
+    })(tx);
+}
+function foldDepositRequestToUsd(client, tx, depositRequest, assetType) {
+    const usdReq = mintCreditFromRequest(client, tx, {
+        depositRequest,
+        assetType,
+    });
+    consumeDepositRequest(client, tx, usdReq, client.creditType());
+}
+/**
+ * Standalone PTB that drains every backing asset parked at the account's
+ * address into USD credit under the account — see {@link appendConsolidateToUsd}.
+ *
+ * Returns an empty `Transaction` when nothing is parked. Callers can
+ * `client.simulate(tx)` to detect a no-op before submitting.
+ */
+export async function buildConsolidateToUsdTx(client, accountId, tx) {
+    const txOut = tx ?? new Transaction();
+    await appendConsolidateToUsd(client, txOut, accountId);
+    return txOut;
+}

package/dist/src/{user → account/funding}/credit.d.ts

@@ -18,7 +18,7 @@
  * same PTB.
  */
 import type { Transaction, TransactionArgument } from "@mysten/sui/transactions";
-import type { WaterXClient } from "../client.ts";
+import type { AccountClientLike } from "../client.ts";
 export interface RedeemVaaParams {
     /** Signed Wormhole MINT VAA (raw bytes / number[] / hex). */
     vaaBytes: Uint8Array | number[] | string;
@@ -30,7 +30,7 @@ export interface RedeemVaaParams {
  * `DepositRequest<CREDIT>` hot-potato argument — **must** be consumed in the
  * same PTB (see {@link consumeCreditDeposit} / `redeemVaaTx`).
  */
-export declare function redeemVaa(client: WaterXClient, tx: Transaction, params: RedeemVaaParams): TransactionArgument;
+export declare function redeemVaa(client: AccountClientLike, tx: Transaction, params: RedeemVaaParams): TransactionArgument;
 export interface ConsumeCreditDepositParams {
     /** The `DepositRequest<CREDIT>` returned by {@link redeemVaa} / {@link custodyMint}. */
     depositRequest: TransactionArgument;
@@ -42,7 +42,7 @@ export interface ConsumeCreditDepositParams {
  * `register_deposit_policy<CREDIT, DirectRule>`). Must run in the same PTB
  * as the `redeem_vaa` / custody `mint` that produced the request.
  */
-export declare function consumeCreditDeposit(client: WaterXClient, tx: Transaction, params: ConsumeCreditDepositParams): void;
+export declare function consumeCreditDeposit(client: AccountClientLike, tx: Transaction, params: ConsumeCreditDepositParams): void;
 export interface RouteWormholeParams {
     /** Destination EVM chain's Wormhole chain id. */
     evmDestinationChain: number;
@@ -52,7 +52,7 @@ export interface RouteWormholeParams {
     evmToken: Uint8Array | number[] | string;
 }
 /** Build `withdrawal_queue::route_wormhole`. Returns the `extra_data` argument. */
-export declare function routeWormhole(client: WaterXClient, tx: Transaction, params: RouteWormholeParams): TransactionArgument;
+export declare function routeWormhole(client: AccountClientLike, tx: Transaction, params: RouteWormholeParams): TransactionArgument;
 export interface RouteNativeParams {
     /** Fully-qualified backing asset Move type `T` (e.g. via `client.getNativeAsset`). */
     assetType: string;
@@ -64,7 +64,7 @@ export interface RouteNativeParams {
     minOutput?: bigint | number;
 }
 /** Build `withdrawal_queue::route_native<T>`. Returns the `extra_data` argument. */
-export declare function routeNative(client: WaterXClient, tx: Transaction, params: RouteNativeParams): TransactionArgument;
+export declare function routeNative(client: AccountClientLike, tx: Transaction, params: RouteNativeParams): TransactionArgument;
 export interface RequestCreditWithdrawParams {
     accountId: string;
     amount: bigint | number;
@@ -80,7 +80,7 @@ export interface RequestCreditWithdrawParams {
  * Returns the `WithdrawRequest<CREDIT>` hot-potato argument (feed to
  * {@link enqueueWithdrawal} in the same PTB).
  */
-export declare function requestCreditWithdraw(client: WaterXClient, tx: Transaction, params: RequestCreditWithdrawParams): TransactionArgument;
+export declare function requestCreditWithdraw(client: AccountClientLike, tx: Transaction, params: RequestCreditWithdrawParams): TransactionArgument;
 export interface EnqueueWithdrawalParams {
     /** `WithdrawRequest<CREDIT>` from {@link requestCreditWithdraw}. */
     withdrawRequest: TransactionArgument;
@@ -90,7 +90,7 @@ export interface EnqueueWithdrawalParams {
  * Build `withdrawal_queue::enqueue<CREDIT>`. Returns the assigned `u64` key
  * argument (also surfaced on-chain via the `Enqueued` event).
  */
-export declare function enqueueWithdrawal(client: WaterXClient, tx: Transaction, params: EnqueueWithdrawalParams): TransactionArgument;
+export declare function enqueueWithdrawal(client: AccountClientLike, tx: Transaction, params: EnqueueWithdrawalParams): TransactionArgument;
 export interface ExecuteWithdrawalWormholeParams {
     /** Queue entry key (from the `Enqueued` event / `enqueueWithdrawal`). */
     key: bigint | number;
@@ -101,7 +101,7 @@ export interface ExecuteWithdrawalWormholeParams {
     bucketAccount?: string | TransactionArgument;
 }
 /** Build `withdrawal_queue::execute_wormhole<CREDIT>` (keeper / executor-gated). */
-export declare function executeWithdrawalWormhole(client: WaterXClient, tx: Transaction, params: ExecuteWithdrawalWormholeParams): void;
+export declare function executeWithdrawalWormhole(client: AccountClientLike, tx: Transaction, params: ExecuteWithdrawalWormholeParams): void;
 export interface ExecuteWithdrawalNativeParams {
     key: bigint | number;
     /** Fully-qualified backing asset Move type `T` (must match the entry's route). */
@@ -110,7 +110,7 @@ export interface ExecuteWithdrawalNativeParams {
     bucketAccount?: string | TransactionArgument;
 }
 /** Build `withdrawal_queue::execute_native<T, CREDIT>` (keeper / executor-gated). */
-export declare function executeWithdrawalNative(client: WaterXClient, tx: Transaction, params: ExecuteWithdrawalNativeParams): void;
+export declare function executeWithdrawalNative(client: AccountClientLike, tx: Transaction, params: ExecuteWithdrawalNativeParams): void;
 export interface CustodyMintParams {
     /** wxa account ID the minted CREDIT lands in. */
     accountId: string;
@@ -126,4 +126,4 @@ export interface CustodyMintParams {
  * `DepositRequest<CREDIT>` hot-potato argument (consume in-PTB via
  * {@link consumeCreditDeposit}).
  */
-export declare function custodyMint(client: WaterXClient, tx: Transaction, params: CustodyMintParams): TransactionArgument;
+export declare function custodyMint(client: AccountClientLike, tx: Transaction, params: CustodyMintParams): TransactionArgument;

package/dist/src/{user → account/funding}/credit.js

@@ -19,12 +19,12 @@
  */
 import { fromHex } from "@mysten/bcs";
 import { normalizeStructTag } from "@mysten/sui/utils";
-import { mint as custodyMintCall } from "../generated/native_custody/custody_vault.js";
-import { requestWithdraw as requestWithdrawCall } from "../generated/waterx_account/account.js";
-import { consumeDepositDirect } from "../generated/waterx_account/direct_rule.js";
-import { enqueue as enqueueCall, executeNative as executeNativeCall, executeWormhole as executeWormholeCall, routeNative as routeNativeCall, routeWormhole as routeWormholeCall, } from "../generated/withdrawal_queue/withdrawal_queue.js";
-import { redeemVaa as redeemVaaCall } from "../generated/wormhole_bridge/wormhole_bridge.js";
-import { makeSenderRequest } from "../utils/account-request.js";
+import { mint as custodyMintCall } from "../../generated/native_custody/custody_vault.js";
+import { requestWithdraw as requestWithdrawCall } from "../../generated/waterx_account/account.js";
+import { consumeDepositDirect } from "../../generated/waterx_account/direct_rule.js";
+import { enqueue as enqueueCall, executeNative as executeNativeCall, executeWormhole as executeWormholeCall, routeNative as routeNativeCall, routeWormhole as routeWormholeCall, } from "../../generated/withdrawal_queue/withdrawal_queue.js";
+import { redeemVaa as redeemVaaCall } from "../../generated/wormhole_bridge/wormhole_bridge.js";
+import { makeSenderRequest } from "../account-request.js";
 // ============================================================================
 // Byte helpers
 // ============================================================================

package/dist/src/{user → account/funding}/custody.d.ts

@@ -17,7 +17,7 @@
  * credit pipeline.
  */
 import type { Transaction, TransactionArgument } from "@mysten/sui/transactions";
-import type { WaterXClient } from "../client.ts";
+import type { AccountClientLike } from "../client.ts";
 export interface MintCreditParams {
     /** wxa account ID the minted CREDIT is deposited into (also the partner-fee key). */
     accountId: string;
@@ -34,7 +34,7 @@ export interface MintCreditParams {
  * Build `custody_vault::mint<T, CREDIT>`. Returns the `DepositRequest<CREDIT>`
  * argument — consume it in the same PTB (see `mintCreditToAccount`).
  */
-export declare function mintCredit(client: WaterXClient, tx: Transaction, params: MintCreditParams): TransactionArgument;
+export declare function mintCredit(client: AccountClientLike, tx: Transaction, params: MintCreditParams): TransactionArgument;
 export interface MintCreditFromRequestParams {
     /** `DepositRequest<T>` from `account::request_deposit<T>` (T must have `NativeCustody` as its deposit policy). */
     depositRequest: TransactionArgument;
@@ -48,10 +48,10 @@ export interface MintCreditFromRequestParams {
  * `DepositRequest<CREDIT>` inherits the input request's `accountId` /
  * `extraData`. Consume it in the same PTB.
  */
-export declare function mintCreditFromRequest(client: WaterXClient, tx: Transaction, params: MintCreditFromRequestParams): TransactionArgument;
+export declare function mintCreditFromRequest(client: AccountClientLike, tx: Transaction, params: MintCreditFromRequestParams): TransactionArgument;
 /**
  * `mintCredit` followed by `direct_rule::consume_deposit_direct<CREDIT>`, so
  * the freshly minted CREDIT settles straight into `accountId`'s wxa balance.
  * Assumes CREDIT's deposit policy is `DirectRule` (the canonical setup).
  */
-export declare function mintCreditToAccount(client: WaterXClient, tx: Transaction, params: MintCreditParams): void;
+export declare function mintCreditToAccount(client: AccountClientLike, tx: Transaction, params: MintCreditParams): void;

package/dist/src/{user → account/funding}/custody.js

@@ -17,8 +17,8 @@
  * credit pipeline.
  */
 import { normalizeStructTag } from "@mysten/sui/utils";
-import * as custody from "../generated/native_custody/custody_vault.js";
-import { consumeDepositDirect } from "../generated/waterx_account/direct_rule.js";
+import * as custody from "../../generated/native_custody/custody_vault.js";
+import { consumeDepositDirect } from "../../generated/waterx_account/direct_rule.js";
 function requireCredit(client) {
     const credit = client.config.packages.waterx_credit;
     if (!credit?.credit_registry) {

package/dist/src/{utils → account/funding}/wormhole.d.ts

@@ -2,7 +2,7 @@
  * Wormhole / Wormholescan integration for the cross-chain credit bridge.
  *
  * Single source of truth for VAA discovery + (de)serialization — mirrors
- * `utils/pyth.ts`'s role for Pyth's Hermes endpoint. Two directions:
+ * `oracle/pyth.ts`'s role for Pyth's Hermes endpoint. Two directions:
  *
  *   - Mint (EVM → Sui): fetch the signed VAA for an EVM `Deposit` by
  *     (emitter chain, emitter address, sequence); the raw bytes feed
@@ -13,7 +13,7 @@
  * Endpoints / chain ids come from `client.wormhole` (network defaults in
  * `WORMHOLE_DEFAULTS`, overridable via `WaterXConfig.wormhole`).
  */
-import type { WaterXClient } from "../client.ts";
+import type { AccountClientLike } from "../client.ts";
 /**
  * Normalize an emitter id to Wormholescan's `emitter` path segment:
  * 64-char lowercase hex, no `0x`. Accepts a 0x EVM address (left-padded to
@@ -75,12 +75,12 @@ export declare function vaaBase64ToHex(b64: string): `0x${string}`;
  * address (0x form accepted — left-padded automatically); `chainId` is the
  * source EVM chain's Wormhole chain id.
  */
-export declare function fetchDepositVaa(client: WaterXClient, evmWormholeChainId: number, evmEmitter: string, sequence: number | string | bigint, opts?: WormholescanOptions): Promise<VaaResponse | null>;
+export declare function fetchDepositVaa(client: AccountClientLike, evmWormholeChainId: number, evmEmitter: string, sequence: number | string | bigint, opts?: WormholescanOptions): Promise<VaaResponse | null>;
 /**
  * List recent Sui→EVM VAAs from the configured bridge `EmitterCap` (burn
  * relayer). Requires `packages.wormhole_bridge.emitter_cap` in config.
  */
-export declare function listBridgeWithdrawalVaas(client: WaterXClient, opts?: WormholescanOptions & {
+export declare function listBridgeWithdrawalVaas(client: AccountClientLike, opts?: WormholescanOptions & {
     page?: number;
     pageSize?: number;
 }): Promise<VaaListItem[]>;

package/dist/src/{utils → account/funding}/wormhole.js

@@ -2,7 +2,7 @@
  * Wormhole / Wormholescan integration for the cross-chain credit bridge.
  *
  * Single source of truth for VAA discovery + (de)serialization — mirrors
- * `utils/pyth.ts`'s role for Pyth's Hermes endpoint. Two directions:
+ * `oracle/pyth.ts`'s role for Pyth's Hermes endpoint. Two directions:
  *
  *   - Mint (EVM → Sui): fetch the signed VAA for an EVM `Deposit` by
  *     (emitter chain, emitter address, sequence); the raw bytes feed

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

@@ -0,0 +1,29 @@
+/**
+ * Unified WaterX account namespace — exposed as `client.account`.
+ *
+ * Aggregates the generic `waterx_account` framework builders with the funding
+ * (credit + custody) builders into one surface. This is the contract's **base**
+ * layer: it lives under `account/` and depends only **down** (base-client /
+ * constants / generated) — it must never import `perp/` or `prediction/`. Builders
+ * are typed to the {@link AccountClientLike} capability interface (in `./client.ts`),
+ * which `PerpClient` satisfies structurally; `bindClient` passes the perp-line
+ * client (which carries the shared `waterx_account` + `AccountRegistry`, bridge /
+ * native_custody / withdrawal_queue / credit_registry) as arg 0. Because
+ * `waterx_account` is a single shared object across both product lines, an account
+ * created here is usable by perp and prediction alike (see the cross-network caveat
+ * on the umbrella `WaterXClient`).
+ *
+ * The prediction-specific account operations (delegate prediction permission,
+ * prediction protocol whitelist / asset allowlist) are NOT generic and stay on
+ * `client.predict`.
+ *
+ * INVARIANT: every export below must be **client-first** — `bindClient` (in
+ * `unified-client.ts`) blindly binds the client as arg 0 to each function here, so
+ * a non-client-first helper (e.g. a local crypto/URL util) leaking out of these
+ * modules would be mis-bound silently. Keep such helpers unexported, or add them to
+ * `NON_CLIENT_FIRST` in `unified-client.ts` (the coverage guard in
+ * `test/perp/unit/unified-client.test.ts` only excuses names on that list).
+ */
+export * from "./account.ts";
+export * from "./funding/credit.ts";
+export * from "./funding/custody.ts";

package/dist/src/account/index.js

@@ -0,0 +1,29 @@
+/**
+ * Unified WaterX account namespace — exposed as `client.account`.
+ *
+ * Aggregates the generic `waterx_account` framework builders with the funding
+ * (credit + custody) builders into one surface. This is the contract's **base**
+ * layer: it lives under `account/` and depends only **down** (base-client /
+ * constants / generated) — it must never import `perp/` or `prediction/`. Builders
+ * are typed to the {@link AccountClientLike} capability interface (in `./client.ts`),
+ * which `PerpClient` satisfies structurally; `bindClient` passes the perp-line
+ * client (which carries the shared `waterx_account` + `AccountRegistry`, bridge /
+ * native_custody / withdrawal_queue / credit_registry) as arg 0. Because
+ * `waterx_account` is a single shared object across both product lines, an account
+ * created here is usable by perp and prediction alike (see the cross-network caveat
+ * on the umbrella `WaterXClient`).
+ *
+ * The prediction-specific account operations (delegate prediction permission,
+ * prediction protocol whitelist / asset allowlist) are NOT generic and stay on
+ * `client.predict`.
+ *
+ * INVARIANT: every export below must be **client-first** — `bindClient` (in
+ * `unified-client.ts`) blindly binds the client as arg 0 to each function here, so
+ * a non-client-first helper (e.g. a local crypto/URL util) leaking out of these
+ * modules would be mis-bound silently. Keep such helpers unexported, or add them to
+ * `NON_CLIENT_FIRST` in `unified-client.ts` (the coverage guard in
+ * `test/perp/unit/unified-client.test.ts` only excuses names on that list).
+ */
+export * from "./account.js"; // generic waterx_account framework builders
+export * from "./funding/credit.js"; // cross-chain CREDIT / bridge builders
+export * from "./funding/custody.js"; // native_custody PSM mint builders

package/dist/src/{user → account}/referral.d.ts

@@ -6,16 +6,16 @@
  * loudly instead of silently aborting on-chain.
  */
 import type { Transaction, TransactionArgument } from "@mysten/sui/transactions";
-import type { WaterXClient } from "../client.ts";
+import type { WxaClientLike } from "./client.ts";
 export interface SetReferralCodeParams {
     /** Referral code string the caller wants to claim. */
     code: string;
     bucketAccount?: string | TransactionArgument;
 }
-export declare function setReferralCode(client: WaterXClient, tx: Transaction, params: SetReferralCodeParams): void;
+export declare function setReferralCode(client: WxaClientLike, tx: Transaction, params: SetReferralCodeParams): void;
 export interface UseReferralCodeParams {
     /** Referral code to bind to the caller's address. */
     code: string;
     bucketAccount?: string | TransactionArgument;
 }
-export declare function useReferralCode(client: WaterXClient, tx: Transaction, params: UseReferralCodeParams): void;
+export declare function useReferralCode(client: WxaClientLike, tx: Transaction, params: UseReferralCodeParams): void;

package/dist/src/{user → account}/referral.js

@@ -6,7 +6,7 @@
  * loudly instead of silently aborting on-chain.
  */
 import * as referral from "../generated/waterx_referral/referral_table.js";
-import { makeSenderRequest } from "../utils/account-request.js";
+import { makeSenderRequest } from "./account-request.js";
 function requireReferralConfig(client) {
     const pkg = client.config.packages.waterx_referral?.published_at;
     const table = client.config.packages.waterx_referral?.referral_table;

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

@@ -0,0 +1,74 @@
+/**
+ * Shared transport base for the two product-line clients (`PerpClient`,
+ * `PredictClient`).
+ *
+ * Holds the half that is identical across both lines: the gRPC client
+ * construction (network + URL resolution), the read-only gRPC convenience
+ * wrappers, `simulate` / `signAndExecuteTransaction`, and the `packageIds()`
+ * lookup. The config-schema half (per-line typed lookups like `getMarket` /
+ * `marketRegistry`) legitimately differs and lives on each subclass.
+ *
+ * `Cfg` is the line's parsed `waterx-config` JSON type. Only the fields needed
+ * here are constrained ({@link BaseLineConfig}); each subclass narrows `Cfg` to
+ * its full config type so `this.config` stays precisely typed.
+ */
+import type { SuiClientTypes } from "@mysten/sui/client";
+import type { Signer } from "@mysten/sui/cryptography";
+import { SuiGrpcClient } from "@mysten/sui/grpc";
+import type { Transaction } from "@mysten/sui/transactions";
+import type { Network } from "./constants.ts";
+/** Default Sui gRPC base URLs by network (public Mysten fullnodes). */
+export declare const DEFAULT_GRPC_URLS: Record<Network, string>;
+/** Minimal shape of a line config that {@link BaseLineClient} reads directly. */
+export interface BaseLineConfig {
+    /** Sui gRPC base URL override (default: public Mysten fullnode for the network). */
+    grpcUrl?: string;
+    /** Package map — iterated by {@link BaseLineClient.packageIds}. */
+    packages: object;
+}
+export declare abstract class BaseLineClient<Cfg extends BaseLineConfig = BaseLineConfig> {
+    /** gRPC client — all RPC including `simulateTransaction`. */
+    grpcClient: SuiGrpcClient;
+    /** Network identifier in upper case (`MAINNET` / `TESTNET`). */
+    network: Network;
+    /** Parsed canonical `waterx-config` JSON for this line. */
+    config: Cfg;
+    protected constructor(network: Network, config: Cfg, opts?: {
+        grpcUrl?: string;
+    });
+    getObject(objectId: string): Promise<SuiClientTypes.GetObjectResponse<{}>>;
+    getObjects(objectIds: string[]): Promise<SuiClientTypes.GetObjectsResponse<{}>>;
+    listOwnedObjects(owner: string): Promise<SuiClientTypes.ListOwnedObjectsResponse<{}>>;
+    listCoins(params: {
+        owner: string;
+        coinType?: string;
+    }): Promise<SuiClientTypes.ListCoinsResponse>;
+    getBalance(params: {
+        owner: string;
+        coinType?: string;
+    }): Promise<SuiClientTypes.GetBalanceResponse>;
+    listDynamicFields(parentId: string): ReturnType<SuiGrpcClient["listDynamicFields"]>;
+    getDynamicField(parentId: string, name: {
+        type: string;
+        bcs: Uint8Array;
+    }): Promise<SuiClientTypes.GetDynamicFieldResponse>;
+    waitForTransaction(digest: string): Promise<SuiClientTypes.TransactionResult<{}>>;
+    /**
+     * Simulate a transaction (no signing). Subclasses may override to add
+     * transport policy (e.g. the prediction line wraps this with rate-limit
+     * retry against the public testnet RPC).
+     */
+    simulate(tx: Transaction): Promise<SuiClientTypes.SimulateTransactionResult<{
+        commandResults: true;
+    }>>;
+    signAndExecuteTransaction<Include extends SuiClientTypes.TransactionInclude = object>(params: {
+        signer: {
+            toSuiAddress: () => string;
+        } & Signer;
+        transaction: Transaction | Uint8Array;
+        additionalSignatures?: string[];
+        include?: Include & SuiClientTypes.TransactionInclude;
+    }): Promise<SuiClientTypes.TransactionResult<Include & SuiClientTypes.TransactionInclude>>;
+    /** All package IDs (`published_at`) keyed by package name. */
+    packageIds(): Record<string, string>;
+}