@waterx/sdk 3.0.1 → 3.1.0

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

@@ -0,0 +1,76 @@
+"use strict";
+/**
+ * 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).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.newTx = newTx;
+exports.refreshWlpPoolOracles = refreshWlpPoolOracles;
+exports.wrapRequestAndExecute = wrapRequestAndExecute;
+exports.maybeConsolidate = maybeConsolidate;
+const transactions_1 = require("@mysten/sui/transactions");
+const consolidate_ts_1 = require("../../account/funding/consolidate.js");
+const index_ts_1 = require("../../oracle/index.js");
+const config_ts_1 = require("../../utils/config.js");
+const trading_ts_1 = require("../user/trading.js");
+const wlp_ts_1 = require("../user/wlp.js");
+function newTx(opts) {
+    return opts?.tx ?? new transactions_1.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.
+ */
+async function refreshWlpPoolOracles(tx, client, extraTickers, opts) {
+    const poolTickers = (0, config_ts_1.getCollateralAssets)(client.config);
+    const oracleTickers = Array.from(new Set([...extraTickers, ...poolTickers]));
+    await (0, index_ts_1.refreshOraclePrices)(tx, client, oracleTickers, {
+        cache: opts.cache,
+        sponsorFund: opts.sponsorFund,
+    });
+    for (const tokenType of Object.values(client.config.packages.wlp.pool_tokens)) {
+        (0, wlp_ts_1.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)
+ */
+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 = (0, index_ts_1.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) {
+        (0, index_ts_1.reimbursePythSponsor)(tx, client, sponsorFund.fund, tradingReq, req.collateralType);
+    }
+    (0, trading_ts_1.executeTrading)(client, tx, {
+        ticker: req.ticker,
+        collateralType: req.collateralType,
+        lpType: req.lpType,
+        request: tradingReq,
+    });
+}
+/** Run the async sweep iff `consolidateToUsd !== false`. */
+async function maybeConsolidate(client, tx, accountId, opts) {
+    if (opts?.consolidateToUsd === false)
+        return;
+    await (0, consolidate_ts_1.appendConsolidateForSpend)(client, tx, accountId);
+}

package/dist/cjs/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/cjs/src/perp/tx-builders/credit.js

@@ -0,0 +1,67 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildRedeemVaaTx = buildRedeemVaaTx;
+exports.buildRequestCreditWithdrawTx = buildRequestCreditWithdrawTx;
+exports.buildExecuteWithdrawalTx = buildExecuteWithdrawalTx;
+const transactions_1 = require("@mysten/sui/transactions");
+const credit_ts_1 = require("../../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.
+ */
+function buildRedeemVaaTx(client, params) {
+    const tx = params.tx ?? new transactions_1.Transaction();
+    const req = (0, credit_ts_1.redeemVaa)(client, tx, params);
+    (0, credit_ts_1.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}.
+ */
+function buildRequestCreditWithdrawTx(client, params) {
+    const tx = params.tx ?? new transactions_1.Transaction();
+    const route = params.route.kind === "wormhole"
+        ? (0, credit_ts_1.routeWormhole)(client, tx, params.route)
+        : (0, credit_ts_1.routeNative)(client, tx, { assetType: params.route.assetType });
+    const wreq = (0, credit_ts_1.requestCreditWithdraw)(client, tx, {
+        accountId: params.accountId,
+        amount: params.amount,
+        recipient: params.recipient,
+        route,
+        creditType: params.creditType,
+        bucketAccount: params.bucketAccount,
+    });
+    (0, credit_ts_1.enqueueWithdrawal)(client, tx, { withdrawRequest: wreq, creditType: params.creditType });
+    return tx;
+}
+/** Keeper: drain one parked queue entry. */
+function buildExecuteWithdrawalTx(client, params) {
+    const tx = params.tx ?? new transactions_1.Transaction();
+    if (params.route.kind === "wormhole") {
+        const fee = params.route.wormholeFeeCoin ??
+            tx.moveCall({ target: "0x2::coin::zero", typeArguments: ["0x2::sui::SUI"] });
+        (0, credit_ts_1.executeWithdrawalWormhole)(client, tx, {
+            key: params.key,
+            wormholeFee: fee,
+            creditType: params.creditType,
+            bucketAccount: params.bucketAccount,
+        });
+    }
+    else {
+        (0, credit_ts_1.executeWithdrawalNative)(client, tx, {
+            key: params.key,
+            assetType: params.route.assetType,
+            creditType: params.creditType,
+            bucketAccount: params.bucketAccount,
+        });
+    }
+    return tx;
+}

package/dist/cjs/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/cjs/src/perp/tx-builders/rewards.js

@@ -0,0 +1,37 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildClaimRewardsToAccountTx = buildClaimRewardsToAccountTx;
+const staking_ts_1 = require("../user/staking.js");
+const common_ts_1 = require("./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.
+ */
+function buildClaimRewardsToAccountTx(client, params) {
+    const tx = (0, common_ts_1.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) {
+        (0, staking_ts_1.claimReward)(client, tx, {
+            accountId: params.accountId,
+            stakeAlias,
+            stakeType,
+            rewardType,
+            bucketAccount: params.bucketAccount,
+        });
+    }
+    return tx;
+}

package/dist/cjs/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/cjs/src/perp/tx-builders/trading.js

@@ -0,0 +1,71 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildClosePositionTx = buildClosePositionTx;
+exports.buildIncreasePositionTx = buildIncreasePositionTx;
+exports.buildDecreasePositionTx = buildDecreasePositionTx;
+exports.buildDepositCollateralTx = buildDepositCollateralTx;
+exports.buildWithdrawCollateralTx = buildWithdrawCollateralTx;
+exports.buildPlaceOrderTx = buildPlaceOrderTx;
+exports.buildCancelOrderTx = buildCancelOrderTx;
+exports.buildUpdateOrderTx = buildUpdateOrderTx;
+exports.buildCancelPreOrderTx = buildCancelPreOrderTx;
+exports.buildAddPreOrderTx = buildAddPreOrderTx;
+const order_ts_1 = require("../user/order.js");
+const trading_ts_1 = require("../user/trading.js");
+const common_ts_1 = require("./common.js");
+async function buildClosePositionTx(client, params) {
+    const tx = (0, common_ts_1.newTx)(params);
+    await (0, common_ts_1.wrapRequestAndExecute)(client, tx, params, params.collateralTicker ?? "USDCUSD", params, () => (0, trading_ts_1.closePositionRequest)(client, tx, params));
+    return tx;
+}
+async function buildIncreasePositionTx(client, params) {
+    const tx = (0, common_ts_1.newTx)(params);
+    await (0, common_ts_1.wrapRequestAndExecute)(client, tx, params, params.collateralTicker ?? "USDCUSD", params, () => (0, trading_ts_1.increasePositionRequest)(client, tx, params));
+    return tx;
+}
+async function buildDecreasePositionTx(client, params) {
+    const tx = (0, common_ts_1.newTx)(params);
+    await (0, common_ts_1.wrapRequestAndExecute)(client, tx, params, params.collateralTicker ?? "USDCUSD", params, () => (0, trading_ts_1.decreasePositionRequest)(client, tx, params));
+    return tx;
+}
+async function buildDepositCollateralTx(client, params) {
+    const tx = (0, common_ts_1.newTx)(params);
+    await (0, common_ts_1.wrapRequestAndExecute)(client, tx, params, params.collateralTicker ?? "USDCUSD", params, () => (0, trading_ts_1.depositCollateralRequest)(client, tx, params));
+    return tx;
+}
+async function buildWithdrawCollateralTx(client, params) {
+    const tx = (0, common_ts_1.newTx)(params);
+    await (0, common_ts_1.wrapRequestAndExecute)(client, tx, params, params.collateralTicker ?? "USDCUSD", params, () => (0, trading_ts_1.withdrawCollateralRequest)(client, tx, params));
+    return tx;
+}
+async function buildPlaceOrderTx(client, params) {
+    const tx = (0, common_ts_1.newTx)(params);
+    await (0, common_ts_1.wrapRequestAndExecute)(client, tx, params, params.collateralTicker ?? "USDCUSD", params, () => (0, order_ts_1.placeOrderRequest)(client, tx, params));
+    return tx;
+}
+async function buildCancelOrderTx(client, params) {
+    const tx = (0, common_ts_1.newTx)(params);
+    await (0, common_ts_1.wrapRequestAndExecute)(client, tx, params, params.collateralTicker ?? "USDCUSD", params, () => (0, order_ts_1.cancelOrderRequest)(client, tx, params));
+    return tx;
+}
+async function buildUpdateOrderTx(client, params) {
+    const tx = (0, common_ts_1.newTx)(params);
+    await (0, common_ts_1.wrapRequestAndExecute)(client, tx, params, params.collateralTicker ?? "USDCUSD", params, () => (0, order_ts_1.updateOrderRequest)(client, tx, params));
+    return tx;
+}
+async function buildCancelPreOrderTx(client, params) {
+    const tx = (0, common_ts_1.newTx)(params);
+    await (0, common_ts_1.wrapRequestAndExecute)(client, tx, params, params.collateralTicker ?? "USDCUSD", params, () => (0, order_ts_1.cancelPreOrderRequest)(client, tx, params));
+    return tx;
+}
+async function buildAddPreOrderTx(client, params) {
+    const tx = (0, common_ts_1.newTx)(params);
+    await (0, common_ts_1.wrapRequestAndExecute)(client, tx, params, params.collateralTicker ?? "USDCUSD", params, () => (0, order_ts_1.addPreOrderRequest)(client, tx, params));
+    return tx;
+}

package/dist/cjs/src/perp/tx-builders/wlp.d.ts

@@ -0,0 +1,90 @@
+/**
+ * High-level WLP composers: mint, mint+stake, unstake+request-redeem, and
+ * cancel-redeem+re-stake. The staking-coupled variants keep the product
+ * invariant that user-held WLP is always staked.
+ */
+import type { Transaction } from "@mysten/sui/transactions";
+import type { PerpClient } from "../client.ts";
+import { type CancelRedeemWlpParams, type MintWlpParams, type RequestRedeemWlpParams } from "../user/wlp.ts";
+import { type CommonBuildOpts } from "./common.ts";
+export interface BuildMintWlpParams extends MintWlpParams, CommonBuildOpts {
+    /** Oracle ticker for the deposited token (must be a registered pool token). */
+    depositTicker: string;
+}
+/**
+ * Mints WLP from a deposit asset already in the wxa account's stored
+ * balance. Refreshes every pool-token oracle + bumps each pool token's
+ * `last_price_refresh_timestamp` so `assert_prices_fresh` inside
+ * `mint_wlp` passes.
+ *
+ * Does NOT use the pyth_sponsor flow — `mint_wlp` produces no
+ * `TradingRequest`, so there's nothing for the sponsor to attach its
+ * witness to. Pyth update fees come from `tx.gas`.
+ */
+export declare function buildMintWlpTx(client: PerpClient, params: BuildMintWlpParams): Promise<Transaction>;
+export interface BuildMintAndStakeWlpParams extends BuildMintWlpParams {
+    /**
+     * Staking pool alias (key into `waterx_staking.pools`). Defaults to `"WLP"`.
+     */
+    stakeAlias?: string;
+    /**
+     * Rewarder coin types to settle on the stake deposit. Order must match the
+     * pool's on-chain `rewarder_ids`. Defaults to every rewarder configured for
+     * the stake pool in `waterx_staking.rewarders[stakeAlias]`.
+     */
+    rewarderTypes?: string[];
+}
+/**
+ * Mints WLP and immediately stakes the minted amount into the WLP staking pool
+ * in the same PTB. The mint's `lp_amount` return is piped directly into the
+ * `stake` call so no precision loss / dust can occur.
+ *
+ * Use this instead of `buildMintWlpTx` when the product flow is "deposit USD
+ * and earn rewards" — un-staked WLP sitting in the wxa account's `Balance<WLP>`
+ * slot earns nothing.
+ */
+export declare function buildMintAndStakeWlpTx(client: PerpClient, params: BuildMintAndStakeWlpParams): Promise<Transaction>;
+export interface BuildUnstakeAndRequestRedeemWlpParams extends Omit<RequestRedeemWlpParams, "lpAmount">, CommonBuildOpts {
+    /** Amount of staked WLP to unstake and enqueue for redemption. */
+    withdrawalAmount: bigint | number;
+    /** Staking pool alias. Defaults to `"WLP"`. */
+    stakeAlias?: string;
+    /**
+     * Rewarder coin types to settle on unstake. Defaults to every rewarder
+     * configured for the stake pool in `waterx_staking.rewarders[stakeAlias]`.
+     */
+    rewarderTypes?: string[];
+}
+/**
+ * Unstakes WLP from the staking pool and immediately enqueues a redeem request
+ * in the same PTB. Mirror of `buildMintAndStakeWlpTx` for withdrawals.
+ *
+ * Refreshes every WLP pool-token oracle by default — `request_redeem` runs
+ * `assert_prices_fresh` internally, so a stale oracle would abort the PTB.
+ * Pass `skipOraclePriceRefresh: true` only when the caller is composing this
+ * into a larger PTB that already pre-pumps prices.
+ */
+export declare function buildUnstakeAndRequestRedeemWlpTx(client: PerpClient, params: BuildUnstakeAndRequestRedeemWlpParams): Promise<Transaction>;
+export interface BuildCancelRedeemAndStakeWlpParams extends CancelRedeemWlpParams, CommonBuildOpts {
+    accountId: string;
+    /**
+     * WLP amount (base units) that was originally enqueued by `request_redeem`
+     * and is being returned to the wxa account by `cancel_redeem` — gets
+     * re-staked into the WLP staking pool in the same PTB.
+     */
+    stakeAmount: bigint | number;
+    /** Staking pool alias. Defaults to `"WLP"`. */
+    stakeAlias?: string;
+    /**
+     * Rewarder coin types to settle on stake. Defaults to every rewarder
+     * configured for the stake pool in `waterx_staking.rewarders[stakeAlias]`.
+     */
+    rewarderTypes?: string[];
+}
+/**
+ * Cancels a pending WLP redeem request and re-stakes the returned WLP in the
+ * same PTB. Third partner of `buildMintAndStakeWlpTx` /
+ * `buildUnstakeAndRequestRedeemWlpTx`; together they keep the product
+ * invariant that user-held WLP is always staked.
+ */
+export declare function buildCancelRedeemAndStakeWlpTx(client: PerpClient, params: BuildCancelRedeemAndStakeWlpParams): Transaction;

package/dist/cjs/src/perp/tx-builders/wlp.js

@@ -0,0 +1,126 @@
+"use strict";
+/**
+ * High-level WLP composers: mint, mint+stake, unstake+request-redeem, and
+ * cancel-redeem+re-stake. The staking-coupled variants keep the product
+ * invariant that user-held WLP is always staked.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildMintWlpTx = buildMintWlpTx;
+exports.buildMintAndStakeWlpTx = buildMintAndStakeWlpTx;
+exports.buildUnstakeAndRequestRedeemWlpTx = buildUnstakeAndRequestRedeemWlpTx;
+exports.buildCancelRedeemAndStakeWlpTx = buildCancelRedeemAndStakeWlpTx;
+const staking_ts_1 = require("../user/staking.js");
+const wlp_ts_1 = require("../user/wlp.js");
+const common_ts_1 = require("./common.js");
+/**
+ * Mints WLP from a deposit asset already in the wxa account's stored
+ * balance. Refreshes every pool-token oracle + bumps each pool token's
+ * `last_price_refresh_timestamp` so `assert_prices_fresh` inside
+ * `mint_wlp` passes.
+ *
+ * Does NOT use the pyth_sponsor flow — `mint_wlp` produces no
+ * `TradingRequest`, so there's nothing for the sponsor to attach its
+ * witness to. Pyth update fees come from `tx.gas`.
+ */
+async function buildMintWlpTx(client, params) {
+    const tx = (0, common_ts_1.newTx)(params);
+    await (0, common_ts_1.maybeConsolidate)(client, tx, params.accountId, params);
+    if (!params.skipOraclePriceRefresh) {
+        await (0, common_ts_1.refreshWlpPoolOracles)(tx, client, [params.depositTicker], {
+            cache: params.pythCache,
+            lpType: params.lpType,
+        });
+    }
+    (0, wlp_ts_1.mintWlp)(client, tx, params);
+    return tx;
+}
+/**
+ * Mints WLP and immediately stakes the minted amount into the WLP staking pool
+ * in the same PTB. The mint's `lp_amount` return is piped directly into the
+ * `stake` call so no precision loss / dust can occur.
+ *
+ * Use this instead of `buildMintWlpTx` when the product flow is "deposit USD
+ * and earn rewards" — un-staked WLP sitting in the wxa account's `Balance<WLP>`
+ * slot earns nothing.
+ */
+async function buildMintAndStakeWlpTx(client, params) {
+    const tx = (0, common_ts_1.newTx)(params);
+    await (0, common_ts_1.maybeConsolidate)(client, tx, params.accountId, params);
+    if (!params.skipOraclePriceRefresh) {
+        await (0, common_ts_1.refreshWlpPoolOracles)(tx, client, [params.depositTicker], {
+            cache: params.pythCache,
+            lpType: params.lpType,
+        });
+    }
+    const stakeAlias = params.stakeAlias ?? "WLP";
+    const lpAmount = (0, wlp_ts_1.mintWlp)(client, tx, params);
+    (0, staking_ts_1.stake)(client, tx, {
+        accountId: params.accountId,
+        stakeAlias,
+        stakeType: params.lpType ?? client.wlpType(),
+        stakeAmount: lpAmount,
+        rewarderTypes: params.rewarderTypes ?? client.getRewarderTypes(stakeAlias),
+        bucketAccount: params.bucketAccount,
+    });
+    return tx;
+}
+/**
+ * Unstakes WLP from the staking pool and immediately enqueues a redeem request
+ * in the same PTB. Mirror of `buildMintAndStakeWlpTx` for withdrawals.
+ *
+ * Refreshes every WLP pool-token oracle by default — `request_redeem` runs
+ * `assert_prices_fresh` internally, so a stale oracle would abort the PTB.
+ * Pass `skipOraclePriceRefresh: true` only when the caller is composing this
+ * into a larger PTB that already pre-pumps prices.
+ */
+async function buildUnstakeAndRequestRedeemWlpTx(client, params) {
+    const tx = (0, common_ts_1.newTx)(params);
+    const stakeAlias = params.stakeAlias ?? "WLP";
+    await (0, common_ts_1.maybeConsolidate)(client, tx, params.accountId, params);
+    if (!params.skipOraclePriceRefresh) {
+        await (0, common_ts_1.refreshWlpPoolOracles)(tx, client, [], {
+            cache: params.pythCache,
+            lpType: params.lpType,
+        });
+    }
+    (0, staking_ts_1.unstake)(client, tx, {
+        accountId: params.accountId,
+        stakeAlias,
+        stakeType: params.lpType ?? client.wlpType(),
+        withdrawalAmount: params.withdrawalAmount,
+        rewarderTypes: params.rewarderTypes ?? client.getRewarderTypes(stakeAlias),
+        bucketAccount: params.bucketAccount,
+    });
+    (0, wlp_ts_1.requestRedeemWlp)(client, tx, {
+        accountId: params.accountId,
+        redeemTokenType: params.redeemTokenType,
+        lpAmount: params.withdrawalAmount,
+        lpType: params.lpType,
+        bucketAccount: params.bucketAccount,
+    });
+    return tx;
+}
+/**
+ * Cancels a pending WLP redeem request and re-stakes the returned WLP in the
+ * same PTB. Third partner of `buildMintAndStakeWlpTx` /
+ * `buildUnstakeAndRequestRedeemWlpTx`; together they keep the product
+ * invariant that user-held WLP is always staked.
+ */
+function buildCancelRedeemAndStakeWlpTx(client, params) {
+    const tx = (0, common_ts_1.newTx)(params);
+    const stakeAlias = params.stakeAlias ?? "WLP";
+    (0, wlp_ts_1.cancelRedeemWlp)(client, tx, {
+        requestId: params.requestId,
+        lpType: params.lpType,
+        bucketAccount: params.bucketAccount,
+    });
+    (0, staking_ts_1.stake)(client, tx, {
+        accountId: params.accountId,
+        stakeAlias,
+        stakeType: params.lpType ?? client.wlpType(),
+        stakeAmount: params.stakeAmount,
+        rewarderTypes: params.rewarderTypes ?? client.getRewarderTypes(stakeAlias),
+        bucketAccount: params.bucketAccount,
+    });
+    return tx;
+}

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

@@ -0,0 +1,23 @@
+/**
+ * High-level perp transaction builders — barrel.
+ *
+ * Each `build*Tx` composer creates (or appends to) a `Transaction`, refreshes
+ * the on-chain `Oracle` via Pyth, optionally pre-sweeps parked balances
+ * (`consolidateToUsd`), wires the `pyth_sponsor_rule` flow when enabled, and
+ * calls the matching `*_request` + `execute`. Implementations are split by
+ * domain under `tx-builders/`:
+ *
+ *   common.ts       CommonBuildOpts + request/execute envelope + oracle refresh
+ *   consolidate.ts  parked-balance → wxUSD pre-sweep (appendConsolidate*)
+ *   trading.ts      position lifecycle + collateral + order lifecycle
+ *   wlp.ts          mint / mint+stake / unstake+redeem / cancel-redeem+restake
+ *   rewards.ts      claim staking rewards to the wxa account
+ *   credit.ts       cross-chain credit / bridge (redeem VAA, withdraw, drain)
+ */
+export type { CommonBuildOpts } from "./tx-builders/common.ts";
+export * from "../account/funding/consolidate.ts";
+export * from "./tx-builders/trading.ts";
+export * from "./tx-builders/wlp.ts";
+export * from "./tx-builders/rewards.ts";
+export * from "./tx-builders/credit.ts";
+export { openPythSponsorFund, PythCache, refreshOraclePrices, reimbursePythSponsor, updatePythPrices, } from "../oracle/index.ts";