four-flap-meme-sdk 1.5.32 → 1.5.34

package/dist/xlayer/portal-buy-first.js

@@ -0,0 +1,415 @@
+/**
+ * XLayer AA Buy-First（内盘 / Flap Portal）
+ *
+ * 对齐 BSC buy-first 思路：
+ * - 买方先买入（多钱包随机拆分资金）
+ * - 卖方再卖出“等值 token”（卖方需要预持仓）
+ * - ✅ 利润：在“卖出后归集 OKB”阶段刮取（executeBatch 拆分给 profitRecipient + owner）
+ *
+ * 说明：
+ * - buy + sell 会放在同一笔 handleOps 内，保持“buy-first 原子”语义
+ * - withdraw 需要知道 sell 后的余额，因此单独再发一笔 handleOps
+ */
+import { Contract, Interface, Wallet, ethers } from 'ethers';
+import { AANonceMap } from './types.js';
+import { ENTRYPOINT_ABI, DEFAULT_WITHDRAW_RESERVE, FLAP_PORTAL, } from './constants.js';
+import { AAAccountManager, encodeExecute, encodeExecuteBatch } from './aa-account.js';
+import { PortalQuery, encodeApproveCall, encodeBuyCall, encodeSellCall, parseOkb } from './portal-ops.js';
+import { mapWithConcurrency } from '../utils/concurrency.js';
+import { PROFIT_CONFIG } from '../utils/constants.js';
+// 固定 gas（用于减少 RPC 与提高可控性）
+const DEFAULT_CALL_GAS_LIMIT_BUY = 450000n;
+const DEFAULT_CALL_GAS_LIMIT_SELL = 450000n;
+const DEFAULT_CALL_GAS_LIMIT_APPROVE = 200000n;
+const DEFAULT_CALL_GAS_LIMIT_WITHDRAW = 120000n;
+function resolveProfitSettings(config) {
+    const extractProfit = config?.extractProfit !== false; // 默认 true
+    const profitBpsRaw = config?.profitBps ?? PROFIT_CONFIG.RATE_BPS_SWAP;
+    const profitBps = Math.max(0, Math.min(10000, Number(profitBpsRaw)));
+    const profitRecipient = config?.profitRecipient ?? PROFIT_CONFIG.RECIPIENT;
+    return { extractProfit, profitBps, profitRecipient };
+}
+function calculateProfitWei(amountWei, profitBps) {
+    if (amountWei <= 0n)
+        return 0n;
+    if (!Number.isFinite(profitBps) || profitBps <= 0)
+        return 0n;
+    return (amountWei * BigInt(profitBps)) / 10000n;
+}
+function shuffle(arr) {
+    const a = arr.slice();
+    for (let i = a.length - 1; i > 0; i--) {
+        const j = Math.floor(Math.random() * (i + 1));
+        [a[i], a[j]] = [a[j], a[i]];
+    }
+    return a;
+}
+/**
+ * ✅ 将金额随机拆分成多份（BigInt 安全）
+ * 每份权重在 0.5 - 1.5 之间随机浮动（用整数权重近似）
+ */
+function splitAmount(totalAmount, count) {
+    if (count <= 0)
+        throw new Error('拆分份数必须大于 0');
+    if (count === 1)
+        return [totalAmount];
+    if (totalAmount <= 0n)
+        return new Array(count).fill(0n);
+    const SCALE = 1000000n;
+    const weights = [];
+    for (let i = 0; i < count; i++) {
+        // [0.5, 1.5) * SCALE
+        const w = BigInt(500000 + Math.floor(Math.random() * 1000000));
+        weights.push(w);
+    }
+    const totalWeight = weights.reduce((a, b) => a + b, 0n);
+    const amounts = [];
+    let allocated = 0n;
+    for (let i = 0; i < count - 1; i++) {
+        const amt = (totalAmount * weights[i]) / totalWeight;
+        amounts.push(amt);
+        allocated += amt;
+    }
+    amounts.push(totalAmount - allocated);
+    return shuffle(amounts);
+}
+export class AAPortalBuyFirstExecutor {
+    constructor(config = {}) {
+        this.config = config;
+        this.aaManager = new AAAccountManager(config);
+        this.portalQuery = new PortalQuery({ rpcUrl: config.rpcUrl, chainId: config.chainId });
+    }
+    async runHandleOps(label, ops, bundlerSigner, beneficiary) {
+        const provider = this.aaManager.getProvider();
+        const entryPointAddress = this.aaManager.getEntryPointAddress();
+        const feeData = await provider.getFeeData();
+        console.log(`\n[${label}] 发送 handleOps，ops=${ops.length} ...`);
+        const entryPointWithSigner = new Contract(entryPointAddress, ENTRYPOINT_ABI, bundlerSigner);
+        const tx = await entryPointWithSigner.handleOps(ops, beneficiary, { gasPrice: feeData.gasPrice ?? 100000000n });
+        console.log(`[${label}] txHash:`, tx.hash);
+        const receipt = await tx.wait();
+        console.log(`[${label}] mined block=${receipt.blockNumber} status=${receipt.status}`);
+        const epIface = new Interface(ENTRYPOINT_ABI);
+        const userOpEvents = [];
+        for (const log of receipt.logs) {
+            try {
+                const parsed = epIface.parseLog(log);
+                if (parsed?.name === 'UserOperationEvent') {
+                    const e = parsed.args;
+                    userOpEvents.push({
+                        userOpHash: e.userOpHash,
+                        sender: e.sender,
+                        paymaster: e.paymaster,
+                        success: e.success,
+                        actualGasCost: e.actualGasCost,
+                        actualGasUsed: e.actualGasUsed,
+                    });
+                }
+            }
+            catch { }
+        }
+        return { txHash: tx.hash, blockNumber: receipt.blockNumber, status: receipt.status, userOpEvents };
+    }
+    pickWallets(privateKeys, n) {
+        const provider = this.aaManager.getProvider();
+        const wallets = privateKeys.map((pk) => new Wallet(pk, provider));
+        if (!n || n <= 0 || n >= wallets.length)
+            return wallets;
+        return wallets.slice(0, n);
+    }
+    async getAccountInfos(wallets) {
+        return await this.aaManager.getMultipleAccountInfo(wallets.map((w) => w.address));
+    }
+    async safePreviewBuy(tokenAddress, okbAmount) {
+        if (okbAmount <= 0n)
+            return 0n;
+        try {
+            return await this.portalQuery.previewBuy(tokenAddress, okbAmount);
+        }
+        catch {
+            // fallback：quoteExactInput(native->token)
+            return await this.portalQuery.quoteExactInput('0x0000000000000000000000000000000000000000', tokenAddress, okbAmount);
+        }
+    }
+    async buildWithdrawUserOp(params) {
+        const senderBalance = params.senderBalance;
+        if (senderBalance <= params.reserveWei)
+            return null;
+        const effConfig = { ...(this.config ?? {}), ...(params.configOverride ?? {}) };
+        const gasPolicyRaw = effConfig.gasPolicy ?? 'bundlerEstimate';
+        const gasPolicy = gasPolicyRaw === 'bundlerEstimate' ? 'fixed' : gasPolicyRaw;
+        // 先估 prefund（空调用）
+        const tempCallData = encodeExecute(params.ownerWallet.address, 0n, '0x');
+        const { prefundWei } = gasPolicy === 'fixed'
+            ? await this.aaManager.buildUserOpWithFixedGas({
+                ownerWallet: params.ownerWallet,
+                sender: params.sender,
+                callData: tempCallData,
+                nonce: params.nonce,
+                initCode: params.initCode,
+                deployed: params.initCode === '0x',
+                fixedGas: {
+                    ...(effConfig.fixedGas ?? {}),
+                    callGasLimit: effConfig.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,
+            });
+        const withdrawAmount = senderBalance > prefundWei + params.reserveWei
+            ? senderBalance - prefundWei - params.reserveWei
+            : 0n;
+        if (withdrawAmount <= 0n)
+            return null;
+        const { extractProfit, profitBps, profitRecipient } = resolveProfitSettings(effConfig);
+        const profitWei = extractProfit ? calculateProfitWei(withdrawAmount, profitBps) : 0n;
+        const toOwnerWei = withdrawAmount - profitWei;
+        const callData = extractProfit && profitWei > 0n
+            ? encodeExecuteBatch([profitRecipient, params.ownerWallet.address], [profitWei, toOwnerWei], ['0x', '0x'])
+            : encodeExecute(params.ownerWallet.address, withdrawAmount, '0x');
+        const { userOp } = gasPolicy === 'fixed'
+            ? await this.aaManager.buildUserOpWithFixedGas({
+                ownerWallet: params.ownerWallet,
+                sender: params.sender,
+                callData,
+                nonce: params.nonce,
+                initCode: params.initCode,
+                deployed: params.initCode === '0x',
+                fixedGas: {
+                    ...(effConfig.fixedGas ?? {}),
+                    callGasLimit: effConfig.fixedGas?.callGasLimit ?? DEFAULT_CALL_GAS_LIMIT_WITHDRAW,
+                },
+            })
+            : await this.aaManager.buildUserOpWithLocalEstimate({
+                ownerWallet: params.ownerWallet,
+                sender: params.sender,
+                callData,
+                nonce: params.nonce,
+                initCode: params.initCode,
+            });
+        return { userOp, prefundWei, profitWei };
+    }
+    /**
+     * 执行一轮 buy-first（内盘）
+     */
+    async execute(params) {
+        const { tradeType = 'FLAP', tokenAddress, buyerPrivateKeys, sellerPrivateKeys, buyerFunds, buyCount, sellCount, slippageBps = 0, withdrawToOwner = true, withdrawReserve = DEFAULT_WITHDRAW_RESERVE, config, } = params;
+        if (tradeType !== 'FLAP') {
+            throw new Error('AAPortalBuyFirstExecutor 仅支持 tradeType=FLAP（内盘）');
+        }
+        const buyers = this.pickWallets(buyerPrivateKeys, buyCount);
+        const sellers = this.pickWallets(sellerPrivateKeys, sellCount);
+        if (buyers.length === 0)
+            throw new Error('buyCount=0 或 buyerPrivateKeys 为空');
+        if (sellers.length === 0)
+            throw new Error('sellCount=0 或 sellerPrivateKeys 为空');
+        const effConfig = { ...(this.config ?? {}), ...(config ?? {}) };
+        const profitSettings = resolveProfitSettings(effConfig);
+        const totalBuyWei = parseOkb(String(buyerFunds));
+        if (totalBuyWei <= 0n)
+            throw new Error('buyerFunds 需要 > 0');
+        const buyAmountsWei = splitAmount(totalBuyWei, buyers.length);
+        // 估算买入 tokenOut，并按 slippageBps 做折减（只用于估算 sellAmount）
+        const quotedPerBuy = await mapWithConcurrency(buyAmountsWei, 6, async (amt) => this.safePreviewBuy(tokenAddress, amt));
+        const quotedTotalTokenOut = quotedPerBuy.reduce((a, b) => a + (b ?? 0n), 0n);
+        const estimatedTokenOutWei = (quotedTotalTokenOut * BigInt(10000 - Math.max(0, Math.min(10000, slippageBps)))) / 10000n;
+        if (estimatedTokenOutWei <= 0n) {
+            throw new Error('买入报价为 0，无法规划 sellAmount（可能无流动性或报价失败）');
+        }
+        const sellAmountsWei = splitAmount(estimatedTokenOutWei, sellers.length);
+        // 获取 AA 账户信息
+        const buyerAis = await this.getAccountInfos(buyers);
+        const sellerAis = await this.getAccountInfos(sellers);
+        // nonceMap
+        const nonceMap = new AANonceMap();
+        for (const ai of buyerAis)
+            nonceMap.init(ai.sender, ai.nonce);
+        for (const ai of sellerAis)
+            nonceMap.init(ai.sender, ai.nonce);
+        // initCode：确保同一 sender 只在第一笔 op 携带
+        const initCodeBySenderLower = new Map();
+        const initIfNeeded = (sender, deployed, ownerAddress) => {
+            const k = sender.toLowerCase();
+            if (initCodeBySenderLower.has(k))
+                return;
+            initCodeBySenderLower.set(k, deployed ? '0x' : this.aaManager.generateInitCode(ownerAddress));
+        };
+        const consumeInitCode = (sender) => {
+            const k = sender.toLowerCase();
+            const cur = initCodeBySenderLower.get(k);
+            if (cur === undefined)
+                throw new Error(`initCode not initialized for sender: ${sender}`);
+            if (cur !== '0x')
+                initCodeBySenderLower.set(k, '0x');
+            return cur;
+        };
+        for (let i = 0; i < buyers.length; i++)
+            initIfNeeded(buyerAis[i].sender, buyerAis[i].deployed, buyers[i].address);
+        for (let i = 0; i < sellers.length; i++)
+            initIfNeeded(sellerAis[i].sender, sellerAis[i].deployed, sellers[i].address);
+        // 卖方余额检查（需要预持仓）
+        const sellerSenders = sellerAis.map((ai) => ai.sender);
+        const sellerTokenBalances = await this.portalQuery.getMultipleTokenBalances(tokenAddress, sellerSenders);
+        for (let i = 0; i < sellers.length; i++) {
+            const sender = sellerSenders[i];
+            const needSell = sellAmountsWei[i] ?? 0n;
+            const bal = sellerTokenBalances.get(sender) ?? 0n;
+            if (needSell > bal) {
+                throw new Error(`卖方预持仓不足: sender=${sender} need=${needSell.toString()} bal=${bal.toString()}`);
+            }
+        }
+        // 卖方 allowance 检查（spender=FLAP_PORTAL）
+        const sellerAllowances = await this.portalQuery.getMultipleAllowances(tokenAddress, sellerSenders, FLAP_PORTAL);
+        // 构建 ops（buy-first：buy -> (approve) -> sell）
+        const ops = [];
+        // 1) buy ops（多买方）
+        for (let i = 0; i < buyers.length; i++) {
+            const w = buyers[i];
+            const ai = buyerAis[i];
+            const sender = ai.sender;
+            const buyWei = buyAmountsWei[i] ?? 0n;
+            if (buyWei <= 0n)
+                continue;
+            const swapData = encodeBuyCall(tokenAddress, buyWei, 0n);
+            const callData = encodeExecute(FLAP_PORTAL, buyWei, swapData);
+            const { userOp, prefundWei } = await this.aaManager.buildUserOpWithFixedGas({
+                ownerWallet: w,
+                sender,
+                nonce: nonceMap.next(sender),
+                initCode: consumeInitCode(sender),
+                callData,
+                deployed: ai.deployed,
+                fixedGas: {
+                    ...(effConfig.fixedGas ?? {}),
+                    callGasLimit: effConfig.fixedGas?.callGasLimit ?? DEFAULT_CALL_GAS_LIMIT_BUY,
+                },
+            });
+            // 确保 sender 有足够余额：买入金额 + prefund（paymaster 下 prefund=0）
+            await this.aaManager.ensureSenderBalance(w, sender, buyWei + prefundWei + parseOkb('0.0001'), `buyFirst/buyer${i + 1}/fund`);
+            const signed = await this.aaManager.signUserOp(userOp, w);
+            ops.push(signed.userOp);
+        }
+        // 2) seller approve + sell ops
+        for (let i = 0; i < sellers.length; i++) {
+            const w = sellers[i];
+            const ai = sellerAis[i];
+            const sender = ai.sender;
+            const sellWei = sellAmountsWei[i] ?? 0n;
+            if (sellWei <= 0n)
+                continue;
+            const allowance = sellerAllowances.get(sender) ?? 0n;
+            if (allowance < sellWei) {
+                const approveCallData = encodeExecute(tokenAddress, 0n, encodeApproveCall(FLAP_PORTAL, ethers.MaxUint256));
+                const { userOp: approveOp, prefundWei } = await this.aaManager.buildUserOpWithFixedGas({
+                    ownerWallet: w,
+                    sender,
+                    nonce: nonceMap.next(sender),
+                    initCode: consumeInitCode(sender),
+                    callData: approveCallData,
+                    deployed: ai.deployed,
+                    fixedGas: {
+                        ...(effConfig.fixedGas ?? {}),
+                        callGasLimit: effConfig.fixedGas?.callGasLimit ?? DEFAULT_CALL_GAS_LIMIT_APPROVE,
+                    },
+                });
+                await this.aaManager.ensureSenderBalance(w, sender, prefundWei + parseOkb('0.0001'), `buyFirst/seller${i + 1}/approve-fund`);
+                const signedApprove = await this.aaManager.signUserOp(approveOp, w);
+                ops.push(signedApprove.userOp);
+            }
+            const sellSwapData = encodeSellCall(tokenAddress, sellWei, 0n);
+            const sellCallData = encodeExecute(FLAP_PORTAL, 0n, sellSwapData);
+            const { userOp: sellOp, prefundWei: sellPrefund } = await this.aaManager.buildUserOpWithFixedGas({
+                ownerWallet: w,
+                sender,
+                nonce: nonceMap.next(sender),
+                initCode: consumeInitCode(sender),
+                callData: sellCallData,
+                deployed: ai.deployed,
+                fixedGas: {
+                    ...(effConfig.fixedGas ?? {}),
+                    callGasLimit: effConfig.fixedGas?.callGasLimit ?? DEFAULT_CALL_GAS_LIMIT_SELL,
+                },
+            });
+            await this.aaManager.ensureSenderBalance(w, sender, sellPrefund + parseOkb('0.0001'), `buyFirst/seller${i + 1}/sell-fund`);
+            const signedSell = await this.aaManager.signUserOp(sellOp, w);
+            ops.push(signedSell.userOp);
+        }
+        if (ops.length === 0) {
+            throw new Error('本轮没有生成任何 UserOp（buyAmounts 或 sellAmounts 可能全为 0）');
+        }
+        // payer/beneficiary
+        const payerWallet = buyers[0];
+        const beneficiary = payerWallet.address;
+        // 第一步：buy-first 原子阶段
+        const buySellResult = await this.runHandleOps('aa-buy-first/portal', ops, payerWallet, beneficiary);
+        // 第二步：可选归集（卖方）
+        let withdrawResult;
+        let finalSellerBalances;
+        let totalProfitWei = 0n;
+        if (withdrawToOwner) {
+            const reserveWei = parseOkb(withdrawReserve);
+            const sellerOkbBalances = await this.portalQuery.getMultipleOkbBalances(sellerSenders);
+            const withdrawOps = [];
+            const withdrawOpsBuilt = await mapWithConcurrency(sellers, 3, async (w, i) => {
+                const sender = sellerAis[i].sender;
+                const senderBalance = sellerOkbBalances.get(sender) ?? 0n;
+                const usedNonce = nonceMap.peek(sender);
+                const built = await this.buildWithdrawUserOp({
+                    ownerWallet: w,
+                    sender,
+                    nonce: usedNonce,
+                    initCode: '0x',
+                    senderBalance,
+                    reserveWei,
+                    configOverride: config,
+                });
+                if (!built)
+                    return null;
+                nonceMap.commit(sender, usedNonce);
+                totalProfitWei += built.profitWei;
+                const signed = await this.aaManager.signUserOp(built.userOp, w);
+                return signed.userOp;
+            });
+            for (const op of withdrawOpsBuilt)
+                if (op)
+                    withdrawOps.push(op);
+            if (withdrawOps.length > 0) {
+                withdrawResult = await this.runHandleOps('aa-buy-first/portal-withdraw', withdrawOps, payerWallet, beneficiary);
+            }
+            finalSellerBalances = await this.portalQuery.getMultipleOkbBalances(sellerSenders);
+        }
+        return {
+            buySellResult,
+            withdrawResult,
+            finalSellerBalances,
+            profit: withdrawToOwner
+                ? {
+                    extractProfit: profitSettings.extractProfit,
+                    profitBps: profitSettings.profitBps,
+                    profitRecipient: profitSettings.profitRecipient,
+                    totalProfitWei: totalProfitWei.toString(),
+                }
+                : undefined,
+            metadata: {
+                tradeType: 'FLAP',
+                tokenAddress,
+                buyerOwners: buyers.map((w) => w.address),
+                buyerSenders: buyerAis.map((ai) => ai.sender),
+                sellerOwners: sellers.map((w) => w.address),
+                sellerSenders,
+                buyAmountsWei: buyAmountsWei.map((x) => x.toString()),
+                sellAmountsWei: sellAmountsWei.map((x) => x.toString()),
+                totalBuyWei: totalBuyWei.toString(),
+                estimatedTokenOutWei: estimatedTokenOutWei.toString(),
+                slippageBps,
+            },
+        };
+    }
+}
+export function createAAPortalBuyFirstExecutor(config) {
+    return new AAPortalBuyFirstExecutor(config);
+}

package/dist/xlayer/types.d.ts

@@ -161,8 +161,12 @@ export interface BundleBuyParams {
     tokenAddress: string;
     /** Owner 私钥列表 */
     privateKeys: string[];
-    /** 每个 owner 的买入金额（OKB） */
+    /** 每个 owner 的买入金额（OKB 或 quoteToken，取决于 quoteToken 参数） */
     buyAmounts: string[];
+    /** 买入使用的代币地址（零地址表示使用原生代币 OKB，非零地址表示使用 ERC20 代币如 USDC） */
+    quoteToken?: string;
+    /** quoteToken 的精度（默认 18，如果 quoteToken 不是 18 位精度需要指定） */
+    quoteTokenDecimals?: number;
     /** 是否将代币转回 owner EOA（默认 false） */
     transferBackToOwner?: boolean;
     /** 配置覆盖 */
@@ -193,8 +197,12 @@ export interface BundleBuySellParams {
     tokenAddress: string;
     /** Owner 私钥列表 */
     privateKeys: string[];
-    /** 每个 owner 的买入金额（OKB） */
+    /** 每个 owner 的买入金额（OKB 或 quoteToken，取决于 quoteToken 参数） */
     buyAmounts: string[];
+    /** 买入使用的代币地址（零地址表示使用原生代币 OKB，非零地址表示使用 ERC20 代币如 USDC） */
+    quoteToken?: string;
+    /** quoteToken 的精度（默认 18，如果 quoteToken 不是 18 位精度需要指定） */
+    quoteTokenDecimals?: number;
     /** 卖出比例（0-100，默认 100 全部卖出） */
     sellPercent?: number;
     /** 是否将 OKB 归集回 owner EOA（默认 true） */
@@ -234,6 +242,14 @@ export interface BundleSwapParams {
     buyAmountOkb?: string;
     /** 预估卖出滑点（基点），默认 100 = 1%（用于 buyAmountOkb 未传入时） */
     slippageBps?: number;
+    /**
+     * ✅ 转账多跳数（AA 专用，且与 BSC 的“多跳”逻辑相互独立）
+     *
+     * 用途：当卖出与买入不是同一个 AA(Sender) 时，需要把卖出得到的 OKB 先转到买方 AA(Sender) 才能执行 buy。
+     * - 0：卖方 AA(Sender) 直接转给买方 AA(Sender)
+     * - >0：按“多跳”方式转账（实现位于 xlayer/*，不会影响 BSC bundle/merkle）
+     */
+    disperseHopCount?: number;
     /** 配置覆盖 */
     config?: Partial<XLayerConfig>;
 }
@@ -263,6 +279,8 @@ export interface BundleSwapResult {
         profitWei?: string;
         /** 预估卖出输出（OKB wei） */
         quotedSellOutWei?: string;
+        /** ✅ AA：转账多跳数（仅 xlayer AA 使用；不影响 BSC） */
+        disperseHopCount?: string;
     };
 }
 /**
@@ -312,6 +330,8 @@ export interface BundleSwapSignResult {
         profitWei?: string;
         /** 预估卖出输出（OKB wei） */
         quotedSellOutWei?: string;
+        /** ✅ AA：转账多跳数（仅 xlayer AA 使用；不影响 BSC） */
+        disperseHopCount?: string;
     };
 }
 /**
@@ -336,6 +356,14 @@ export interface BundleBatchSwapParams {
     sellAmount?: string;
     /** 卖出比例（0-100，默认 100） */
     sellPercent?: number;
+    /**
+     * ✅ 转账多跳数（AA 专用）
+     *
+     * 用途：卖出所得 OKB 需要在同一笔 handleOps 内分发给多个买方 AA(Sender)。
+     * - 0：卖方 AA(Sender) 直接分发给所有买方 AA(Sender)
+     * - >0：按“多跳”方式分发（实现位于 xlayer/*，不会影响 BSC bundle/merkle）
+     */
+    disperseHopCount?: number;
     /** 配置覆盖 */
     config?: Partial<XLayerConfig>;
 }
@@ -360,6 +388,8 @@ export interface BundleBatchSwapResult {
         profitWei?: string;
         /** 预估卖出输出（OKB wei） */
         quotedSellOutWei?: string;
+        /** ✅ AA：转账多跳数（仅 xlayer AA 使用；不影响 BSC） */
+        disperseHopCount?: string;
     };
 }
 export interface BundleBatchSwapSignParams extends BundleBatchSwapParams {
@@ -392,6 +422,8 @@ export interface BundleBatchSwapSignResult {
         profitWei?: string;
         /** 预估卖出输出（OKB wei） */
         quotedSellOutWei?: string;
+        /** ✅ AA：转账多跳数（仅 xlayer AA 使用；不影响 BSC） */
+        disperseHopCount?: string;
     };
 }
 /**
@@ -458,6 +490,16 @@ export interface BundleSellResult {
     sellResult: HandleOpsResult;
     /** 归集交易结果（如果 withdrawToOwner） */
     withdrawResult?: HandleOpsResult;
+    /**
+     * 利润汇总（如果 withdrawToOwner=true 且实际归集金额>0）
+     * - 注意：AA 的 handleOps tx.value 永远是 0；利润是“从 AA Sender 余额里拆分转走”的金额
+     */
+    profit?: {
+        extractProfit: boolean;
+        profitBps: number;
+        profitRecipient: string;
+        totalProfitWei: string;
+    };
 }
 /**
  * 捆绑买卖结果
@@ -473,6 +515,13 @@ export interface BundleBuySellResult {
     withdrawResult?: HandleOpsResult;
     /** 各 sender 的最终 OKB 余额 */
     finalBalances: Map<string, bigint>;
+    /** 利润汇总（如果 withdrawToOwner=true 且实际归集金额>0） */
+    profit?: {
+        extractProfit: boolean;
+        profitBps: number;
+        profitRecipient: string;
+        totalProfitWei: string;
+    };
 }
 /**
  * 刷量结果
@@ -487,6 +536,64 @@ export interface VolumeResult {
     /** 总交易量（OKB） */
     totalVolume: bigint;
 }
+export type BuyFirstTradeType = 'FLAP' | 'V2';
+export interface BuyFirstParams {
+    tradeType?: BuyFirstTradeType;
+    /** DEX 标识（仅 V2 时使用，用于选择 Router） */
+    dexKey?: string;
+    /** 显式指定 Router 地址（仅 V2 时使用） */
+    routerAddress?: string;
+    /** DEX deadline 分钟数（仅 V2 时使用） */
+    deadlineMinutes?: number;
+    tokenAddress: string;
+    buyerPrivateKeys: string[];
+    sellerPrivateKeys: string[];
+    /** 本轮总买入资金（OKB） */
+    buyerFunds: string;
+    buyCount?: number;
+    sellCount?: number;
+    /** 报价滑点（仅用于估算 sellAmount），默认 0 */
+    slippageBps?: number;
+    withdrawToOwner?: boolean;
+    withdrawReserve?: string;
+    config?: Partial<XLayerConfig>;
+}
+export interface BuyFirstResult {
+    buySellResult: HandleOpsResult;
+    withdrawResult?: HandleOpsResult;
+    finalSellerBalances?: Map<string, bigint>;
+    profit?: {
+        extractProfit: boolean;
+        profitBps: number;
+        profitRecipient: string;
+        totalProfitWei: string;
+    };
+    metadata: {
+        tradeType: BuyFirstTradeType;
+        tokenAddress: string;
+        buyerOwners: string[];
+        buyerSenders: string[];
+        sellerOwners: string[];
+        sellerSenders: string[];
+        buyAmountsWei: string[];
+        sellAmountsWei: string[];
+        totalBuyWei: string;
+        estimatedTokenOutWei: string;
+        slippageBps: number;
+    };
+}
+export interface BuyFirstVolumeParams extends Omit<BuyFirstParams, 'buyerFunds'> {
+    buyerFundsPerRound: string;
+    rounds: number;
+    intervalMs?: number;
+}
+export interface BuyFirstVolumeResult {
+    successRounds: number;
+    failedRounds: number;
+    roundResults: BuyFirstResult[];
+    /** 总交易量（OKB wei，按“买入资金*2”统计） */
+    totalVolume: bigint;
+}
 /**
  * 外盘（PotatoSwap）交易参数
  */

package/package.json

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