four-flap-meme-sdk 1.6.34 → 1.6.36

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

@@ -31,7 +31,6 @@ export declare class AAAccountManager {
     private bundler;
     private paymaster?;
     private paymasterData?;
-    private useParticlePaymaster;
     private gasLimitMultiplier;
     private senderCache;
     private deployedSenderSet;
@@ -64,27 +63,8 @@ export declare class AAAccountManager {
      * 而临时生成的 hop 钱包余额为 0，会导致 AA21 验证失败。
      *
      * 如果配置了 Paymaster，prefund = 0，hop 钱包不需要余额即可通过验证。
-     *
-     * 支持两种模式：
-     * 1. 静态配置：config.paymaster 指定 Paymaster 合约地址
-     * 2. Particle Paymaster：config.useParticlePaymaster = true，自动请求 pm_sponsorUserOperation
      */
     hasPaymaster(): boolean;
-    /**
-     * 是否使用 Particle Paymaster（动态请求 paymasterAndData）
-     */
-    usesParticlePaymaster(): boolean;
-    /**
-     * 请求 Particle Paymaster 赞助 UserOp
-     *
-     * @param userOp 未签名的 UserOperation
-     * @returns paymasterAndData，如果失败则返回 '0x'
-     */
-    requestParticlePaymasterSponsor(userOp: UserOperation): Promise<string>;
-    /**
-     * 批量请求 Particle Paymaster 赞助
-     */
-    requestParticlePaymasterSponsorBatch(userOps: UserOperation[]): Promise<string[]>;
     /**
      * 获取当前 Fee Data
      */

package/dist/xlayer/aa-account.js

@@ -42,7 +42,6 @@ export class AAAccountManager {
         this.salt = config.salt ?? DEFAULT_SALT;
         this.paymaster = config.paymaster;
         this.paymasterData = config.paymasterData;
-        this.useParticlePaymaster = config.useParticlePaymaster ?? false;
         this.gasLimitMultiplier = config.gasLimitMultiplier ?? GAS_LIMIT_MULTIPLIER;
         // 默认 fixed：最大化降低 RPC / bundler 请求；如需更稳可显式传 bundlerEstimate
         this.defaultGasPolicy = config.gasPolicy ?? 'fixed';
@@ -101,40 +100,9 @@ export class AAAccountManager {
      * 而临时生成的 hop 钱包余额为 0，会导致 AA21 验证失败。
      *
      * 如果配置了 Paymaster，prefund = 0，hop 钱包不需要余额即可通过验证。
-     *
-     * 支持两种模式：
-     * 1. 静态配置：config.paymaster 指定 Paymaster 合约地址
-     * 2. Particle Paymaster：config.useParticlePaymaster = true，自动请求 pm_sponsorUserOperation
      */
     hasPaymaster() {
-        return !!this.paymaster || this.useParticlePaymaster;
-    }
-    /**
-     * 是否使用 Particle Paymaster（动态请求 paymasterAndData）
-     */
-    usesParticlePaymaster() {
-        return this.useParticlePaymaster;
-    }
-    /**
-     * 请求 Particle Paymaster 赞助 UserOp
-     *
-     * @param userOp 未签名的 UserOperation
-     * @returns paymasterAndData，如果失败则返回 '0x'
-     */
-    async requestParticlePaymasterSponsor(userOp) {
-        if (!this.useParticlePaymaster)
-            return '0x';
-        const result = await this.bundler.sponsorUserOperation(userOp);
-        return result ?? '0x';
-    }
-    /**
-     * 批量请求 Particle Paymaster 赞助
-     */
-    async requestParticlePaymasterSponsorBatch(userOps) {
-        if (!this.useParticlePaymaster)
-            return userOps.map(() => '0x');
-        const results = await this.bundler.sponsorUserOperationBatch(userOps);
-        return results.map(r => r ?? '0x');
+        return !!this.paymaster;
     }
     /**
      * 获取当前 Fee Data
@@ -588,18 +556,6 @@ export class AAAccountManager {
             userOp = result.userOp;
             prefundWei = result.prefundWei;
         }
-        // ✅ Particle Paymaster：请求赞助并填入 paymasterAndData
-        if (this.useParticlePaymaster && userOp.paymasterAndData === '0x') {
-            const sponsorData = await this.requestParticlePaymasterSponsor(userOp);
-            if (sponsorData && sponsorData !== '0x') {
-                userOp = { ...userOp, paymasterAndData: sponsorData };
-                prefundWei = 0n; // Paymaster 代付，无需 prefund
-                console.log('[AAAccountManager] ✅ Particle Paymaster 赞助成功');
-            }
-            else {
-                console.warn('[AAAccountManager] ⚠️ Particle Paymaster 赞助失败，回退为自付模式');
-            }
-        }
         const signed = await this.signUserOp(userOp, params.ownerWallet);
         return { ...signed, prefundWei };
     }
@@ -649,14 +605,6 @@ export class AAAccountManager {
             userOp = result.userOp;
             prefundWei = result.prefundWei;
         }
-        // ✅ Particle Paymaster：请求赞助并填入 paymasterAndData
-        if (this.useParticlePaymaster && userOp.paymasterAndData === '0x') {
-            const sponsorData = await this.requestParticlePaymasterSponsor(userOp);
-            if (sponsorData && sponsorData !== '0x') {
-                userOp = { ...userOp, paymasterAndData: sponsorData };
-                prefundWei = 0n; // Paymaster 代付，无需 prefund
-            }
-        }
         // 只有非 signOnly 模式才执行 ensureSenderBalance
         if (!signOnly) {
             await this.ensureSenderBalance(ownerWallet, sender, prefundWei, 'buildUserOpWithState');
@@ -674,10 +622,6 @@ export class AAAccountManager {
      * @returns 是否进行了转账
      */
     async ensureSenderBalance(ownerWallet, sender, requiredWei, tag) {
-        // 如果有 Paymaster（静态配置或 Particle），无需检查余额
-        if (this.hasPaymaster()) {
-            return { funded: false };
-        }
         if (this.paymaster) {
             const code = await this.provider.getCode(this.paymaster);
             if (code && code !== '0x') {

package/dist/xlayer/bundle.js

@@ -1534,8 +1534,8 @@ export class BundleExecutor {
             name: tokenInfo.name,
             symbol: tokenInfo.symbol,
             meta: tokenInfo.meta,
-            dexThresh: params.dexThresh ?? 0,
-            salt: params.salt ?? ethers.hexlify(ethers.randomBytes(32)),
+            dexThresh: (params.dexThresh ?? 1) & 0xff, // ✅ 与 BSC 保持一致，默认 1
+            salt: params.salt ?? ethers.ZeroHash, // ✅ 修复：与 bundleCreateBuySign 保持一致，使用 ZeroHash 确保代币地址预计算一致
             taxRate: params.taxRate ?? 0,
             migratorType: params.migratorType ?? 0,
             quoteToken: params.quoteToken ?? ZERO_ADDRESS,

package/dist/xlayer/bundler.d.ts

@@ -116,27 +116,6 @@ export declare class BundlerClient {
      * 获取当前链 ID
      */
     getChainId(): number;
-    /**
-     * 请求 Particle Paymaster 赞助 UserOperation
-     *
-     * Particle 的 Paymaster 服务会返回 paymasterAndData，
-     * 将其填入 UserOp 后，用户无需支付 prefund（gas 由 Paymaster 代付）
-     *
-     * @param userOp 未签名的 UserOperation（paymasterAndData 为空）
-     * @returns paymasterAndData 字符串，如果不支持则返回 null
-     */
-    sponsorUserOperation(userOp: UserOperation): Promise<string | null>;
-    /**
-     * 批量请求 Paymaster 赞助
-     *
-     * @param userOps 未签名的 UserOperations
-     * @returns paymasterAndData 数组，不支持的返回 null
-     */
-    sponsorUserOperationBatch(userOps: UserOperation[]): Promise<(string | null)[]>;
-    /**
-     * 检查 Paymaster 是否可用
-     */
-    isPaymasterAvailable(): Promise<boolean>;
 }
 /**
  * 创建默认的 Bundler 客户端

package/dist/xlayer/bundler.js

@@ -245,102 +245,6 @@ export class BundlerClient {
     getChainId() {
         return this.chainId;
     }
-    // ============================================================================
-    // Paymaster API（Particle Network 特有）
-    // ============================================================================
-    /**
-     * 请求 Particle Paymaster 赞助 UserOperation
-     *
-     * Particle 的 Paymaster 服务会返回 paymasterAndData，
-     * 将其填入 UserOp 后，用户无需支付 prefund（gas 由 Paymaster 代付）
-     *
-     * @param userOp 未签名的 UserOperation（paymasterAndData 为空）
-     * @returns paymasterAndData 字符串，如果不支持则返回 null
-     */
-    async sponsorUserOperation(userOp) {
-        try {
-            // Particle 使用 pm_sponsorUserOperation 方法
-            const result = await this.rpc('pm_sponsorUserOperation', [userOp, this.entryPoint]);
-            if (typeof result === 'string') {
-                return result;
-            }
-            if (result && typeof result === 'object' && result.paymasterAndData) {
-                return result.paymasterAndData;
-            }
-            return null;
-        }
-        catch (err) {
-            // Paymaster 不可用或不愿意赞助，返回 null
-            console.warn('[Bundler] Paymaster 请求失败（可能不支持或拒绝赞助）:', err);
-            return null;
-        }
-    }
-    /**
-     * 批量请求 Paymaster 赞助
-     *
-     * @param userOps 未签名的 UserOperations
-     * @returns paymasterAndData 数组，不支持的返回 null
-     */
-    async sponsorUserOperationBatch(userOps) {
-        if (userOps.length === 0)
-            return [];
-        try {
-            const results = await this.rpcBatch(userOps.map(op => ({
-                method: 'pm_sponsorUserOperation',
-                params: [op, this.entryPoint],
-            })));
-            return results.map(r => {
-                if (typeof r === 'string')
-                    return r;
-                if (r && typeof r === 'object' && r.paymasterAndData) {
-                    return r.paymasterAndData;
-                }
-                return null;
-            });
-        }
-        catch (err) {
-            console.warn('[Bundler] 批量 Paymaster 请求失败，尝试单个请求:', err);
-            // 降级为单个请求
-            const out = [];
-            for (const op of userOps) {
-                out.push(await this.sponsorUserOperation(op));
-            }
-            return out;
-        }
-    }
-    /**
-     * 检查 Paymaster 是否可用
-     */
-    async isPaymasterAvailable() {
-        try {
-            // 尝试调用一个空的 sponsor 请求，看是否返回错误
-            // 如果返回 "method not found" 则不支持
-            const testOp = {
-                sender: '0x0000000000000000000000000000000000000001',
-                nonce: '0x0',
-                initCode: '0x',
-                callData: '0x',
-                callGasLimit: '0x5208',
-                verificationGasLimit: '0x5208',
-                preVerificationGas: '0x5208',
-                maxFeePerGas: '0x1',
-                maxPriorityFeePerGas: '0x1',
-                paymasterAndData: '0x',
-                signature: '0x',
-            };
-            await this.rpc('pm_sponsorUserOperation', [testOp, this.entryPoint]);
-            return true;
-        }
-        catch (err) {
-            const msg = String(err?.message || err || '').toLowerCase();
-            // 如果是 "method not found" 则不支持
-            if (msg.includes('method not found') || msg.includes('not supported') || msg.includes('unknown method')) {
-                return false;
-            }
-            // 其他错误（如拒绝赞助）说明方法存在，只是不愿意赞助这个特定请求
-            return true;
-        }
-    }
 }
 // ============================================================================
 // 工具函数

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,54 @@ 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} 个`);
+                    }
+                    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（预充值的钱包 nonce 应该是 0）
+                            nonceMap.init(prefundedHop.senderAddress, 0n);
+                        }
+                        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 +736,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 +782,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,518 @@
+/**
+ * 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 = [];
+        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);
+                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,
+                });
+                // 签名
+                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,51 @@ 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} 个`);
+                    }
+                    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,
+                            });
+                            nonceMap.init(prefundedHop.senderAddress, 0n);
+                        }
+                        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

@@ -72,12 +72,6 @@ export interface XLayerConfig {
     paymaster?: string;
     /** Paymaster Data（与 paymaster 一起使用） */
     paymasterData?: string;
-    /**
-     * 使用 Particle Network 的 Paymaster 服务（自动请求赞助）
-     * 如果启用，SDK 会调用 pm_sponsorUserOperation 获取 paymasterAndData
-     * 这样 hop 钱包无需 prefund，可以支持多跳
-     */
-    useParticlePaymaster?: boolean;
     /** 默认超时时间（毫秒） */
     timeoutMs?: number;
     /** Gas 估算安全余量倍数 */
@@ -558,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.34",
+  "version": "1.6.36",
   "description": "SDK for Flap bonding curve and four.meme TokenManager",
   "type": "module",
   "main": "dist/index.js",