four-flap-meme-sdk 1.6.35 → 1.6.37

package/dist/xlayer/aa-account.d.ts

@@ -89,6 +89,12 @@ export declare class AAAccountManager {
      * 获取完整的 AA 账户信息
      */
     getAccountInfo(ownerAddress: string, salt?: bigint): Promise<AAAccount>;
+    /**
+     * 批量获取多个 AA sender 的 nonce
+     * @param senderAddresses AA sender 地址列表
+     * @returns 对应的 nonce 数组
+     */
+    batchGetNonces(senderAddresses: string[]): Promise<bigint[]>;
     /**
      * 生成 initCode（用于在 UserOp 中部署账户）
      */

package/dist/xlayer/aa-account.js

@@ -290,6 +290,40 @@ export class AAAccountManager {
             nonce,
         };
     }
+    /**
+     * 批量获取多个 AA sender 的 nonce
+     * @param senderAddresses AA sender 地址列表
+     * @returns 对应的 nonce 数组
+     */
+    async batchGetNonces(senderAddresses) {
+        if (senderAddresses.length === 0)
+            return [];
+        await this.syncEntryPointIfNeeded();
+        const epIface = new Interface(ENTRYPOINT_ABI);
+        const nonceCalls = senderAddresses.map((sender) => ({
+            target: this.entryPointAddress,
+            allowFailure: true,
+            callData: epIface.encodeFunctionData('getNonce', [sender, 0]),
+        }));
+        const nonces = new Array(senderAddresses.length).fill(0n);
+        const BATCH = 350;
+        for (let cursor = 0; cursor < nonceCalls.length; cursor += BATCH) {
+            const sliceCalls = nonceCalls.slice(cursor, cursor + BATCH);
+            const res = await this.multicallAggregate3({ calls: sliceCalls });
+            for (let i = 0; i < res.length; i++) {
+                const r = res[i];
+                const idx = cursor + i;
+                if (!r?.success || !r.returnData || r.returnData === '0x')
+                    continue;
+                try {
+                    const decoded = epIface.decodeFunctionResult('getNonce', r.returnData);
+                    nonces[idx] = BigInt(decoded?.[0] ?? 0n);
+                }
+                catch { /* ignore */ }
+            }
+        }
+        return nonces;
+    }
     /**
      * 生成 initCode（用于在 UserOp 中部署账户）
      */

package/dist/xlayer/dex-bundle-swap.js

@@ -426,6 +426,7 @@ export class AADexSwapExecutor {
     async bundleBatchSwapSign(params) {
         const { dexKey, routerAddress: routerAddressIn, tokenAddress, sellerPrivateKey, buyerPrivateKeys, buyAmountsOkb, sellAmount, sellPercent = 100, capitalMode = true, // ✅ 默认资金利用率模式（卖出→分发→买入）
         disperseHopCount: disperseHopCountIn, payerPrivateKey, beneficiary: beneficiaryIn, payerStartNonce, routeAddress, skipApprovalCheck = false, tradeType, lpFeeProfile = 0, quoteToken, quoteTokenDecimals = 6, // XLayer USDT/USDC/USDT0 都是 6 位精度
+        prefundedHopWallets, // ✅ 预充值多跳：已预充值的 hop 钱包列表
          } = params;
         const effectiveConfig = { ...(this.config ?? {}), ...(params.config ?? {}) };
         const { extractProfit, profitBps, profitRecipient } = resolveProfitSettings(effectiveConfig);
@@ -581,17 +582,23 @@ export class AADexSwapExecutor {
             extractProfit,
             profitWei: ethers.formatEther(profitWei),
         });
-        // ✅ 多跳模式与 Paymaster 的关系：
+        // ✅ 多跳模式判断：
         // ERC-4337 的 handleOps 执行流程是"先验证所有 UserOps，再执行所有 UserOps"
         // hop 钱包是临时生成的（余额=0），在 validation 阶段无法支付 prefund，会导致 AA21 错误
         // 
-        // 但是！如果配置了 Paymaster，prefund = 0n，hop 钱包不需要余额即可通过验证
-        // 因此：只有在 **没有 Paymaster** 时才需要强制禁用多跳
+        // 多跳可用的条件：
+        // 1. 配置了 Paymaster（prefund = 0n，hop 钱包不需要余额）
+        // 2. 传入了预充值好的 hop 钱包（hop 钱包已有余额支付 prefund）
         const hasPaymaster = this.aaManager.hasPaymaster();
-        const effectiveHopCount = hasPaymaster ? hopCount : 0;
-        if (hopCount > 0 && !hasPaymaster) {
-            console.warn('[AA DEX 批量换手] ⚠️ 无 Paymaster 模式不支持多跳（hop 钱包无法支付 prefund），已自动降级为直接分发模式');
-            console.warn('[AA DEX 批量换手] 💡 提示：配置 Paymaster 可启用多跳功能');
+        const hasPrefundedHops = Array.isArray(prefundedHopWallets) && prefundedHopWallets.length > 0;
+        const canDoMultiHop = hasPaymaster || hasPrefundedHops;
+        const effectiveHopCount = canDoMultiHop ? hopCount : 0;
+        if (hopCount > 0 && !canDoMultiHop) {
+            console.warn('[AA DEX 批量换手] ⚠️ 无法执行多跳（hop 钱包无法支付 prefund），已自动降级为直接分发模式');
+            console.warn('[AA DEX 批量换手] 💡 提示：使用 HopWalletManager.prefundHopWallets() 预充值 hop 钱包，或配置 Paymaster');
+        }
+        else if (hopCount > 0 && hasPrefundedHops) {
+            console.log('[AA DEX 批量换手] ✅ 预充值多跳模式已启用 (hopCount:', hopCount, ', prefundedHops:', prefundedHopWallets.length, ')');
         }
         else if (hopCount > 0 && hasPaymaster) {
             console.log('[AA DEX 批量换手] ✅ Paymaster 模式已启用，支持多跳换手 (hopCount:', hopCount, ')');
@@ -655,9 +662,13 @@ export class AADexSwapExecutor {
                 }
             }
             else {
-                // ⚠️ 多跳模式在 XLayer AA 下不可行（effectiveHopCount 已强制为 0）
-                // 以下代码保留但不会执行，仅供参考
-                console.log('[AA DEX 批量换手] 进入多跳模式 (effectiveHopCount > 0):', { effectiveHopCount, buyerCount: buyerSenders.length });
+                // ✅ 多跳模式：使用预充值的 hop 钱包或 Paymaster 模式
+                console.log('[AA DEX 批量换手] 进入多跳模式 (effectiveHopCount > 0):', {
+                    effectiveHopCount,
+                    buyerCount: buyerSenders.length,
+                    usePrefundedHops: hasPrefundedHops,
+                    usePaymaster: hasPaymaster,
+                });
                 const feeData = await this.aaManager.getFeeData();
                 const gasPrice = feeData.gasPrice ?? feeData.maxFeePerGas ?? 5000000000n;
                 // 预估 prefund 的函数（使用全局常量）
@@ -667,25 +678,59 @@ export class AADexSwapExecutor {
                     const totalGas = callGas + verifyGas + preVerifyGas;
                     return (totalGas * gasPrice * PREFUND_BUFFER_PERCENT) / 100n;
                 };
-                // ✅ 为每个买方生成独立的多跳链
-                // hopChains[buyerIdx] = [hop0, hop1, ..., hop(H-1)] 每条链有 hopCount 个 hop 钱包
+                // ✅ 构建 hop 钱包列表
+                // 如果有预充值的 hop 钱包，使用它们；否则生成新钱包（需要 Paymaster）
                 const allGeneratedHopWallets = [];
-                for (let buyerIdx = 0; buyerIdx < buyerSenders.length; buyerIdx++) {
-                    const chainHops = [];
-                    for (let h = 0; h < hopCount; h++) {
-                        const randomWallet = ethers.Wallet.createRandom();
-                        const wallet = new ethers.Wallet(randomWallet.privateKey);
-                        const sender = await this.aaManager.predictSenderAddress(wallet.address);
-                        const code = await provider.getCode(sender);
-                        const deployed = code !== null && code !== '0x';
-                        const initCode = deployed ? '0x' : this.aaManager.generateInitCode(wallet.address);
-                        chainHops.push({ wallet, sender, deployed, initCode });
-                        // 初始化 nonce
-                        nonceMap.init(sender, 0n);
+                if (hasPrefundedHops) {
+                    // ✅ 预充值模式：使用传入的 hop 钱包
+                    // 每个买方分配 effectiveHopCount 个 hop 钱包
+                    const totalHopsNeeded = buyerSenders.length * effectiveHopCount;
+                    if (prefundedHopWallets.length < totalHopsNeeded) {
+                        throw new Error(`预充值 hop 钱包数量不足: 需要 ${totalHopsNeeded} 个，实际 ${prefundedHopWallets.length} 个`);
+                    }
+                    // ✅ 关键修复：从链上获取所有 hop 钱包的真实 nonce（用户可能重复使用同一批 hop 钱包）
+                    const hopSenders = prefundedHopWallets.slice(0, totalHopsNeeded).map(h => h.senderAddress);
+                    const hopNonces = await this.aaManager.batchGetNonces(hopSenders);
+                    let hopIdx = 0;
+                    for (let buyerIdx = 0; buyerIdx < buyerSenders.length; buyerIdx++) {
+                        const chainHops = [];
+                        for (let h = 0; h < effectiveHopCount; h++) {
+                            const prefundedHop = prefundedHopWallets[hopIdx];
+                            const wallet = new ethers.Wallet(prefundedHop.privateKey, provider);
+                            chainHops.push({
+                                wallet,
+                                sender: prefundedHop.senderAddress,
+                                deployed: prefundedHop.deployed,
+                                initCode: prefundedHop.initCode,
+                            });
+                            // ✅ 使用从链上获取的真实 nonce（而非硬编码 0）
+                            const realNonce = hopNonces[hopIdx] ?? 0n;
+                            nonceMap.init(prefundedHop.senderAddress, realNonce);
+                            hopIdx++;
+                        }
+                        allGeneratedHopWallets.push(chainHops);
                     }
-                    allGeneratedHopWallets.push(chainHops);
+                    console.log(`[AA DEX 多跳] ✅ 使用预充值 hop 钱包: ${totalHopsNeeded} 个 (${buyerSenders.length} 条链 × ${effectiveHopCount} 跳)`);
+                }
+                else {
+                    // Paymaster 模式：生成新钱包（不需要预充值，prefund=0）
+                    for (let buyerIdx = 0; buyerIdx < buyerSenders.length; buyerIdx++) {
+                        const chainHops = [];
+                        for (let h = 0; h < effectiveHopCount; h++) {
+                            const randomWallet = ethers.Wallet.createRandom();
+                            const wallet = new ethers.Wallet(randomWallet.privateKey, provider);
+                            const sender = await this.aaManager.predictSenderAddress(wallet.address);
+                            const code = await provider.getCode(sender);
+                            const deployed = code !== null && code !== '0x';
+                            const initCode = deployed ? '0x' : this.aaManager.generateInitCode(wallet.address);
+                            chainHops.push({ wallet, sender, deployed, initCode });
+                            // 初始化 nonce
+                            nonceMap.init(sender, 0n);
+                        }
+                        allGeneratedHopWallets.push(chainHops);
+                    }
+                    console.log(`[AA DEX 多跳] 使用 Paymaster 模式生成 hop 钱包: ${buyerSenders.length * effectiveHopCount} 个`);
                 }
-                console.log(`[AA DEX 多跳] 总 hop 钱包数: ${buyerSenders.length * hopCount} (${buyerSenders.length} 条链 × ${hopCount} 跳)`);
                 // ✅ 利润刮取（只在第一笔 seller UserOp 中执行）
                 let profitHandled = false;
                 // ✅ 构建每条多跳链的 UserOps
@@ -696,16 +741,14 @@ export class AADexSwapExecutor {
                     const buyAmount = buyAmountsWei[buyerIdx] ?? 0n;
                     if (buyAmount <= 0n)
                         continue;
-                    // 计算这条链上所有 hop 的 prefund（使用常量）
-                    const hopPrefunds = chainHops.map((hop, idx) => {
-                        // 最后一个 hop 转账给 buyer，中间 hop 转账给下一个 hop
-                        return estimatePrefund(HOP_CALL_GAS_LIMIT, hop.deployed);
-                    });
-                    const totalHopPrefund = hopPrefunds.reduce((a, b) => a + b, 0n);
-                    // 计算 buyer 的 prefund（用于买入，使用常量）
+                    // ✅ 计算 buyer 的 prefund（用于买入，使用常量）
                     const buyerPrefund = estimatePrefund(DEX_BUY_CALL_GAS_LIMIT, buyerAi.deployed);
-                    // 这条链的总金额 = 买入金额 + 所有 hop prefund + buyer prefund
-                    const chainTotalAmount = buyAmount + totalHopPrefund + buyerPrefund;
+                    // ✅ 计算分发金额：
+                    // - 预充值模式：hop 已有 prefund，分发金额 = 买入金额 + buyer prefund
+                    // - Paymaster 模式：prefund = 0，分发金额 = 买入金额 + buyer prefund
+                    // 注意：无论哪种模式，都不需要在分发中包含 hop 的 prefund
+                    //（预充值模式下 hop 已有余额，Paymaster 模式下 prefund=0）
+                    const chainTotalAmount = buyAmount + buyerPrefund;
                     // 1) seller → hop0
                     const hop0 = chainHops[0];
                     let callData0;
@@ -744,13 +787,12 @@ export class AADexSwapExecutor {
                     });
                     outOps.push(signedSellerToHop0.userOp);
                     // 2) hop[j] → hop[j+1] (中间跳)
-                    let remainingPrefund = totalHopPrefund;
+                    // ✅ 预充值模式下，hop 钱包自己有 prefund，只需要传递买入金额 + buyer prefund
                     for (let j = 0; j < chainHops.length - 1; j++) {
                         const currentHop = chainHops[j];
                         const nextHop = chainHops[j + 1];
-                        // 当前 hop 扣除自己的 prefund 后转给下一个
-                        remainingPrefund -= hopPrefunds[j];
-                        const amountToTransfer = buyAmount + remainingPrefund + buyerPrefund;
+                        // 传递金额 = 买入金额 + buyer prefund（hop 自己的 gas 从预充值中支付）
+                        const amountToTransfer = buyAmount + buyerPrefund;
                         let callData;
                         if (useNativeToken) {
                             callData = encodeExecute(nextHop.sender, amountToTransfer, '0x');

package/dist/xlayer/hop-wallet-manager.d.ts

@@ -0,0 +1,143 @@
+/**
+ * XLayer AA 多跳钱包管理器
+ *
+ * 功能：
+ * 1. 生成临时 Hop 钱包（可导出私钥）
+ * 2. 预充值 Hop 钱包（支持取消）
+ * 3. 退回预充值资金（原路返回）
+ * 4. 状态回调（进度通知）
+ */
+import { Wallet } from 'ethers';
+import { AAAccountManager } from './aa-account.js';
+import { XLayerConfig } from './types.js';
+/** Hop 钱包信息 */
+export interface HopWalletInfo {
+    /** 钱包索引 */
+    index: number;
+    /** Owner 私钥（可导出） */
+    privateKey: string;
+    /** Owner 地址 */
+    ownerAddress: string;
+    /** AA Sender 地址 */
+    senderAddress: string;
+    /** 是否已部署 */
+    deployed: boolean;
+    /** initCode（未部署时需要） */
+    initCode: string;
+    /** 预充值金额（wei） */
+    prefundWei: bigint;
+    /** 预充值状态 */
+    prefundStatus: 'pending' | 'funded' | 'refunded' | 'failed';
+    /** 预充值交易哈希 */
+    prefundTxHash?: string;
+    /** 退款交易哈希 */
+    refundTxHash?: string;
+}
+/** 预充值进度回调 */
+export interface PrefundProgressCallback {
+    (progress: {
+        phase: 'generating' | 'prefunding' | 'confirming' | 'ready' | 'cancelled' | 'refunding' | 'refunded' | 'error';
+        current: number;
+        total: number;
+        message: string;
+        hopWallets?: HopWalletInfo[];
+        error?: Error;
+    }): void;
+}
+/** 预充值配置 */
+export interface PrefundConfig {
+    /** Hop 数量 */
+    hopCount: number;
+    /** 每个 Hop 的预估 gas 消耗 */
+    hopCallGasLimit?: bigint;
+    /** 预留缓冲百分比（默认 150%） */
+    bufferPercent?: bigint;
+    /** Payer 钱包 */
+    payerWallet: Wallet;
+    /** 进度回调 */
+    onProgress?: PrefundProgressCallback;
+    /** 取消信号 */
+    abortSignal?: AbortSignal;
+}
+/** 预充值结果 */
+export interface PrefundResult {
+    /** 是否成功 */
+    success: boolean;
+    /** Hop 钱包列表 */
+    hopWallets: HopWalletInfo[];
+    /** 总预充值金额（wei） */
+    totalPrefundWei: bigint;
+    /** 预充值交易哈希 */
+    prefundTxHash?: string;
+    /** 错误信息 */
+    error?: Error;
+    /** 是否被取消 */
+    cancelled?: boolean;
+}
+/** 退款结果 */
+export interface RefundResult {
+    /** 是否成功 */
+    success: boolean;
+    /** 退款总金额（wei） */
+    totalRefundWei: bigint;
+    /** 退款交易哈希列表 */
+    refundTxHashes: string[];
+    /** 各 Hop 退款详情 */
+    hopRefunds: {
+        hopIndex: number;
+        refundWei: bigint;
+        txHash?: string;
+        error?: string;
+    }[];
+    /** 错误信息 */
+    error?: Error;
+}
+export declare class HopWalletManager {
+    private aaManager;
+    private provider;
+    private config;
+    constructor(config?: XLayerConfig);
+    /**
+     * 生成 Hop 钱包列表
+     */
+    generateHopWallets(count: number): Promise<HopWalletInfo[]>;
+    /**
+     * 计算单个 Hop 需要的 prefund
+     */
+    calculateHopPrefund(deployed: boolean, callGasLimit?: bigint): Promise<bigint>;
+    /**
+     * 预充值 Hop 钱包
+     *
+     * 使用 Payer 发送一笔批量转账交易，给所有 Hop 钱包充值 prefund
+     */
+    prefundHopWallets(config: PrefundConfig): Promise<PrefundResult>;
+    /**
+     * 退回 Hop 钱包的预充值资金
+     *
+     * 将所有 Hop 钱包的余额转回给指定地址（通常是 Payer）
+     */
+    refundHopWallets(hopWallets: HopWalletInfo[], refundTo: string, onProgress?: PrefundProgressCallback): Promise<RefundResult>;
+    /**
+     * 使用 Payer 批量退回 Hop 钱包资金
+     *
+     * 通过 handleOps 批量执行所有 Hop 的退款操作
+     */
+    refundHopWalletsViaPayer(hopWallets: HopWalletInfo[], payerWallet: Wallet, refundTo: string, onProgress?: PrefundProgressCallback): Promise<RefundResult>;
+    /**
+     * 导出 Hop 钱包信息（用于备份）
+     */
+    exportHopWallets(hopWallets: HopWalletInfo[]): string;
+    /**
+     * 导入 Hop 钱包信息
+     */
+    importHopWallets(jsonStr: string): Promise<HopWalletInfo[]>;
+    /**
+     * 编码 execute 调用
+     */
+    private encodeExecute;
+    /**
+     * 获取 AAAccountManager
+     */
+    getAAManager(): AAAccountManager;
+}
+export declare function createHopWalletManager(config?: XLayerConfig): HopWalletManager;

package/dist/xlayer/hop-wallet-manager.js

@@ -0,0 +1,526 @@
+/**
+ * XLayer AA 多跳钱包管理器
+ *
+ * 功能：
+ * 1. 生成临时 Hop 钱包（可导出私钥）
+ * 2. 预充值 Hop 钱包（支持取消）
+ * 3. 退回预充值资金（原路返回）
+ * 4. 状态回调（进度通知）
+ */
+import { ethers, Wallet } from 'ethers';
+import { AAAccountManager } from './aa-account.js';
+import { VERIFICATION_GAS_LIMIT_DEPLOY, VERIFICATION_GAS_LIMIT_NORMAL, PRE_VERIFICATION_GAS, } from './constants.js';
+// ============================================================================
+// HopWalletManager
+// ============================================================================
+const DEFAULT_HOP_CALL_GAS_LIMIT = 150000n;
+const DEFAULT_BUFFER_PERCENT = 150n; // 1.5x
+export class HopWalletManager {
+    constructor(config = {}) {
+        this.config = config;
+        this.aaManager = new AAAccountManager(config);
+        this.provider = this.aaManager.getProvider();
+    }
+    /**
+     * 生成 Hop 钱包列表
+     */
+    async generateHopWallets(count) {
+        const hopWallets = [];
+        for (let i = 0; i < count; i++) {
+            const randomWallet = ethers.Wallet.createRandom();
+            const wallet = new Wallet(randomWallet.privateKey);
+            const ownerAddress = wallet.address;
+            const senderAddress = await this.aaManager.predictSenderAddress(ownerAddress);
+            const code = await this.provider.getCode(senderAddress);
+            const deployed = code !== null && code !== '0x';
+            const initCode = deployed ? '0x' : this.aaManager.generateInitCode(ownerAddress);
+            hopWallets.push({
+                index: i,
+                privateKey: randomWallet.privateKey,
+                ownerAddress,
+                senderAddress,
+                deployed,
+                initCode,
+                prefundWei: 0n,
+                prefundStatus: 'pending',
+            });
+        }
+        return hopWallets;
+    }
+    /**
+     * 计算单个 Hop 需要的 prefund
+     */
+    async calculateHopPrefund(deployed, callGasLimit) {
+        const feeData = await this.aaManager.getFeeData();
+        const gasPrice = feeData.gasPrice ?? feeData.maxFeePerGas ?? 5000000000n;
+        const callGas = callGasLimit ?? DEFAULT_HOP_CALL_GAS_LIMIT;
+        const verifyGas = deployed ? VERIFICATION_GAS_LIMIT_NORMAL : VERIFICATION_GAS_LIMIT_DEPLOY;
+        const preVerifyGas = PRE_VERIFICATION_GAS;
+        const totalGas = callGas + verifyGas + preVerifyGas;
+        return (totalGas * gasPrice * DEFAULT_BUFFER_PERCENT) / 100n;
+    }
+    /**
+     * 预充值 Hop 钱包
+     *
+     * 使用 Payer 发送一笔批量转账交易，给所有 Hop 钱包充值 prefund
+     */
+    async prefundHopWallets(config) {
+        const { hopCount, hopCallGasLimit, bufferPercent, payerWallet, onProgress, abortSignal } = config;
+        // 检查取消信号
+        const checkAbort = () => {
+            if (abortSignal?.aborted) {
+                throw new Error('PREFUND_CANCELLED');
+            }
+        };
+        try {
+            // 1. 生成 Hop 钱包
+            onProgress?.({
+                phase: 'generating',
+                current: 0,
+                total: hopCount,
+                message: `正在生成 ${hopCount} 个 Hop 钱包...`,
+            });
+            checkAbort();
+            const hopWallets = await this.generateHopWallets(hopCount);
+            onProgress?.({
+                phase: 'generating',
+                current: hopCount,
+                total: hopCount,
+                message: `已生成 ${hopCount} 个 Hop 钱包`,
+                hopWallets,
+            });
+            // 2. 计算每个 Hop 需要的 prefund
+            checkAbort();
+            const feeData = await this.aaManager.getFeeData();
+            const gasPrice = feeData.gasPrice ?? feeData.maxFeePerGas ?? 5000000000n;
+            const effectiveBufferPercent = bufferPercent ?? DEFAULT_BUFFER_PERCENT;
+            for (const hop of hopWallets) {
+                const callGas = hopCallGasLimit ?? DEFAULT_HOP_CALL_GAS_LIMIT;
+                const verifyGas = hop.deployed ? VERIFICATION_GAS_LIMIT_NORMAL : VERIFICATION_GAS_LIMIT_DEPLOY;
+                const preVerifyGas = PRE_VERIFICATION_GAS;
+                const totalGas = callGas + verifyGas + preVerifyGas;
+                hop.prefundWei = (totalGas * gasPrice * effectiveBufferPercent) / 100n;
+            }
+            const totalPrefundWei = hopWallets.reduce((sum, h) => sum + h.prefundWei, 0n);
+            // 3. 检查 Payer 余额
+            const payerAddress = payerWallet.address;
+            const payerBalance = await this.provider.getBalance(payerAddress);
+            const estimatedGas = 21000n * BigInt(hopCount) + 50000n; // 预估 gas
+            const totalNeeded = totalPrefundWei + estimatedGas * gasPrice;
+            if (payerBalance < totalNeeded) {
+                throw new Error(`Payer 余额不足: 需要 ${ethers.formatEther(totalNeeded)} OKB, 当前 ${ethers.formatEther(payerBalance)} OKB`);
+            }
+            // 4. 发送预充值交易
+            onProgress?.({
+                phase: 'prefunding',
+                current: 0,
+                total: hopCount,
+                message: `正在发送预充值交易...`,
+                hopWallets,
+            });
+            checkAbort();
+            // 使用批量转账（逐笔发送，XLayer 不支持 Bundle）
+            const connectedPayer = payerWallet.connect(this.provider);
+            const nonce = await this.provider.getTransactionCount(payerAddress, 'pending');
+            const txHashes = [];
+            for (let i = 0; i < hopWallets.length; i++) {
+                checkAbort();
+                const hop = hopWallets[i];
+                const tx = await connectedPayer.sendTransaction({
+                    to: hop.senderAddress,
+                    value: hop.prefundWei,
+                    nonce: nonce + i,
+                    gasPrice,
+                    gasLimit: 21055n,
+                });
+                hop.prefundTxHash = tx.hash;
+                txHashes.push(tx.hash);
+                onProgress?.({
+                    phase: 'prefunding',
+                    current: i + 1,
+                    total: hopCount,
+                    message: `已发送 ${i + 1}/${hopCount} 笔预充值交易`,
+                    hopWallets,
+                });
+            }
+            // 5. 等待所有交易确认
+            onProgress?.({
+                phase: 'confirming',
+                current: 0,
+                total: hopCount,
+                message: `正在等待交易确认...`,
+                hopWallets,
+            });
+            for (let i = 0; i < txHashes.length; i++) {
+                checkAbort();
+                const receipt = await this.provider.waitForTransaction(txHashes[i], 1, 60000);
+                if (receipt?.status === 1) {
+                    hopWallets[i].prefundStatus = 'funded';
+                }
+                else {
+                    hopWallets[i].prefundStatus = 'failed';
+                }
+                onProgress?.({
+                    phase: 'confirming',
+                    current: i + 1,
+                    total: hopCount,
+                    message: `已确认 ${i + 1}/${hopCount} 笔交易`,
+                    hopWallets,
+                });
+            }
+            // 检查是否全部成功
+            const allFunded = hopWallets.every(h => h.prefundStatus === 'funded');
+            if (!allFunded) {
+                const failedCount = hopWallets.filter(h => h.prefundStatus === 'failed').length;
+                throw new Error(`${failedCount} 笔预充值交易失败`);
+            }
+            onProgress?.({
+                phase: 'ready',
+                current: hopCount,
+                total: hopCount,
+                message: `✅ 预充值完成，共 ${ethers.formatEther(totalPrefundWei)} OKB`,
+                hopWallets,
+            });
+            return {
+                success: true,
+                hopWallets,
+                totalPrefundWei,
+                prefundTxHash: txHashes[0],
+            };
+        }
+        catch (error) {
+            const err = error;
+            if (err.message === 'PREFUND_CANCELLED') {
+                onProgress?.({
+                    phase: 'cancelled',
+                    current: 0,
+                    total: hopCount,
+                    message: '预充值已取消',
+                });
+                return {
+                    success: false,
+                    hopWallets: [],
+                    totalPrefundWei: 0n,
+                    cancelled: true,
+                };
+            }
+            onProgress?.({
+                phase: 'error',
+                current: 0,
+                total: hopCount,
+                message: `预充值失败: ${err.message}`,
+                error: err,
+            });
+            return {
+                success: false,
+                hopWallets: [],
+                totalPrefundWei: 0n,
+                error: err,
+            };
+        }
+    }
+    /**
+     * 退回 Hop 钱包的预充值资金
+     *
+     * 将所有 Hop 钱包的余额转回给指定地址（通常是 Payer）
+     */
+    async refundHopWallets(hopWallets, refundTo, onProgress) {
+        const hopRefunds = [];
+        const refundTxHashes = [];
+        let totalRefundWei = 0n;
+        onProgress?.({
+            phase: 'refunding',
+            current: 0,
+            total: hopWallets.length,
+            message: `正在退回 ${hopWallets.length} 个 Hop 钱包的资金...`,
+            hopWallets,
+        });
+        const feeData = await this.aaManager.getFeeData();
+        const gasPrice = feeData.gasPrice ?? feeData.maxFeePerGas ?? 5000000000n;
+        const gasLimit = 21055n;
+        const gasCost = gasLimit * gasPrice;
+        for (let i = 0; i < hopWallets.length; i++) {
+            const hop = hopWallets[i];
+            try {
+                // 检查 Hop sender 余额
+                const balance = await this.provider.getBalance(hop.senderAddress);
+                if (balance <= gasCost) {
+                    // 余额不足以支付 gas，跳过
+                    hopRefunds.push({
+                        hopIndex: hop.index,
+                        refundWei: 0n,
+                        error: '余额不足以支付 gas',
+                    });
+                    continue;
+                }
+                const refundAmount = balance - gasCost;
+                // 使用 AA 账户转账（通过 UserOp）
+                const hopWallet = new Wallet(hop.privateKey, this.provider);
+                // 构建简单的 native 转账 UserOp
+                const { userOp } = await this.aaManager.buildUserOpWithFixedGas({
+                    ownerWallet: hopWallet,
+                    sender: hop.senderAddress,
+                    nonce: 0n,
+                    initCode: hop.initCode,
+                    callData: this.encodeExecute(refundTo, refundAmount, '0x'),
+                    deployed: hop.deployed,
+                });
+                // 签名（buildUserOpWithFixedGas 不签名，需要手动签名）
+                const signedOp = await this.aaManager.signUserOp(userOp, hopWallet);
+                // 发送 handleOps
+                const entryPoint = this.aaManager.getEntryPoint();
+                const connectedEntryPoint = entryPoint.connect(new Wallet(hop.privateKey, this.provider));
+                // 由于 Hop 没有足够的 gas 发送 handleOps，需要用 Payer 来发送
+                // 这里我们返回 UserOp，让调用者处理
+                hopRefunds.push({
+                    hopIndex: hop.index,
+                    refundWei: refundAmount,
+                    error: '需要外部 Payer 发送 handleOps（Hop 余额仅够 prefund）',
+                });
+                totalRefundWei += refundAmount;
+            }
+            catch (error) {
+                hopRefunds.push({
+                    hopIndex: hop.index,
+                    refundWei: 0n,
+                    error: error.message,
+                });
+            }
+            onProgress?.({
+                phase: 'refunding',
+                current: i + 1,
+                total: hopWallets.length,
+                message: `已处理 ${i + 1}/${hopWallets.length} 个 Hop 钱包`,
+                hopWallets,
+            });
+        }
+        onProgress?.({
+            phase: 'refunded',
+            current: hopWallets.length,
+            total: hopWallets.length,
+            message: `退款完成，共 ${ethers.formatEther(totalRefundWei)} OKB`,
+            hopWallets,
+        });
+        return {
+            success: true,
+            totalRefundWei,
+            refundTxHashes,
+            hopRefunds,
+        };
+    }
+    /**
+     * 使用 Payer 批量退回 Hop 钱包资金
+     *
+     * 通过 handleOps 批量执行所有 Hop 的退款操作
+     */
+    async refundHopWalletsViaPayer(hopWallets, payerWallet, refundTo, onProgress) {
+        const hopRefunds = [];
+        const refundTxHashes = [];
+        let totalRefundWei = 0n;
+        onProgress?.({
+            phase: 'refunding',
+            current: 0,
+            total: hopWallets.length,
+            message: `正在构建退款 UserOps...`,
+            hopWallets,
+        });
+        const feeData = await this.aaManager.getFeeData();
+        const gasPrice = feeData.gasPrice ?? feeData.maxFeePerGas ?? 5000000000n;
+        // 构建所有退款 UserOps
+        const userOps = [];
+        const hopWalletsToRefund = [];
+        // ✅ 关键修复：从链上批量获取所有 hop 钱包的真实 nonce
+        const hopSenders = hopWallets.map(h => h.senderAddress);
+        const hopNonces = await this.aaManager.batchGetNonces(hopSenders);
+        for (let i = 0; i < hopWallets.length; i++) {
+            const hop = hopWallets[i];
+            try {
+                const balance = await this.provider.getBalance(hop.senderAddress);
+                // 估算 UserOp 执行需要的 gas
+                const estimatedGas = 150000n * gasPrice;
+                if (balance <= estimatedGas) {
+                    hopRefunds.push({
+                        hopIndex: hop.index,
+                        refundWei: 0n,
+                        error: '余额不足',
+                    });
+                    continue;
+                }
+                const refundAmount = balance - estimatedGas;
+                // 构建 UserOp
+                const hopWallet = new Wallet(hop.privateKey, this.provider);
+                // ✅ 使用从链上获取的真实 nonce
+                const realNonce = hopNonces[i] ?? 0n;
+                // ✅ 检查 hop 钱包是否已部署（根据 nonce 判断，nonce > 0 说明已用过，肯定已部署）
+                const isDeployed = realNonce > 0n || hop.deployed;
+                const initCode = isDeployed ? '0x' : hop.initCode;
+                const { userOp } = await this.aaManager.buildUserOpWithFixedGas({
+                    ownerWallet: hopWallet,
+                    sender: hop.senderAddress,
+                    nonce: realNonce,
+                    initCode,
+                    callData: this.encodeExecute(refundTo, refundAmount, '0x'),
+                    deployed: isDeployed,
+                });
+                // 签名
+                const signedOp = await this.aaManager.signUserOp(userOp, hopWallet);
+                userOps.push(signedOp.userOp);
+                hopWalletsToRefund.push(hop);
+                totalRefundWei += refundAmount;
+                hopRefunds.push({
+                    hopIndex: hop.index,
+                    refundWei: refundAmount,
+                });
+            }
+            catch (error) {
+                hopRefunds.push({
+                    hopIndex: hop.index,
+                    refundWei: 0n,
+                    error: error.message,
+                });
+            }
+        }
+        if (userOps.length === 0) {
+            onProgress?.({
+                phase: 'refunded',
+                current: hopWallets.length,
+                total: hopWallets.length,
+                message: '没有可退款的 Hop 钱包',
+                hopWallets,
+            });
+            return {
+                success: true,
+                totalRefundWei: 0n,
+                refundTxHashes: [],
+                hopRefunds,
+            };
+        }
+        onProgress?.({
+            phase: 'refunding',
+            current: 0,
+            total: userOps.length,
+            message: `正在发送 handleOps 退款交易 (${userOps.length} 个 UserOps)...`,
+            hopWallets,
+        });
+        // 发送 handleOps
+        try {
+            const connectedPayer = payerWallet.connect(this.provider);
+            const entryPoint = this.aaManager.getEntryPoint();
+            const entryPointWithSigner = entryPoint.connect(connectedPayer);
+            const tx = await entryPointWithSigner.handleOps(userOps, payerWallet.address, {
+                gasPrice,
+                gasLimit: 500000n * BigInt(userOps.length),
+            });
+            refundTxHashes.push(tx.hash);
+            onProgress?.({
+                phase: 'confirming',
+                current: 0,
+                total: 1,
+                message: `等待 handleOps 交易确认...`,
+                hopWallets,
+            });
+            const receipt = await tx.wait();
+            if (receipt?.status === 1) {
+                for (const hop of hopWalletsToRefund) {
+                    hop.prefundStatus = 'refunded';
+                    hop.refundTxHash = tx.hash;
+                }
+                onProgress?.({
+                    phase: 'refunded',
+                    current: hopWallets.length,
+                    total: hopWallets.length,
+                    message: `✅ 退款完成，共 ${ethers.formatEther(totalRefundWei)} OKB`,
+                    hopWallets,
+                });
+                return {
+                    success: true,
+                    totalRefundWei,
+                    refundTxHashes,
+                    hopRefunds,
+                };
+            }
+            else {
+                throw new Error('handleOps 交易失败');
+            }
+        }
+        catch (error) {
+            onProgress?.({
+                phase: 'error',
+                current: 0,
+                total: hopWallets.length,
+                message: `退款失败: ${error.message}`,
+                error: error,
+                hopWallets,
+            });
+            return {
+                success: false,
+                totalRefundWei: 0n,
+                refundTxHashes,
+                hopRefunds,
+                error: error,
+            };
+        }
+    }
+    /**
+     * 导出 Hop 钱包信息（用于备份）
+     */
+    exportHopWallets(hopWallets) {
+        const exportData = hopWallets.map(h => ({
+            index: h.index,
+            privateKey: h.privateKey,
+            ownerAddress: h.ownerAddress,
+            senderAddress: h.senderAddress,
+            prefundWei: h.prefundWei.toString(),
+            prefundStatus: h.prefundStatus,
+            prefundTxHash: h.prefundTxHash,
+        }));
+        return JSON.stringify(exportData, null, 2);
+    }
+    /**
+     * 导入 Hop 钱包信息
+     */
+    async importHopWallets(jsonStr) {
+        const data = JSON.parse(jsonStr);
+        const hopWallets = [];
+        for (const item of data) {
+            const wallet = new Wallet(item.privateKey);
+            const senderAddress = await this.aaManager.predictSenderAddress(wallet.address);
+            const code = await this.provider.getCode(senderAddress);
+            const deployed = code !== null && code !== '0x';
+            const initCode = deployed ? '0x' : this.aaManager.generateInitCode(wallet.address);
+            hopWallets.push({
+                index: item.index,
+                privateKey: item.privateKey,
+                ownerAddress: item.ownerAddress,
+                senderAddress,
+                deployed,
+                initCode,
+                prefundWei: BigInt(item.prefundWei || '0'),
+                prefundStatus: item.prefundStatus || 'pending',
+                prefundTxHash: item.prefundTxHash,
+            });
+        }
+        return hopWallets;
+    }
+    /**
+     * 编码 execute 调用
+     */
+    encodeExecute(to, value, data) {
+        const iface = new ethers.Interface([
+            'function execute(address dest, uint256 value, bytes func) external',
+        ]);
+        return iface.encodeFunctionData('execute', [to, value, data]);
+    }
+    /**
+     * 获取 AAAccountManager
+     */
+    getAAManager() {
+        return this.aaManager;
+    }
+}
+// ============================================================================
+// 工厂函数
+// ============================================================================
+export function createHopWalletManager(config = {}) {
+    return new HopWalletManager(config);
+}

package/dist/xlayer/index.d.ts

@@ -66,6 +66,7 @@ export { BundleExecutor, createBundleExecutor, bundleBuy, bundleSell, bundleBuyS
 export { DexBundleExecutor, createDexBundleExecutor, dexBundleBuySell, type DexBundleConfig, type DexBundleBuySellParams, } from './dex-bundle.js';
 export { AAPortalSwapExecutor, } from './portal-bundle-swap.js';
 export { AADexSwapExecutor, } from './dex-bundle-swap.js';
+export { HopWalletManager, createHopWalletManager, type HopWalletInfo, type PrefundProgressCallback, type PrefundConfig, type PrefundResult, type RefundResult, } from './hop-wallet-manager.js';
 export { AAPortalBuyFirstExecutor, createAAPortalBuyFirstExecutor, } from './portal-buy-first.js';
 export { AADexBuyFirstExecutor, createAADexBuyFirstExecutor, } from './dex-buy-first.js';
 export { BuyFirstVolumeExecutor, createBuyFirstVolumeExecutor, makeBuyFirstVolume, } from './buy-first-volume.js';

package/dist/xlayer/index.js

@@ -94,6 +94,10 @@ export { DexBundleExecutor, createDexBundleExecutor, dexBundleBuySell, } from '.
 export { AAPortalSwapExecutor, } from './portal-bundle-swap.js';
 export { AADexSwapExecutor, } from './dex-bundle-swap.js';
 // ============================================================================
+// Hop 钱包管理器（多跳预充值）
+// ============================================================================
+export { HopWalletManager, createHopWalletManager, } from './hop-wallet-manager.js';
+// ============================================================================
 // AA Buy-First（刷量专用）
 // ============================================================================
 export { AAPortalBuyFirstExecutor, createAAPortalBuyFirstExecutor, } from './portal-buy-first.js';

package/dist/xlayer/portal-bundle-swap.js

@@ -277,7 +277,8 @@ export class AAPortalSwapExecutor {
      */
     async bundleBatchSwapSign(params) {
         const { tokenAddress, sellerPrivateKey, buyerPrivateKeys, buyAmountsOkb, sellAmount, sellPercent = 100, capitalMode = true, // ✅ 默认资金利用率模式（卖出→分发→买入）
-        disperseHopCount: disperseHopCountIn, payerPrivateKey, beneficiary: beneficiaryIn, payerStartNonce, routeAddress, skipApprovalCheck = false, quoteToken, quoteTokenDecimals = 6, } = params;
+        disperseHopCount: disperseHopCountIn, payerPrivateKey, beneficiary: beneficiaryIn, payerStartNonce, routeAddress, skipApprovalCheck = false, quoteToken, quoteTokenDecimals = 6, prefundedHopWallets, // ✅ 预充值多跳：已预充值的 hop 钱包列表
+         } = params;
         const effectiveConfig = { ...(this.config ?? {}), ...(params.config ?? {}) };
         const { extractProfit, profitBps, profitRecipient } = resolveProfitSettings(effectiveConfig);
         // ✅ ERC20 稳定币支持
@@ -390,17 +391,23 @@ export class AAPortalSwapExecutor {
             extractProfit,
             profitWei: ethers.formatEther(profitWei),
         });
-        // ✅ 多跳模式与 Paymaster 的关系：
+        // ✅ 多跳模式判断：
         // ERC-4337 的 handleOps 执行流程是"先验证所有 UserOps，再执行所有 UserOps"
         // hop 钱包是临时生成的（余额=0），在 validation 阶段无法支付 prefund，会导致 AA21 错误
         // 
-        // 但是！如果配置了 Paymaster，prefund = 0n，hop 钱包不需要余额即可通过验证
-        // 因此：只有在 **没有 Paymaster** 时才需要强制禁用多跳
+        // 多跳可用的条件：
+        // 1. 配置了 Paymaster（prefund = 0n，hop 钱包不需要余额）
+        // 2. 传入了预充值好的 hop 钱包（hop 钱包已有余额支付 prefund）
         const hasPaymaster = this.aaManager.hasPaymaster();
-        const effectiveHopCount = hasPaymaster ? hopCount : 0;
-        if (hopCount > 0 && !hasPaymaster) {
-            console.warn('[AA Portal 批量换手] ⚠️ 无 Paymaster 模式不支持多跳（hop 钱包无法支付 prefund），已自动降级为直接分发模式');
-            console.warn('[AA Portal 批量换手] 💡 提示：配置 Paymaster 可启用多跳功能');
+        const hasPrefundedHops = Array.isArray(prefundedHopWallets) && prefundedHopWallets.length > 0;
+        const canDoMultiHop = hasPaymaster || hasPrefundedHops;
+        const effectiveHopCount = canDoMultiHop ? hopCount : 0;
+        if (hopCount > 0 && !canDoMultiHop) {
+            console.warn('[AA Portal 批量换手] ⚠️ 无法执行多跳（hop 钱包无法支付 prefund），已自动降级为直接分发模式');
+            console.warn('[AA Portal 批量换手] 💡 提示：使用 HopWalletManager.prefundHopWallets() 预充值 hop 钱包，或配置 Paymaster');
+        }
+        else if (hopCount > 0 && hasPrefundedHops) {
+            console.log('[AA Portal 批量换手] ✅ 预充值多跳模式已启用 (hopCount:', hopCount, ', prefundedHops:', prefundedHopWallets.length, ')');
         }
         else if (hopCount > 0 && hasPaymaster) {
             console.log('[AA Portal 批量换手] ✅ Paymaster 模式已启用，支持多跳换手 (hopCount:', hopCount, ')');
@@ -462,9 +469,13 @@ export class AAPortalSwapExecutor {
                 }
             }
             else {
-                // ⚠️ 多跳模式在 XLayer AA 下不可行（effectiveHopCount 已强制为 0）
-                // 以下代码保留但不会执行，仅供参考
-                console.log('[AA Portal 批量换手] 进入多跳模式 (effectiveHopCount > 0):', { effectiveHopCount, buyerCount: buyerSenders.length });
+                // ✅ 多跳模式：使用预充值的 hop 钱包或 Paymaster 模式
+                console.log('[AA Portal 批量换手] 进入多跳模式 (effectiveHopCount > 0):', {
+                    effectiveHopCount,
+                    buyerCount: buyerSenders.length,
+                    usePrefundedHops: hasPrefundedHops,
+                    usePaymaster: hasPaymaster,
+                });
                 const feeData = await this.aaManager.getFeeData();
                 const gasPrice = feeData.gasPrice ?? feeData.maxFeePerGas ?? 5000000000n;
                 const provider = this.aaManager.getProvider();
@@ -475,25 +486,57 @@ export class AAPortalSwapExecutor {
                     const totalGas = callGas + verifyGas + preVerifyGas;
                     return (totalGas * gasPrice * PREFUND_BUFFER_PERCENT) / 100n;
                 };
-                // ✅ 为每个买方生成独立的多跳链
-                // hopChains[buyerIdx] = [hop0, hop1, ..., hop(H-1)] 每条链有 hopCount 个 hop 钱包
+                // ✅ 构建 hop 钱包列表
+                // 如果有预充值的 hop 钱包，使用它们；否则生成新钱包（需要 Paymaster）
                 const allGeneratedHopWallets = [];
-                for (let buyerIdx = 0; buyerIdx < buyerSenders.length; buyerIdx++) {
-                    const chainHops = [];
-                    for (let h = 0; h < hopCount; h++) {
-                        const randomWallet = ethers.Wallet.createRandom();
-                        const wallet = new ethers.Wallet(randomWallet.privateKey);
-                        const sender = await this.aaManager.predictSenderAddress(wallet.address);
-                        const code = await provider.getCode(sender);
-                        const deployed = code !== null && code !== '0x';
-                        const initCode = deployed ? '0x' : this.aaManager.generateInitCode(wallet.address);
-                        chainHops.push({ wallet, sender, deployed, initCode });
-                        // 初始化 nonce
-                        nonceMap.init(sender, 0n);
+                if (hasPrefundedHops) {
+                    // ✅ 预充值模式：使用传入的 hop 钱包
+                    const totalHopsNeeded = buyerSenders.length * effectiveHopCount;
+                    if (prefundedHopWallets.length < totalHopsNeeded) {
+                        throw new Error(`预充值 hop 钱包数量不足: 需要 ${totalHopsNeeded} 个，实际 ${prefundedHopWallets.length} 个`);
+                    }
+                    // ✅ 关键修复：从链上获取所有 hop 钱包的真实 nonce（用户可能重复使用同一批 hop 钱包）
+                    const hopSenders = prefundedHopWallets.slice(0, totalHopsNeeded).map(h => h.senderAddress);
+                    const hopNonces = await this.aaManager.batchGetNonces(hopSenders);
+                    let hopIdx = 0;
+                    for (let buyerIdx = 0; buyerIdx < buyerSenders.length; buyerIdx++) {
+                        const chainHops = [];
+                        for (let h = 0; h < effectiveHopCount; h++) {
+                            const prefundedHop = prefundedHopWallets[hopIdx];
+                            const wallet = new ethers.Wallet(prefundedHop.privateKey, provider);
+                            chainHops.push({
+                                wallet,
+                                sender: prefundedHop.senderAddress,
+                                deployed: prefundedHop.deployed,
+                                initCode: prefundedHop.initCode,
+                            });
+                            // ✅ 使用从链上获取的真实 nonce（而非硬编码 0）
+                            const realNonce = hopNonces[hopIdx] ?? 0n;
+                            nonceMap.init(prefundedHop.senderAddress, realNonce);
+                            hopIdx++;
+                        }
+                        allGeneratedHopWallets.push(chainHops);
+                    }
+                    console.log(`[AA Portal 多跳] ✅ 使用预充值 hop 钱包: ${totalHopsNeeded} 个`);
+                }
+                else {
+                    // Paymaster 模式：生成新钱包
+                    for (let buyerIdx = 0; buyerIdx < buyerSenders.length; buyerIdx++) {
+                        const chainHops = [];
+                        for (let h = 0; h < effectiveHopCount; h++) {
+                            const randomWallet = ethers.Wallet.createRandom();
+                            const wallet = new ethers.Wallet(randomWallet.privateKey, provider);
+                            const sender = await this.aaManager.predictSenderAddress(wallet.address);
+                            const code = await provider.getCode(sender);
+                            const deployed = code !== null && code !== '0x';
+                            const initCode = deployed ? '0x' : this.aaManager.generateInitCode(wallet.address);
+                            chainHops.push({ wallet, sender, deployed, initCode });
+                            nonceMap.init(sender, 0n);
+                        }
+                        allGeneratedHopWallets.push(chainHops);
                     }
-                    allGeneratedHopWallets.push(chainHops);
+                    console.log(`[AA Portal 多跳] 使用 Paymaster 模式生成 hop 钱包`);
                 }
-                console.log(`[AA 多跳] 总 hop 钱包数: ${buyerSenders.length * hopCount} (${buyerSenders.length} 条链 × ${hopCount} 跳)`);
                 // ✅ 利润刮取（只在第一笔 seller UserOp 中执行）
                 let profitHandled = false;
                 // ✅ 构建每条多跳链的 UserOps

package/dist/xlayer/types.d.ts

@@ -552,6 +552,24 @@ export interface BundleBatchSwapSignParams extends BundleBatchSwapParams {
     payerStartNonce?: number;
     handleOpsGasLimit?: bigint;
     routeAddress?: string;
+    /**
+     * ✅ 预充值多跳：传入已预充值好的 Hop 钱包列表
+     *
+     * 如果提供此参数，将使用这些 hop 钱包进行多跳转账，
+     * 而不是自动生成新钱包（需要 Paymaster 才能工作的模式）
+     *
+     * 使用流程：
+     * 1. 调用 HopWalletManager.prefundHopWallets() 预充值
+     * 2. 将返回的 hopWallets 传入此参数
+     * 3. 多跳将使用这些已有余额的 hop 钱包
+     */
+    prefundedHopWallets?: Array<{
+        privateKey: string;
+        ownerAddress: string;
+        senderAddress: string;
+        deployed: boolean;
+        initCode: string;
+    }>;
 }
 export interface BundleBatchSwapSignResult {
     signedTransactions: string[];

package/package.json

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

package/dist/flap/portal-bundle-merkle/encryption.d.ts

@@ -1,16 +0,0 @@
-/**
- * ECDH + AES-GCM 加密工具（浏览器兼容）
- * 用于将签名交易用服务器公钥加密
- */
-/**
- * 用服务器公钥加密签名交易（ECDH + AES-GCM）
- *
- * @param signedTransactions 签名后的交易数组
- * @param publicKeyBase64 服务器提供的公钥（Base64 格式）
- * @returns JSON 字符串 {e: 临时公钥, i: IV, d: 密文}
- */
-export declare function encryptWithPublicKey(signedTransactions: string[], publicKeyBase64: string): Promise<string>;
-/**
- * 验证公钥格式（Base64）
- */
-export declare function validatePublicKey(publicKeyBase64: string): boolean;

package/dist/flap/portal-bundle-merkle/encryption.js

@@ -1,146 +0,0 @@
-/**
- * ECDH + AES-GCM 加密工具（浏览器兼容）
- * 用于将签名交易用服务器公钥加密
- */
-/**
- * 获取全局 crypto 对象（最简单直接的方式）
- */
-function getCryptoAPI() {
-    // 尝试所有可能的全局对象，优先浏览器环境
-    const cryptoObj = (typeof window !== 'undefined' && window.crypto) ||
-        (typeof self !== 'undefined' && self.crypto) ||
-        (typeof global !== 'undefined' && global.crypto) ||
-        (typeof globalThis !== 'undefined' && globalThis.crypto);
-    if (!cryptoObj) {
-        const env = typeof window !== 'undefined' ? 'Browser' : 'Node.js';
-        const protocol = typeof location !== 'undefined' ? location.protocol : 'unknown';
-        throw new Error(`❌ Crypto API 不可用。环境: ${env}, 协议: ${protocol}. ` +
-            '请确保在 HTTPS 或 localhost 下运行');
-    }
-    return cryptoObj;
-}
-/**
- * 获取 SubtleCrypto（用于加密操作）
- */
-function getSubtleCrypto() {
-    const crypto = getCryptoAPI();
-    if (!crypto.subtle) {
-        const protocol = typeof location !== 'undefined' ? location.protocol : 'unknown';
-        const hostname = typeof location !== 'undefined' ? location.hostname : 'unknown';
-        throw new Error(`❌ SubtleCrypto API 不可用。协议: ${protocol}, 主机: ${hostname}. ` +
-            '请确保：1) 使用 HTTPS (或 localhost)；2) 浏览器支持 Web Crypto API；' +
-            '3) 不在无痕/隐私浏览模式下');
-    }
-    return crypto.subtle;
-}
-/**
- * Base64 转 ArrayBuffer（优先使用浏览器 API）
- */
-function base64ToArrayBuffer(base64) {
-    // 浏览器环境（优先）
-    if (typeof atob !== 'undefined') {
-        const binaryString = atob(base64);
-        const bytes = new Uint8Array(binaryString.length);
-        for (let i = 0; i < binaryString.length; i++) {
-            bytes[i] = binaryString.charCodeAt(i);
-        }
-        return bytes.buffer;
-    }
-    // Node.js 环境（fallback）
-    if (typeof Buffer !== 'undefined') {
-        return Buffer.from(base64, 'base64').buffer;
-    }
-    throw new Error('❌ Base64 解码不可用');
-}
-/**
- * ArrayBuffer 转 Base64（优先使用浏览器 API）
- */
-function arrayBufferToBase64(buffer) {
-    // 浏览器环境（优先）
-    if (typeof btoa !== 'undefined') {
-        const bytes = new Uint8Array(buffer);
-        let binary = '';
-        for (let i = 0; i < bytes.length; i++) {
-            binary += String.fromCharCode(bytes[i]);
-        }
-        return btoa(binary);
-    }
-    // Node.js 环境（fallback）
-    if (typeof Buffer !== 'undefined') {
-        return Buffer.from(buffer).toString('base64');
-    }
-    throw new Error('❌ Base64 编码不可用');
-}
-/**
- * 生成随机 Hex 字符串
- */
-function randomHex(length) {
-    const crypto = getCryptoAPI();
-    const array = new Uint8Array(length);
-    crypto.getRandomValues(array);
-    return Array.from(array)
-        .map(b => b.toString(16).padStart(2, '0'))
-        .join('');
-}
-/**
- * 用服务器公钥加密签名交易（ECDH + AES-GCM）
- *
- * @param signedTransactions 签名后的交易数组
- * @param publicKeyBase64 服务器提供的公钥（Base64 格式）
- * @returns JSON 字符串 {e: 临时公钥, i: IV, d: 密文}
- */
-export async function encryptWithPublicKey(signedTransactions, publicKeyBase64) {
-    try {
-        // 0. 获取 SubtleCrypto 和 Crypto API
-        const subtle = getSubtleCrypto();
-        const crypto = getCryptoAPI();
-        // 1. 准备数据
-        const payload = {
-            signedTransactions,
-            timestamp: Date.now(),
-            nonce: randomHex(8)
-        };
-        const plaintext = JSON.stringify(payload);
-        // 2. 生成临时 ECDH 密钥对
-        const ephemeralKeyPair = await subtle.generateKey({ name: 'ECDH', namedCurve: 'P-256' }, true, ['deriveKey']);
-        // 3. 导入服务器公钥
-        const publicKeyBuffer = base64ToArrayBuffer(publicKeyBase64);
-        const publicKey = await subtle.importKey('raw', publicKeyBuffer, { name: 'ECDH', namedCurve: 'P-256' }, false, []);
-        // 4. 派生共享密钥（AES-256）
-        const sharedKey = await subtle.deriveKey({ name: 'ECDH', public: publicKey }, ephemeralKeyPair.privateKey, { name: 'AES-GCM', length: 256 }, false, ['encrypt']);
-        // 5. AES-GCM 加密
-        const iv = crypto.getRandomValues(new Uint8Array(12));
-        const encrypted = await subtle.encrypt({ name: 'AES-GCM', iv }, sharedKey, new TextEncoder().encode(plaintext));
-        // 6. 导出临时公钥
-        const ephemeralPublicKeyRaw = await subtle.exportKey('raw', ephemeralKeyPair.publicKey);
-        // 7. 返回加密包（JSON 格式）
-        return JSON.stringify({
-            e: arrayBufferToBase64(ephemeralPublicKeyRaw), // 临时公钥
-            i: arrayBufferToBase64(iv.buffer), // IV
-            d: arrayBufferToBase64(encrypted) // 密文
-        });
-    }
-    catch (error) {
-        throw new Error(`加密失败: ${error?.message || String(error)}`);
-    }
-}
-/**
- * 验证公钥格式（Base64）
- */
-export function validatePublicKey(publicKeyBase64) {
-    try {
-        if (!publicKeyBase64)
-            return false;
-        // Base64 字符集验证
-        if (!/^[A-Za-z0-9+/=]+$/.test(publicKeyBase64))
-            return false;
-        // ECDH P-256 公钥固定长度 65 字节（未压缩）
-        // Base64 编码后约 88 字符
-        if (publicKeyBase64.length < 80 || publicKeyBase64.length > 100)
-            return false;
-        return true;
-    }
-    catch {
-        return false;
-    }
-}