@waterx/sdk 3.0.1 → 3.1.0

package/dist/cjs/src/account/funding/wormhole.js

@@ -0,0 +1,166 @@
+"use strict";
+/**
+ * Wormhole / Wormholescan integration for the cross-chain credit bridge.
+ *
+ * Single source of truth for VAA discovery + (de)serialization — mirrors
+ * `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
+ *     `wormhole_bridge::redeem_vaa`.
+ *   - Withdraw (Sui → EVM): list recent VAAs emitted by the bridge's
+ *     `EmitterCap` to submit on the EVM side.
+ *
+ * Endpoints / chain ids come from `client.wormhole` (network defaults in
+ * `WORMHOLE_DEFAULTS`, overridable via `WaterXConfig.wormhole`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.padEvmEmitter = void 0;
+exports.toWormholescanEmitter = toWormholescanEmitter;
+exports.fetchVaa = fetchVaa;
+exports.listVaasByEmitter = listVaasByEmitter;
+exports.waitForVaa = waitForVaa;
+exports.vaaBase64ToBytes = vaaBase64ToBytes;
+exports.vaaBytesToBase64 = vaaBytesToBase64;
+exports.vaaBase64ToHex = vaaBase64ToHex;
+exports.fetchDepositVaa = fetchDepositVaa;
+exports.listBridgeWithdrawalVaas = listBridgeWithdrawalVaas;
+const bcs_1 = require("@mysten/bcs");
+// ============================================================================
+// Emitter address formatting
+// ============================================================================
+/**
+ * Normalize an emitter id to Wormholescan's `emitter` path segment:
+ * 64-char lowercase hex, no `0x`. Accepts a 0x EVM address (left-padded to
+ * 32 bytes) or a 32-byte Sui object id (the bridge `EmitterCap` id).
+ */
+function toWormholescanEmitter(idOrAddress) {
+    const raw = idOrAddress.startsWith("0x") ? idOrAddress.slice(2) : idOrAddress;
+    return raw.toLowerCase().padStart(64, "0");
+}
+/** EVM-side naming alias of {@link toWormholescanEmitter}. */
+exports.padEvmEmitter = toWormholescanEmitter;
+async function doFetch(url, opts) {
+    const fetchImpl = opts?.fetchImpl ?? globalThis.fetch;
+    if (!fetchImpl) {
+        throw new Error("wormhole: no global `fetch` available; pass opts.fetchImpl");
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), opts?.timeoutMs ?? 10_000);
+    const onOuterAbort = () => controller.abort();
+    opts?.signal?.addEventListener("abort", onOuterAbort, { once: true });
+    try {
+        return await fetchImpl(url, { cache: "no-store", signal: controller.signal });
+    }
+    finally {
+        clearTimeout(timer);
+        opts?.signal?.removeEventListener("abort", onOuterAbort);
+    }
+}
+/**
+ * Fetch a single signed VAA. Returns `null` while guardians haven't signed
+ * it yet (HTTP 404 or no `vaa` field) so callers can retry on the next tick.
+ */
+async function fetchVaa(apiBase, chainId, emitter, sequence, opts) {
+    const url = `${apiBase}/vaas/${chainId}/${emitter}/${sequence}`;
+    const res = await doFetch(url, opts);
+    if (res.status === 404)
+        return null;
+    if (!res.ok) {
+        throw new Error(`Wormholescan ${res.status}: ${await res.text()}`);
+    }
+    const json = (await res.json());
+    if (!json?.data?.vaa)
+        return null;
+    return json.data;
+}
+/**
+ * List recent VAAs emitted by `emitter` on `chainId`, newest first. Used by
+ * the burn relayer to discover Sui→EVM `WithdrawalInitiated` messages
+ * (Wormholescan only returns guardian-signed VAAs, so the await is implicit).
+ */
+async function listVaasByEmitter(apiBase, chainId, emitter, opts) {
+    const page = opts?.page ?? 0;
+    const pageSize = opts?.pageSize ?? 20;
+    const url = `${apiBase}/vaas/${chainId}/${emitter}?page=${page}&pageSize=${pageSize}`;
+    const res = await doFetch(url, opts);
+    if (!res.ok) {
+        throw new Error(`Wormholescan list ${res.status}: ${await res.text()}`);
+    }
+    const json = (await res.json());
+    return json.data ?? [];
+}
+/** Poll {@link fetchVaa} until the VAA is signed or `timeoutMs` elapses. */
+async function waitForVaa(apiBase, chainId, emitter, sequence, opts = {}) {
+    const intervalMs = opts.intervalMs ?? 30_000;
+    const timeoutMs = opts.timeoutMs ?? 25 * 60_000;
+    const start = Date.now();
+    let attempt = 0;
+    while (Date.now() - start < timeoutMs) {
+        if (opts.signal?.aborted)
+            throw new Error("waitForVaa: aborted");
+        attempt++;
+        opts.onTick?.(attempt);
+        const vaa = await fetchVaa(apiBase, chainId, emitter, sequence, opts);
+        if (vaa)
+            return vaa;
+        await abortableSleep(intervalMs, opts.signal);
+    }
+    throw new Error("waitForVaa: timeout");
+}
+function abortableSleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(new Error("waitForVaa: aborted"));
+        };
+        if (signal?.aborted) {
+            clearTimeout(timer);
+            reject(new Error("waitForVaa: aborted"));
+            return;
+        }
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+// ============================================================================
+// VAA (de)serialization — portable (Node + edge/browser)
+// ============================================================================
+/** Base64 VAA → raw bytes (the form Sui `redeem_vaa(vector<u8>)` expects). */
+function vaaBase64ToBytes(b64) {
+    return (0, bcs_1.fromBase64)(b64);
+}
+/** Raw bytes → base64 (round-trips a VAA pulled off-chain). */
+function vaaBytesToBase64(bytes) {
+    return (0, bcs_1.toBase64)(bytes);
+}
+/** Base64 VAA → `0x`-prefixed hex (the form EVM `submitWithdrawalVAA(bytes)` expects). */
+function vaaBase64ToHex(b64) {
+    return `0x${(0, bcs_1.toHex)((0, bcs_1.fromBase64)(b64))}`;
+}
+// ============================================================================
+// Client-aware convenience
+// ============================================================================
+/**
+ * Fetch the signed VAA for an inbound EVM `Deposit` using the client's
+ * configured Wormholescan endpoint. `emitter` is the EVM-side bridge
+ * address (0x form accepted — left-padded automatically); `chainId` is the
+ * source EVM chain's Wormhole chain id.
+ */
+function fetchDepositVaa(client, evmWormholeChainId, evmEmitter, sequence, opts) {
+    return fetchVaa(client.wormhole.wormholescan_api, evmWormholeChainId, toWormholescanEmitter(evmEmitter), sequence, opts);
+}
+/**
+ * List recent Sui→EVM VAAs from the configured bridge `EmitterCap` (burn
+ * relayer). Requires `packages.wormhole_bridge.emitter_cap` in config.
+ */
+function listBridgeWithdrawalVaas(client, opts) {
+    const emitterCap = client.config.packages.wormhole_bridge?.emitter_cap;
+    if (!emitterCap) {
+        throw new Error("wormhole_bridge.emitter_cap missing from config");
+    }
+    return listVaasByEmitter(client.wormhole.wormholescan_api, client.wormhole.sui_chain_id, toWormholescanEmitter(emitterCap), opts);
+}

package/dist/cjs/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/cjs/src/account/index.js

@@ -0,0 +1,45 @@
+"use strict";
+/**
+ * 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).
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./account.js"), exports); // generic waterx_account framework builders
+__exportStar(require("./funding/credit.js"), exports); // cross-chain CREDIT / bridge builders
+__exportStar(require("./funding/custody.js"), exports); // native_custody PSM mint builders

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

@@ -0,0 +1,21 @@
+/**
+ * Referral builders — backed by the standalone `waterx_referral` package.
+ * Requires
+ * `config.packages.waterx_referral.{published_at,referral_table}` to be
+ * populated; otherwise the builder throws so misconfigured deployments fail
+ * loudly instead of silently aborting on-chain.
+ */
+import type { Transaction, TransactionArgument } from "@mysten/sui/transactions";
+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: 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: WxaClientLike, tx: Transaction, params: UseReferralCodeParams): void;

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

@@ -0,0 +1,78 @@
+"use strict";
+/**
+ * Referral builders — backed by the standalone `waterx_referral` package.
+ * Requires
+ * `config.packages.waterx_referral.{published_at,referral_table}` to be
+ * populated; otherwise the builder throws so misconfigured deployments fail
+ * loudly instead of silently aborting on-chain.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setReferralCode = setReferralCode;
+exports.useReferralCode = useReferralCode;
+const referral = __importStar(require("../generated/waterx_referral/referral_table.js"));
+const account_request_ts_1 = require("./account-request.js");
+function requireReferralConfig(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 };
+}
+function setReferralCode(client, tx, params) {
+    const { pkg, table } = requireReferralConfig(client);
+    const req = (0, account_request_ts_1.makeSenderRequest)(client, tx, params.bucketAccount);
+    referral.setReferralCode({
+        package: pkg,
+        arguments: {
+            table: tx.object(table),
+            req: req,
+            code: params.code,
+        },
+    })(tx);
+}
+function useReferralCode(client, tx, params) {
+    const { pkg, table } = requireReferralConfig(client);
+    const req = (0, account_request_ts_1.makeSenderRequest)(client, tx, params.bucketAccount);
+    referral.useReferralCode({
+        package: pkg,
+        arguments: {
+            table: tx.object(table),
+            req: req,
+            code: params.code,
+        },
+    })(tx);
+}

package/dist/cjs/src/account/waterx-account.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Shared `waterx_account` PTB builders.
+ *
+ * Perp and prediction both create/operate accounts through the **same** on-chain
+ * `waterx_account` system (same package + `AccountRegistry`), so the actual PTB
+ * calls are assembled here once. Each product line resolves the deployment
+ * coordinates (`WxaAccountRef`) and builds its own `senderRequest` (via its own
+ * account-request helper), then delegates the moveCall to these functions.
+ *
+ * These builders are raw `tx.moveCall(...)` (no generated-bindings dependency),
+ * so the module is shared by both `src/user/account.ts` (perp) and
+ * `src/prediction/account.ts` (prediction) without coupling to either line's
+ * generated code.
+ */
+import type { Transaction, TransactionArgument } from "@mysten/sui/transactions";
+/** Resolved `waterx_account` deployment coordinates (each line resolves these from its own client). */
+export interface WxaAccountRef {
+    /** `waterx_account` package id (`published_at`). */
+    packageId: string;
+    /** `AccountRegistry` shared-object id. */
+    registry: string;
+}
+/**
+ * `waterx_account::account::create_account`. Returns the new account id
+ * (Move return value). `senderRequest` is the `account::request` hot-potato the
+ * caller built with its own account-request helper.
+ */
+export declare function createAccountCall(tx: Transaction, ref: WxaAccountRef, params: {
+    senderRequest: TransactionArgument;
+    alias: string;
+}): TransactionArgument;

package/dist/cjs/src/account/waterx-account.js

@@ -0,0 +1,29 @@
+"use strict";
+/**
+ * Shared `waterx_account` PTB builders.
+ *
+ * Perp and prediction both create/operate accounts through the **same** on-chain
+ * `waterx_account` system (same package + `AccountRegistry`), so the actual PTB
+ * calls are assembled here once. Each product line resolves the deployment
+ * coordinates (`WxaAccountRef`) and builds its own `senderRequest` (via its own
+ * account-request helper), then delegates the moveCall to these functions.
+ *
+ * These builders are raw `tx.moveCall(...)` (no generated-bindings dependency),
+ * so the module is shared by both `src/user/account.ts` (perp) and
+ * `src/prediction/account.ts` (prediction) without coupling to either line's
+ * generated code.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAccountCall = createAccountCall;
+/**
+ * `waterx_account::account::create_account`. Returns the new account id
+ * (Move return value). `senderRequest` is the `account::request` hot-potato the
+ * caller built with its own account-request helper.
+ */
+function createAccountCall(tx, ref, params) {
+    const [accountId] = tx.moveCall({
+        target: `${ref.packageId}::account::create_account`,
+        arguments: [tx.object(ref.registry), params.senderRequest, tx.pure.string(params.alias)],
+    });
+    return accountId;
+}

package/dist/cjs/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>;
+}

package/dist/cjs/src/base-client.js

@@ -0,0 +1,101 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseLineClient = exports.DEFAULT_GRPC_URLS = void 0;
+const grpc_1 = require("@mysten/sui/grpc");
+/** Default Sui gRPC base URLs by network (public Mysten fullnodes). */
+exports.DEFAULT_GRPC_URLS = {
+    MAINNET: "https://fullnode.mainnet.sui.io:443",
+    TESTNET: "https://fullnode.testnet.sui.io:443",
+};
+function isPublishedPackage(value) {
+    return (!!value &&
+        typeof value === "object" &&
+        "published_at" in value &&
+        typeof value.published_at === "string" &&
+        value.published_at.length > 0);
+}
+class BaseLineClient {
+    /** gRPC client — all RPC including `simulateTransaction`. */
+    grpcClient;
+    /** Network identifier in upper case (`MAINNET` / `TESTNET`). */
+    network;
+    /** Parsed canonical `waterx-config` JSON for this line. */
+    config;
+    constructor(network, config, opts = {}) {
+        this.network = network;
+        this.config = config;
+        const grpcUrl = opts.grpcUrl ?? config.grpcUrl ?? exports.DEFAULT_GRPC_URLS[network];
+        this.grpcClient = new grpc_1.SuiGrpcClient({
+            baseUrl: grpcUrl,
+            network: network.toLowerCase(),
+        });
+    }
+    // ========================================================
+    // 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 });
+    }
+    /**
+     * 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).
+     */
+    async simulate(tx) {
+        return this.grpcClient.simulateTransaction({
+            transaction: tx,
+            include: { commandResults: true },
+        });
+    }
+    async signAndExecuteTransaction(params) {
+        return this.grpcClient.signAndExecuteTransaction(params);
+    }
+    // ========================================================
+    // Shared config lookup
+    // ========================================================
+    /** All package IDs (`published_at`) keyed by package name. */
+    packageIds() {
+        const out = {};
+        for (const [name, pkg] of Object.entries(this.config.packages)) {
+            if (isPublishedPackage(pkg))
+                out[name] = pkg.published_at;
+        }
+        return out;
+    }
+}
+exports.BaseLineClient = BaseLineClient;

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

@@ -0,0 +1,32 @@
+export type Network = "MAINNET" | "TESTNET";
+/** Basis-point denominator (10_000). Matches BP_SCALE in the Move contracts. */
+export declare const BPS_SCALE = 10000n;
+/** Float scaling factor (1e9). All `Float` values from `bucket_v2_framework` are 1e9-scaled. */
+export declare const FLOAT_SCALE = 1000000000n;
+/** Double scaling factor (1e18). Used for high-precision intermediate values (e.g. u256 fields). */
+export declare const DOUBLE_SCALE = 1000000000000000000n;
+/** SUI coin decimals (gas + staking rewards). */
+export declare const SUI_DECIMALS = 9;
+/** WLP LP-token decimals. */
+export declare const WLP_DECIMALS = 6;
+/** Shared decimals for trading collateral / WLP backing assets (USDC, USDSUI). */
+export declare const COLLATERAL_DECIMALS = 6;
+/**
+ * @deprecated Import the individual `SUI_DECIMALS` / `WLP_DECIMALS` /
+ * `COLLATERAL_DECIMALS` constants instead. Kept as a back-compat shim so
+ * downstream code that still does `import { TOKEN_DECIMALS }` keeps working;
+ * removed in a future major.
+ */
+export declare const TOKEN_DECIMALS: {
+    readonly SUI: 9;
+    readonly USDC: 6;
+    readonly USDSUI: 6;
+    readonly WLP: 6;
+};
+export declare const MS_PER_YEAR: number;
+/**
+ * Zero-address placeholder used as the sender in dry-run / simulate calls.
+ * Line-agnostic (every read path simulates with it); re-exported from
+ * `perp/constants.ts` for back-compat.
+ */
+export declare const DRY_RUN_SENDER = "0x0000000000000000000000000000000000000000000000000000000000000000";

package/dist/cjs/src/constants.js

@@ -0,0 +1,41 @@
+"use strict";
+// Shared, line-agnostic primitives (network id, scaling, decimals, time).
+// Perp-domain enums (permissions / order tags / action codes / fee rates) live
+// in `perp/constants.ts`; prediction has its own `prediction/constants.ts`.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DRY_RUN_SENDER = exports.MS_PER_YEAR = exports.TOKEN_DECIMALS = exports.COLLATERAL_DECIMALS = exports.WLP_DECIMALS = exports.SUI_DECIMALS = exports.DOUBLE_SCALE = exports.FLOAT_SCALE = exports.BPS_SCALE = void 0;
+// ======== Scaling ========
+/** Basis-point denominator (10_000). Matches BP_SCALE in the Move contracts. */
+exports.BPS_SCALE = 10000n;
+/** Float scaling factor (1e9). All `Float` values from `bucket_v2_framework` are 1e9-scaled. */
+exports.FLOAT_SCALE = 1000000000n;
+/** Double scaling factor (1e18). Used for high-precision intermediate values (e.g. u256 fields). */
+exports.DOUBLE_SCALE = 1000000000000000000n;
+// ======== Token decimals ========
+/** SUI coin decimals (gas + staking rewards). */
+exports.SUI_DECIMALS = 9;
+/** WLP LP-token decimals. */
+exports.WLP_DECIMALS = 6;
+/** Shared decimals for trading collateral / WLP backing assets (USDC, USDSUI). */
+exports.COLLATERAL_DECIMALS = 6;
+/**
+ * @deprecated Import the individual `SUI_DECIMALS` / `WLP_DECIMALS` /
+ * `COLLATERAL_DECIMALS` constants instead. Kept as a back-compat shim so
+ * downstream code that still does `import { TOKEN_DECIMALS }` keeps working;
+ * removed in a future major.
+ */
+exports.TOKEN_DECIMALS = {
+    SUI: exports.SUI_DECIMALS,
+    USDC: exports.COLLATERAL_DECIMALS,
+    USDSUI: exports.COLLATERAL_DECIMALS,
+    WLP: exports.WLP_DECIMALS,
+};
+// ======== Time ========
+exports.MS_PER_YEAR = 365 * 24 * 60 * 60 * 1000;
+// ======== Well-known addresses ========
+/**
+ * Zero-address placeholder used as the sender in dry-run / simulate calls.
+ * Line-agnostic (every read path simulates with it); re-exported from
+ * `perp/constants.ts` for back-compat.
+ */
+exports.DRY_RUN_SENDER = "0x0000000000000000000000000000000000000000000000000000000000000000";