four-flap-meme-sdk 2.2.0 → 2.2.2

package/dist/contracts/tm-bundle-merkle/submit.js

@@ -1,3 +1,928 @@
-/** Bundle 提交 — 实现见 bundle-core/submit；ENI 见 chains/eni/submit */
-export { submitBundleToMerkle, submitMultipleBundles, submitMultipleBundlesParallel, submitBundleToBlockRazor, submitMultipleBundlesToBlockRazor, submitMultipleBundlesToBlockRazorParallel, submitDirectToRpc, submitDirectToRpcSequential, submitDirectToRpcSequentialNoWait, submitDirectToRpcParallel, submitDirectToRpcSmart, } from '../../bundle-core/submit.js';
-export { submitBundleToEni, submitEniParallelThenProfit, } from '../../chains/eni/submit.js';
+/**
+ * 独立的Bundle提交方法
+ *
+ * 用于服务器端接收前端构建的签名交易后，提交到Merkle或BlockRazor
+ * 以及 Monad 等不支持 Bundle 的链的逐笔广播
+ */
+import { MerkleClient } from '../../shared/clients/merkle.js';
+import { BlockRazorClient } from '../../shared/clients/blockrazor.js';
+import { ethers } from 'ethers';
+// ✅ MerkleClient 缓存（复用连接，减少初始化开销）
+const merkleClientCache = new Map();
+const CLIENT_CACHE_TTL_MS = 60 * 1000; // 60秒缓存
+/**
+ * 获取或创建 MerkleClient（带缓存）
+ */
+function getMerkleClient(config) {
+    const cacheKey = `${config.apiKey}-${config.chainId ?? 56}-${config.customRpcUrl || ''}`;
+    const now = Date.now();
+    const cached = merkleClientCache.get(cacheKey);
+    if (cached && cached.expireAt > now) {
+        return cached.client;
+    }
+    // 创建新客户端并缓存
+    const client = new MerkleClient({
+        apiKey: config.apiKey,
+        chainId: config.chainId ?? 56,
+        customRpcUrl: config.customRpcUrl
+    });
+    merkleClientCache.set(cacheKey, { client, expireAt: now + CLIENT_CACHE_TTL_MS });
+    return client;
+}
+/**
+ * 提交已签名的交易到Merkle（服务器端使用）
+ *
+ * 这个方法接收前端构建和签名好的交易，直接提交到Merkle服务
+ *
+ * @param signedTransactions 签名后的交易数组
+ * @param config Merkle提交配置（精简版，只需要提交相关参数）
+ * @returns Bundle提交结果
+ *
+ * @example
+ * ```typescript
+ * // 服务器端代码
+ * import { submitBundleToMerkle } from 'four-flap-meme-sdk';
+ *
+ * const result = await submitBundleToMerkle(signedTransactions, {
+ *   apiKey: process.env.MERKLE_API_KEY,
+ *   customRpcUrl: process.env.MERKLE_RPC_URL,
+ *   bundleBlockOffset: 5
+ * });
+ *
+ * if (result.code) {
+ * } else {
+ *   console.error('❌ Bundle提交失败:', result.error);
+ * }
+ * ```
+ */
+export async function submitBundleToMerkle(signedTransactions, config) {
+    try {
+        const totalTransactions = signedTransactions?.length ?? 0;
+        // 验证输入
+        if (!signedTransactions || signedTransactions.length === 0) {
+            return {
+                code: false,
+                totalTransactions,
+                error: 'signedTransactions cannot be empty'
+            };
+        }
+        if (!config.apiKey) {
+            return {
+                code: false,
+                totalTransactions,
+                error: 'apiKey is required in config'
+            };
+        }
+        // ✅ 使用缓存的 MerkleClient（复用连接 + 区块号缓存）
+        const merkle = getMerkleClient(config);
+        // 提交Bundle
+        const bundleResult = await merkle.sendBundle({
+            transactions: signedTransactions,
+            blockOffset: config.bundleBlockOffset ?? 3,
+            minBlockOffset: config.minBlockOffset ?? 3,
+            autoRetry: config.autoRetryBundle ?? false,
+            maxRetries: config.maxBundleRetries ?? 2
+        });
+        // ✅ 提交成功
+        return {
+            code: true,
+            totalTransactions,
+            bundleHash: bundleResult.bundleHash,
+            txHashes: bundleResult.txHashes,
+            targetBlock: bundleResult.targetBlock,
+            txCount: bundleResult.txCount
+        };
+    }
+    catch (error) {
+        // ❌ 提交失败
+        return {
+            code: false,
+            totalTransactions: signedTransactions?.length ?? 0,
+            error: error?.message || String(error)
+        };
+    }
+}
+/**
+ * 批量提交多个Bundle到Merkle（顺序执行）
+ *
+ * @param bundles 多个Bundle的签名交易数组
+ * @param config Merkle提交配置
+ * @returns Bundle提交结果数组
+ */
+export async function submitMultipleBundles(bundles, config) {
+    const results = [];
+    for (const signedTransactions of bundles) {
+        const result = await submitBundleToMerkle(signedTransactions, config);
+        results.push(result);
+    }
+    return results;
+}
+/**
+ * 并行提交多个Bundle到Merkle（适用于独立的Bundle）
+ *
+ * @param bundles 多个Bundle的签名交易数组
+ * @param config Merkle提交配置
+ * @returns Bundle提交结果数组
+ */
+export async function submitMultipleBundlesParallel(bundles, config) {
+    const promises = bundles.map(signedTransactions => submitBundleToMerkle(signedTransactions, config));
+    return await Promise.all(promises);
+}
+// ==================== BlockRazor Bundle 提交方法 ====================
+// ✅ BlockRazorClient 缓存（复用连接，减少初始化开销）
+const blockRazorClientCache = new Map();
+/**
+ * 获取或创建 BlockRazorClient（带缓存）
+ */
+function getBlockRazorClient(config) {
+    const cacheKey = `${config.apiKey || 'default'}-${config.customRpcUrl || ''}-${config.builderRpcUrl || ''}`;
+    const now = Date.now();
+    const cached = blockRazorClientCache.get(cacheKey);
+    if (cached && cached.expireAt > now) {
+        return cached.client;
+    }
+    // 创建新客户端并缓存
+    const client = new BlockRazorClient({
+        apiKey: config.apiKey,
+        chainId: 56, // BlockRazor 目前只支持 BSC
+        customRpcUrl: config.customRpcUrl,
+        builderRpcUrl: config.builderRpcUrl
+    });
+    blockRazorClientCache.set(cacheKey, { client, expireAt: now + CLIENT_CACHE_TTL_MS });
+    return client;
+}
+/**
+ * 提交已签名的交易到 BlockRazor（服务器端使用）
+ *
+ * BlockRazor 是 BSC 链的 Block Builder 服务，支持 Bundle 提交
+ *
+ * 特点：
+ * - 向 Builder EOA 转账 BNB 可提高优先级
+ * - 支持 Bundle 合并提高打包率
+ * - 最低 Gas Price 要求: 0.05 Gwei
+ *
+ * @param signedTransactions 签名后的交易数组
+ * @param config BlockRazor 提交配置
+ * @returns Bundle 提交结果
+ *
+ * @example
+ * ```typescript
+ * // 服务器端代码
+ * import { submitBundleToBlockRazor } from 'four-flap-meme-sdk';
+ *
+ * const result = await submitBundleToBlockRazor(signedTransactions, {
+ *   blockOffset: 10,
+ *   noMerge: false,  // 允许合并
+ *   autoRetry: true
+ * });
+ *
+ * if (result.code) {
+ * } else {
+ *   console.error('❌ Bundle 提交失败:', result.error);
+ * }
+ * ```
+ */
+export async function submitBundleToBlockRazor(signedTransactions, config) {
+    try {
+        const totalTransactions = signedTransactions?.length ?? 0;
+        // 验证输入
+        if (!signedTransactions || signedTransactions.length === 0) {
+            return {
+                code: false,
+                totalTransactions,
+                error: 'signedTransactions cannot be empty'
+            };
+        }
+        // ✅ 使用缓存的 BlockRazorClient
+        const client = getBlockRazorClient(config);
+        // 提交 Bundle
+        const bundleResult = await client.sendBundle({
+            transactions: signedTransactions,
+            blockOffset: config.blockOffset ?? 100,
+            maxBlockOffset: config.maxBlockOffset ?? 100,
+            noMerge: config.noMerge ?? false,
+            revertingTxHashes: config.revertingTxHashes,
+            autoRetry: config.autoRetry ?? false,
+            maxRetries: config.maxRetries ?? 3
+        });
+        // ✅ 提交成功
+        return {
+            code: true,
+            totalTransactions,
+            bundleHash: bundleResult.bundleHash,
+            txHashes: bundleResult.txHashes,
+            maxBlockNumber: bundleResult.maxBlockNumber,
+            txCount: bundleResult.txCount
+        };
+    }
+    catch (error) {
+        // ❌ 提交失败
+        return {
+            code: false,
+            totalTransactions: signedTransactions?.length ?? 0,
+            error: error?.message || String(error)
+        };
+    }
+}
+/**
+ * 批量提交多个 Bundle 到 BlockRazor（顺序执行）
+ *
+ * @param bundles 多个 Bundle 的签名交易数组
+ * @param config BlockRazor 提交配置
+ * @returns Bundle 提交结果数组
+ */
+export async function submitMultipleBundlesToBlockRazor(bundles, config) {
+    const results = [];
+    for (const signedTransactions of bundles) {
+        const result = await submitBundleToBlockRazor(signedTransactions, config);
+        results.push(result);
+    }
+    return results;
+}
+/**
+ * 并行提交多个 Bundle 到 BlockRazor（适用于独立的 Bundle）
+ *
+ * @param bundles 多个 Bundle 的签名交易数组
+ * @param config BlockRazor 提交配置
+ * @returns Bundle 提交结果数组
+ */
+export async function submitMultipleBundlesToBlockRazorParallel(bundles, config) {
+    const promises = bundles.map(signedTransactions => submitBundleToBlockRazor(signedTransactions, config));
+    return await Promise.all(promises);
+}
+function shouldTreatBroadcastErrorAsMaybeSent(msg) {
+    const m = String(msg || '').toLowerCase();
+    return (m.includes('already known') ||
+        m.includes('known transaction') ||
+        m.includes('already exists') ||
+        m.includes('nonce too low') ||
+        m.includes('nonce has already been used') ||
+        m.includes('nonce expired') ||
+        m.includes('replacement transaction underpriced'));
+}
+async function recoverTxHashIfAlreadySeen(provider, signedTx, errorMessage) {
+    if (!shouldTreatBroadcastErrorAsMaybeSent(errorMessage))
+        return undefined;
+    try {
+        const hash = ethers.keccak256(signedTx);
+        if (!hash)
+            return undefined;
+        const tx = await provider.getTransaction(hash);
+        return tx ? hash : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * 并行广播到 RPC（用于不支持 Bundle 的链，如 Monad）
+ *
+ * ✅ 优化：默认使用并行广播，速度更快
+ *
+ * @param signedTransactions 签名后的交易数组
+ * @param config 直接广播配置
+ * @returns 广播结果
+ *
+ * @example
+ * ```typescript
+ * // 服务器端代码（Monad 链）
+ * import { submitDirectToRpc } from 'four-flap-meme-sdk';
+ *
+ * const result = await submitDirectToRpc(signedTransactions, {
+ *   rpcUrl: 'https://rpc-mainnet.monadinfra.com',
+ *   chainId: 143,
+ *   chainName: 'MONAD'
+ * });
+ *
+ * if (result.code) {
+ * } else {
+ *   console.error('❌ 全部广播失败:', result.errorSummary);
+ * }
+ * ```
+ */
+export async function submitDirectToRpc(signedTransactions, config) {
+    const totalTransactions = signedTransactions?.length ?? 0;
+    // 验证输入
+    if (!signedTransactions || signedTransactions.length === 0) {
+        return {
+            code: false,
+            totalTransactions: 0,
+            successCount: 0,
+            failedCount: 0,
+            txHashes: [],
+            results: [],
+            errorSummary: 'signedTransactions cannot be empty'
+        };
+    }
+    if (!config.rpcUrl) {
+        return {
+            code: false,
+            totalTransactions,
+            successCount: 0,
+            failedCount: totalTransactions,
+            txHashes: [],
+            results: [],
+            errorSummary: 'rpcUrl is required in config'
+        };
+    }
+    const chainId = config.chainId ?? 143;
+    const chainName = config.chainName ?? 'MONAD';
+    // 创建 Provider
+    const provider = new ethers.JsonRpcProvider(config.rpcUrl, {
+        chainId,
+        name: chainName
+    });
+    // ✅ 并行广播所有交易
+    const broadcastPromises = signedTransactions.map(async (signedTx, i) => {
+        try {
+            const txResponse = await provider.broadcastTransaction(signedTx);
+            // 如果需要等待确认
+            if (config.waitForConfirmation) {
+                try {
+                    const receipt = await provider.waitForTransaction(txResponse.hash, 1, config.confirmationTimeout ?? 30000);
+                    if (receipt && receipt.status === 0) {
+                        console.warn(`⚠️ [${chainName}] 交易 ${txResponse.hash} 执行失败（已上链但状态为0）`);
+                    }
+                }
+                catch (waitError) {
+                    console.warn(`⚠️ [${chainName}] 等待交易确认超时: ${txResponse.hash}`);
+                }
+            }
+            return {
+                index: i,
+                success: true,
+                txHash: txResponse.hash
+            };
+        }
+        catch (error) {
+            const errorMessage = error?.message || String(error);
+            console.error(`❌ [${chainName}] 交易 ${i + 1}/${totalTransactions} 广播失败:`, errorMessage);
+            // ✅ 兼容：nonce too low / already known 等情况下，交易可能已经被接收
+            const recovered = await recoverTxHashIfAlreadySeen(provider, signedTx, errorMessage);
+            if (recovered) {
+                if (config.waitForConfirmation) {
+                    try {
+                        await provider.waitForTransaction(recovered, 1, config.confirmationTimeout ?? 30000);
+                    }
+                    catch { }
+                }
+                return { index: i, success: true, txHash: recovered, error: errorMessage };
+            }
+            return {
+                index: i,
+                success: false,
+                error: errorMessage
+            };
+        }
+    });
+    const results = await Promise.all(broadcastPromises);
+    // 按索引排序结果
+    results.sort((a, b) => a.index - b.index);
+    const txHashes = results.filter(r => r.success && r.txHash).map(r => r.txHash);
+    const errors = results.filter(r => !r.success).map(r => `交易 ${r.index + 1}: ${r.error}`);
+    const successCount = txHashes.length;
+    const failedCount = totalTransactions - successCount;
+    return {
+        code: successCount > 0,
+        totalTransactions,
+        successCount,
+        failedCount,
+        txHashes,
+        results,
+        errorSummary: errors.length > 0 ? errors.join('; ') : undefined
+    };
+}
+/**
+ * ✅ 顺序广播并等待确认（用于多跳交易等需要顺序执行的场景）
+ *
+ * 每笔交易广播后会等待上链确认，确保后续交易能正确执行
+ *
+ * ⚠️ 多跳场景：如果某笔交易失败，会立即停止（因为后续交易肯定也会失败）
+ *
+ * @param signedTransactions 签名后的交易数组
+ * @param config 直接广播配置
+ * @returns 广播结果
+ */
+export async function submitDirectToRpcSequential(signedTransactions, config) {
+    const totalTransactions = signedTransactions?.length ?? 0;
+    if (!signedTransactions || signedTransactions.length === 0) {
+        return {
+            code: false,
+            totalTransactions: 0,
+            successCount: 0,
+            failedCount: 0,
+            txHashes: [],
+            results: [],
+            errorSummary: 'signedTransactions cannot be empty'
+        };
+    }
+    if (!config.rpcUrl) {
+        return {
+            code: false,
+            totalTransactions,
+            successCount: 0,
+            failedCount: totalTransactions,
+            txHashes: [],
+            results: [],
+            errorSummary: 'rpcUrl is required in config'
+        };
+    }
+    const chainId = config.chainId ?? 143;
+    const chainName = config.chainName ?? 'MONAD';
+    // ✅ XLayer 链默认 120 秒超时（网络可能较慢）
+    const confirmationTimeout = config.confirmationTimeout ?? (chainId === 196 ? 120000 : 60000);
+    const provider = new ethers.JsonRpcProvider(config.rpcUrl, {
+        chainId,
+        name: chainName
+    });
+    const results = [];
+    const txHashes = [];
+    const errors = [];
+    console.log(`📤 [${chainName}] 开始顺序广播 ${totalTransactions} 笔交易（等待每笔确认）`);
+    // 顺序广播并等待确认
+    for (let i = 0; i < signedTransactions.length; i++) {
+        const signedTx = signedTransactions[i];
+        try {
+            // 广播交易
+            const txResponse = await provider.broadcastTransaction(signedTx);
+            console.log(`📡 [${chainName}] 交易 ${i + 1}/${totalTransactions} 广播成功: ${txResponse.hash}，等待确认...`);
+            // ✅ 等待交易确认
+            const receipt = await provider.waitForTransaction(txResponse.hash, 1, // 等待1个确认
+            confirmationTimeout);
+            if (receipt && receipt.status === 1) {
+                console.log(`✅ [${chainName}] 交易 ${i + 1}/${totalTransactions} 已确认: ${txResponse.hash}`);
+                results.push({
+                    index: i,
+                    success: true,
+                    txHash: txResponse.hash
+                });
+                txHashes.push(txResponse.hash);
+            }
+            else {
+                const errorMsg = `交易执行失败（status=${receipt?.status})`;
+                console.error(`❌ [${chainName}] 交易 ${i + 1}/${totalTransactions} 上链失败: ${errorMsg}`);
+                results.push({
+                    index: i,
+                    success: false,
+                    txHash: txResponse.hash,
+                    error: errorMsg
+                });
+                errors.push(`交易 ${i + 1}: ${errorMsg}`);
+                // ✅ 多跳场景：如果某笔失败，后续交易肯定也会失败，立即停止
+                console.warn(`⚠️ [${chainName}] 多跳模式检测到失败，停止后续 ${totalTransactions - i - 1} 笔交易`);
+                break;
+            }
+        }
+        catch (error) {
+            const errorMessage = error?.message || String(error);
+            console.error(`❌ [${chainName}] 交易 ${i + 1}/${totalTransactions} 广播/确认失败:`, errorMessage);
+            // ✅ 兼容：nonce too low / already known 等情况下，交易可能已经被接收
+            const recovered = await recoverTxHashIfAlreadySeen(provider, signedTx, errorMessage);
+            if (recovered) {
+                console.log(`🔄 [${chainName}] 交易 ${i + 1} 可能已广播，尝试等待确认: ${recovered}`);
+                // 顺序模式依赖确认：尽量等待一下
+                try {
+                    const receipt = await provider.waitForTransaction(recovered, 1, confirmationTimeout);
+                    if (receipt && receipt.status === 1) {
+                        console.log(`✅ [${chainName}] 交易 ${i + 1}/${totalTransactions} 恢复成功: ${recovered}`);
+                        results.push({ index: i, success: true, txHash: recovered, error: errorMessage });
+                        txHashes.push(recovered);
+                        continue;
+                    }
+                    const errorMsg = `交易执行失败（status=${receipt?.status})`;
+                    console.error(`❌ [${chainName}] 交易 ${i + 1} 恢复失败: ${errorMsg}`);
+                    results.push({ index: i, success: false, txHash: recovered, error: `${errorMessage} | ${errorMsg}` });
+                    errors.push(`交易 ${i + 1}: ${errorMessage} | ${errorMsg}`);
+                    // ✅ 多跳场景：失败则停止
+                    console.warn(`⚠️ [${chainName}] 多跳模式检测到失败，停止后续 ${totalTransactions - i - 1} 笔交易`);
+                    break;
+                }
+                catch (waitError) {
+                    // 等待超时：对于多跳场景，不能假设成功，需要停止
+                    const waitErrorMsg = waitError?.message || String(waitError);
+                    console.error(`⏱️ [${chainName}] 交易 ${i + 1} 等待确认超时: ${waitErrorMsg}`);
+                    results.push({ index: i, success: false, txHash: recovered, error: `${errorMessage} | 等待确认超时: ${waitErrorMsg}` });
+                    errors.push(`交易 ${i + 1}: ${errorMessage} | 等待确认超时`);
+                    // ✅ 多跳场景：超时也停止
+                    console.warn(`⚠️ [${chainName}] 多跳模式检测到超时，停止后续 ${totalTransactions - i - 1} 笔交易`);
+                    break;
+                }
+            }
+            results.push({
+                index: i,
+                success: false,
+                error: errorMessage
+            });
+            errors.push(`交易 ${i + 1}: ${errorMessage}`);
+            // ✅ 多跳场景：如果某笔失败，后续交易肯定也会失败，立即停止
+            console.warn(`⚠️ [${chainName}] 多跳模式检测到失败，停止后续 ${totalTransactions - i - 1} 笔交易`);
+            break;
+        }
+    }
+    const successCount = txHashes.length;
+    const failedCount = totalTransactions - successCount;
+    console.log(`📊 [${chainName}] 顺序广播完成: 成功 ${successCount}/${totalTransactions}`);
+    return {
+        code: successCount > 0,
+        totalTransactions,
+        successCount,
+        failedCount,
+        txHashes,
+        results,
+        errorSummary: errors.length > 0 ? errors.join('; ') : undefined
+    };
+}
+/**
+ * ✅ 顺序广播但不等待确认（用于 AA handleOps + tail 等 nonce 连续的场景）
+ *
+ * 按顺序逐笔发送交易，每笔只等待广播成功（RPC 返回 txHash），不等待链上确认。
+ * 这样可以保证交易按顺序进入 mempool，同时避免等待确认超时。
+ *
+ * @param signedTransactions 签名后的交易数组
+ * @param config 直接广播配置
+ * @returns 广播结果
+ */
+export async function submitDirectToRpcSequentialNoWait(signedTransactions, config) {
+    const totalTransactions = signedTransactions?.length ?? 0;
+    if (!signedTransactions || signedTransactions.length === 0) {
+        return {
+            code: false,
+            totalTransactions: 0,
+            successCount: 0,
+            failedCount: 0,
+            txHashes: [],
+            results: [],
+            errorSummary: 'signedTransactions cannot be empty'
+        };
+    }
+    if (!config.rpcUrl) {
+        return {
+            code: false,
+            totalTransactions,
+            successCount: 0,
+            failedCount: totalTransactions,
+            txHashes: [],
+            results: [],
+            errorSummary: 'rpcUrl is required in config'
+        };
+    }
+    const chainId = config.chainId ?? 143;
+    const chainName = config.chainName ?? 'MONAD';
+    const provider = new ethers.JsonRpcProvider(config.rpcUrl, {
+        chainId,
+        name: chainName
+    });
+    const results = [];
+    const txHashes = [];
+    const errors = [];
+    // ✅ 顺序广播，每笔只等待广播成功（不等待链上确认）
+    for (let i = 0; i < signedTransactions.length; i++) {
+        const signedTx = signedTransactions[i];
+        try {
+            // 广播交易，等待 RPC 返回 txHash
+            const txResponse = await provider.broadcastTransaction(signedTx);
+            results.push({
+                index: i,
+                success: true,
+                txHash: txResponse.hash
+            });
+            txHashes.push(txResponse.hash);
+            console.log(`✅ [${chainName}] 交易 ${i + 1}/${totalTransactions} 广播成功: ${txResponse.hash}`);
+        }
+        catch (error) {
+            const errorMessage = error?.message || String(error);
+            console.error(`❌ [${chainName}] 交易 ${i + 1}/${totalTransactions} 广播失败:`, errorMessage);
+            // ✅ 兼容：nonce too low / already known 等情况下，交易可能已经被接收
+            const recovered = await recoverTxHashIfAlreadySeen(provider, signedTx, errorMessage);
+            if (recovered) {
+                results.push({ index: i, success: true, txHash: recovered, error: errorMessage });
+                txHashes.push(recovered);
+                continue;
+            }
+            results.push({
+                index: i,
+                success: false,
+                error: errorMessage
+            });
+            errors.push(`交易 ${i + 1}: ${errorMessage}`);
+            // ✅ 如果某笔失败，继续尝试后续交易（可能是 nonce 问题可以自动恢复）
+        }
+    }
+    const successCount = txHashes.length;
+    const failedCount = totalTransactions - successCount;
+    return {
+        code: successCount > 0,
+        totalTransactions,
+        successCount,
+        failedCount,
+        txHashes,
+        results,
+        errorSummary: errors.length > 0 ? errors.join('; ') : undefined
+    };
+}
+/**
+ * 并行逐笔广播到 RPC（速度更快，但可能有 nonce 冲突）
+ *
+ * ⚠️ 注意：仅适用于不同钱包的交易，同一钱包的多笔交易应使用顺序广播
+ *
+ * @param signedTransactions 签名后的交易数组
+ * @param config 直接广播配置
+ * @returns 广播结果
+ */
+export async function submitDirectToRpcParallel(signedTransactions, config) {
+    const totalTransactions = signedTransactions?.length ?? 0;
+    if (!signedTransactions || signedTransactions.length === 0) {
+        return {
+            code: false,
+            totalTransactions: 0,
+            successCount: 0,
+            failedCount: 0,
+            txHashes: [],
+            results: [],
+            errorSummary: 'signedTransactions cannot be empty'
+        };
+    }
+    if (!config.rpcUrl) {
+        return {
+            code: false,
+            totalTransactions,
+            successCount: 0,
+            failedCount: totalTransactions,
+            txHashes: [],
+            results: [],
+            errorSummary: 'rpcUrl is required in config'
+        };
+    }
+    const chainId = config.chainId ?? 143;
+    const chainName = config.chainName ?? 'MONAD';
+    const provider = new ethers.JsonRpcProvider(config.rpcUrl, {
+        chainId,
+        name: chainName
+    });
+    // 并行广播
+    const broadcastPromises = signedTransactions.map(async (signedTx, i) => {
+        try {
+            const txResponse = await provider.broadcastTransaction(signedTx);
+            return {
+                index: i,
+                success: true,
+                txHash: txResponse.hash
+            };
+        }
+        catch (error) {
+            return {
+                index: i,
+                success: false,
+                error: error?.message || String(error)
+            };
+        }
+    });
+    const results = await Promise.all(broadcastPromises);
+    const txHashes = results.filter(r => r.success && r.txHash).map(r => r.txHash);
+    const errors = results.filter(r => !r.success).map(r => `交易 ${r.index + 1}: ${r.error}`);
+    const successCount = txHashes.length;
+    const failedCount = totalTransactions - successCount;
+    return {
+        code: successCount > 0,
+        totalTransactions,
+        successCount,
+        failedCount,
+        txHashes,
+        results,
+        errorSummary: errors.length > 0 ? errors.join('; ') : undefined
+    };
+}
+/**
+ * ENI 快速并行广播：业务交易并行 + 利润交易顺序跟随
+ *
+ * 流程：
+ *   1. 解码所有签名交易，识别哪些 from 地址有多笔交易（即含利润尾随交易的 payer）
+ *   2. 把交易分为 "独立交易" 和 "依赖交易"（同 from 的第 2 笔及之后的交易）
+ *   3. 并行广播所有独立交易（业务交易）
+ *   4. 等待 payer 的业务交易上链后，再提交其利润交易（顺序跟随）
+ *   5. 返回合并结果
+ */
+export async function submitEniParallelThenProfit(signedTransactions, config) {
+    const totalTransactions = signedTransactions?.length ?? 0;
+    const emptyFail = (msg) => ({
+        code: false, totalTransactions, successCount: 0, failedCount: totalTransactions,
+        txHashes: [], results: [], errorSummary: msg,
+    });
+    if (!signedTransactions || signedTransactions.length === 0)
+        return emptyFail('signedTransactions cannot be empty');
+    if (!config.rpcUrl)
+        return emptyFail('rpcUrl is required');
+    const chainId = config.chainId ?? 173;
+    const chainName = config.chainName ?? 'ENI';
+    const provider = new ethers.JsonRpcProvider(config.rpcUrl, { chainId, name: chainName });
+    // Step 1: 按 from 地址分组，识别独立交易和依赖交易
+    const fromCounts = new Map();
+    const txMeta = [];
+    for (let i = 0; i < signedTransactions.length; i++) {
+        try {
+            const tx = ethers.Transaction.from(signedTransactions[i]);
+            const from = (tx.from || '').toLowerCase();
+            const seq = fromCounts.get(from) || 0;
+            txMeta.push({ from, index: i, seqInFrom: seq });
+            fromCounts.set(from, seq + 1);
+        }
+        catch {
+            txMeta.push({ from: '', index: i, seqInFrom: 0 });
+        }
+    }
+    // 独立交易：每个 from 的第一笔（seqInFrom === 0）
+    // 依赖交易：每个 from 的第 2 笔及之后（seqInFrom > 0，通常是利润交易）
+    const independentIndices = txMeta.filter(m => m.seqInFrom === 0).map(m => m.index);
+    const dependentGroups = new Map();
+    for (const m of txMeta) {
+        if (m.seqInFrom > 0) {
+            if (!dependentGroups.has(m.from))
+                dependentGroups.set(m.from, []);
+            dependentGroups.get(m.from).push(m.index);
+        }
+    }
+    console.log(`🚀 [${chainName}] 并行广播 ${independentIndices.length} 笔业务交易，${totalTransactions - independentIndices.length} 笔利润交易顺序跟随`);
+    // Step 2: 并行广播所有独立交易
+    const allResults = new Array(totalTransactions);
+    const independentPromises = independentIndices.map(async (idx) => {
+        try {
+            const resp = await provider.broadcastTransaction(signedTransactions[idx]);
+            allResults[idx] = { index: idx, success: true, txHash: resp.hash };
+        }
+        catch (error) {
+            const errorMessage = error?.message || String(error);
+            const recovered = await recoverTxHashIfAlreadySeen(provider, signedTransactions[idx], errorMessage);
+            if (recovered) {
+                allResults[idx] = { index: idx, success: true, txHash: recovered, error: errorMessage };
+            }
+            else {
+                allResults[idx] = { index: idx, success: false, error: errorMessage };
+                console.error(`❌ [${chainName}] 业务交易 ${idx + 1} 广播失败: ${errorMessage.slice(0, 120)}`);
+            }
+        }
+    });
+    await Promise.all(independentPromises);
+    // Step 3: 顺序提交依赖交易（利润交易）
+    // 需要等待同 from 的业务交易先上链（nonce 依赖）
+    for (const [from, indices] of dependentGroups) {
+        // 找到该 from 的业务交易（seqInFrom===0）
+        const parentMeta = txMeta.find(m => m.from === from && m.seqInFrom === 0);
+        if (parentMeta) {
+            const parentResult = allResults[parentMeta.index];
+            if (parentResult?.success && parentResult.txHash) {
+                // 等待业务交易上链确认
+                try {
+                    await Promise.race([
+                        provider.waitForTransaction(parentResult.txHash, 1, 10000),
+                        new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), 10000)),
+                    ]);
+                }
+                catch {
+                    console.warn(`⚠️ [${chainName}] 等待 ${from.slice(0, 10)}... 业务交易确认超时，仍尝试发送利润交易`);
+                }
+            }
+        }
+        // 按顺序提交该 from 的依赖交易
+        for (const idx of indices) {
+            try {
+                const resp = await provider.broadcastTransaction(signedTransactions[idx]);
+                allResults[idx] = { index: idx, success: true, txHash: resp.hash };
+                console.log(`💰 [${chainName}] 利润交易 ${idx + 1} 广播成功: ${resp.hash}`);
+            }
+            catch (error) {
+                const errorMessage = error?.message || String(error);
+                const recovered = await recoverTxHashIfAlreadySeen(provider, signedTransactions[idx], errorMessage);
+                if (recovered) {
+                    allResults[idx] = { index: idx, success: true, txHash: recovered, error: errorMessage };
+                }
+                else {
+                    allResults[idx] = { index: idx, success: false, error: errorMessage };
+                    console.error(`❌ [${chainName}] 利润交易 ${idx + 1} 广播失败: ${errorMessage.slice(0, 120)}`);
+                }
+            }
+        }
+    }
+    // Step 4: 汇总结果
+    const txHashes = allResults.filter(r => r?.success && r.txHash).map(r => r.txHash);
+    const errors = allResults.filter(r => r && !r.success).map(r => `交易 ${r.index + 1}: ${r.error}`);
+    return {
+        code: txHashes.length > 0,
+        totalTransactions,
+        successCount: txHashes.length,
+        failedCount: totalTransactions - txHashes.length,
+        txHashes,
+        results: allResults.filter(Boolean),
+        errorSummary: errors.length > 0 ? errors.join('; ') : undefined,
+    };
+}
+/**
+ * ENI Bundle 提交：模拟验证 → 快速顺序广播 → 同块确认
+ *
+ * 复用同一 Provider 快速顺序广播，最小化延迟、最大化同块概率。
+ * ENI 出块 ~1.08s，连续 nonce 快速提交同块率极高。
+ */
+export async function submitBundleToEni(signedTransactions, config) {
+    const totalTransactions = signedTransactions?.length ?? 0;
+    const emptyFail = (msg) => ({
+        code: false, totalTransactions, successCount: 0, failedCount: totalTransactions,
+        txHashes: [], results: [], sameBlock: false, errorSummary: msg,
+    });
+    if (!signedTransactions || signedTransactions.length === 0)
+        return emptyFail('signedTransactions cannot be empty');
+    if (!config.rpcUrl)
+        return emptyFail('rpcUrl is required');
+    const chainId = config.chainId ?? 173;
+    const chainName = config.chainName ?? 'ENI';
+    const simulationTimeout = config.simulationTimeout ?? 10000;
+    const blockConfirmTimeout = config.blockConfirmTimeout ?? 15000;
+    const provider = new ethers.JsonRpcProvider(config.rpcUrl, { chainId, name: chainName });
+    // Phase 1: 模拟验证
+    const simStart = Date.now();
+    const simErrors = [];
+    for (let i = 0; i < signedTransactions.length; i++) {
+        try {
+            const tx = ethers.Transaction.from(signedTransactions[i]);
+            await Promise.race([
+                provider.call({ to: tx.to, data: tx.data, value: tx.value, from: tx.from }),
+                new Promise((_, reject) => setTimeout(() => reject(new Error('simulation timeout')), simulationTimeout)),
+            ]);
+        }
+        catch (e) {
+            const msg = e?.message || String(e);
+            if (msg.includes('simulation timeout')) {
+                console.warn(`⚠️ [${chainName}] 交易 ${i + 1} 模拟超时，跳过验证`);
+            }
+            else if (msg.includes('execution reverted') || msg.includes('CALL_EXCEPTION')) {
+                simErrors.push(`交易 ${i + 1} 模拟失败: ${msg.slice(0, 200)}`);
+            }
+        }
+    }
+    const simulationDurationMs = Date.now() - simStart;
+    if (simErrors.length > 0) {
+        return { ...emptyFail(simErrors.join('; ')), simulationDurationMs };
+    }
+    console.log(`✅ [${chainName}] Bundle 模拟通过 (${totalTransactions} 笔, ${simulationDurationMs}ms)`);
+    // Phase 2: 快速顺序广播（复用同一 provider 减少连接开销）
+    const broadStart = Date.now();
+    const results = [];
+    const txHashes = [];
+    for (let i = 0; i < signedTransactions.length; i++) {
+        try {
+            const txResponse = await provider.broadcastTransaction(signedTransactions[i]);
+            results.push({ index: i, success: true, txHash: txResponse.hash });
+            txHashes.push(txResponse.hash);
+        }
+        catch (error) {
+            const errorMessage = error?.message || String(error);
+            const recovered = await recoverTxHashIfAlreadySeen(provider, signedTransactions[i], errorMessage);
+            if (recovered) {
+                results.push({ index: i, success: true, txHash: recovered, error: errorMessage });
+                txHashes.push(recovered);
+            }
+            else {
+                results.push({ index: i, success: false, error: errorMessage });
+                console.error(`❌ [${chainName}] Bundle tx ${i + 1}/${totalTransactions} 失败: ${errorMessage}`);
+            }
+        }
+    }
+    const broadcastDurationMs = Date.now() - broadStart;
+    const successCount = txHashes.length;
+    const failedCount = totalTransactions - successCount;
+    if (successCount === 0) {
+        return {
+            code: false, totalTransactions, successCount, failedCount, txHashes, results,
+            sameBlock: false, simulationDurationMs, broadcastDurationMs,
+            errorSummary: results.filter(r => !r.success).map(r => r.error).join('; '),
+        };
+    }
+    // Phase 3: 同块确认
+    let sameBlock = false;
+    let blockNumber;
+    const blockNumbers = [];
+    try {
+        const receipts = await Promise.all(txHashes.map(hash => Promise.race([
+            provider.waitForTransaction(hash, 1, blockConfirmTimeout),
+            new Promise((resolve) => setTimeout(() => resolve(null), blockConfirmTimeout)),
+        ])));
+        for (const receipt of receipts) {
+            if (receipt && receipt.blockNumber) {
+                blockNumbers.push(receipt.blockNumber);
+            }
+        }
+        if (blockNumbers.length === txHashes.length && blockNumbers.length > 0) {
+            const uniqueBlocks = new Set(blockNumbers);
+            sameBlock = uniqueBlocks.size === 1;
+            blockNumber = sameBlock ? blockNumbers[0] : undefined;
+            console.log(`📦 [${chainName}] Bundle 区块: blocks=[${[...uniqueBlocks].join(',')}] sameBlock=${sameBlock}`);
+        }
+    }
+    catch (e) {
+        console.warn(`⚠️ [${chainName}] Bundle 区块确认超时`);
+    }
+    return {
+        code: true, totalTransactions, successCount, failedCount, txHashes, results,
+        sameBlock, blockNumber,
+        blockNumbers: blockNumbers.length > 0 ? blockNumbers : undefined,
+        simulationDurationMs, broadcastDurationMs,
+    };
+}