@waterx/sdk 2.4.1 → 3.0.0

package/dist/src/{index.d.ts → perp/index.d.ts}

@@ -1,29 +1,29 @@
-export { WaterXClient } from "./client.ts";
+export { PerpClient } from "./client.ts";
 export type { CreateClientOptions } from "./client.ts";
 export { PYTH_DEFAULTS, WORMHOLE_DEFAULTS, clearConfigCache, defaultConfigUrl, loadConfig, } from "./config.ts";
 export type { BasePackageEntry, ConstantFeedEntry, WaterxReferralPackage, LoadConfigOptions, NativeCustodyAsset, NativeCustodyPackage, PythInfraConfig, PythRulePackage, PythSponsorRulePackage, SupraFeedEntry, SupraRulePackage, TestnetFaucetPackage, TrustedEmitterRow, WaterXConfig, WaterXPackages, WaterxCreditPackage, WaterxOraclePackage, WaterxPerpMarketEntry, WaterxPerpPackage, WaterxStakingPackage, WithdrawalQueuePackage, WlpPackage, WormholeBridgePackage, WormholeInfraConfig, WxaAccountPackage, } from "./config.ts";
 export { ACTION_ADD_PRE_ORDER, ACTION_CANCEL_ORDER, ACTION_CANCEL_PRE_ORDER, ACTION_CLOSE_POSITION, ACTION_DECREASE_POSITION, ACTION_DEPOSIT_COLLATERAL, ACTION_INCREASE_POSITION, ACTION_LIQUIDATE, ACTION_OPEN_POSITION, ACTION_PLACE_ORDER, ACTION_UPDATE_ORDER, ACTION_WITHDRAW_COLLATERAL, BPS_SCALE, CRYPTO_FEE_RATE, DOUBLE_SCALE, DRY_RUN_SENDER, FLOAT_SCALE, MAINTENANCE_MARGIN_RATE, ORDER_LIMIT_BUY, ORDER_LIMIT_SELL, ORDER_STOP_BUY, ORDER_STOP_SELL, ORDER_TAG_WILDCARD, PERM_ALL, PERM_ALL_TRADING, PERM_CANCEL_ORDER, PERM_CLOSE_POSITION, PERM_DECREASE_POSITION, PERM_DEPOSIT_COLLATERAL, PERM_INCREASE_POSITION, PERM_MINT_WLP, PERM_OPEN_POSITION, PERM_PLACE_ORDER, PERM_REDEEM_WLP, PERM_WITHDRAW_COLLATERAL, STAKING_PERM_DEPOSIT_STAKE, STAKING_PERM_REDEEM_STAKE, STAKING_PERM_CLAIM_REWARD, STAKING_PERM_ALL, STOCK_FEE_RATE, MS_PER_YEAR, SUI_DECIMALS, WLP_DECIMALS, COLLATERAL_DECIMALS, TOKEN_DECIMALS, } from "./constants.ts";
 export type { Network } from "./constants.ts";
-export { getMarketTickers, getCollateralAssets } from "./utils/config.ts";
-export { annualizedApyFromRatio, annualizeFundingRate, calcBorrowRate, calcBorrowRateAccrual, calcDynamicFeeBps, calcEffectiveCollateralUsd, calcEstLiqPrice, calcFee, calcFundingFeeUsd, calcFundingRate, calcImpactFeeRate, calcLeverage, calcMaxReducibleCollateralUsd, calcNotional, calcPositionBorrowFee, calcTokenUtilizationBps, calcTotalTradingFeeRate, calcUnrealizedPnl, calcWlpIncentiveApy, calcWlpMintOut, calcWlpPrice, calcWlpRedeemOut, decodeFundingIndexDelta, rawPrice, } from "./utils/math.ts";
+export { getMarketTickers, getCollateralAssets } from "../utils/config.ts";
+export { annualizedApyFromRatio, annualizeFundingRate, calcBorrowRate, calcBorrowRateAccrual, calcDynamicFeeBps, calcEffectiveCollateralUsd, calcEstLiqPrice, calcFee, calcFundingFeeUsd, calcFundingRate, calcImpactFeeRate, calcLeverage, calcMaxReducibleCollateralUsd, calcNotional, calcPositionBorrowFee, calcTokenUtilizationBps, calcTotalTradingFeeRate, calcUnrealizedPnl, calcWlpIncentiveApy, calcWlpMintOut, calcWlpPrice, calcWlpRedeemOut, decodeFundingIndexDelta, rawPrice, } from "../utils/math.ts";
 export * from "./user/index.ts";
 export * from "./tx-builders.ts";
 export * from "./fetch.ts";
-export { PythCache, aggregateTicker, aggregateTickerWithConstant, aggregateTickerWithPyth, buildPythPriceUpdateCalls, fetchPriceFeedsUpdateData, refreshOraclePrices, updatePythPrices, } from "./utils/pyth.ts";
-export { fetchDepositVaa, fetchVaa, listBridgeWithdrawalVaas, listVaasByEmitter, padEvmEmitter, toWormholescanEmitter, vaaBase64ToBytes, vaaBase64ToHex, vaaBytesToBase64, waitForVaa, } from "./utils/wormhole.ts";
-export type { VaaListItem, VaaResponse, WormholescanOptions } from "./utils/wormhole.ts";
-export { AccountData as AccountDataBcs, GlobalConfigData as GlobalConfigDataBcs, MarketData as MarketDataBcs, OrderData as OrderDataBcs, PoolData as PoolDataBcs, PositionData as PositionDataBcs, RedeemRequestData as RedeemRequestDataBcs, TokenPoolData as TokenPoolDataBcs, } from "./generated/waterx_perp_view/view.ts";
-export { Position as PositionBcs, Order as OrderBcs } from "./generated/waterx_perp/position.ts";
-export { Market as MarketBcs } from "./generated/waterx_perp/trading.ts";
-export { MarketConfig as MarketConfigBcs } from "./generated/waterx_perp/market_config.ts";
-export * as tradingCalls from "./generated/waterx_perp/trading.ts";
-export * as lpPoolCalls from "./generated/waterx_perp/lp_pool.ts";
-export * as viewCalls from "./generated/waterx_perp_view/view.ts";
-export * as wxaAccountCalls from "./generated/waterx_account/account.ts";
-export * as stakingCalls from "./generated/waterx_staking/waterx_staking.ts";
-export * as oracleCalls from "./generated/waterx_oracle/oracle.ts";
-export * as pythRuleCalls from "./generated/waterx_pyth_rule/pyth_rule.ts";
-export * as pythSponsorRuleCalls from "./generated/pyth_sponsor_rule/pyth_sponsor_rule.ts";
-export * as referralCalls from "./generated/waterx_referral/referral_table.ts";
-export * as nativeCustodyCalls from "./generated/native_custody/custody_vault.ts";
-export * as withdrawalQueueCalls from "./generated/withdrawal_queue/withdrawal_queue.ts";
+export { PythCache, aggregateTicker, aggregateTickerWithConstant, aggregateTickerWithPyth, buildPythPriceUpdateCalls, fetchPriceFeedsUpdateData, refreshOraclePrices, updatePythPrices, } from "../oracle/index.ts";
+export { fetchDepositVaa, fetchVaa, listBridgeWithdrawalVaas, listVaasByEmitter, padEvmEmitter, toWormholescanEmitter, vaaBase64ToBytes, vaaBase64ToHex, vaaBytesToBase64, waitForVaa, } from "../account/funding/wormhole.ts";
+export type { VaaListItem, VaaResponse, WormholescanOptions } from "../account/funding/wormhole.ts";
+export { AccountData as AccountDataBcs, GlobalConfigData as GlobalConfigDataBcs, MarketData as MarketDataBcs, OrderData as OrderDataBcs, PoolData as PoolDataBcs, PositionData as PositionDataBcs, RedeemRequestData as RedeemRequestDataBcs, TokenPoolData as TokenPoolDataBcs, } from "../generated/waterx_perp_view/view.ts";
+export { Position as PositionBcs, Order as OrderBcs } from "../generated/waterx_perp/position.ts";
+export { Market as MarketBcs } from "../generated/waterx_perp/trading.ts";
+export { MarketConfig as MarketConfigBcs } from "../generated/waterx_perp/market_config.ts";
+export * as tradingCalls from "../generated/waterx_perp/trading.ts";
+export * as lpPoolCalls from "../generated/waterx_perp/lp_pool.ts";
+export * as viewCalls from "../generated/waterx_perp_view/view.ts";
+export * as wxaAccountCalls from "../generated/waterx_account/account.ts";
+export * as stakingCalls from "../generated/waterx_staking/waterx_staking.ts";
+export * as oracleCalls from "../generated/waterx_oracle/oracle.ts";
+export * as pythRuleCalls from "../generated/waterx_pyth_rule/pyth_rule.ts";
+export * as pythSponsorRuleCalls from "../generated/pyth_sponsor_rule/pyth_sponsor_rule.ts";
+export * as referralCalls from "../generated/waterx_referral/referral_table.ts";
+export * as nativeCustodyCalls from "../generated/native_custody/custody_vault.ts";
+export * as withdrawalQueueCalls from "../generated/withdrawal_queue/withdrawal_queue.ts";

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

@@ -1,35 +1,35 @@
 // ======== Core ========
-export { WaterXClient } from "./client.js";
+export { PerpClient } from "./client.js";
 export { PYTH_DEFAULTS, WORMHOLE_DEFAULTS, clearConfigCache, defaultConfigUrl, loadConfig, } from "./config.js";
 // ======== Constants & enums ========
 export { ACTION_ADD_PRE_ORDER, ACTION_CANCEL_ORDER, ACTION_CANCEL_PRE_ORDER, ACTION_CLOSE_POSITION, ACTION_DECREASE_POSITION, ACTION_DEPOSIT_COLLATERAL, ACTION_INCREASE_POSITION, ACTION_LIQUIDATE, ACTION_OPEN_POSITION, ACTION_PLACE_ORDER, ACTION_UPDATE_ORDER, ACTION_WITHDRAW_COLLATERAL, BPS_SCALE, CRYPTO_FEE_RATE, DOUBLE_SCALE, DRY_RUN_SENDER, FLOAT_SCALE, MAINTENANCE_MARGIN_RATE, ORDER_LIMIT_BUY, ORDER_LIMIT_SELL, ORDER_STOP_BUY, ORDER_STOP_SELL, ORDER_TAG_WILDCARD, PERM_ALL, PERM_ALL_TRADING, PERM_CANCEL_ORDER, PERM_CLOSE_POSITION, PERM_DECREASE_POSITION, PERM_DEPOSIT_COLLATERAL, PERM_INCREASE_POSITION, PERM_MINT_WLP, PERM_OPEN_POSITION, PERM_PLACE_ORDER, PERM_REDEEM_WLP, PERM_WITHDRAW_COLLATERAL, STAKING_PERM_DEPOSIT_STAKE, STAKING_PERM_REDEEM_STAKE, STAKING_PERM_CLAIM_REWARD, STAKING_PERM_ALL, STOCK_FEE_RATE, MS_PER_YEAR, SUI_DECIMALS, WLP_DECIMALS, COLLATERAL_DECIMALS, TOKEN_DECIMALS, } from "./constants.js";
 // ======== Utilities ========
-export { getMarketTickers, getCollateralAssets } from "./utils/config.js";
-export { annualizedApyFromRatio, annualizeFundingRate, calcBorrowRate, calcBorrowRateAccrual, calcDynamicFeeBps, calcEffectiveCollateralUsd, calcEstLiqPrice, calcFee, calcFundingFeeUsd, calcFundingRate, calcImpactFeeRate, calcLeverage, calcMaxReducibleCollateralUsd, calcNotional, calcPositionBorrowFee, calcTokenUtilizationBps, calcTotalTradingFeeRate, calcUnrealizedPnl, calcWlpIncentiveApy, calcWlpMintOut, calcWlpPrice, calcWlpRedeemOut, decodeFundingIndexDelta, rawPrice, } from "./utils/math.js";
+export { getMarketTickers, getCollateralAssets } from "../utils/config.js";
+export { annualizedApyFromRatio, annualizeFundingRate, calcBorrowRate, calcBorrowRateAccrual, calcDynamicFeeBps, calcEffectiveCollateralUsd, calcEstLiqPrice, calcFee, calcFundingFeeUsd, calcFundingRate, calcImpactFeeRate, calcLeverage, calcMaxReducibleCollateralUsd, calcNotional, calcPositionBorrowFee, calcTokenUtilizationBps, calcTotalTradingFeeRate, calcUnrealizedPnl, calcWlpIncentiveApy, calcWlpMintOut, calcWlpPrice, calcWlpRedeemOut, decodeFundingIndexDelta, rawPrice, } from "../utils/math.js";
 // ======== Transaction builders (user-side) ========
 export * from "./user/index.js";
 // ======== High-level Tx builders ========
 export * from "./tx-builders.js";
 // ======== Read-only queries ========
 export * from "./fetch.js";
-// ======== Pyth oracle utilities ========
-export { PythCache, aggregateTicker, aggregateTickerWithConstant, aggregateTickerWithPyth, buildPythPriceUpdateCalls, fetchPriceFeedsUpdateData, refreshOraclePrices, updatePythPrices, } from "./utils/pyth.js";
+// ======== Oracle utilities (Pyth source + rule aggregation) ========
+export { PythCache, aggregateTicker, aggregateTickerWithConstant, aggregateTickerWithPyth, buildPythPriceUpdateCalls, fetchPriceFeedsUpdateData, refreshOraclePrices, updatePythPrices, } from "../oracle/index.js";
 // ======== Wormhole / Wormholescan utilities (credit bridge) ========
-export { fetchDepositVaa, fetchVaa, listBridgeWithdrawalVaas, listVaasByEmitter, padEvmEmitter, toWormholescanEmitter, vaaBase64ToBytes, vaaBase64ToHex, vaaBytesToBase64, waitForVaa, } from "./utils/wormhole.js";
+export { fetchDepositVaa, fetchVaa, listBridgeWithdrawalVaas, listVaasByEmitter, padEvmEmitter, toWormholescanEmitter, vaaBase64ToBytes, vaaBase64ToHex, vaaBytesToBase64, waitForVaa, } from "../account/funding/wormhole.js";
 // ======== Generated BCS types (sui-ts-codegen) ========
-export { AccountData as AccountDataBcs, GlobalConfigData as GlobalConfigDataBcs, MarketData as MarketDataBcs, OrderData as OrderDataBcs, PoolData as PoolDataBcs, PositionData as PositionDataBcs, RedeemRequestData as RedeemRequestDataBcs, TokenPoolData as TokenPoolDataBcs, } from "./generated/waterx_perp_view/view.js";
-export { Position as PositionBcs, Order as OrderBcs } from "./generated/waterx_perp/position.js";
-export { Market as MarketBcs } from "./generated/waterx_perp/trading.js";
-export { MarketConfig as MarketConfigBcs } from "./generated/waterx_perp/market_config.js";
+export { AccountData as AccountDataBcs, GlobalConfigData as GlobalConfigDataBcs, MarketData as MarketDataBcs, OrderData as OrderDataBcs, PoolData as PoolDataBcs, PositionData as PositionDataBcs, RedeemRequestData as RedeemRequestDataBcs, TokenPoolData as TokenPoolDataBcs, } from "../generated/waterx_perp_view/view.js";
+export { Position as PositionBcs, Order as OrderBcs } from "../generated/waterx_perp/position.js";
+export { Market as MarketBcs } from "../generated/waterx_perp/trading.js";
+export { MarketConfig as MarketConfigBcs } from "../generated/waterx_perp/market_config.js";
 // Re-export entire generated namespaces for power users.
-export * as tradingCalls from "./generated/waterx_perp/trading.js";
-export * as lpPoolCalls from "./generated/waterx_perp/lp_pool.js";
-export * as viewCalls from "./generated/waterx_perp_view/view.js";
-export * as wxaAccountCalls from "./generated/waterx_account/account.js";
-export * as stakingCalls from "./generated/waterx_staking/waterx_staking.js";
-export * as oracleCalls from "./generated/waterx_oracle/oracle.js";
-export * as pythRuleCalls from "./generated/waterx_pyth_rule/pyth_rule.js";
-export * as pythSponsorRuleCalls from "./generated/pyth_sponsor_rule/pyth_sponsor_rule.js";
-export * as referralCalls from "./generated/waterx_referral/referral_table.js";
-export * as nativeCustodyCalls from "./generated/native_custody/custody_vault.js";
-export * as withdrawalQueueCalls from "./generated/withdrawal_queue/withdrawal_queue.js";
+export * as tradingCalls from "../generated/waterx_perp/trading.js";
+export * as lpPoolCalls from "../generated/waterx_perp/lp_pool.js";
+export * as viewCalls from "../generated/waterx_perp_view/view.js";
+export * as wxaAccountCalls from "../generated/waterx_account/account.js";
+export * as stakingCalls from "../generated/waterx_staking/waterx_staking.js";
+export * as oracleCalls from "../generated/waterx_oracle/oracle.js";
+export * as pythRuleCalls from "../generated/waterx_pyth_rule/pyth_rule.js";
+export * as pythSponsorRuleCalls from "../generated/pyth_sponsor_rule/pyth_sponsor_rule.js";
+export * as referralCalls from "../generated/waterx_referral/referral_table.js";
+export * as nativeCustodyCalls from "../generated/native_custody/custody_vault.js";
+export * as withdrawalQueueCalls from "../generated/withdrawal_queue/withdrawal_queue.js";

package/dist/src/perp/tx-builders/common.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Shared scaffolding for the high-level perp `build*Tx` composers:
+ * `CommonBuildOpts`, the new-or-reuse PTB helper, the WLP pool-oracle refresh,
+ * and the request+execute envelope (optional Pyth-sponsor flow + pre-sweep).
+ */
+import { Transaction, type TransactionArgument } from "@mysten/sui/transactions";
+import { PythCache } from "../../oracle/index.ts";
+import type { PerpClient } from "../client.ts";
+export interface CommonBuildOpts {
+    /** Append to an existing PTB instead of creating a new one. */
+    tx?: Transaction;
+    /** Skip oracle refresh entirely (caller manages freshness). Default: false. */
+    skipOraclePriceRefresh?: boolean;
+    /** Share a `PythCache` across builders to avoid redundant pyth_state reads. */
+    pythCache?: PythCache;
+    /**
+     * Wire the `pyth_sponsor_rule` flow:
+     *   - open a Fund via `pyth_sponsor_rule::request(sponsor)`
+     *   - pay Pyth update fees from the Fund (instead of `tx.gas`)
+     *   - reimburse leftover into the sponsor pool + attach
+     *     `PythSponsorRule` witness to the TradingRequest so markets
+     *     whose `request_checklist` contains `PythSponsorRule` accept it
+     * Default: true (matches the testnet/mainnet checklist config).
+     * Pass `false` only when the market checklist is empty.
+     */
+    useSponsor?: boolean;
+    /**
+     * Pre-sweep parked backing assets (USDC, USDsui, …) at the wxa account's
+     * address into USD credit, plus any CREDIT coins/funds at the address into
+     * the internal wxa slot — see {@link appendConsolidateForSpend}. Skips empty
+     * buckets via gRPC probes so it's safe on any account.
+     *
+     * Default: `true`. Set to `false` to skip (e.g. caller already swept,
+     * deployment lacks `native_custody`, or the gRPC reads aren't worth
+     * the latency).
+     *
+     * Each enabled call adds 2 gRPC reads per configured backing asset
+     * (`getBalance` + `listCoins`).
+     *
+     * Only honored by async builders (this is an async sweep). Sync
+     * builders never auto-prepend the sweep — for those, call
+     * {@link buildConsolidateToUsdTx} separately.
+     */
+    consolidateToUsd?: boolean;
+}
+interface RequestParams {
+    ticker: string;
+    collateralType: string;
+    lpType?: string;
+}
+export declare function newTx(opts?: CommonBuildOpts): Transaction;
+/**
+ * Refresh every WLP pool-token oracle (+ caller-supplied extra tickers) and
+ * bump each pool token's `last_price_refresh_timestamp` so the pool's
+ * `assert_prices_fresh` passes when the next `mint_wlp` / `request_redeem` /
+ * trading `execute` runs in the same PTB.
+ */
+export declare function refreshWlpPoolOracles(tx: Transaction, client: PerpClient, extraTickers: string[], opts: {
+    cache?: PythCache;
+    sponsorFund?: {
+        fund: TransactionArgument;
+        packageId: string;
+    };
+    lpType?: string;
+}): Promise<void>;
+/**
+ * Build the *Request + execute envelope with optional Pyth sponsor flow:
+ *
+ *   [fund = sponsor.request()]
+ *   refreshOraclePrices(..., sponsorFund?)
+ *   req = buildRequest()
+ *   [sponsor.reimburse(fund, req)]
+ *   trading::execute(req)
+ */
+export declare function wrapRequestAndExecute(client: PerpClient, tx: Transaction, req: RequestParams & {
+    accountId: string;
+}, collateralTicker: string, opts: CommonBuildOpts | undefined, buildRequest: (sponsorFund?: {
+    fund: TransactionArgument;
+    packageId: string;
+}) => TransactionArgument): Promise<void>;
+/** Run the async sweep iff `consolidateToUsd !== false`. */
+export declare function maybeConsolidate(client: PerpClient, tx: Transaction, accountId: string, opts: CommonBuildOpts | undefined): Promise<void>;
+export {};

package/dist/src/perp/tx-builders/common.js

@@ -0,0 +1,70 @@
+/**
+ * Shared scaffolding for the high-level perp `build*Tx` composers:
+ * `CommonBuildOpts`, the new-or-reuse PTB helper, the WLP pool-oracle refresh,
+ * and the request+execute envelope (optional Pyth-sponsor flow + pre-sweep).
+ */
+import { Transaction } from "@mysten/sui/transactions";
+import { appendConsolidateForSpend } from "../../account/funding/consolidate.js";
+import { openPythSponsorFund, refreshOraclePrices, reimbursePythSponsor, } from "../../oracle/index.js";
+import { getCollateralAssets } from "../../utils/config.js";
+import { executeTrading } from "../user/trading.js";
+import { updateTokenValue } from "../user/wlp.js";
+export function newTx(opts) {
+    return opts?.tx ?? new Transaction();
+}
+/**
+ * Refresh every WLP pool-token oracle (+ caller-supplied extra tickers) and
+ * bump each pool token's `last_price_refresh_timestamp` so the pool's
+ * `assert_prices_fresh` passes when the next `mint_wlp` / `request_redeem` /
+ * trading `execute` runs in the same PTB.
+ */
+export async function refreshWlpPoolOracles(tx, client, extraTickers, opts) {
+    const poolTickers = getCollateralAssets(client.config);
+    const oracleTickers = Array.from(new Set([...extraTickers, ...poolTickers]));
+    await refreshOraclePrices(tx, client, oracleTickers, {
+        cache: opts.cache,
+        sponsorFund: opts.sponsorFund,
+    });
+    for (const tokenType of Object.values(client.config.packages.wlp.pool_tokens)) {
+        updateTokenValue(client, tx, { tokenType, lpType: opts.lpType });
+    }
+}
+/**
+ * Build the *Request + execute envelope with optional Pyth sponsor flow:
+ *
+ *   [fund = sponsor.request()]
+ *   refreshOraclePrices(..., sponsorFund?)
+ *   req = buildRequest()
+ *   [sponsor.reimburse(fund, req)]
+ *   trading::execute(req)
+ */
+export async function wrapRequestAndExecute(client, tx, req, collateralTicker, opts, buildRequest) {
+    await maybeConsolidate(client, tx, req.accountId, opts);
+    const useSponsor = opts?.useSponsor ?? true;
+    let sponsorFund;
+    if (useSponsor)
+        sponsorFund = openPythSponsorFund(tx, client);
+    if (!opts?.skipOraclePriceRefresh) {
+        await refreshWlpPoolOracles(tx, client, [req.ticker, collateralTicker], {
+            cache: opts?.pythCache,
+            sponsorFund,
+            lpType: req.lpType,
+        });
+    }
+    const tradingReq = buildRequest(sponsorFund);
+    if (sponsorFund) {
+        reimbursePythSponsor(tx, client, sponsorFund.fund, tradingReq, req.collateralType);
+    }
+    executeTrading(client, tx, {
+        ticker: req.ticker,
+        collateralType: req.collateralType,
+        lpType: req.lpType,
+        request: tradingReq,
+    });
+}
+/** Run the async sweep iff `consolidateToUsd !== false`. */
+export async function maybeConsolidate(client, tx, accountId, opts) {
+    if (opts?.consolidateToUsd === false)
+        return;
+    await appendConsolidateForSpend(client, tx, accountId);
+}

package/dist/src/perp/tx-builders/credit.d.ts

@@ -0,0 +1,65 @@
+/**
+ * High-level cross-chain credit / bridge composers: VAA redeem (EVM → Sui mint),
+ * the user-side withdraw request (encode route + `request_withdraw` + enqueue),
+ * and the keeper-side queue drain.
+ */
+import { Transaction, type TransactionArgument } from "@mysten/sui/transactions";
+import { type RedeemVaaParams, type RouteWormholeParams } from "../../account/funding/credit.ts";
+import type { PerpClient } from "../client.ts";
+export interface BuildRedeemVaaParams extends RedeemVaaParams {
+    /** Append to an existing PTB instead of creating a new one. */
+    tx?: Transaction;
+}
+/**
+ * Mint (EVM → Sui): `redeem_vaa<CREDIT>` + consume the resulting
+ * `DepositRequest<CREDIT>` via the configured wxa deposit policy, in one
+ * PTB. The recipient wxa account is encoded in the VAA payload.
+ */
+export declare function buildRedeemVaaTx(client: PerpClient, params: BuildRedeemVaaParams): Transaction;
+export type CreditWithdrawRoute = ({
+    kind: "wormhole";
+} & RouteWormholeParams) | {
+    kind: "native";
+    assetType: string;
+};
+export interface BuildRequestCreditWithdrawParams {
+    accountId: string;
+    amount: bigint | number;
+    /** Sui-side recipient (honored for native payouts; ignored for wormhole). */
+    recipient: string;
+    route: CreditWithdrawRoute;
+    creditType?: string;
+    bucketAccount?: string | TransactionArgument;
+    tx?: Transaction;
+}
+/**
+ * Withdraw (user side): encode the route, `account::request_withdraw<CREDIT>`,
+ * then `withdrawal_queue::enqueue<CREDIT>` — all in one PTB. A keeper later
+ * drains the parked entry via {@link buildExecuteWithdrawalTx}.
+ */
+export declare function buildRequestCreditWithdrawTx(client: PerpClient, params: BuildRequestCreditWithdrawParams): Transaction;
+export type ExecuteWithdrawalRoute = {
+    kind: "wormhole";
+    /**
+     * `Coin<SUI>` paying the Wormhole message fee. Omit to mint a zero-value
+     * coin via `0x2::coin::zero<SUI>` — sponsor-safe (never touches `tx.gas`,
+     * so Shinami-style gas stations don't reject the PTB) and free as long as
+     * `WormholeState.message_fee == 0`. Pass an explicit coin (e.g.
+     * `tx.object(...)`) once Wormhole raises the message fee.
+     */
+    wormholeFeeCoin?: TransactionArgument;
+} | {
+    kind: "native";
+    assetType: string;
+};
+export interface BuildExecuteWithdrawalParams {
+    /** Queue entry key (from the `Enqueued` event). */
+    key: bigint | number;
+    route: ExecuteWithdrawalRoute;
+    creditType?: string;
+    /** Executor identity (must be on the queue allowlist). Defaults to tx sender. */
+    bucketAccount?: string | TransactionArgument;
+    tx?: Transaction;
+}
+/** Keeper: drain one parked queue entry. */
+export declare function buildExecuteWithdrawalTx(client: PerpClient, params: BuildExecuteWithdrawalParams): Transaction;

package/dist/src/perp/tx-builders/credit.js

@@ -0,0 +1,62 @@
+/**
+ * High-level cross-chain credit / bridge composers: VAA redeem (EVM → Sui mint),
+ * the user-side withdraw request (encode route + `request_withdraw` + enqueue),
+ * and the keeper-side queue drain.
+ */
+import { Transaction } from "@mysten/sui/transactions";
+import { consumeCreditDeposit, enqueueWithdrawal, executeWithdrawalNative, executeWithdrawalWormhole, redeemVaa, requestCreditWithdraw, routeNative, routeWormhole, } from "../../account/funding/credit.js";
+/**
+ * Mint (EVM → Sui): `redeem_vaa<CREDIT>` + consume the resulting
+ * `DepositRequest<CREDIT>` via the configured wxa deposit policy, in one
+ * PTB. The recipient wxa account is encoded in the VAA payload.
+ */
+export function buildRedeemVaaTx(client, params) {
+    const tx = params.tx ?? new Transaction();
+    const req = redeemVaa(client, tx, params);
+    consumeCreditDeposit(client, tx, { depositRequest: req, creditType: params.creditType });
+    return tx;
+}
+/**
+ * Withdraw (user side): encode the route, `account::request_withdraw<CREDIT>`,
+ * then `withdrawal_queue::enqueue<CREDIT>` — all in one PTB. A keeper later
+ * drains the parked entry via {@link buildExecuteWithdrawalTx}.
+ */
+export function buildRequestCreditWithdrawTx(client, params) {
+    const tx = params.tx ?? new Transaction();
+    const route = params.route.kind === "wormhole"
+        ? routeWormhole(client, tx, params.route)
+        : routeNative(client, tx, { assetType: params.route.assetType });
+    const wreq = requestCreditWithdraw(client, tx, {
+        accountId: params.accountId,
+        amount: params.amount,
+        recipient: params.recipient,
+        route,
+        creditType: params.creditType,
+        bucketAccount: params.bucketAccount,
+    });
+    enqueueWithdrawal(client, tx, { withdrawRequest: wreq, creditType: params.creditType });
+    return tx;
+}
+/** Keeper: drain one parked queue entry. */
+export function buildExecuteWithdrawalTx(client, params) {
+    const tx = params.tx ?? new Transaction();
+    if (params.route.kind === "wormhole") {
+        const fee = params.route.wormholeFeeCoin ??
+            tx.moveCall({ target: "0x2::coin::zero", typeArguments: ["0x2::sui::SUI"] });
+        executeWithdrawalWormhole(client, tx, {
+            key: params.key,
+            wormholeFee: fee,
+            creditType: params.creditType,
+            bucketAccount: params.bucketAccount,
+        });
+    }
+    else {
+        executeWithdrawalNative(client, tx, {
+            key: params.key,
+            assetType: params.route.assetType,
+            creditType: params.creditType,
+            bucketAccount: params.bucketAccount,
+        });
+    }
+    return tx;
+}

package/dist/src/perp/tx-builders/rewards.d.ts

@@ -0,0 +1,30 @@
+/**
+ * High-level reward composer: claim every accrued staking reward to the wxa
+ * account (TTO). The account owner collects each coin via `wxa_account::receive`
+ * in a separate user action.
+ */
+import type { Transaction, TransactionArgument } from "@mysten/sui/transactions";
+import type { PerpClient } from "../client.ts";
+import { type CommonBuildOpts } from "./common.ts";
+export interface BuildClaimRewardsToAccountParams extends CommonBuildOpts {
+    accountId: string;
+    /** Staking pool alias. Defaults to `"WLP"`. */
+    stakeAlias?: string;
+    /** Fully-qualified stake coin type. Defaults to `client.wlpType()`. */
+    stakeType?: string;
+    /**
+     * Reward coin types to claim. Defaults to every rewarder configured for the
+     * stake pool in `waterx_staking.rewarders[stakeAlias]`.
+     */
+    rewarderTypes?: string[];
+    bucketAccount?: string | TransactionArgument;
+}
+/**
+ * Claims every accrued reward for `accountId` on the given stake pool. Each
+ * resulting `Coin<R>` is TTO'd to the wxa account's UID address via
+ * `wxa_account::transfer_coin<R>` (the default behaviour of the Move
+ * `staking::claim` entry — no deposit-policy registration required for the
+ * reward token). The account owner collects each coin via
+ * `wxa_account::receive` in a separate user action.
+ */
+export declare function buildClaimRewardsToAccountTx(client: PerpClient, params: BuildClaimRewardsToAccountParams): Transaction;

package/dist/src/perp/tx-builders/rewards.js

@@ -0,0 +1,34 @@
+/**
+ * High-level reward composer: claim every accrued staking reward to the wxa
+ * account (TTO). The account owner collects each coin via `wxa_account::receive`
+ * in a separate user action.
+ */
+import { claimReward } from "../user/staking.js";
+import { newTx } from "./common.js";
+/**
+ * Claims every accrued reward for `accountId` on the given stake pool. Each
+ * resulting `Coin<R>` is TTO'd to the wxa account's UID address via
+ * `wxa_account::transfer_coin<R>` (the default behaviour of the Move
+ * `staking::claim` entry — no deposit-policy registration required for the
+ * reward token). The account owner collects each coin via
+ * `wxa_account::receive` in a separate user action.
+ */
+export function buildClaimRewardsToAccountTx(client, params) {
+    const tx = newTx(params);
+    const stakeAlias = params.stakeAlias ?? "WLP";
+    const stakeType = params.stakeType ?? client.wlpType();
+    const rewarderTypes = params.rewarderTypes ?? client.getRewarderTypes(stakeAlias);
+    if (rewarderTypes.length === 0) {
+        throw new Error(`buildClaimRewardsToAccountTx: no rewarders configured for stakeAlias=${stakeAlias}`);
+    }
+    for (const rewardType of rewarderTypes) {
+        claimReward(client, tx, {
+            accountId: params.accountId,
+            stakeAlias,
+            stakeType,
+            rewardType,
+            bucketAccount: params.bucketAccount,
+        });
+    }
+    return tx;
+}

package/dist/src/perp/tx-builders/trading.d.ts

@@ -0,0 +1,51 @@
+/**
+ * High-level trading composers: position lifecycle (close / increase /
+ * decrease), collateral deposit / withdraw, and order lifecycle (place /
+ * cancel / update / pre-order). Each wraps the matching `*_request` builder in
+ * the shared request+execute envelope.
+ */
+import type { Transaction } from "@mysten/sui/transactions";
+import type { PerpClient } from "../client.ts";
+import { type AddPreOrderRequestParams, type CancelOrderRequestParams, type CancelPreOrderRequestParams, type PlaceOrderRequestParams, type UpdateOrderRequestParams } from "../user/order.ts";
+import { type ClosePositionRequestParams, type DecreasePositionRequestParams, type DepositCollateralRequestParams, type IncreasePositionRequestParams, type WithdrawCollateralRequestParams } from "../user/trading.ts";
+import { type CommonBuildOpts } from "./common.ts";
+export interface BuildClosePositionParams extends ClosePositionRequestParams, CommonBuildOpts {
+    collateralTicker?: string;
+}
+export declare function buildClosePositionTx(client: PerpClient, params: BuildClosePositionParams): Promise<Transaction>;
+export interface BuildIncreasePositionParams extends IncreasePositionRequestParams, CommonBuildOpts {
+    collateralTicker?: string;
+}
+export declare function buildIncreasePositionTx(client: PerpClient, params: BuildIncreasePositionParams): Promise<Transaction>;
+export interface BuildDecreasePositionParams extends DecreasePositionRequestParams, CommonBuildOpts {
+    collateralTicker?: string;
+}
+export declare function buildDecreasePositionTx(client: PerpClient, params: BuildDecreasePositionParams): Promise<Transaction>;
+export interface BuildDepositCollateralParams extends DepositCollateralRequestParams, CommonBuildOpts {
+    collateralTicker?: string;
+}
+export declare function buildDepositCollateralTx(client: PerpClient, params: BuildDepositCollateralParams): Promise<Transaction>;
+export interface BuildWithdrawCollateralParams extends WithdrawCollateralRequestParams, CommonBuildOpts {
+    collateralTicker?: string;
+}
+export declare function buildWithdrawCollateralTx(client: PerpClient, params: BuildWithdrawCollateralParams): Promise<Transaction>;
+export interface BuildPlaceOrderParams extends PlaceOrderRequestParams, CommonBuildOpts {
+    collateralTicker?: string;
+}
+export declare function buildPlaceOrderTx(client: PerpClient, params: BuildPlaceOrderParams): Promise<Transaction>;
+export interface BuildCancelOrderParams extends CancelOrderRequestParams, CommonBuildOpts {
+    collateralTicker?: string;
+}
+export declare function buildCancelOrderTx(client: PerpClient, params: BuildCancelOrderParams): Promise<Transaction>;
+export interface BuildUpdateOrderParams extends UpdateOrderRequestParams, CommonBuildOpts {
+    collateralTicker?: string;
+}
+export declare function buildUpdateOrderTx(client: PerpClient, params: BuildUpdateOrderParams): Promise<Transaction>;
+export interface BuildCancelPreOrderParams extends CancelPreOrderRequestParams, CommonBuildOpts {
+    collateralTicker?: string;
+}
+export declare function buildCancelPreOrderTx(client: PerpClient, params: BuildCancelPreOrderParams): Promise<Transaction>;
+export interface BuildAddPreOrderParams extends AddPreOrderRequestParams, CommonBuildOpts {
+    collateralTicker?: string;
+}
+export declare function buildAddPreOrderTx(client: PerpClient, params: BuildAddPreOrderParams): Promise<Transaction>;

package/dist/src/perp/tx-builders/trading.js

@@ -0,0 +1,59 @@
+/**
+ * High-level trading composers: position lifecycle (close / increase /
+ * decrease), collateral deposit / withdraw, and order lifecycle (place /
+ * cancel / update / pre-order). Each wraps the matching `*_request` builder in
+ * the shared request+execute envelope.
+ */
+import { addPreOrderRequest, cancelOrderRequest, cancelPreOrderRequest, placeOrderRequest, updateOrderRequest, } from "../user/order.js";
+import { closePositionRequest, decreasePositionRequest, depositCollateralRequest, increasePositionRequest, withdrawCollateralRequest, } from "../user/trading.js";
+import { newTx, wrapRequestAndExecute } from "./common.js";
+export async function buildClosePositionTx(client, params) {
+    const tx = newTx(params);
+    await wrapRequestAndExecute(client, tx, params, params.collateralTicker ?? "USDCUSD", params, () => closePositionRequest(client, tx, params));
+    return tx;
+}
+export async function buildIncreasePositionTx(client, params) {
+    const tx = newTx(params);
+    await wrapRequestAndExecute(client, tx, params, params.collateralTicker ?? "USDCUSD", params, () => increasePositionRequest(client, tx, params));
+    return tx;
+}
+export async function buildDecreasePositionTx(client, params) {
+    const tx = newTx(params);
+    await wrapRequestAndExecute(client, tx, params, params.collateralTicker ?? "USDCUSD", params, () => decreasePositionRequest(client, tx, params));
+    return tx;
+}
+export async function buildDepositCollateralTx(client, params) {
+    const tx = newTx(params);
+    await wrapRequestAndExecute(client, tx, params, params.collateralTicker ?? "USDCUSD", params, () => depositCollateralRequest(client, tx, params));
+    return tx;
+}
+export async function buildWithdrawCollateralTx(client, params) {
+    const tx = newTx(params);
+    await wrapRequestAndExecute(client, tx, params, params.collateralTicker ?? "USDCUSD", params, () => withdrawCollateralRequest(client, tx, params));
+    return tx;
+}
+export async function buildPlaceOrderTx(client, params) {
+    const tx = newTx(params);
+    await wrapRequestAndExecute(client, tx, params, params.collateralTicker ?? "USDCUSD", params, () => placeOrderRequest(client, tx, params));
+    return tx;
+}
+export async function buildCancelOrderTx(client, params) {
+    const tx = newTx(params);
+    await wrapRequestAndExecute(client, tx, params, params.collateralTicker ?? "USDCUSD", params, () => cancelOrderRequest(client, tx, params));
+    return tx;
+}
+export async function buildUpdateOrderTx(client, params) {
+    const tx = newTx(params);
+    await wrapRequestAndExecute(client, tx, params, params.collateralTicker ?? "USDCUSD", params, () => updateOrderRequest(client, tx, params));
+    return tx;
+}
+export async function buildCancelPreOrderTx(client, params) {
+    const tx = newTx(params);
+    await wrapRequestAndExecute(client, tx, params, params.collateralTicker ?? "USDCUSD", params, () => cancelPreOrderRequest(client, tx, params));
+    return tx;
+}
+export async function buildAddPreOrderTx(client, params) {
+    const tx = newTx(params);
+    await wrapRequestAndExecute(client, tx, params, params.collateralTicker ?? "USDCUSD", params, () => addPreOrderRequest(client, tx, params));
+    return tx;
+}