four-flap-meme-sdk 1.5.4 → 1.5.6

package/dist/sol/nozomi/client.js

@@ -0,0 +1,222 @@
+/**
+ * Nozomi 客户端
+ * 用于发送交易到 Temporal Nozomi 服务
+ * @module sol/nozomi/client
+ */
+import { Transaction, ComputeBudgetProgram, } from '@solana/web3.js';
+import { NOZOMI_CONFIG } from '../constants.js';
+import { buildNozomiTipInstruction, getRandomNozomiTipAccount } from './tip.js';
+/**
+ * Nozomi 客户端
+ * 用于发送交易到 Temporal Nozomi 服务
+ */
+export class NozomiClient {
+    constructor(config) {
+        this.apiKeyFast = config.apiKeyFast;
+        this.apiKeyMev = config.apiKeyMev || config.apiKeyFast;
+        this.defaultRegion = config.defaultRegion || 'auto';
+        this.defaultUseMevProtection = config.defaultUseMevProtection || false;
+        this.timeout = config.timeout || 30000;
+    }
+    /**
+     * 获取 Nozomi 端点 URL
+     * @param useMevProtection 是否使用 MEV 保护
+     * @param region 区域
+     */
+    getEndpoint(useMevProtection = false, region = 'auto') {
+        const apiKey = useMevProtection ? this.apiKeyMev : this.apiKeyFast;
+        const host = NOZOMI_CONFIG.REGIONS[region] || NOZOMI_CONFIG.REGIONS.auto;
+        return `https://${host}/?c=${apiKey}`;
+    }
+    /**
+     * 发送单笔交易
+     * @param transaction 交易（Transaction 或 VersionedTransaction）
+     * @param options 发送选项
+     */
+    async sendTransaction(transaction, options) {
+        const useMevProtection = options?.useMevProtection ?? this.defaultUseMevProtection;
+        const region = options?.region ?? this.defaultRegion;
+        const endpoint = this.getEndpoint(useMevProtection, region);
+        const startTime = Date.now();
+        try {
+            // 序列化交易
+            const serialized = transaction.serialize();
+            const base64Tx = Buffer.from(serialized).toString('base64');
+            // 发送请求
+            const response = await fetch(endpoint, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    jsonrpc: '2.0',
+                    id: 1,
+                    method: 'sendTransaction',
+                    params: [
+                        base64Tx,
+                        {
+                            encoding: 'base64',
+                            skipPreflight: options?.skipPreflight ?? true,
+                            maxRetries: options?.maxRetries ?? 0,
+                        },
+                    ],
+                }),
+                signal: AbortSignal.timeout(this.timeout),
+            });
+            const result = await response.json();
+            const latency = Date.now() - startTime;
+            if (result.error) {
+                return {
+                    success: false,
+                    error: `${result.error.message}${result.error.data ? `: ${result.error.data}` : ''}`,
+                    latency,
+                };
+            }
+            return {
+                success: true,
+                signature: result.result,
+                latency,
+            };
+        }
+        catch (error) {
+            const latency = Date.now() - startTime;
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : String(error),
+                latency,
+            };
+        }
+    }
+    /**
+     * 批量发送交易（并行发送，非 Bundle）
+     * @param transactions 交易列表
+     * @param options 发送选项
+     */
+    async sendTransactions(transactions, options) {
+        const startTime = Date.now();
+        const results = await Promise.all(transactions.map((tx) => this.sendTransaction(tx, options)));
+        const successCount = results.filter((r) => r.success).length;
+        const failCount = results.length - successCount;
+        return {
+            total: transactions.length,
+            successCount,
+            failCount,
+            results,
+            totalLatency: Date.now() - startTime,
+        };
+    }
+    /**
+     * 构建并发送交易
+     * @param connection Solana 连接（用于获取 blockhash）
+     * @param instructions 指令列表
+     * @param signers 签名者列表（第一个为 feePayer）
+     * @param buildOptions 构建选项
+     * @param sendOptions 发送选项
+     */
+    async buildAndSendTransaction(connection, instructions, signers, buildOptions, sendOptions) {
+        if (signers.length === 0) {
+            return {
+                success: false,
+                error: 'At least one signer (feePayer) is required',
+            };
+        }
+        const feePayer = signers[0];
+        const { blockhash } = await connection.getLatestBlockhash('finalized');
+        const transaction = new Transaction();
+        // 添加计算预算指令
+        if (buildOptions?.computeUnitPrice) {
+            transaction.add(ComputeBudgetProgram.setComputeUnitPrice({
+                microLamports: buildOptions.computeUnitPrice,
+            }));
+        }
+        else {
+            // 使用默认推荐值
+            transaction.add(ComputeBudgetProgram.setComputeUnitPrice({
+                microLamports: NOZOMI_CONFIG.RECOMMENDED_PRIORITY_FEE,
+            }));
+        }
+        if (buildOptions?.computeUnitLimit) {
+            transaction.add(ComputeBudgetProgram.setComputeUnitLimit({
+                units: buildOptions.computeUnitLimit,
+            }));
+        }
+        // 添加 Nozomi Tip（必须在业务指令之前）
+        if (buildOptions?.addTip !== false) {
+            const tipLamports = buildOptions?.tipLamports || BigInt(NOZOMI_CONFIG.DEFAULT_TIP_LAMPORTS);
+            transaction.add(buildNozomiTipInstruction(feePayer.publicKey, tipLamports, buildOptions?.tipAccount));
+        }
+        // 添加业务指令
+        transaction.add(...instructions);
+        // 设置交易属性
+        transaction.recentBlockhash = blockhash;
+        transaction.feePayer = feePayer.publicKey;
+        // 签名
+        transaction.sign(...signers);
+        // 发送
+        return this.sendTransaction(transaction, sendOptions);
+    }
+}
+/**
+ * 构建带 Nozomi Tip 的交易
+ * @param connection Solana 连接
+ * @param instructions 指令列表
+ * @param feePayer 手续费支付者
+ * @param options 构建选项
+ */
+export async function buildNozomiTransaction(connection, instructions, feePayer, options) {
+    const { blockhash } = await connection.getLatestBlockhash('finalized');
+    const transaction = new Transaction();
+    // 添加计算预算指令
+    if (options?.computeUnitPrice) {
+        transaction.add(ComputeBudgetProgram.setComputeUnitPrice({
+            microLamports: options.computeUnitPrice,
+        }));
+    }
+    else {
+        transaction.add(ComputeBudgetProgram.setComputeUnitPrice({
+            microLamports: NOZOMI_CONFIG.RECOMMENDED_PRIORITY_FEE,
+        }));
+    }
+    if (options?.computeUnitLimit) {
+        transaction.add(ComputeBudgetProgram.setComputeUnitLimit({
+            units: options.computeUnitLimit,
+        }));
+    }
+    // 添加 Nozomi Tip（必须在业务指令之前）
+    if (options?.addTip !== false) {
+        const tipLamports = options?.tipLamports || BigInt(NOZOMI_CONFIG.DEFAULT_TIP_LAMPORTS);
+        transaction.add(buildNozomiTipInstruction(feePayer.publicKey, tipLamports, options?.tipAccount));
+    }
+    // 添加业务指令
+    transaction.add(...instructions);
+    // 设置交易属性
+    transaction.recentBlockhash = blockhash;
+    transaction.feePayer = feePayer.publicKey;
+    return transaction;
+}
+/**
+ * 将现有交易添加 Nozomi Tip
+ * 注意：这会在交易开头添加 Tip 指令
+ * @param transaction 原始交易
+ * @param feePayer 手续费支付者
+ * @param tipLamports Tip 金额
+ * @param tipAccount Tip 账户
+ */
+export function addNozomiTipToTransaction(transaction, feePayer, tipLamports = BigInt(NOZOMI_CONFIG.DEFAULT_TIP_LAMPORTS), tipAccount) {
+    const tipInstruction = buildNozomiTipInstruction(feePayer.publicKey, tipLamports, tipAccount || getRandomNozomiTipAccount());
+    // 创建新交易，先添加 tip，再添加原有指令
+    const newTransaction = new Transaction();
+    // 复制计算预算指令（如果有）
+    const computeBudgetInstructions = transaction.instructions.filter((ix) => ix.programId.toBase58() === 'ComputeBudget111111111111111111111111111111');
+    const otherInstructions = transaction.instructions.filter((ix) => ix.programId.toBase58() !== 'ComputeBudget111111111111111111111111111111');
+    // 先添加计算预算，再添加 tip，最后添加其他指令
+    newTransaction.add(...computeBudgetInstructions);
+    newTransaction.add(tipInstruction);
+    newTransaction.add(...otherInstructions);
+    // 复制交易属性
+    if (transaction.recentBlockhash) {
+        newTransaction.recentBlockhash = transaction.recentBlockhash;
+    }
+    if (transaction.feePayer) {
+        newTransaction.feePayer = transaction.feePayer;
+    }
+    return newTransaction;
+}

package/dist/sol/nozomi/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Nozomi 交易加速服务
+ * Temporal Nozomi - 快速提交 Solana 交易
+ * @module sol/nozomi
+ */
+export * from './types.js';
+export * from './tip.js';
+export * from './client.js';

package/dist/sol/nozomi/index.js

@@ -0,0 +1,8 @@
+/**
+ * Nozomi 交易加速服务
+ * Temporal Nozomi - 快速提交 Solana 交易
+ * @module sol/nozomi
+ */
+export * from './types.js';
+export * from './tip.js';
+export * from './client.js';

package/dist/sol/nozomi/tip.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Nozomi Tip 相关功能
+ * @module sol/nozomi/tip
+ */
+import { PublicKey, TransactionInstruction } from '@solana/web3.js';
+/**
+ * 随机选择一个 Tip 账户
+ * @returns Tip 账户地址
+ */
+export declare function getRandomNozomiTipAccount(): string;
+/**
+ * 获取所有 Tip 账户
+ * @returns Tip 账户列表
+ */
+export declare function getAllNozomiTipAccounts(): string[];
+/**
+ * 验证是否是有效的 Nozomi Tip 账户
+ * @param address 地址
+ */
+export declare function isValidNozomiTipAccount(address: string): boolean;
+/**
+ * 构建 Nozomi Tip 指令
+ * @param fromPubkey 付款者公钥
+ * @param tipLamports Tip 金额（lamports），默认 0.001 SOL
+ * @param tipAccount 可选：指定 Tip 账户，默认随机选择
+ * @returns TransactionInstruction
+ */
+export declare function buildNozomiTipInstruction(fromPubkey: PublicKey, tipLamports?: bigint, tipAccount?: string): TransactionInstruction;
+/**
+ * 计算推荐的 Tip 金额
+ * 根据优先级计算
+ * @param priority 优先级 (1-10，10 最高)
+ * @returns 推荐的 Tip 金额（lamports）
+ */
+export declare function calculateRecommendedNozomiTip(priority?: number): bigint;
+/**
+ * Nozomi Tip 金额预设
+ */
+export declare const NOZOMI_TIP_PRESETS: {
+    /** 最低 tip (0.001 SOL) */
+    readonly LOW: bigint;
+    /** 标准 tip (0.001 SOL) */
+    readonly STANDARD: bigint;
+    /** 中等 tip (0.002 SOL) */
+    readonly MEDIUM: bigint;
+    /** 高 tip (0.005 SOL) */
+    readonly HIGH: bigint;
+    /** 紧急 tip (0.01 SOL) */
+    readonly URGENT: bigint;
+};

package/dist/sol/nozomi/tip.js

@@ -0,0 +1,80 @@
+/**
+ * Nozomi Tip 相关功能
+ * @module sol/nozomi/tip
+ */
+import { PublicKey, SystemProgram, } from '@solana/web3.js';
+import { NOZOMI_CONFIG } from '../constants.js';
+/**
+ * 随机选择一个 Tip 账户
+ * @returns Tip 账户地址
+ */
+export function getRandomNozomiTipAccount() {
+    const accounts = NOZOMI_CONFIG.TIP_ACCOUNTS;
+    const index = Math.floor(Math.random() * accounts.length);
+    return accounts[index];
+}
+/**
+ * 获取所有 Tip 账户
+ * @returns Tip 账户列表
+ */
+export function getAllNozomiTipAccounts() {
+    return [...NOZOMI_CONFIG.TIP_ACCOUNTS];
+}
+/**
+ * 验证是否是有效的 Nozomi Tip 账户
+ * @param address 地址
+ */
+export function isValidNozomiTipAccount(address) {
+    return NOZOMI_CONFIG.TIP_ACCOUNTS.includes(address);
+}
+/**
+ * 构建 Nozomi Tip 指令
+ * @param fromPubkey 付款者公钥
+ * @param tipLamports Tip 金额（lamports），默认 0.001 SOL
+ * @param tipAccount 可选：指定 Tip 账户，默认随机选择
+ * @returns TransactionInstruction
+ */
+export function buildNozomiTipInstruction(fromPubkey, tipLamports = BigInt(NOZOMI_CONFIG.DEFAULT_TIP_LAMPORTS), tipAccount) {
+    const tipAccountAddress = tipAccount || getRandomNozomiTipAccount();
+    // 确保 tip 金额不低于最小值
+    const finalTip = tipLamports < BigInt(NOZOMI_CONFIG.MIN_TIP_LAMPORTS)
+        ? BigInt(NOZOMI_CONFIG.MIN_TIP_LAMPORTS)
+        : tipLamports;
+    return SystemProgram.transfer({
+        fromPubkey,
+        toPubkey: new PublicKey(tipAccountAddress),
+        lamports: finalTip,
+    });
+}
+/**
+ * 计算推荐的 Tip 金额
+ * 根据优先级计算
+ * @param priority 优先级 (1-10，10 最高)
+ * @returns 推荐的 Tip 金额（lamports）
+ */
+export function calculateRecommendedNozomiTip(priority = 5) {
+    // 基础 tip 0.001 SOL
+    const baseTip = BigInt(NOZOMI_CONFIG.DEFAULT_TIP_LAMPORTS);
+    // 根据优先级增加（1-10 映射到 1x - 3x）
+    const priorityMultiplier = 1 + (priority / 10) * 2;
+    const tip = BigInt(Math.floor(Number(baseTip) * priorityMultiplier));
+    // 确保不低于最小值
+    return tip < BigInt(NOZOMI_CONFIG.MIN_TIP_LAMPORTS)
+        ? BigInt(NOZOMI_CONFIG.MIN_TIP_LAMPORTS)
+        : tip;
+}
+/**
+ * Nozomi Tip 金额预设
+ */
+export const NOZOMI_TIP_PRESETS = {
+    /** 最低 tip (0.001 SOL) */
+    LOW: BigInt(1000000),
+    /** 标准 tip (0.001 SOL) */
+    STANDARD: BigInt(1000000),
+    /** 中等 tip (0.002 SOL) */
+    MEDIUM: BigInt(2000000),
+    /** 高 tip (0.005 SOL) */
+    HIGH: BigInt(5000000),
+    /** 紧急 tip (0.01 SOL) */
+    URGENT: BigInt(10000000),
+};

package/dist/sol/nozomi/types.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Nozomi 类型定义
+ * @module sol/nozomi/types
+ */
+/**
+ * Nozomi 区域
+ */
+export type NozomiRegion = 'auto' | 'pit' | 'tyo' | 'sgp' | 'ewr' | 'ams' | 'fra';
+/**
+ * Nozomi 客户端配置
+ */
+export interface NozomiClientConfig {
+    /** 最快提交 API Key */
+    apiKeyFast: string;
+    /** MEV 保护 API Key (可选，如果不提供则使用 apiKeyFast) */
+    apiKeyMev?: string;
+    /** 默认区域 */
+    defaultRegion?: NozomiRegion;
+    /** 默认是否使用 MEV 保护 */
+    defaultUseMevProtection?: boolean;
+    /** 请求超时（毫秒） */
+    timeout?: number;
+}
+/**
+ * Nozomi 发送选项
+ */
+export interface NozomiSendOptions {
+    /** 是否使用 MEV 保护 */
+    useMevProtection?: boolean;
+    /** 区域节点 */
+    region?: NozomiRegion;
+    /** 是否跳过预检 */
+    skipPreflight?: boolean;
+    /** 最大重试次数（Nozomi 内部重试） */
+    maxRetries?: number;
+}
+/**
+ * Nozomi 发送结果
+ */
+export interface NozomiSendResult {
+    /** 是否成功 */
+    success: boolean;
+    /** 交易签名 */
+    signature?: string;
+    /** 错误信息 */
+    error?: string;
+    /** 延迟（毫秒） */
+    latency?: number;
+}
+/**
+ * Nozomi 批量发送结果
+ */
+export interface NozomiBatchSendResult {
+    /** 总数 */
+    total: number;
+    /** 成功数 */
+    successCount: number;
+    /** 失败数 */
+    failCount: number;
+    /** 各交易结果 */
+    results: NozomiSendResult[];
+    /** 总耗时（毫秒） */
+    totalLatency: number;
+}
+/**
+ * 交易构建选项
+ */
+export interface NozomiTransactionBuildOptions {
+    /** 是否添加 Nozomi Tip */
+    addTip?: boolean;
+    /** Tip 金额（lamports），默认 0.001 SOL */
+    tipLamports?: bigint;
+    /** 指定 Tip 账户，默认随机选择 */
+    tipAccount?: string;
+    /** 计算单元限制 */
+    computeUnitLimit?: number;
+    /** 计算单元价格（microlamports），建议 1,000,000 */
+    computeUnitPrice?: number;
+}
+/**
+ * Nozomi RPC 错误
+ */
+export interface NozomiRpcError {
+    code: number;
+    message: string;
+    data?: string;
+}
+/**
+ * Nozomi RPC 响应
+ */
+export interface NozomiRpcResponse<T = string> {
+    jsonrpc: string;
+    id: number;
+    result?: T;
+    error?: NozomiRpcError;
+}

package/dist/sol/nozomi/types.js

@@ -0,0 +1,5 @@
+/**
+ * Nozomi 类型定义
+ * @module sol/nozomi/types
+ */
+export {};

package/dist/sol/token/create-complete.d.ts

@@ -0,0 +1,115 @@
+/**
+ * 完整代币创建流程
+ * 包括：上传元数据 → 创建 Mint → 创建 Metadata → Mint 初始供应
+ * @module sol/token/create-complete
+ */
+import { Connection, Keypair, PublicKey } from '@solana/web3.js';
+import type { TokenStandard } from './types.js';
+/**
+ * 完整代币创建参数
+ */
+export interface CreateTokenCompleteParams {
+    /** 代币名称 */
+    name: string;
+    /** 代币符号 */
+    symbol: string;
+    /** 代币描述 */
+    description: string;
+    /** 精度（小数位数） */
+    decimals: number;
+    /** 初始供应量（不含精度，如 1000000 表示 100万） */
+    initialSupply: bigint;
+    /** 图片 Buffer（用于上传 IPFS） */
+    imageBuffer?: Buffer | Uint8Array;
+    /** 图片 File 对象（浏览器环境） */
+    imageFile?: File;
+    /** 已上传的元数据 CID（如果已有，则不需要上传） */
+    metadataCid?: string;
+    /** 创建者 Keypair */
+    creator: Keypair;
+    /** Mint 权限（默认为 creator） */
+    mintAuthority?: PublicKey;
+    /** 冻结权限（null 表示不可冻结） */
+    freezeAuthority?: PublicKey | null;
+    /** 代币标准（默认 TOKEN_2022） */
+    tokenStandard?: TokenStandard;
+    /** 社交链接 */
+    social?: {
+        telegram?: string;
+        twitter?: string;
+        website?: string;
+    };
+}
+/**
+ * 完整代币创建结果
+ */
+export interface CreateTokenCompleteResult {
+    success: boolean;
+    /** Mint 地址 */
+    mint?: string;
+    /** Mint Keypair（需要保存用于后续操作） */
+    mintKeypair?: Keypair;
+    /** Metadata 账户地址 */
+    metadataAddress?: string;
+    /** 元数据 URI（IPFS） */
+    metadataUri?: string;
+    /** 创建者 ATA 地址 */
+    creatorAta?: string;
+    /** 签名后的交易列表（按顺序提交） */
+    signedTransactions?: Array<{
+        data: string;
+        signature: string;
+        description: string;
+    }>;
+    /** blockhash */
+    recentBlockhash?: string;
+    /** 最后有效区块高度 */
+    lastValidBlockHeight?: number;
+    /** 错误信息 */
+    error?: string;
+}
+/**
+ * 创建完整代币（上传元数据 + 创建 Mint + 创建 Metadata + Mint 初始供应）
+ *
+ * 流程：
+ * 1. 上传图片和元数据到 IPFS（使用 Flap 官方接口）
+ * 2. 创建 Mint 账户 + Mint 初始供应量
+ * 3. 创建 Metaplex Metadata 账户
+ *
+ * @param connection Solana 连接
+ * @param params 创建参数
+ */
+export declare function createTokenComplete(connection: Connection, params: CreateTokenCompleteParams): Promise<CreateTokenCompleteResult>;
+/**
+ * 创建代币（不上传元数据，使用已有 URI）
+ * 适用于元数据已经上传的情况
+ */
+export declare function createTokenWithUri(connection: Connection, params: {
+    name: string;
+    symbol: string;
+    metadataUri: string;
+    decimals: number;
+    initialSupply: bigint;
+    creator: Keypair;
+    mintAuthority?: PublicKey;
+    freezeAuthority?: PublicKey | null;
+    tokenStandard?: TokenStandard;
+}): Promise<CreateTokenCompleteResult>;
+/**
+ * 将创建结果转换为后端 API 格式
+ */
+export declare function toBackendCreateTokenRequest(result: CreateTokenCompleteResult): {
+    mint: string;
+    metadataAddress: string;
+    metadataUri: string;
+    imageUri?: string;
+    creatorAta: string;
+    transactions: Array<{
+        data: string;
+        signature: string;
+        description: string;
+    }>;
+    recentBlockhash: string;
+    lastValidBlockHeight: number;
+    timestamp: number;
+} | null;