four-flap-meme-sdk 1.5.4 → 1.5.6

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

@@ -0,0 +1,488 @@
+/**
+ * Jupiter Studio API V1
+ * @module sol/dex/jup/studio
+ *
+ * Studio API 提供在 Meteora DBC (Dynamic Bonding Curve) 上创建代币的功能
+ * 支持配置市值、费用、vesting 等参数
+ */
+import { jupGet, jupPost, getBaseUrl, getJupiterConfig } from './client.js';
+// ============================================================================
+// 常量
+// ============================================================================
+/** Quote 代币 Mint 地址 */
+export const QUOTE_MINTS = {
+    /** USDC */
+    USDC: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+    /** SOL (Wrapped) */
+    SOL: 'So11111111111111111111111111111111111111112',
+    /** JUP */
+    JUP: 'JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN',
+};
+/** Vesting 持续时间常量 */
+export const VESTING_DURATIONS = {
+    /** 无 vesting */
+    NONE: 0,
+    /** 6 个月 (180天) */
+    SIX_MONTHS: 15552000,
+    /** 约 6 个月 (183天) */
+    SIX_MONTHS_183: 15811200,
+    /** 1 年 (365天) */
+    ONE_YEAR: 31536000,
+};
+// ============================================================================
+// Create DBC Pool - 创建 DBC 池
+// ============================================================================
+/**
+ * 创建 DBC 池交易
+ *
+ * 在 Meteora DBC 上创建代币，支持配置市值、费用、vesting 等参数。
+ *
+ * @param params 创建参数
+ * @param config Jupiter 配置
+ * @returns 创建响应
+ *
+ * @example
+ * ```typescript
+ * import { Sol } from 'four-flap-meme-sdk'
+ *
+ * Sol.setJupiterConfig({ apiKey: 'your-api-key' })
+ *
+ * // 创建 DBC 池
+ * const result = await Sol.createDbcPoolTx({
+ *   buildCurveByMarketCapParam: {
+ *     quoteMint: Sol.QUOTE_MINTS.USDC,
+ *     initialMarketCap: 16000,      // 16k USDC 初始市值
+ *     migrationMarketCap: 69000,    // 69k USDC 迁移市值
+ *     tokenQuoteDecimal: 6,
+ *     lockedVestingParam: {
+ *       totalLockedVestingAmount: 0,
+ *       cliffUnlockAmount: 0,
+ *       numberOfVestingPeriod: 0,
+ *       totalVestingDuration: 0,
+ *       cliffDurationFromMigrationTime: 0,
+ *     },
+ *   },
+ *   antiSniping: true,
+ *   fee: { feeBps: 100 },
+ *   tokenName: 'My Token',
+ *   tokenSymbol: 'MTK',
+ *   tokenImageContentType: 'image/png',
+ *   creator: wallet.publicKey.toBase58(),
+ *   isLpLocked: true,
+ * })
+ *
+ * console.log(`代币 Mint: ${result.mint}`)
+ * console.log(`图片上传 URL: ${result.imagePresignedUrl}`)
+ * console.log(`元数据上传 URL: ${result.metadataPresignedUrl}`)
+ *
+ * // 1. 上传图片
+ * await fetch(result.imagePresignedUrl, {
+ *   method: 'PUT',
+ *   headers: { 'Content-Type': 'image/png' },
+ *   body: imageBuffer,
+ * })
+ *
+ * // 2. 上传元数据
+ * const metadata = {
+ *   name: 'My Token',
+ *   symbol: 'MTK',
+ *   description: 'Token description',
+ *   image: result.imageUrl,
+ * }
+ * await fetch(result.metadataPresignedUrl, {
+ *   method: 'PUT',
+ *   headers: { 'Content-Type': 'application/json' },
+ *   body: JSON.stringify(metadata),
+ * })
+ *
+ * // 3. 签名并发送交易
+ * const tx = VersionedTransaction.deserialize(Buffer.from(result.transaction, 'base64'))
+ * tx.sign([wallet])
+ * // 发送交易...
+ * ```
+ */
+export async function createDbcPoolTx(params, config) {
+    return jupPost('/studio/v1/dbc-pool/create-tx', params, config);
+}
+/**
+ * 创建简单 DBC 池
+ *
+ * 使用简化参数创建 DBC 池。
+ *
+ * @param name 代币名称
+ * @param symbol 代币符号
+ * @param creator 创建者地址
+ * @param options 可选参数
+ * @param config Jupiter 配置
+ * @returns 创建响应
+ *
+ * @example
+ * ```typescript
+ * // 使用 USDC 作为 quote，默认参数创建
+ * const result = await Sol.createSimpleDbcPool(
+ *   'My Token',
+ *   'MTK',
+ *   wallet.publicKey.toBase58(),
+ *   {
+ *     quoteMint: 'usdc',
+ *     initialMarketCap: 16000,
+ *     migrationMarketCap: 69000,
+ *   },
+ * )
+ * ```
+ */
+export async function createSimpleDbcPool(name, symbol, creator, options, config) {
+    // 解析 quote mint
+    let quoteMint;
+    const qm = options?.quoteMint?.toLowerCase();
+    switch (qm) {
+        case 'usdc':
+            quoteMint = QUOTE_MINTS.USDC;
+            break;
+        case 'sol':
+            quoteMint = QUOTE_MINTS.SOL;
+            break;
+        case 'jup':
+            quoteMint = QUOTE_MINTS.JUP;
+            break;
+        default:
+            quoteMint = options?.quoteMint || QUOTE_MINTS.USDC;
+    }
+    // 确定小数位
+    const tokenQuoteDecimal = quoteMint === QUOTE_MINTS.SOL ? 9 : 6;
+    return createDbcPoolTx({
+        buildCurveByMarketCapParam: {
+            quoteMint,
+            initialMarketCap: options?.initialMarketCap ?? 16000,
+            migrationMarketCap: options?.migrationMarketCap ?? 69000,
+            tokenQuoteDecimal,
+            lockedVestingParam: {
+                totalLockedVestingAmount: 0,
+                cliffUnlockAmount: 0,
+                numberOfVestingPeriod: 0,
+                totalVestingDuration: 0,
+                cliffDurationFromMigrationTime: 0,
+            },
+        },
+        antiSniping: options?.antiSniping ?? true,
+        fee: { feeBps: options?.feeBps ?? 100 },
+        tokenName: name,
+        tokenSymbol: symbol,
+        tokenImageContentType: options?.imageContentType ?? 'image/png',
+        creator,
+        isLpLocked: options?.isLpLocked ?? true,
+    }, config);
+}
+/**
+ * 创建带 Vesting 的 DBC 池
+ *
+ * @param name 代币名称
+ * @param symbol 代币符号
+ * @param creator 创建者地址
+ * @param vestingPercent Vesting 百分比（0-80）
+ * @param vestingDuration Vesting 持续时间
+ * @param options 其他选项
+ * @param config Jupiter 配置
+ * @returns 创建响应
+ */
+export async function createDbcPoolWithVesting(name, symbol, creator, vestingPercent, vestingDuration, options, config) {
+    if (vestingPercent < 0 || vestingPercent > 80) {
+        throw new Error('vestingPercent 必须在 0-80 之间');
+    }
+    // 解析 quote mint
+    let quoteMint;
+    const qm = options?.quoteMint?.toLowerCase();
+    switch (qm) {
+        case 'usdc':
+            quoteMint = QUOTE_MINTS.USDC;
+            break;
+        case 'sol':
+            quoteMint = QUOTE_MINTS.SOL;
+            break;
+        case 'jup':
+            quoteMint = QUOTE_MINTS.JUP;
+            break;
+        default:
+            quoteMint = options?.quoteMint || QUOTE_MINTS.USDC;
+    }
+    const tokenQuoteDecimal = quoteMint === QUOTE_MINTS.SOL ? 9 : 6;
+    // 计算 vesting 期数
+    let numberOfVestingPeriod = 0;
+    if (vestingDuration === VESTING_DURATIONS.SIX_MONTHS) {
+        numberOfVestingPeriod = 6;
+    }
+    else if (vestingDuration === VESTING_DURATIONS.SIX_MONTHS_183) {
+        numberOfVestingPeriod = 183;
+    }
+    else if (vestingDuration === VESTING_DURATIONS.ONE_YEAR) {
+        numberOfVestingPeriod = 12;
+    }
+    return createDbcPoolTx({
+        buildCurveByMarketCapParam: {
+            quoteMint,
+            initialMarketCap: options?.initialMarketCap ?? 16000,
+            migrationMarketCap: options?.migrationMarketCap ?? 69000,
+            tokenQuoteDecimal,
+            lockedVestingParam: {
+                totalLockedVestingAmount: vestingPercent,
+                cliffUnlockAmount: 0,
+                numberOfVestingPeriod,
+                totalVestingDuration: vestingDuration,
+                cliffDurationFromMigrationTime: options?.cliffDuration ?? 0,
+            },
+        },
+        antiSniping: true,
+        fee: { feeBps: 100 },
+        tokenName: name,
+        tokenSymbol: symbol,
+        tokenImageContentType: options?.imageContentType ?? 'image/png',
+        creator,
+        isLpLocked: true,
+    }, config);
+}
+// ============================================================================
+// Submit DBC Pool - 提交 DBC 池
+// ============================================================================
+/**
+ * 提交 DBC 池交易
+ *
+ * 提交已签名的交易到链上创建 DBC 池。
+ *
+ * @param params 提交参数
+ * @param config Jupiter 配置
+ * @returns 提交响应
+ *
+ * @example
+ * ```typescript
+ * // 签名交易后提交
+ * const result = await Sol.submitDbcPool({
+ *   transaction: signedTxBase64,
+ *   owner: wallet.publicKey.toBase58(),
+ *   content: 'My awesome token description',
+ * })
+ *
+ * if (result.success) {
+ *   console.log(`创建成功: ${result.data.mint}`)
+ *   console.log(`配置 Key: ${result.data.configKey}`)
+ * }
+ * ```
+ */
+export async function submitDbcPool(params, config) {
+    const baseUrl = getBaseUrl(config);
+    const cfg = getJupiterConfig(config);
+    const formData = new FormData();
+    formData.append('transaction', params.transaction);
+    formData.append('owner', params.owner);
+    if (params.content) {
+        formData.append('content', params.content);
+    }
+    if (params.headerImage) {
+        formData.append('headerImage', params.headerImage);
+    }
+    const response = await fetch(`${baseUrl}/studio/v1/dbc-pool/submit`, {
+        method: 'POST',
+        headers: {
+            'x-api-key': cfg.apiKey,
+            // Note: Don't set Content-Type for FormData, browser will set it with boundary
+        },
+        body: formData,
+    });
+    if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(`Jupiter API error (${response.status}): ${errorText}`);
+    }
+    return await response.json();
+}
+// ============================================================================
+// Pool Addresses - 获取池地址
+// ============================================================================
+/**
+ * 获取 DBC 池地址
+ *
+ * @param mint 代币 Mint 地址
+ * @param config Jupiter 配置
+ * @returns 池地址响应
+ *
+ * @example
+ * ```typescript
+ * const addresses = await Sol.getDbcPoolAddresses('tokenMintAddress...')
+ *
+ * if (addresses.success) {
+ *   console.log(`DBC 池: ${addresses.data.dbcPoolAddress}`)
+ *   console.log(`DAMM V2 池: ${addresses.data.dammv2PoolAddress}`)
+ * }
+ * ```
+ */
+export async function getDbcPoolAddresses(mint, config) {
+    return jupGet(`/studio/v1/dbc-pool/addresses/${mint}`, {}, config);
+}
+/**
+ * 获取 DBC 池地址（仅地址）
+ *
+ * @param mint 代币 Mint 地址
+ * @param config Jupiter 配置
+ * @returns DBC 池地址或 null
+ */
+export async function getDbcPoolAddress(mint, config) {
+    const response = await getDbcPoolAddresses(mint, config);
+    return response.data?.dbcPoolAddress ?? null;
+}
+/**
+ * 获取 DAMM V2 池地址
+ *
+ * @param mint 代币 Mint 地址
+ * @param config Jupiter 配置
+ * @returns DAMM V2 池地址或 null
+ */
+export async function getDammV2PoolAddress(mint, config) {
+    const response = await getDbcPoolAddresses(mint, config);
+    return response.data?.dammv2PoolAddress ?? null;
+}
+/**
+ * 检查代币是否已迁移到 DAMM V2
+ *
+ * @param mint 代币 Mint 地址
+ * @param config Jupiter 配置
+ * @returns 是否已迁移
+ */
+export async function isTokenMigrated(mint, config) {
+    const response = await getDbcPoolAddresses(mint, config);
+    return response.data?.dammv2PoolAddress !== null;
+}
+// ============================================================================
+// DBC Fee - 费用管理
+// ============================================================================
+/**
+ * 获取 DBC 费用信息
+ *
+ * @param poolAddress DBC 池地址
+ * @param config Jupiter 配置
+ * @returns 费用信息
+ *
+ * @example
+ * ```typescript
+ * const fee = await Sol.getDbcFee('poolAddress...')
+ *
+ * console.log(`未领取: ${fee.unclaimed}`)
+ * console.log(`总计: ${fee.total}`)
+ * ```
+ */
+export async function getDbcFee(poolAddress, config) {
+    return jupPost('/studio/v1/dbc/fee', { poolAddress }, config);
+}
+/**
+ * 创建领取 DBC 费用交易
+ *
+ * @param params 领取参数
+ * @param config Jupiter 配置
+ * @returns 领取响应
+ *
+ * @example
+ * ```typescript
+ * // 获取未领取费用
+ * const fee = await Sol.getDbcFee('poolAddress...')
+ *
+ * if (BigInt(fee.unclaimed) > 0) {
+ *   // 创建领取交易
+ *   const result = await Sol.createClaimDbcFeeTx({
+ *     ownerWallet: wallet.publicKey.toBase58(),
+ *     poolAddress: 'poolAddress...',
+ *     maxQuoteAmount: Number(fee.unclaimed),
+ *   })
+ *
+ *   // 签名并发送
+ *   const tx = VersionedTransaction.deserialize(
+ *     Buffer.from(result.transaction, 'base64')
+ *   )
+ *   tx.sign([wallet])
+ *   // 发送交易...
+ * }
+ * ```
+ */
+export async function createClaimDbcFeeTx(params, config) {
+    return jupPost('/studio/v1/dbc/fee/create-tx', params, config);
+}
+/**
+ * 领取所有未领取的 DBC 费用
+ *
+ * @param ownerWallet 所有者钱包
+ * @param poolAddress 池地址
+ * @param config Jupiter 配置
+ * @returns 领取交易或 null（无费用可领）
+ */
+export async function claimAllDbcFee(ownerWallet, poolAddress, config) {
+    const fee = await getDbcFee(poolAddress, config);
+    const unclaimed = BigInt(fee.unclaimed);
+    if (unclaimed <= 0) {
+        return null;
+    }
+    return createClaimDbcFeeTx({
+        ownerWallet,
+        poolAddress,
+        maxQuoteAmount: Number(unclaimed),
+    }, config);
+}
+// ============================================================================
+// 便捷方法
+// ============================================================================
+/**
+ * 生成代币元数据
+ *
+ * @param name 代币名称
+ * @param symbol 代币符号
+ * @param description 描述
+ * @param imageUrl 图片 URL
+ * @param options 其他选项
+ * @returns 元数据 JSON 字符串
+ */
+export function generateTokenMetadata(name, symbol, description, imageUrl, options) {
+    const metadata = {
+        name,
+        symbol,
+        description,
+        image: imageUrl,
+    };
+    if (options?.externalUrl)
+        metadata.external_url = options.externalUrl;
+    if (options?.twitter)
+        metadata.twitter = options.twitter;
+    if (options?.telegram)
+        metadata.telegram = options.telegram;
+    if (options?.discord)
+        metadata.discord = options.discord;
+    if (options?.website)
+        metadata.website = options.website;
+    return JSON.stringify(metadata);
+}
+/**
+ * 上传图片到预签名 URL
+ *
+ * @param presignedUrl 预签名 URL
+ * @param imageData 图片数据 (Buffer 或 Blob)
+ * @param contentType 图片类型
+ * @returns 是否成功
+ */
+export async function uploadDbcTokenImage(presignedUrl, imageData, contentType) {
+    const response = await fetch(presignedUrl, {
+        method: 'PUT',
+        headers: { 'Content-Type': contentType },
+        body: imageData,
+    });
+    return response.ok;
+}
+/**
+ * 上传元数据到预签名 URL
+ *
+ * @param presignedUrl 预签名 URL
+ * @param metadata 元数据对象或 JSON 字符串
+ * @returns 是否成功
+ */
+export async function uploadDbcTokenMetadata(presignedUrl, metadata) {
+    const body = typeof metadata === 'string' ? metadata : JSON.stringify(metadata);
+    const response = await fetch(presignedUrl, {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json' },
+        body,
+    });
+    return response.ok;
+}