four-flap-meme-sdk 2.2.2 → 2.2.4

package/dist/bundle-core/submit.js

@@ -0,0 +1,727 @@
+/**
+ * 独立的Bundle提交方法
+ *
+ * 用于服务器端接收前端构建的签名交易后，提交到Merkle或BlockRazor
+ * 以及 Monad 等不支持 Bundle 的链的逐笔广播
+ */
+import { MerkleClient } from '../shared/clients/merkle.js';
+import { BlockRazorClient } from '../shared/clients/blockrazor.js';
+import { ethers } from 'ethers';
+import { getErrorMessageFromUnknown } from '../shared/foundation/index.js';
+import { createSignProvider } from './sign-context-helpers.js';
+// ✅ 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;
+}
+async function submitBundlesSequential(bundles, submitFn) {
+    const results = [];
+    for (const signedTransactions of bundles) {
+        results.push(await submitFn(signedTransactions));
+    }
+    return results;
+}
+async function submitBundlesParallel(bundles, submitFn) {
+    return Promise.all(bundles.map((signedTransactions) => submitFn(signedTransactions)));
+}
+/**
+ * 提交已签名的交易到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: getErrorMessageFromUnknown(error),
+        };
+    }
+}
+/**
+ * 批量提交多个Bundle到Merkle（顺序执行）
+ *
+ * @param bundles 多个Bundle的签名交易数组
+ * @param config Merkle提交配置
+ * @returns Bundle提交结果数组
+ */
+export async function submitMultipleBundles(bundles, config) {
+    return submitBundlesSequential(bundles, (signedTransactions) => submitBundleToMerkle(signedTransactions, config));
+}
+/**
+ * 并行提交多个Bundle到Merkle（适用于独立的Bundle）
+ *
+ * @param bundles 多个Bundle的签名交易数组
+ * @param config Merkle提交配置
+ * @returns Bundle提交结果数组
+ */
+export async function submitMultipleBundlesParallel(bundles, config) {
+    return submitBundlesParallel(bundles, (signedTransactions) => submitBundleToMerkle(signedTransactions, config));
+}
+// ==================== 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: getErrorMessageFromUnknown(error),
+        };
+    }
+}
+/**
+ * 批量提交多个 Bundle 到 BlockRazor（顺序执行）
+ *
+ * @param bundles 多个 Bundle 的签名交易数组
+ * @param config BlockRazor 提交配置
+ * @returns Bundle 提交结果数组
+ */
+export async function submitMultipleBundlesToBlockRazor(bundles, config) {
+    return submitBundlesSequential(bundles, (signedTransactions) => submitBundleToBlockRazor(signedTransactions, config));
+}
+/**
+ * 并行提交多个 Bundle 到 BlockRazor（适用于独立的 Bundle）
+ *
+ * @param bundles 多个 Bundle 的签名交易数组
+ * @param config BlockRazor 提交配置
+ * @returns Bundle 提交结果数组
+ */
+export async function submitMultipleBundlesToBlockRazorParallel(bundles, config) {
+    return submitBundlesParallel(bundles, (signedTransactions) => submitBundleToBlockRazor(signedTransactions, config));
+}
+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.Transaction.from(signedTx).hash;
+        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';
+    const provider = createSignProvider(config.rpcUrl, chainId, 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 = getErrorMessageFromUnknown(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 = createSignProvider(config.rpcUrl, chainId, chainName);
+    const results = [];
+    const txHashes = [];
+    const errors = [];
+    // 顺序广播并等待确认
+    for (let i = 0; i < signedTransactions.length; i++) {
+        const signedTx = signedTransactions[i];
+        try {
+            // 广播交易
+            const txResponse = await provider.broadcastTransaction(signedTx);
+            // ✅ 等待交易确认
+            const receipt = await provider.waitForTransaction(txResponse.hash, 1, // 等待1个确认
+            confirmationTimeout);
+            if (receipt && receipt.status === 1) {
+                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 = getErrorMessageFromUnknown(error);
+            console.error(`❌ [${chainName}] 交易 ${i + 1}/${totalTransactions} 广播/确认失败:`, errorMessage);
+            // ✅ 兼容：nonce too low / already known 等情况下，交易可能已经被接收
+            const recovered = await recoverTxHashIfAlreadySeen(provider, signedTx, errorMessage);
+            if (recovered) {
+                // 顺序模式依赖确认：尽量等待一下
+                try {
+                    const receipt = await provider.waitForTransaction(recovered, 1, confirmationTimeout);
+                    if (receipt && receipt.status === 1) {
+                        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 = getErrorMessageFromUnknown(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;
+    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 = createSignProvider(config.rpcUrl, chainId, 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);
+        }
+        catch (error) {
+            const errorMessage = getErrorMessageFromUnknown(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 = createSignProvider(config.rpcUrl, chainId, 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: getErrorMessageFromUnknown(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,
+    };
+}
+/**
+ * 智能广播到 RPC（自动选择并行或顺序）
+ */
+export async function submitDirectToRpcSmart(signedTransactions, config, options) {
+    const emptyFail = (mode) => ({
+        code: false,
+        totalTransactions: 0,
+        successCount: 0,
+        failedCount: 0,
+        txHashes: [],
+        results: [],
+        errorSummary: 'signedTransactions cannot be empty',
+        mode,
+    });
+    if (!signedTransactions || signedTransactions.length === 0) {
+        return emptyFail('parallel');
+    }
+    const hasMultipleFromSameWallet = (() => {
+        if (signedTransactions.length < 2)
+            return false;
+        const seen = new Set();
+        for (const raw of signedTransactions) {
+            if (!raw)
+                continue;
+            try {
+                const tx = ethers.Transaction.from(raw);
+                const from = (tx.from || '').toLowerCase();
+                if (!from)
+                    continue;
+                if (seen.has(from))
+                    return true;
+                seen.add(from);
+            }
+            catch {
+                // ignore parse errors
+            }
+        }
+        return false;
+    })();
+    if (hasMultipleFromSameWallet) {
+        const result = options?.waitConfirmation
+            ? await submitDirectToRpcSequential(signedTransactions, config)
+            : await submitDirectToRpcSequentialNoWait(signedTransactions, config);
+        return { ...result, mode: 'sequential' };
+    }
+    const result = await submitDirectToRpcParallel(signedTransactions, config);
+    return { ...result, mode: 'parallel' };
+}