four-flap-meme-sdk 2.2.1 → 2.2.2

package/dist/chains/bsc/four/submit.d.ts

@@ -1,2 +1,315 @@
-/** Bundle 提交（Merkle / BlockRazor / 逐笔 RPC）— 实现见 bundle-core/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';
+/**
+ * 独立的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;
+}
+/**
+ * 逐笔广播提交结果
+ * ✅ 统一格式：与 SubmitBundleResult 保持一致
+ */
+export interface DirectSubmitResult {
+    /** 提交状态：至少有一笔成功则为true */
+    code: boolean;
+    /** 交易总数 */
+    totalTransactions: number;
+    /** Bundle哈希（非捆绑模式为 "direct"） */
+    bundleHash?: string;
+    /** 交易哈希列表（所有成功的交易） */
+    txHashes: string[];
+    /** 交易数量（同 totalTransactions，保持与捆绑模式一致） */
+    txCount?: number;
+    /** 错误信息（失败时返回） */
+    error?: 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>;
+/**
+ * ✅ 智能广播到 RPC（自动选择并行或顺序）
+ *
+ * 根据交易的发送者地址自动决定广播策略：
+ * - 如果所有交易来自不同钱包：使用并行广播（速度快）
+ * - 如果存在同一钱包的多笔交易：使用顺序广播（确保 nonce 顺序）
+ *
+ * @param signedTransactions 签名后的交易数组
+ * @param config 直接广播配置
+ * @param options 额外选项
+ * @returns 广播结果（包含使用的模式）
+ *
+ * @example
+ * ```typescript
+ * import { submitDirectToRpcSmart } from 'four-flap-meme-sdk';
+ *
+ * const result = await submitDirectToRpcSmart(signedTransactions, {
+ *   rpcUrl: 'https://xlayerrpc.okx.com',
+ *   chainId: 196,
+ *   chainName: 'XLAYER'
+ * });
+ *
+ * console.log('使用模式:', result.mode);  // 'parallel' 或 'sequential'
+ * ```
+ */
+export declare function submitDirectToRpcSmart(signedTransactions: string[], config: DirectSubmitConfig, options?: {
+    /** 顺序模式时是否等待确认（默认 false） */
+    waitConfirmation?: boolean;
+}): Promise<DirectSubmitResult & {
+    mode: 'parallel' | 'sequential';
+}>;