four-flap-meme-sdk 1.5.55 → 1.5.56

package/dist/sol/dex/jup/legacy.js

@@ -0,0 +1,416 @@
+/**
+ * Jupiter Legacy Swap API
+ * @module sol/dex/jup/legacy
+ *
+ * Legacy Swap API 提供更多自定义选项的交易路由
+ * 文档: https://docs.jup.ag/docs/apis/swap-api
+ */
+import { jupGet, jupPost } from './client.js';
+// ============================================================================
+// Quote - 获取报价
+// ============================================================================
+/**
+ * 获取 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 async function getLegacyQuote(params, config) {
+    const queryParams = {
+        inputMint: params.inputMint,
+        outputMint: params.outputMint,
+        amount: String(params.amount),
+        slippageBps: params.slippageBps,
+        swapMode: params.swapMode,
+        restrictIntermediateTokens: params.restrictIntermediateTokens,
+        onlyDirectRoutes: params.onlyDirectRoutes,
+        asLegacyTransaction: params.asLegacyTransaction,
+        platformFeeBps: params.platformFeeBps,
+        maxAccounts: params.maxAccounts,
+        instructionVersion: params.instructionVersion,
+        dynamicSlippage: params.dynamicSlippage,
+    };
+    // 处理数组参数
+    if (params.dexes?.length) {
+        queryParams.dexes = params.dexes.join(',');
+    }
+    if (params.excludeDexes?.length) {
+        queryParams.excludeDexes = params.excludeDexes.join(',');
+    }
+    return jupGet('/swap/v1/quote', queryParams, config);
+}
+/**
+ * 简化的 Legacy 报价获取
+ *
+ * @param inputMint 输入代币 Mint
+ * @param outputMint 输出代币 Mint
+ * @param amount 数量
+ * @param slippageBps 滑点 BPS (默认: 50)
+ * @param config Jupiter 配置
+ * @returns Quote 响应
+ */
+export async function getLegacyQuoteSimple(inputMint, outputMint, amount, slippageBps = 50, config) {
+    return getLegacyQuote({
+        inputMint,
+        outputMint,
+        amount,
+        slippageBps,
+    }, config);
+}
+// ============================================================================
+// Swap - 构建交易
+// ============================================================================
+/**
+ * 构建 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 async function buildLegacySwap(params, config) {
+    return jupPost('/swap/v1/swap', params, config);
+}
+// ============================================================================
+// Swap Instructions - 获取分解指令
+// ============================================================================
+/**
+ * 获取 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 async function getLegacySwapInstructions(params, config) {
+    return jupPost('/swap/v1/swap-instructions', params, config);
+}
+/**
+ * 获取所有支持的 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 async function getProgramIdToLabel(config) {
+    return jupGet('/swap/v1/program-id-to-label', {}, config);
+}
+/**
+ * 获取所有支持的 DEX 标签列表
+ *
+ * @param config Jupiter 配置
+ * @returns DEX 标签数组
+ *
+ * @example
+ * ```typescript
+ * const labels = await Sol.getAllDexLabels()
+ * // ['Raydium', 'Raydium CLMM', 'Orca V2', 'Whirlpool', ...]
+ * ```
+ */
+export async function getAllDexLabels(config) {
+    const map = await getProgramIdToLabel(config);
+    return [...new Set(Object.values(map))].sort();
+}
+/**
+ * 通过标签获取 Program ID
+ *
+ * @param label DEX 标签
+ * @param config Jupiter 配置
+ * @returns Program ID 或 null
+ *
+ * @example
+ * ```typescript
+ * const raydiumId = await Sol.getProgramIdByLabel('Raydium')
+ * // '675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8'
+ * ```
+ */
+export async function getProgramIdByLabel(label, config) {
+    const map = await getProgramIdToLabel(config);
+    for (const [programId, dexLabel] of Object.entries(map)) {
+        if (dexLabel === label) {
+            return programId;
+        }
+    }
+    return null;
+}
+/**
+ * 通过 Program ID 获取 DEX 标签
+ *
+ * @param programId Program ID
+ * @param config Jupiter 配置
+ * @returns DEX 标签或 null
+ *
+ * @example
+ * ```typescript
+ * const label = await Sol.getLabelByProgramId(
+ *   '675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8'
+ * )
+ * // 'Raydium'
+ * ```
+ */
+export async function getLabelByProgramId(programId, config) {
+    const map = await getProgramIdToLabel(config);
+    return map[programId] || 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 async function searchDex(keyword, config) {
+    const map = await getProgramIdToLabel(config);
+    const lowerKeyword = keyword.toLowerCase();
+    return Object.entries(map)
+        .filter(([, label]) => label.toLowerCase().includes(lowerKeyword))
+        .map(([programId, label]) => ({ programId, label }));
+}
+// ============================================================================
+// 便捷方法
+// ============================================================================
+/**
+ * 获取路由标签
+ *
+ * @param quote Quote 响应
+ * @returns 路由标签数组
+ */
+export function getRouteLabels(quote) {
+    return quote.routePlan
+        .map(r => r.swapInfo.label)
+        .filter((label) => !!label);
+}
+/**
+ * 计算路由跳数
+ *
+ * @param quote Quote 响应
+ * @returns 跳数
+ */
+export function getRouteHops(quote) {
+    return quote.routePlan.length;
+}
+/**
+ * 获取报价摘要
+ *
+ * @param quote Quote 响应
+ * @returns 报价摘要
+ */
+export function getQuoteSummary(quote) {
+    return {
+        inputMint: quote.inputMint,
+        outputMint: quote.outputMint,
+        inAmount: quote.inAmount,
+        outAmount: quote.outAmount,
+        minOutAmount: quote.otherAmountThreshold,
+        priceImpact: parseFloat(quote.priceImpactPct),
+        slippageBps: quote.slippageBps,
+        route: getRouteLabels(quote).join(' → '),
+        hops: getRouteHops(quote),
+        usdValue: quote.swapUsdValue ? parseFloat(quote.swapUsdValue) : null,
+    };
+}
+/**
+ * 比较多个报价
+ *
+ * @param quotes Quote 响应数组
+ * @returns 排序后的报价（输出最多的在前）
+ */
+export function compareQuotes(quotes) {
+    return [...quotes].sort((a, b) => {
+        const outA = BigInt(a.outAmount);
+        const outB = BigInt(b.outAmount);
+        if (outB > outA)
+            return 1;
+        if (outB < outA)
+            return -1;
+        return 0;
+    });
+}
+/**
+ * 获取最佳报价
+ *
+ * 比较不同 DEX 组合的报价，返回输出最多的
+ *
+ * @param inputMint 输入代币 Mint
+ * @param outputMint 输出代币 Mint
+ * @param amount 数量
+ * @param options 选项
+ * @param config Jupiter 配置
+ * @returns 最佳报价
+ */
+export async function getBestLegacyQuote(inputMint, outputMint, amount, options, config) {
+    const slippageBps = options?.slippageBps ?? 50;
+    // 获取普通报价
+    const normalQuote = await getLegacyQuote({
+        inputMint,
+        outputMint,
+        amount,
+        slippageBps,
+    }, config);
+    let directQuote = null;
+    let directSavings = null;
+    // 可选：比较直接路由
+    if (options?.compareDirectRoute) {
+        try {
+            directQuote = await getLegacyQuote({
+                inputMint,
+                outputMint,
+                amount,
+                slippageBps,
+                onlyDirectRoutes: true,
+            }, config);
+            // 计算差异
+            const normalOut = BigInt(normalQuote.outAmount);
+            const directOut = BigInt(directQuote.outAmount);
+            if (normalOut > directOut) {
+                directSavings = (normalOut - directOut).toString();
+            }
+        }
+        catch {
+            // 直接路由可能不可用
+        }
+    }
+    return {
+        best: normalQuote,
+        direct: directQuote,
+        directSavings,
+    };
+}