four-flap-meme-sdk 1.4.91 → 1.4.92

package/dist/xlayer/aa-account.js

@@ -0,0 +1,510 @@
+/**
+ * XLayer AA 账户管理器
+ *
+ * 核心功能：
+ * - AA 账户（Sender）地址预测和部署
+ * - UserOperation 构建和签名
+ * - 余额管理和资金充值
+ * - initCode 生成
+ */
+import { ethers, JsonRpcProvider, Wallet, Contract, Interface } from 'ethers';
+import { XLAYER_CHAIN_ID, DEFAULT_RPC_URL, ENTRYPOINT_V06, SIMPLE_ACCOUNT_FACTORY, DEFAULT_SALT, DEFAULT_GAS_PRICE, GAS_LIMIT_MULTIPLIER, VERIFICATION_GAS_LIMIT_DEPLOY, VERIFICATION_GAS_LIMIT_NORMAL, PRE_VERIFICATION_GAS, FACTORY_ABI, ENTRYPOINT_ABI, SIMPLE_ACCOUNT_ABI, } from './constants.js';
+import { BundlerClient } from './bundler.js';
+// ============================================================================
+// AA 账户管理器
+// ============================================================================
+/**
+ * AA 账户管理器
+ *
+ * 管理 ERC-4337 SimpleAccount：
+ * - 地址预测（无需部署即可知道地址）
+ * - UserOp 构建和签名
+ * - Gas 估算和 Prefund 计算
+ * - 支持 Paymaster（免 Gas）
+ */
+export class AAAccountManager {
+    constructor(config = {}) {
+        this.chainId = config.chainId ?? XLAYER_CHAIN_ID;
+        const rpcUrl = config.rpcUrl ?? DEFAULT_RPC_URL;
+        this.provider = new JsonRpcProvider(rpcUrl, {
+            chainId: this.chainId,
+            name: 'xlayer',
+        });
+        this.factoryAddress = config.factory ?? SIMPLE_ACCOUNT_FACTORY;
+        this.entryPointAddress = config.entryPoint ?? ENTRYPOINT_V06;
+        this.salt = config.salt ?? DEFAULT_SALT;
+        this.paymaster = config.paymaster;
+        this.paymasterData = config.paymasterData;
+        this.gasLimitMultiplier = config.gasLimitMultiplier ?? GAS_LIMIT_MULTIPLIER;
+        this.factory = new Contract(this.factoryAddress, FACTORY_ABI, this.provider);
+        this.entryPoint = new Contract(this.entryPointAddress, ENTRYPOINT_ABI, this.provider);
+        this.bundler = new BundlerClient({
+            url: config.bundlerUrl,
+            chainId: this.chainId,
+            entryPoint: this.entryPointAddress,
+            timeoutMs: config.timeoutMs,
+        });
+    }
+    /**
+     * 获取 Provider
+     */
+    getProvider() {
+        return this.provider;
+    }
+    /**
+     * 获取 EntryPoint 合约
+     */
+    getEntryPoint() {
+        return this.entryPoint;
+    }
+    /**
+     * 获取 EntryPoint 地址
+     */
+    getEntryPointAddress() {
+        return this.entryPointAddress;
+    }
+    /**
+     * 获取 Bundler 客户端
+     */
+    getBundler() {
+        return this.bundler;
+    }
+    /**
+     * 获取当前 Fee Data
+     */
+    async getFeeData() {
+        return await this.provider.getFeeData();
+    }
+    /**
+     * 预测 AA Sender 地址
+     *
+     * @param ownerAddress Owner EOA 地址
+     * @param salt 可选的 salt 覆盖
+     * @returns 预测的 Sender 地址
+     */
+    async predictSenderAddress(ownerAddress, salt) {
+        const useSalt = salt ?? this.salt;
+        // 使用 staticCall 模拟 createAccount 获取预测地址
+        // 这比 getAddress 更可靠（某些链上 getAddress 有问题）
+        return await this.factory.createAccount.staticCall(ownerAddress, useSalt);
+    }
+    /**
+     * 获取完整的 AA 账户信息
+     */
+    async getAccountInfo(ownerAddress, salt) {
+        const sender = await this.predictSenderAddress(ownerAddress, salt);
+        const [code, balance, nonce] = await Promise.all([
+            this.provider.getCode(sender),
+            this.provider.getBalance(sender),
+            this.entryPoint.getNonce(sender, 0),
+        ]);
+        return {
+            owner: ownerAddress,
+            sender,
+            deployed: code !== null && code !== '0x',
+            balance,
+            nonce,
+        };
+    }
+    /**
+     * 生成 initCode（用于在 UserOp 中部署账户）
+     */
+    generateInitCode(ownerAddress, salt) {
+        const useSalt = salt ?? this.salt;
+        const factoryIface = new Interface(FACTORY_ABI);
+        const calldata = factoryIface.encodeFunctionData('createAccount', [ownerAddress, useSalt]);
+        return ethers.concat([this.factoryAddress, calldata]);
+    }
+    /**
+     * 构建 paymasterAndData
+     */
+    buildPaymasterAndData() {
+        if (!this.paymaster)
+            return '0x';
+        if (this.paymasterData) {
+            return ethers.concat([this.paymaster, this.paymasterData]);
+        }
+        return this.paymaster;
+    }
+    /**
+     * 构建未签名的 UserOperation（使用 Bundler 估算 Gas）
+     */
+    async buildUserOpWithBundlerEstimate(params) {
+        const feeData = await this.provider.getFeeData();
+        const legacyGasPrice = feeData.gasPrice ?? feeData.maxFeePerGas ?? DEFAULT_GAS_PRICE;
+        const paymasterAndData = this.buildPaymasterAndData();
+        // 构建初步 UserOp（Gas 字段为 0，等待估算）
+        let userOp = {
+            sender: params.sender,
+            nonce: ethers.toBeHex(params.nonce),
+            initCode: params.initCode ?? '0x',
+            callData: params.callData,
+            callGasLimit: '0x0',
+            verificationGasLimit: '0x0',
+            preVerificationGas: '0x0',
+            maxFeePerGas: ethers.toBeHex(legacyGasPrice * 2n),
+            maxPriorityFeePerGas: ethers.toBeHex(legacyGasPrice),
+            paymasterAndData,
+            signature: '0x',
+        };
+        // 调用 Bundler 估算 Gas
+        const estimate = await this.bundler.estimateUserOperationGas(userOp);
+        userOp = {
+            ...userOp,
+            callGasLimit: estimate.callGasLimit,
+            verificationGasLimit: estimate.verificationGasLimit,
+            preVerificationGas: estimate.preVerificationGas,
+        };
+        // 使用 Bundler 建议的费率
+        if (estimate.maxFeePerGas && estimate.maxPriorityFeePerGas) {
+            userOp = {
+                ...userOp,
+                maxFeePerGas: estimate.maxFeePerGas,
+                maxPriorityFeePerGas: estimate.maxPriorityFeePerGas,
+            };
+        }
+        // 计算 prefund（如果使用 Paymaster 则不需要）
+        const gasTotal = BigInt(userOp.callGasLimit) +
+            BigInt(userOp.verificationGasLimit) +
+            BigInt(userOp.preVerificationGas);
+        const prefundWei = paymasterAndData !== '0x' ? 0n : gasTotal * BigInt(userOp.maxFeePerGas);
+        return { userOp, prefundWei };
+    }
+    /**
+     * 构建未签名的 UserOperation（本地估算 Gas，不依赖 Bundler）
+     *
+     * 适用于无法通过 Bundler 估算的场景（如尚未授权的 sell 操作）
+     */
+    async buildUserOpWithLocalEstimate(params) {
+        const feeData = await this.provider.getFeeData();
+        const legacyGasPrice = feeData.gasPrice ?? feeData.maxFeePerGas ?? DEFAULT_GAS_PRICE;
+        const paymasterAndData = this.buildPaymasterAndData();
+        // 估算 callGasLimit
+        let callGasLimit = params.callGasLimit;
+        if (!callGasLimit) {
+            try {
+                // EntryPoint 调用 sender.execute 时 msg.value 恒为 0
+                const estimated = await this.provider.estimateGas({
+                    from: this.entryPointAddress,
+                    to: params.sender,
+                    data: params.callData,
+                    value: 0n,
+                });
+                callGasLimit = BigInt(Math.ceil(Number(estimated) * this.gasLimitMultiplier));
+            }
+            catch {
+                // 兜底值
+                callGasLimit = 500000n;
+            }
+        }
+        const hasInitCode = params.initCode && params.initCode !== '0x';
+        const verificationGasLimit = hasInitCode ? VERIFICATION_GAS_LIMIT_DEPLOY : VERIFICATION_GAS_LIMIT_NORMAL;
+        const preVerificationGas = PRE_VERIFICATION_GAS;
+        const userOp = {
+            sender: params.sender,
+            nonce: ethers.toBeHex(params.nonce),
+            initCode: params.initCode ?? '0x',
+            callData: params.callData,
+            callGasLimit: ethers.toBeHex(callGasLimit),
+            verificationGasLimit: ethers.toBeHex(verificationGasLimit),
+            preVerificationGas: ethers.toBeHex(preVerificationGas),
+            // XLayer 更像 legacy gasPrice 语义
+            maxFeePerGas: ethers.toBeHex(legacyGasPrice),
+            maxPriorityFeePerGas: ethers.toBeHex(legacyGasPrice),
+            paymasterAndData,
+            signature: '0x',
+        };
+        const gasTotal = callGasLimit + verificationGasLimit + preVerificationGas;
+        const prefundWei = paymasterAndData !== '0x' ? 0n : gasTotal * legacyGasPrice;
+        return { userOp, prefundWei };
+    }
+    /**
+     * 签名 UserOperation
+     */
+    async signUserOp(userOp, ownerWallet) {
+        const userOpHash = await this.entryPoint.getUserOpHash(userOp);
+        const signature = await ownerWallet.signMessage(ethers.getBytes(userOpHash));
+        return {
+            userOp: { ...userOp, signature },
+            userOpHash,
+            prefundWei: 0n, // 已在构建时计算
+            sender: userOp.sender,
+        };
+    }
+    /**
+     * 构建并签名 UserOperation（完整流程）
+     */
+    async buildAndSignUserOp(params) {
+        const ownerAddress = params.ownerWallet.address;
+        const accountInfo = await this.getAccountInfo(ownerAddress);
+        const initCode = accountInfo.deployed ? '0x' : this.generateInitCode(ownerAddress);
+        const buildParams = {
+            ownerWallet: params.ownerWallet,
+            sender: accountInfo.sender,
+            callData: params.callData,
+            nonce: accountInfo.nonce,
+            initCode,
+        };
+        let userOp;
+        let prefundWei;
+        if (params.useBundlerEstimate !== false) {
+            const result = await this.buildUserOpWithBundlerEstimate(buildParams);
+            userOp = result.userOp;
+            prefundWei = result.prefundWei;
+        }
+        else {
+            const result = await this.buildUserOpWithLocalEstimate({
+                ...buildParams,
+                callGasLimit: params.callGasLimit,
+            });
+            userOp = result.userOp;
+            prefundWei = result.prefundWei;
+        }
+        const signed = await this.signUserOp(userOp, params.ownerWallet);
+        return { ...signed, prefundWei };
+    }
+    /**
+     * 确保 Sender 有足够的 OKB 余额
+     *
+     * @param ownerWallet Owner 钱包（用于转账）
+     * @param sender Sender 地址
+     * @param requiredWei 所需余额（wei）
+     * @param tag 日志标签
+     * @returns 是否进行了转账
+     */
+    async ensureSenderBalance(ownerWallet, sender, requiredWei, tag) {
+        // 如果使用 Paymaster，不需要给 sender 转账
+        if (this.paymaster) {
+            return { funded: false };
+        }
+        const balance = await this.provider.getBalance(sender);
+        if (balance >= requiredWei) {
+            return { funded: false };
+        }
+        const missing = requiredWei - balance;
+        console.log(`[${tag ?? 'ensureSenderBalance'}] sender OKB 不足，owner 补充：${ethers.formatEther(missing)} OKB`);
+        const tx = await ownerWallet.sendTransaction({ to: sender, value: missing });
+        console.log(` - fund tx: ${tx.hash}`);
+        await tx.wait();
+        return { funded: true, txHash: tx.hash };
+    }
+    /**
+     * 批量获取多个 owner 的 AA 账户信息
+     */
+    async getMultipleAccountInfo(ownerAddresses) {
+        return Promise.all(ownerAddresses.map((addr) => this.getAccountInfo(addr)));
+    }
+}
+// ============================================================================
+// 工具函数
+// ============================================================================
+/**
+ * 编码 SimpleAccount.execute 调用
+ */
+export function encodeExecute(dest, value, data) {
+    const iface = new Interface(SIMPLE_ACCOUNT_ABI);
+    return iface.encodeFunctionData('execute', [dest, value, data]);
+}
+/**
+ * 编码 SimpleAccount.executeBatch 调用
+ */
+export function encodeExecuteBatch(dests, values, datas) {
+    const iface = new Interface(SIMPLE_ACCOUNT_ABI);
+    return iface.encodeFunctionData('executeBatch', [dests, values, datas]);
+}
+/**
+ * 创建 AA 账户管理器
+ */
+export function createAAAccountManager(config) {
+    return new AAAccountManager(config);
+}
+/**
+ * 快速预测 Sender 地址
+ */
+export async function predictSender(ownerAddress, config) {
+    const manager = createAAAccountManager(config);
+    return manager.predictSenderAddress(ownerAddress);
+}
+/**
+ * 从私钥创建连接了 Provider 的 Wallet
+ */
+export function createWallet(privateKey, config) {
+    const rpcUrl = config?.rpcUrl ?? DEFAULT_RPC_URL;
+    const chainId = config?.chainId ?? XLAYER_CHAIN_ID;
+    const provider = new JsonRpcProvider(rpcUrl, { chainId, name: 'xlayer' });
+    return new Wallet(privateKey, provider);
+}
+/**
+ * 批量生成随机钱包并预测 AA 地址
+ *
+ * @param params 生成参数
+ * @returns 钱包列表和汇总信息
+ *
+ * @example
+ * ```typescript
+ * const result = await generateAAWallets({ count: 5 });
+ *
+ * console.log(result.formatted);
+ * // 输出:
+ * // === XLayer AA Wallets ===
+ * // #1
+ * //   Owner:  0x1234...
+ * //   Sender: 0xabcd...
+ * //   Key:    0x...
+ * // ...
+ *
+ * // 直接使用私钥列表
+ * await bundleBuy({
+ *   tokenAddress: '0x...',
+ *   privateKeys: result.privateKeys,
+ *   buyAmounts: ['0.01', '0.01', '0.01', '0.01', '0.01'],
+ * });
+ * ```
+ */
+export async function generateAAWallets(params) {
+    const { count, config } = params;
+    const manager = createAAAccountManager(config);
+    const wallets = [];
+    const owners = [];
+    const privateKeys = [];
+    const senders = [];
+    console.log(`\n生成 ${count} 个 XLayer AA 钱包...\n`);
+    for (let i = 0; i < count; i++) {
+        // 生成随机钱包
+        const wallet = Wallet.createRandom();
+        const owner = wallet.address;
+        const privateKey = wallet.privateKey;
+        // 预测 AA 地址
+        const sender = await manager.predictSenderAddress(owner);
+        wallets.push({
+            index: i + 1,
+            owner,
+            privateKey,
+            sender,
+        });
+        owners.push(owner);
+        privateKeys.push(privateKey);
+        senders.push(sender);
+        console.log(`#${i + 1}`);
+        console.log(`  Owner:  ${owner}`);
+        console.log(`  Sender: ${sender}`);
+    }
+    // 生成格式化输出
+    const formatted = formatWalletOutput(wallets);
+    return {
+        wallets,
+        owners,
+        privateKeys,
+        senders,
+        formatted,
+    };
+}
+/**
+ * 从助记词批量派生钱包并预测 AA 地址
+ *
+ * @param mnemonic 助记词
+ * @param count 派生数量
+ * @param startIndex 起始索引（默认 0）
+ * @param config 配置
+ */
+export async function generateAAWalletsFromMnemonic(mnemonic, count, startIndex = 0, config) {
+    const manager = createAAAccountManager(config);
+    const wallets = [];
+    const owners = [];
+    const privateKeys = [];
+    const senders = [];
+    console.log(`\n从助记词派生 ${count} 个 XLayer AA 钱包 (起始索引: ${startIndex})...\n`);
+    for (let i = 0; i < count; i++) {
+        const index = startIndex + i;
+        const path = `m/44'/60'/0'/0/${index}`;
+        // 从助记词派生
+        const hdNode = ethers.HDNodeWallet.fromPhrase(mnemonic, undefined, path);
+        const owner = hdNode.address;
+        const privateKey = hdNode.privateKey;
+        // 预测 AA 地址
+        const sender = await manager.predictSenderAddress(owner);
+        wallets.push({
+            index: i + 1,
+            owner,
+            privateKey,
+            sender,
+            mnemonic: i === 0 ? mnemonic : undefined, // 只在第一个记录助记词
+            derivationPath: path,
+        });
+        owners.push(owner);
+        privateKeys.push(privateKey);
+        senders.push(sender);
+        console.log(`#${i + 1} (path: ${path})`);
+        console.log(`  Owner:  ${owner}`);
+        console.log(`  Sender: ${sender}`);
+    }
+    const formatted = formatWalletOutput(wallets, mnemonic);
+    return {
+        wallets,
+        owners,
+        privateKeys,
+        senders,
+        formatted,
+    };
+}
+/**
+ * 从私钥列表预测 AA 地址
+ *
+ * @param privateKeys 私钥列表
+ * @param config 配置
+ */
+export async function predictSendersFromPrivateKeys(privateKeys, config) {
+    const manager = createAAAccountManager(config);
+    const wallets = [];
+    const owners = [];
+    const senders = [];
+    console.log(`\n预测 ${privateKeys.length} 个 AA 地址...\n`);
+    for (let i = 0; i < privateKeys.length; i++) {
+        const wallet = new Wallet(privateKeys[i]);
+        const owner = wallet.address;
+        const sender = await manager.predictSenderAddress(owner);
+        wallets.push({
+            index: i + 1,
+            owner,
+            privateKey: privateKeys[i],
+            sender,
+        });
+        owners.push(owner);
+        senders.push(sender);
+        console.log(`#${i + 1}`);
+        console.log(`  Owner:  ${owner}`);
+        console.log(`  Sender: ${sender}`);
+    }
+    const formatted = formatWalletOutput(wallets);
+    return {
+        wallets,
+        owners,
+        privateKeys,
+        senders,
+        formatted,
+    };
+}
+/**
+ * 格式化钱包输出
+ */
+function formatWalletOutput(wallets, mnemonic) {
+    let output = '=== XLayer AA Wallets ===\n\n';
+    if (mnemonic) {
+        output += `Mnemonic: ${mnemonic}\n\n`;
+    }
+    for (const w of wallets) {
+        output += `#${w.index}\n`;
+        output += `  Owner:  ${w.owner}\n`;
+        output += `  Sender: ${w.sender}\n`;
+        output += `  Key:    ${w.privateKey}\n`;
+        if (w.derivationPath) {
+            output += `  Path:   ${w.derivationPath}\n`;
+        }
+        output += '\n';
+    }
+    output += '=== 汇总 ===\n\n';
+    output += `Owners (EOA):\n${wallets.map(w => w.owner).join('\n')}\n\n`;
+    output += `Senders (AA):\n${wallets.map(w => w.sender).join('\n')}\n\n`;
+    output += `Private Keys:\n${wallets.map(w => w.privateKey).join('\n')}\n`;
+    return output;
+}

package/dist/xlayer/bundle.d.ts

@@ -0,0 +1,93 @@
+/**
+ * XLayer 捆绑交易 SDK
+ *
+ * 通过 ERC-4337 handleOps 实现多个地址的原子化交易：
+ * - 捆绑买入：多个 sender 同一笔 handleOps 买入
+ * - 捆绑卖出：多个 sender 同一笔 handleOps 卖出
+ * - 买卖一体化：买入 -> 授权 -> 卖出 -> 归集
+ * - OKB 归集：将 sender 的 OKB 转回 owner
+ */
+import type { XLayerConfig, BundleBuyParams, BundleBuyResult, BundleSellParams, BundleSellResult, BundleBuySellParams, BundleBuySellResult } from './types.js';
+import { AAAccountManager } from './aa-account.js';
+import { PortalQuery } from './portal-ops.js';
+/**
+ * XLayer 捆绑交易执行器
+ *
+ * 核心设计原则：
+ * 1. 用户只需操控 AA 地址（Sender）
+ * 2. 如果指定了 Paymaster，不需要往 AA 转手续费
+ * 3. 多个 UserOp 放入同一笔 handleOps 保证原子性
+ */
+export declare class BundleExecutor {
+    private aaManager;
+    private portalQuery;
+    private config;
+    private portalAddress;
+    constructor(config?: XLayerConfig);
+    /**
+     * 获取 AA 管理器
+     */
+    getAAManager(): AAAccountManager;
+    /**
+     * 获取 Portal 查询器
+     */
+    getPortalQuery(): PortalQuery;
+    /**
+     * 执行 handleOps 并解析结果
+     */
+    private runHandleOps;
+    /**
+     * 构建买入 UserOp
+     */
+    private buildBuyUserOp;
+    /**
+     * 构建授权 UserOp
+     */
+    private buildApproveUserOp;
+    /**
+     * 构建卖出 UserOp
+     */
+    private buildSellUserOp;
+    /**
+     * 构建归集 UserOp（将 OKB 从 sender 转回 owner）
+     */
+    private buildWithdrawUserOp;
+    /**
+     * 构建代币转账 UserOp（将代币从 sender 转回 owner）
+     */
+    private buildTransferTokenUserOp;
+    /**
+     * 捆绑买入
+     *
+     * 多个地址同一笔 handleOps 买入代币
+     */
+    bundleBuy(params: BundleBuyParams): Promise<BundleBuyResult>;
+    /**
+     * 捆绑卖出
+     *
+     * 多个地址同一笔 handleOps 卖出代币
+     */
+    bundleSell(params: BundleSellParams): Promise<BundleSellResult>;
+    /**
+     * 捆绑买卖（先买后卖）
+     *
+     * 完整流程：买入 -> 授权 -> 卖出 -> 归集
+     */
+    bundleBuySell(params: BundleBuySellParams): Promise<BundleBuySellResult>;
+}
+/**
+ * 创建捆绑交易执行器
+ */
+export declare function createBundleExecutor(config?: XLayerConfig): BundleExecutor;
+/**
+ * 快速捆绑买入
+ */
+export declare function bundleBuy(params: BundleBuyParams): Promise<BundleBuyResult>;
+/**
+ * 快速捆绑卖出
+ */
+export declare function bundleSell(params: BundleSellParams): Promise<BundleSellResult>;
+/**
+ * 快速捆绑买卖
+ */
+export declare function bundleBuySell(params: BundleBuySellParams): Promise<BundleBuySellResult>;