100x-sdk 1.0.2 → 1.0.4

package/src/modules/simulator/calcLiq.js

@@ -4,74 +4,63 @@ const Decimal = require('decimal.js');
 
 
 /**
- * 计算代币买入时的流动性影响 Calculate liquidity impact for token buy operations
- * 
- * 此函数分析买入操作对价格区间内流动性的影响，计算可用的自由流动性、锁定流动性，
- * 并支持跳过指定订单（将其流动性视为可用）。适用于做多订单（up_orders）场景。
+ * Calculate liquidity impact for token buy operations
+ *
  * This function analyzes the liquidity impact of buy operations within price ranges,
  * calculates available free liquidity, locked liquidity, and supports skipping specific
  * orders (treating their liquidity as available). Applicable for long orders (up_orders) scenarios.
- * 
- * @param {bigint|string|number} price - 当前代币价格，作为计算起始价格 Current token price, used as calculation start price
- * @param {bigint|string|number} buyTokenAmount - 购买的代币数量，目标买入数量 Amount of tokens to buy, target purchase amount
- * @param {Array<Object>} orders - 订单数组，按 lock_lp_start_price 从小到大排序 Array of orders sorted by lock_lp_start_price (ascending):
- *   - order_type: {number} 订单类型(1=做多,2=做空) Order type (1=long, 2=short)
- *   - mint: {string} 代币地址 Token mint address
- *   - user: {string} 用户地址 User address
- *   - lock_lp_start_price: {string} LP锁定开始价格 LP lock start price (required)
- *   - lock_lp_end_price: {string} LP锁定结束价格 LP lock end price (required)
- *   - lock_lp_sol_amount: {number} 锁定的SOL数量 Locked SOL amount (required)
- *   - lock_lp_token_amount: {number} 锁定的代币数量 Locked token amount (required)
- *   - start_time: {number} 开始时间戳 Start timestamp
- *   - end_time: {number} 结束时间戳 End timestamp
- *   - margin_sol_amount: {number} 保证金SOL数量 Margin SOL amount
- *   - borrow_amount: {number} 借贷数量 Borrow amount
- *   - position_asset_amount: {number} 持仓资产数量 Position asset amount
- *   - borrow_fee: {number} 借贷费用 Borrow fee
- *   - order_pda: {string} 订单PDA地址 Order PDA address (required for passOrder matching)
- * @param {number} onceMaxOrder - 一次处理的最大订单数，限制遍历范围 Maximum orders to process at once, limits traversal range
- * @param {string|null} passOrder - 需要跳过的订单PDA地址字符串，当该值与订单的order_pda匹配时，跳过该订单并将其流动性计入自由流动性 Order PDA address string to skip, when this value matches an order's order_pda, skip that order and count its liquidity as free liquidity
- * 
- * @returns {Object} 流动性计算结果对象，包含详细的流动性分析数据 Liquidity calculation result object with detailed liquidity analysis data:
- * 
- *   **自由流动性 Free Liquidity:**
- *   - free_lp_sol_amount_sum: {bigint} 可用自由流动性SOL总量，包含以下来源：1)价格间隙流动性 2)跳过订单的流动性 3)无限流动性（如有）
- *                                       Total available free liquidity SOL amount, includes: 1) price gap liquidity 2) skipped order liquidity 3) infinite liquidity (if any)
- *   - free_lp_token_amount_sum: {bigint} 可用自由流动性Token总量，与SOL对应，表示在不强平任何订单情况下可买到的最大代币数量
- *                                         Total available free liquidity token amount, corresponds to SOL, represents max tokens buyable without force closing any orders
- * 
- *   **锁定流动性 Locked Liquidity:**
- *   - lock_lp_sol_amount_sum: {bigint} 被锁定的流动性SOL总量，不包括跳过的订单，这部分流动性不可直接使用
- *                                       Total locked liquidity SOL amount, excludes skipped orders, this liquidity is not directly usable
- *   - lock_lp_token_amount_sum: {bigint} 被锁定的流动性Token总量，不包括跳过的订单，对应于锁定的SOL流动性
- *                                         Total locked liquidity token amount, excludes skipped orders, corresponds to locked SOL liquidity
- * 
- *   **流动性状态标识 Liquidity Status Indicators:**
- *   - has_infinite_lp: {boolean} 是否包含无限流动性，true表示订单链表已结束且计算了到最大价格(MAX_U128_PRICE)的流动性
- *                                  Whether includes infinite liquidity, true means order chain ended and liquidity to max price (MAX_U128_PRICE) was calculated
- *   - pass_order_id: {number} 被跳过的订单在数组中的索引位置，-1表示没有跳过任何订单，>=0表示跳过了对应索引的订单
- *                               Index of skipped order in array, -1 means no order skipped, >=0 means order at that index was skipped
- * 
- *   **买入执行信息 Buy Execution Info:**
- *   - force_close_num: {number} 需要强平的订单数量，表示为了买到目标数量需要强制平仓多少个订单，0表示无需强平
- *                                 Number of orders that need to be force closed, indicates how many orders need force closure to buy target amount, 0 means no force closure needed
- *   - ideal_lp_sol_amount: {bigint} 理想SOL使用量，基于当前价格使用CurveAMM直接计算的理论最小SOL需求，不考虑流动性分布
- *                                     Ideal SOL usage, theoretical minimum SOL requirement calculated directly from current price using CurveAMM, ignores liquidity distribution
- *   - real_lp_sol_amount: {bigint} 实际SOL使用量，考虑真实流动性分布的精确SOL需求。0表示当前自由流动性不足以满足买入需求，需要强平更多订单
- *                                    Actual SOL usage, precise SOL requirement considering real liquidity distribution. 0 means current free liquidity insufficient for buy requirement, need to force close more orders
- * 
- * @throws {Error} 参数验证错误：price、buyTokenAmount、orders、onceMaxOrder 参数无效 Parameter validation error: invalid price, buyTokenAmount, orders, or onceMaxOrder
- * @throws {Error} 价格转换错误：无法将价格参数转换为 BigInt Price conversion error: cannot convert price parameters to BigInt
- * @throws {Error} 流动性计算错误：CurveAMM 计算失败或数值转换错误 Liquidity calculation error: CurveAMM calculation failure or value conversion error
- * @throws {Error} 间隙流动性计算失败：价格间隙流动性计算异常 Gap liquidity calculation failure: price gap liquidity calculation exception
- * @throws {Error} 无限流动性计算失败：最大价格流动性计算异常 Infinite liquidity calculation failure: max price liquidity calculation exception
- * @throws {Error} 订单数据格式错误：订单对象缺少必需字段 Order data format error: order object missing required fields
+ *
+ * @param {bigint|string|number} price - Current token price, used as calculation start price
+ * @param {bigint|string|number} buyTokenAmount - Amount of tokens to buy, target purchase amount
+ * @param {Array<Object>} orders - Array of orders sorted by lock_lp_start_price (ascending):
+ *   - order_type: {number} Order type (1=long, 2=short)
+ *   - mint: {string} Token mint address
+ *   - user: {string} User address
+ *   - lock_lp_start_price: {string} LP lock start price (required)
+ *   - lock_lp_end_price: {string} LP lock end price (required)
+ *   - lock_lp_sol_amount: {number} Locked SOL amount (required)
+ *   - lock_lp_token_amount: {number} Locked token amount (required)
+ *   - start_time: {number} Start timestamp
+ *   - end_time: {number} End timestamp
+ *   - margin_sol_amount: {number} Margin SOL amount
+ *   - borrow_amount: {number} Borrow amount
+ *   - position_asset_amount: {number} Position asset amount
+ *   - borrow_fee: {number} Borrow fee
+ *   - order_pda: {string} Order PDA address (required for passOrder matching)
+ * @param {number} onceMaxOrder - Maximum orders to process at once, limits traversal range
+ * @param {string|null} passOrder - Order PDA address string to skip, when this value matches an order's order_pda, skip that order and count its liquidity as free liquidity
+ *
+ * @returns {Object} Liquidity calculation result object with detailed liquidity analysis data:
+ *
+ *   **Free Liquidity:**
+ *   - free_lp_sol_amount_sum: {bigint} Total available free liquidity SOL amount, includes: 1) price gap liquidity 2) skipped order liquidity 3) infinite liquidity (if any)
+ *   - free_lp_token_amount_sum: {bigint} Total available free liquidity token amount, corresponds to SOL, represents max tokens buyable without force closing any orders
+ *
+ *   **Locked Liquidity:**
+ *   - lock_lp_sol_amount_sum: {bigint} Total locked liquidity SOL amount, excludes skipped orders, this liquidity is not directly usable
+ *   - lock_lp_token_amount_sum: {bigint} Total locked liquidity token amount, excludes skipped orders, corresponds to locked SOL liquidity
+ *
+ *   **Liquidity Status Indicators:**
+ *   - has_infinite_lp: {boolean} Whether includes infinite liquidity, true means order chain ended and liquidity to max price (MAX_U128_PRICE) was calculated
+ *   - pass_order_id: {number} Index of skipped order in array, -1 means no order skipped, >=0 means order at that index was skipped
+ *
+ *   **Buy Execution Info:**
+ *   - force_close_num: {number} Number of orders that need to be force closed, indicates how many orders need force closure to buy target amount, 0 means no force closure needed
+ *   - ideal_lp_sol_amount: {bigint} Ideal SOL usage, theoretical minimum SOL requirement calculated directly from current price using CurveAMM, ignores liquidity distribution
+ *   - real_lp_sol_amount: {bigint} Actual SOL usage, precise SOL requirement considering real liquidity distribution. 0 means current free liquidity insufficient for buy requirement, need to force close more orders
+ *
+ * @throws {Error} Parameter validation error: invalid price, buyTokenAmount, orders, or onceMaxOrder
+ * @throws {Error} Price conversion error: cannot convert price parameters to BigInt
+ * @throws {Error} Liquidity calculation error: CurveAMM calculation failure or value conversion error
+ * @throws {Error} Gap liquidity calculation failure: price gap liquidity calculation exception
+ * @throws {Error} Infinite liquidity calculation failure: max price liquidity calculation exception
+ * @throws {Error} Order data format error: order object missing required fields
  */
 function calcLiqTokenBuy(price, buyTokenAmount, orders, onceMaxOrder, passOrder = null, initialVirtualSol = null, initialVirtualToken = null) {
-  // 由于是买入操作 肯定拿的是 up_orders 方向的 订单  lock_lp_start_price <  lock_lp_end_price
-  // 并且 lock_lp_start_price 在 orders 中是从小到大排序的
+  // Since this is a buy operation, the orders are definitely in the up_orders direction  lock_lp_start_price <  lock_lp_end_price
+  // And lock_lp_start_price is sorted in ascending order in orders
 
-  // 参数验证
+  // Parameter validation
   if (!price && price !== 0) {
     throw new Error('参数验证错误：price 参数不能为空 Parameter validation error: price cannot be null');
   }
@@ -89,15 +78,15 @@ function calcLiqTokenBuy(price, buyTokenAmount, orders, onceMaxOrder, passOrder
   }
 
   const result = {
-    free_lp_sol_amount_sum: 0n,  // 间隙中可使用的sol流动性数量
-    free_lp_token_amount_sum: 0n, // 间隙中可使用的token流动性数量
+    free_lp_sol_amount_sum: 0n,  // Amount of SOL liquidity usable in the gaps
+    free_lp_token_amount_sum: 0n, // Amount of token liquidity usable in the gaps
     lock_lp_sol_amount_sum: 0n,
     lock_lp_token_amount_sum: 0n,
-    has_infinite_lp: false, // 是否包含无限流动性
-    pass_order_id: -1, // 跳过的订单索引
-    force_close_num: 0, // 强平订单数量
-    ideal_lp_sol_amount: 0n, // 理想情况下买到buyTokenAmount的数量, 理想情况下使用的SOL数量
-    real_lp_sol_amount: 0n, // 要买到buyTokenAmount的数量, 实际使用的SOL数量
+    has_infinite_lp: false, // Whether includes infinite liquidity
+    pass_order_id: -1, // Index of skipped order
+    force_close_num: 0, // Number of force closed orders
+    ideal_lp_sol_amount: 0n, // Amount of SOL used to buy buyTokenAmount under ideal conditions
+    real_lp_sol_amount: 0n, // Amount of SOL actually used to buy buyTokenAmount
   }
 
 
@@ -110,7 +99,7 @@ function calcLiqTokenBuy(price, buyTokenAmount, orders, onceMaxOrder, passOrder
     throw new Error(`价格转换错误：无法将 buyTokenAmount 转换为 BigInt Price conversion error: Cannot convert buyTokenAmount to BigInt - ${error.message}`);
   }
 
-  // 声明用于跟踪前一次自由流动性总量的变量
+  // Declare variable for tracking the previous free liquidity total
   let prev_free_lp_sol_amount_sum;
 
   //result.ideal_lp_token_amount_sum = buyTokenAmountBigInt;
@@ -126,13 +115,13 @@ function calcLiqTokenBuy(price, buyTokenAmount, orders, onceMaxOrder, passOrder
       initialVirtualSolDecimal,
       initialVirtualTokenDecimal
     );
-    // console.log(`理想计算: 当前价格=${priceBigInt}, 目标代币=${buyTokenAmountBigInt}, 理想SOL=${result.ideal_lp_sol_amount}`);
+    // console.log(`ideal calculation: current price=${priceBigInt}, target token=${buyTokenAmountBigInt}, ideal SOL=${result.ideal_lp_sol_amount}`);
   } catch (error) {
     throw new Error(`buy流动性计算错误：理想流动性计算失败 Liquidity calculation error: Ideal liquidity calculation failed - ${error.message}`);
   }
 
 
-  // orders 长度为0 时要单独计算
+  // orders length of 0 requires separate calculation
   if (orders.length === 0) {
     
 
@@ -154,14 +143,14 @@ function calcLiqTokenBuy(price, buyTokenAmount, orders, onceMaxOrder, passOrder
 
 
 
-  // 选择较小值进行遍历
+  // Choose the smaller value for traversal
   const loopCount = Math.min(orders.length, onceMaxOrder);
 
   let counti = 0;
   for (let i = 0; i < loopCount; i++) {
     const order = orders[i];
 
-    // 验证订单数据格式
+    // Validate order data format
     if (!order) {
       throw new Error(`订单数据格式错误：订单 ${i} 为空 Order data format error: Order ${i} is null`);
     }
@@ -173,15 +162,15 @@ function calcLiqTokenBuy(price, buyTokenAmount, orders, onceMaxOrder, passOrder
     }
 
 
-    // 计算间隙流动性
+    // Calculate gap liquidity
     let startPrice, endPrice;
     try {
       if (i === 0) {
-        // 第一个订单：使用当前价格到订单开始价格的间隙
+        // First order: use the gap from current price to order start price
         startPrice = BigInt(price);
         endPrice = BigInt(order.lock_lp_start_price);
       } else {
-        // 后续订单：使用前一个订单结束价格到当前订单开始价格的间隙
+        // Subsequent orders: use the gap from previous order end price to current order start price
         startPrice = BigInt(orders[i - 1].lock_lp_end_price);
         endPrice = BigInt(order.lock_lp_start_price);
       }
@@ -190,7 +179,7 @@ function calcLiqTokenBuy(price, buyTokenAmount, orders, onceMaxOrder, passOrder
     }
 
 
-    // 如果存在价格间隙，计算自由流动性
+    // If a price gap exists, calculate free liquidity
     if (endPrice > startPrice) {
       try {
         const initialVirtualSolDecimal = new Decimal(initialVirtualSol).div(CurveAMM.SOL_PRECISION_FACTOR_DECIMAL);
@@ -205,30 +194,30 @@ function calcLiqTokenBuy(price, buyTokenAmount, orders, onceMaxOrder, passOrder
           const [solAmount, tokenAmount] = gapLiquidity;
 
           try {
-            prev_free_lp_sol_amount_sum = result.free_lp_sol_amount_sum; // 上次的值
+            prev_free_lp_sol_amount_sum = result.free_lp_sol_amount_sum; // Previous value
             result.free_lp_sol_amount_sum += BigInt(solAmount);
             result.free_lp_token_amount_sum += BigInt(tokenAmount);
-            // console.log(`间隙[${i}]: ${startPrice}→${endPrice}, 间隙SOL=${solAmount}, 间隙Token=${tokenAmount}, 累计自由Token=${result.free_lp_token_amount_sum}`);
+            // console.log(`gap[${i}]: ${startPrice}→${endPrice}, gap SOL=${solAmount}, gap Token=${tokenAmount}, cumulative free Token=${result.free_lp_token_amount_sum}`);
           } catch (error) {
             throw new Error(`流动性计算错误：无法转换间隙流动性数值 Liquidity calculation error: Cannot convert gap liquidity values - ${error.message}`);
           }
 
 
-          // 计算实际使用的SOL数量 到能买到为止
+          // Calculate the actual amount of SOL used, until enough can be bought
           if (result.real_lp_sol_amount === 0n) {
             if (result.free_lp_token_amount_sum > buyTokenAmountBigInt) {
-              // 这时间隙流动性已经够买入的了
-              // 计算最后精确需要买多少token
+              // At this point the gap liquidity is already enough to buy
+              // Calculate the final precise amount of token to buy
               try {
                 const actualBuyAmount = buyTokenAmountBigInt - (result.free_lp_token_amount_sum - BigInt(tokenAmount));
                 // console.log("actualBuyAmount",actualBuyAmount)
                 const [, preciseSol] = CurveAMM.buyFromPriceWithTokenOutput(startPrice, actualBuyAmount)
                 result.real_lp_sol_amount = prev_free_lp_sol_amount_sum + BigInt(preciseSol);
 
-                // console.log(`实际计算[${i}]: 自由流动性已足够, actualBuyAmount=${actualBuyAmount}, preciseSol=${preciseSol}, 实际SOL=${result.real_lp_sol_amount}`);
-                result.force_close_num = counti; // 强平订单数量
+                // console.log(`actual calculation[${i}]: free liquidity sufficient, actualBuyAmount=${actualBuyAmount}, preciseSol=${preciseSol}, actual SOL=${result.real_lp_sol_amount}`);
+                result.force_close_num = counti; // Number of force closed orders
               } catch (error) {
-                // console.log('错误详情:', error);
+                // console.log('error details:', error);
                 throw new Error(`流动性计算错误：精确SOL计算失败 Liquidity calculation error: Precise SOL calculation failed - ${error.message}`);
               }
             }
@@ -246,13 +235,13 @@ function calcLiqTokenBuy(price, buyTokenAmount, orders, onceMaxOrder, passOrder
     } else {
     }
 
-    // 检查是否需要跳过该订单（passOrder 逻辑）
+    // Check whether this order needs to be skipped (passOrder logic)
     //const shouldSkipOrder = passOrder && typeof passOrder === 'string' && order.order_pda === passOrder;
 
 
     if (passOrder == order.order_pda) {
 
-      // 将跳过订单的流动性加到自由流动性中
+      // Add the skipped order's liquidity to the free liquidity
       try {
         if (order.lock_lp_sol_amount === undefined || order.lock_lp_sol_amount === null) {
           throw new Error(`订单数据格式错误：跳过订单 ${i} 缺少 lock_lp_sol_amount Order data format error: Skipped order ${i} missing lock_lp_sol_amount`);
@@ -261,25 +250,25 @@ function calcLiqTokenBuy(price, buyTokenAmount, orders, onceMaxOrder, passOrder
           throw new Error(`订单数据格式错误：跳过订单 ${i} 缺少 lock_lp_token_amount Order data format error: Skipped order ${i} missing lock_lp_token_amount`);
         }
 
-        const prevFreeSolSum = result.free_lp_sol_amount_sum; // 保存之前的值用于计算
+        const prevFreeSolSum = result.free_lp_sol_amount_sum; // Save the previous value for calculation
         result.free_lp_sol_amount_sum += BigInt(order.lock_lp_sol_amount);
         result.free_lp_token_amount_sum += BigInt(order.lock_lp_token_amount);
 
         result.pass_order_id = i;
 
 
-        // 检查跳过订单后的自由流动性是否已满足买入需求
+        // Check whether the free liquidity after skipping the order already meets the buy requirement
         if (result.real_lp_sol_amount === 0n) {
           if (result.free_lp_token_amount_sum >= buyTokenAmountBigInt) {
-            // 自由流动性已经够买入需求了
+            // Free liquidity is already enough for the buy requirement
             try {
               //const remainingToken = result.free_lp_token_amount_sum - buyTokenAmountBigInt;
-              // 从当前价格开始计算需要多少SOL来买到精确的token数量
+              // Calculate from the current price how much SOL is needed to buy the precise token amount
               const targetPrice = i === 0 ? BigInt(price) : BigInt(orders[i - 1].lock_lp_end_price);
               const actualBuyAmount = buyTokenAmountBigInt - (result.free_lp_token_amount_sum - BigInt(order.lock_lp_token_amount));
               const [, preciseSol] = CurveAMM.buyFromPriceWithTokenOutput(targetPrice, actualBuyAmount);
               result.real_lp_sol_amount = prevFreeSolSum + BigInt(preciseSol);
-              // console.log(`实际计算[${i}]: 跳过订单后足够, targetPrice=${targetPrice}, preciseSol=${preciseSol}, 实际SOL=${result.real_lp_sol_amount}`);
+              // console.log(`actual calculation[${i}]: sufficient after skipping order, targetPrice=${targetPrice}, preciseSol=${preciseSol}, actual SOL=${result.real_lp_sol_amount}`);
               result.force_close_num = counti;
             } catch (error) {
               throw new Error(`流动性计算错误：跳过订单后精确SOL计算失败 Liquidity calculation error: Precise SOL calculation failed after skipping order - ${error.message}`);
@@ -294,7 +283,7 @@ function calcLiqTokenBuy(price, buyTokenAmount, orders, onceMaxOrder, passOrder
         throw new Error(`流动性计算错误：无法处理跳过订单 ${i} 的流动性 Liquidity calculation error: Cannot process skipped order ${i} liquidity - ${error.message}`);
       }
     } else {
-      // 累加锁定的流动性（正常情况）
+      // Accumulate locked liquidity (normal case)
       try {
         if (order.lock_lp_sol_amount === undefined || order.lock_lp_sol_amount === null) {
           throw new Error(`订单数据格式错误：订单 ${i} 缺少 lock_lp_sol_amount Order data format error: Order ${i} missing lock_lp_sol_amount`);
@@ -320,7 +309,7 @@ function calcLiqTokenBuy(price, buyTokenAmount, orders, onceMaxOrder, passOrder
 
   }
 
-  // 如果遍历的订单数小于等于onceMaxOrder，说明链表结束，需要计算无限流动性
+  // If the number of traversed orders is less than or equal to onceMaxOrder, the chain has ended and infinite liquidity needs to be calculated
   if (orders.length <= onceMaxOrder && orders.length > 0) {
 
     const lastOrder = orders[orders.length - 1];
@@ -358,16 +347,16 @@ function calcLiqTokenBuy(price, buyTokenAmount, orders, onceMaxOrder, passOrder
             throw new Error(`流动性计算错误：无法转换无限流动性数值 Liquidity calculation error: Cannot convert infinite liquidity values - ${error.message}`);
           }
 
-          // 进入无限流动性后 也要 , 计算实际使用的SOL数量 到能买到为止
+          // After entering infinite liquidity, also calculate the actual amount of SOL used, until enough can be bought
           if (result.real_lp_sol_amount === 0n) {
             if (result.free_lp_token_amount_sum > buyTokenAmountBigInt) {
-              // 这时间隙流动性已经够买入的了
-              // 计算最后精确需要买多少token
+              // At this point the gap liquidity is already enough to buy
+              // Calculate the final precise amount of token to buy
               try {
                 const actualBuyAmount = buyTokenAmountBigInt - (result.free_lp_token_amount_sum - BigInt(tokenAmount));
                 const [, preciseSol] = CurveAMM.buyFromPriceWithTokenOutput(lastEndPrice, actualBuyAmount)
                 result.real_lp_sol_amount += BigInt(preciseSol);
-                result.force_close_num = counti; // 强平订单数量
+                result.force_close_num = counti; // Number of force closed orders
               } catch (error) {
                 throw new Error(`流动性计算错误：无限流动性精确SOL计算失败 Liquidity calculation error: Infinite liquidity precise SOL calculation failed - ${error.message}`);
               }
@@ -394,74 +383,63 @@ function calcLiqTokenBuy(price, buyTokenAmount, orders, onceMaxOrder, passOrder
 
 
 /**
- * 计算代币卖出时的流动性影响 Calculate liquidity impact for token sell operations
- * 
- * 此函数分析卖出操作对价格区间内流动性的影响，计算可用的自由流动性、锁定流动性，
- * 并支持跳过指定订单（将其流动性视为可用）。适用于做空订单（down_orders）场景。
+ * Calculate liquidity impact for token sell operations
+ *
  * This function analyzes the liquidity impact of sell operations within price ranges,
  * calculates available free liquidity, locked liquidity, and supports skipping specific
  * orders (treating their liquidity as available). Applicable for short orders (down_orders) scenarios.
- * 
- * @param {bigint|string|number} price - 当前代币价格，作为计算起始价格 Current token price, used as calculation start price
- * @param {bigint|string|number} sellTokenAmount - 卖出的代币数量，目标卖出数量 Amount of tokens to sell, target sell amount
- * @param {Array<Object>} orders - 订单数组，按 lock_lp_start_price 从大到小排序 Array of orders sorted by lock_lp_start_price (descending):
- *   - order_type: {number} 订单类型(1=做多,2=做空) Order type (1=long, 2=short)
- *   - mint: {string} 代币地址 Token mint address
- *   - user: {string} 用户地址 User address
- *   - lock_lp_start_price: {string} LP锁定开始价格（高价） LP lock start price (high price) (required)
- *   - lock_lp_end_price: {string} LP锁定结束价格（低价） LP lock end price (low price) (required)
- *   - lock_lp_sol_amount: {number} 锁定的SOL数量 Locked SOL amount (required)
- *   - lock_lp_token_amount: {number} 锁定的代币数量 Locked token amount (required)
- *   - start_time: {number} 开始时间戳 Start timestamp
- *   - end_time: {number} 结束时间戳 End timestamp
- *   - margin_sol_amount: {number} 保证金SOL数量 Margin SOL amount
- *   - borrow_amount: {number} 借贷数量 Borrow amount
- *   - position_asset_amount: {number} 持仓资产数量 Position asset amount
- *   - borrow_fee: {number} 借贷费用 Borrow fee
- *   - order_pda: {string} 订单PDA地址 Order PDA address (required for passOrder matching)
- * @param {number} onceMaxOrder - 一次处理的最大订单数，限制遍历范围 Maximum orders to process at once, limits traversal range
- * @param {string|null} passOrder - 需要跳过的订单PDA地址字符串，当该值与订单的order_pda匹配时，跳过该订单并将其流动性计入自由流动性 Order PDA address string to skip, when this value matches an order's order_pda, skip that order and count its liquidity as free liquidity
- * 
- * @returns {Object} 流动性计算结果对象，包含详细的流动性分析数据 Liquidity calculation result object with detailed liquidity analysis data:
- * 
- *   **自由流动性 Free Liquidity:**
- *   - free_lp_sol_amount_sum: {bigint} 可用自由流动性SOL总量，表示卖出时能获得的SOL，包含：1)价格间隙流动性 2)跳过订单的流动性 3)无限流动性（如有）
- *                                       Total available free liquidity SOL amount, represents SOL obtainable from selling, includes: 1) price gap liquidity 2) skipped order liquidity 3) infinite liquidity (if any)
- *   - free_lp_token_amount_sum: {bigint} 可用自由流动性Token总量，表示在不强平任何订单情况下可卖出的最大代币数量
- *                                         Total available free liquidity token amount, represents max tokens sellable without force closing any orders
- * 
- *   **锁定流动性 Locked Liquidity:**
- *   - lock_lp_sol_amount_sum: {bigint} 被锁定的流动性SOL总量，不包括跳过的订单，这部分流动性不可直接使用
- *                                       Total locked liquidity SOL amount, excludes skipped orders, this liquidity is not directly usable
- *   - lock_lp_token_amount_sum: {bigint} 被锁定的流动性Token总量，不包括跳过的订单，对应于锁定的SOL流动性
- *                                         Total locked liquidity token amount, excludes skipped orders, corresponds to locked SOL liquidity
- * 
- *   **流动性状态标识 Liquidity Status Indicators:**
- *   - has_infinite_lp: {boolean} 是否包含无限流动性，true表示订单链表已结束且计算了到最小价格(MIN_U128_PRICE)的流动性
- *                                  Whether includes infinite liquidity, true means order chain ended and liquidity to min price (MIN_U128_PRICE) was calculated
- *   - pass_order_id: {number} 被跳过的订单在数组中的索引位置，-1表示没有跳过任何订单，>=0表示跳过了对应索引的订单
- *                               Index of skipped order in array, -1 means no order skipped, >=0 means order at that index was skipped
- * 
- *   **卖出执行信息 Sell Execution Info:**
- *   - force_close_num: {number} 需要强平的订单数量，表示为了卖出目标数量需要强制平仓多少个订单，0表示无需强平
- *                                 Number of orders that need to be force closed, indicates how many orders need force closure to sell target amount, 0 means no force closure needed
- *   - ideal_lp_sol_amount: {bigint} 理想SOL获得量，基于当前价格使用CurveAMM直接计算的理论最大SOL收益，不考虑流动性分布
- *                                     Ideal SOL amount obtainable, theoretical maximum SOL revenue calculated directly from current price using CurveAMM, ignores liquidity distribution
- *   - real_lp_sol_amount: {bigint} 实际SOL获得量，考虑真实流动性分布的精确SOL收益。0表示当前自由流动性不足以满足卖出需求，需要强平更多订单
- *                                    Actual SOL amount obtainable, precise SOL revenue considering real liquidity distribution. 0 means current free liquidity insufficient for sell requirement, need to force close more orders
- * 
- * @throws {Error} 参数验证错误：price、sellTokenAmount、orders、onceMaxOrder 参数无效 Parameter validation error: invalid price, sellTokenAmount, orders, or onceMaxOrder
- * @throws {Error} 价格转换错误：无法将价格参数转换为 BigInt Price conversion error: cannot convert price parameters to BigInt
- * @throws {Error} 流动性计算错误：CurveAMM 计算失败或数值转换错误 Liquidity calculation error: CurveAMM calculation failure or value conversion error
- * @throws {Error} 间隙流动性计算失败：价格间隙流动性计算异常 Gap liquidity calculation failure: price gap liquidity calculation exception
- * @throws {Error} 无限流动性计算失败：最小价格流动性计算异常 Infinite liquidity calculation failure: min price liquidity calculation exception
- * @throws {Error} 订单数据格式错误：订单对象缺少必需字段 Order data format error: order object missing required fields
+ *
+ * @param {bigint|string|number} price - Current token price, used as calculation start price
+ * @param {bigint|string|number} sellTokenAmount - Amount of tokens to sell, target sell amount
+ * @param {Array<Object>} orders - Array of orders sorted by lock_lp_start_price (descending):
+ *   - order_type: {number} Order type (1=long, 2=short)
+ *   - mint: {string} Token mint address
+ *   - user: {string} User address
+ *   - lock_lp_start_price: {string} LP lock start price (high price) (required)
+ *   - lock_lp_end_price: {string} LP lock end price (low price) (required)
+ *   - lock_lp_sol_amount: {number} Locked SOL amount (required)
+ *   - lock_lp_token_amount: {number} Locked token amount (required)
+ *   - start_time: {number} Start timestamp
+ *   - end_time: {number} End timestamp
+ *   - margin_sol_amount: {number} Margin SOL amount
+ *   - borrow_amount: {number} Borrow amount
+ *   - position_asset_amount: {number} Position asset amount
+ *   - borrow_fee: {number} Borrow fee
+ *   - order_pda: {string} Order PDA address (required for passOrder matching)
+ * @param {number} onceMaxOrder - Maximum orders to process at once, limits traversal range
+ * @param {string|null} passOrder - Order PDA address string to skip, when this value matches an order's order_pda, skip that order and count its liquidity as free liquidity
+ *
+ * @returns {Object} Liquidity calculation result object with detailed liquidity analysis data:
+ *
+ *   **Free Liquidity:**
+ *   - free_lp_sol_amount_sum: {bigint} Total available free liquidity SOL amount, represents SOL obtainable from selling, includes: 1) price gap liquidity 2) skipped order liquidity 3) infinite liquidity (if any)
+ *   - free_lp_token_amount_sum: {bigint} Total available free liquidity token amount, represents max tokens sellable without force closing any orders
+ *
+ *   **Locked Liquidity:**
+ *   - lock_lp_sol_amount_sum: {bigint} Total locked liquidity SOL amount, excludes skipped orders, this liquidity is not directly usable
+ *   - lock_lp_token_amount_sum: {bigint} Total locked liquidity token amount, excludes skipped orders, corresponds to locked SOL liquidity
+ *
+ *   **Liquidity Status Indicators:**
+ *   - has_infinite_lp: {boolean} Whether includes infinite liquidity, true means order chain ended and liquidity to min price (MIN_U128_PRICE) was calculated
+ *   - pass_order_id: {number} Index of skipped order in array, -1 means no order skipped, >=0 means order at that index was skipped
+ *
+ *   **Sell Execution Info:**
+ *   - force_close_num: {number} Number of orders that need to be force closed, indicates how many orders need force closure to sell target amount, 0 means no force closure needed
+ *   - ideal_lp_sol_amount: {bigint} Ideal SOL amount obtainable, theoretical maximum SOL revenue calculated directly from current price using CurveAMM, ignores liquidity distribution
+ *   - real_lp_sol_amount: {bigint} Actual SOL amount obtainable, precise SOL revenue considering real liquidity distribution. 0 means current free liquidity insufficient for sell requirement, need to force close more orders
+ *
+ * @throws {Error} Parameter validation error: invalid price, sellTokenAmount, orders, or onceMaxOrder
+ * @throws {Error} Price conversion error: cannot convert price parameters to BigInt
+ * @throws {Error} Liquidity calculation error: CurveAMM calculation failure or value conversion error
+ * @throws {Error} Gap liquidity calculation failure: price gap liquidity calculation exception
+ * @throws {Error} Infinite liquidity calculation failure: min price liquidity calculation exception
+ * @throws {Error} Order data format error: order object missing required fields
  */
 function calcLiqTokenSell(price, sellTokenAmount, orders, onceMaxOrder, passOrder = null, initialVirtualSol = null, initialVirtualToken = null) {
-  // 由于是卖出操作 肯定拿的是 down_orders 方向的 订单  lock_lp_start_price >  lock_lp_end_price
-  // 并且 lock_lp_start_price 在 orders 中是从大到小排序的
+  // Since this is a sell operation, the orders are definitely in the down_orders direction  lock_lp_start_price >  lock_lp_end_price
+  // And lock_lp_start_price is sorted in descending order in orders
 
-  // 参数验证
+  // Parameter validation
   if (!price && price !== 0) {
     throw new Error('参数验证错误：price 参数不能为空 Parameter validation error: price cannot be null');
   }
@@ -479,15 +457,15 @@ function calcLiqTokenSell(price, sellTokenAmount, orders, onceMaxOrder, passOrde
   }
 
   const result = {
-    free_lp_sol_amount_sum: 0n,  // 间隙中可使用的sol流动性数量
-    free_lp_token_amount_sum: 0n, // 间隙中可使用的token流动性数量
+    free_lp_sol_amount_sum: 0n,  // Amount of SOL liquidity usable in the gaps
+    free_lp_token_amount_sum: 0n, // Amount of token liquidity usable in the gaps
     lock_lp_sol_amount_sum: 0n,
     lock_lp_token_amount_sum: 0n,
-    has_infinite_lp: false, // 是否包含无限流动性
-    pass_order_id: -1, // 跳过的订单索引
-    force_close_num: 0, // 强平订单数量
-    ideal_lp_sol_amount: 0n, // 理想情况下卖出sellTokenAmount能获得的SOL数量
-    real_lp_sol_amount: 0n, // 实际卖出sellTokenAmount能获得的SOL数量
+    has_infinite_lp: false, // Whether includes infinite liquidity
+    pass_order_id: -1, // Index of skipped order
+    force_close_num: 0, // Number of force closed orders
+    ideal_lp_sol_amount: 0n, // Amount of SOL obtainable from selling sellTokenAmount under ideal conditions
+    real_lp_sol_amount: 0n, // Amount of SOL actually obtainable from selling sellTokenAmount
   }
 
   let sellTokenAmountBigInt;
@@ -497,10 +475,10 @@ function calcLiqTokenSell(price, sellTokenAmount, orders, onceMaxOrder, passOrde
     throw new Error(`价格转换错误：无法将 sellTokenAmount 转换为 BigInt Price conversion error: Cannot convert sellTokenAmount to BigInt - ${error.message}`);
   }
 
-  // 声明用于跟踪前一次自由流动性总量的变量
+  // Declare variable for tracking the previous free liquidity total
   let prev_free_lp_sol_amount_sum;
 
-  // 计算理想情况下卖出能获得的SOL数量
+  // Calculate the amount of SOL obtainable from selling under ideal conditions
   try {
     const priceBigInt = BigInt(price);
     const initialVirtualSolDecimal = new Decimal(initialVirtualSol).div(CurveAMM.SOL_PRECISION_FACTOR_DECIMAL);
@@ -513,12 +491,12 @@ function calcLiqTokenSell(price, sellTokenAmount, orders, onceMaxOrder, passOrde
       initialVirtualSolDecimal,
       initialVirtualTokenDecimal
     );
-    // console.log(`理想计算: 当前价格=${priceBigInt}, 卖出代币=${sellTokenAmountBigInt}, 理想SOL=${result.ideal_lp_sol_amount}`);
+    // console.log(`ideal calculation: current price=${priceBigInt}, sell token=${sellTokenAmountBigInt}, ideal SOL=${result.ideal_lp_sol_amount}`);
   } catch (error) {
     throw new Error(`sell流动性计算错误：理想流动性计算失败 Liquidity calculation error: Ideal liquidity calculation failed - ${error.message}`);
   }
 
-  // orders 长度为0 时要单独计算
+  // orders length of 0 requires separate calculation
   if (orders.length === 0) {
     const initialVirtualSolDecimal = new Decimal(initialVirtualSol).div(CurveAMM.SOL_PRECISION_FACTOR_DECIMAL);
     const initialVirtualTokenDecimal = new Decimal(initialVirtualToken).div(CurveAMM.TOKEN_PRECISION_FACTOR_DECIMAL);
@@ -531,7 +509,7 @@ function calcLiqTokenSell(price, sellTokenAmount, orders, onceMaxOrder, passOrde
     if (sellResult) {
       [result.free_lp_token_amount_sum, result.free_lp_sol_amount_sum] = sellResult;
     } else {
-      // 如果当前价格已经低于最小价格，无法再卖出
+      // If the current price is already below the minimum price, no more can be sold
       result.free_lp_token_amount_sum = 0n;
       result.free_lp_sol_amount_sum = 0n;
     }
@@ -543,15 +521,15 @@ function calcLiqTokenSell(price, sellTokenAmount, orders, onceMaxOrder, passOrde
 
 
 
-  // 选择较小值进行遍历
+  // Choose the smaller value for traversal
   const loopCount = Math.min(orders.length, onceMaxOrder);
 
   let counti = 0;
   for (let i = 0; i < loopCount; i++) {
     const order = orders[i];
-    // console.log(`处理卖出订单[${i}]: 累计自由Token=${result.free_lp_token_amount_sum}, 目标=${sellTokenAmountBigInt}, 需要=${sellTokenAmountBigInt > result.free_lp_token_amount_sum}`);
+    // console.log(`processing sell order[${i}]: cumulative free Token=${result.free_lp_token_amount_sum}, target=${sellTokenAmountBigInt}, needed=${sellTokenAmountBigInt > result.free_lp_token_amount_sum}`);
 
-    // 验证订单数据格式
+    // Validate order data format
     if (!order) {
       throw new Error(`订单数据格式错误：订单 ${i} 为空 Order data format error: Order ${i} is null`);
     }
@@ -563,15 +541,15 @@ function calcLiqTokenSell(price, sellTokenAmount, orders, onceMaxOrder, passOrde
     }
 
 
-    // 计算间隙流动性（卖出方向：从高价到低价）
+    // Calculate gap liquidity (sell direction: from high price to low price)
     let startPrice, endPrice;
     try {
       if (i === 0) {
-        // 第一个订单：从当前价格（高）到订单开始价格（低）的间隙
+        // First order: gap from current price (high) to order start price (low)
         startPrice = BigInt(price);
         endPrice = BigInt(order.lock_lp_start_price);
       } else {
-        // 后续订单：从前一个订单结束价格（高）到当前订单开始价格（低）的间隙
+        // Subsequent orders: gap from previous order end price (high) to current order start price (low)
         startPrice = BigInt(orders[i - 1].lock_lp_end_price);
         endPrice = BigInt(order.lock_lp_start_price);
       }
@@ -580,7 +558,7 @@ function calcLiqTokenSell(price, sellTokenAmount, orders, onceMaxOrder, passOrde
     }
 
 
-    // 如果存在价格间隙（卖出时startPrice应该大于endPrice）
+    // If a price gap exists (when selling, startPrice should be greater than endPrice)
     if (startPrice > endPrice) {
       try {
         const initialVirtualSolDecimal = new Decimal(initialVirtualSol).div(CurveAMM.SOL_PRECISION_FACTOR_DECIMAL);
@@ -595,25 +573,25 @@ function calcLiqTokenSell(price, sellTokenAmount, orders, onceMaxOrder, passOrde
           const [tokenAmount, solAmount] = gapLiquidity;
 
           try {
-            prev_free_lp_sol_amount_sum = result.free_lp_sol_amount_sum; // 上次的值
+            prev_free_lp_sol_amount_sum = result.free_lp_sol_amount_sum; // Previous value
             result.free_lp_sol_amount_sum += BigInt(solAmount);
             result.free_lp_token_amount_sum += BigInt(tokenAmount);
-            // console.log(`卖出间隙[${i}]: ${startPrice}→${endPrice}, 间隙Token=${tokenAmount}, 间隙SOL=${solAmount}, 累计自由Token=${result.free_lp_token_amount_sum}`);
+            // console.log(`sell gap[${i}]: ${startPrice}→${endPrice}, gap Token=${tokenAmount}, gap SOL=${solAmount}, cumulative free Token=${result.free_lp_token_amount_sum}`);
           } catch (error) {
             throw new Error(`流动性计算错误：无法转换间隙流动性数值 Liquidity calculation error: Cannot convert gap liquidity values - ${error.message}`);
           }
 
-          // 计算实际获得的SOL数量 到能卖出为止
+          // Calculate the actual amount of SOL obtained, until enough can be sold
           if (result.real_lp_sol_amount === 0n) {
             if (result.free_lp_token_amount_sum >= sellTokenAmountBigInt) {
-              // 这时间隙流动性已经够卖出的了
-              // 计算精确能获得多少SOL
+              // At this point the gap liquidity is already enough to sell
+              // Calculate the precise amount of SOL obtainable
               try {
                 const actualSellAmount = sellTokenAmountBigInt - (result.free_lp_token_amount_sum - BigInt(tokenAmount));
                 const [, preciseSol] = CurveAMM.sellFromPriceWithTokenInput(startPrice, actualSellAmount);
                 result.real_lp_sol_amount = prev_free_lp_sol_amount_sum + preciseSol;
-                // console.log(`卖出实际计算[${i}]: 自由流动性已足够, actualSellAmount=${actualSellAmount}, preciseSol=${preciseSol}, 实际SOL=${result.real_lp_sol_amount}`);
-                result.force_close_num = counti; // 强平订单数量
+                // console.log(`sell actual calculation[${i}]: free liquidity sufficient, actualSellAmount=${actualSellAmount}, preciseSol=${preciseSol}, actual SOL=${result.real_lp_sol_amount}`);
+                result.force_close_num = counti; // Number of force closed orders
               } catch (error) {
                 throw new Error(`流动性计算错误：精确SOL计算失败 Liquidity calculation error: Precise SOL calculation failed - ${error.message}`);
               }
@@ -632,11 +610,11 @@ function calcLiqTokenSell(price, sellTokenAmount, orders, onceMaxOrder, passOrde
     } else {
     }
 
-    // 检查是否需要跳过该订单（passOrder 逻辑）
+    // Check whether this order needs to be skipped (passOrder logic)
 
     if (passOrder == order.order_pda) {
 
-      // 将跳过订单的流动性加到自由流动性中
+      // Add the skipped order's liquidity to the free liquidity
       try {
         if (order.lock_lp_sol_amount === undefined || order.lock_lp_sol_amount === null) {
           throw new Error(`订单数据格式错误：跳过订单 ${i} 缺少 lock_lp_sol_amount Order data format error: Skipped order ${i} missing lock_lp_sol_amount`);
@@ -645,19 +623,19 @@ function calcLiqTokenSell(price, sellTokenAmount, orders, onceMaxOrder, passOrde
           throw new Error(`订单数据格式错误：跳过订单 ${i} 缺少 lock_lp_token_amount Order data format error: Skipped order ${i} missing lock_lp_token_amount`);
         }
 
-        const prevFreeSolSum = result.free_lp_sol_amount_sum; // 保存之前的值用于计算
+        const prevFreeSolSum = result.free_lp_sol_amount_sum; // Save the previous value for calculation
         result.free_lp_sol_amount_sum += BigInt(order.lock_lp_sol_amount);
         result.free_lp_token_amount_sum += BigInt(order.lock_lp_token_amount);
 
         result.pass_order_id = i;
 
 
-        // 检查跳过订单后的自由流动性是否已满足卖出需求
+        // Check whether the free liquidity after skipping the order already meets the sell requirement
         if (result.real_lp_sol_amount === 0n) {
           if (result.free_lp_token_amount_sum >= sellTokenAmountBigInt) {
-            // 自由流动性已经够卖出需求了
+            // Free liquidity is already enough for the sell requirement
             try {
-              // 计算精确能获得多少SOL
+              // Calculate the precise amount of SOL obtainable
               const targetPrice = i === 0 ? BigInt(price) : BigInt(orders[i - 1].lock_lp_end_price);
               const actualSellAmount = sellTokenAmountBigInt - (result.free_lp_token_amount_sum - BigInt(order.lock_lp_token_amount));
               const [, preciseSol] = CurveAMM.sellFromPriceWithTokenInput(targetPrice, actualSellAmount);
@@ -676,7 +654,7 @@ function calcLiqTokenSell(price, sellTokenAmount, orders, onceMaxOrder, passOrde
         throw new Error(`流动性计算错误：无法处理跳过订单 ${i} 的流动性 Liquidity calculation error: Cannot process skipped order ${i} liquidity - ${error.message}`);
       }
     } else {
-      // 累加锁定的流动性（正常情况）
+      // Accumulate locked liquidity (normal case)
       try {
         if (order.lock_lp_sol_amount === undefined || order.lock_lp_sol_amount === null) {
           throw new Error(`订单数据格式错误：订单 ${i} 缺少 lock_lp_sol_amount Order data format error: Order ${i} missing lock_lp_sol_amount`);
@@ -699,7 +677,7 @@ function calcLiqTokenSell(price, sellTokenAmount, orders, onceMaxOrder, passOrde
 
   }
 
-  // 如果遍历的订单数小于等于onceMaxOrder，说明链表结束，需要计算无限流动性
+  // If the number of traversed orders is less than or equal to onceMaxOrder, the chain has ended and infinite liquidity needs to be calculated
   if (orders.length <= onceMaxOrder && orders.length > 0) {
 
     const lastOrder = orders[orders.length - 1];
@@ -740,15 +718,15 @@ function calcLiqTokenSell(price, sellTokenAmount, orders, onceMaxOrder, passOrde
             throw new Error(`流动性计算错误：无法转换无限流动性数值 Liquidity calculation error: Cannot convert infinite liquidity values - ${error.message}`);
           }
 
-          // 进入无限流动性后，计算实际获得的SOL数量
+          // After entering infinite liquidity, calculate the actual amount of SOL obtained
           if (result.real_lp_sol_amount === 0n) {
             if (result.free_lp_token_amount_sum >= sellTokenAmountBigInt) {
-              // 无限流动性够卖出需求了
+              // Infinite liquidity is enough for the sell requirement
               try {
                 const actualSellAmount = sellTokenAmountBigInt - (result.free_lp_token_amount_sum - BigInt(tokenAmount));
                 const [, preciseSol] = CurveAMM.sellFromPriceWithTokenInput(lastEndPrice, actualSellAmount);
                 result.real_lp_sol_amount = prevFreeSolSum + preciseSol;
-                result.force_close_num = counti; // 强平订单数量
+                result.force_close_num = counti; // Number of force closed orders
               } catch (error) {
                 throw new Error(`流动性计算错误：无限流动性精确SOL计算失败 Liquidity calculation error: Infinite liquidity precise SOL calculation failed - ${error.message}`);
               }