four-flap-meme-sdk 1.5.55 → 1.5.56

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

@@ -0,0 +1,603 @@
+/**
+ * Jupiter Lend API (Jupiter Earn)
+ * @module sol/dex/jup/lend
+ *
+ * Lend API 提供存款赚息功能
+ * 用户可以存入代币获取 APY 收益
+ */
+import { jupGet, jupPost } from './client.js';
+// ============================================================================
+// Deposit - 存款
+// ============================================================================
+/**
+ * 构建存款交易
+ *
+ * 将代币存入 Jupiter Earn 赚取利息。
+ *
+ * @param params 存款参数
+ * @param config Jupiter 配置
+ * @returns 未签名交易
+ *
+ * @example
+ * ```typescript
+ * import { Sol } from 'four-flap-meme-sdk'
+ *
+ * Sol.setJupiterConfig({ apiKey: 'your-api-key' })
+ *
+ * // 存入 5 USDC
+ * const result = await Sol.buildLendDeposit({
+ *   asset: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', // USDC
+ *   signer: wallet.publicKey.toBase58(),
+ *   amount: '5', // 5 USDC
+ * })
+ *
+ * // 签名并发送
+ * const tx = VersionedTransaction.deserialize(
+ *   Buffer.from(result.transaction, 'base64')
+ * )
+ * tx.sign([wallet])
+ * const signature = await connection.sendTransaction(tx)
+ * ```
+ */
+export async function buildLendDeposit(params, config) {
+    return jupPost('/lend/v1/earn/deposit', params, config);
+}
+// ============================================================================
+// Withdraw - 取款
+// ============================================================================
+/**
+ * 构建取款交易
+ *
+ * 从 Jupiter Earn 取出存款和收益。
+ *
+ * @param params 取款参数
+ * @param config Jupiter 配置
+ * @returns 未签名交易
+ *
+ * @example
+ * ```typescript
+ * // 取出 5 USDC
+ * const result = await Sol.buildLendWithdraw({
+ *   asset: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+ *   signer: wallet.publicKey.toBase58(),
+ *   amount: '5',
+ * })
+ *
+ * // 签名并发送
+ * const tx = VersionedTransaction.deserialize(
+ *   Buffer.from(result.transaction, 'base64')
+ * )
+ * tx.sign([wallet])
+ * await connection.sendTransaction(tx)
+ * ```
+ */
+export async function buildLendWithdraw(params, config) {
+    return jupPost('/lend/v1/earn/withdraw', params, config);
+}
+// ============================================================================
+// Mint - 按份额存款
+// ============================================================================
+/**
+ * 构建 Mint 交易 (按份额存款)
+ *
+ * 使用份额 (shares) 而非代币数量来存款。
+ * 这是更底层的接口，适合精确控制份额的场景。
+ *
+ * @param params Mint 参数
+ * @param config Jupiter 配置
+ * @returns 未签名交易
+ *
+ * @example
+ * ```typescript
+ * const result = await Sol.buildLendMint({
+ *   asset: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+ *   signer: wallet.publicKey.toBase58(),
+ *   shares: '1000000', // 份额数量
+ * })
+ * ```
+ */
+export async function buildLendMint(params, config) {
+    return jupPost('/lend/v1/earn/mint', params, config);
+}
+// ============================================================================
+// Burn - 按份额取款
+// ============================================================================
+/**
+ * 构建 Burn 交易 (按份额取款)
+ *
+ * 使用份额 (shares) 而非代币数量来取款。
+ * 这是更底层的接口，适合精确控制份额的场景。
+ *
+ * @param params Burn 参数
+ * @param config Jupiter 配置
+ * @returns 未签名交易
+ *
+ * @example
+ * ```typescript
+ * const result = await Sol.buildLendBurn({
+ *   asset: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+ *   signer: wallet.publicKey.toBase58(),
+ *   shares: '1000000', // 份额数量
+ * })
+ * ```
+ */
+export async function buildLendBurn(params, config) {
+    return jupPost('/lend/v1/earn/burn', params, config);
+}
+// ============================================================================
+// Redeem - 按份额赎回
+// ============================================================================
+/**
+ * 构建 Redeem 交易 (按份额赎回)
+ *
+ * 与 Burn 类似，使用份额来赎回代币。
+ *
+ * @param params Redeem 参数
+ * @param config Jupiter 配置
+ * @returns 未签名交易
+ *
+ * @example
+ * ```typescript
+ * const result = await Sol.buildLendRedeem({
+ *   asset: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+ *   signer: wallet.publicKey.toBase58(),
+ *   shares: '1000000',
+ * })
+ * ```
+ */
+export async function buildLendRedeem(params, config) {
+    return jupPost('/lend/v1/earn/redeem', params, config);
+}
+// ============================================================================
+// Instructions - 获取分解指令
+// ============================================================================
+/**
+ * 获取存款指令
+ *
+ * 返回单个指令而非完整交易，适合自定义组装交易。
+ *
+ * @param params 存款参数
+ * @param config Jupiter 配置
+ * @returns 指令
+ *
+ * @example
+ * ```typescript
+ * const instruction = await Sol.getLendDepositInstruction({
+ *   asset: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+ *   signer: wallet.publicKey.toBase58(),
+ *   amount: '5',
+ * })
+ *
+ * // 反序列化为 TransactionInstruction
+ * const ix = 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'),
+ * })
+ * ```
+ */
+export async function getLendDepositInstruction(params, config) {
+    return jupPost('/lend/v1/earn/deposit-instructions', params, config);
+}
+/**
+ * 获取取款指令
+ *
+ * @param params 取款参数
+ * @param config Jupiter 配置
+ * @returns 指令
+ */
+export async function getLendWithdrawInstruction(params, config) {
+    return jupPost('/lend/v1/earn/withdraw-instructions', params, config);
+}
+/**
+ * 获取 Mint 指令
+ *
+ * @param params Mint 参数
+ * @param config Jupiter 配置
+ * @returns 指令
+ */
+export async function getLendMintInstruction(params, config) {
+    return jupPost('/lend/v1/earn/mint-instructions', params, config);
+}
+/**
+ * 获取 Burn 指令
+ *
+ * @param params Burn 参数
+ * @param config Jupiter 配置
+ * @returns 指令
+ */
+export async function getLendBurnInstruction(params, config) {
+    return jupPost('/lend/v1/earn/burn-instructions', params, config);
+}
+/**
+ * 获取 Redeem 指令
+ *
+ * @param params Redeem 参数
+ * @param config Jupiter 配置
+ * @returns 指令
+ */
+export async function getLendRedeemInstruction(params, config) {
+    return jupPost('/lend/v1/earn/redeem-instructions', params, config);
+}
+// ============================================================================
+// Tokens - 获取支持的代币
+// ============================================================================
+/**
+ * 获取所有 Earn 支持的代币
+ *
+ * 返回详细的代币信息，包括：
+ * - jl 代币地址和底层资产地址
+ * - 当前收益率 (APY)
+ * - 总存款量和总供应量
+ * - 份额转换比率
+ * - 流动性数据
+ *
+ * @param config Jupiter 配置
+ * @returns 代币信息数组
+ *
+ * @example
+ * ```typescript
+ * const tokens = await Sol.getEarnTokens()
+ *
+ * tokens.forEach(token => {
+ *   // 计算 APY (基点转百分比)
+ *   const apy = Number(token.totalRate) / 100
+ *
+ *   console.log(`${token.symbol}:`)
+ *   console.log(`  APY: ${apy.toFixed(2)}%`)
+ *   console.log(`  底层资产: ${token.asset.symbol}`)
+ *   console.log(`  价格: $${token.asset.price}`)
+ *   console.log(`  jl代币地址: ${token.address}`)
+ *   console.log(`  资产地址: ${token.assetAddress}`)
+ * })
+ *
+ * // 示例输出:
+ * // jlUSDC:
+ * //   APY: 5.46%
+ * //   底层资产: USDC
+ * //   价格: $0.999730840125
+ * ```
+ */
+export async function getEarnTokens(config) {
+    return jupGet('/lend/v1/earn/tokens', {}, config);
+}
+/**
+ * 获取单个代币的 Earn 信息
+ *
+ * @param assetMint 底层资产 Mint 地址
+ * @param config Jupiter 配置
+ * @returns 代币信息或 null
+ *
+ * @example
+ * ```typescript
+ * const usdcInfo = await Sol.getEarnTokenByAsset(
+ *   'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'
+ * )
+ *
+ * if (usdcInfo) {
+ *   console.log('USDC APY:', Number(usdcInfo.totalRate) / 100, '%')
+ * }
+ * ```
+ */
+export async function getEarnTokenByAsset(assetMint, config) {
+    const tokens = await getEarnTokens(config);
+    return tokens.find(t => t.assetAddress === assetMint) || null;
+}
+/**
+ * 获取所有 Earn APY 信息
+ *
+ * @param config Jupiter 配置
+ * @returns APY 映射 { assetMint: { symbol, apy, supplyRate, rewardsRate } }
+ *
+ * @example
+ * ```typescript
+ * const apys = await Sol.getEarnApys()
+ *
+ * // { 'EPj...': { symbol: 'USDC', apy: 5.46, ... }, ... }
+ * console.log('USDC APY:', apys['EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'].apy)
+ * ```
+ */
+export async function getEarnApys(config) {
+    const tokens = await getEarnTokens(config);
+    const result = {};
+    for (const token of tokens) {
+        result[token.assetAddress] = {
+            symbol: token.asset.symbol,
+            jlSymbol: token.symbol,
+            apy: Number(token.totalRate) / 100, // 基点转百分比
+            supplyRate: Number(token.supplyRate) / 100,
+            rewardsRate: Number(token.rewardsRate) / 100,
+            price: parseFloat(token.asset.price),
+        };
+    }
+    return result;
+}
+/**
+ * 计算份额对应的资产数量
+ *
+ * @param shares 份额数量 (最小单位)
+ * @param tokenInfo 代币信息
+ * @returns 资产数量 (最小单位)
+ */
+export function sharesToAssets(shares, tokenInfo) {
+    const sharesNum = BigInt(shares);
+    const convertToAssets = BigInt(tokenInfo.convertToAssets);
+    // convertToAssets 是 1e6 份额对应的资产数量
+    return sharesNum * convertToAssets / BigInt(1000000);
+}
+/**
+ * 计算资产数量对应的份额
+ *
+ * @param assets 资产数量 (最小单位)
+ * @param tokenInfo 代币信息
+ * @returns 份额数量 (最小单位)
+ */
+export function assetsToShares(assets, tokenInfo) {
+    const assetsNum = BigInt(assets);
+    const convertToShares = BigInt(tokenInfo.convertToShares);
+    // convertToShares 是 1e6 资产对应的份额数量
+    return assetsNum * convertToShares / BigInt(1000000);
+}
+// ============================================================================
+// Positions - 用户仓位
+// ============================================================================
+/**
+ * 获取用户的 Earn 仓位
+ *
+ * 返回用户在所有 Earn 代币的存款仓位。
+ *
+ * @param users 用户地址（支持单个或多个，逗号分隔）
+ * @param config Jupiter 配置
+ * @returns 仓位数组
+ *
+ * @example
+ * ```typescript
+ * const positions = await Sol.getEarnPositions(
+ *   '9yFqMjJgsEcZ8GnEtFqxw1oFbPPVpypMVgYzQWgECFNy'
+ * )
+ *
+ * positions.forEach(pos => {
+ *   if (BigInt(pos.shares) > 0n) {
+ *     console.log(`${pos.token.asset.symbol}:`)
+ *     console.log(`  份额: ${pos.shares}`)
+ *     console.log(`  底层资产: ${pos.underlyingAssets}`)
+ *     console.log(`  APY: ${Number(pos.token.totalRate) / 100}%`)
+ *   }
+ * })
+ * ```
+ */
+export async function getEarnPositions(users, config) {
+    const usersParam = Array.isArray(users) ? users.join(',') : users;
+    return jupGet('/lend/v1/earn/positions', { users: usersParam }, config);
+}
+/**
+ * 获取用户在指定代币的 Earn 仓位
+ *
+ * @param user 用户地址
+ * @param assetMint 底层资产 Mint 地址
+ * @param config Jupiter 配置
+ * @returns 仓位或 null
+ *
+ * @example
+ * ```typescript
+ * const usdcPosition = await Sol.getEarnPositionByAsset(
+ *   '9yFqMjJgsEcZ8GnEtFqxw1oFbPPVpypMVgYzQWgECFNy',
+ *   'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', // USDC
+ * )
+ *
+ * if (usdcPosition && BigInt(usdcPosition.shares) > 0n) {
+ *   console.log('USDC 存款:', usdcPosition.underlyingAssets)
+ * }
+ * ```
+ */
+export async function getEarnPositionByAsset(user, assetMint, config) {
+    const positions = await getEarnPositions(user, config);
+    return positions.find(p => p.token.assetAddress === assetMint) || null;
+}
+/**
+ * 获取用户的非零 Earn 仓位
+ *
+ * @param user 用户地址
+ * @param config Jupiter 配置
+ * @returns 非零仓位数组
+ *
+ * @example
+ * ```typescript
+ * const activePositions = await Sol.getActiveEarnPositions(
+ *   '9yFqMjJgsEcZ8GnEtFqxw1oFbPPVpypMVgYzQWgECFNy'
+ * )
+ *
+ * activePositions.forEach(pos => {
+ *   console.log(`${pos.token.asset.symbol}: ${pos.underlyingAssets}`)
+ * })
+ * ```
+ */
+export async function getActiveEarnPositions(user, config) {
+    const positions = await getEarnPositions(user, config);
+    return positions.filter(p => BigInt(p.shares) > 0n || BigInt(p.underlyingBalance) > 0n);
+}
+/**
+ * 获取用户的 Earn 资产总值 (USD)
+ *
+ * @param user 用户地址
+ * @param config Jupiter 配置
+ * @returns 总值 USD
+ *
+ * @example
+ * ```typescript
+ * const totalValue = await Sol.getEarnTotalValue(
+ *   '9yFqMjJgsEcZ8GnEtFqxw1oFbPPVpypMVgYzQWgECFNy'
+ * )
+ * console.log('Earn 总值: $' + totalValue.toFixed(2))
+ * ```
+ */
+export async function getEarnTotalValue(user, config) {
+    const positions = await getEarnPositions(user, config);
+    let totalValue = 0;
+    for (const pos of positions) {
+        const underlyingAssets = BigInt(pos.underlyingAssets);
+        if (underlyingAssets > 0n) {
+            const price = parseFloat(pos.token.asset.price);
+            const decimals = pos.token.decimals;
+            const uiAmount = Number(underlyingAssets) / Math.pow(10, decimals);
+            totalValue += uiAmount * price;
+        }
+    }
+    return totalValue;
+}
+// ============================================================================
+// Earnings - 收益统计
+// ============================================================================
+/**
+ * 获取用户的收益统计
+ *
+ * 返回用户的存款、取款和收益汇总。
+ *
+ * @param user 用户地址（可选，不传则获取所有）
+ * @param config Jupiter 配置
+ * @returns 收益信息数组
+ *
+ * @example
+ * ```typescript
+ * const earnings = await Sol.getEarnEarnings(
+ *   '9yFqMjJgsEcZ8GnEtFqxw1oFbPPVpypMVgYzQWgECFNy'
+ * )
+ *
+ * earnings.forEach(e => {
+ *   console.log(`代币: ${e.address}`)
+ *   console.log(`  总存款: ${e.totalDeposits}`)
+ *   console.log(`  总取款: ${e.totalWithdraws}`)
+ *   console.log(`  当前余额: ${e.totalBalance}`)
+ *   console.log(`  收益: ${e.earnings}`)
+ * })
+ * ```
+ */
+export async function getEarnEarnings(user, config) {
+    const params = {};
+    if (user) {
+        params.user = user;
+    }
+    return jupGet('/lend/v1/earn/earnings', params, config);
+}
+/**
+ * 获取用户在指定代币的收益
+ *
+ * @param user 用户地址
+ * @param jlTokenAddress jl 代币地址（如 jlUSDC 地址）
+ * @param config Jupiter 配置
+ * @returns 收益信息或 null
+ */
+export async function getEarnEarningsByToken(user, jlTokenAddress, config) {
+    const earnings = await getEarnEarnings(user, config);
+    return earnings.find(e => e.address === jlTokenAddress) || null;
+}
+/**
+ * 获取用户的总收益汇总
+ *
+ * @param user 用户地址
+ * @param config Jupiter 配置
+ * @returns 汇总信息
+ *
+ * @example
+ * ```typescript
+ * const summary = await Sol.getEarnEarningsSummary(user)
+ * console.log('总存款:', summary.totalDeposits)
+ * console.log('总取款:', summary.totalWithdraws)
+ * console.log('总收益:', summary.totalEarnings)
+ * ```
+ */
+export async function getEarnEarningsSummary(user, config) {
+    const earnings = await getEarnEarnings(user, config);
+    let totalDeposits = 0n;
+    let totalWithdraws = 0n;
+    let totalBalance = 0n;
+    let totalEarnings = 0n;
+    for (const e of earnings) {
+        totalDeposits += BigInt(e.totalDeposits || '0');
+        totalWithdraws += BigInt(e.totalWithdraws || '0');
+        totalBalance += BigInt(e.totalBalance || '0');
+        totalEarnings += BigInt(e.earnings || '0');
+    }
+    return {
+        totalDeposits,
+        totalWithdraws,
+        totalBalance,
+        totalEarnings,
+    };
+}
+// ============================================================================
+// 便捷方法
+// ============================================================================
+/** 常见的 Earn 支持代币 */
+export const LEND_SUPPORTED_ASSETS = {
+    /** USDC */
+    USDC: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+    /** USDT */
+    USDT: 'Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB',
+    /** SOL */
+    SOL: 'So11111111111111111111111111111111111111112',
+};
+/**
+ * 存入 USDC
+ *
+ * @param signer 签名者公钥
+ * @param amount 数量 (UI 数量，如 "100" 表示 100 USDC)
+ * @param config Jupiter 配置
+ * @returns 未签名交易
+ */
+export async function depositUsdc(signer, amount, config) {
+    return buildLendDeposit({
+        asset: LEND_SUPPORTED_ASSETS.USDC,
+        signer,
+        amount,
+    }, config);
+}
+/**
+ * 取出 USDC
+ *
+ * @param signer 签名者公钥
+ * @param amount 数量
+ * @param config Jupiter 配置
+ * @returns 未签名交易
+ */
+export async function withdrawUsdc(signer, amount, config) {
+    return buildLendWithdraw({
+        asset: LEND_SUPPORTED_ASSETS.USDC,
+        signer,
+        amount,
+    }, config);
+}
+/**
+ * 存入 SOL
+ *
+ * @param signer 签名者公钥
+ * @param amount 数量 (UI 数量，如 "1" 表示 1 SOL)
+ * @param config Jupiter 配置
+ * @returns 未签名交易
+ */
+export async function depositSol(signer, amount, config) {
+    return buildLendDeposit({
+        asset: LEND_SUPPORTED_ASSETS.SOL,
+        signer,
+        amount,
+    }, config);
+}
+/**
+ * 取出 SOL
+ *
+ * @param signer 签名者公钥
+ * @param amount 数量
+ * @param config Jupiter 配置
+ * @returns 未签名交易
+ */
+export async function withdrawSol(signer, amount, config) {
+    return buildLendWithdraw({
+        asset: LEND_SUPPORTED_ASSETS.SOL,
+        signer,
+        amount,
+    }, config);
+}