four-flap-meme-sdk 1.5.55 → 1.5.56

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

@@ -0,0 +1,511 @@
+/**
+ * Jupiter Trigger API (限价单/触发订单)
+ * @module sol/dex/jup/trigger
+ *
+ * Trigger API 提供限价单功能
+ * 用户可以创建、取消和查询触发订单
+ */
+import type { JupiterConfig } from './types.js';
+/** 订单参数 */
+export interface TriggerOrderParams {
+    /** 输入代币数量 (最小单位) */
+    makingAmount: string;
+    /** 输出代币数量 (最小单位) */
+    takingAmount: string;
+    /** 过期时间 (Unix 时间戳，可选) */
+    expiredAt?: string;
+    /** 滑点 BPS (默认: 0) */
+    slippageBps?: number | string;
+    /** 手续费 BPS (需要 feeAccount) */
+    feeBps?: string;
+}
+/** 创建订单请求参数 */
+export interface TriggerCreateOrderParams {
+    /** 输入代币 Mint */
+    inputMint: string;
+    /** 输出代币 Mint */
+    outputMint: string;
+    /** Maker 地址 (订单创建者) */
+    maker: string;
+    /** Payer 地址 (支付者，通常与 maker 相同) */
+    payer: string;
+    /** 订单参数 */
+    params: TriggerOrderParams;
+    /**
+     * 计算单元价格 (微 lamports)
+     * 默认: 'auto' (95th percentile)
+     */
+    computeUnitPrice?: string | 'auto';
+    /** 手续费账户 (Token 账户，通过 Referral Program) */
+    feeAccount?: string;
+    /** 是否自动包装/解包 SOL (默认: true) */
+    wrapAndUnwrapSol?: boolean;
+}
+/** 创建订单响应 */
+export interface TriggerCreateOrderResponse {
+    /** 请求 ID (用于 /execute) */
+    requestId: string;
+    /** Base64 编码的未签名交易 */
+    transaction: string;
+    /** 订单账户地址 (Base58) */
+    order?: string;
+}
+/** 取消单个订单请求参数 */
+export interface TriggerCancelSingleOrderParams {
+    /** Maker 地址 */
+    maker: string;
+    /** 订单账户地址 */
+    order: string;
+    /** 计算单元价格 */
+    computeUnitPrice?: string | 'auto';
+}
+/** 取消单个订单响应 */
+export interface TriggerCancelSingleOrderResponse {
+    /** 请求 ID */
+    requestId: string;
+    /** Base64 编码的未签名交易 */
+    transaction: string;
+}
+/** 批量取消订单请求参数 */
+export interface TriggerCancelOrdersParams {
+    /** Maker 地址 */
+    maker: string;
+    /** 订单账户地址数组 */
+    orders: string[];
+    /** 计算单元价格 */
+    computeUnitPrice?: string | 'auto';
+}
+/** 批量取消订单响应 */
+export interface TriggerCancelOrdersResponse {
+    /** 请求 ID */
+    requestId: string;
+    /** Base64 编码的未签名交易数组 */
+    transactions: string[];
+}
+/** 执行交易请求参数 */
+export interface TriggerExecuteParams {
+    /** 请求 ID (来自 createOrder 或 cancelOrder 响应) */
+    requestId: string;
+    /** 已签名的交易 (Base64) */
+    signedTransaction: string;
+}
+/** 执行状态 */
+export type TriggerExecuteStatus = 'Success' | 'Failed';
+/** 执行交易响应 */
+export interface TriggerExecuteResponse {
+    /** 状态码 */
+    code: number;
+    /** 交易签名 */
+    signature: string;
+    /** 执行状态 */
+    status: TriggerExecuteStatus;
+}
+/** 订单状态 */
+export type TriggerOrderStatus = 'Open' | 'Completed' | 'Cancelled' | 'Expired';
+/** 订单列表状态 */
+export type TriggerOrderListStatus = 'active' | 'history';
+/** 交易记录 */
+export interface TriggerTrade {
+    /** 订单账户地址 */
+    orderKey: string;
+    /** Keeper 地址 */
+    keeper: string;
+    /** 输入代币 Mint */
+    inputMint: string;
+    /** 输出代币 Mint */
+    outputMint: string;
+    /** 输入数量 (UI) */
+    inputAmount: string;
+    /** 输出数量 (UI) */
+    outputAmount: string;
+    /** 原始输入数量 */
+    rawInputAmount: string;
+    /** 原始输出数量 */
+    rawOutputAmount: string;
+    /** 手续费代币 Mint */
+    feeMint: string;
+    /** 手续费数量 (UI) */
+    feeAmount: string;
+    /** 原始手续费数量 */
+    rawFeeAmount: string;
+    /** 交易签名 */
+    txId: string;
+    /** 确认时间 */
+    confirmedAt: string;
+    /** 操作类型 */
+    action: string;
+    /** 产品元数据 */
+    productMeta?: unknown;
+}
+/** 订单详细信息 */
+export interface TriggerOrderDetail {
+    /** 用户公钥 */
+    userPubkey: string;
+    /** 订单账户地址 */
+    orderKey: string;
+    /** 输入代币 Mint */
+    inputMint: string;
+    /** 输出代币 Mint */
+    outputMint: string;
+    /** 输入数量 (UI) */
+    makingAmount: string;
+    /** 输出数量 (UI) */
+    takingAmount: string;
+    /** 剩余输入数量 (UI) */
+    remainingMakingAmount: string;
+    /** 剩余输出数量 (UI) */
+    remainingTakingAmount: string;
+    /** 原始输入数量 */
+    rawMakingAmount: string;
+    /** 原始输出数量 */
+    rawTakingAmount: string;
+    /** 原始剩余输入数量 */
+    rawRemainingMakingAmount: string;
+    /** 原始剩余输出数量 */
+    rawRemainingTakingAmount: string;
+    /** 滑点 BPS */
+    slippageBps: string;
+    /** 过期时间 */
+    expiredAt: string | null;
+    /** 创建时间 */
+    createdAt: string;
+    /** 更新时间 */
+    updatedAt: string;
+    /** 状态 */
+    status: TriggerOrderStatus;
+    /** 开单交易签名 */
+    openTx: string;
+    /** 关单交易签名 */
+    closeTx: string;
+    /** 程序版本 */
+    programVersion: string;
+    /** 交易记录 */
+    trades: TriggerTrade[];
+}
+/** 获取订单响应 */
+export interface TriggerGetOrdersResponse {
+    /** 用户地址 */
+    user: string;
+    /** 订单状态类型 */
+    orderStatus: TriggerOrderListStatus;
+    /** 订单列表 */
+    orders: TriggerOrderDetail[];
+    /** 总页数 */
+    totalPages: number;
+    /** 当前页 */
+    page: number;
+}
+/** 获取订单参数 */
+export interface TriggerGetOrdersParams {
+    /** 用户地址 */
+    user?: string;
+    /** 页码 (默认: 1) */
+    page?: number;
+    /** 订单状态 ('active' | 'history') */
+    orderStatus?: TriggerOrderListStatus;
+}
+/**
+ * 创建触发订单（限价单）
+ *
+ * 创建一个在指定价格执行的订单。
+ *
+ * @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 declare function createTriggerOrder(params: TriggerCreateOrderParams, config?: JupiterConfig): Promise<TriggerCreateOrderResponse>;
+/**
+ * 创建简单限价单
+ *
+ * @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 declare function createSimpleTriggerOrder(inputMint: string, outputMint: string, maker: string, makingAmount: string, takingAmount: string, options?: {
+    slippageBps?: number;
+    expiredAt?: string;
+    computeUnitPrice?: string | 'auto';
+    wrapAndUnwrapSol?: boolean;
+}, config?: JupiterConfig): Promise<TriggerCreateOrderResponse>;
+/**
+ * 取消单个触发订单
+ *
+ * @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 declare function cancelTriggerOrder(params: TriggerCancelSingleOrderParams, config?: JupiterConfig): Promise<TriggerCancelSingleOrderResponse>;
+/**
+ * 批量取消触发订单
+ *
+ * @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 declare function cancelTriggerOrders(params: TriggerCancelOrdersParams, config?: JupiterConfig): Promise<TriggerCancelOrdersResponse>;
+/**
+ * 快捷取消单个订单
+ *
+ * @param maker Maker 地址
+ * @param orderAccount 订单账户地址
+ * @param config Jupiter 配置
+ * @returns 取消订单响应
+ */
+export declare function cancelSingleTriggerOrder(maker: string, orderAccount: string, config?: JupiterConfig): Promise<TriggerCancelSingleOrderResponse>;
+/**
+ * 执行已签名的触发订单交易
+ *
+ * 将签名后的交易发送到 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 declare function executeTriggerOrder(params: TriggerExecuteParams, config?: JupiterConfig): Promise<TriggerExecuteResponse>;
+/**
+ * 创建订单并执行（一步完成）
+ *
+ * @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 declare function createAndExecuteTriggerOrder(params: TriggerCreateOrderParams, signTransaction: (tx: unknown) => Promise<unknown>, config?: JupiterConfig): Promise<TriggerExecuteResponse & {
+    order?: string;
+}>;
+/**
+ * 获取用户的触发订单（带分页）
+ *
+ * @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 declare function getTriggerOrders(params: TriggerGetOrdersParams, config?: JupiterConfig): Promise<TriggerGetOrdersResponse>;
+/**
+ * 获取用户的活跃订单
+ *
+ * @param user 用户地址
+ * @param page 页码（默认: 1）
+ * @param config Jupiter 配置
+ * @returns 活跃订单响应
+ */
+export declare function getActiveTriggerOrders(user: string, page?: number, config?: JupiterConfig): Promise<TriggerGetOrdersResponse>;
+/**
+ * 获取用户的历史订单
+ *
+ * @param user 用户地址
+ * @param page 页码（默认: 1）
+ * @param config Jupiter 配置
+ * @returns 历史订单响应
+ */
+export declare function getHistoryTriggerOrders(user: string, page?: number, config?: JupiterConfig): Promise<TriggerGetOrdersResponse>;
+/**
+ * 获取所有活跃订单（自动分页）
+ *
+ * @param user 用户地址
+ * @param config Jupiter 配置
+ * @returns 所有活跃订单
+ */
+export declare function getAllActiveTriggerOrders(user: string, config?: JupiterConfig): Promise<TriggerOrderDetail[]>;
+/**
+ * 计算限价单价格
+ *
+ * @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 declare function calculateTriggerPrice(makingAmount: string, makingDecimals: number, takingAmount: string, takingDecimals: number): number;
+/**
+ * 从价格计算 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 declare function calculateTakingAmount(makingAmount: string, makingDecimals: number, price: number, takingDecimals: number): string;