four-flap-meme-sdk 1.4.88 → 1.4.89

package/dist/sol/dex/jup/legacy.d.ts

@@ -0,0 +1,623 @@
+/**
+ * Jupiter Legacy Swap API
+ * @module sol/dex/jup/legacy
+ *
+ * Legacy Swap API 提供更多自定义选项的交易路由
+ * 文档: https://docs.jup.ag/docs/apis/swap-api
+ */
+import type { JupiterConfig } from './types.js';
+/** Swap 模式 */
+export type LegacySwapMode = 'ExactIn' | 'ExactOut';
+/** 指令版本 */
+export type LegacyInstructionVersion = 'V1' | 'V2';
+/** 路由交换信息 */
+export interface LegacySwapInfo {
+    /** AMM Key */
+    ammKey: string;
+    /** AMM 标签 (如 'Raydium CLMM', 'Orca') */
+    label?: string;
+    /** 输入代币 Mint */
+    inputMint: string;
+    /** 输出代币 Mint */
+    outputMint: string;
+    /** 输入数量 */
+    inAmount: string;
+    /** 输出数量 */
+    outAmount: string;
+    /** 手续费数量 (已弃用) */
+    feeAmount?: string;
+    /** 手续费代币 (已弃用) */
+    feeMint?: string;
+}
+/** 路由计划 */
+export interface LegacyRoutePlan {
+    /** 交换信息 */
+    swapInfo: LegacySwapInfo;
+    /** 百分比 */
+    percent: number | null;
+    /** BPS */
+    bps?: number | null;
+}
+/** 平台手续费 */
+export interface LegacyPlatformFee {
+    /** 手续费数量 */
+    amount: string;
+    /** 手续费 BPS */
+    feeBps: number;
+}
+/** Quote 请求参数 */
+export interface LegacyQuoteParams {
+    /** 输入代币 Mint */
+    inputMint: string;
+    /** 输出代币 Mint */
+    outputMint: string;
+    /**
+     * 原始数量 (最小单位)
+     * - ExactIn: 输入数量
+     * - ExactOut: 输出数量
+     */
+    amount: string | number;
+    /** 滑点 BPS (默认: 50) */
+    slippageBps?: number;
+    /**
+     * Swap 模式 (默认: ExactIn)
+     * - ExactIn: 精确输入
+     * - ExactOut: 精确输出 (仅部分 AMM 支持)
+     */
+    swapMode?: LegacySwapMode;
+    /**
+     * 指定使用的 DEX 列表
+     * 例如: ['Raydium', 'Orca V2', 'Meteora DLMM']
+     */
+    dexes?: string[];
+    /**
+     * 排除的 DEX 列表
+     * 例如: ['Raydium', 'Orca V2']
+     */
+    excludeDexes?: string[];
+    /** 限制中间代币为稳定币 (默认: true) */
+    restrictIntermediateTokens?: boolean;
+    /** 仅使用直接路由/单跳 (默认: false) */
+    onlyDirectRoutes?: boolean;
+    /** 使用 Legacy 交易格式 (默认: false) */
+    asLegacyTransaction?: boolean;
+    /** 平台手续费 BPS */
+    platformFeeBps?: number;
+    /** 最大账户数量 (默认: 64) */
+    maxAccounts?: number;
+    /** 指令版本 (默认: V1) */
+    instructionVersion?: LegacyInstructionVersion;
+    /** 动态滑点 (默认: false) */
+    dynamicSlippage?: boolean;
+}
+/** Quote 响应 */
+export interface LegacyQuoteResponse {
+    /** 输入代币 Mint */
+    inputMint: string;
+    /** 输入数量 */
+    inAmount: string;
+    /** 输出代币 Mint */
+    outputMint: string;
+    /**
+     * 输出数量
+     * 包含平台费和 DEX 费用，不包含滑点
+     */
+    outAmount: string;
+    /**
+     * 最小输出阈值
+     * 考虑滑点后的最小输出
+     */
+    otherAmountThreshold: string;
+    /** Swap 模式 */
+    swapMode: LegacySwapMode;
+    /** 滑点 BPS */
+    slippageBps: number;
+    /** 价格影响百分比 */
+    priceImpactPct: string;
+    /** 路由计划 */
+    routePlan: LegacyRoutePlan[];
+    /** 平台手续费 */
+    platformFee: LegacyPlatformFee | null;
+    /** Context Slot */
+    contextSlot?: number;
+    /** 耗时 (秒) */
+    timeTaken?: number;
+    /** Swap USD 价值 */
+    swapUsdValue?: string;
+    /** 是否使用了简化路由 */
+    simplerRouteUsed?: boolean;
+    /** 指令版本 */
+    instructionVersion?: LegacyInstructionVersion;
+}
+/** 优先级等级 */
+export type PriorityLevel = 'medium' | 'high' | 'veryHigh';
+/** 优先费配置 - priorityLevelWithMaxLamports */
+export interface PriorityLevelWithMaxLamports {
+    priorityLevelWithMaxLamports: {
+        /** 优先级等级 */
+        priorityLevel: PriorityLevel;
+        /** 最大 lamports 上限 */
+        maxLamports: number;
+        /** 是否使用全局费率市场 (默认: false) */
+        global?: boolean;
+    };
+}
+/** 优先费配置 - jitoTipLamports */
+export interface JitoTipLamports {
+    jitoTipLamports: number;
+}
+/** 优先费配置 - jitoTipLamportsWithPayer */
+export interface JitoTipLamportsWithPayer {
+    jitoTipLamportsWithPayer: {
+        /** Jito tip 数量 */
+        lamports: number;
+        /** 支付者公钥 */
+        payer: string;
+    };
+}
+/** 优先费配置类型 */
+export type PrioritizationFeeLamports = number | 'auto' | PriorityLevelWithMaxLamports | JitoTipLamports | JitoTipLamportsWithPayer;
+/** Swap 请求参数 */
+export interface LegacySwapParams {
+    /** 用户公钥 */
+    userPublicKey: string;
+    /** Quote 响应 */
+    quoteResponse: LegacyQuoteResponse;
+    /**
+     * 自定义支付者公钥
+     * 支付交易费用和代币账户租金
+     */
+    payer?: string;
+    /**
+     * 是否自动包装/解包 SOL (默认: true)
+     * - true + 输入为 SOL: 将 SOL 包装为 WSOL
+     * - true + 输出为 SOL: 将 WSOL 解包为 SOL
+     * - false: 需要已存在的 WSOL 账户
+     */
+    wrapAndUnwrapSol?: boolean;
+    /**
+     * 使用共享程序账户 (由路由引擎动态决定)
+     * 对于复杂路由需要多个中间代币账户
+     */
+    useSharedAccounts?: boolean;
+    /**
+     * 手续费账户 (需要已初始化)
+     * 代币账户的 mint 必须是输入或输出代币
+     * 如果 /quote 传入了 platformFeeBps，则必须传入此参数
+     */
+    feeAccount?: string;
+    /**
+     * 跟踪账户公钥
+     * 用于追踪交易，可通过 Solscan/Dune 等查询
+     */
+    trackingAccount?: string;
+    /**
+     * 优先费配置
+     * - 数字: 固定 lamports
+     * - 'auto': 自动估算
+     * - priorityLevelWithMaxLamports: 按等级估算并设置上限
+     * - jitoTipLamports: Jito tip (需要连接 Jito RPC)
+     * - jitoTipLamportsWithPayer: Jito tip 并指定支付者
+     */
+    prioritizationFeeLamports?: PrioritizationFeeLamports;
+    /** 使用 Legacy 交易格式 (默认: false) */
+    asLegacyTransaction?: boolean;
+    /**
+     * 目标代币账户
+     * 接收输出代币的账户，需要已初始化
+     * 与 nativeDestinationAccount 互斥
+     */
+    destinationTokenAccount?: string;
+    /**
+     * 原生 SOL 目标账户
+     * 仅当输出为 SOL 时有效
+     * 与 destinationTokenAccount 互斥
+     */
+    nativeDestinationAccount?: string;
+    /**
+     * 动态计算 CU 限制 (默认: false)
+     * 启用后会模拟交易获取实际 CU，但会多一次 RPC 调用
+     * 推荐启用以准确估算 CU 和降低优先费
+     */
+    dynamicComputeUnitLimit?: boolean;
+    /**
+     * 跳过用户账户 RPC 调用 (默认: false)
+     * 启用后不检查必需账户是否存在
+     */
+    skipUserAccountsRpcCalls?: boolean;
+    /**
+     * 动态滑点 (默认: false)
+     * 已不再维护，推荐使用 Ultra API 的 RTSE
+     */
+    dynamicSlippage?: boolean;
+    /**
+     * 精确的 CU 价格 (微 lamports)
+     * computeUnitLimit (1400000) * computeUnitPriceMicroLamports
+     * 推荐使用 prioritizationFeeLamports + dynamicComputeUnitLimit
+     */
+    computeUnitPriceMicroLamports?: number;
+    /**
+     * 交易有效期 slots 数量
+     * 例如: 10 slots ≈ 4 秒
+     */
+    blockhashSlotsToExpiry?: number;
+}
+/** Swap 响应 */
+export interface LegacySwapResponse {
+    /** Base64 编码的未签名交易 */
+    swapTransaction: string;
+    /** 区块高度有效期限 */
+    lastValidBlockHeight: number;
+    /** 优先费 lamports */
+    prioritizationFeeLamports?: number;
+}
+/** 账户信息 */
+export interface InstructionAccount {
+    /** 账户公钥 */
+    pubkey: string;
+    /** 是否是签名者 */
+    isSigner: boolean;
+    /** 是否可写 */
+    isWritable: boolean;
+}
+/** 指令 */
+export interface Instruction {
+    /** Program ID */
+    programId: string;
+    /** 账户列表 */
+    accounts: InstructionAccount[];
+    /** 指令数据 (Base64) */
+    data: string;
+}
+/** Swap Instructions 响应 */
+export interface LegacySwapInstructionsResponse {
+    /**
+     * 其他指令
+     * 如果设置了 Jito tip，会包含 Jito tip 指令
+     */
+    otherInstructions: Instruction[];
+    /**
+     * Compute Budget 指令
+     * 用于设置交易的计算预算
+     */
+    computeBudgetInstructions: Instruction[];
+    /**
+     * Setup 指令
+     * 用于创建用户所需的代币账户
+     */
+    setupInstructions: Instruction[];
+    /**
+     * Swap 指令
+     * 实际的交换指令
+     */
+    swapInstruction: Instruction;
+    /**
+     * Address Lookup Table 地址
+     * 版本化交易使用
+     */
+    addressLookupTableAddresses: string[];
+    /**
+     * Cleanup 指令
+     * 用于包装/解包 SOL
+     */
+    cleanupInstruction?: Instruction;
+}
+/**
+ * 获取 Legacy Swap 报价
+ *
+ * Legacy API 提供更多自定义选项，适合需要精细控制路由的场景。
+ *
+ * @param params 报价参数
+ * @param config Jupiter 配置
+ * @returns Quote 响应
+ *
+ * @example
+ * ```typescript
+ * import { Sol } from 'four-flap-meme-sdk'
+ *
+ * Sol.setJupiterConfig({ apiKey: 'your-api-key' })
+ *
+ * // 基础报价
+ * const quote = await Sol.getLegacyQuote({
+ *   inputMint: 'So11111111111111111111111111111111111111112',
+ *   outputMint: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+ *   amount: '100000000', // 0.1 SOL
+ * })
+ *
+ * console.log('输出数量:', quote.outAmount)
+ * console.log('最小输出:', quote.otherAmountThreshold)
+ * console.log('价格影响:', quote.priceImpactPct)
+ * console.log('路由:', quote.routePlan.map(r => r.swapInfo.label).join(' -> '))
+ *
+ * // 高级选项
+ * const advancedQuote = await Sol.getLegacyQuote({
+ *   inputMint: 'So11111111111111111111111111111111111111112',
+ *   outputMint: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+ *   amount: '100000000',
+ *   slippageBps: 100, // 1% 滑点
+ *   dexes: ['Raydium', 'Orca V2'], // 只用这些 DEX
+ *   onlyDirectRoutes: true, // 单跳
+ * })
+ * ```
+ */
+export declare function getLegacyQuote(params: LegacyQuoteParams, config?: JupiterConfig): Promise<LegacyQuoteResponse>;
+/**
+ * 简化的 Legacy 报价获取
+ *
+ * @param inputMint 输入代币 Mint
+ * @param outputMint 输出代币 Mint
+ * @param amount 数量
+ * @param slippageBps 滑点 BPS (默认: 50)
+ * @param config Jupiter 配置
+ * @returns Quote 响应
+ */
+export declare function getLegacyQuoteSimple(inputMint: string, outputMint: string, amount: string | number, slippageBps?: number, config?: JupiterConfig): Promise<LegacyQuoteResponse>;
+/**
+ * 构建 Legacy Swap 交易
+ *
+ * @param params Swap 参数
+ * @param config Jupiter 配置
+ * @returns Swap 响应（包含未签名交易）
+ *
+ * @example
+ * ```typescript
+ * // 1. 获取报价
+ * const quote = await Sol.getLegacyQuote({
+ *   inputMint: 'So11111111111111111111111111111111111111112',
+ *   outputMint: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+ *   amount: '100000000',
+ * })
+ *
+ * // 2. 构建交易
+ * const swap = await Sol.buildLegacySwap({
+ *   quoteResponse: quote,
+ *   userPublicKey: wallet.publicKey.toBase58(),
+ * })
+ *
+ * // 3. 签名并发送
+ * const tx = VersionedTransaction.deserialize(
+ *   Buffer.from(swap.swapTransaction, 'base64')
+ * )
+ * tx.sign([wallet])
+ * const signature = await connection.sendTransaction(tx)
+ * ```
+ */
+export declare function buildLegacySwap(params: LegacySwapParams, config?: JupiterConfig): Promise<LegacySwapResponse>;
+/**
+ * 获取 Swap 分解指令
+ *
+ * 返回分解的指令而非完整交易，允许自定义组装交易。
+ * 适用于需要同时添加优先费和 Jito tip 等高级场景。
+ *
+ * @param params Swap 参数 (与 buildLegacySwap 相同)
+ * @param config Jupiter 配置
+ * @returns 分解的指令
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   TransactionMessage,
+ *   VersionedTransaction,
+ *   AddressLookupTableAccount
+ * } from '@solana/web3.js'
+ *
+ * // 1. 获取报价
+ * const quote = await Sol.getLegacyQuote({
+ *   inputMint: 'So11111111111111111111111111111111111111112',
+ *   outputMint: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+ *   amount: '100000000',
+ * })
+ *
+ * // 2. 获取分解指令
+ * const instructions = await Sol.getLegacySwapInstructions({
+ *   userPublicKey: wallet.publicKey.toBase58(),
+ *   quoteResponse: quote,
+ *   prioritizationFeeLamports: {
+ *     jitoTipLamports: 10000, // 添加 Jito tip
+ *   }
+ * })
+ *
+ * // 3. 获取 Address Lookup Tables
+ * const lookupTables = await Promise.all(
+ *   instructions.addressLookupTableAddresses.map(addr =>
+ *     connection.getAddressLookupTable(new PublicKey(addr))
+ *   )
+ * )
+ *
+ * // 4. 反序列化指令
+ * const allInstructions = [
+ *   ...instructions.computeBudgetInstructions,
+ *   ...instructions.setupInstructions,
+ *   instructions.swapInstruction,
+ *   ...(instructions.cleanupInstruction ? [instructions.cleanupInstruction] : []),
+ *   ...instructions.otherInstructions, // Jito tip 指令在这里
+ * ].map(ix => deserializeInstruction(ix))
+ *
+ * // 5. 构建版本化交易
+ * const messageV0 = new TransactionMessage({
+ *   payerKey: wallet.publicKey,
+ *   recentBlockhash: blockhash,
+ *   instructions: allInstructions,
+ * }).compileToV0Message(lookupTables)
+ *
+ * const tx = new VersionedTransaction(messageV0)
+ * tx.sign([wallet])
+ * ```
+ */
+export declare function getLegacySwapInstructions(params: LegacySwapParams, config?: JupiterConfig): Promise<LegacySwapInstructionsResponse>;
+/**
+ * 反序列化指令的辅助函数
+ *
+ * 将 API 返回的指令格式转换为 @solana/web3.js 可用格式
+ *
+ * @example
+ * ```typescript
+ * import { PublicKey, TransactionInstruction } from '@solana/web3.js'
+ *
+ * function deserializeInstruction(instruction: Instruction): TransactionInstruction {
+ *   return new TransactionInstruction({
+ *     programId: new PublicKey(instruction.programId),
+ *     keys: instruction.accounts.map(acc => ({
+ *       pubkey: new PublicKey(acc.pubkey),
+ *       isSigner: acc.isSigner,
+ *       isWritable: acc.isWritable,
+ *     })),
+ *     data: Buffer.from(instruction.data, 'base64'),
+ *   })
+ * }
+ * ```
+ */
+/** Program ID 到标签的映射 */
+export type ProgramIdToLabelMap = Record<string, string>;
+/**
+ * 获取所有支持的 DEX 及其 Program ID
+ *
+ * 返回 Program ID 到 DEX 标签的映射。
+ * 可用于 /quote 的 dexes 和 excludeDexes 参数。
+ *
+ * @param config Jupiter 配置
+ * @returns Program ID 到标签的映射
+ *
+ * @example
+ * ```typescript
+ * const dexMap = await Sol.getProgramIdToLabel()
+ *
+ * // 查看所有 DEX
+ * Object.entries(dexMap).forEach(([programId, label]) => {
+ *   console.log(`${label}: ${programId}`)
+ * })
+ *
+ * // 常见 DEX:
+ * // Raydium: 675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8
+ * // Raydium CLMM: CAMMCzo5YL8w4VFF8KVHrK22GGUsp5VTaW7grrKgrWqK
+ * // Orca V2: 9W959DqEETiGZocYWCQPaJ6sBmUzgfxXfqGeTEdp3aQP
+ * // Whirlpool: whirLbMiicVdio4qvUfM5KAg6Ct8VwpYzGff3uctyCc
+ * // Meteora: Eo7WjKq67rjJQSZxS6z3YkapzY3eMj6Xy8X5EQVn5UaB
+ * // Meteora DLMM: LBUZKhRxPF3XUpBCjp4YzTKgLccjZhTSDM9YuVaPwxo
+ * // Pump.fun: 6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P
+ * ```
+ */
+export declare function getProgramIdToLabel(config?: JupiterConfig): Promise<ProgramIdToLabelMap>;
+/**
+ * 获取所有支持的 DEX 标签列表
+ *
+ * @param config Jupiter 配置
+ * @returns DEX 标签数组
+ *
+ * @example
+ * ```typescript
+ * const labels = await Sol.getAllDexLabels()
+ * // ['Raydium', 'Raydium CLMM', 'Orca V2', 'Whirlpool', ...]
+ * ```
+ */
+export declare function getAllDexLabels(config?: JupiterConfig): Promise<string[]>;
+/**
+ * 通过标签获取 Program ID
+ *
+ * @param label DEX 标签
+ * @param config Jupiter 配置
+ * @returns Program ID 或 null
+ *
+ * @example
+ * ```typescript
+ * const raydiumId = await Sol.getProgramIdByLabel('Raydium')
+ * // '675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8'
+ * ```
+ */
+export declare function getProgramIdByLabel(label: string, config?: JupiterConfig): Promise<string | null>;
+/**
+ * 通过 Program ID 获取 DEX 标签
+ *
+ * @param programId Program ID
+ * @param config Jupiter 配置
+ * @returns DEX 标签或 null
+ *
+ * @example
+ * ```typescript
+ * const label = await Sol.getLabelByProgramId(
+ *   '675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8'
+ * )
+ * // 'Raydium'
+ * ```
+ */
+export declare function getLabelByProgramId(programId: string, config?: JupiterConfig): Promise<string | null>;
+/**
+ * 搜索 DEX
+ *
+ * @param keyword 搜索关键词（不区分大小写）
+ * @param config Jupiter 配置
+ * @returns 匹配的 { programId, label } 数组
+ *
+ * @example
+ * ```typescript
+ * const results = await Sol.searchDex('raydium')
+ * // [
+ * //   { programId: '675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8', label: 'Raydium' },
+ * //   { programId: 'CAMMCzo5YL8w4VFF8KVHrK22GGUsp5VTaW7grrKgrWqK', label: 'Raydium CLMM' },
+ * //   { programId: 'CPMMoo8L3F4NbTegBCKVNunggL7H1ZpdTHKxQB5qKP1C', label: 'Raydium CP' },
+ * // ]
+ * ```
+ */
+export declare function searchDex(keyword: string, config?: JupiterConfig): Promise<{
+    programId: string;
+    label: string;
+}[]>;
+/**
+ * 获取路由标签
+ *
+ * @param quote Quote 响应
+ * @returns 路由标签数组
+ */
+export declare function getRouteLabels(quote: LegacyQuoteResponse): string[];
+/**
+ * 计算路由跳数
+ *
+ * @param quote Quote 响应
+ * @returns 跳数
+ */
+export declare function getRouteHops(quote: LegacyQuoteResponse): number;
+/**
+ * 获取报价摘要
+ *
+ * @param quote Quote 响应
+ * @returns 报价摘要
+ */
+export declare function getQuoteSummary(quote: LegacyQuoteResponse): {
+    inputMint: string;
+    outputMint: string;
+    inAmount: string;
+    outAmount: string;
+    minOutAmount: string;
+    priceImpact: number;
+    slippageBps: number;
+    route: string;
+    hops: number;
+    usdValue: number | null;
+};
+/**
+ * 比较多个报价
+ *
+ * @param quotes Quote 响应数组
+ * @returns 排序后的报价（输出最多的在前）
+ */
+export declare function compareQuotes(quotes: LegacyQuoteResponse[]): LegacyQuoteResponse[];
+/**
+ * 获取最佳报价
+ *
+ * 比较不同 DEX 组合的报价，返回输出最多的
+ *
+ * @param inputMint 输入代币 Mint
+ * @param outputMint 输出代币 Mint
+ * @param amount 数量
+ * @param options 选项
+ * @param config Jupiter 配置
+ * @returns 最佳报价
+ */
+export declare function getBestLegacyQuote(inputMint: string, outputMint: string, amount: string | number, options?: {
+    slippageBps?: number;
+    compareDirectRoute?: boolean;
+}, config?: JupiterConfig): Promise<{
+    best: LegacyQuoteResponse;
+    direct: LegacyQuoteResponse | null;
+    directSavings: string | null;
+}>;