@waterx/sdk 2.4.1 → 3.0.0

package/README.md

@@ -6,24 +6,28 @@ TypeScript SDK for the WaterX protocol on Sui — **two product lines in one pac
 
 ## Two lines, one package
 
-The perp and prediction lines expose builder functions with **colliding names** (`placeOrder`, `createAccount`, `deposit`, …), so they are kept in separate namespaces:
+The perp and prediction lines expose builder functions with **colliding names** (`placeOrder`, `deposit`, …), so they are kept in separate namespaces under one umbrella `WaterXClient`:
 
 ```ts
-import { Client } from "@waterx/sdk";
-
-const client = await Client.create({ network: "TESTNET" });
-client.perp.buildPlaceOrderTx(params);   // perpetuals
-client.predict.placeOrder(tx, params);   // prediction markets
-// raw line clients for signing/executing: client.perpClient / client.predictClient
-// each line can target a different network: Client.create({ perp: { network: "MAINNET" }, predict: { network: "TESTNET" } })
+import { WaterXClient } from "@waterx/sdk";
+
+const client = await WaterXClient.create({ network: "TESTNET" });
+client.account.createAccount(tx, { alias });  // shared waterx_account + funding (credit/custody)
+client.perp.buildPlaceOrderTx(params);        // perpetuals
+client.predict.placeOrder(tx, params);        // prediction markets
+// client.perp / client.predict ARE the line clients — sign/execute on them directly:
+//   await client.perp.signAndExecuteTransaction({ transaction: tx, signer })
+// each line can target a different network: WaterXClient.create({ perp: { network: "MAINNET" }, predict: { network: "TESTNET" } })
 ```
 
+> `WaterXClient` is the umbrella entry point. `Client` is kept as a **deprecated alias** for one major cycle.
+
 Import surfaces:
 
 | Import | What |
 |--------|------|
-| `@waterx/sdk` | `Client` (unified) + `perp` / `prediction` namespaces. Perp's API is also re-exported flat here (**deprecated** — prefer `client.perp` or the `perp` namespace; removed next major). |
-| `@waterx/sdk/perp` | Perp line: `WaterXClient`, builders, fetch, Pyth/Wormhole utils. |
+| `@waterx/sdk` | `WaterXClient` (umbrella) + `perp` / `prediction` namespaces. Perp's API is also re-exported flat here (**deprecated** — prefer `client.perp` or the `perp` namespace; removed next major). |
+| `@waterx/sdk/perp` | Perp line: `PerpClient`, builders, fetch, Pyth/Wormhole utils. |
 | `@waterx/sdk/prediction` | Prediction line: `PredictClient`, builders, fetch, utils. |
 
 ## Install
@@ -37,19 +41,19 @@ Consumers: `pnpm add @waterx/sdk @mysten/sui`
 
 ## Quickstart (unified client)
 
-`Client.create()` loads each line's deployment config from the canonical `waterx-config` JSON and returns a ready client. Builders are **build-only** — they return / mutate a `Transaction`; signing & execution stay with the caller (the line client, or a frontend wallet), so multi-step Pyth injection and wallet flows keep working.
+`WaterXClient.create()` loads each line's deployment config from the canonical `waterx-config` JSON and returns a ready client. Builders are **build-only** — they return / mutate a `Transaction`; signing & execution stay with the caller (`client.perp` / `client.predict` are the line clients, or a frontend wallet), so multi-step Pyth injection and wallet flows keep working.
 
 ```ts
-import { Client, rawPrice } from "@waterx/sdk";
+import { WaterXClient, rawPrice } from "@waterx/sdk";
 import { Transaction } from "@mysten/sui/transactions";
 
-const client = await Client.create({ network: "TESTNET" });
+const client = await WaterXClient.create({ network: "TESTNET" });
 const signer = /* your Ed25519Keypair or wallet Signer */;
 
 // --- Perp: place a market order ---
 const tx = await client.perp.buildPlaceOrderTx({
   ticker: "BTCUSD",
-  collateralType: client.perpClient.creditType(),
+  collateralType: client.perp.creditType(),
   accountId: "0x...", // UserAccount object id (hex)
   main: {
     isLong: true,
@@ -61,25 +65,25 @@ const tx = await client.perp.buildPlaceOrderTx({
   },
   preOrders: [],
 });
-await client.perpClient.signAndExecuteTransaction({ transaction: tx, signer });
+await client.perp.signAndExecuteTransaction({ transaction: tx, signer });
 
 // --- Prediction: same pattern under client.predict ---
 const ptx = new Transaction();
 client.predict.placeOrder(ptx, params);
-await client.predictClient.signAndExecuteTransaction({ transaction: ptx, signer });
+await client.predict.signAndExecuteTransaction({ transaction: ptx, signer });
 ```
 
-> Account creation is shared: both lines build accounts via the same on-chain `waterx_account` system, so an account created through `client.perp.createAccount` is usable by `client.predict.*` (and vice versa).
+> Account creation is shared: `client.account.*` builds accounts via the one on-chain `waterx_account` system (perp-backed), so an account created through `client.account.createAccount` is usable by both `client.perp.*` and `client.predict.*`. (On split-network setups `client.account` follows the perp line — reach the predict line's generic account builders via the `prediction` namespace.)
 
 ## Per-line clients
 
 If you only need one line, construct it directly (both factories are **async** — they fetch deployment config):
 
 ```ts
-import { WaterXClient } from "@waterx/sdk/perp";
+import { PerpClient } from "@waterx/sdk/perp";
 import { PredictClient } from "@waterx/sdk/prediction";
 
-const perp = await WaterXClient.create("TESTNET"); // or WaterXClient.testnet()
+const perp = await PerpClient.create("TESTNET"); // or PerpClient.testnet()
 const predict = await PredictClient.create("TESTNET"); // or PredictClient.testnet()
 ```
 
@@ -91,9 +95,9 @@ To avoid doc drift, per-action usage lives in maintained, lint-checked code rath
 
 - **Perp recipes:** [`examples/`](./examples) — ~30 runnable scripts (place orders, WLP mint/redeem, account/delegates, reads). Each uses `buildClient()` + a builder + `simThenMaybeExecute`.
 - **Prediction recipes:** [`test/prediction/e2e/`](./test/prediction/e2e) — the live reference for `client.predict.*` flows.
-- **Authoritative export list:** [`src/index.ts`](./src/index.ts) (perp) and [`src/prediction/index.ts`](./src/prediction/index.ts) — clients, builders, view helpers, BCS types, and `*Calls` generated namespaces.
+- **Authoritative export list:** [`src/perp/index.ts`](./src/perp/index.ts) (perp) and [`src/prediction/index.ts`](./src/prediction/index.ts) — clients, builders, view helpers, BCS types, and `*Calls` generated namespaces. The package root (`.`) is [`src/sdk.ts`](./src/sdk.ts) (umbrella + flat-perp re-export); the shared base is published at `@waterx/sdk/account` and `@waterx/sdk/oracle`.
 
-Perp `build*Tx` helpers are Pyth-backed (`async`; they refresh feeds before the call). Pyth/Wormhole helpers live in [`src/utils/`](./src/utils).
+Perp `build*Tx` helpers are Pyth-backed (`async`; they refresh feeds before the call). Oracle (Pyth/Hermes) helpers live in [`src/oracle/`](./src/oracle).
 
 ## Development
 

package/dist/src/{utils → account}/account-request.d.ts

@@ -4,6 +4,6 @@
  * injected. Used by every user/* builder to authenticate the caller.
  */
 import type { Transaction, TransactionArgument } from "@mysten/sui/transactions";
-import type { WaterXClient } from "../client.ts";
+import type { WxaClientLike } from "./client.ts";
 export type BucketAccount = string | TransactionArgument | undefined;
-export declare function makeSenderRequest(client: WaterXClient, tx: Transaction, bucketAccount: BucketAccount): TransactionArgument;
+export declare function makeSenderRequest(client: WxaClientLike, tx: Transaction, bucketAccount: BucketAccount): TransactionArgument;

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

@@ -11,23 +11,24 @@
  * or a `TransactionArgument`).
  */
 import type { Transaction, TransactionArgument } from "@mysten/sui/transactions";
-import type { WaterXClient } from "../client.ts";
+import type { WxaClientLike } from "./client.ts";
 export interface CreateAccountParams {
     /** Alias / display name for the new account (max length checked on-chain). */
     alias: string;
     /** Optional Bucket Account to act through (otherwise tx.sender). */
     bucketAccount?: string | TransactionArgument;
 }
-/** Build `waterx_account::create_account`. Returns the new account ID via Move return value. */
-export declare function createAccount(client: WaterXClient, tx: Transaction, params: CreateAccountParams): void;
+/** Build `waterx_account::create_account`. Returns the new account ID (Move return value). */
+export declare function createAccount(client: WxaClientLike, tx: Transaction, params: CreateAccountParams): TransactionArgument;
 export interface SetAliasParams {
     accountId: string;
     alias: string;
     bucketAccount?: string | TransactionArgument;
 }
-export declare function setAlias(client: WaterXClient, tx: Transaction, params: SetAliasParams): void;
+export declare function setAlias(client: WxaClientLike, tx: Transaction, params: SetAliasParams): void;
 export interface AddDelegateParams {
-    accountId: string;
+    /** Account ID — an `0x2::object::ID` string or a PTB argument. */
+    accountId: string | TransactionArgument;
     delegateAddress: string;
     alias: string;
     /** Bitmask matching `waterx_account` permission constants. */
@@ -36,13 +37,14 @@ export interface AddDelegateParams {
     expiresAtMs?: bigint | number;
     bucketAccount?: string | TransactionArgument;
 }
-export declare function addDelegate(client: WaterXClient, tx: Transaction, params: AddDelegateParams): void;
+export declare function addDelegate(client: WxaClientLike, tx: Transaction, params: AddDelegateParams): void;
 export interface RemoveDelegateParams {
-    accountId: string;
+    /** Account ID — an `0x2::object::ID` string or a PTB argument. */
+    accountId: string | TransactionArgument;
     delegateAddress: string;
     bucketAccount?: string | TransactionArgument;
 }
-export declare function removeDelegate(client: WaterXClient, tx: Transaction, params: RemoveDelegateParams): void;
+export declare function removeDelegate(client: WxaClientLike, tx: Transaction, params: RemoveDelegateParams): void;
 export interface SetDelegateProtocolPermissionParams {
     accountId: string;
     delegateAddress: string;
@@ -52,10 +54,10 @@ export interface SetDelegateProtocolPermissionParams {
     protocolType: string;
     bucketAccount?: string | TransactionArgument;
 }
-export declare function setDelegateProtocolPermission(client: WaterXClient, tx: Transaction, params: SetDelegateProtocolPermissionParams): void;
+export declare function setDelegateProtocolPermission(client: WxaClientLike, tx: Transaction, params: SetDelegateProtocolPermissionParams): void;
 export interface RequestDepositParams {
-    /** wxa account ID receiving the deposit. */
-    accountId: string;
+    /** wxa account ID receiving the deposit (ID string or PTB argument). */
+    accountId: string | TransactionArgument;
     /** Coin or coin transaction argument to deposit. */
     coin: TransactionArgument;
     /** Fully-qualified coin type. */
@@ -64,10 +66,10 @@ export interface RequestDepositParams {
     extraData?: Uint8Array;
 }
 /** Build `account::request_deposit<T>`. Returns the `DepositRequest<T>` argument. */
-export declare function requestDeposit(client: WaterXClient, tx: Transaction, params: RequestDepositParams): TransactionArgument;
+export declare function requestDeposit(client: WxaClientLike, tx: Transaction, params: RequestDepositParams): TransactionArgument;
 export interface RequestDepositFromReceivingsParams {
-    /** wxa account ID receiving the deposit. */
-    accountId: string;
+    /** wxa account ID receiving the deposit (ID string or PTB argument). */
+    accountId: string | TransactionArgument;
     /**
      * `Receiving<Coin<T>>` arguments — one per `Coin<T>` previously transferred
      * onto the account's address. Build each with
@@ -85,7 +87,7 @@ export interface RequestDepositFromReceivingsParams {
  * transfer-to-object path) into a single `DepositRequest<T>`. Returns the
  * `DepositRequest<T>` argument.
  */
-export declare function requestDepositFromReceivings(client: WaterXClient, tx: Transaction, params: RequestDepositFromReceivingsParams): TransactionArgument;
+export declare function requestDepositFromReceivings(client: WxaClientLike, tx: Transaction, params: RequestDepositFromReceivingsParams): TransactionArgument;
 export interface RequestDepositFromFundsParams {
     /** wxa account ID receiving the deposit. */
     accountId: string;
@@ -112,9 +114,9 @@ export interface RequestDepositFromFundsParams {
  * no `T`, so check `settled_funds_value<T>` off-chain first if you want to
  * skip empty drains.
  */
-export declare function requestDepositFromFunds(client: WaterXClient, tx: Transaction, params: RequestDepositFromFundsParams): TransactionArgument;
+export declare function requestDepositFromFunds(client: WxaClientLike, tx: Transaction, params: RequestDepositFromFundsParams): TransactionArgument;
 export interface RequestWithdrawParams {
-    accountId: string;
+    accountId: string | TransactionArgument;
     amount: bigint | number;
     /** Recipient for the eventual coin payout (policy decides exact mechanics). */
     recipient: string;
@@ -125,13 +127,13 @@ export interface RequestWithdrawParams {
     bucketAccount?: string | TransactionArgument;
 }
 /** Build `account::request_withdraw<T>`. Returns the `WithdrawRequest<T>` argument. */
-export declare function requestWithdraw(client: WaterXClient, tx: Transaction, params: RequestWithdrawParams): TransactionArgument;
+export declare function requestWithdraw(client: WxaClientLike, tx: Transaction, params: RequestWithdrawParams): TransactionArgument;
 export interface TransferToAccountParams {
-    accountId: string;
+    accountId: string | TransactionArgument;
     coin: TransactionArgument;
     coinType: string;
 }
-export declare function transferToAccount(client: WaterXClient, tx: Transaction, params: TransferToAccountParams): void;
+export declare function transferToAccount(client: WxaClientLike, tx: Transaction, params: TransferToAccountParams): void;
 export interface ReceiveParams {
     accountId: string;
     /**
@@ -153,4 +155,4 @@ export interface ReceiveParams {
  * Bypasses the deposit-policy flow — use for reward coins (and other
  * tokens / objects) that have no registered deposit policy.
  */
-export declare function receive(client: WaterXClient, tx: Transaction, params: ReceiveParams): TransactionArgument;
+export declare function receive(client: WxaClientLike, tx: Transaction, params: ReceiveParams): TransactionArgument;

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

@@ -10,14 +10,14 @@
  * a Bucket `Account` object, pass `bucketAccount` (an object ID string
  * or a `TransactionArgument`).
  */
-import { ACCUMULATOR_ROOT } from "../constants.js";
-import { createAccountCall } from "../core/waterx-account.js";
 import * as wxa from "../generated/waterx_account/account.js";
-import { makeSenderRequest } from "../utils/account-request.js";
-/** Build `waterx_account::create_account`. Returns the new account ID via Move return value. */
+import { makeSenderRequest } from "./account-request.js";
+import { ACCUMULATOR_ROOT } from "./constants.js";
+import { createAccountCall } from "./waterx-account.js";
+/** Build `waterx_account::create_account`. Returns the new account ID (Move return value). */
 export function createAccount(client, tx, params) {
     const req = makeSenderRequest(client, tx, params.bucketAccount);
-    createAccountCall(tx, {
+    return createAccountCall(tx, {
         packageId: client.config.packages.waterx_account.published_at,
         registry: client.config.packages.waterx_account.account_registry,
     }, { senderRequest: req, alias: params.alias });

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

@@ -0,0 +1,42 @@
+/**
+ * `AccountClientLike` — the narrow capability slice the account/funding builders
+ * read, instead of the concrete `PerpClient`.
+ *
+ * The account framework + funding (credit / custody / bridge / consolidate) is
+ * the contract's **base** layer: both product lines depend down onto it. Typing
+ * these builders to `PerpClient` inverted that — so they take this structural
+ * interface instead. `PerpClient` satisfies it without an `implements` clause
+ * (it `extends BaseLineClient<WaterXConfig>` and carries the config-view slice +
+ * the `wormhole` infra block); a future funding-capable client can too.
+ *
+ * The config schema it reads lives in `account/config.ts` (the base layer), so
+ * this file imports **nothing** from `perp/` — `account/` no longer depends on the
+ * perp line even at the type level. `PerpClient`'s `WaterXConfig` is assignable to
+ * the narrower `AccountConfig` (`WaterXPackages extends AccountPackages`).
+ */
+import type { BaseLineClient } from "../base-client.ts";
+import type { AccountConfig, NativeCustodyAsset, WaterxCreditPackage, WormholeBridgePackage, WormholeInfraConfig, WxaConfig } from "./config.ts";
+/**
+ * The slice the **generic wxa builders** (create account / delegates / alias /
+ * deposit-request) read — just the `waterx_account` + `bucket_framework` package
+ * ids and transport. Both `PerpClient` and `PredictClient` satisfy it (their full
+ * configs are assignable to {@link WxaConfig}), so these builders are shared by
+ * both lines. The funding-capable {@link AccountClientLike} is a superset.
+ */
+export type WxaClientLike = BaseLineClient<WxaConfig>;
+export interface AccountClientLike extends BaseLineClient<AccountConfig> {
+    /** External Wormhole infra (network default, overridable via config). */
+    readonly wormhole: WormholeInfraConfig;
+    /** Fully-qualified CREDIT coin Move type; throws if `waterx_credit.credit_type` is unset. */
+    creditType(): string;
+    /** `waterx_credit` package entry; throws if absent. */
+    getCredit(): WaterxCreditPackage;
+    /** `wormhole_bridge` package entry; throws if absent. */
+    getBridge(): WormholeBridgePackage;
+    /** Sui Wormhole `State` object id (per-deployment, falls back to `wormhole` infra). */
+    wormholeStateId(): string;
+    /** All native-custody backing-asset rows; throws if no custody vault. */
+    getNativeAssets(): readonly NativeCustodyAsset[];
+    /** A native-custody asset row by its fully-qualified Move type; throws if unknown. */
+    getNativeAsset(moveType: string): NativeCustodyAsset;
+}

package/dist/src/account/client.js

@@ -0,0 +1,17 @@
+/**
+ * `AccountClientLike` — the narrow capability slice the account/funding builders
+ * read, instead of the concrete `PerpClient`.
+ *
+ * The account framework + funding (credit / custody / bridge / consolidate) is
+ * the contract's **base** layer: both product lines depend down onto it. Typing
+ * these builders to `PerpClient` inverted that — so they take this structural
+ * interface instead. `PerpClient` satisfies it without an `implements` clause
+ * (it `extends BaseLineClient<WaterXConfig>` and carries the config-view slice +
+ * the `wormhole` infra block); a future funding-capable client can too.
+ *
+ * The config schema it reads lives in `account/config.ts` (the base layer), so
+ * this file imports **nothing** from `perp/` — `account/` no longer depends on the
+ * perp line even at the type level. `PerpClient`'s `WaterXConfig` is assignable to
+ * the narrower `AccountConfig` (`WaterXPackages extends AccountPackages`).
+ */
+export {};

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

@@ -0,0 +1,151 @@
+/**
+ * Account-layer config schema — the package entries + config slice the base
+ * (`waterx_account` framework + funding: credit / custody / bridge / queue +
+ * referral) reads. This is the **base**: `perp/config.ts` imports these and
+ * `WaterXPackages extends AccountPackages`; nothing here imports `perp/` or
+ * `prediction/`. Snake_case mirrors the canonical `waterx-config` JSON 1:1.
+ */
+import type { BaseLineConfig } from "../base-client.ts";
+export interface BasePackageEntry {
+    published_at: string;
+    original_id: string;
+    version: number;
+    upgrade_capability?: string;
+}
+export interface WxaAccountPackage extends BasePackageEntry {
+    admin_cap: string;
+    account_registry: string;
+}
+export interface WaterxReferralPackage extends BasePackageEntry {
+    /** Shared `ReferralTable`. */
+    referral_table: string;
+}
+export interface WaterxCreditPackage {
+    published_at: string;
+    /** Shared `CreditRegistry<CREDIT>` (phase-1 output). */
+    credit_registry?: string;
+    /**
+     * Fully-qualified CREDIT coin Move type, e.g. `0x..::usd::USD`. Required for
+     * any credit/bridge flow — `client.creditType()` returns it as-is.
+     */
+    credit_type?: string;
+}
+/** One backing-asset row on the native custody vault (PSM). */
+export interface NativeCustodyAsset {
+    /** Human-readable asset label, e.g. `"MOCK_USDC"` / `"USDC"` (from `add_asset`). */
+    name?: string;
+    /** Fully-qualified backing asset Move type `T`. */
+    type: string;
+    decimal: number;
+    mint_fee_scaled: string;
+    burn_fee_scaled: string;
+    min_burn_amount: string;
+}
+export interface NativeCustodyPackage {
+    published_at: string;
+    /** Shared `CustodyVault<CREDIT>` (phase-4 output). */
+    vault?: string;
+    /** Backing assets registered via `add_asset` (array, identified by `type`). */
+    assets: NativeCustodyAsset[];
+}
+export interface TrustedEmitterRow {
+    /** Source EVM chain's Wormhole chain id (e.g. 10002 = Sepolia). */
+    chain_id: number;
+    /** 32-byte left-padded EVM bridge address (0x form). */
+    evm_bridge_address_32b: string;
+    /** Whitelisted 20-byte EVM token addresses (0x form). */
+    evm_tokens_20b: string[];
+}
+export interface WormholeBridgePackage {
+    published_at: string;
+    /** Shared Sui Wormhole `State` object id for this deployment. */
+    wormhole_state: string;
+    hourly_mint_limit?: string;
+    max_mint_per_tx?: string;
+    hourly_burn_limit?: string;
+    max_burn_per_tx?: string;
+    /**
+     * @deprecated EVM emitter↔token config now lives solely under `evm.bridge.chains`
+     * (deposit_vault = emitter, wormhole_chain_id = chain key). The runtime allowlist is
+     * read from the on-chain `Bridge` object, not from config. Kept optional for back-compat.
+     */
+    trusted_emitters?: TrustedEmitterRow[];
+    /** Shared `Bridge` (phase-5 output). */
+    bridge?: string;
+    /**
+     * The bridge's `EmitterCap` object id (Sui-side Wormhole emitter address
+     * for burn-relay Wormholescan lookups). Not written by the deploy script
+     * — resolve from the on-chain `Bridge` object if absent.
+     */
+    emitter_cap?: string;
+}
+export interface WithdrawalQueuePackage {
+    published_at: string;
+    /** Addresses on the queue executor allowlist (keepers). */
+    executors?: string[];
+    /** Shared `Queue<CREDIT>` (phase-6 output). */
+    queue?: string;
+}
+/**
+ * Wormhole infra for the cross-chain credit bridge. `state_id` is the same
+ * shared Sui Wormhole `State` object Pyth uses (kept in sync with
+ * `PYTH_DEFAULTS[*].wormhole_state_id`). Override per-deployment via
+ * `WaterXConfig.wormhole` if a deployment ever points elsewhere.
+ */
+export interface WormholeInfraConfig {
+    /** Shared Sui Wormhole `State` object. */
+    state_id: string;
+    /** Wormhole core package id on Sui. */
+    core_package: string;
+    /** Sui's Wormhole chain id (21 on both mainnet and testnet). */
+    sui_chain_id: number;
+    /** Wormholescan REST base for VAA lookups (no trailing slash). */
+    wormholescan_api: string;
+}
+/**
+ * The minimal package slice the **generic wxa builders** (create / delegate /
+ * alias …) read — only the fields BOTH the perp and prediction line configs are
+ * guaranteed to carry (prediction makes `original_id` / `version` / `admin_cap`
+ * optional, so the strict {@link WxaAccountPackage} is too narrow a target here).
+ */
+export interface WxaPackages {
+    bucket_framework: {
+        published_at: string;
+    };
+    waterx_account: {
+        published_at: string;
+        account_registry: string;
+    };
+    waterx_referral?: {
+        published_at: string;
+        referral_table: string;
+    };
+}
+/** Narrow config for the generic wxa builders — both line configs are assignable. */
+export interface WxaConfig extends BaseLineConfig {
+    packages: WxaPackages;
+}
+/**
+ * The package subset the account base + funding builders read. The full
+ * line config (`WaterXPackages`) **extends** this, so any line client's config
+ * is structurally an account config.
+ */
+export interface AccountPackages extends WxaPackages {
+    bucket_framework: BasePackageEntry;
+    waterx_account: WxaAccountPackage;
+    waterx_referral?: WaterxReferralPackage;
+    waterx_credit?: WaterxCreditPackage;
+    wormhole_bridge?: WormholeBridgePackage;
+    withdrawal_queue?: WithdrawalQueuePackage;
+    native_custody?: NativeCustodyPackage;
+}
+/**
+ * The narrow config shape the account/funding builders need. `WaterXConfig`
+ * (the perp line's full config) is assignable to this, so `PerpClient` satisfies
+ * {@link import("./client.ts").AccountClientLike} without importing `perp/`.
+ */
+export interface AccountConfig extends BaseLineConfig {
+    packages: AccountPackages;
+    /** Wormhole infra override (defaults from `WORMHOLE_DEFAULTS[network]`). */
+    wormhole?: WormholeInfraConfig;
+}

package/dist/src/account/config.js

@@ -0,0 +1,8 @@
+/**
+ * Account-layer config schema — the package entries + config slice the base
+ * (`waterx_account` framework + funding: credit / custody / bridge / queue +
+ * referral) reads. This is the **base**: `perp/config.ts` imports these and
+ * `WaterXPackages extends AccountPackages`; nothing here imports `perp/` or
+ * `prediction/`. Snake_case mirrors the canonical `waterx-config` JSON 1:1.
+ */
+export {};

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

@@ -0,0 +1,5 @@
+/**
+ * Account-framework constants (shared base — neither perp- nor prediction-specific).
+ */
+/** Sentinel "accumulator root" address passed to `waterx_account` add-position/order. */
+export declare const ACCUMULATOR_ROOT = "0xacc";

package/dist/src/account/constants.js

@@ -0,0 +1,5 @@
+/**
+ * Account-framework constants (shared base — neither perp- nor prediction-specific).
+ */
+/** Sentinel "accumulator root" address passed to `waterx_account` add-position/order. */
+export const ACCUMULATOR_ROOT = "0xacc";

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

@@ -0,0 +1,15 @@
+/**
+ * Referral queries (`waterx_referral::referral_table`).
+ *
+ * Account-base reads — typed to {@link WxaClientLike} (just `waterx_referral` +
+ * transport), not the perp line. Co-located with the referral builders in
+ * `account/referral.ts`; both product lines can use them. The perp `fetch/`
+ * barrel re-exports these for back-compat.
+ */
+import type { WxaClientLike } from "../client.ts";
+/** Returns the referrer address bound to `referee`, or `undefined` if none. */
+export declare function getRefererFor(client: WxaClientLike, referee: string): Promise<string | undefined>;
+/** True if `code` is a syntactically valid referral code (matches the contract's char rules). */
+export declare function isValidReferralCode(client: WxaClientLike, code: string): Promise<boolean>;
+/** True if `code` is already claimed in the on-chain ReferralTable. */
+export declare function referralCodeExists(client: WxaClientLike, code: string): Promise<boolean>;

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

@@ -0,0 +1,51 @@
+/**
+ * Referral queries (`waterx_referral::referral_table`).
+ *
+ * Account-base reads — typed to {@link WxaClientLike} (just `waterx_referral` +
+ * transport), not the perp line. Co-located with the referral builders in
+ * `account/referral.ts`; both product lines can use them. The perp `fetch/`
+ * barrel re-exports these for back-compat.
+ */
+import { bcs } from "@mysten/sui/bcs";
+import { Transaction } from "@mysten/sui/transactions";
+import { isValidReferralCode as isValidReferralCodeCall, referralCodeExists as referralCodeExistsCall, tryGetRefer as tryGetReferCall, } from "../../generated/waterx_referral/referral_table.js";
+import { simulateAndExtract } from "./simulate.js";
+function requireReferralPackage(client) {
+    const pkg = client.config.packages.waterx_referral?.published_at;
+    const table = client.config.packages.waterx_referral?.referral_table;
+    if (!pkg || !table) {
+        throw new Error("referral package not configured: set config.packages.waterx_referral.{published_at,referral_table}");
+    }
+    return { pkg, table };
+}
+/** Returns the referrer address bound to `referee`, or `undefined` if none. */
+export async function getRefererFor(client, referee) {
+    const { pkg, table } = requireReferralPackage(client);
+    const tx = new Transaction();
+    tryGetReferCall({
+        package: pkg,
+        arguments: { table: tx.object(table), referee },
+    })(tx);
+    const bytes = await simulateAndExtract(client, tx);
+    const opt = bcs.option(bcs.Address).parse(bytes);
+    return opt ?? undefined;
+}
+/** True if `code` is a syntactically valid referral code (matches the contract's char rules). */
+export async function isValidReferralCode(client, code) {
+    const { pkg } = requireReferralPackage(client);
+    const tx = new Transaction();
+    isValidReferralCodeCall({ package: pkg, arguments: { code } })(tx);
+    const bytes = await simulateAndExtract(client, tx);
+    return bcs.bool().parse(bytes);
+}
+/** True if `code` is already claimed in the on-chain ReferralTable. */
+export async function referralCodeExists(client, code) {
+    const { pkg, table } = requireReferralPackage(client);
+    const tx = new Transaction();
+    referralCodeExistsCall({
+        package: pkg,
+        arguments: { table: tx.object(table), code },
+    })(tx);
+    const bytes = await simulateAndExtract(client, tx);
+    return bcs.bool().parse(bytes);
+}

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

@@ -0,0 +1,34 @@
+/**
+ * Shared simulate/decode plumbing for the read helpers.
+ *
+ * Each public read builds a one-shot PTB, runs `client.simulate(tx)` with the
+ * zero address as sender, and decodes the command's BCS return values. Typed to
+ * the transport base ({@link BaseLineClient}) so any line client satisfies it —
+ * this is the **base** copy the perp `fetch/simulate.ts` re-exports, so the
+ * plumbing lives once. Internal to `fetch/` — not part of the public surface.
+ */
+import { Transaction } from "@mysten/sui/transactions";
+import type { BaseLineClient } from "../../base-client.ts";
+export interface SimulationCommandResult {
+    returnValues?: {
+        bcs?: Uint8Array | string;
+        value?: {
+            bcs?: Uint8Array | string;
+        };
+    }[];
+}
+export interface SimulationResult {
+    $kind?: string;
+    FailedTransaction?: {
+        status?: {
+            error?: {
+                message?: string;
+            };
+        };
+    };
+    commandResults?: SimulationCommandResult[] | null;
+}
+export declare function toBytes(b: Uint8Array | string | undefined): Uint8Array | undefined;
+export declare function simulateRaw(client: BaseLineClient, tx: Transaction): Promise<SimulationResult>;
+export declare function extractAt(sim: SimulationResult, commandIndex: number, returnIndex?: number): Uint8Array;
+export declare function simulateAndExtract(client: BaseLineClient, tx: Transaction, commandIndex?: number, returnIndex?: number): Promise<Uint8Array>;

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

@@ -0,0 +1,43 @@
+/**
+ * Shared simulate/decode plumbing for the read helpers.
+ *
+ * Each public read builds a one-shot PTB, runs `client.simulate(tx)` with the
+ * zero address as sender, and decodes the command's BCS return values. Typed to
+ * the transport base ({@link BaseLineClient}) so any line client satisfies it —
+ * this is the **base** copy the perp `fetch/simulate.ts` re-exports, so the
+ * plumbing lives once. Internal to `fetch/` — not part of the public surface.
+ */
+import { fromBase64 } from "@mysten/bcs";
+import { DRY_RUN_SENDER } from "../../constants.js";
+export function toBytes(b) {
+    if (!b)
+        return undefined;
+    if (typeof b === "string")
+        return fromBase64(b);
+    // gRPC returns Uint8Array; JSON-RPC serialization may turn it into a
+    // numeric-indexed object. Normalize both.
+    if (b instanceof Uint8Array)
+        return b;
+    return new Uint8Array(Object.values(b));
+}
+export async function simulateRaw(client, tx) {
+    tx.setSender(DRY_RUN_SENDER);
+    const sim = (await client.simulate(tx));
+    if (sim.$kind === "FailedTransaction") {
+        const err = sim.FailedTransaction?.status?.error?.message ?? "FailedTransaction";
+        throw new Error(`simulate aborted: ${err}`);
+    }
+    return sim;
+}
+export function extractAt(sim, commandIndex, returnIndex = 0) {
+    const ret = sim.commandResults?.[commandIndex]?.returnValues?.[returnIndex];
+    const bytes = toBytes(ret?.bcs) ?? toBytes(ret?.value?.bcs);
+    if (!bytes) {
+        throw new Error(`simulate returned no BCS value at commandResults[${commandIndex}].returnValues[${returnIndex}]`);
+    }
+    return bytes;
+}
+export async function simulateAndExtract(client, tx, commandIndex = 0, returnIndex = 0) {
+    const sim = await simulateRaw(client, tx);
+    return extractAt(sim, commandIndex, returnIndex);
+}