forgex-cli 1.0.59 → 1.0.62

package/dist/src/data-source.js

@@ -1,24 +1,24 @@
 /**
- * ForgeX CLI DataSource -- 统一数据源门面
+ * ForgeX CLI DataSource -- Unified Data Source Facade
  *
- * 命令层唯一的数据访问接口。将所有数据适配器（CodexAdapter、RpcAdapter、
- * JitoAdapter、DataStore）统一封装，提供简洁的接口供命令层调用。
+ * Single data access interface for the command layer. Wraps all data adapters (CodexAdapter, RpcAdapter,
+ * JitoAdapter, DataStore) into a unified facade with simple interfaces for command use.
  *
- * 路由逻辑:
- *   代币信息 / 价格 / K线 / 池信息  --> CodexAdapter (远程, 缓存穿透到 DataStore)
- *   余额 / 账户信息 / 交易确认      --> RpcAdapter (链上)
- *   Bundle 发送 / 状态查询           --> JitoAdapter (Jito Block Engine)
- *   交易记录 / 持仓 / 钱包组数据     --> DataStore (本地文件)
+ * Routing logic:
+ *   Token info / price / candlestick / pool info  --> CodexAdapter (remote, cache-through to DataStore)
+ *   Balance / account info / tx confirmation      --> RpcAdapter (on-chain)
+ *   Bundle send / status query           --> JitoAdapter (Jito Block Engine)
+ *   Trade records / positions / wallet group data     --> DataStore (local files)
  *
- * 缓存穿透:
- *   优先读 DataStore 本地缓存。如果 miss 或过期，则从远程 (Codex/RPC) 获取
- *   最新数据，写入 DataStore 后返回。
+ * Cache-through:
+ *   Reads DataStore local cache first. On miss or expiry, fetches from remote (Codex/RPC),
+ *   writes to DataStore, then returns.
  *
- * 容错:
- *   当 Codex API 不可用时，fallback 到 DataStore 中的历史缓存。
- *   RPC/Jito 不可用时，抛出 DataSourceError 供命令层处理。
+ * Fault tolerance:
+ *   When Codex API is unavailable, falls back to historical cache in DataStore.
+ *   When RPC/Jito unavailable, throws DataSourceError for command layer to handle.
  *
- * 设计参考: ARCH-DESIGN-v2.md Section 2.7
+ * Design reference: ARCH-DESIGN-v2.md Section 2.7
  */
 import { getCodexAdapter } from './adapters/codex-adapter.js';
 import { getRpcAdapter } from './adapters/rpc-adapter.js';
@@ -26,14 +26,14 @@ import { getJitoAdapter } from './adapters/jito-adapter.js';
 import { getDataStore } from './data-store/index.js';
 import { getTxTracker } from './tx-tracker/index.js';
 // ============================================================
-// 统一错误类型
+// Unified Error Type
 // ============================================================
 export class DataSourceError extends Error {
-    /** 错误来源 */
+    /** Error source */
     source;
-    /** 是否已 fallback 到缓存 */
+    /** Whether fallback to cache was used */
     fellBackToCache;
-    /** 原始错误 */
+    /** Original error */
     cause;
     constructor(message, source, options) {
         super(message);
@@ -44,16 +44,16 @@ export class DataSourceError extends Error {
     }
 }
 // ============================================================
-// 缓存过期阈值 (ms)
+// Cache expiry thresholds (ms)
 // ============================================================
-/** 代币信息缓存有效期: 10 分钟 */
+/** Token info cache TTL: 10 minutes */
 const TOKEN_INFO_TTL_MS = 10 * 60 * 1000;
-/** 池信息缓存有效期: 2 分钟 */
+/** Pool info cache TTL: 2 minutes */
 const POOL_INFO_TTL_MS = 2 * 60 * 1000;
-/** SOL 价格缓存有效期: 1 分钟 */
+/** SOL price cache TTL: 1 minute */
 const SOL_PRICE_TTL_MS = 60 * 1000;
 // ============================================================
-// DataSource 实现
+// DataSource Implementation
 // ============================================================
 export class DataSource {
     codex;
@@ -69,24 +69,24 @@ export class DataSource {
         this.tracker = options?.tracker ?? getTxTracker();
     }
     // ============================================================
-    // 代币信息 -- CodexAdapter + DataStore 缓存穿透
+    // Token Info -- CodexAdapter + DataStore cache-through
     // ============================================================
     /**
-     * 获取代币基本信息。
+     * Get basic token info.
      *
-     * 流程:
-     * 1. 先查 DataStore 缓存
-     * 2. 缓存命中且未过期 -> 直接返回
-     * 3. 缓存 miss 或过期 -> 从 Codex 获取并写入 DataStore
-     * 4. Codex 不可用 -> fallback 到 DataStore 陈旧缓存 (如有)
+     * Flow:
+     * 1. Check DataStore cache first
+     * 2. Cache hit and not expired -> return directly
+     * 3. Cache miss or expired -> fetch from Codex and write to DataStore
+     * 4. Codex unavailable -> fallback to stale DataStore cache (if any)
      */
     async getTokenInfo(ca) {
-        // 1. 查本地缓存
+        // 1. Check local cache
         const cached = this.store.getTokenInfo(ca);
         if (cached && !this.isExpired(cached.updatedAt, TOKEN_INFO_TTL_MS)) {
             return cached;
         }
-        // 2. 从 Codex 获取
+        // 2. Fetch from Codex
         try {
             const marketData = await this.codex.getTokenMarketData(ca);
             const topPair = await this.codex.getTopPair(ca).catch(() => null);
@@ -100,37 +100,37 @@ export class DataSource {
                 pairAddress: marketData.topPairAddress || topPair?.pairAddress || '',
                 updatedAt: Date.now(),
             };
-            // 写入 DataStore
+            // Write to DataStore
             await this.store.saveTokenInfo(ca, tokenInfo);
             return tokenInfo;
         }
         catch (err) {
-            // 3. Codex 不可用, fallback 到陈旧缓存
+            // 3. Codex unavailable, fallback to stale cache
             if (cached) {
                 return cached;
             }
-            throw new DataSourceError(`获取代币信息失败 (${ca}): ${err.message}`, 'codex', { cause: err });
+            throw new DataSourceError(`Failed to get token info (${ca}): ${err.message}`, 'codex', { cause: err });
         }
     }
     /**
-     * 获取代币详细市场数据 (包含价格、交易量、持有者等)。
-     * 直接从 Codex 获取, 不做本地缓存穿透 (市场数据实时性要求高)。
+     * Get detailed token market data (including price, volume, holders, etc).
+     * Fetches directly from Codex without local cache-through (market data requires high timeliness).
      */
     async getTokenMarketData(ca) {
         try {
             return await this.codex.getTokenMarketData(ca);
         }
         catch (err) {
-            throw new DataSourceError(`获取代币市场数据失败 (${ca}): ${err.message}`, 'codex', { cause: err });
+            throw new DataSourceError(`Failed to get token market data (${ca}): ${err.message}`, 'codex', { cause: err });
         }
     }
     // ============================================================
-    // 价格 -- CodexAdapter + DataStore 缓存穿透
+    // Price -- CodexAdapter + DataStore cache-through
     // ============================================================
     /**
-     * 获取代币价格 (SOL 和 USD)。
+     * Get token price (SOL and USD).
      *
-     * 缓存穿透: 先查 DataStore pool-info 缓存的价格, 过期则从 Codex 获取。
+     * Cache-through: checks DataStore pool-info cached price first, fetches from Codex if expired.
      */
     async getTokenPrice(ca) {
         try {
@@ -138,57 +138,57 @@ export class DataSource {
             return result;
         }
         catch (err) {
-            // fallback: 从 DataStore 的 pool-info 中读取历史价格
+            // fallback: read historical price from DataStore pool-info
             const poolInfo = this.store.getPoolInfo(ca);
             if (poolInfo) {
                 return { priceSol: poolInfo.priceSol, priceUsd: poolInfo.priceUsd };
             }
-            throw new DataSourceError(`获取代币价格失败 (${ca}): ${err.message}`, 'codex', { cause: err });
+            throw new DataSourceError(`Failed to get token price (${ca}): ${err.message}`, 'codex', { cause: err });
         }
     }
     /**
-     * 获取 SOL 价格 (USD)。
+     * Get SOL price (USD).
      *
-     * 缓存穿透: 先查 DataStore, 过期则从 Codex 获取并更新。
+     * Cache-through: checks DataStore first, fetches from Codex and updates if expired.
      */
     async getSolPrice() {
-        // 1. 查本地缓存
+        // 1. Check local cache
         const cachedPrice = this.store.getSolPrice();
         if (cachedPrice > 0) {
-            // 检查缓存是否过期 -- getSolPrice 返回的是数字, 需要额外检查时间
-            // DataStore 内部的 MemoryCache 有 30s TTL, 这里再加一层文件级 TTL
-            // 由于 DataStore.getSolPrice() 已经有 MemoryCache, 这里信任它即可
-            // 但如果明确需要刷新, 下面的 try 会尝试
+            // Check if cache is expired -- getSolPrice returns a number, needs extra time check
+            // DataStore internal MemoryCache has 30s TTL, adding another file-level TTL here
+            // Since DataStore.getSolPrice() already has MemoryCache, trust it here
+            // But if refresh is explicitly needed, the try below will attempt it
         }
-        // 2. 从 Codex 获取
+        // 2. Fetch from Codex
         try {
             const price = await this.codex.getSolPrice();
             await this.store.saveSolPrice(price);
             return price;
         }
         catch (err) {
-            // fallback: 使用缓存
+            // fallback: use cache
             if (cachedPrice > 0) {
                 return cachedPrice;
             }
-            throw new DataSourceError(`获取 SOL 价格失败: ${err.message}`, 'codex', { fellBackToCache: false, cause: err });
+            throw new DataSourceError(`Failed to get SOL price: ${err.message}`, 'codex', { fellBackToCache: false, cause: err });
         }
     }
     // ============================================================
-    // 池/流动性信息 -- CodexAdapter + DataStore 缓存穿透
+    // Pool/Liquidity Info -- CodexAdapter + DataStore cache-through
     // ============================================================
     /**
-     * 获取流动性池信息。
+     * Get liquidity pool info.
      *
-     * 缓存穿透: DataStore 有效 -> 返回; miss/过期 -> Codex 获取并写入。
+     * Cache-through: DataStore valid -> return; miss/expired -> fetch from Codex and write.
      */
     async getPoolInfo(ca) {
-        // 1. 查本地缓存
+        // 1. Check local cache
         const cached = this.store.getPoolInfo(ca);
         if (cached && !this.isExpired(cached.updatedAt, POOL_INFO_TTL_MS)) {
             return cached;
         }
-        // 2. 从 Codex 获取
+        // 2. Fetch from Codex
         try {
             const codexPool = await this.codex.getPoolInfo(ca);
             const poolInfo = {
@@ -204,105 +204,105 @@ export class DataSource {
             return poolInfo;
         }
         catch (err) {
-            // fallback 到陈旧缓存
+            // fallback to stale cache
             if (cached) {
                 return cached;
             }
-            throw new DataSourceError(`获取池信息失败 (${ca}): ${err.message}`, 'codex', { cause: err });
+            throw new DataSourceError(`Failed to get pool info (${ca}): ${err.message}`, 'codex', { cause: err });
         }
     }
     // ============================================================
-    // K线数据 -- CodexAdapter (无本地缓存)
+    // Candlestick Data -- CodexAdapter (no local cache)
     // ============================================================
     /**
-     * 获取 K线 (OHLCV) 数据。
-     * K线数据量大且时效性强, 不做本地缓存。
+     * Get candlestick (OHLCV) data.
+     * Candlestick data is large and time-sensitive, no local caching.
      */
     async getKlineData(params) {
         try {
             return await this.codex.getBars(params);
         }
         catch (err) {
-            throw new DataSourceError(`获取 K线数据失败: ${err.message}`, 'codex', { cause: err });
+            throw new DataSourceError(`Failed to get candlestick data: ${err.message}`, 'codex', { cause: err });
         }
     }
     /**
-     * 获取代币的交易对列表。
+     * Get trading pair list for a token.
      */
     async getPairsForToken(ca, limit) {
         try {
             return await this.codex.getPairsForToken(ca, limit);
         }
         catch (err) {
-            throw new DataSourceError(`获取交易对失败 (${ca}): ${err.message}`, 'codex', { cause: err });
+            throw new DataSourceError(`Failed to get trading pairs (${ca}): ${err.message}`, 'codex', { cause: err });
         }
     }
     // ============================================================
-    // 余额查询 -- RpcAdapter (链上实时数据)
+    // Balance Queries -- RpcAdapter (on-chain real-time data)
     // ============================================================
     /**
-     * 获取单个钱包的 SOL 余额。
+     * Get SOL balance for a single wallet.
      */
     async getSolBalance(address) {
         try {
             return await this.rpc.getSolBalance(address);
         }
         catch (err) {
-            throw new DataSourceError(`获取 SOL 余额失败 (${address}): ${err.message}`, 'rpc', { cause: err });
+            throw new DataSourceError(`Failed to get SOL balance (${address}): ${err.message}`, 'rpc', { cause: err });
         }
     }
     /**
-     * 批量获取多个钱包的 SOL 余额。
+     * Batch get SOL balances for multiple wallets.
      */
     async getBatchSolBalances(addresses) {
         try {
             return await this.rpc.getBatchSolBalances(addresses);
         }
         catch (err) {
-            throw new DataSourceError(`批量获取 SOL 余额失败: ${err.message}`, 'rpc', { cause: err });
+            throw new DataSourceError(`Failed to batch get SOL balances: ${err.message}`, 'rpc', { cause: err });
         }
     }
     /**
-     * 获取单个钱包的单个 Token 余额。
+     * Get single token balance for a wallet.
      */
     async getTokenBalance(walletAddress, tokenMint) {
         try {
             return await this.rpc.getTokenBalance(walletAddress, tokenMint);
         }
         catch (err) {
-            throw new DataSourceError(`获取 Token 余额失败 (${walletAddress}): ${err.message}`, 'rpc', { cause: err });
+            throw new DataSourceError(`Failed to get token balance (${walletAddress}): ${err.message}`, 'rpc', { cause: err });
         }
     }
     /**
-     * 批量获取多个钱包在指定代币上的余额。
+     * Batch get token balances for multiple wallets on a specific token.
      */
     async getBatchTokenBalances(walletAddresses, tokenMint) {
         try {
             return await this.rpc.getBatchTokenBalances(walletAddresses, tokenMint);
         }
         catch (err) {
-            throw new DataSourceError(`批量获取 Token 余额失败: ${err.message}`, 'rpc', { cause: err });
+            throw new DataSourceError(`Failed to batch get token balances: ${err.message}`, 'rpc', { cause: err });
         }
     }
     /**
-     * 获取单个钱包的所有 Token 账户。
+     * Get all token accounts for a single wallet.
      */
     async getTokenAccountsByOwner(walletAddress) {
         try {
             return await this.rpc.getTokenAccountsByOwner(walletAddress);
         }
         catch (err) {
-            throw new DataSourceError(`获取 Token 账户列表失败 (${walletAddress}): ${err.message}`, 'rpc', { cause: err });
+            throw new DataSourceError(`Failed to get token account list (${walletAddress}): ${err.message}`, 'rpc', { cause: err });
         }
     }
     /**
-     * 获取钱包组在指定代币上的完整余额数据。
+     * Get complete balance data for wallet group on a specific token.
      *
-     * 从 RPC 实时获取并更新 DataStore, 然后返回 BalancesFile。
+     * Fetches from RPC in real-time, updates DataStore, then returns BalancesFile.
      */
     async getWalletBalances(walletAddresses, ca, groupId) {
         try {
-            // 并行获取 SOL 和 Token 余额
+            // Fetch SOL and Token balances in parallel
             const [solBalances, tokenBalances] = await Promise.all([
                 this.rpc.getBatchSolBalances(walletAddresses),
                 this.rpc.getBatchTokenBalances(walletAddresses, ca),
@@ -314,7 +314,7 @@ export class DataSource {
                 tokenBalance: tokenBalances[addr] ?? 0,
                 updatedAt: now,
             }));
-            // 批量写入 DataStore
+            // Batch write to DataStore
             await this.store.updateBalancesBatch(ca, groupId, balances);
             return {
                 ca,
@@ -324,240 +324,240 @@ export class DataSource {
             };
         }
         catch (err) {
-            // fallback: 返回 DataStore 中的历史数据
+            // fallback: return historical data from DataStore
             const cached = this.store.getBalances(ca, groupId);
             if (cached) {
                 return cached;
             }
-            throw new DataSourceError(`获取钱包余额失败: ${err.message}`, 'rpc', { cause: err });
+            throw new DataSourceError(`Failed to get wallet balances: ${err.message}`, 'rpc', { cause: err });
         }
     }
     // ============================================================
-    // 交易状态 -- RpcAdapter
+    // Transaction Status -- RpcAdapter
     // ============================================================
     /**
-     * 查询单笔交易的确认状态。
+     * Query confirmation status of a single transaction.
      */
     async getTransactionStatus(txHash) {
         try {
             return await this.rpc.getTransactionStatus(txHash);
         }
         catch (err) {
-            throw new DataSourceError(`获取交易状态失败 (${txHash}): ${err.message}`, 'rpc', { cause: err });
+            throw new DataSourceError(`Failed to get transaction status (${txHash}): ${err.message}`, 'rpc', { cause: err });
         }
     }
     /**
-     * 获取交易详情。
+     * Get transaction details.
      */
     async getTransactionDetail(txHash) {
         try {
             return await this.rpc.getTransactionDetail(txHash);
         }
         catch (err) {
-            throw new DataSourceError(`获取交易详情失败 (${txHash}): ${err.message}`, 'rpc', { cause: err });
+            throw new DataSourceError(`Failed to get transaction details (${txHash}): ${err.message}`, 'rpc', { cause: err });
         }
     }
     /**
-     * 批量查询交易状态。
+     * Batch query transaction statuses.
      */
     async getBatchTransactionStatuses(txHashes) {
         try {
             return await this.rpc.getBatchTransactionStatuses(txHashes);
         }
         catch (err) {
-            throw new DataSourceError(`批量获取交易状态失败: ${err.message}`, 'rpc', { cause: err });
+            throw new DataSourceError(`Failed to batch get transaction statuses: ${err.message}`, 'rpc', { cause: err });
         }
     }
     // ============================================================
-    // Bundle 操作 -- JitoAdapter
+    // Bundle Operations -- JitoAdapter
     // ============================================================
     /**
-     * 发送 Bundle 到 Jito Block Engine。
+     * Send bundle to Jito Block Engine.
      */
     async sendBundle(base64Txs) {
         try {
             return await this.jito.sendBundle(base64Txs);
         }
         catch (err) {
-            throw new DataSourceError(`发送 Bundle 失败: ${err.message}`, 'jito', { cause: err });
+            throw new DataSourceError(`Failed to send bundle: ${err.message}`, 'jito', { cause: err });
         }
     }
     /**
-     * 查询 Bundle 状态。
+     * Query bundle status.
      */
     async getBundleStatus(bundleId) {
         try {
             return await this.jito.getBundleStatus(bundleId);
         }
         catch (err) {
-            throw new DataSourceError(`获取 Bundle 状态失败 (${bundleId}): ${err.message}`, 'jito', { cause: err });
+            throw new DataSourceError(`Failed to get bundle status (${bundleId}): ${err.message}`, 'jito', { cause: err });
         }
     }
     /**
-     * 等待 Bundle 确认。
+     * Wait for bundle confirmation.
      */
     async waitForBundleConfirmation(bundleId, options) {
         try {
             return await this.jito.waitForBundleConfirmation(bundleId, options);
         }
         catch (err) {
-            throw new DataSourceError(`等待 Bundle 确认失败 (${bundleId}): ${err.message}`, 'jito', { cause: err });
+            throw new DataSourceError(`Failed waiting for bundle confirmation (${bundleId}): ${err.message}`, 'jito', { cause: err });
         }
     }
     // ============================================================
-    // 单笔交易发送 -- JitoAdapter (sendTransaction)
+    // Single Transaction Sending -- JitoAdapter (sendTransaction)
     // ============================================================
     /**
-     * 通过 Jito 发送单笔交易。
+     * Send single transaction via Jito.
      */
     async sendTransaction(base64Tx) {
         try {
             return await this.jito.sendTransaction(base64Tx);
         }
         catch (err) {
-            throw new DataSourceError(`发送交易失败: ${err.message}`, 'jito', { cause: err });
+            throw new DataSourceError(`Failed to send transaction: ${err.message}`, 'jito', { cause: err });
         }
     }
     /**
-     * 通过 RPC 确认交易状态。
+     * Confirm transaction status via RPC.
      */
     async confirmTransactionByRpc(connection, signature, timeoutMs) {
         try {
             return await this.jito.confirmTransactionByRpc(connection, signature, timeoutMs);
         }
         catch (err) {
-            throw new DataSourceError(`确认交易失败 (${signature}): ${err.message}`, 'rpc', { cause: err });
+            throw new DataSourceError(`Failed to confirm transaction (${signature}): ${err.message}`, 'rpc', { cause: err });
         }
     }
     // ============================================================
-    // 交易记录 -- DataStore (本地文件)
+    // Trade Records -- DataStore (local files)
     // ============================================================
     /**
-     * 获取交易记录。
+     * Get trade records.
      */
     getTransactions(ca, groupId) {
         return this.store.getTransactions(ca, groupId);
     }
     /**
-     * 获取指定钱包的交易记录。
+     * Get trade records for a specific wallet.
      */
     getTransactionsByWallet(ca, groupId, wallet) {
         return this.store.getTransactionsByWallet(ca, groupId, wallet);
     }
     /**
-     * 追加交易记录。
+     * Append trade records.
      */
     async appendTransaction(ca, groupId, tx) {
         try {
             await this.store.appendTransaction(ca, groupId, tx);
         }
         catch (err) {
-            throw new DataSourceError(`写入交易记录失败: ${err.message}`, 'store', { cause: err });
+            throw new DataSourceError(`Failed to write trade records: ${err.message}`, 'store', { cause: err });
         }
     }
     // ============================================================
-    // 持仓数据 -- DataStore (本地文件)
+    // Position Data -- DataStore (local files)
     // ============================================================
     /**
-     * 获取持仓数据。
+     * Get position data.
      */
     getHoldings(ca, groupId) {
         return this.store.getHoldings(ca, groupId);
     }
     /**
-     * 更新持仓数据。
+     * Update position data.
      */
     async updateHolding(ca, groupId, wallet, update) {
         try {
             await this.store.updateHolding(ca, groupId, wallet, update);
         }
         catch (err) {
-            throw new DataSourceError(`更新持仓失败: ${err.message}`, 'store', { cause: err });
+            throw new DataSourceError(`Failed to update positions: ${err.message}`, 'store', { cause: err });
         }
     }
     // ============================================================
-    // 余额快照 -- DataStore (本地文件)
+    // Balance Snapshots -- DataStore (local files)
     // ============================================================
     /**
-     * 获取本地缓存的余额快照。
+     * Get locally cached balance snapshot.
      */
     getBalancesSnapshot(ca, groupId) {
         return this.store.getBalances(ca, groupId);
     }
     /**
-     * 更新余额快照。
+     * Update balance snapshot.
      */
     async updateBalance(ca, groupId, wallet, balance) {
         try {
             await this.store.updateBalance(ca, groupId, wallet, balance);
         }
         catch (err) {
-            throw new DataSourceError(`更新余额快照失败: ${err.message}`, 'store', { cause: err });
+            throw new DataSourceError(`Failed to update balance snapshot: ${err.message}`, 'store', { cause: err });
         }
     }
     // ============================================================
-    // 全局数据 -- DataStore
+    // Global Data -- DataStore
     // ============================================================
     /**
-     * 获取手续费配置。
+     * Get fee configuration.
      */
     getFeeConfig() {
         return this.store.getFeeConfig();
     }
     /**
-     * 保存手续费配置。
+     * Save fee configuration.
      */
     async saveFeeConfig(config) {
         try {
             await this.store.saveFeeConfig(config);
         }
         catch (err) {
-            throw new DataSourceError(`保存手续费配置失败: ${err.message}`, 'store', { cause: err });
+            throw new DataSourceError(`Failed to save fee configuration: ${err.message}`, 'store', { cause: err });
         }
     }
     // ============================================================
-    // DataStore 工具方法
+    // DataStore Utility Methods
     // ============================================================
     /**
-     * 列出所有有数据的代币 CA。
+     * List all token CAs with data.
      */
     listTokens() {
         return this.store.listTokens();
     }
     /**
-     * 列出某个代币下所有有数据的钱包组 ID。
+     * List all wallet group IDs with data for a token.
      */
     listGroups(ca) {
         return this.store.listGroups(ca);
     }
     // ============================================================
-    // 交易追踪 -- TxTracker
+    // Transaction Tracking -- TxTracker
     // ============================================================
     /**
-     * 追踪单笔交易。
-     * 轮询确认后自动写入 DataStore (交易记录 + 持仓 + 余额)。
+     * Track a single transaction.
+     * Auto-writes to DataStore after polling confirmation (trade records + positions + balances).
      */
     async trackTransaction(txHash, context, options) {
         return this.tracker.trackTransaction(txHash, context, options);
     }
     /**
-     * 追踪 Jito Bundle。
-     * Bundle 确认后逐个处理内部交易并写入 DataStore。
+     * Track a Jito Bundle.
+     * Processes internal transactions individually after bundle confirmation and writes to DataStore.
      */
     async trackBundle(bundleId, txHashes, context, options) {
         return this.tracker.trackBundle(bundleId, txHashes, context, options);
     }
     /**
-     * 批量追踪多笔独立交易。
+     * Batch track multiple independent transactions.
      */
     async trackBatch(entries, options) {
         return this.tracker.trackBatch(entries, options);
     }
     // ============================================================
-    // 健康检查
+    // Health Check
     // ============================================================
     /**
-     * 检查所有数据源的健康状态。
+     * Check health status of all data sources.
      */
     async healthCheck() {
         const [codexResult, rpcResult, jitoResult] = await Promise.all([
@@ -572,43 +572,43 @@ export class DataSource {
         };
     }
     // ============================================================
-    // 底层适配器直接访问 (高级用途)
+    // Direct adapter access (advanced use)
     // ============================================================
-    /** 获取底层 CodexAdapter (仅当 DataSource 接口不够用时使用) */
+    /** Get underlying CodexAdapter (only when DataSource interface is insufficient) */
     getCodexAdapter() {
         return this.codex;
     }
-    /** 获取底层 RpcAdapter */
+    /** Get underlying RpcAdapter */
     getRpcAdapter() {
         return this.rpc;
     }
-    /** 获取底层 JitoAdapter */
+    /** Get underlying JitoAdapter */
     getJitoAdapter() {
         return this.jito;
     }
-    /** 获取底层 DataStore */
+    /** Get underlying DataStore */
     getDataStore() {
         return this.store;
     }
-    /** 获取底层 TxTracker */
+    /** Get underlying TxTracker */
     getTxTracker() {
         return this.tracker;
     }
     // ============================================================
-    // 内部工具方法
+    // Internal utility methods
     // ============================================================
     /**
-     * 检查时间戳是否已过期。
-     * @param updatedAt 上次更新时间 (ms)
-     * @param ttlMs 有效期 (ms)
-     * @returns true 表示已过期
+     * Check if timestamp has expired.
+     * @param updatedAt Last update time (ms)
+     * @param ttlMs Time-to-live (ms)
+     * @returns true if expired
      */
     isExpired(updatedAt, ttlMs) {
         return Date.now() - updatedAt > ttlMs;
     }
     /**
-     * 根据 DEX/交易所名称推断 DEX 类型。
-     * Codex API 返回的 exchangeName 映射到 TokenInfoFile.dex 枚举。
+     * Infer DEX type from DEX/exchange name.
+     * Maps Codex API exchangeName to TokenInfoFile.dex enum.
      */
     inferDex(exchangeName) {
         if (!exchangeName)
@@ -624,17 +624,17 @@ export class DataSource {
             return 'launchlab';
         if (name.includes('meteora'))
             return 'meteora';
-        // 无法识别时默认 pump
+        // Default to pump when unrecognized
         return 'pump';
     }
 }
 // ============================================================
-// 单例管理
+// Singleton Management
 // ============================================================
 let _instance = null;
 /**
- * 获取 DataSource 全局单例。
- * 命令层的标准入口:
+ * Get DataSource global singleton.
+ * Standard entry point for command layer:
  *   import { getDataSource } from '../data-source.js';
  *   const ds = getDataSource();
  */
@@ -645,7 +645,7 @@ export function getDataSource() {
     return _instance;
 }
 /**
- * 重置单例 (用于测试或配置变更后重新初始化)。
+ * Reset singleton (for testing or re-initialization after config changes).
  */
 export function resetDataSource() {
     _instance = null;