100x-sdk 1.0.2 → 1.0.4

package/src/modules/simulator/long_shrot_stop.js

@@ -8,122 +8,122 @@ const JSONbig = require('json-bigint')({ storeAsString: false });
 /**
  * Simulate long position stop loss calculation
  *
- * 模拟做多仓位的止损计算,返回可执行的止损价格和相关参数。
- * 该函数会自动调整止损价格以避免与现有订单的价格区间重叠,
- * 并返回合约执行时需要的插入位置索引数组。
+ * Simulates the stop loss calculation for a long position, returning the executable stop loss price and related parameters.
+ * This function automatically adjusts the stop loss price to avoid overlapping with the price ranges of existing orders,
+ * and returns the insertion position index array required for contract execution.
  *
- * @param {string} mint - Token address / 代币地址
- * @param {bigint|string|number} buyTokenAmount - Token amount to buy for long position (u64 format, precision 10^9) / 做多买入的代币数量 (u64格式, 精度 10^9)
- * @param {bigint|string|number} stopLossPrice - User desired stop loss price (u128 format) / 用户期望的止损价格 (u128格式)
- * @param {Object|null} lastPrice - Token info, default null / 代币当前价格信息,默认null会自动获取
- * @param {Object|null} ordersData - Orders data, default null / 订单数据,默认null会自动获取
- * @param {number} borrowFee - Borrow fee rate, default 2000 (2000/100000 = 0.02%) / 借贷手续费率,默认2000 (2000/100000 = 0.02%)
+ * @param {string} mint - Token address
+ * @param {bigint|string|number} buyTokenAmount - Token amount to buy for long position (u64 format, precision 10^9)
+ * @param {bigint|string|number} stopLossPrice - User desired stop loss price (u128 format)
+ * @param {Object|null} lastPrice - Token info, default null (auto-fetched if null)
+ * @param {Object|null} ordersData - Orders data, default null (auto-fetched if null)
+ * @param {number} borrowFee - Borrow fee rate, default 2000 (2000/100000 = 0.02%)
  *
- * @returns {Promise<Object>} Stop loss analysis result / 止损分析结果对象
- * @returns {bigint} returns.executableStopLossPrice - 计算出的可执行止损价格 (u128格式)
- *   - 这是经过调整后不与现有订单重叠的止损价格
- *   - 可能低于用户输入的 stopLossPrice (因为需要避免重叠)
- *   - 可以直接用于调用 sdk.trading.long() 的 closePrice 参数
+ * @returns {Promise<Object>} Stop loss analysis result
+ * @returns {bigint} returns.executableStopLossPrice - Calculated executable stop loss price (u128 format)
+ *   - This is the stop loss price adjusted to not overlap with existing orders
+ *   - May be lower than the user-provided stopLossPrice (to avoid overlap)
+ *   - Can be used directly as the closePrice parameter of sdk.trading.long()
  *
- * @returns {bigint} returns.tradeAmount - 止损时预计卖出获得的SOL数量 (lamports)
- *   - 这是在 executableStopLossPrice 价格卖出 buyTokenAmount 代币能获得的SOL
- *   - 不包含手续费扣除
- *   - 用于估算止损时的收益
+ * @returns {bigint} returns.tradeAmount - Estimated SOL amount obtained from selling at stop loss (lamports)
+ *   - This is the SOL obtained from selling buyTokenAmount tokens at the executableStopLossPrice
+ *   - Does not include fee deduction
+ *   - Used to estimate the proceeds at stop loss
  *
- * @returns {number} returns.stopLossPercentage - 止损百分比 (相对于当前价格)
- *   - 计算公式: ((currentPrice - executableStopLossPrice) / currentPrice) * 100
- *   - 例如: 3.5 表示止损价格比当前价格低3.5%
- *   - 做多时这个值应该是正数 (止损价低于当前价)
+ * @returns {number} returns.stopLossPercentage - Stop loss percentage (relative to current price)
+ *   - Formula: ((currentPrice - executableStopLossPrice) / currentPrice) * 100
+ *   - For example: 3.5 means the stop loss price is 3.5% lower than the current price
+ *   - For a long position this value should be positive (stop loss price below current price)
  *
- * @returns {number} returns.leverage - 杠杆倍数
- *   - 计算公式: currentPrice / (currentPrice - executableStopLossPrice)
- *   - 例如: 28.57 表示约28.57倍杠杆
- *   - 杠杆越高,风险越大,但潜在收益也越大
+ * @returns {number} returns.leverage - Leverage ratio
+ *   - Formula: currentPrice / (currentPrice - executableStopLossPrice)
+ *   - For example: 28.57 means about 28.57x leverage
+ *   - The higher the leverage, the higher the risk, but also the higher the potential return
  *
- * @returns {bigint} returns.currentPrice - 当前价格 (u128格式)
- *   - 计算时使用的代币当前价格
- *   - 用于参考和验证
+ * @returns {bigint} returns.currentPrice - Current price (u128 format)
+ *   - The current token price used in the calculation
+ *   - Used for reference and validation
  *
- * @returns {number} returns.iterations - 价格调整迭代次数
- *   - 为了避免价格区间重叠,函数自动调整止损价格的次数
- *   - 每次调整会将价格降低 PRICE_ADJUSTMENT_PERCENTAGE (默认0.5%)
- *   - 如果迭代次数过高,可能需要重新选择止损价格
+ * @returns {number} returns.iterations - Number of price adjustment iterations
+ *   - The number of times the function automatically adjusted the stop loss price to avoid price range overlap
+ *   - Each adjustment lowers the price by PRICE_ADJUSTMENT_PERCENTAGE (default 0.5%)
+ *   - If the iteration count is too high, you may need to reselect the stop loss price
  *
- * @returns {bigint} returns.originalStopLossPrice - 用户输入的原始止损价格 (u128格式)
- *   - 用于对比调整前后的价格差异
- *   - 如果 executableStopLossPrice 与此差异较大,说明现有订单较密集
+ * @returns {bigint} returns.originalStopLossPrice - User-provided original stop loss price (u128 format)
+ *   - Used to compare the price difference before and after adjustment
+ *   - If executableStopLossPrice differs greatly from this, it indicates existing orders are dense
  *
- * @returns {number[]} returns.close_insert_indices - 平仓订单插入位置的候选索引数组 ⭐ 新增
- *   - 数组包含多个候选插入位置的 OrderBook 索引值
- *   - 结构: [主位置index, 前1个index, 后1个index, 前2个index, 后2个index, 前3个index, 后3个index]
- *   - 例如: [25, 10, 33, 5, 40, 2, 50] 表示主位置是索引25,备选位置包括索引10、33等
- *   - 最多包含7个索引值 (1个主位置 + 前3个 + 后3个)
- *   - 如果订单簿为空,返回 [65535] (u16::MAX,表示插入到头部)
- *   - 用途: 传递给 sdk.trading.long() 的 closeInsertIndices 参数
- *   - 提高成功率: 即使主位置的订单被删除,合约也能尝试其他候选位置
+ * @returns {number[]} returns.close_insert_indices - Candidate index array for the closing order insertion position ⭐ New
+ *   - The array contains the OrderBook index values of multiple candidate insertion positions
+ *   - Structure: [main position index, 1st before, 1st after, 2nd before, 2nd after, 3rd before, 3rd after]
+ *   - For example: [25, 10, 33, 5, 40, 2, 50] means the main position is index 25, with alternative positions including indices 10, 33, etc.
+ *   - Contains up to 7 index values (1 main position + 3 before + 3 after)
+ *   - If the orderbook is empty, returns [65535] (u16::MAX, meaning insert at the head)
+ *   - Usage: passed as the closeInsertIndices parameter of sdk.trading.long()
+ *   - Improves success rate: even if the order at the main position is deleted, the contract can try other candidate positions
  *
- * @returns {bigint} returns.estimatedMargin - 预估所需保证金 (SOL lamports)
- *   - 计算公式: 买入成本 - 平仓收益(扣除手续费后)
- *   - 这是执行此止损策略需要的最少保证金
- *   - 可以用于 sdk.trading.long() 的 marginSolMax 参数
- *   - 实际调用时建议增加10-20%余量以应对价格波动
+ * @returns {bigint} returns.estimatedMargin - Estimated required margin (SOL lamports)
+ *   - Formula: buy cost - close proceeds (after fee deduction)
+ *   - This is the minimum margin required to execute this stop loss strategy
+ *   - Can be used as the marginSolMax parameter of sdk.trading.long()
+ *   - When actually calling, it is recommended to add a 10-20% buffer to handle price fluctuations
  *
- * @throws {Error} 当缺少必需参数时
- * @throws {Error} 当无法获取价格或订单数据时
- * @throws {Error} 当达到最大迭代次数仍无法找到合适的止损价格时
- * @throws {Error} 当价格调整后变为负数时
+ * @throws {Error} When required parameters are missing
+ * @throws {Error} When price or orders data cannot be fetched
+ * @throws {Error} When a suitable stop loss price cannot be found after reaching the maximum iterations
+ * @throws {Error} When the price becomes negative after adjustment
  *
  * @example
- * // 基础用法: 做多1个代币,止损价格为当前价格的97%
+ * // Basic usage: long 1 token, stop loss price at 97% of the current price
  * const result = await sdk.simulator.simulateLongStopLoss(
  *   '4Kq51Kt48FCwdo5CeKjRVPodH1ticHa7mZ5n5gqMEy1X',  // mint
- *   1000000000n,                                       // 1 token (精度10^9)
- *   BigInt('97000000000000000000')                     // 止损价格
+ *   1000000000n,                                       // 1 token (precision 10^9)
+ *   BigInt('97000000000000000000')                     // stop loss price
  * );
  *
- * console.log(`可执行止损价格: ${result.executableStopLossPrice}`);
- * console.log(`止损百分比: ${result.stopLossPercentage}%`);
- * console.log(`杠杆倍数: ${result.leverage}x`);
- * console.log(`预估保证金: ${result.estimatedMargin} lamports`);
- * console.log(`插入位置索引: ${result.close_insert_indices}`);
+ * console.log(`Executable stop loss price: ${result.executableStopLossPrice}`);
+ * console.log(`Stop loss percentage: ${result.stopLossPercentage}%`);
+ * console.log(`Leverage: ${result.leverage}x`);
+ * console.log(`Estimated margin: ${result.estimatedMargin} lamports`);
+ * console.log(`Insert position indices: ${result.close_insert_indices}`);
  *
  * @example
- * // 完整使用流程: 模拟后执行做多交易
+ * // Full workflow: simulate then execute a long trade
  * async function openLongPosition(sdk, mint, buyTokenAmount, stopLossPrice) {
- *   // 1. 模拟止损计算
+ *   // 1. Simulate stop loss calculation
  *   const simulation = await sdk.simulator.simulateLongStopLoss(
  *     mint,
  *     buyTokenAmount,
  *     stopLossPrice
  *   );
  *
- *   // 2. 检查止损价格是否被大幅调整
+ *   // 2. Check whether the stop loss price was significantly adjusted
  *   const priceDiff = Number((simulation.originalStopLossPrice - simulation.executableStopLossPrice) * 10000n / simulation.originalStopLossPrice) / 100;
  *   if (priceDiff > 1.0) {
- *     console.warn(`止损价格被调整了 ${priceDiff}%, 当前订单较密集`);
+ *     console.warn(`Stop loss price was adjusted by ${priceDiff}%, existing orders are dense`);
  *   }
  *
- *   // 3. 准备交易参数
- *   const maxSolAmount = simulation.estimatedMargin * 120n / 100n; // 增加20%余量
- *   const marginSolMax = simulation.estimatedMargin * 115n / 100n; // 增加15%余量
+ *   // 3. Prepare transaction parameters
+ *   const maxSolAmount = simulation.estimatedMargin * 120n / 100n; // add 20% buffer
+ *   const marginSolMax = simulation.estimatedMargin * 115n / 100n; // add 15% buffer
  *
- *   // 4. 执行做多交易
+ *   // 4. Execute the long trade
  *   const tx = await sdk.trading.long({
  *     mint: mint,
  *     buyTokenAmount: buyTokenAmount,
  *     maxSolAmount: maxSolAmount,
  *     marginSolMax: marginSolMax,
  *     closePrice: simulation.executableStopLossPrice,
- *     closeInsertIndices: simulation.close_insert_indices  // ⭐ 使用新的索引数组
+ *     closeInsertIndices: simulation.close_insert_indices  // ⭐ use the new index array
  *   });
  *
  *   return tx;
  * }
  *
- * @see {@link simulateShortStopLoss} 做空仓位的止损计算
- * @see {@link simulateLongSolStopLoss} 基于SOL金额的做多止损计算
+ * @see {@link simulateShortStopLoss} Stop loss calculation for short positions
+ * @see {@link simulateLongSolStopLoss} SOL-amount-based stop loss calculation for long positions
  * @since 2.0.0
- * @version 2.0.0 - 从返回 prev_order_pda/next_order_pda 改为返回 close_insert_indices
+ * @version 2.0.0 - Changed from returning prev_order_pda/next_order_pda to returning close_insert_indices
  */
 async function simulateLongStopLoss(mint, buyTokenAmount, stopLossPrice, lastPrice = null, ordersData = null, borrowFee = null, initialVirtualSol = null, initialVirtualToken = null) {
     try {
@@ -132,12 +132,12 @@ async function simulateLongStopLoss(mint, buyTokenAmount, stopLossPrice, lastPri
             throw new Error('Missing required parameters');
         }
 
-        // 如果没有传入 borrowFee 或池子参数，从链上一次性获取
+        // If borrowFee or pool parameters are not provided, fetch them from the chain in a single call
         if (borrowFee === null || initialVirtualSol === null || initialVirtualToken === null) {
             const curveAccount = await this.sdk.chain.getCurveAccount(mint, { skipBalances: true });
             if (borrowFee === null) borrowFee = curveAccount.borrowFee;
-            // 链上返回的是 u64 原始单位（lamports/最小单位），需要除以 10^9 转为人类可读单位
-            // 与 calcLiq.js 中的转换方式一致
+            // The chain returns u64 raw units (lamports/smallest unit), which need to be divided by 10^9 to convert to human-readable units
+            // Consistent with the conversion method in calcLiq.js
             if (initialVirtualSol === null) initialVirtualSol = new Decimal(curveAccount.initialVirtualSol.toString()).div(CurveAMM.SOL_PRECISION_FACTOR_DECIMAL).toString();
             if (initialVirtualToken === null) initialVirtualToken = new Decimal(curveAccount.initialVirtualToken.toString()).div(CurveAMM.TOKEN_PRECISION_FACTOR_DECIMAL).toString();
         }
@@ -191,7 +191,7 @@ async function simulateLongStopLoss(mint, buyTokenAmount, stopLossPrice, lastPri
         let finalOverlapResult = null; // Record final overlap result
         let finalTradeAmount = 0n; // Record final trade amount
 
-        // 检查并调整止损价格以满足最小距离要求 (做多: 止损价必须低于当前价至少 MIN_STOP_LOSS_PERCENT)
+        // Check and adjust the stop loss price to meet the minimum distance requirement (long: stop loss price must be below current price by at least MIN_STOP_LOSS_PERCENT)
         // Check and adjust stop loss price to meet minimum distance requirement (long: stop loss must be below current price by at least MIN_STOP_LOSS_PERCENT)
         const minAllowedStopLoss = currentPrice - (currentPrice * BigInt(MIN_STOP_LOSS_PERCENT)) / 1000n;
         if (stopLossStartPrice > minAllowedStopLoss) {
@@ -230,33 +230,33 @@ async function simulateLongStopLoss(mint, buyTokenAmount, stopLossPrice, lastPri
             }
 
             stopLossEndPrice = tradeResult[0]; // Price after trade completion
-            const tradeAmount = tradeResult[1]; // SOL输出量 / SOL output amount
+            const tradeAmount = tradeResult[1]; // SOL output amount
 
             // console.log(`  - stopLossEndPrice: ${stopLossEndPrice.toString()}`);
             // console.log(`  - tradeAmount: ${tradeAmount.toString()}`);
 
-            //console.log(`迭代 ${iteration}: 起始价格=${stopLossStartPrice}, 结束价格=${stopLossEndPrice}, SOL输出量=${tradeAmount} / Iteration ${iteration}: Start=${stopLossStartPrice}, End=${stopLossEndPrice}, SOL output=${tradeAmount}`);
+            //console.log(`Iteration ${iteration}: startPrice=${stopLossStartPrice}, endPrice=${stopLossEndPrice}, SOL output=${tradeAmount} / Iteration ${iteration}: Start=${stopLossStartPrice}, End=${stopLossEndPrice}, SOL output=${tradeAmount}`);
 
-            // 检查价格区间重叠 / Check price range overlap
+            // Check price range overlap
             const overlapResult = checkPriceRangeOverlap('down_orders', downOrders, stopLossStartPrice, stopLossEndPrice);
-            
+
             if (overlapResult.no_overlap) {
-                //console.log('价格区间无重叠，可以执行 / No price range overlap, can execute');
-                finalOverlapResult = overlapResult; // 记录最终的overlap结果 / Record final overlap result
-                finalTradeAmount = tradeAmount; // 记录最终的交易金额 / Record final trade amount
+                //console.log('No price range overlap, can execute / No price range overlap, can execute');
+                finalOverlapResult = overlapResult; // Record final overlap result
+                finalTradeAmount = tradeAmount; // Record final trade amount
                 break;
             }
 
-            //console.log(`发现重叠: ${overlapResult.overlap_reason} / Found overlap: ${overlapResult.overlap_reason}`);
+            //console.log(`Found overlap: ${overlapResult.overlap_reason} / Found overlap: ${overlapResult.overlap_reason}`);
 
-            // 调整起始价格（减少0.5%）/ Adjust start price (decrease by 0.5%)
-            // 使用方案2：直接计算 0.5% = 5/1000
+            // Adjust start price (decrease by 0.5%)
+            // Using approach 2: directly compute 0.5% = 5/1000
             const adjustmentAmount = (stopLossStartPrice * BigInt(PRICE_ADJUSTMENT_PERCENTAGE)) / 1000n;
             stopLossStartPrice = stopLossStartPrice - adjustmentAmount;
 
-            //console.log(`调整后起始价格: ${stopLossStartPrice} / Adjusted start price: ${stopLossStartPrice}`);
+            //console.log(`Adjusted start price: ${stopLossStartPrice} / Adjusted start price: ${stopLossStartPrice}`);
 
-            // 安全检查：确保价格不会变成负数 / Safety check: ensure price doesn't become negative
+            // Safety check: ensure the price does not become negative
             if (stopLossStartPrice <= 0n) {
                 throw new Error('止损价格调整后变为负数，无法继续 / Stop loss price became negative after adjustment');
             }
@@ -266,30 +266,30 @@ async function simulateLongStopLoss(mint, buyTokenAmount, stopLossPrice, lastPri
             throw new Error('达到最大迭代次数，无法找到合适的止损价格 / Reached maximum iterations, cannot find suitable stop loss price');
         }
 
-        // 计算最终返回值 / Calculate final return values
+        // Calculate final return values
         const executableStopLossPrice = stopLossStartPrice;
-        
-        // 计算止损百分比 / Calculate stop loss percentage
+
+        // Calculate stop loss percentage
         let stopLossPercentage = 0;
         let leverage = 1;
-        
+
         if (currentPrice !== executableStopLossPrice) {
             stopLossPercentage = Number((BigInt(10000) * (currentPrice - executableStopLossPrice)) / currentPrice) / 100;
             leverage = Number((BigInt(10000) * currentPrice) / (currentPrice - executableStopLossPrice)) / 10000;
         }
 
-        // 计算保证金 / Calculate margin requirement
+        // Calculate margin requirement
         let estimatedMargin = 0n;
         try {
-            // 1. 计算从当前价格买入所需的SOL
+            // 1. Calculate the SOL required to buy from the current price
             const buyResult = CurveAMM.buyFromPriceWithTokenOutputWithParams(currentPrice, buyTokenAmount, initialVirtualSol, initialVirtualToken);
             if (buyResult) {
                 const requiredSol = buyResult[1]; // SOL input amount
 
-                // 2. 计算平仓时扣除手续费后的收益
+                // 2. Calculate the proceeds at close after deducting the fee
                 const closeOutputSolAfterFee = CurveAMM.calculateAmountAfterFee(finalTradeAmount, borrowFee);
-                
-                // 3. 计算保证金 = 买入成本 - 平仓收益(扣费后)
+
+                // 3. Calculate margin = buy cost - close proceeds (after fee deduction)
                 if (closeOutputSolAfterFee !== null && requiredSol > closeOutputSolAfterFee) {
                     estimatedMargin = requiredSol - closeOutputSolAfterFee;
                 }
@@ -328,122 +328,122 @@ async function simulateLongStopLoss(mint, buyTokenAmount, stopLossPrice, lastPri
 /**
  * Simulate short position stop loss calculation
  *
- * 模拟做空仓位的止损计算,返回可执行的止损价格和相关参数。
- * 该函数会自动调整止损价格以避免与现有订单的价格区间重叠,
- * 并返回合约执行时需要的插入位置索引数组。
+ * Simulates the stop loss calculation for a short position, returning the executable stop loss price and related parameters.
+ * This function automatically adjusts the stop loss price to avoid overlapping with the price ranges of existing orders,
+ * and returns the insertion position index array required for contract execution.
  *
- * @param {string} mint - Token address / 代币地址
- * @param {bigint|string|number} sellTokenAmount - Token amount to sell for short position (u64 format, precision 10^9) / 做空卖出的代币数量 (u64格式, 精度 10^9)
- * @param {bigint|string|number} stopLossPrice - User desired stop loss price (u128 format) / 用户期望的止损价格 (u128格式)
- * @param {Object|null} lastPrice - Token info, default null / 代币当前价格信息,默认null会自动获取
- * @param {Object|null} ordersData - Orders data, default null / 订单数据,默认null会自动获取
- * @param {number} borrowFee - Borrow fee rate, default 2000 (2000/100000 = 0.02%) / 借贷手续费率,默认2000 (2000/100000 = 0.02%)
+ * @param {string} mint - Token address
+ * @param {bigint|string|number} sellTokenAmount - Token amount to sell for short position (u64 format, precision 10^9)
+ * @param {bigint|string|number} stopLossPrice - User desired stop loss price (u128 format)
+ * @param {Object|null} lastPrice - Token info, default null (auto-fetched if null)
+ * @param {Object|null} ordersData - Orders data, default null (auto-fetched if null)
+ * @param {number} borrowFee - Borrow fee rate, default 2000 (2000/100000 = 0.02%)
  *
- * @returns {Promise<Object>} Stop loss analysis result / 止损分析结果对象
- * @returns {bigint} returns.executableStopLossPrice - 计算出的可执行止损价格 (u128格式)
- *   - 这是经过调整后不与现有订单重叠的止损价格
- *   - 可能高于用户输入的 stopLossPrice (因为需要避免重叠)
- *   - 可以直接用于调用 sdk.trading.short() 的 closePrice 参数
+ * @returns {Promise<Object>} Stop loss analysis result
+ * @returns {bigint} returns.executableStopLossPrice - Calculated executable stop loss price (u128 format)
+ *   - This is the stop loss price adjusted to not overlap with existing orders
+ *   - May be higher than the user-provided stopLossPrice (to avoid overlap)
+ *   - Can be used directly as the closePrice parameter of sdk.trading.short()
  *
- * @returns {bigint} returns.tradeAmount - 止损时预计买入需要的SOL数量 (lamports)
- *   - 这是在 executableStopLossPrice 价格买回 sellTokenAmount 代币需要的SOL
- *   - 不包含手续费
- *   - 用于估算止损时的成本
+ * @returns {bigint} returns.tradeAmount - Estimated SOL amount needed to buy back at stop loss (lamports)
+ *   - This is the SOL needed to buy back sellTokenAmount tokens at the executableStopLossPrice
+ *   - Does not include fees
+ *   - Used to estimate the cost at stop loss
  *
- * @returns {number} returns.stopLossPercentage - 止损百分比 (相对于当前价格)
- *   - 计算公式: ((executableStopLossPrice - currentPrice) / currentPrice) * 100
- *   - 例如: 3.5 表示止损价格比当前价格高3.5%
- *   - 做空时这个值应该是正数 (止损价高于当前价)
+ * @returns {number} returns.stopLossPercentage - Stop loss percentage (relative to current price)
+ *   - Formula: ((executableStopLossPrice - currentPrice) / currentPrice) * 100
+ *   - For example: 3.5 means the stop loss price is 3.5% higher than the current price
+ *   - For a short position this value should be positive (stop loss price above current price)
  *
- * @returns {number} returns.leverage - 杠杆倍数
- *   - 计算公式: currentPrice / (executableStopLossPrice - currentPrice)
- *   - 例如: 28.57 表示约28.57倍杠杆
- *   - 杠杆越高,风险越大,但潜在收益也越大
+ * @returns {number} returns.leverage - Leverage ratio
+ *   - Formula: currentPrice / (executableStopLossPrice - currentPrice)
+ *   - For example: 28.57 means about 28.57x leverage
+ *   - The higher the leverage, the higher the risk, but also the higher the potential return
  *
- * @returns {bigint} returns.currentPrice - 当前价格 (u128格式)
- *   - 计算时使用的代币当前价格
- *   - 用于参考和验证
+ * @returns {bigint} returns.currentPrice - Current price (u128 format)
+ *   - The current token price used in the calculation
+ *   - Used for reference and validation
  *
- * @returns {number} returns.iterations - 价格调整迭代次数
- *   - 为了避免价格区间重叠,函数自动调整止损价格的次数
- *   - 每次调整会将价格提高 PRICE_ADJUSTMENT_PERCENTAGE (默认0.5%)
- *   - 如果迭代次数过高,可能需要重新选择止损价格
+ * @returns {number} returns.iterations - Number of price adjustment iterations
+ *   - The number of times the function automatically adjusted the stop loss price to avoid price range overlap
+ *   - Each adjustment raises the price by PRICE_ADJUSTMENT_PERCENTAGE (default 0.5%)
+ *   - If the iteration count is too high, you may need to reselect the stop loss price
  *
- * @returns {bigint} returns.originalStopLossPrice - 用户输入的原始止损价格 (u128格式)
- *   - 用于对比调整前后的价格差异
- *   - 如果 executableStopLossPrice 与此差异较大,说明现有订单较密集
+ * @returns {bigint} returns.originalStopLossPrice - User-provided original stop loss price (u128 format)
+ *   - Used to compare the price difference before and after adjustment
+ *   - If executableStopLossPrice differs greatly from this, it indicates existing orders are dense
  *
- * @returns {number[]} returns.close_insert_indices - 平仓订单插入位置的候选索引数组 ⭐ 新增
- *   - 数组包含多个候选插入位置的 OrderBook 索引值
- *   - 结构: [主位置index, 前1个index, 后1个index, 前2个index, 后2个index, 前3个index, 后3个index]
- *   - 例如: [25, 10, 33, 5, 40, 2, 50] 表示主位置是索引25,备选位置包括索引10、33等
- *   - 最多包含7个索引值 (1个主位置 + 前3个 + 后3个)
- *   - 如果订单簿为空,返回 [65535] (u16::MAX,表示插入到头部)
- *   - 用途: 传递给 sdk.trading.short() 的 closeInsertIndices 参数
- *   - 提高成功率: 即使主位置的订单被删除,合约也能尝试其他候选位置
+ * @returns {number[]} returns.close_insert_indices - Candidate index array for the closing order insertion position ⭐ New
+ *   - The array contains the OrderBook index values of multiple candidate insertion positions
+ *   - Structure: [main position index, 1st before, 1st after, 2nd before, 2nd after, 3rd before, 3rd after]
+ *   - For example: [25, 10, 33, 5, 40, 2, 50] means the main position is index 25, with alternative positions including indices 10, 33, etc.
+ *   - Contains up to 7 index values (1 main position + 3 before + 3 after)
+ *   - If the orderbook is empty, returns [65535] (u16::MAX, meaning insert at the head)
+ *   - Usage: passed as the closeInsertIndices parameter of sdk.trading.short()
+ *   - Improves success rate: even if the order at the main position is deleted, the contract can try other candidate positions
  *
- * @returns {bigint} returns.estimatedMargin - 预估所需保证金 (SOL lamports)
- *   - 计算公式: 平仓成本(含手续费) - 开仓收益 - 开仓手续费
- *   - 这是执行此止损策略需要的最少保证金
- *   - 可以用于 sdk.trading.short() 的 marginSolMax 参数
- *   - 实际调用时建议增加10-20%余量以应对价格波动
+ * @returns {bigint} returns.estimatedMargin - Estimated required margin (SOL lamports)
+ *   - Formula: close cost (including fee) - open proceeds - open fee
+ *   - This is the minimum margin required to execute this stop loss strategy
+ *   - Can be used as the marginSolMax parameter of sdk.trading.short()
+ *   - When actually calling, it is recommended to add a 10-20% buffer to handle price fluctuations
  *
- * @throws {Error} 当缺少必需参数时
- * @throws {Error} 当无法获取价格或订单数据时
- * @throws {Error} 当达到最大迭代次数仍无法找到合适的止损价格时
- * @throws {Error} 当价格调整后超过最大值时
+ * @throws {Error} When required parameters are missing
+ * @throws {Error} When price or orders data cannot be fetched
+ * @throws {Error} When a suitable stop loss price cannot be found after reaching the maximum iterations
+ * @throws {Error} When the price exceeds the maximum value after adjustment
  *
  * @example
- * // 基础用法: 做空1个代币,止损价格为当前价格的103%
+ * // Basic usage: short 1 token, stop loss price at 103% of the current price
  * const result = await sdk.simulator.simulateShortStopLoss(
  *   '4Kq51Kt48FCwdo5CeKjRVPodH1ticHa7mZ5n5gqMEy1X',  // mint
- *   1000000000n,                                       // 1 token (精度10^9)
- *   BigInt('103000000000000000000')                    // 止损价格
+ *   1000000000n,                                       // 1 token (precision 10^9)
+ *   BigInt('103000000000000000000')                    // stop loss price
  * );
  *
- * console.log(`可执行止损价格: ${result.executableStopLossPrice}`);
- * console.log(`止损百分比: ${result.stopLossPercentage}%`);
- * console.log(`杠杆倍数: ${result.leverage}x`);
- * console.log(`预估保证金: ${result.estimatedMargin} lamports`);
- * console.log(`插入位置索引: ${result.close_insert_indices}`);
+ * console.log(`Executable stop loss price: ${result.executableStopLossPrice}`);
+ * console.log(`Stop loss percentage: ${result.stopLossPercentage}%`);
+ * console.log(`Leverage: ${result.leverage}x`);
+ * console.log(`Estimated margin: ${result.estimatedMargin} lamports`);
+ * console.log(`Insert position indices: ${result.close_insert_indices}`);
  *
  * @example
- * // 完整使用流程: 模拟后执行做空交易
+ * // Full workflow: simulate then execute a short trade
  * async function openShortPosition(sdk, mint, sellTokenAmount, stopLossPrice) {
- *   // 1. 模拟止损计算
+ *   // 1. Simulate stop loss calculation
  *   const simulation = await sdk.simulator.simulateShortStopLoss(
  *     mint,
  *     sellTokenAmount,
  *     stopLossPrice
  *   );
  *
- *   // 2. 检查止损价格是否被大幅调整
+ *   // 2. Check whether the stop loss price was significantly adjusted
  *   const priceDiff = Number((simulation.executableStopLossPrice - simulation.originalStopLossPrice) * 10000n / simulation.originalStopLossPrice) / 100;
  *   if (priceDiff > 1.0) {
- *     console.warn(`止损价格被调整了 ${priceDiff}%, 当前订单较密集`);
+ *     console.warn(`Stop loss price was adjusted by ${priceDiff}%, existing orders are dense`);
  *   }
  *
- *   // 3. 准备交易参数
- *   const minSolOutput = simulation.tradeAmount * 80n / 100n; // 至少获得80%
- *   const marginSolMax = simulation.estimatedMargin * 115n / 100n; // 增加15%余量
+ *   // 3. Prepare transaction parameters
+ *   const minSolOutput = simulation.tradeAmount * 80n / 100n; // obtain at least 80%
+ *   const marginSolMax = simulation.estimatedMargin * 115n / 100n; // add 15% buffer
  *
- *   // 4. 执行做空交易
+ *   // 4. Execute the short trade
  *   const tx = await sdk.trading.short({
  *     mint: mint,
  *     borrowSellTokenAmount: sellTokenAmount,
  *     minSolOutput: minSolOutput,
  *     marginSolMax: marginSolMax,
  *     closePrice: simulation.executableStopLossPrice,
- *     closeInsertIndices: simulation.close_insert_indices  // ⭐ 使用新的索引数组
+ *     closeInsertIndices: simulation.close_insert_indices  // ⭐ use the new index array
  *   });
  *
  *   return tx;
  * }
  *
- * @see {@link simulateLongStopLoss} 做多仓位的止损计算
- * @see {@link simulateShortSolStopLoss} 基于SOL金额的做空止损计算
+ * @see {@link simulateLongStopLoss} Stop loss calculation for long positions
+ * @see {@link simulateShortSolStopLoss} SOL-amount-based stop loss calculation for short positions
  * @since 2.0.0
- * @version 2.0.0 - 从返回 prev_order_pda/next_order_pda 改为返回 close_insert_indices
+ * @version 2.0.0 - Changed from returning prev_order_pda/next_order_pda to returning close_insert_indices
  */
 async function simulateShortStopLoss(mint, sellTokenAmount, stopLossPrice, lastPrice = null, ordersData = null, borrowFee = null, initialVirtualSol = null, initialVirtualToken = null) {
     try {
@@ -452,12 +452,12 @@ async function simulateShortStopLoss(mint, sellTokenAmount, stopLossPrice, lastP
             throw new Error('Missing required parameters');
         }
 
-        // 如果没有传入 borrowFee 或池子参数，从链上一次性获取
+        // If borrowFee or pool parameters are not provided, fetch them from the chain in a single call
         if (borrowFee === null || initialVirtualSol === null || initialVirtualToken === null) {
             const curveAccount = await this.sdk.chain.getCurveAccount(mint, { skipBalances: true });
             if (borrowFee === null) borrowFee = curveAccount.borrowFee;
-            // 链上返回的是 u64 原始单位（lamports/最小单位），需要除以 10^9 转为人类可读单位
-            // 与 calcLiq.js 中的转换方式一致
+            // The chain returns u64 raw units (lamports/smallest unit), which need to be divided by 10^9 to convert to human-readable units
+            // Consistent with the conversion method in calcLiq.js
             if (initialVirtualSol === null) initialVirtualSol = new Decimal(curveAccount.initialVirtualSol.toString()).div(CurveAMM.SOL_PRECISION_FACTOR_DECIMAL).toString();
             if (initialVirtualToken === null) initialVirtualToken = new Decimal(curveAccount.initialVirtualToken.toString()).div(CurveAMM.TOKEN_PRECISION_FACTOR_DECIMAL).toString();
         }
@@ -508,7 +508,7 @@ async function simulateShortStopLoss(mint, sellTokenAmount, stopLossPrice, lastP
         let finalOverlapResult = null; // Record final overlap result
         let finalTradeAmount = 0n; // Record final trade amount
 
-        // 检查并调整止损价格以满足最小距离要求 (做空: 止损价必须高于当前价至少 MIN_STOP_LOSS_PERCENT)
+        // Check and adjust the stop loss price to meet the minimum distance requirement (short: stop loss price must be above current price by at least MIN_STOP_LOSS_PERCENT)
         // Check and adjust stop loss price to meet minimum distance requirement (short: stop loss must be above current price by at least MIN_STOP_LOSS_PERCENT)
         const minAllowedStopLoss = currentPrice + (currentPrice * BigInt(MIN_STOP_LOSS_PERCENT)) / 1000n;
         if (stopLossStartPrice < minAllowedStopLoss) {
@@ -543,33 +543,33 @@ async function simulateShortStopLoss(mint, sellTokenAmount, stopLossPrice, lastP
             }
 
             stopLossEndPrice = tradeResult[0]; // Price after trade completion
-            const tradeAmount = tradeResult[1]; // SOL输入量 / SOL input amount
+            const tradeAmount = tradeResult[1]; // SOL input amount
 
             // console.log(`  - stopLossEndPrice: ${stopLossEndPrice.toString()}`);
             // console.log(`  - tradeAmount: ${tradeAmount.toString()}`);
 
-            //console.log(`迭代 ${iteration}: 起始价格=${stopLossStartPrice}, 结束价格=${stopLossEndPrice}, SOL输入量=${tradeAmount} / Iteration ${iteration}: Start=${stopLossStartPrice}, End=${stopLossEndPrice}, SOL input=${tradeAmount}`);
+            //console.log(`Iteration ${iteration}: startPrice=${stopLossStartPrice}, endPrice=${stopLossEndPrice}, SOL input=${tradeAmount} / Iteration ${iteration}: Start=${stopLossStartPrice}, End=${stopLossEndPrice}, SOL input=${tradeAmount}`);
 
-            // 检查价格区间重叠 / Check price range overlap
+            // Check price range overlap
             const overlapResult = checkPriceRangeOverlap('up_orders', upOrders, stopLossStartPrice, stopLossEndPrice);
-            
+
             if (overlapResult.no_overlap) {
                 //console.log(' / No price range overlap, can execute');
-                finalOverlapResult = overlapResult; // 记录最终的overlap结果 / Record final overlap result
-                finalTradeAmount = tradeAmount; // 记录最终的交易金额 / Record final trade amount
+                finalOverlapResult = overlapResult; // Record final overlap result
+                finalTradeAmount = tradeAmount; // Record final trade amount
                 break;
             }
 
-            //console.log(`发现重叠: ${overlapResult.overlap_reason} / Found overlap: ${overlapResult.overlap_reason}`);
+            //console.log(`Found overlap: ${overlapResult.overlap_reason} / Found overlap: ${overlapResult.overlap_reason}`);
 
-            // 调整起始价格（增加0.5%）/ Adjust start price (increase by 0.5%)
-            // 使用方案2：直接计算 0.5% = 5/1000
+            // Adjust start price (increase by 0.5%)
+            // Using approach 2: directly compute 0.5% = 5/1000
             const adjustmentAmount = (stopLossStartPrice * BigInt(PRICE_ADJUSTMENT_PERCENTAGE)) / 1000n;
             stopLossStartPrice = stopLossStartPrice + adjustmentAmount;
 
-            //console.log(`调整后起始价格: ${stopLossStartPrice} / Adjusted start price: ${stopLossStartPrice}`);
+            //console.log(`Adjusted start price: ${stopLossStartPrice} / Adjusted start price: ${stopLossStartPrice}`);
 
-            // 安全检查：确保价格不会超过最大值 / Safety check: ensure price doesn't exceed maximum
+            // Safety check: ensure the price does not exceed the maximum
             if (stopLossStartPrice >= CurveAMM.MAX_U128_PRICE) {
                 throw new Error(`Stop loss price exceeded maximum after adjustment: ${stopLossStartPrice} >= ${CurveAMM.MAX_U128_PRICE}`);
             }
@@ -579,34 +579,34 @@ async function simulateShortStopLoss(mint, sellTokenAmount, stopLossPrice, lastP
             throw new Error('达到最大迭代次数，无法找到合适的止损价格 / Reached maximum iterations, cannot find suitable stop loss price');
         }
 
-        // 计算最终返回值 / Calculate final return values
+        // Calculate final return values
         const executableStopLossPrice = stopLossStartPrice;
-        
-        // 计算止损百分比 / Calculate stop loss percentage
+
+        // Calculate stop loss percentage
         // For short position, stop loss price is higher than current price, so it's a positive percentage
         const stopLossPercentage = Number((BigInt(10000) * (executableStopLossPrice - currentPrice)) / currentPrice) / 100;
-        
-        // 计算杠杆比例 / Calculate leverage ratio
+
+        // Calculate leverage ratio
         // For short position, leverage = current price / (stop loss price - current price)
         const leverage = Number((BigInt(10000) * currentPrice) / (executableStopLossPrice - currentPrice)) / 10000;
 
-        // 计算保证金 / Calculate margin requirement
-        // 与合约公式一致 (long_short.rs 第890-894行):
+        // Calculate margin requirement
+        // Consistent with the contract formula (long_short.rs lines 890-894):
         //   real_margin_sol = close_buy_sol_with_fee - output_sol - fee_sol
-        //   其中 output_sol 是扣费后净SOL, fee_sol 是开仓手续费
-        //   展开: real_margin_sol = close_buy_sol_with_fee - raw_sell_sol
+        //   where output_sol is the net SOL after fees, and fee_sol is the open fee
+        //   expanded: real_margin_sol = close_buy_sol_with_fee - raw_sell_sol
         let estimatedMargin = 0n;
-        let rawSellSol = 0n; // 卖出 token 获得的原始 SOL（未扣费），供调用方计算 minSolOutput
+        let rawSellSol = 0n; // Raw SOL obtained from selling tokens (before fees), for the caller to compute minSolOutput
         try {
-            // 1. 计算从当前价格卖出代币获得的原始SOL（未扣费）
+            // 1. Calculate the raw SOL (before fees) obtained from selling tokens at the current price
             const sellResult = CurveAMM.sellFromPriceWithTokenInputWithParams(currentPrice, sellTokenAmount, initialVirtualSol, initialVirtualToken);
             if (sellResult) {
-                rawSellSol = sellResult[1]; // 卖出获得的原始SOL（未扣费）
+                rawSellSol = sellResult[1]; // Raw SOL obtained from the sale (before fees)
 
-                // 2. 计算平仓成本（含手续费，使用 ceiling 除法与合约一致）
+                // 2. Calculate the close cost (including fees, using ceiling division to match the contract)
                 const closeCostWithFee = CurveAMM.calculateTotalAmountWithFee(finalTradeAmount, borrowFee);
 
-                // 3. 保证金 = 平仓成本（含费） - 原始卖出SOL
+                // 3. Margin = close cost (including fee) - raw sell SOL
                 if (closeCostWithFee !== null && closeCostWithFee > rawSellSol) {
                     estimatedMargin = closeCostWithFee - rawSellSol;
                 }
@@ -625,7 +625,7 @@ async function simulateShortStopLoss(mint, sellTokenAmount, stopLossPrice, lastP
 
         return {
             executableStopLossPrice: executableStopLossPrice, // Calculated reasonable stop loss value
-            tradeAmount: finalTradeAmount, // SOL input amount (平仓时买回 token 需要的 SOL)
+            tradeAmount: finalTradeAmount, // SOL input amount (SOL needed to buy back tokens at close)
             stopLossPercentage: stopLossPercentage, // Stop loss percentage relative to current price
             leverage: leverage, // Leverage ratio
             currentPrice: currentPrice, // Current price
@@ -633,7 +633,7 @@ async function simulateShortStopLoss(mint, sellTokenAmount, stopLossPrice, lastP
             originalStopLossPrice: BigInt(stopLossPrice), // Original stop loss price
             close_insert_indices: finalOverlapResult.close_insert_indices, // Candidate insertion indices for closing order
             estimatedMargin: estimatedMargin, // Estimated margin requirement in SOL (lamports)
-            rawSellSol: rawSellSol // 卖出 token 获得的原始 SOL（未扣费），用于调用方计算 minSolOutput
+            rawSellSol: rawSellSol // Raw SOL obtained from selling tokens (before fees), used by the caller to compute minSolOutput
         };
 
     } catch (error) {
@@ -653,54 +653,54 @@ async function simulateShortStopLoss(mint, sellTokenAmount, stopLossPrice, lastP
 /**
  * Simulate long position stop loss calculation with SOL amount input
  *
- * 基于 SOL 金额的做多止损计算。该函数会自动计算出对应的代币数量,
- * 使得保证金需求接近用户输入的 SOL 金额。
+ * SOL-amount-based stop loss calculation for a long position. This function automatically computes the corresponding token amount,
+ * so that the margin requirement is close to the SOL amount provided by the user.
  *
- * @param {string} mint - Token address / 代币地址
- * @param {bigint|string|number} buySolAmount - SOL amount to spend for long position (u64 format, lamports) / 做多投入的SOL金额 (u64格式, lamports)
- * @param {bigint|string|number} stopLossPrice - User desired stop loss price (u128 format) / 用户期望的止损价格 (u128格式)
- * @param {Object|null} lastPrice - Token info, default null / 代币当前价格信息,默认null会自动获取
- * @param {Object|null} ordersData - Orders data, default null / 订单数据,默认null会自动获取
- * @param {number} borrowFee - Borrow fee rate, default 2000 (2000/100000 = 0.02%) / 借贷手续费率,默认2000 (2000/100000 = 0.02%)
+ * @param {string} mint - Token address
+ * @param {bigint|string|number} buySolAmount - SOL amount to spend for long position (u64 format, lamports)
+ * @param {bigint|string|number} stopLossPrice - User desired stop loss price (u128 format)
+ * @param {Object|null} lastPrice - Token info, default null (auto-fetched if null)
+ * @param {Object|null} ordersData - Orders data, default null (auto-fetched if null)
+ * @param {number} borrowFee - Borrow fee rate, default 2000 (2000/100000 = 0.02%)
  *
- * @returns {Promise<Object>} Stop loss analysis result / 止损分析结果对象
- * @returns {bigint} returns.executableStopLossPrice - 可执行止损价格 (u128格式) - 同 {@link simulateLongStopLoss}
- * @returns {bigint} returns.tradeAmount - 止损时预计卖出获得的SOL数量 (lamports) - 同 {@link simulateLongStopLoss}
- * @returns {number} returns.stopLossPercentage - 止损百分比 - 同 {@link simulateLongStopLoss}
- * @returns {number} returns.leverage - 杠杆倍数 - 同 {@link simulateLongStopLoss}
- * @returns {bigint} returns.currentPrice - 当前价格 (u128格式) - 同 {@link simulateLongStopLoss}
- * @returns {number} returns.iterations - 价格调整迭代次数 - 同 {@link simulateLongStopLoss}
- * @returns {bigint} returns.originalStopLossPrice - 原始止损价格 (u128格式) - 同 {@link simulateLongStopLoss}
- * @returns {number[]} returns.close_insert_indices - 平仓订单插入位置的候选索引数组 ⭐ - 同 {@link simulateLongStopLoss}
- * @returns {bigint} returns.estimatedMargin - 预估所需保证金 (SOL lamports) - 同 {@link simulateLongStopLoss}
- * @returns {bigint} returns.buyTokenAmount - 计算出的买入代币数量 ⭐ 额外字段
- *   - 这是根据 buySolAmount 反向计算出的代币数量
- *   - 使得 estimatedMargin 接近 buySolAmount
- *   - 可以直接用于 sdk.trading.long() 的 buyTokenAmount 参数
- * @returns {number} returns.adjustmentIterations - 代币数量调整迭代次数 ⭐ 额外字段
- *   - 二分查找算法调整代币数量的迭代次数
- *   - 用于评估计算精度
+ * @returns {Promise<Object>} Stop loss analysis result
+ * @returns {bigint} returns.executableStopLossPrice - Executable stop loss price (u128 format) - same as {@link simulateLongStopLoss}
+ * @returns {bigint} returns.tradeAmount - Estimated SOL amount obtained from selling at stop loss (lamports) - same as {@link simulateLongStopLoss}
+ * @returns {number} returns.stopLossPercentage - Stop loss percentage - same as {@link simulateLongStopLoss}
+ * @returns {number} returns.leverage - Leverage ratio - same as {@link simulateLongStopLoss}
+ * @returns {bigint} returns.currentPrice - Current price (u128 format) - same as {@link simulateLongStopLoss}
+ * @returns {number} returns.iterations - Number of price adjustment iterations - same as {@link simulateLongStopLoss}
+ * @returns {bigint} returns.originalStopLossPrice - Original stop loss price (u128 format) - same as {@link simulateLongStopLoss}
+ * @returns {number[]} returns.close_insert_indices - Candidate index array for the closing order insertion position ⭐ - same as {@link simulateLongStopLoss}
+ * @returns {bigint} returns.estimatedMargin - Estimated required margin (SOL lamports) - same as {@link simulateLongStopLoss}
+ * @returns {bigint} returns.buyTokenAmount - Calculated token amount to buy ⭐ Additional field
+ *   - This is the token amount reverse-calculated from buySolAmount
+ *   - Such that estimatedMargin is close to buySolAmount
+ *   - Can be used directly as the buyTokenAmount parameter of sdk.trading.long()
+ * @returns {number} returns.adjustmentIterations - Number of token amount adjustment iterations ⭐ Additional field
+ *   - The number of iterations the binary search algorithm used to adjust the token amount
+ *   - Used to assess calculation precision
  *
- * @throws {Error} 当缺少必需参数时
- * @throws {Error} 当无法获取价格或订单数据时
- * @throws {Error} 当无法计算代币数量时
+ * @throws {Error} When required parameters are missing
+ * @throws {Error} When price or orders data cannot be fetched
+ * @throws {Error} When the token amount cannot be calculated
  *
  * @example
- * // 基础用法: 投入 0.1 SOL 做多,止损价格为当前价格的97%
+ * // Basic usage: spend 0.1 SOL to go long, stop loss price at 97% of the current price
  * const result = await sdk.simulator.simulateLongSolStopLoss(
  *   '4Kq51Kt48FCwdo5CeKjRVPodH1ticHa7mZ5n5gqMEy1X',  // mint
- *   100000000n,                                        // 0.1 SOL (精度10^9)
- *   BigInt('97000000000000000000')                     // 止损价格
+ *   100000000n,                                        // 0.1 SOL (precision 10^9)
+ *   BigInt('97000000000000000000')                     // stop loss price
  * );
  *
- * console.log(`买入代币数量: ${result.buyTokenAmount}`);
- * console.log(`预估保证金: ${result.estimatedMargin} lamports`);
- * console.log(`插入位置索引: ${result.close_insert_indices}`);
+ * console.log(`Token amount to buy: ${result.buyTokenAmount}`);
+ * console.log(`Estimated margin: ${result.estimatedMargin} lamports`);
+ * console.log(`Insert position indices: ${result.close_insert_indices}`);
  *
- * @see {@link simulateLongStopLoss} 基于代币数量的做多止损计算
- * @see {@link simulateShortSolStopLoss} 基于SOL金额的做空止损计算
+ * @see {@link simulateLongStopLoss} Token-amount-based stop loss calculation for long positions
+ * @see {@link simulateShortSolStopLoss} SOL-amount-based stop loss calculation for short positions
  * @since 2.0.0
- * @version 2.0.0 - 从返回 prev_order_pda/next_order_pda 改为返回 close_insert_indices
+ * @version 2.0.0 - Changed from returning prev_order_pda/next_order_pda to returning close_insert_indices
  */
 async function simulateLongSolStopLoss(mint, buySolAmount, stopLossPrice, lastPrice = null, ordersData = null, borrowFee = null, initialVirtualSol = null, initialVirtualToken = null, curveAccount = null) {
     try {
@@ -709,7 +709,7 @@ async function simulateLongSolStopLoss(mint, buySolAmount, stopLossPrice, lastPr
             throw new Error('Missing required parameters');
         }
 
-        // 如果没有传入 borrowFee 或池子参数，从链上一次性获取（支持外部传入 curveAccount 避免重复 RPC）
+        // If borrowFee or pool parameters are not provided, fetch them from the chain in a single call (supports passing in curveAccount externally to avoid duplicate RPC)
         if (borrowFee === null || initialVirtualSol === null || initialVirtualToken === null) {
             if (!curveAccount) {
                 curveAccount = await this.sdk.chain.getCurveAccount(mint, { skipBalances: true });
@@ -750,70 +750,70 @@ async function simulateLongSolStopLoss(mint, buySolAmount, stopLossPrice, lastPr
         let iterations = 0;
         const maxIterations = 50;
 
-        // 根据杠杆倍数动态计算二分查找上界
-        // 高杠杆(如20x)时止损距离小，每个代币的保证金贡献小，需要更多代币才能消耗完保证金
+        // Dynamically compute the binary search upper bound based on the leverage ratio
+        // At high leverage (e.g. 20x) the stop loss distance is small, each token contributes little margin, so more tokens are needed to consume the full margin
         // Calculate dynamic binary search upper bound based on leverage
         const stopLossPriceBigInt = BigInt(stopLossPrice);
         const priceDiff = currentPrice - stopLossPriceBigInt;
         const estimatedLeverage = priceDiff > 0n ? Number(currentPrice * 10000n / priceDiff) / 10000 : 10;
-        const safeMultiplier = BigInt(Math.ceil(estimatedLeverage * 3)); // 3倍安全系数
-        const multiplier = safeMultiplier > 10n ? safeMultiplier : 10n; // 最小10倍
+        const safeMultiplier = BigInt(Math.ceil(estimatedLeverage * 3)); // 3x safety factor
+        const multiplier = safeMultiplier > 10n ? safeMultiplier : 10n; // minimum 10x
 
-        // 使用二分查找算法找到 estimatedMargin < buySolAmount 的最大值
+        // Use a binary search algorithm to find the maximum estimatedMargin that is less than buySolAmount
         // Use binary search algorithm to find maximum estimatedMargin that is less than buySolAmount
-        let left = 1n; // 最小值，确保有一个有效的下界
-        let right = buyTokenAmount * multiplier; // 上界：根据杠杆动态计算
+        let left = 1n; // minimum value, ensuring a valid lower bound
+        let right = buyTokenAmount * multiplier; // upper bound: dynamically computed based on leverage
         let bestResult = null;
-        let bestMargin = 0n; // 记录最大的合法 estimatedMargin
+        let bestMargin = 0n; // record the maximum valid estimatedMargin
         let bestTokenAmount = buyTokenAmount;
-        
-        // 二分查找主循环：寻找 estimatedMargin < buySolAmount 的最大值
+
+        // Binary search main loop: find the maximum estimatedMargin that is less than buySolAmount
         while (iterations < maxIterations && left <= right) {
             const mid = (left + right) / 2n;
-            
-            // 计算当前 token 数量的结果
+
+            // Calculate the result for the current token amount
             const currentResult = await simulateLongStopLoss.call(this, mint, mid, stopLossPrice, lastPrice, ordersData, borrowFee, initialVirtualSol, initialVirtualToken);
             const currentMargin = currentResult.estimatedMargin;
-            
+
             //console.log(`Binary search iteration ${iterations}: tokenAmount=${mid}, estimatedMargin=${currentMargin}, target=${buySolAmount}`);
-            
-            // 只考虑 estimatedMargin < buySolAmount 的情况
+
+            // Only consider the case where estimatedMargin < buySolAmount
             if (currentMargin < BigInt(buySolAmount)) {
-                // 这是一个合法的解，检查是否比当前最佳解更好
+                // This is a valid solution, check whether it is better than the current best solution
                 if (currentMargin > bestMargin) {
                     bestMargin = currentMargin;
                     bestResult = currentResult;
                     bestTokenAmount = mid;
                     //console.log(`Found better solution: estimatedMargin=${currentMargin}, tokenAmount=${mid}`);
                 }
-                
-                // 如果差距已经很小（距离目标值小于10000000 lamports），可以提前退出
+
+                // If the gap is already very small (within 10000000 lamports of the target), we can exit early
                 if (BigInt(buySolAmount) - currentMargin <= 10000000n) {
                     //console.log(`Found optimal solution: estimatedMargin=${currentMargin}, diff=${BigInt(buySolAmount) - currentMargin} (< 10000000 lamports tolerance)`);
                     break;
                 }
-                
-                // 继续向右搜索，寻找更大的合法值
+
+                // Continue searching to the right for a larger valid value
                 left = mid + 1n;
             } else {
-                // estimatedMargin >= buySolAmount，需要减少 tokenAmount
+                // estimatedMargin >= buySolAmount, need to reduce tokenAmount
                 //console.log(`estimatedMargin too large (${currentMargin} >= ${buySolAmount}), searching left`);
                 right = mid - 1n;
             }
-            
+
             iterations++;
         }
-        
-        // 确保找到的结果满足要求
+
+        // Ensure the found result meets the requirement
         if (bestResult && bestMargin < BigInt(buySolAmount)) {
             stopLossResult = bestResult;
             buyTokenAmount = bestTokenAmount;
             //console.log(`Binary search completed: best tokenAmount=${bestTokenAmount}, estimatedMargin=${bestMargin}, target=${buySolAmount}`);
         } else {
-            // 如果没有找到合法解，使用一个很小的 tokenAmount 作为安全回退
+            // If no valid solution is found, use a very small tokenAmount as a safe fallback
             //console.log(`No valid solution found (estimatedMargin < buySolAmount), using minimal tokenAmount`);
-            buyTokenAmount = buyTokenAmount / 10n; // 使用更小的值
-            if (buyTokenAmount <= 0n) buyTokenAmount = 1000000000n; // 最小值保护 (0.001 token with 9 decimals)
+            buyTokenAmount = buyTokenAmount / 10n; // use a smaller value
+            if (buyTokenAmount <= 0n) buyTokenAmount = 1000000000n; // minimum value protection (0.001 token with 9 decimals)
             stopLossResult = await simulateLongStopLoss.call(this, mint, buyTokenAmount, stopLossPrice, lastPrice, ordersData, borrowFee, initialVirtualSol, initialVirtualToken);
         }
 
@@ -837,54 +837,54 @@ async function simulateLongSolStopLoss(mint, buySolAmount, stopLossPrice, lastPr
 /**
  * Simulate short position stop loss calculation with SOL amount input
  *
- * 基于 SOL 金额的做空止损计算。该函数会自动计算出对应的代币数量,
- * 使得保证金需求接近用户输入的 SOL 金额。
+ * SOL-amount-based stop loss calculation for a short position. This function automatically computes the corresponding token amount,
+ * so that the margin requirement is close to the SOL amount provided by the user.
  *
- * @param {string} mint - Token address / 代币地址
- * @param {bigint|string|number} sellSolAmount - SOL amount needed for short position stop loss (u64 format, lamports) / 做空投入的SOL金额 (u64格式, lamports)
- * @param {bigint|string|number} stopLossPrice - User desired stop loss price (u128 format) / 用户期望的止损价格 (u128格式)
- * @param {Object|null} lastPrice - Token info, default null / 代币当前价格信息,默认null会自动获取
- * @param {Object|null} ordersData - Orders data, default null / 订单数据,默认null会自动获取
- * @param {number} borrowFee - Borrow fee rate, default 2000 (2000/100000 = 0.02%) / 借贷手续费率,默认2000 (2000/100000 = 0.02%)
+ * @param {string} mint - Token address
+ * @param {bigint|string|number} sellSolAmount - SOL amount needed for short position stop loss (u64 format, lamports)
+ * @param {bigint|string|number} stopLossPrice - User desired stop loss price (u128 format)
+ * @param {Object|null} lastPrice - Token info, default null (auto-fetched if null)
+ * @param {Object|null} ordersData - Orders data, default null (auto-fetched if null)
+ * @param {number} borrowFee - Borrow fee rate, default 2000 (2000/100000 = 0.02%)
  *
- * @returns {Promise<Object>} Stop loss analysis result / 止损分析结果对象
- * @returns {bigint} returns.executableStopLossPrice - 可执行止损价格 (u128格式) - 同 {@link simulateShortStopLoss}
- * @returns {bigint} returns.tradeAmount - 止损时预计买入需要的SOL数量 (lamports) - 同 {@link simulateShortStopLoss}
- * @returns {number} returns.stopLossPercentage - 止损百分比 - 同 {@link simulateShortStopLoss}
- * @returns {number} returns.leverage - 杠杆倍数 - 同 {@link simulateShortStopLoss}
- * @returns {bigint} returns.currentPrice - 当前价格 (u128格式) - 同 {@link simulateShortStopLoss}
- * @returns {number} returns.iterations - 价格调整迭代次数 - 同 {@link simulateShortStopLoss}
- * @returns {bigint} returns.originalStopLossPrice - 原始止损价格 (u128格式) - 同 {@link simulateShortStopLoss}
- * @returns {number[]} returns.close_insert_indices - 平仓订单插入位置的候选索引数组 ⭐ - 同 {@link simulateShortStopLoss}
- * @returns {bigint} returns.estimatedMargin - 预估所需保证金 (SOL lamports) - 同 {@link simulateShortStopLoss}
- * @returns {bigint} returns.sellTokenAmount - 计算出的卖出代币数量 ⭐ 额外字段
- *   - 这是根据 sellSolAmount 反向计算出的代币数量
- *   - 使得 estimatedMargin 接近 sellSolAmount
- *   - 可以直接用于 sdk.trading.short() 的 borrowSellTokenAmount 参数
- * @returns {number} returns.adjustmentIterations - 代币数量调整迭代次数 ⭐ 额外字段
- *   - 二分查找算法调整代币数量的迭代次数
- *   - 用于评估计算精度
+ * @returns {Promise<Object>} Stop loss analysis result
+ * @returns {bigint} returns.executableStopLossPrice - Executable stop loss price (u128 format) - same as {@link simulateShortStopLoss}
+ * @returns {bigint} returns.tradeAmount - Estimated SOL amount needed to buy at stop loss (lamports) - same as {@link simulateShortStopLoss}
+ * @returns {number} returns.stopLossPercentage - Stop loss percentage - same as {@link simulateShortStopLoss}
+ * @returns {number} returns.leverage - Leverage ratio - same as {@link simulateShortStopLoss}
+ * @returns {bigint} returns.currentPrice - Current price (u128 format) - same as {@link simulateShortStopLoss}
+ * @returns {number} returns.iterations - Number of price adjustment iterations - same as {@link simulateShortStopLoss}
+ * @returns {bigint} returns.originalStopLossPrice - Original stop loss price (u128 format) - same as {@link simulateShortStopLoss}
+ * @returns {number[]} returns.close_insert_indices - Candidate index array for the closing order insertion position ⭐ - same as {@link simulateShortStopLoss}
+ * @returns {bigint} returns.estimatedMargin - Estimated required margin (SOL lamports) - same as {@link simulateShortStopLoss}
+ * @returns {bigint} returns.sellTokenAmount - Calculated token amount to sell ⭐ Additional field
+ *   - This is the token amount reverse-calculated from sellSolAmount
+ *   - Such that estimatedMargin is close to sellSolAmount
+ *   - Can be used directly as the borrowSellTokenAmount parameter of sdk.trading.short()
+ * @returns {number} returns.adjustmentIterations - Number of token amount adjustment iterations ⭐ Additional field
+ *   - The number of iterations the binary search algorithm used to adjust the token amount
+ *   - Used to assess calculation precision
  *
- * @throws {Error} 当缺少必需参数时
- * @throws {Error} 当无法获取价格或订单数据时
- * @throws {Error} 当无法计算代币数量时
+ * @throws {Error} When required parameters are missing
+ * @throws {Error} When price or orders data cannot be fetched
+ * @throws {Error} When the token amount cannot be calculated
  *
  * @example
- * // 基础用法: 投入 0.1 SOL 做空,止损价格为当前价格的103%
+ * // Basic usage: spend 0.1 SOL to go short, stop loss price at 103% of the current price
  * const result = await sdk.simulator.simulateShortSolStopLoss(
  *   '4Kq51Kt48FCwdo5CeKjRVPodH1ticHa7mZ5n5gqMEy1X',  // mint
- *   100000000n,                                        // 0.1 SOL (精度10^9)
- *   BigInt('103000000000000000000')                    // 止损价格
+ *   100000000n,                                        // 0.1 SOL (precision 10^9)
+ *   BigInt('103000000000000000000')                    // stop loss price
  * );
  *
- * console.log(`卖出代币数量: ${result.sellTokenAmount}`);
- * console.log(`预估保证金: ${result.estimatedMargin} lamports`);
- * console.log(`插入位置索引: ${result.close_insert_indices}`);
+ * console.log(`Token amount to sell: ${result.sellTokenAmount}`);
+ * console.log(`Estimated margin: ${result.estimatedMargin} lamports`);
+ * console.log(`Insert position indices: ${result.close_insert_indices}`);
  *
- * @see {@link simulateShortStopLoss} 基于代币数量的做空止损计算
- * @see {@link simulateLongSolStopLoss} 基于SOL金额的做多止损计算
+ * @see {@link simulateShortStopLoss} Token-amount-based stop loss calculation for short positions
+ * @see {@link simulateLongSolStopLoss} SOL-amount-based stop loss calculation for long positions
  * @since 2.0.0
- * @version 2.0.0 - 从返回 prev_order_pda/next_order_pda 改为返回 close_insert_indices
+ * @version 2.0.0 - Changed from returning prev_order_pda/next_order_pda to returning close_insert_indices
  */
 async function simulateShortSolStopLoss(mint, sellSolAmount, stopLossPrice, lastPrice = null, ordersData = null, borrowFee = null, initialVirtualSol = null, initialVirtualToken = null, curveAccount = null) {
     try {
@@ -893,7 +893,7 @@ async function simulateShortSolStopLoss(mint, sellSolAmount, stopLossPrice, last
             throw new Error('Missing required parameters');
         }
 
-        // 如果没有传入 borrowFee 或池子参数，从链上一次性获取（支持外部传入 curveAccount 避免重复 RPC）
+        // If borrowFee or pool parameters are not provided, fetch them from the chain in a single call (supports passing in curveAccount externally to avoid duplicate RPC)
         if (borrowFee === null || initialVirtualSol === null || initialVirtualToken === null) {
             if (!curveAccount) {
                 curveAccount = await this.sdk.chain.getCurveAccount(mint, { skipBalances: true });
@@ -936,70 +936,70 @@ async function simulateShortSolStopLoss(mint, sellSolAmount, stopLossPrice, last
         let iterations = 0;
         const maxIterations = 50;
 
-        // 根据杠杆倍数动态计算二分查找上界
-        // 高杠杆(如20x)时止损距离小，每个代币的保证金贡献小，需要更多代币才能消耗完保证金
+        // Dynamically compute the binary search upper bound based on the leverage ratio
+        // At high leverage (e.g. 20x) the stop loss distance is small, each token contributes little margin, so more tokens are needed to consume the full margin
         // Calculate dynamic binary search upper bound based on leverage
         const stopLossPriceBigInt = BigInt(stopLossPrice);
         const priceDiff = stopLossPriceBigInt - currentPrice;
         const estimatedLeverage = priceDiff > 0n ? Number(currentPrice * 10000n / priceDiff) / 10000 : 10;
-        const safeMultiplier = BigInt(Math.ceil(estimatedLeverage * 3)); // 3倍安全系数
-        const multiplier = safeMultiplier > 10n ? safeMultiplier : 10n; // 最小10倍
+        const safeMultiplier = BigInt(Math.ceil(estimatedLeverage * 3)); // 3x safety factor
+        const multiplier = safeMultiplier > 10n ? safeMultiplier : 10n; // minimum 10x
 
-        // 使用二分查找算法找到 estimatedMargin < sellSolAmount 的最大值
+        // Use a binary search algorithm to find the maximum estimatedMargin that is less than sellSolAmount
         // Use binary search algorithm to find maximum estimatedMargin that is less than sellSolAmount
-        let left = 1n; // 最小值，确保有一个有效的下界
-        let right = sellTokenAmount * multiplier; // 上界：根据杠杆动态计算
+        let left = 1n; // minimum value, ensuring a valid lower bound
+        let right = sellTokenAmount * multiplier; // upper bound: dynamically computed based on leverage
         let bestResult = null;
-        let bestMargin = 0n; // 记录最大的合法 estimatedMargin
+        let bestMargin = 0n; // record the maximum valid estimatedMargin
         let bestTokenAmount = sellTokenAmount;
-        
-        // 二分查找主循环：寻找 estimatedMargin < sellSolAmount 的最大值
+
+        // Binary search main loop: find the maximum estimatedMargin that is less than sellSolAmount
         while (iterations < maxIterations && left <= right) {
             const mid = (left + right) / 2n;
-            
-            // 计算当前 token 数量的结果
+
+            // Calculate the result for the current token amount
             const currentResult = await simulateShortStopLoss.call(this, mint, mid, stopLossPrice, lastPrice, ordersData, borrowFee, initialVirtualSol, initialVirtualToken);
             const currentMargin = currentResult.estimatedMargin;
-            
+
             //console.log(`Binary search iteration ${iterations}: tokenAmount=${mid}, estimatedMargin=${currentMargin}, target=${sellSolAmount}`);
-            
-            // 只考虑 estimatedMargin < sellSolAmount 的情况
+
+            // Only consider the case where estimatedMargin < sellSolAmount
             if (currentMargin < BigInt(sellSolAmount)) {
-                // 这是一个合法的解，检查是否比当前最佳解更好
+                // This is a valid solution, check whether it is better than the current best solution
                 if (currentMargin > bestMargin) {
                     bestMargin = currentMargin;
                     bestResult = currentResult;
                     bestTokenAmount = mid;
                     //console.log(`Found better solution: estimatedMargin=${currentMargin}, tokenAmount=${mid}`);
                 }
-                
-                // 如果差距已经很小（距离目标值小于10000000 lamports），可以提前退出
+
+                // If the gap is already very small (within 10000000 lamports of the target), we can exit early
                 if (BigInt(sellSolAmount) - currentMargin <= 10000000n) {
                     //console.log(`Found optimal solution: estimatedMargin=${currentMargin}, diff=${BigInt(sellSolAmount) - currentMargin} (< 10000000 lamports tolerance)`);
                     break;
                 }
-                
-                // 继续向右搜索，寻找更大的合法值
+
+                // Continue searching to the right for a larger valid value
                 left = mid + 1n;
             } else {
-                // estimatedMargin >= sellSolAmount，需要减少 tokenAmount
+                // estimatedMargin >= sellSolAmount, need to reduce tokenAmount
                 //console.log(`estimatedMargin too large (${currentMargin} >= ${sellSolAmount}), searching left`);
                 right = mid - 1n;
             }
-            
+
             iterations++;
         }
-        
-        // 确保找到的结果满足要求
+
+        // Ensure the found result meets the requirement
         if (bestResult && bestMargin < BigInt(sellSolAmount)) {
             stopLossResult = bestResult;
             sellTokenAmount = bestTokenAmount;
             //console.log(`Binary search completed: best tokenAmount=${bestTokenAmount}, estimatedMargin=${bestMargin}, target=${sellSolAmount}`);
         } else {
-            // 如果没有找到合法解，使用一个很小的 tokenAmount 作为安全回退
+            // If no valid solution is found, use a very small tokenAmount as a safe fallback
             //console.log(`No valid solution found (estimatedMargin < sellSolAmount), using minimal tokenAmount`);
-            sellTokenAmount = sellTokenAmount / 10n; // 使用更小的值
-            if (sellTokenAmount <= 0n) sellTokenAmount = 1000000000n; // 最小值保护 (0.001 token with 9 decimals)
+            sellTokenAmount = sellTokenAmount / 10n; // use a smaller value
+            if (sellTokenAmount <= 0n) sellTokenAmount = 1000000000n; // minimum value protection (0.001 token with 9 decimals)
             stopLossResult = await simulateShortStopLoss.call(this, mint, sellTokenAmount, stopLossPrice, lastPrice, ordersData, borrowFee, initialVirtualSol, initialVirtualToken);
         }