four-flap-meme-sdk 1.5.55 → 1.5.56

package/dist/sol/utils/balance.js

@@ -0,0 +1,638 @@
+/**
+ * Solana 余额查询功能
+ * 使用批量 RPC 调用优化，减少限流风险
+ * @module sol/utils/balance
+ */
+import { PublicKey, } from '@solana/web3.js';
+import { getAccount, getAssociatedTokenAddressSync, TOKEN_PROGRAM_ID, TOKEN_2022_PROGRAM_ID, } from '@solana/spl-token';
+import { lamportsToSol } from '../constants.js';
+// ============================================================================
+// Decimals 缓存（减少重复查询）
+// ============================================================================
+const decimalsCache = new Map();
+/**
+ * 获取代币精度（带缓存）
+ */
+async function getTokenDecimals(connection, mint) {
+    const cached = decimalsCache.get(mint);
+    if (cached !== undefined)
+        return cached;
+    try {
+        const mintPubkey = new PublicKey(mint);
+        const mintInfo = await connection.getParsedAccountInfo(mintPubkey);
+        if (mintInfo.value?.data && 'parsed' in mintInfo.value.data) {
+            const decimals = mintInfo.value.data.parsed.info.decimals;
+            decimalsCache.set(mint, decimals);
+            return decimals;
+        }
+    }
+    catch {
+        // 默认值
+    }
+    return 9;
+}
+/**
+ * 批量获取代币精度（一次 RPC 调用）
+ */
+async function batchGetTokenDecimals(connection, mints) {
+    const result = new Map();
+    const uncachedMints = [];
+    const uncachedIndexes = [];
+    // 检查缓存
+    for (let i = 0; i < mints.length; i++) {
+        const mint = mints[i];
+        const cached = decimalsCache.get(mint);
+        if (cached !== undefined) {
+            result.set(mint, cached);
+        }
+        else {
+            uncachedMints.push(mint);
+            uncachedIndexes.push(i);
+        }
+    }
+    if (uncachedMints.length === 0)
+        return result;
+    // 批量查询未缓存的
+    try {
+        const mintPubkeys = uncachedMints.map(m => new PublicKey(m));
+        const mintInfos = await connection.getMultipleParsedAccounts(mintPubkeys);
+        for (let i = 0; i < uncachedMints.length; i++) {
+            const mint = uncachedMints[i];
+            const info = mintInfos.value[i];
+            let decimals = 9;
+            if (info?.data && 'parsed' in info.data) {
+                decimals = info.data.parsed.info.decimals;
+            }
+            decimalsCache.set(mint, decimals);
+            result.set(mint, decimals);
+        }
+    }
+    catch {
+        // 使用默认值
+        for (const mint of uncachedMints) {
+            result.set(mint, 9);
+        }
+    }
+    return result;
+}
+// ==================== SOL 余额 ====================
+/**
+ * 查询单个地址的 SOL 余额
+ * @param connection Solana 连接
+ * @param address 钱包地址
+ */
+export async function getSolBalance(connection, address) {
+    try {
+        const publicKey = new PublicKey(address);
+        const balance = await connection.getBalance(publicKey);
+        const lamports = BigInt(balance);
+        return {
+            address,
+            lamports,
+            sol: lamportsToSol(lamports),
+            success: true,
+        };
+    }
+    catch (error) {
+        return {
+            address,
+            lamports: BigInt(0),
+            sol: 0,
+            success: false,
+            error: error.message,
+        };
+    }
+}
+/**
+ * 批量查询 SOL 余额
+ * @param connection Solana 连接
+ * @param addresses 钱包地址列表
+ * @param batchSize 每批查询数量（默认 100）
+ */
+export async function batchGetSolBalance(connection, addresses, batchSize = 100) {
+    const results = [];
+    let successCount = 0;
+    let failedCount = 0;
+    // 分批查询
+    for (let i = 0; i < addresses.length; i += batchSize) {
+        const batch = addresses.slice(i, i + batchSize);
+        // 使用 getMultipleAccountsInfo 批量查询
+        try {
+            const publicKeys = batch.map(addr => new PublicKey(addr));
+            const accounts = await connection.getMultipleAccountsInfo(publicKeys);
+            for (let j = 0; j < batch.length; j++) {
+                const account = accounts[j];
+                const address = batch[j];
+                if (account) {
+                    const lamports = BigInt(account.lamports);
+                    results.push({
+                        address,
+                        lamports,
+                        sol: lamportsToSol(lamports),
+                        success: true,
+                    });
+                    successCount++;
+                }
+                else {
+                    // 账户不存在，余额为 0
+                    results.push({
+                        address,
+                        lamports: BigInt(0),
+                        sol: 0,
+                        success: true,
+                    });
+                    successCount++;
+                }
+            }
+        }
+        catch (error) {
+            // 如果批量查询失败，逐个查询
+            for (const address of batch) {
+                const result = await getSolBalance(connection, address);
+                results.push(result);
+                if (result.success) {
+                    successCount++;
+                }
+                else {
+                    failedCount++;
+                }
+            }
+        }
+        // 批次间延迟
+        if (i + batchSize < addresses.length) {
+            await new Promise(resolve => setTimeout(resolve, 100));
+        }
+    }
+    return {
+        results,
+        successCount,
+        failedCount,
+    };
+}
+// ==================== 代币余额 ====================
+/**
+ * 查询单个地址的代币余额
+ * @param connection Solana 连接
+ * @param walletAddress 钱包地址
+ * @param tokenMint 代币 Mint 地址
+ * @param useToken2022 是否使用 Token-2022 程序（默认 false）
+ */
+export async function getTokenBalance(connection, walletAddress, tokenMint, useToken2022 = false) {
+    try {
+        const wallet = new PublicKey(walletAddress);
+        const mint = new PublicKey(tokenMint);
+        const programId = useToken2022 ? TOKEN_2022_PROGRAM_ID : TOKEN_PROGRAM_ID;
+        // 使用同步方法获取 ATA 地址（避免 RPC 调用）
+        const ata = getAssociatedTokenAddressSync(mint, wallet, false, programId);
+        // 获取 decimals（带缓存）
+        const decimals = await getTokenDecimals(connection, tokenMint);
+        try {
+            const account = await getAccount(connection, ata, 'confirmed', programId);
+            const balance = BigInt(account.amount.toString());
+            return {
+                address: walletAddress,
+                tokenAddress: tokenMint,
+                balance,
+                decimals,
+                uiBalance: Number(balance) / Math.pow(10, decimals),
+                success: true,
+            };
+        }
+        catch {
+            // ATA 不存在，余额为 0
+            return {
+                address: walletAddress,
+                tokenAddress: tokenMint,
+                balance: BigInt(0),
+                decimals,
+                uiBalance: 0,
+                success: true,
+            };
+        }
+    }
+    catch (error) {
+        return {
+            address: walletAddress,
+            tokenAddress: tokenMint,
+            balance: BigInt(0),
+            decimals: 0,
+            uiBalance: 0,
+            success: false,
+            error: error.message,
+        };
+    }
+}
+/**
+ * 批量查询代币余额（多个钱包，同一代币）
+ * 使用 getMultipleAccountsInfo 优化，单次 RPC 调用查询多个账户
+ *
+ * @param connection Solana 连接
+ * @param walletAddresses 钱包地址列表
+ * @param tokenMint 代币 Mint 地址
+ * @param useToken2022 是否使用 Token-2022 程序
+ */
+export async function batchGetTokenBalance(connection, walletAddresses, tokenMint, useToken2022 = false) {
+    const results = [];
+    let successCount = 0;
+    let failedCount = 0;
+    // 获取 decimals（带缓存，只查一次）
+    const decimals = await getTokenDecimals(connection, tokenMint);
+    const programId = useToken2022 ? TOKEN_2022_PROGRAM_ID : TOKEN_PROGRAM_ID;
+    const mint = new PublicKey(tokenMint);
+    // 使用同步方法批量获取 ATA 地址（无 RPC 调用）
+    const atas = walletAddresses.map((addr) => {
+        const wallet = new PublicKey(addr);
+        return getAssociatedTokenAddressSync(mint, wallet, false, programId);
+    });
+    // 批量查询账户（Solana 单次最多 100 个账户）
+    const batchSize = 100;
+    for (let i = 0; i < atas.length; i += batchSize) {
+        const batchAtas = atas.slice(i, i + batchSize);
+        const batchAddresses = walletAddresses.slice(i, i + batchSize);
+        try {
+            const accounts = await connection.getMultipleAccountsInfo(batchAtas);
+            for (let j = 0; j < batchAtas.length; j++) {
+                const account = accounts[j];
+                const address = batchAddresses[j];
+                if (account && account.data.length > 0) {
+                    // 解析代币账户数据
+                    // Token 账户结构：前 64 字节是 mint 和 owner，接下来 8 字节是 amount
+                    const data = account.data;
+                    let balance = BigInt(0);
+                    if (data.length >= 72) {
+                        // 读取 amount（offset 64，8 字节，little-endian）
+                        const amountBytes = data.slice(64, 72);
+                        for (let k = 7; k >= 0; k--) {
+                            balance = (balance << BigInt(8)) + BigInt(amountBytes[k]);
+                        }
+                    }
+                    results.push({
+                        address,
+                        tokenAddress: tokenMint,
+                        balance,
+                        decimals,
+                        uiBalance: Number(balance) / Math.pow(10, decimals),
+                        success: true,
+                    });
+                    successCount++;
+                }
+                else {
+                    // 账户不存在
+                    results.push({
+                        address,
+                        tokenAddress: tokenMint,
+                        balance: BigInt(0),
+                        decimals,
+                        uiBalance: 0,
+                        success: true,
+                    });
+                    successCount++;
+                }
+            }
+        }
+        catch (error) {
+            // 批量失败，标记所有为失败
+            for (const address of batchAddresses) {
+                results.push({
+                    address,
+                    tokenAddress: tokenMint,
+                    balance: BigInt(0),
+                    decimals,
+                    uiBalance: 0,
+                    success: false,
+                    error: error.message,
+                });
+                failedCount++;
+            }
+        }
+        // 批次间延迟（减少限流）
+        if (i + batchSize < atas.length) {
+            await new Promise(resolve => setTimeout(resolve, 50));
+        }
+    }
+    return {
+        results,
+        successCount,
+        failedCount,
+    };
+}
+/**
+ * 批量查询多个代币余额（单个钱包，多个代币）
+ *
+ * @param connection Solana 连接
+ * @param walletAddress 钱包地址
+ * @param tokenMints 代币 Mint 地址列表
+ * @param useToken2022 是否使用 Token-2022 程序
+ */
+export async function batchGetMultiTokenBalance(connection, walletAddress, tokenMints, useToken2022 = false) {
+    const results = [];
+    let successCount = 0;
+    let failedCount = 0;
+    const programId = useToken2022 ? TOKEN_2022_PROGRAM_ID : TOKEN_PROGRAM_ID;
+    const wallet = new PublicKey(walletAddress);
+    // 批量获取 decimals（一次 RPC 调用）
+    const decimalsMap = await batchGetTokenDecimals(connection, tokenMints);
+    // 使用同步方法批量获取 ATA 地址（无 RPC 调用）
+    const atas = tokenMints.map((mintStr) => {
+        const mint = new PublicKey(mintStr);
+        return getAssociatedTokenAddressSync(mint, wallet, false, programId);
+    });
+    // 批量查询账户
+    const batchSize = 100;
+    for (let i = 0; i < atas.length; i += batchSize) {
+        const batchAtas = atas.slice(i, i + batchSize);
+        const batchMints = tokenMints.slice(i, i + batchSize);
+        try {
+            const accounts = await connection.getMultipleAccountsInfo(batchAtas);
+            for (let j = 0; j < batchAtas.length; j++) {
+                const account = accounts[j];
+                const tokenMint = batchMints[j];
+                const decimals = decimalsMap.get(tokenMint) || 9;
+                if (account && account.data.length > 0) {
+                    const data = account.data;
+                    let balance = BigInt(0);
+                    if (data.length >= 72) {
+                        const amountBytes = data.slice(64, 72);
+                        for (let k = 7; k >= 0; k--) {
+                            balance = (balance << BigInt(8)) + BigInt(amountBytes[k]);
+                        }
+                    }
+                    results.push({
+                        address: walletAddress,
+                        tokenAddress: tokenMint,
+                        balance,
+                        decimals,
+                        uiBalance: Number(balance) / Math.pow(10, decimals),
+                        success: true,
+                    });
+                    successCount++;
+                }
+                else {
+                    results.push({
+                        address: walletAddress,
+                        tokenAddress: tokenMint,
+                        balance: BigInt(0),
+                        decimals,
+                        uiBalance: 0,
+                        success: true,
+                    });
+                    successCount++;
+                }
+            }
+        }
+        catch (error) {
+            for (const tokenMint of batchMints) {
+                results.push({
+                    address: walletAddress,
+                    tokenAddress: tokenMint,
+                    balance: BigInt(0),
+                    decimals: decimalsMap.get(tokenMint) || 9,
+                    uiBalance: 0,
+                    success: false,
+                    error: error.message,
+                });
+                failedCount++;
+            }
+        }
+        if (i + batchSize < atas.length) {
+            await new Promise(resolve => setTimeout(resolve, 50));
+        }
+    }
+    return {
+        results,
+        successCount,
+        failedCount,
+    };
+}
+/**
+ * 获取钱包持有的所有代币
+ * @param connection Solana 连接
+ * @param walletAddress 钱包地址
+ * @param includeToken2022 是否包含 Token-2022 代币
+ */
+export async function getAllTokenBalances(connection, walletAddress, includeToken2022 = true) {
+    const wallet = new PublicKey(walletAddress);
+    // 获取 SOL 余额
+    const solResult = await getSolBalance(connection, walletAddress);
+    const tokens = [];
+    // 查询 SPL Token 账户
+    try {
+        const tokenAccounts = await connection.getParsedTokenAccountsByOwner(wallet, {
+            programId: TOKEN_PROGRAM_ID,
+        });
+        for (const { account } of tokenAccounts.value) {
+            const data = account.data;
+            if ('parsed' in data) {
+                const info = data.parsed.info;
+                const balance = BigInt(info.tokenAmount.amount);
+                if (balance > 0) {
+                    tokens.push({
+                        mint: info.mint,
+                        balance,
+                        decimals: info.tokenAmount.decimals,
+                        uiBalance: info.tokenAmount.uiAmount || 0,
+                    });
+                }
+            }
+        }
+    }
+    catch {
+        // 忽略错误
+    }
+    // 查询 Token-2022 账户
+    if (includeToken2022) {
+        try {
+            const token2022Accounts = await connection.getParsedTokenAccountsByOwner(wallet, {
+                programId: TOKEN_2022_PROGRAM_ID,
+            });
+            for (const { account } of token2022Accounts.value) {
+                const data = account.data;
+                if ('parsed' in data) {
+                    const info = data.parsed.info;
+                    const balance = BigInt(info.tokenAmount.amount);
+                    if (balance > 0) {
+                        tokens.push({
+                            mint: info.mint,
+                            balance,
+                            decimals: info.tokenAmount.decimals,
+                            uiBalance: info.tokenAmount.uiAmount || 0,
+                        });
+                    }
+                }
+            }
+        }
+        catch {
+            // 忽略错误
+        }
+    }
+    return {
+        address: walletAddress,
+        sol: {
+            lamports: solResult.lamports,
+            balance: solResult.sol,
+        },
+        tokens,
+    };
+}
+/**
+ * 批量获取钱包完整余额信息
+ * @param connection Solana 连接
+ * @param walletAddresses 钱包地址列表
+ */
+export async function batchGetAllBalances(connection, walletAddresses) {
+    const results = [];
+    // 并行查询，但限制并发数
+    const concurrency = 5;
+    for (let i = 0; i < walletAddresses.length; i += concurrency) {
+        const batch = walletAddresses.slice(i, i + concurrency);
+        const batchResults = await Promise.all(batch.map(addr => getAllTokenBalances(connection, addr)));
+        results.push(...batchResults);
+        // 批次间延迟
+        if (i + concurrency < walletAddresses.length) {
+            await new Promise(resolve => setTimeout(resolve, 100));
+        }
+    }
+    return results;
+}
+/**
+ * 批量查询多个钱包的多个代币余额（矩阵查询）
+ * 优化 RPC 调用次数，适合大批量查询
+ *
+ * @param connection Solana 连接
+ * @param walletAddresses 钱包地址列表
+ * @param tokenMints 代币 Mint 地址列表
+ * @param useToken2022 是否使用 Token-2022 程序
+ *
+ * @example
+ * ```typescript
+ * const result = await batchGetMatrixBalance(
+ *   connection,
+ *   ['wallet1', 'wallet2', 'wallet3'],
+ *   ['tokenA', 'tokenB'],
+ * )
+ *
+ * // 获取某个钱包的某个代币余额
+ * const balance = result.byWallet.get('wallet1')?.get('tokenA')
+ * ```
+ */
+export async function batchGetMatrixBalance(connection, walletAddresses, tokenMints, useToken2022 = false) {
+    const byWallet = new Map();
+    const byToken = new Map();
+    const results = [];
+    let successCount = 0;
+    let failedCount = 0;
+    let rpcCalls = 0;
+    const programId = useToken2022 ? TOKEN_2022_PROGRAM_ID : TOKEN_PROGRAM_ID;
+    // 1. 批量获取所有代币的 decimals（一次 RPC 调用）
+    const decimalsMap = await batchGetTokenDecimals(connection, tokenMints);
+    rpcCalls++;
+    // 2. 构建所有 ATA 地址（无 RPC 调用）
+    const ataInfos = [];
+    for (const walletAddress of walletAddresses) {
+        const wallet = new PublicKey(walletAddress);
+        byWallet.set(walletAddress, new Map());
+        for (const mintStr of tokenMints) {
+            const mint = new PublicKey(mintStr);
+            const ata = getAssociatedTokenAddressSync(mint, wallet, false, programId);
+            const decimals = decimalsMap.get(mintStr) || 9;
+            ataInfos.push({ ata, wallet: walletAddress, mint: mintStr, decimals });
+            if (!byToken.has(mintStr)) {
+                byToken.set(mintStr, new Map());
+            }
+        }
+    }
+    // 3. 批量查询所有 ATA 账户
+    const batchSize = 100;
+    for (let i = 0; i < ataInfos.length; i += batchSize) {
+        const batch = ataInfos.slice(i, i + batchSize);
+        const ataPubkeys = batch.map(info => info.ata);
+        try {
+            const accounts = await connection.getMultipleAccountsInfo(ataPubkeys);
+            rpcCalls++;
+            for (let j = 0; j < batch.length; j++) {
+                const info = batch[j];
+                const account = accounts[j];
+                let balance = BigInt(0);
+                if (account && account.data.length >= 72) {
+                    const amountBytes = account.data.slice(64, 72);
+                    for (let k = 7; k >= 0; k--) {
+                        balance = (balance << BigInt(8)) + BigInt(amountBytes[k]);
+                    }
+                }
+                const result = {
+                    address: info.wallet,
+                    tokenAddress: info.mint,
+                    balance,
+                    decimals: info.decimals,
+                    uiBalance: Number(balance) / Math.pow(10, info.decimals),
+                    success: true,
+                };
+                results.push(result);
+                byWallet.get(info.wallet).set(info.mint, result);
+                byToken.get(info.mint).set(info.wallet, result);
+                successCount++;
+            }
+        }
+        catch (error) {
+            for (const info of batch) {
+                const result = {
+                    address: info.wallet,
+                    tokenAddress: info.mint,
+                    balance: BigInt(0),
+                    decimals: info.decimals,
+                    uiBalance: 0,
+                    success: false,
+                    error: error.message,
+                };
+                results.push(result);
+                byWallet.get(info.wallet).set(info.mint, result);
+                byToken.get(info.mint).set(info.wallet, result);
+                failedCount++;
+            }
+        }
+        // 批次间短暂延迟
+        if (i + batchSize < ataInfos.length) {
+            await new Promise(resolve => setTimeout(resolve, 30));
+        }
+    }
+    return {
+        byWallet,
+        byToken,
+        results,
+        stats: {
+            totalQueries: walletAddresses.length * tokenMints.length,
+            successCount,
+            failedCount,
+            rpcCalls,
+        },
+    };
+}
+// ============================================================================
+// 缓存管理
+// ============================================================================
+/**
+ * 清除 decimals 缓存
+ * @param mint 可选，指定代币地址；不传则清除全部
+ */
+export function clearDecimalsCache(mint) {
+    if (mint) {
+        decimalsCache.delete(mint);
+    }
+    else {
+        decimalsCache.clear();
+    }
+}
+/**
+ * 获取缓存的 decimals 数量
+ */
+export function getDecimalsCacheSize() {
+    return decimalsCache.size;
+}
+/**
+ * 预热 decimals 缓存
+ * @param connection Solana 连接
+ * @param mints 代币 Mint 地址列表
+ */
+export async function warmupDecimalsCache(connection, mints) {
+    await batchGetTokenDecimals(connection, mints);
+}