four-flap-meme-sdk 1.5.55 → 1.5.56

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

@@ -0,0 +1,397 @@
+/**
+ * Jupiter Trigger API (限价单/触发订单)
+ * @module sol/dex/jup/trigger
+ *
+ * Trigger API 提供限价单功能
+ * 用户可以创建、取消和查询触发订单
+ */
+import { jupGet, jupPost } from './client.js';
+// ============================================================================
+// Create Order - 创建订单
+// ============================================================================
+/**
+ * 创建触发订单（限价单）
+ *
+ * 创建一个在指定价格执行的订单。
+ *
+ * @param params 创建订单参数
+ * @param config Jupiter 配置
+ * @returns 创建订单响应
+ *
+ * @example
+ * ```typescript
+ * import { Sol } from 'four-flap-meme-sdk'
+ *
+ * Sol.setJupiterConfig({ apiKey: 'your-api-key' })
+ *
+ * // 创建限价单：用 100 USDC 换取至少 0.5 SOL
+ * const result = await Sol.createTriggerOrder({
+ *   inputMint: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', // USDC
+ *   outputMint: 'So11111111111111111111111111111111111111112',  // SOL
+ *   maker: wallet.publicKey.toBase58(),
+ *   payer: wallet.publicKey.toBase58(),
+ *   params: {
+ *     makingAmount: '100000000', // 100 USDC (6 decimals)
+ *     takingAmount: '500000000', // 0.5 SOL (9 decimals)
+ *     slippageBps: 0,
+ *   },
+ *   computeUnitPrice: 'auto',
+ *   wrapAndUnwrapSol: true,
+ * })
+ *
+ * console.log('订单账户:', result.order)
+ * console.log('请求 ID:', result.requestId)
+ *
+ * // 签名并发送交易
+ * const tx = VersionedTransaction.deserialize(
+ *   Buffer.from(result.transaction, 'base64')
+ * )
+ * tx.sign([wallet])
+ * const signature = await connection.sendTransaction(tx)
+ * ```
+ */
+export async function createTriggerOrder(params, config) {
+    return jupPost('/trigger/v1/createOrder', params, config);
+}
+/**
+ * 创建简单限价单
+ *
+ * @param inputMint 输入代币 Mint
+ * @param outputMint 输出代币 Mint
+ * @param maker Maker 地址
+ * @param makingAmount 输入数量
+ * @param takingAmount 期望输出数量
+ * @param options 可选参数
+ * @param config Jupiter 配置
+ * @returns 创建订单响应
+ *
+ * @example
+ * ```typescript
+ * const result = await Sol.createSimpleTriggerOrder(
+ *   'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', // USDC
+ *   'So11111111111111111111111111111111111111112',  // SOL
+ *   wallet.publicKey.toBase58(),
+ *   '100000000', // 100 USDC
+ *   '500000000', // 0.5 SOL
+ * )
+ * ```
+ */
+export async function createSimpleTriggerOrder(inputMint, outputMint, maker, makingAmount, takingAmount, options, config) {
+    return createTriggerOrder({
+        inputMint,
+        outputMint,
+        maker,
+        payer: maker,
+        params: {
+            makingAmount,
+            takingAmount,
+            slippageBps: options?.slippageBps ?? 0,
+            expiredAt: options?.expiredAt,
+        },
+        computeUnitPrice: options?.computeUnitPrice ?? 'auto',
+        wrapAndUnwrapSol: options?.wrapAndUnwrapSol ?? true,
+    }, config);
+}
+// ============================================================================
+// Cancel Order - 取消订单
+// ============================================================================
+/**
+ * 取消单个触发订单
+ *
+ * @param params 取消订单参数
+ * @param config Jupiter 配置
+ * @returns 取消订单响应
+ *
+ * @example
+ * ```typescript
+ * const result = await Sol.cancelTriggerOrder({
+ *   maker: wallet.publicKey.toBase58(),
+ *   order: 'orderAccountAddress',
+ * })
+ *
+ * // 签名并发送
+ * const tx = VersionedTransaction.deserialize(
+ *   Buffer.from(result.transaction, 'base64')
+ * )
+ * tx.sign([wallet])
+ *
+ * // 执行
+ * await Sol.executeTriggerOrder({
+ *   requestId: result.requestId,
+ *   signedTransaction: Buffer.from(tx.serialize()).toString('base64'),
+ * })
+ * ```
+ */
+export async function cancelTriggerOrder(params, config) {
+    return jupPost('/trigger/v1/cancelOrder', params, config);
+}
+/**
+ * 批量取消触发订单
+ *
+ * @param params 批量取消参数
+ * @param config Jupiter 配置
+ * @returns 批量取消响应（包含多个交易）
+ *
+ * @example
+ * ```typescript
+ * const result = await Sol.cancelTriggerOrders({
+ *   maker: wallet.publicKey.toBase58(),
+ *   orders: ['order1', 'order2'],
+ * })
+ *
+ * // 需要签名并执行每个交易
+ * for (const txBase64 of result.transactions) {
+ *   const tx = VersionedTransaction.deserialize(Buffer.from(txBase64, 'base64'))
+ *   tx.sign([wallet])
+ *   await connection.sendTransaction(tx)
+ * }
+ * ```
+ */
+export async function cancelTriggerOrders(params, config) {
+    return jupPost('/trigger/v1/cancelOrders', params, config);
+}
+/**
+ * 快捷取消单个订单
+ *
+ * @param maker Maker 地址
+ * @param orderAccount 订单账户地址
+ * @param config Jupiter 配置
+ * @returns 取消订单响应
+ */
+export async function cancelSingleTriggerOrder(maker, orderAccount, config) {
+    return cancelTriggerOrder({
+        maker,
+        order: orderAccount,
+        computeUnitPrice: 'auto',
+    }, config);
+}
+// ============================================================================
+// Execute - 执行交易
+// ============================================================================
+/**
+ * 执行已签名的触发订单交易
+ *
+ * 将签名后的交易发送到 Jupiter 执行。
+ *
+ * @param params 执行参数
+ * @param config Jupiter 配置
+ * @returns 执行结果
+ *
+ * @example
+ * ```typescript
+ * // 1. 创建订单
+ * const createResult = await Sol.createTriggerOrder({
+ *   inputMint: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+ *   outputMint: 'So11111111111111111111111111111111111111112',
+ *   maker: wallet.publicKey.toBase58(),
+ *   payer: wallet.publicKey.toBase58(),
+ *   params: {
+ *     makingAmount: '100000000',
+ *     takingAmount: '500000000',
+ *   },
+ * })
+ *
+ * // 2. 签名交易
+ * const tx = VersionedTransaction.deserialize(
+ *   Buffer.from(createResult.transaction, 'base64')
+ * )
+ * tx.sign([wallet])
+ *
+ * // 3. 执行交易
+ * const executeResult = await Sol.executeTriggerOrder({
+ *   requestId: createResult.requestId,
+ *   signedTransaction: Buffer.from(tx.serialize()).toString('base64'),
+ * })
+ *
+ * if (executeResult.status === 'Success') {
+ *   console.log('订单创建成功:', executeResult.signature)
+ * }
+ * ```
+ */
+export async function executeTriggerOrder(params, config) {
+    return jupPost('/trigger/v1/execute', params, config);
+}
+/**
+ * 创建订单并执行（一步完成）
+ *
+ * @param params 创建订单参数
+ * @param signTransaction 签名函数
+ * @param config Jupiter 配置
+ * @returns 执行结果和订单账户
+ *
+ * @example
+ * ```typescript
+ * const result = await Sol.createAndExecuteTriggerOrder(
+ *   {
+ *     inputMint: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+ *     outputMint: 'So11111111111111111111111111111111111111112',
+ *     maker: wallet.publicKey.toBase58(),
+ *     payer: wallet.publicKey.toBase58(),
+ *     params: {
+ *       makingAmount: '100000000',
+ *       takingAmount: '500000000',
+ *     },
+ *   },
+ *   async (tx) => {
+ *     tx.sign([wallet])
+ *     return tx
+ *   }
+ * )
+ *
+ * console.log('签名:', result.signature)
+ * console.log('订单:', result.order)
+ * ```
+ */
+export async function createAndExecuteTriggerOrder(params, signTransaction, config) {
+    // 1. 创建订单
+    const createResult = await createTriggerOrder(params, config);
+    // 2. 反序列化并签名
+    // 注意：这里假设使用者会在 signTransaction 中处理反序列化
+    const signedTx = await signTransaction(createResult.transaction);
+    // 3. 执行
+    const executeResult = await executeTriggerOrder({
+        requestId: createResult.requestId,
+        signedTransaction: signedTx,
+    }, config);
+    return {
+        ...executeResult,
+        order: createResult.order,
+    };
+}
+// ============================================================================
+// Get Orders - 获取订单
+// ============================================================================
+/**
+ * 获取用户的触发订单（带分页）
+ *
+ * @param params 查询参数
+ * @param config Jupiter 配置
+ * @returns 订单列表响应（含分页信息）
+ *
+ * @example
+ * ```typescript
+ * // 获取活跃订单
+ * const activeOrders = await Sol.getTriggerOrders({
+ *   user: wallet.publicKey.toBase58(),
+ *   orderStatus: 'active',
+ *   page: 1,
+ * })
+ *
+ * console.log(`共 ${activeOrders.totalPages} 页`)
+ * activeOrders.orders.forEach(order => {
+ *   console.log(`订单: ${order.orderKey}`)
+ *   console.log(`  ${order.makingAmount} -> ${order.takingAmount}`)
+ *   console.log(`  状态: ${order.status}`)
+ *   console.log(`  交易数: ${order.trades.length}`)
+ * })
+ *
+ * // 获取历史订单
+ * const history = await Sol.getTriggerOrders({
+ *   user: wallet.publicKey.toBase58(),
+ *   orderStatus: 'history',
+ * })
+ * ```
+ */
+export async function getTriggerOrders(params, config) {
+    const queryParams = {};
+    if (params.user)
+        queryParams.user = params.user;
+    if (params.page)
+        queryParams.page = params.page;
+    if (params.orderStatus)
+        queryParams.orderStatus = params.orderStatus;
+    return jupGet('/trigger/v1/getTriggerOrders', queryParams, config);
+}
+/**
+ * 获取用户的活跃订单
+ *
+ * @param user 用户地址
+ * @param page 页码（默认: 1）
+ * @param config Jupiter 配置
+ * @returns 活跃订单响应
+ */
+export async function getActiveTriggerOrders(user, page = 1, config) {
+    return getTriggerOrders({ user, orderStatus: 'active', page }, config);
+}
+/**
+ * 获取用户的历史订单
+ *
+ * @param user 用户地址
+ * @param page 页码（默认: 1）
+ * @param config Jupiter 配置
+ * @returns 历史订单响应
+ */
+export async function getHistoryTriggerOrders(user, page = 1, config) {
+    return getTriggerOrders({ user, orderStatus: 'history', page }, config);
+}
+/**
+ * 获取所有活跃订单（自动分页）
+ *
+ * @param user 用户地址
+ * @param config Jupiter 配置
+ * @returns 所有活跃订单
+ */
+export async function getAllActiveTriggerOrders(user, config) {
+    const allOrders = [];
+    let page = 1;
+    while (true) {
+        const response = await getActiveTriggerOrders(user, page, config);
+        allOrders.push(...response.orders);
+        if (page >= response.totalPages)
+            break;
+        page++;
+    }
+    return allOrders;
+}
+// ============================================================================
+// 便捷方法
+// ============================================================================
+/**
+ * 计算限价单价格
+ *
+ * @param makingAmount 输入数量
+ * @param makingDecimals 输入代币精度
+ * @param takingAmount 输出数量
+ * @param takingDecimals 输出代币精度
+ * @returns 价格 (输出/输入)
+ *
+ * @example
+ * ```typescript
+ * // 100 USDC -> 0.5 SOL
+ * const price = Sol.calculateTriggerPrice(
+ *   '100000000', 6,  // 100 USDC
+ *   '500000000', 9,  // 0.5 SOL
+ * )
+ * console.log('价格:', price, 'SOL/USDC') // 0.005
+ * ```
+ */
+export function calculateTriggerPrice(makingAmount, makingDecimals, takingAmount, takingDecimals) {
+    const making = Number(makingAmount) / Math.pow(10, makingDecimals);
+    const taking = Number(takingAmount) / Math.pow(10, takingDecimals);
+    return taking / making;
+}
+/**
+ * 从价格计算 takingAmount
+ *
+ * @param makingAmount 输入数量
+ * @param makingDecimals 输入代币精度
+ * @param price 期望价格 (输出/输入)
+ * @param takingDecimals 输出代币精度
+ * @returns takingAmount
+ *
+ * @example
+ * ```typescript
+ * // 100 USDC，价格 0.005 SOL/USDC
+ * const takingAmount = Sol.calculateTakingAmount(
+ *   '100000000', 6,  // 100 USDC
+ *   0.005,           // 价格
+ *   9,               // SOL 精度
+ * )
+ * console.log('takingAmount:', takingAmount) // '500000000'
+ * ```
+ */
+export function calculateTakingAmount(makingAmount, makingDecimals, price, takingDecimals) {
+    const making = Number(makingAmount) / Math.pow(10, makingDecimals);
+    const taking = making * price;
+    return Math.floor(taking * Math.pow(10, takingDecimals)).toString();
+}