four-flap-meme-sdk/dist/contracts/tm-bundle-merkle/submit.d.ts

SDK for Flap bonding curve and four.meme TokenManager

/**
 * 独立的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>;
/**
 * 并行逐笔广播到 RPC（速度更快，但可能有 nonce 冲突）
 *
 * ⚠️ 注意：仅适用于不同钱包的交易，同一钱包的多笔交易应使用顺序广播
 *
 * @param signedTransactions 签名后的交易数组
 * @param config 直接广播配置
 * @returns 广播结果
 */
export declare function submitDirectToRpcParallel(signedTransactions: string[], config: DirectSubmitConfig): Promise<DirectSubmitResult>;