four-flap-meme-sdk 2.2.0 → 2.2.2

package/dist/contracts/tm-bundle-merkle/submit.d.ts

@@ -1,3 +1,314 @@
-/** Bundle 提交 — 实现见 bundle-core/submit；ENI 见 chains/eni/submit */
-export { submitBundleToMerkle, submitMultipleBundles, submitMultipleBundlesParallel, submitBundleToBlockRazor, submitMultipleBundlesToBlockRazor, submitMultipleBundlesToBlockRazorParallel, submitDirectToRpc, submitDirectToRpcSequential, submitDirectToRpcSequentialNoWait, submitDirectToRpcParallel, submitDirectToRpcSmart, type MerkleSubmitConfig, type SubmitBundleResult, type BlockRazorSubmitConfig, type BlockRazorSubmitResult, type DirectSubmitConfig, type DirectSubmitResult, type DirectTxResult, } from '../../bundle-core/submit.js';
-export { submitBundleToEni, submitEniParallelThenProfit, type EniBundleSubmitConfig, type EniBundleSubmitResult, } from '../../chains/eni/submit.js';
+/**
+ * 独立的Bundle提交方法
+ *
+ * 用于服务器端接收前端构建的签名交易后，提交到Merkle或BlockRazor
+ * 以及 Monad 等不支持 Bundle 的链的逐笔广播
+ */
+/**
+ * 精简的Merkle提交配置（只包含提交需要的字段）
+ */
+export interface MerkleSubmitConfig {
+    /** Merkle API Key（必需） */
+    apiKey: string;
+    /** 自定义RPC URL（可选） */
+    customRpcUrl?: string;
+    /** 链ID（可选，默认56=BSC） */
+    chainId?: 56 | 1;
+    /** Bundle区块偏移量（可选，默认3） */
+    bundleBlockOffset?: number;
+    /** 最小区块偏移量（可选，默认3） */
+    minBlockOffset?: number;
+    /** 是否自动重试（可选，默认false） */
+    autoRetryBundle?: boolean;
+    /** 最大重试次数（可选，默认2） */
+    maxBundleRetries?: number;
+}
+/**
+ * Bundle提交结果
+ */
+export interface SubmitBundleResult {
+    /** 提交状态：true=成功，false=失败 */
+    code: boolean;
+    /** 交易总数（无论成功与否都会返回） */
+    totalTransactions: number;
+    /** Bundle哈希（成功时返回） */
+    bundleHash?: string;
+    /** 交易哈希列表（成功时返回） */
+    txHashes?: string[];
+    /** 目标区块号（成功时返回） */
+    targetBlock?: number;
+    /** 交易数量（成功时返回） */
+    txCount?: number;
+    /** 错误信息（失败时返回） */
+    error?: string;
+}
+/**
+ * 提交已签名的交易到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 declare function submitBundleToMerkle(signedTransactions: string[], config: MerkleSubmitConfig): Promise<SubmitBundleResult>;
+/**
+ * 批量提交多个Bundle到Merkle（顺序执行）
+ *
+ * @param bundles 多个Bundle的签名交易数组
+ * @param config Merkle提交配置
+ * @returns Bundle提交结果数组
+ */
+export declare function submitMultipleBundles(bundles: string[][], config: MerkleSubmitConfig): Promise<SubmitBundleResult[]>;
+/**
+ * 并行提交多个Bundle到Merkle（适用于独立的Bundle）
+ *
+ * @param bundles 多个Bundle的签名交易数组
+ * @param config Merkle提交配置
+ * @returns Bundle提交结果数组
+ */
+export declare function submitMultipleBundlesParallel(bundles: string[][], config: MerkleSubmitConfig): Promise<SubmitBundleResult[]>;
+/**
+ * BlockRazor 提交配置
+ * 参考: https://blockrazor.gitbook.io/blockrazor/bsc/block-builder/send-bundle
+ */
+export interface BlockRazorSubmitConfig {
+    /** API Key（可选，根据 Tier 需要） */
+    apiKey?: string;
+    /** 自定义 RPC URL（用于查询区块号等，可选） */
+    customRpcUrl?: string;
+    /** Builder RPC URL（用于发送 Bundle，可选） */
+    builderRpcUrl?: string;
+    /** 区块偏移量（默认 10，最大有效区块 = 当前区块 + offset） */
+    blockOffset?: number;
+    /** 最大区块偏移量（默认 100） */
+    maxBlockOffset?: number;
+    /** 是否禁止 Bundle 合并（默认 false，允许合并可提高打包率） */
+    noMerge?: boolean;
+    /** 允许 revert 的交易哈希列表 */
+    revertingTxHashes?: string[];
+    /** 是否自动重试（默认 false） */
+    autoRetry?: boolean;
+    /** 最大重试次数（默认 3） */
+    maxRetries?: number;
+}
+/**
+ * BlockRazor Bundle 提交结果
+ */
+export interface BlockRazorSubmitResult {
+    /** 提交状态：true=成功，false=失败 */
+    code: boolean;
+    /** 交易总数 */
+    totalTransactions: number;
+    /** Bundle 哈希（成功时返回） */
+    bundleHash?: string;
+    /** 交易哈希列表（成功时返回） */
+    txHashes?: string[];
+    /** 最大有效区块号（成功时返回） */
+    maxBlockNumber?: number;
+    /** 交易数量（成功时返回） */
+    txCount?: number;
+    /** 错误信息（失败时返回） */
+    error?: string;
+}
+/**
+ * 提交已签名的交易到 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 declare function submitBundleToBlockRazor(signedTransactions: string[], config: BlockRazorSubmitConfig): Promise<BlockRazorSubmitResult>;
+/**
+ * 批量提交多个 Bundle 到 BlockRazor（顺序执行）
+ *
+ * @param bundles 多个 Bundle 的签名交易数组
+ * @param config BlockRazor 提交配置
+ * @returns Bundle 提交结果数组
+ */
+export declare function submitMultipleBundlesToBlockRazor(bundles: string[][], config: BlockRazorSubmitConfig): Promise<BlockRazorSubmitResult[]>;
+/**
+ * 并行提交多个 Bundle 到 BlockRazor（适用于独立的 Bundle）
+ *
+ * @param bundles 多个 Bundle 的签名交易数组
+ * @param config BlockRazor 提交配置
+ * @returns Bundle 提交结果数组
+ */
+export declare function submitMultipleBundlesToBlockRazorParallel(bundles: string[][], config: BlockRazorSubmitConfig): Promise<BlockRazorSubmitResult[]>;
+/**
+ * 逐笔广播配置（用于不支持 Bundle 的链，如 Monad）
+ */
+export interface DirectSubmitConfig {
+    /** RPC URL（必需） */
+    rpcUrl: string;
+    /** 链ID（可选，默认143=Monad） */
+    chainId?: number;
+    /** 链名称（可选，用于日志） */
+    chainName?: string;
+    /** 是否等待交易确认（可选，默认false） */
+    waitForConfirmation?: boolean;
+    /** 确认超时时间ms（可选，默认30000） */
+    confirmationTimeout?: number;
+}
+/**
+ * 单笔交易结果
+ */
+export interface DirectTxResult {
+    /** 交易索引 */
+    index: number;
+    /** 是否成功 */
+    success: boolean;
+    /** 交易哈希（成功时返回） */
+    txHash?: string;
+    /** 错误信息（失败时返回） */
+    error?: string;
+}
+/**
+ * 逐笔广播提交结果
+ */
+export interface DirectSubmitResult {
+    /** 提交状态：至少有一笔成功则为true */
+    code: boolean;
+    /** 交易总数 */
+    totalTransactions: number;
+    /** 成功数量 */
+    successCount: number;
+    /** 失败数量 */
+    failedCount: number;
+    /** 交易哈希列表（成功的交易） */
+    txHashes: string[];
+    /** 每笔交易的详细结果 */
+    results: DirectTxResult[];
+    /** 错误摘要（如果有失败） */
+    errorSummary?: string;
+}
+/**
+ * 并行广播到 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 declare function submitDirectToRpc(signedTransactions: string[], config: DirectSubmitConfig): Promise<DirectSubmitResult>;
+/**
+ * ✅ 顺序广播并等待确认（用于多跳交易等需要顺序执行的场景）
+ *
+ * 每笔交易广播后会等待上链确认，确保后续交易能正确执行
+ *
+ * ⚠️ 多跳场景：如果某笔交易失败，会立即停止（因为后续交易肯定也会失败）
+ *
+ * @param signedTransactions 签名后的交易数组
+ * @param config 直接广播配置
+ * @returns 广播结果
+ */
+export declare function submitDirectToRpcSequential(signedTransactions: string[], config: DirectSubmitConfig): Promise<DirectSubmitResult>;
+/**
+ * ✅ 顺序广播但不等待确认（用于 AA handleOps + tail 等 nonce 连续的场景）
+ *
+ * 按顺序逐笔发送交易，每笔只等待广播成功（RPC 返回 txHash），不等待链上确认。
+ * 这样可以保证交易按顺序进入 mempool，同时避免等待确认超时。
+ *
+ * @param signedTransactions 签名后的交易数组
+ * @param config 直接广播配置
+ * @returns 广播结果
+ */
+export declare function submitDirectToRpcSequentialNoWait(signedTransactions: string[], config: DirectSubmitConfig): Promise<DirectSubmitResult>;
+/**
+ * 并行逐笔广播到 RPC（速度更快，但可能有 nonce 冲突）
+ *
+ * ⚠️ 注意：仅适用于不同钱包的交易，同一钱包的多笔交易应使用顺序广播
+ *
+ * @param signedTransactions 签名后的交易数组
+ * @param config 直接广播配置
+ * @returns 广播结果
+ */
+export declare function submitDirectToRpcParallel(signedTransactions: string[], config: DirectSubmitConfig): Promise<DirectSubmitResult>;
+export interface EniBundleSubmitConfig extends DirectSubmitConfig {
+    simulationTimeout?: number;
+    blockConfirmTimeout?: number;
+}
+export interface EniBundleSubmitResult extends DirectSubmitResult {
+    sameBlock: boolean;
+    blockNumber?: number;
+    blockNumbers?: number[];
+    simulationDurationMs?: number;
+    broadcastDurationMs?: number;
+}
+/**
+ * ENI 快速并行广播：业务交易并行 + 利润交易顺序跟随
+ *
+ * 流程：
+ *   1. 解码所有签名交易，识别哪些 from 地址有多笔交易（即含利润尾随交易的 payer）
+ *   2. 把交易分为 "独立交易" 和 "依赖交易"（同 from 的第 2 笔及之后的交易）
+ *   3. 并行广播所有独立交易（业务交易）
+ *   4. 等待 payer 的业务交易上链后，再提交其利润交易（顺序跟随）
+ *   5. 返回合并结果
+ */
+export declare function submitEniParallelThenProfit(signedTransactions: string[], config: DirectSubmitConfig): Promise<DirectSubmitResult>;
+/**
+ * ENI Bundle 提交：模拟验证 → 快速顺序广播 → 同块确认
+ *
+ * 复用同一 Provider 快速顺序广播，最小化延迟、最大化同块概率。
+ * ENI 出块 ~1.08s，连续 nonce 快速提交同块率极高。
+ */
+export declare function submitBundleToEni(signedTransactions: string[], config: EniBundleSubmitConfig): Promise<EniBundleSubmitResult>;