four-flap-meme-sdk 1.4.90 → 1.4.92

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

@@ -0,0 +1,640 @@
+/**
+ * Jupiter Lend API (Jupiter Earn)
+ * @module sol/dex/jup/lend
+ *
+ * Lend API 提供存款赚息功能
+ * 用户可以存入代币获取 APY 收益
+ */
+import type { JupiterConfig } from './types.js';
+/** 存款请求参数 */
+export interface LendDepositParams {
+    /** 代币 Mint 地址 */
+    asset: string;
+    /** 签名者/用户公钥 */
+    signer: string;
+    /** 存款数量 (UI 数量，如 "5" 表示 5 USDC) */
+    amount: string;
+}
+/** 取款请求参数 */
+export interface LendWithdrawParams {
+    /** 代币 Mint 地址 */
+    asset: string;
+    /** 签名者/用户公钥 */
+    signer: string;
+    /** 取款数量 (UI 数量) */
+    amount: string;
+}
+/** Mint 请求参数 (按份额存款) */
+export interface LendMintParams {
+    /** 代币 Mint 地址 */
+    asset: string;
+    /** 签名者/用户公钥 */
+    signer: string;
+    /** 份额数量 (最小单位) */
+    shares: string;
+}
+/** Burn 请求参数 (按份额取款) */
+export interface LendBurnParams {
+    /** 代币 Mint 地址 */
+    asset: string;
+    /** 签名者/用户公钥 */
+    signer: string;
+    /** 份额数量 (最小单位) */
+    shares: string;
+}
+/** Redeem 请求参数 (按份额赎回) */
+export interface LendRedeemParams {
+    /** 代币 Mint 地址 */
+    asset: string;
+    /** 签名者/用户公钥 */
+    signer: string;
+    /** 份额数量 (最小单位) */
+    shares: string;
+}
+/** 交易响应 */
+export interface LendTransactionResponse {
+    /** Base64 编码的未签名交易 */
+    transaction: string;
+}
+/** 账户信息 */
+export interface LendInstructionAccount {
+    /** 账户公钥 */
+    pubkey: string;
+    /** 是否是签名者 */
+    isSigner: boolean;
+    /** 是否可写 */
+    isWritable: boolean;
+}
+/** 指令响应 */
+export interface LendInstructionResponse {
+    /** Program ID */
+    programId: string;
+    /** 账户列表 */
+    accounts: LendInstructionAccount[];
+    /** 指令数据 (Base64) */
+    data: string;
+}
+/** 底层资产信息 */
+export interface LendUnderlyingAsset {
+    /** 资产地址 */
+    address: string;
+    /** 链 ID */
+    chainId: string;
+    /** 名称 */
+    name: string;
+    /** 符号 */
+    symbol: string;
+    /** 精度 */
+    decimals: number;
+    /** Logo URL */
+    logoUrl: string;
+    /** 价格 (USD) */
+    price: string;
+    /** CoinGecko ID */
+    coingeckoId: string;
+}
+/** 流动性供应数据 */
+export interface LendLiquiditySupplyData {
+    /** 带利息模式 */
+    modeWithInterest: boolean;
+    /** 总供应量 */
+    supply: string;
+    /** 提款限额 */
+    withdrawalLimit: string;
+    /** 最后更新时间戳 */
+    lastUpdateTimestamp: string;
+    /** 扩展百分比 */
+    expandPercent: number;
+    /** 扩展持续时间 */
+    expandDuration: string;
+    /** 基础提款限额 */
+    baseWithdrawalLimit: string;
+    /** 距离限额可提款金额 */
+    withdrawableUntilLimit: string;
+    /** 可提款金额 */
+    withdrawable: string;
+}
+/** Earn 代币信息 */
+export interface LendTokenInfo {
+    /** ID */
+    id: number;
+    /** jl 代币地址 (如 jlUSDC) */
+    address: string;
+    /** 名称 (如 "jupiter lend USDC") */
+    name: string;
+    /** 符号 (如 "jlUSDC") */
+    symbol: string;
+    /** 精度 */
+    decimals: number;
+    /** 底层资产地址 */
+    assetAddress: string;
+    /** 底层资产信息 */
+    asset: LendUnderlyingAsset;
+    /** 总资产 (最小单位) */
+    totalAssets: string;
+    /** 总供应量 (最小单位) */
+    totalSupply: string;
+    /** 资产转份额比率 */
+    convertToShares: string;
+    /** 份额转资产比率 */
+    convertToAssets: string;
+    /** 奖励率 (基点) */
+    rewardsRate: string;
+    /** 供应率 (基点) */
+    supplyRate: string;
+    /** 总收益率 (基点) = rewardsRate + supplyRate */
+    totalRate: string;
+    /** 再平衡差异 */
+    rebalanceDifference: string;
+    /** 流动性供应数据 */
+    liquiditySupplyData: LendLiquiditySupplyData;
+    /** 奖励列表 */
+    rewards: unknown[];
+}
+/** 用户存款仓位 */
+export interface LendPosition {
+    /** 代币信息 */
+    token: LendTokenInfo;
+    /** 持有者地址 */
+    ownerAddress: string;
+    /** 份额数量 (最小单位) */
+    shares: string;
+    /** 底层资产数量 (最小单位) */
+    underlyingAssets: string;
+    /** 底层资产余额 (最小单位) */
+    underlyingBalance: string;
+    /** 授权额度 */
+    allowance: string;
+}
+/** 用户收益信息 */
+export interface LendEarnings {
+    /** jl 代币地址 */
+    address: string;
+    /** 用户地址 */
+    ownerAddress: string;
+    /** 总存款 */
+    totalDeposits: string;
+    /** 总取款 */
+    totalWithdraws: string;
+    /** 总余额 */
+    totalBalance: string;
+    /** 总资产 */
+    totalAssets: string;
+    /** 收益 (利息) */
+    earnings: string;
+}
+/**
+ * 构建存款交易
+ *
+ * 将代币存入 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 declare function buildLendDeposit(params: LendDepositParams, config?: JupiterConfig): Promise<LendTransactionResponse>;
+/**
+ * 构建取款交易
+ *
+ * 从 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 declare function buildLendWithdraw(params: LendWithdrawParams, config?: JupiterConfig): Promise<LendTransactionResponse>;
+/**
+ * 构建 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 declare function buildLendMint(params: LendMintParams, config?: JupiterConfig): Promise<LendTransactionResponse>;
+/**
+ * 构建 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 declare function buildLendBurn(params: LendBurnParams, config?: JupiterConfig): Promise<LendTransactionResponse>;
+/**
+ * 构建 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 declare function buildLendRedeem(params: LendRedeemParams, config?: JupiterConfig): Promise<LendTransactionResponse>;
+/**
+ * 获取存款指令
+ *
+ * 返回单个指令而非完整交易，适合自定义组装交易。
+ *
+ * @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 declare function getLendDepositInstruction(params: LendDepositParams, config?: JupiterConfig): Promise<LendInstructionResponse>;
+/**
+ * 获取取款指令
+ *
+ * @param params 取款参数
+ * @param config Jupiter 配置
+ * @returns 指令
+ */
+export declare function getLendWithdrawInstruction(params: LendWithdrawParams, config?: JupiterConfig): Promise<LendInstructionResponse>;
+/**
+ * 获取 Mint 指令
+ *
+ * @param params Mint 参数
+ * @param config Jupiter 配置
+ * @returns 指令
+ */
+export declare function getLendMintInstruction(params: LendMintParams, config?: JupiterConfig): Promise<LendInstructionResponse>;
+/**
+ * 获取 Burn 指令
+ *
+ * @param params Burn 参数
+ * @param config Jupiter 配置
+ * @returns 指令
+ */
+export declare function getLendBurnInstruction(params: LendBurnParams, config?: JupiterConfig): Promise<LendInstructionResponse>;
+/**
+ * 获取 Redeem 指令
+ *
+ * @param params Redeem 参数
+ * @param config Jupiter 配置
+ * @returns 指令
+ */
+export declare function getLendRedeemInstruction(params: LendRedeemParams, config?: JupiterConfig): Promise<LendInstructionResponse>;
+/**
+ * 获取所有 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 declare function getEarnTokens(config?: JupiterConfig): Promise<LendTokenInfo[]>;
+/**
+ * 获取单个代币的 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 declare function getEarnTokenByAsset(assetMint: string, config?: JupiterConfig): Promise<LendTokenInfo | 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 declare function getEarnApys(config?: JupiterConfig): Promise<Record<string, {
+    symbol: string;
+    jlSymbol: string;
+    apy: number;
+    supplyRate: number;
+    rewardsRate: number;
+    price: number;
+}>>;
+/**
+ * 计算份额对应的资产数量
+ *
+ * @param shares 份额数量 (最小单位)
+ * @param tokenInfo 代币信息
+ * @returns 资产数量 (最小单位)
+ */
+export declare function sharesToAssets(shares: string | bigint, tokenInfo: LendTokenInfo): bigint;
+/**
+ * 计算资产数量对应的份额
+ *
+ * @param assets 资产数量 (最小单位)
+ * @param tokenInfo 代币信息
+ * @returns 份额数量 (最小单位)
+ */
+export declare function assetsToShares(assets: string | bigint, tokenInfo: LendTokenInfo): bigint;
+/**
+ * 获取用户的 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 declare function getEarnPositions(users: string | string[], config?: JupiterConfig): Promise<LendPosition[]>;
+/**
+ * 获取用户在指定代币的 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 declare function getEarnPositionByAsset(user: string, assetMint: string, config?: JupiterConfig): Promise<LendPosition | 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 declare function getActiveEarnPositions(user: string, config?: JupiterConfig): Promise<LendPosition[]>;
+/**
+ * 获取用户的 Earn 资产总值 (USD)
+ *
+ * @param user 用户地址
+ * @param config Jupiter 配置
+ * @returns 总值 USD
+ *
+ * @example
+ * ```typescript
+ * const totalValue = await Sol.getEarnTotalValue(
+ *   '9yFqMjJgsEcZ8GnEtFqxw1oFbPPVpypMVgYzQWgECFNy'
+ * )
+ * console.log('Earn 总值: $' + totalValue.toFixed(2))
+ * ```
+ */
+export declare function getEarnTotalValue(user: string, config?: JupiterConfig): Promise<number>;
+/**
+ * 获取用户的收益统计
+ *
+ * 返回用户的存款、取款和收益汇总。
+ *
+ * @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 declare function getEarnEarnings(user?: string, config?: JupiterConfig): Promise<LendEarnings[]>;
+/**
+ * 获取用户在指定代币的收益
+ *
+ * @param user 用户地址
+ * @param jlTokenAddress jl 代币地址（如 jlUSDC 地址）
+ * @param config Jupiter 配置
+ * @returns 收益信息或 null
+ */
+export declare function getEarnEarningsByToken(user: string, jlTokenAddress: string, config?: JupiterConfig): Promise<LendEarnings | 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 declare function getEarnEarningsSummary(user: string, config?: JupiterConfig): Promise<{
+    totalDeposits: bigint;
+    totalWithdraws: bigint;
+    totalBalance: bigint;
+    totalEarnings: bigint;
+}>;
+/** 常见的 Earn 支持代币 */
+export declare const LEND_SUPPORTED_ASSETS: {
+    /** USDC */
+    readonly USDC: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
+    /** USDT */
+    readonly USDT: "Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB";
+    /** SOL */
+    readonly SOL: "So11111111111111111111111111111111111111112";
+};
+/**
+ * 存入 USDC
+ *
+ * @param signer 签名者公钥
+ * @param amount 数量 (UI 数量，如 "100" 表示 100 USDC)
+ * @param config Jupiter 配置
+ * @returns 未签名交易
+ */
+export declare function depositUsdc(signer: string, amount: string, config?: JupiterConfig): Promise<LendTransactionResponse>;
+/**
+ * 取出 USDC
+ *
+ * @param signer 签名者公钥
+ * @param amount 数量
+ * @param config Jupiter 配置
+ * @returns 未签名交易
+ */
+export declare function withdrawUsdc(signer: string, amount: string, config?: JupiterConfig): Promise<LendTransactionResponse>;
+/**
+ * 存入 SOL
+ *
+ * @param signer 签名者公钥
+ * @param amount 数量 (UI 数量，如 "1" 表示 1 SOL)
+ * @param config Jupiter 配置
+ * @returns 未签名交易
+ */
+export declare function depositSol(signer: string, amount: string, config?: JupiterConfig): Promise<LendTransactionResponse>;
+/**
+ * 取出 SOL
+ *
+ * @param signer 签名者公钥
+ * @param amount 数量
+ * @param config Jupiter 配置
+ * @returns 未签名交易
+ */
+export declare function withdrawSol(signer: string, amount: string, config?: JupiterConfig): Promise<LendTransactionResponse>;