four-flap-meme-sdk 1.6.32 → 1.6.34

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

@@ -31,6 +31,7 @@ export declare class AAAccountManager {
     private bundler;
     private paymaster?;
     private paymasterData?;
+    private useParticlePaymaster;
     private gasLimitMultiplier;
     private senderCache;
     private deployedSenderSet;
@@ -56,6 +57,34 @@ export declare class AAAccountManager {
      * 获取 Bundler 客户端
      */
     getBundler(): BundlerClient;
+    /**
+     * 判断是否配置了 Paymaster（用于决定多跳可行性）
+     *
+     * ERC-4337 多跳场景下，如果没有 Paymaster，hop 钱包需要自己支付 prefund，
+     * 而临时生成的 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,6 +42,7 @@ 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';
@@ -93,6 +94,48 @@ export class AAAccountManager {
     getBundler() {
         return this.bundler;
     }
+    /**
+     * 判断是否配置了 Paymaster（用于决定多跳可行性）
+     *
+     * ERC-4337 多跳场景下，如果没有 Paymaster，hop 钱包需要自己支付 prefund，
+     * 而临时生成的 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');
+    }
     /**
      * 获取当前 Fee Data
      */
@@ -545,6 +588,18 @@ 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 };
     }
@@ -594,6 +649,14 @@ 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');
@@ -611,6 +674,10 @@ 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/bundler.d.ts

@@ -116,6 +116,27 @@ 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,6 +245,102 @@ 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

@@ -581,9 +581,24 @@ export class AADexSwapExecutor {
             extractProfit,
             profitWei: ethers.formatEther(profitWei),
         });
+        // ✅ 多跳模式与 Paymaster 的关系：
+        // ERC-4337 的 handleOps 执行流程是"先验证所有 UserOps，再执行所有 UserOps"
+        // hop 钱包是临时生成的（余额=0），在 validation 阶段无法支付 prefund，会导致 AA21 错误
+        // 
+        // 但是！如果配置了 Paymaster，prefund = 0n，hop 钱包不需要余额即可通过验证
+        // 因此：只有在 **没有 Paymaster** 时才需要强制禁用多跳
+        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 可启用多跳功能');
+        }
+        else if (hopCount > 0 && hasPaymaster) {
+            console.log('[AA DEX 批量换手] ✅ Paymaster 模式已启用，支持多跳换手 (hopCount:', hopCount, ')');
+        }
         if (capitalMode && buyerSenders.length > 0 && totalBuyWei > 0n) {
-            if (hopCount <= 0) {
-                console.log('[AA DEX 批量换手] 进入直接分发模式 (hopCount <= 0)');
+            if (effectiveHopCount <= 0) {
+                console.log('[AA DEX 批量换手] 进入直接分发模式 (effectiveHopCount <= 0)');
                 // ✅ 关键修复：计算每个买方执行买入 UserOp 需要的 prefund（gas 费用）
                 // EntryPoint 在 validation 阶段会扣除 prefund，此时分发还没执行
                 // 因此需要为每个买方额外预留 prefund
@@ -640,9 +655,9 @@ export class AADexSwapExecutor {
                 }
             }
             else {
-                // ✅ 多跳模式（BSC 模式）：每个买方有独立的多跳链
-                // 填写 3 跳 + 2 个买方 = 2 条独立的多跳链，每条 3 个 hop 钱包 = 6 个动态生成的 hop 钱包
-                console.log('[AA DEX 批量换手] 进入多跳模式 (hopCount > 0):', { hopCount, buyerCount: buyerSenders.length });
+                // ⚠️ 多跳模式在 XLayer AA 下不可行（effectiveHopCount 已强制为 0）
+                // 以下代码保留但不会执行，仅供参考
+                console.log('[AA DEX 批量换手] 进入多跳模式 (effectiveHopCount > 0):', { effectiveHopCount, buyerCount: buyerSenders.length });
                 const feeData = await this.aaManager.getFeeData();
                 const gasPrice = feeData.gasPrice ?? feeData.maxFeePerGas ?? 5000000000n;
                 // 预估 prefund 的函数（使用全局常量）
@@ -880,7 +895,7 @@ export class AADexSwapExecutor {
                 profitRecipient,
                 profitWei: profitWei.toString(),
                 quotedSellOutWei: quotedSellOutWei.toString(),
-                disperseHopCount: capitalMode ? String(hopCount) : '0', // ✅ capitalMode=false 时无分发
+                disperseHopCount: capitalMode ? String(effectiveHopCount) : '0', // ✅ XLayer AA 模式强制使用直接分发
             },
         };
     }

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

@@ -390,9 +390,24 @@ export class AAPortalSwapExecutor {
             extractProfit,
             profitWei: ethers.formatEther(profitWei),
         });
+        // ✅ 多跳模式与 Paymaster 的关系：
+        // ERC-4337 的 handleOps 执行流程是"先验证所有 UserOps，再执行所有 UserOps"
+        // hop 钱包是临时生成的（余额=0），在 validation 阶段无法支付 prefund，会导致 AA21 错误
+        // 
+        // 但是！如果配置了 Paymaster，prefund = 0n，hop 钱包不需要余额即可通过验证
+        // 因此：只有在 **没有 Paymaster** 时才需要强制禁用多跳
+        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 可启用多跳功能');
+        }
+        else if (hopCount > 0 && hasPaymaster) {
+            console.log('[AA Portal 批量换手] ✅ Paymaster 模式已启用，支持多跳换手 (hopCount:', hopCount, ')');
+        }
         if (capitalMode && buyerSenders.length > 0 && totalBuyWei > 0n) {
-            if (hopCount <= 0) {
-                console.log('[AA Portal 批量换手] 进入直接分发模式 (hopCount <= 0)');
+            if (effectiveHopCount <= 0) {
+                console.log('[AA Portal 批量换手] 进入直接分发模式 (effectiveHopCount <= 0)');
                 // ✅ 关键修复：计算每个买方执行买入 UserOp 需要的 prefund（gas 费用）
                 // EntryPoint 在 validation 阶段会扣除 prefund，此时分发还没执行
                 // 因此需要为每个买方额外预留 prefund
@@ -447,9 +462,9 @@ export class AAPortalSwapExecutor {
                 }
             }
             else {
-                // ✅ 多跳模式（BSC 模式）：每个买方有独立的多跳链
-                // 填写 3 跳 + 2 个买方 = 2 条独立的多跳链，每条 3 个 hop 钱包 = 6 个动态生成的 hop 钱包
-                console.log('[AA Portal 批量换手] 进入多跳模式 (hopCount > 0):', { hopCount, buyerCount: buyerSenders.length });
+                // ⚠️ 多跳模式在 XLayer AA 下不可行（effectiveHopCount 已强制为 0）
+                // 以下代码保留但不会执行，仅供参考
+                console.log('[AA Portal 批量换手] 进入多跳模式 (effectiveHopCount > 0):', { effectiveHopCount, buyerCount: buyerSenders.length });
                 const feeData = await this.aaManager.getFeeData();
                 const gasPrice = feeData.gasPrice ?? feeData.maxFeePerGas ?? 5000000000n;
                 const provider = this.aaManager.getProvider();
@@ -673,7 +688,7 @@ export class AAPortalSwapExecutor {
                 profitRecipient,
                 profitWei: profitWei.toString(),
                 quotedSellOutWei: quotedSellOutWei.toString(),
-                disperseHopCount: capitalMode ? String(hopCount) : '0', // ✅ capitalMode=false 时无分发
+                disperseHopCount: capitalMode ? String(effectiveHopCount) : '0', // ✅ XLayer AA 模式强制使用直接分发
             },
         };
     }

package/dist/xlayer/types.d.ts

@@ -72,6 +72,12 @@ export interface XLayerConfig {
     paymaster?: string;
     /** Paymaster Data（与 paymaster 一起使用） */
     paymasterData?: string;
+    /**
+     * 使用 Particle Network 的 Paymaster 服务（自动请求赞助）
+     * 如果启用，SDK 会调用 pm_sponsorUserOperation 获取 paymasterAndData
+     * 这样 hop 钱包无需 prefund，可以支持多跳
+     */
+    useParticlePaymaster?: boolean;
     /** 默认超时时间（毫秒） */
     timeoutMs?: number;
     /** Gas 估算安全余量倍数 */

package/package.json

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