four-flap-meme-sdk/dist/clients/merkle.d.ts

SDK for Flap bonding curve and four.meme TokenManager

/**
 * Merkle.io Bundle Service 客户端
 *
 * 提供基于 Merkle 的 MEV 保护和捆绑交易服务
 *
 * 官方文档: https://docs.merkle.io/
 *
 * 使用示例:
 * ```typescript
 * import { MerkleClient } from 'four-flap-meme-sdk';
 *
 * const merkle = new MerkleClient({
 *   apiKey: 'pk_mbs_...',
 *   chainId: 56
 * });
 *
 * const bundleHash = await merkle.sendBundle({
 *   transactions: [tx1, tx2, tx3],
 *   targetBlock: currentBlock + 2
 * });
 * ```
 */
import { JsonRpcProvider, Wallet, TransactionLike } from 'ethers';
/**
 * Merkle 客户端配置
 */
export interface MerkleConfig {
    /** Merkle API Key (例如: pk_mbs_...) */
    apiKey: string;
    /** 链 ID: 56=BSC, 1=Ethereum */
    chainId: 56 | 1;
    /** 自定义 RPC URL（可选，默认使用 Merkle 官方 RPC） */
    customRpcUrl?: string;
}
/**
 * Bundle 参数
 */
export interface BundleParams {
    /** 已签名的交易数组（原始交易字符串） */
    txs: string[];
    /** 目标区块号（十六进制字符串，例如: "0x123abc"） */
    blockNumber: string;
    /** 最小时间戳（可选，0 表示不限制） */
    minTimestamp?: number;
    /** 最大时间戳（可选，0 表示不限制） */
    maxTimestamp?: number;
}
/**
 * 网络状态信息
 */
export interface NetworkStatus {
    /** 当前区块号 */
    currentBlock: number;
    /** 当前 Gas Price (wei) */
    gasPrice: bigint;
    /** 建议的最小 Gas Price (wei) */
    suggestedMinGasPrice: bigint;
    /** 平均出块时间（秒） */
    avgBlockTime: number;
}
/**
 * 发送 Bundle 的选项
 */
export interface SendBundleOptions {
    /** 已签名的交易数组 */
    transactions: string[];
    /** 目标区块号（十进制数字，会自动转换为十六进制） */
    targetBlock?: number;
    /** 最小时间戳 */
    minTimestamp?: number;
    /** 最大时间戳 */
    maxTimestamp?: number;
    /** 如果不指定 targetBlock，则使用当前区块 + offset（默认3） */
    blockOffset?: number;
    /** 最小区块偏移量，用于确保足够的提交时间窗口（默认3） */
    minBlockOffset?: number;
    /** 是否启用自动重试（默认false） */
    autoRetry?: boolean;
    /** 最大重试次数（默认2） */
    maxRetries?: number;
}
/**
 * Bundle 发送结果
 */
export interface BundleResult {
    /** Bundle Hash */
    bundleHash: string;
    /** 交易哈希列表 */
    txHashes: string[];
    /** 目标区块号 */
    targetBlock: number;
    /** 交易数量 */
    txCount: number;
}
/**
 * 交易确认结果
 */
export interface TransactionResult {
    /** 交易索引 */
    index: number;
    /** 交易哈希 */
    hash: string;
    /** 是否成功 */
    success: boolean;
    /** 区块号 */
    blockNumber?: number;
    /** Gas 使用量 */
    gasUsed?: string;
    /** 有效 Gas Price */
    effectiveGasPrice?: string;
    /** Gas 费用（BNB/ETH） */
    gasCost?: string;
    /** 错误信息 */
    error?: string;
}
/**
 * Merkle 客户端
 */
export declare class MerkleClient {
    private provider;
    private chainId;
    private chainName;
    private blockNumberCache;
    private static BLOCK_CACHE_TTL_MS;
    constructor(config: MerkleConfig);
    /**
     * 获取 Provider
     */
    getProvider(): JsonRpcProvider;
    /**
     * 获取当前区块号（带缓存，减少 RPC 调用）
     * @param forceRefresh 是否强制刷新缓存
     */
    getBlockNumber(forceRefresh?: boolean): Promise<number>;
    /**
     * 获取 Gas 价格信息
     */
    getFeeData(): Promise<import("ethers").FeeData>;
    /**
     * 获取网络状态（用于 Bundle 参数优化）
     */
    getNetworkStatus(): Promise<NetworkStatus>;
    /**
     * 发送捆绑交易（底层方法）
     *
     * @param params Bundle 参数
     * @returns Bundle Hash
     */
    sendBundleRaw(params: BundleParams): Promise<string>;
    /**
     * 发送捆绑交易（高级方法，带智能优化和重试）
     *
     * @param options 发送选项
     * @returns Bundle 结果
     */
    sendBundle(options: SendBundleOptions): Promise<BundleResult>;
    /**
     * 等待 Bundle 中的交易确认
     *
     * @param txHashes 交易哈希列表
     * @param confirmations 确认数（默认 1）
     * @param timeout 超时时间（毫秒，默认 120000）
     * @returns 交易结果列表
     */
    waitForBundleConfirmation(txHashes: string[], confirmations?: number, timeout?: number): Promise<TransactionResult[]>;
    /**
     * 准备并签名交易（辅助方法）
     *
     * @param wallet 钱包
     * @param transactions 交易列表
     * @param options 可选参数
     * @returns 已签名的交易数组
     */
    signTransactions(wallet: Wallet, transactions: TransactionLike[], options?: {
        /** 起始 Nonce（可选，默认从链上获取） */
        startNonce?: number;
        /** Gas Price（可选，默认从链上获取并提高 50%） */
        gasPrice?: bigint;
        /** Gas Price 增幅百分比（默认 50，即提高 50%） */
        gasPriceMultiplier?: number;
    }): Promise<string[]>;
    /**
     * 检查交易是否已包含在区块中
     *
     * @param txHash 交易哈希
     * @returns 是否已包含
     */
    isTransactionIncluded(txHash: string): Promise<boolean>;
    /**
     * 等待达到目标区块
     *
     * @param targetBlock 目标区块号
     * @param maxAttempts 最大尝试次数（默认 10）
     * @param intervalMs 检查间隔（毫秒，默认 1000）
     * @returns 是否达到目标区块
     */
    waitForBlock(targetBlock: number, maxAttempts?: number, intervalMs?: number): Promise<boolean>;
    /**
     * 获取当前 Provider 的统计信息（用于调试）
     */
    getProviderInfo(): {
        chainId: number;
        chainName: string;
        rpcUrl: string;
    };
}
/**
 * 创建 Merkle 客户端的便捷函数
 */
export declare function createMerkleClient(apiKey: string, chainId?: 56 | 1): MerkleClient;