four-flap-meme-sdk 1.5.26 → 1.5.27

package/dist/index.d.ts

@@ -53,4 +53,4 @@ export { submitDirectToRpc, submitDirectToRpcSequential, // ✅ 新增：顺序
 submitDirectToRpcParallel, type DirectSubmitConfig, type DirectSubmitResult, type DirectTxResult } from './contracts/tm-bundle-merkle/submit.js';
 export { directV2BatchBuy, directV2BatchSell, directV3BatchBuy, directV3BatchSell, getRouterAddress, DIRECT_ROUTERS, type DirectV2BuyParams, type DirectV2SellParams, type DirectV3BuyParams, type DirectV3SellParams, type DirectRouterResult, type DirectRouterSignConfig, type DexKey, type RouterVersion, } from './dex/index.js';
 export * as XLayer from './xlayer/index.js';
-export { bundleBuy as xlayerBundleBuy, bundleSell as xlayerBundleSell, bundleBuySell as xlayerBundleBuySell, createBundleExecutor as xlayerCreateBundleExecutor, BundleExecutor as XLayerBundleExecutor, makeVolume as xlayerMakeVolume, singleRoundVolume as xlayerSingleRoundVolume, createVolumeExecutor as xlayerCreateVolumeExecutor, VolumeExecutor as XLayerVolumeExecutor, createDexExecutor as xlayerCreateDexExecutor, createDexQuery as xlayerCreateDexQuery, quoteOkbToToken as xlayerQuoteOkbToToken, quoteTokenToOkb as xlayerQuoteTokenToOkb, DexExecutor as XLayerDexExecutor, DexQuery as XLayerDexQuery, createAAAccountManager as xlayerCreateAAAccountManager, predictSender as xlayerPredictSender, createWallet as xlayerCreateWallet, AAAccountManager as XLayerAAAccountManager, generateAAWallets as xlayerGenerateAAWallets, generateAAWalletsFromMnemonic as xlayerGenerateAAWalletsFromMnemonic, predictSendersFromPrivateKeys as xlayerPredictSendersFromPrivateKeys, createBundlerClient as xlayerCreateBundlerClient, BundlerClient as XLayerBundlerClient, createPortalQuery as xlayerCreatePortalQuery, PortalQuery as XLayerPortalQuery, encodeBuyCall as xlayerEncodeBuyCall, encodeSellCall as xlayerEncodeSellCall, encodeApproveCall as xlayerEncodeApproveCall, parseOkb as xlayerParseOkb, formatOkb as xlayerFormatOkb, XLAYER_CHAIN_ID, FLAP_PORTAL as XLAYER_FLAP_PORTAL, ENTRYPOINT_V06 as XLAYER_ENTRYPOINT, SIMPLE_ACCOUNT_FACTORY as XLAYER_FACTORY, PARTICLE_BUNDLER_URL as XLAYER_BUNDLER_URL, WOKB as XLAYER_WOKB, POTATOSWAP_V2_ROUTER as XLAYER_POTATOSWAP_ROUTER, type XLayerConfig, type BundleBuyParams as XLayerBundleBuyParams, type BundleSellParams as XLayerBundleSellParams, type BundleBuySellParams as XLayerBundleBuySellParams, type VolumeParams as XLayerVolumeParams, type BundleBuyResult as XLayerBundleBuyResult, type BundleSellResult as XLayerBundleSellResult, type BundleBuySellResult as XLayerBundleBuySellResult, type VolumeResult as XLayerVolumeResult, type HandleOpsResult as XLayerHandleOpsResult, type AAAccount as XLayerAAAccount, type UserOperation as XLayerUserOperation, type GeneratedAAWallet as XLayerGeneratedAAWallet, type GenerateAAWalletsParams as XLayerGenerateAAWalletsParams, type GenerateAAWalletsResult as XLayerGenerateAAWalletsResult, } from './xlayer/index.js';
+export { bundleBuy as xlayerBundleBuy, bundleSell as xlayerBundleSell, bundleBuySell as xlayerBundleBuySell, bundleSwap as xlayerBundleSwap, bundleSwapSign as xlayerBundleSwapSign, bundleBatchSwap as xlayerBundleBatchSwap, bundleBatchSwapSign as xlayerBundleBatchSwapSign, createBundleExecutor as xlayerCreateBundleExecutor, BundleExecutor as XLayerBundleExecutor, makeVolume as xlayerMakeVolume, singleRoundVolume as xlayerSingleRoundVolume, createVolumeExecutor as xlayerCreateVolumeExecutor, VolumeExecutor as XLayerVolumeExecutor, createDexExecutor as xlayerCreateDexExecutor, createDexQuery as xlayerCreateDexQuery, quoteOkbToToken as xlayerQuoteOkbToToken, quoteTokenToOkb as xlayerQuoteTokenToOkb, DexExecutor as XLayerDexExecutor, DexQuery as XLayerDexQuery, createAAAccountManager as xlayerCreateAAAccountManager, predictSender as xlayerPredictSender, createWallet as xlayerCreateWallet, AAAccountManager as XLayerAAAccountManager, generateAAWallets as xlayerGenerateAAWallets, generateAAWalletsFromMnemonic as xlayerGenerateAAWalletsFromMnemonic, predictSendersFromPrivateKeys as xlayerPredictSendersFromPrivateKeys, createBundlerClient as xlayerCreateBundlerClient, BundlerClient as XLayerBundlerClient, createPortalQuery as xlayerCreatePortalQuery, PortalQuery as XLayerPortalQuery, encodeBuyCall as xlayerEncodeBuyCall, encodeSellCall as xlayerEncodeSellCall, encodeApproveCall as xlayerEncodeApproveCall, parseOkb as xlayerParseOkb, formatOkb as xlayerFormatOkb, XLAYER_CHAIN_ID, FLAP_PORTAL as XLAYER_FLAP_PORTAL, ENTRYPOINT_V06 as XLAYER_ENTRYPOINT, SIMPLE_ACCOUNT_FACTORY as XLAYER_FACTORY, PARTICLE_BUNDLER_URL as XLAYER_BUNDLER_URL, WOKB as XLAYER_WOKB, POTATOSWAP_V2_ROUTER as XLAYER_POTATOSWAP_ROUTER, type XLayerConfig, type BundleBuyParams as XLayerBundleBuyParams, type BundleSellParams as XLayerBundleSellParams, type BundleBuySellParams as XLayerBundleBuySellParams, type BundleSwapParams as XLayerBundleSwapParams, type BundleSwapSignParams as XLayerBundleSwapSignParams, type BundleBatchSwapParams as XLayerBundleBatchSwapParams, type BundleBatchSwapSignParams as XLayerBundleBatchSwapSignParams, type VolumeParams as XLayerVolumeParams, type BundleBuyResult as XLayerBundleBuyResult, type BundleSellResult as XLayerBundleSellResult, type BundleBuySellResult as XLayerBundleBuySellResult, type BundleSwapResult as XLayerBundleSwapResult, type BundleSwapSignResult as XLayerBundleSwapSignResult, type BundleBatchSwapResult as XLayerBundleBatchSwapResult, type BundleBatchSwapSignResult as XLayerBundleBatchSwapSignResult, type VolumeResult as XLayerVolumeResult, type HandleOpsResult as XLayerHandleOpsResult, type AAAccount as XLayerAAAccount, type UserOperation as XLayerUserOperation, type GeneratedAAWallet as XLayerGeneratedAAWallet, type GenerateAAWalletsParams as XLayerGenerateAAWalletsParams, type GenerateAAWalletsResult as XLayerGenerateAAWalletsResult, } from './xlayer/index.js';

package/dist/index.js

@@ -102,7 +102,7 @@ DIRECT_ROUTERS, } from './dex/index.js';
 export * as XLayer from './xlayer/index.js';
 export { 
 // 捆绑交易
-bundleBuy as xlayerBundleBuy, bundleSell as xlayerBundleSell, bundleBuySell as xlayerBundleBuySell, createBundleExecutor as xlayerCreateBundleExecutor, BundleExecutor as XLayerBundleExecutor, 
+bundleBuy as xlayerBundleBuy, bundleSell as xlayerBundleSell, bundleBuySell as xlayerBundleBuySell, bundleSwap as xlayerBundleSwap, bundleSwapSign as xlayerBundleSwapSign, bundleBatchSwap as xlayerBundleBatchSwap, bundleBatchSwapSign as xlayerBundleBatchSwapSign, createBundleExecutor as xlayerCreateBundleExecutor, BundleExecutor as XLayerBundleExecutor, 
 // 刷量
 makeVolume as xlayerMakeVolume, singleRoundVolume as xlayerSingleRoundVolume, createVolumeExecutor as xlayerCreateVolumeExecutor, VolumeExecutor as XLayerVolumeExecutor, 
 // DEX 交易

package/dist/xlayer/bundle.d.ts

@@ -7,7 +7,7 @@
  * - 买卖一体化：买入 -> 授权 -> 卖出 -> 归集
  * - OKB 归集：将 sender 的 OKB 转回 owner
  */
-import type { XLayerConfig, BundleBuyParams, BundleBuyResult, BundleSellParams, BundleSellResult, BundleBuySellParams, BundleBuySellResult } from './types.js';
+import type { XLayerConfig, BundleBuyParams, BundleBuyResult, BundleSellParams, BundleSellResult, BundleBuySellParams, BundleBuySellResult, BundleSwapParams, BundleSwapResult, BundleSwapSignParams, BundleSwapSignResult, BundleBatchSwapParams, BundleBatchSwapResult, BundleBatchSwapSignParams, BundleBatchSwapSignResult } from './types.js';
 import { AAAccountManager } from './aa-account.js';
 import { PortalQuery } from './portal-ops.js';
 /**
@@ -36,6 +36,21 @@ export declare class BundleExecutor {
      * 执行 handleOps 并解析结果
      */
     private runHandleOps;
+    /**
+     * 构造并签名 handleOps 交易（raw signed tx）
+     * - 用于“像 BSC 一样：前端/后端提交 raw tx bundle”的场景
+     */
+    private signHandleOpsTx;
+    private getErc20Decimals;
+    /**
+     * 构建买入 UserOp（已知 sender/nonce/initCode 的版本）
+     */
+    private buildBuyUserOpWithState;
+    /**
+     * 构建换手所需的 UserOps（approve? + sell + buy），并返回元数据
+     */
+    private buildSwapOps;
+    private buildBatchSwapOps;
     /**
      * 构建买入 UserOp
      */
@@ -79,6 +94,24 @@ export declare class BundleExecutor {
      * 完整流程：买入 -> 授权 -> 卖出 -> 归集
      */
     bundleBuySell(params: BundleBuySellParams): Promise<BundleBuySellResult>;
+    /**
+     * ✅ 捆绑换手（AA）：卖方卖出 → 买方买入，同一笔 handleOps 原子执行
+     */
+    bundleSwap(params: BundleSwapParams): Promise<BundleSwapResult>;
+    /**
+     * ✅ 捆绑换手（AA，仅签名）：返回 raw signed tx 列表（像 BSC 捆绑一样交给后端提交）
+     * - signedTransactions[0] = handleOps tx（payer 签名）
+     * - 如果传入 routeAddress，则 signedTransactions[1] = tailTx（nonce+1）
+     */
+    bundleSwapSign(params: BundleSwapSignParams): Promise<BundleSwapSignResult>;
+    /**
+     * ✅ 批量捆绑换手（AA）：一卖多买，同一笔 handleOps 原子执行
+     */
+    bundleBatchSwap(params: BundleBatchSwapParams): Promise<BundleBatchSwapResult>;
+    /**
+     * ✅ 批量捆绑换手（AA，仅签名）
+     */
+    bundleBatchSwapSign(params: BundleBatchSwapSignParams): Promise<BundleBatchSwapSignResult>;
 }
 /**
  * 创建捆绑交易执行器
@@ -96,3 +129,19 @@ export declare function bundleSell(params: BundleSellParams): Promise<BundleSell
  * 快速捆绑买卖
  */
 export declare function bundleBuySell(params: BundleBuySellParams): Promise<BundleBuySellResult>;
+/**
+ * 快速捆绑换手（链上执行）
+ */
+export declare function bundleSwap(params: BundleSwapParams): Promise<BundleSwapResult>;
+/**
+ * 快速捆绑换手（仅签名，返回 raw signed tx）
+ */
+export declare function bundleSwapSign(params: BundleSwapSignParams): Promise<BundleSwapSignResult>;
+/**
+ * 快速批量捆绑换手（链上执行）
+ */
+export declare function bundleBatchSwap(params: BundleBatchSwapParams): Promise<BundleBatchSwapResult>;
+/**
+ * 快速批量捆绑换手（仅签名）
+ */
+export declare function bundleBatchSwapSign(params: BundleBatchSwapSignParams): Promise<BundleBatchSwapSignResult>;

package/dist/xlayer/bundle.js

@@ -7,7 +7,7 @@
  * - 买卖一体化：买入 -> 授权 -> 卖出 -> 归集
  * - OKB 归集：将 sender 的 OKB 转回 owner
  */
-import { Wallet, Interface, Contract } from 'ethers';
+import { Wallet, Interface, Contract, Transaction, ethers } from 'ethers';
 import { FLAP_PORTAL, ENTRYPOINT_ABI, DEFAULT_CALL_GAS_LIMIT_SELL, DEFAULT_WITHDRAW_RESERVE, } from './constants.js';
 import { AAAccountManager, encodeExecute } from './aa-account.js';
 import { encodeBuyCall, encodeSellCall, encodeApproveCall, encodeTransferCall, PortalQuery, parseOkb, formatOkb, } from './portal-ops.js';
@@ -153,6 +153,288 @@ export class BundleExecutor {
             userOpEvents,
         };
     }
+    /**
+     * 构造并签名 handleOps 交易（raw signed tx）
+     * - 用于“像 BSC 一样：前端/后端提交 raw tx bundle”的场景
+     */
+    async signHandleOpsTx(params) {
+        const provider = this.aaManager.getProvider();
+        const entryPointAddress = this.aaManager.getEntryPointAddress();
+        const epIface = new Interface(ENTRYPOINT_ABI);
+        const data = epIface.encodeFunctionData('handleOps', [params.ops, params.beneficiary]);
+        const feeData = await provider.getFeeData();
+        const gasPrice = params.gasPrice ?? feeData.gasPrice ?? 100000000n;
+        const nonce = params.nonce ?? await provider.getTransactionCount(params.payerWallet.address, 'pending');
+        let gasLimit = params.gasLimit;
+        if (!gasLimit) {
+            try {
+                const est = await provider.estimateGas({
+                    from: params.payerWallet.address,
+                    to: entryPointAddress,
+                    data,
+                    value: 0n,
+                });
+                gasLimit = BigInt(Math.ceil(Number(est) * 1.2));
+            }
+            catch {
+                // 兜底：handleOps 可能很大，使用相对保守的 gasLimit
+                gasLimit = 3500000n;
+            }
+        }
+        return await params.payerWallet.signTransaction({
+            to: entryPointAddress,
+            data,
+            value: 0n,
+            nonce,
+            gasLimit,
+            gasPrice,
+            chainId: this.config.chainId ?? 196,
+            type: 0,
+        });
+    }
+    async getErc20Decimals(tokenAddress) {
+        const provider = this.aaManager.getProvider();
+        const token = new Contract(tokenAddress, ['function decimals() view returns (uint8)'], provider);
+        try {
+            const d = await token.decimals();
+            const n = Number(d);
+            return Number.isFinite(n) ? n : 18;
+        }
+        catch {
+            return 18;
+        }
+    }
+    /**
+     * 构建买入 UserOp（已知 sender/nonce/initCode 的版本）
+     */
+    async buildBuyUserOpWithState(params) {
+        const swapData = encodeBuyCall(params.tokenAddress, params.buyAmountWei, 0n);
+        const callData = encodeExecute(this.portalAddress, params.buyAmountWei, swapData);
+        if (!params.signOnly) {
+            // 估算前确保 sender 有足够余额（用于模拟）；paymaster 场景会自动跳过
+            await this.aaManager.ensureSenderBalance(params.ownerWallet, params.sender, params.buyAmountWei + parseOkb('0.0003'), `${params.ownerName ?? 'owner'}/swap-buy-prefund-before-estimate`);
+        }
+        const gasPolicyRaw = this.config.gasPolicy ?? 'bundlerEstimate';
+        const gasPolicy = params.signOnly && gasPolicyRaw === 'bundlerEstimate' ? 'fixed' : gasPolicyRaw;
+        const { userOp, prefundWei } = gasPolicy === 'fixed'
+            ? await this.aaManager.buildUserOpWithFixedGas({
+                ownerWallet: params.ownerWallet,
+                sender: params.sender,
+                callData,
+                nonce: params.nonce,
+                initCode: params.initCode,
+                deployed: params.initCode === '0x',
+                fixedGas: {
+                    ...(this.config.fixedGas ?? {}),
+                    callGasLimit: this.config.fixedGas?.callGasLimit ?? DEFAULT_CALL_GAS_LIMIT_BUY,
+                },
+            })
+            : gasPolicy === 'localEstimate'
+                ? await this.aaManager.buildUserOpWithLocalEstimate({
+                    ownerWallet: params.ownerWallet,
+                    sender: params.sender,
+                    callData,
+                    nonce: params.nonce,
+                    initCode: params.initCode,
+                })
+                : await this.aaManager.buildUserOpWithBundlerEstimate({
+                    ownerWallet: params.ownerWallet,
+                    sender: params.sender,
+                    callData,
+                    nonce: params.nonce,
+                    initCode: params.initCode,
+                });
+        if (!params.signOnly) {
+            // 补足 prefund + 买入金额
+            await this.aaManager.ensureSenderBalance(params.ownerWallet, params.sender, params.buyAmountWei + prefundWei + parseOkb('0.0002'), `${params.ownerName ?? 'owner'}/swap-buy-fund`);
+        }
+        const signed = await this.aaManager.signUserOp(userOp, params.ownerWallet);
+        return { ...signed, prefundWei, ownerName: params.ownerName };
+    }
+    /**
+     * 构建换手所需的 UserOps（approve? + sell + buy），并返回元数据
+     */
+    async buildSwapOps(params, opts) {
+        const signOnly = opts?.signOnly ?? false;
+        const { tokenAddress, sellerPrivateKey, buyerPrivateKey, sellAmount, sellPercent = 100, buyAmountOkb, slippageBps = 100, } = params;
+        const provider = this.aaManager.getProvider();
+        const sellerOwner = new Wallet(sellerPrivateKey, provider);
+        const buyerOwner = new Wallet(buyerPrivateKey, provider);
+        const [sellerAi, buyerAi] = await this.aaManager.getMultipleAccountInfo([sellerOwner.address, buyerOwner.address]);
+        const sellerSender = sellerAi.sender;
+        const buyerSender = buyerAi.sender;
+        const nonceMap = new AANonceMap();
+        nonceMap.init(sellerSender, sellerAi.nonce);
+        nonceMap.init(buyerSender, buyerAi.nonce);
+        // 计算卖出数量
+        const decimals = await this.getErc20Decimals(tokenAddress);
+        const sellerTokenBal = await this.portalQuery.getTokenBalance(tokenAddress, sellerSender);
+        const sellAmountWei = (() => {
+            if (sellAmount && String(sellAmount).trim().length > 0) {
+                return ethers.parseUnits(String(sellAmount).trim(), decimals);
+            }
+            const pct = Math.max(0, Math.min(100, Math.floor(sellPercent)));
+            return (sellerTokenBal * BigInt(pct)) / 100n;
+        })();
+        if (sellAmountWei <= 0n) {
+            throw new Error('卖出数量为 0（请检查 sellAmount/sellPercent 或卖方余额）');
+        }
+        // 检查授权
+        const allowance = await this.portalQuery.getAllowance(tokenAddress, sellerSender, this.portalAddress);
+        const needApprove = allowance < sellAmountWei;
+        // 计算买入 OKB 数量（默认用 previewSell(sellAmount) * (1 - slippage)）
+        const buyAmountWei = buyAmountOkb && String(buyAmountOkb).trim().length > 0
+            ? parseOkb(String(buyAmountOkb).trim())
+            : (() => {
+                const bps = Math.max(0, Math.min(10000, Math.floor(slippageBps)));
+                return 0n; // placeholder, filled below
+            })();
+        let finalBuyAmountWei = buyAmountWei;
+        if (!(buyAmountOkb && String(buyAmountOkb).trim().length > 0)) {
+            const quoted = await this.portalQuery.previewSell(tokenAddress, sellAmountWei);
+            const bps = Math.max(0, Math.min(10000, Math.floor(slippageBps)));
+            finalBuyAmountWei = (quoted * BigInt(10000 - bps)) / 10000n;
+        }
+        if (finalBuyAmountWei <= 0n) {
+            throw new Error('买入 OKB 数量为 0（请检查 buyAmountOkb 或卖出预览输出）');
+        }
+        // initCode 处理：同一个 sender 的第一笔 op 才带 initCode
+        const sellerInitCode0 = sellerAi.deployed ? '0x' : this.aaManager.generateInitCode(sellerOwner.address);
+        const buyerInitCode0 = buyerAi.deployed ? '0x' : this.aaManager.generateInitCode(buyerOwner.address);
+        let sellerInitCodeForNext = sellerInitCode0;
+        let buyerInitCodeForNext = buyerInitCode0;
+        const outOps = [];
+        // 1) approve（可选）
+        if (needApprove) {
+            const approveNonce = nonceMap.next(sellerSender);
+            const signedApprove = await this.buildApproveUserOp(sellerOwner, tokenAddress, this.portalAddress, sellerSender, approveNonce, sellerInitCodeForNext, 'seller', signOnly);
+            outOps.push(signedApprove.userOp);
+            sellerInitCodeForNext = '0x';
+        }
+        // 2) sell
+        const sellNonce = nonceMap.next(sellerSender);
+        const signedSell = await this.buildSellUserOp(sellerOwner, tokenAddress, sellAmountWei, sellerSender, sellNonce, sellerInitCodeForNext, needApprove, 'seller', signOnly);
+        outOps.push(signedSell.userOp);
+        sellerInitCodeForNext = '0x';
+        // 3) buy（买方）
+        const buyNonce = nonceMap.next(buyerSender);
+        const signedBuy = await this.buildBuyUserOpWithState({
+            ownerWallet: buyerOwner,
+            sender: buyerSender,
+            nonce: buyNonce,
+            initCode: buyerInitCodeForNext,
+            tokenAddress,
+            buyAmountWei: finalBuyAmountWei,
+            ownerName: 'buyer',
+            signOnly,
+        });
+        outOps.push(signedBuy.userOp);
+        buyerInitCodeForNext = '0x';
+        return {
+            ops: outOps,
+            metadata: {
+                sellerOwner: sellerOwner.address,
+                sellerSender,
+                buyerOwner: buyerOwner.address,
+                buyerSender,
+                sellAmountWei: sellAmountWei.toString(),
+                buyAmountWei: finalBuyAmountWei.toString(),
+                hasApprove: needApprove,
+            },
+        };
+    }
+    async buildBatchSwapOps(params, opts) {
+        const signOnly = opts?.signOnly ?? false;
+        const { tokenAddress, sellerPrivateKey, buyerPrivateKeys, buyAmountsOkb, sellAmount, sellPercent = 100, } = params;
+        if (buyerPrivateKeys.length !== buyAmountsOkb.length) {
+            throw new Error('buyerPrivateKeys 和 buyAmountsOkb 长度必须一致');
+        }
+        if (buyerPrivateKeys.length === 0) {
+            throw new Error('至少需要 1 个 buyerPrivateKey');
+        }
+        const provider = this.aaManager.getProvider();
+        const sellerOwner = new Wallet(sellerPrivateKey, provider);
+        const buyerOwners = buyerPrivateKeys.map((pk) => new Wallet(pk, provider));
+        const accountInfos = await this.aaManager.getMultipleAccountInfo([
+            sellerOwner.address,
+            ...buyerOwners.map((w) => w.address),
+        ]);
+        const sellerAi = accountInfos[0];
+        const buyerAis = accountInfos.slice(1);
+        const sellerSender = sellerAi.sender;
+        const buyerSenders = buyerAis.map((ai) => ai.sender);
+        const nonceMap = new AANonceMap();
+        nonceMap.init(sellerSender, sellerAi.nonce);
+        for (const ai of buyerAis)
+            nonceMap.init(ai.sender, ai.nonce);
+        // 计算卖出数量
+        const decimals = await this.getErc20Decimals(tokenAddress);
+        const sellerTokenBal = await this.portalQuery.getTokenBalance(tokenAddress, sellerSender);
+        const sellAmountWei = (() => {
+            if (sellAmount && String(sellAmount).trim().length > 0) {
+                return ethers.parseUnits(String(sellAmount).trim(), decimals);
+            }
+            const pct = Math.max(0, Math.min(100, Math.floor(sellPercent)));
+            return (sellerTokenBal * BigInt(pct)) / 100n;
+        })();
+        if (sellAmountWei <= 0n) {
+            throw new Error('卖出数量为 0（请检查 sellAmount/sellPercent 或卖方余额）');
+        }
+        // 检查授权
+        const allowance = await this.portalQuery.getAllowance(tokenAddress, sellerSender, this.portalAddress);
+        const needApprove = allowance < sellAmountWei;
+        // initCode：同一个 sender 的第一笔 op 才带 initCode
+        let sellerInitCodeForNext = sellerAi.deployed ? '0x' : this.aaManager.generateInitCode(sellerOwner.address);
+        const buyerInitCodes = buyerAis.map((ai, idx) => ai.deployed ? '0x' : this.aaManager.generateInitCode(buyerOwners[idx].address));
+        const outOps = [];
+        // 1) approve（可选）
+        if (needApprove) {
+            const approveNonce = nonceMap.next(sellerSender);
+            const signedApprove = await this.buildApproveUserOp(sellerOwner, tokenAddress, this.portalAddress, sellerSender, approveNonce, sellerInitCodeForNext, 'seller', signOnly);
+            outOps.push(signedApprove.userOp);
+            sellerInitCodeForNext = '0x';
+        }
+        // 2) sell（一次）
+        const sellNonce = nonceMap.next(sellerSender);
+        const signedSell = await this.buildSellUserOp(sellerOwner, tokenAddress, sellAmountWei, sellerSender, sellNonce, sellerInitCodeForNext, needApprove, 'seller', signOnly);
+        outOps.push(signedSell.userOp);
+        sellerInitCodeForNext = '0x';
+        // 3) buyers buy（多笔）
+        const buyAmountsWei = buyAmountsOkb.map((v) => parseOkb(String(v)));
+        const signedBuys = await mapWithConcurrency(buyerOwners, 4, async (w, i) => {
+            const sender = buyerSenders[i];
+            const initCode = buyerInitCodes[i];
+            const nonce = nonceMap.next(sender);
+            const amountWei = buyAmountsWei[i] ?? 0n;
+            if (amountWei <= 0n) {
+                throw new Error(`buyAmountsOkb[${i}] 无效（<=0）`);
+            }
+            return await this.buildBuyUserOpWithState({
+                ownerWallet: w,
+                sender,
+                nonce,
+                initCode,
+                tokenAddress,
+                buyAmountWei: amountWei,
+                ownerName: `buyer${i + 1}`,
+                signOnly,
+            });
+        });
+        for (const s of signedBuys)
+            outOps.push(s.userOp);
+        return {
+            ops: outOps,
+            metadata: {
+                sellerOwner: sellerOwner.address,
+                sellerSender,
+                buyerOwners: buyerOwners.map((w) => w.address),
+                buyerSenders,
+                sellAmountWei: sellAmountWei.toString(),
+                buyAmountsWei: buyAmountsWei.map((x) => x.toString()),
+                hasApprove: needApprove,
+            },
+        };
+    }
     /**
      * 构建买入 UserOp
      */
@@ -200,11 +482,14 @@ export class BundleExecutor {
     /**
      * 构建授权 UserOp
      */
-    async buildApproveUserOp(ownerWallet, tokenAddress, spender, sender, nonce, initCode, ownerName) {
+    async buildApproveUserOp(ownerWallet, tokenAddress, spender, sender, nonce, initCode, ownerName, signOnly = false) {
         const approveData = encodeApproveCall(spender);
         const callData = encodeExecute(tokenAddress, 0n, approveData);
-        await this.aaManager.ensureSenderBalance(ownerWallet, sender, parseOkb('0.0002'), `${ownerName ?? 'owner'}/approve-prefund`);
-        const gasPolicy = this.config.gasPolicy ?? 'bundlerEstimate';
+        if (!signOnly) {
+            await this.aaManager.ensureSenderBalance(ownerWallet, sender, parseOkb('0.0002'), `${ownerName ?? 'owner'}/approve-prefund`);
+        }
+        const gasPolicyRaw = this.config.gasPolicy ?? 'bundlerEstimate';
+        const gasPolicy = signOnly && gasPolicyRaw === 'bundlerEstimate' ? 'fixed' : gasPolicyRaw;
         const { userOp, prefundWei } = gasPolicy === 'fixed'
             ? await this.aaManager.buildUserOpWithFixedGas({
                 ownerWallet,
@@ -218,25 +503,38 @@ export class BundleExecutor {
                     callGasLimit: this.config.fixedGas?.callGasLimit ?? DEFAULT_CALL_GAS_LIMIT_APPROVE,
                 },
             })
-            : await this.aaManager.buildUserOpWithLocalEstimate({
-                ownerWallet,
-                sender,
-                callData,
-                nonce,
-                initCode,
-            });
-        await this.aaManager.ensureSenderBalance(ownerWallet, sender, prefundWei + parseOkb('0.00005'), `${ownerName ?? 'owner'}/approve-fund`);
+            : gasPolicy === 'localEstimate'
+                ? await this.aaManager.buildUserOpWithLocalEstimate({
+                    ownerWallet,
+                    sender,
+                    callData,
+                    nonce,
+                    initCode,
+                })
+                : await this.aaManager.buildUserOpWithBundlerEstimate({
+                    ownerWallet,
+                    sender,
+                    callData,
+                    nonce,
+                    initCode,
+                });
+        if (!signOnly) {
+            await this.aaManager.ensureSenderBalance(ownerWallet, sender, prefundWei + parseOkb('0.00005'), `${ownerName ?? 'owner'}/approve-fund`);
+        }
         const signed = await this.aaManager.signUserOp(userOp, ownerWallet);
         return { ...signed, prefundWei, ownerName };
     }
     /**
      * 构建卖出 UserOp
      */
-    async buildSellUserOp(ownerWallet, tokenAddress, sellAmount, sender, nonce, initCode, needApprove, ownerName) {
+    async buildSellUserOp(ownerWallet, tokenAddress, sellAmount, sender, nonce, initCode, needApprove, ownerName, signOnly = false) {
         const sellData = encodeSellCall(tokenAddress, sellAmount, 0n);
         const callData = encodeExecute(this.portalAddress, 0n, sellData);
-        await this.aaManager.ensureSenderBalance(ownerWallet, sender, parseOkb('0.0003'), `${ownerName ?? 'owner'}/sell-prefund`);
-        const gasPolicy = this.config.gasPolicy ?? 'bundlerEstimate';
+        if (!signOnly) {
+            await this.aaManager.ensureSenderBalance(ownerWallet, sender, parseOkb('0.0003'), `${ownerName ?? 'owner'}/sell-prefund`);
+        }
+        const gasPolicyRaw = this.config.gasPolicy ?? 'bundlerEstimate';
+        const gasPolicy = signOnly && gasPolicyRaw === 'bundlerEstimate' ? 'fixed' : gasPolicyRaw;
         // 如果需要 approve（还未执行），estimateGas 可能 revert；因此默认就用固定 callGasLimit
         const { userOp, prefundWei } = gasPolicy === 'fixed'
             ? await this.aaManager.buildUserOpWithFixedGas({
@@ -251,23 +549,33 @@ export class BundleExecutor {
                     callGasLimit: this.config.fixedGas?.callGasLimit ?? DEFAULT_CALL_GAS_LIMIT_SELL,
                 },
             })
-            : needApprove
-                ? await this.aaManager.buildUserOpWithLocalEstimate({
-                    ownerWallet,
-                    sender,
-                    callData,
-                    nonce,
-                    initCode,
-                    callGasLimit: DEFAULT_CALL_GAS_LIMIT_SELL,
-                })
-                : await this.aaManager.buildUserOpWithLocalEstimate({
+            : gasPolicy === 'localEstimate'
+                ? (needApprove
+                    ? await this.aaManager.buildUserOpWithLocalEstimate({
+                        ownerWallet,
+                        sender,
+                        callData,
+                        nonce,
+                        initCode,
+                        callGasLimit: DEFAULT_CALL_GAS_LIMIT_SELL,
+                    })
+                    : await this.aaManager.buildUserOpWithLocalEstimate({
+                        ownerWallet,
+                        sender,
+                        callData,
+                        nonce,
+                        initCode,
+                    }))
+                : await this.aaManager.buildUserOpWithBundlerEstimate({
                     ownerWallet,
                     sender,
                     callData,
                     nonce,
                     initCode,
                 });
-        await this.aaManager.ensureSenderBalance(ownerWallet, sender, prefundWei + parseOkb('0.00005'), `${ownerName ?? 'owner'}/sell-fund`);
+        if (!signOnly) {
+            await this.aaManager.ensureSenderBalance(ownerWallet, sender, prefundWei + parseOkb('0.00005'), `${ownerName ?? 'owner'}/sell-fund`);
+        }
         const signed = await this.aaManager.signUserOp(userOp, ownerWallet);
         return { ...signed, prefundWei, ownerName };
     }
@@ -300,8 +608,11 @@ export class BundleExecutor {
         }
         // 先估算 prefund（使用空调用）
         const tempCallData = encodeExecute(params.ownerWallet.address, 0n, '0x');
-        await this.aaManager.ensureSenderBalance(params.ownerWallet, params.sender, parseOkb('0.0002'), `${params.ownerName ?? 'owner'}/withdraw-prefund`);
-        const gasPolicy = this.config.gasPolicy ?? 'bundlerEstimate';
+        if (!params.signOnly) {
+            await this.aaManager.ensureSenderBalance(params.ownerWallet, params.sender, parseOkb('0.0002'), `${params.ownerName ?? 'owner'}/withdraw-prefund`);
+        }
+        const gasPolicyRaw = this.config.gasPolicy ?? 'bundlerEstimate';
+        const gasPolicy = params.signOnly && gasPolicyRaw === 'bundlerEstimate' ? 'fixed' : gasPolicyRaw;
         const { prefundWei } = gasPolicy === 'fixed'
             ? await this.aaManager.buildUserOpWithFixedGas({
                 ownerWallet: params.ownerWallet,
@@ -315,13 +626,21 @@ export class BundleExecutor {
                     callGasLimit: this.config.fixedGas?.callGasLimit ?? DEFAULT_CALL_GAS_LIMIT_WITHDRAW,
                 },
             })
-            : await this.aaManager.buildUserOpWithLocalEstimate({
-                ownerWallet: params.ownerWallet,
-                sender: params.sender,
-                callData: tempCallData,
-                nonce: params.nonce,
-                initCode: params.initCode,
-            });
+            : gasPolicy === 'localEstimate'
+                ? await this.aaManager.buildUserOpWithLocalEstimate({
+                    ownerWallet: params.ownerWallet,
+                    sender: params.sender,
+                    callData: tempCallData,
+                    nonce: params.nonce,
+                    initCode: params.initCode,
+                })
+                : await this.aaManager.buildUserOpWithBundlerEstimate({
+                    ownerWallet: params.ownerWallet,
+                    sender: params.sender,
+                    callData: tempCallData,
+                    nonce: params.nonce,
+                    initCode: params.initCode,
+                });
         // 计算可归集金额（用已知余额近似；fund 发生时余额会变大，属于可接受的保守近似）
         const withdrawAmount = senderBalance > prefundWei + params.reserveWei
             ? senderBalance - prefundWei - params.reserveWei
@@ -344,13 +663,21 @@ export class BundleExecutor {
                     callGasLimit: this.config.fixedGas?.callGasLimit ?? DEFAULT_CALL_GAS_LIMIT_WITHDRAW,
                 },
             })
-            : await this.aaManager.buildUserOpWithLocalEstimate({
-                ownerWallet: params.ownerWallet,
-                sender: params.sender,
-                callData,
-                nonce: params.nonce,
-                initCode: params.initCode,
-            });
+            : gasPolicy === 'localEstimate'
+                ? await this.aaManager.buildUserOpWithLocalEstimate({
+                    ownerWallet: params.ownerWallet,
+                    sender: params.sender,
+                    callData,
+                    nonce: params.nonce,
+                    initCode: params.initCode,
+                })
+                : await this.aaManager.buildUserOpWithBundlerEstimate({
+                    ownerWallet: params.ownerWallet,
+                    sender: params.sender,
+                    callData,
+                    nonce: params.nonce,
+                    initCode: params.initCode,
+                });
         console.log(`\n[${params.ownerName ?? 'owner'}] withdraw: ${formatOkb(withdrawAmount)} OKB`);
         const signed = await this.aaManager.signUserOp(userOp, params.ownerWallet);
         return { ...signed, prefundWei, ownerName: params.ownerName };
@@ -752,6 +1079,142 @@ export class BundleExecutor {
         const finalBalances = await this.portalQuery.getMultipleOkbBalances(senders);
         return { buyResult, sellResult, withdrawResult, finalBalances };
     }
+    /**
+     * ✅ 捆绑换手（AA）：卖方卖出 → 买方买入，同一笔 handleOps 原子执行
+     */
+    async bundleSwap(params) {
+        const provider = this.aaManager.getProvider();
+        const payerWallet = new Wallet(params.sellerPrivateKey, provider);
+        const beneficiary = payerWallet.address;
+        const { ops, metadata } = await this.buildSwapOps(params, { signOnly: false });
+        const swapResult = await this.runHandleOps('swapBundle', ops, payerWallet, beneficiary);
+        if (!swapResult)
+            throw new Error('换手交易失败');
+        return { swapResult, metadata };
+    }
+    /**
+     * ✅ 捆绑换手（AA，仅签名）：返回 raw signed tx 列表（像 BSC 捆绑一样交给后端提交）
+     * - signedTransactions[0] = handleOps tx（payer 签名）
+     * - 如果传入 routeAddress，则 signedTransactions[1] = tailTx（nonce+1）
+     */
+    async bundleSwapSign(params) {
+        const provider = this.aaManager.getProvider();
+        const payerPk = (params.payerPrivateKey ?? params.sellerPrivateKey);
+        const payerWallet = new Wallet(payerPk, provider);
+        const beneficiary = params.beneficiary ?? payerWallet.address;
+        const { ops, metadata } = await this.buildSwapOps(params, { signOnly: true });
+        // 先签 handleOps
+        const signedHandleOpsTx = await this.signHandleOpsTx({
+            ops,
+            payerWallet,
+            beneficiary,
+            nonce: params.payerStartNonce,
+            gasLimit: params.handleOpsGasLimit,
+        });
+        const signedTxs = [signedHandleOpsTx];
+        // 可选：追加 route 尾交易（nonce+1）
+        if (params.routeAddress) {
+            const tx = Transaction.from(signedHandleOpsTx);
+            const nonce = Number(tx.nonce);
+            const chainId = Number(tx.chainId || 0);
+            if (!Number.isFinite(nonce) || nonce < 0)
+                throw new Error('解析 handleOps nonce 失败');
+            if (!Number.isFinite(chainId) || chainId <= 0)
+                throw new Error('解析 handleOps chainId 失败');
+            const tailTx = await payerWallet.signTransaction({
+                to: params.routeAddress,
+                value: 0n,
+                data: '0x',
+                nonce: nonce + 1,
+                gasLimit: 21000n,
+                gasPrice: tx.gasPrice ?? undefined,
+                chainId,
+                type: 0,
+            });
+            signedTxs.push(tailTx);
+        }
+        return {
+            signedTransactions: signedTxs,
+            metadata: {
+                payer: payerWallet.address,
+                beneficiary,
+                sellerOwner: metadata.sellerOwner,
+                sellerSender: metadata.sellerSender,
+                buyerOwner: metadata.buyerOwner,
+                buyerSender: metadata.buyerSender,
+                sellAmountWei: metadata.sellAmountWei,
+                buyAmountWei: metadata.buyAmountWei,
+                hasApprove: metadata.hasApprove,
+                routeAddress: params.routeAddress,
+            },
+        };
+    }
+    /**
+     * ✅ 批量捆绑换手（AA）：一卖多买，同一笔 handleOps 原子执行
+     */
+    async bundleBatchSwap(params) {
+        const provider = this.aaManager.getProvider();
+        const payerWallet = new Wallet(params.sellerPrivateKey, provider);
+        const beneficiary = payerWallet.address;
+        const { ops, metadata } = await this.buildBatchSwapOps(params, { signOnly: false });
+        const swapResult = await this.runHandleOps('batchSwapBundle', ops, payerWallet, beneficiary);
+        if (!swapResult)
+            throw new Error('批量换手交易失败');
+        return { swapResult, metadata };
+    }
+    /**
+     * ✅ 批量捆绑换手（AA，仅签名）
+     */
+    async bundleBatchSwapSign(params) {
+        const provider = this.aaManager.getProvider();
+        const payerPk = (params.payerPrivateKey ?? params.sellerPrivateKey);
+        const payerWallet = new Wallet(payerPk, provider);
+        const beneficiary = params.beneficiary ?? payerWallet.address;
+        const { ops, metadata } = await this.buildBatchSwapOps(params, { signOnly: true });
+        const signedHandleOpsTx = await this.signHandleOpsTx({
+            ops,
+            payerWallet,
+            beneficiary,
+            nonce: params.payerStartNonce,
+            gasLimit: params.handleOpsGasLimit,
+        });
+        const signedTxs = [signedHandleOpsTx];
+        if (params.routeAddress) {
+            const tx = Transaction.from(signedHandleOpsTx);
+            const nonce = Number(tx.nonce);
+            const chainId = Number(tx.chainId || 0);
+            if (!Number.isFinite(nonce) || nonce < 0)
+                throw new Error('解析 handleOps nonce 失败');
+            if (!Number.isFinite(chainId) || chainId <= 0)
+                throw new Error('解析 handleOps chainId 失败');
+            const tailTx = await payerWallet.signTransaction({
+                to: params.routeAddress,
+                value: 0n,
+                data: '0x',
+                nonce: nonce + 1,
+                gasLimit: 21000n,
+                gasPrice: tx.gasPrice ?? undefined,
+                chainId,
+                type: 0,
+            });
+            signedTxs.push(tailTx);
+        }
+        return {
+            signedTransactions: signedTxs,
+            metadata: {
+                payer: payerWallet.address,
+                beneficiary,
+                sellerOwner: metadata.sellerOwner,
+                sellerSender: metadata.sellerSender,
+                buyerOwners: metadata.buyerOwners,
+                buyerSenders: metadata.buyerSenders,
+                sellAmountWei: metadata.sellAmountWei,
+                buyAmountsWei: metadata.buyAmountsWei,
+                hasApprove: metadata.hasApprove,
+                routeAddress: params.routeAddress,
+            },
+        };
+    }
 }
 // ============================================================================
 // 便捷函数
@@ -783,3 +1246,31 @@ export async function bundleBuySell(params) {
     const executor = createBundleExecutor(params.config);
     return executor.bundleBuySell(params);
 }
+/**
+ * 快速捆绑换手（链上执行）
+ */
+export async function bundleSwap(params) {
+    const executor = createBundleExecutor(params.config);
+    return executor.bundleSwap(params);
+}
+/**
+ * 快速捆绑换手（仅签名，返回 raw signed tx）
+ */
+export async function bundleSwapSign(params) {
+    const executor = createBundleExecutor(params.config);
+    return executor.bundleSwapSign(params);
+}
+/**
+ * 快速批量捆绑换手（链上执行）
+ */
+export async function bundleBatchSwap(params) {
+    const executor = createBundleExecutor(params.config);
+    return executor.bundleBatchSwap(params);
+}
+/**
+ * 快速批量捆绑换手（仅签名）
+ */
+export async function bundleBatchSwapSign(params) {
+    const executor = createBundleExecutor(params.config);
+    return executor.bundleBatchSwapSign(params);
+}

package/dist/xlayer/index.d.ts

@@ -61,13 +61,17 @@ export * from './types.js';
 export { BundlerClient, createBundlerClient, type BundlerConfig, type BundlerReceipt, } from './bundler.js';
 export { AAAccountManager, createAAAccountManager, predictSender, createWallet, encodeExecute, encodeExecuteBatch, generateAAWallets, generateAAWalletsFromMnemonic, predictSendersFromPrivateKeys, type GeneratedAAWallet, type GenerateAAWalletsParams, type GenerateAAWalletsResult, } from './aa-account.js';
 export { encodeBuyCall, encodeSellCall, encodeApproveCall, encodeTransferCall, PortalQuery, createPortalQuery, applySlippage, formatOkb, parseOkb, formatTokenAmount, parseTokenAmount, type PortalQueryConfig, } from './portal-ops.js';
-export { BundleExecutor, createBundleExecutor, bundleBuy, bundleSell, bundleBuySell, } from './bundle.js';
+export { BundleExecutor, createBundleExecutor, bundleBuy, bundleSell, bundleBuySell, bundleSwap, bundleSwapSign, bundleBatchSwap, bundleBatchSwapSign, } from './bundle.js';
 export { VolumeExecutor, createVolumeExecutor, makeVolume, singleRoundVolume, } from './volume.js';
 export { DexQuery, DexExecutor, createDexQuery, createDexExecutor, quoteOkbToToken, quoteTokenToOkb, encodeSwapExactETHForTokens, encodeSwapExactTokensForETH, encodeSwapExactTokensForTokens, encodeSwapExactETHForTokensSupportingFee, encodeSwapExactTokensForETHSupportingFee, encodeSwapExactTokensForTokensSupportingFee, type DexConfig, } from './dex.js';
 export declare const xlayer: {
     bundleBuy: (params: import("./types.js").BundleBuyParams) => Promise<import("./types.js").BundleBuyResult>;
     bundleSell: (params: import("./types.js").BundleSellParams) => Promise<import("./types.js").BundleSellResult>;
     bundleBuySell: (params: import("./types.js").BundleBuySellParams) => Promise<import("./types.js").BundleBuySellResult>;
+    bundleSwap: (params: import("./types.js").BundleSwapParams) => Promise<import("./types.js").BundleSwapResult>;
+    bundleSwapSign: (params: import("./types.js").BundleSwapSignParams) => Promise<import("./types.js").BundleSwapSignResult>;
+    bundleBatchSwap: (params: import("./types.js").BundleBatchSwapParams) => Promise<import("./types.js").BundleBatchSwapResult>;
+    bundleBatchSwapSign: (params: import("./types.js").BundleBatchSwapSignParams) => Promise<import("./types.js").BundleBatchSwapSignResult>;
     makeVolume: (params: import("./types.js").VolumeParams) => Promise<import("./types.js").VolumeResult>;
     quoteOkbToToken: (okbAmount: bigint, tokenAddress: string, config?: import("./dex.js").DexConfig | undefined) => Promise<bigint>;
     quoteTokenToOkb: (tokenAmount: bigint, tokenAddress: string, config?: import("./dex.js").DexConfig | undefined) => Promise<bigint>;

package/dist/xlayer/index.js

@@ -81,7 +81,7 @@ export { encodeBuyCall, encodeSellCall, encodeApproveCall, encodeTransferCall, P
 // ============================================================================
 // 捆绑交易
 // ============================================================================
-export { BundleExecutor, createBundleExecutor, bundleBuy, bundleSell, bundleBuySell, } from './bundle.js';
+export { BundleExecutor, createBundleExecutor, bundleBuy, bundleSell, bundleBuySell, bundleSwap, bundleSwapSign, bundleBatchSwap, bundleBatchSwapSign, } from './bundle.js';
 // ============================================================================
 // 刷量/做市
 // ============================================================================
@@ -112,6 +112,22 @@ export const xlayer = {
         const { bundleBuySell } = await import('./bundle.js');
         return bundleBuySell(...args);
     },
+    bundleSwap: async (...args) => {
+        const { bundleSwap } = await import('./bundle.js');
+        return bundleSwap(...args);
+    },
+    bundleSwapSign: async (...args) => {
+        const { bundleSwapSign } = await import('./bundle.js');
+        return bundleSwapSign(...args);
+    },
+    bundleBatchSwap: async (...args) => {
+        const { bundleBatchSwap } = await import('./bundle.js');
+        return bundleBatchSwap(...args);
+    },
+    bundleBatchSwapSign: async (...args) => {
+        const { bundleBatchSwapSign } = await import('./bundle.js');
+        return bundleBatchSwapSign(...args);
+    },
     // 刷量
     makeVolume: async (...args) => {
         const { makeVolume } = await import('./volume.js');

package/dist/xlayer/types.d.ts

@@ -189,6 +189,142 @@ export interface BundleBuySellParams {
     /** 配置覆盖 */
     config?: Partial<XLayerConfig>;
 }
+/**
+ * 捆绑换手参数（AA 模式，单卖单买）
+ * - 卖方 AA 先卖出
+ * - 买方 AA 再买入
+ * - 两个 UserOp（以及可选 approve）放入同一笔 handleOps
+ */
+export interface BundleSwapParams {
+    /** 代币地址 */
+    tokenAddress: string;
+    /** 卖方 Owner 私钥 */
+    sellerPrivateKey: string;
+    /** 买方 Owner 私钥 */
+    buyerPrivateKey: string;
+    /** 卖出数量（人类可读字符串，按代币 decimals 解析）；优先于 sellPercent */
+    sellAmount?: string;
+    /** 卖出比例（0-100，默认 100） */
+    sellPercent?: number;
+    /**
+     * 买入 OKB 数量（字符串）。
+     * - 不传则默认使用 previewSell(sellAmount) 的结果，并应用 slippageBps
+     */
+    buyAmountOkb?: string;
+    /** 预估卖出滑点（基点），默认 100 = 1%（用于 buyAmountOkb 未传入时） */
+    slippageBps?: number;
+    /** 配置覆盖 */
+    config?: Partial<XLayerConfig>;
+}
+/**
+ * 捆绑换手执行结果（链上执行 handleOps）
+ */
+export interface BundleSwapResult {
+    /** handleOps 交易结果 */
+    swapResult: HandleOpsResult;
+    /** 元数据（便于前端显示） */
+    metadata: {
+        sellerOwner: string;
+        sellerSender: string;
+        buyerOwner: string;
+        buyerSender: string;
+        sellAmountWei: string;
+        buyAmountWei: string;
+        hasApprove: boolean;
+    };
+}
+/**
+ * 捆绑换手签名参数（仅签名 handleOps 交易；可选追加 route 尾交易）
+ * - 返回 raw signed tx，可按“BSC 捆绑”模式交给后端/Builder 提交
+ */
+export interface BundleSwapSignParams extends BundleSwapParams {
+    /** Payer 私钥（用于签 handleOps 交易）；默认 sellerPrivateKey */
+    payerPrivateKey?: string;
+    /** beneficiary（默认 payer 地址） */
+    beneficiary?: string;
+    /** 可选：指定 payer 起始 nonce（不传则用 pending nonce） */
+    payerStartNonce?: number;
+    /** 可选：覆盖 handleOps gasLimit（不传则自动 estimate，失败回退） */
+    handleOpsGasLimit?: bigint;
+    /**
+     * 可选：routeAddress（如果你的后端要求“route 尾交易”，则传入）
+     * - SDK 会自动构造 nonce+1 的空转账 tailTx
+     */
+    routeAddress?: string;
+}
+/**
+ * 捆绑换手签名结果
+ */
+export interface BundleSwapSignResult {
+    /** raw signed tx 列表（handleOps 在前；如果有 routeAddress 则 tailTx 在后） */
+    signedTransactions: string[];
+    /** 元数据（便于前端显示） */
+    metadata: {
+        payer: string;
+        beneficiary: string;
+        sellerOwner: string;
+        sellerSender: string;
+        buyerOwner: string;
+        buyerSender: string;
+        sellAmountWei: string;
+        buyAmountWei: string;
+        hasApprove: boolean;
+        routeAddress?: string;
+    };
+}
+/**
+ * 批量捆绑换手参数（一卖多买）
+ */
+export interface BundleBatchSwapParams {
+    /** 代币地址 */
+    tokenAddress: string;
+    /** 卖方 Owner 私钥 */
+    sellerPrivateKey: string;
+    /** 买方 Owner 私钥列表 */
+    buyerPrivateKeys: string[];
+    /** 每个买方的买入 OKB 数量（字符串，长度必须与 buyerPrivateKeys 一致） */
+    buyAmountsOkb: string[];
+    /** 卖出数量（人类可读字符串，按代币 decimals 解析）；优先于 sellPercent */
+    sellAmount?: string;
+    /** 卖出比例（0-100，默认 100） */
+    sellPercent?: number;
+    /** 配置覆盖 */
+    config?: Partial<XLayerConfig>;
+}
+export interface BundleBatchSwapResult {
+    swapResult: HandleOpsResult;
+    metadata: {
+        sellerOwner: string;
+        sellerSender: string;
+        buyerOwners: string[];
+        buyerSenders: string[];
+        sellAmountWei: string;
+        buyAmountsWei: string[];
+        hasApprove: boolean;
+    };
+}
+export interface BundleBatchSwapSignParams extends BundleBatchSwapParams {
+    payerPrivateKey?: string;
+    beneficiary?: string;
+    payerStartNonce?: number;
+    handleOpsGasLimit?: bigint;
+    routeAddress?: string;
+}
+export interface BundleBatchSwapSignResult {
+    signedTransactions: string[];
+    metadata: {
+        payer: string;
+        beneficiary: string;
+        sellerOwner: string;
+        sellerSender: string;
+        buyerOwners: string[];
+        buyerSenders: string[];
+        sellAmountWei: string;
+        buyAmountsWei: string[];
+        hasApprove: boolean;
+        routeAddress?: string;
+    };
+}
 /**
  * 刷量参数
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "four-flap-meme-sdk",
-  "version": "1.5.26",
+  "version": "1.5.27",
   "description": "SDK for Flap bonding curve and four.meme TokenManager",
   "type": "module",
   "main": "dist/index.js",