100x-sdk 1.0.3 → 1.0.4

package/src/modules/simulator/calc_sol_liq.js

@@ -2,14 +2,14 @@
 const CurveAMM = require('../../utils/curve_amm');
 
 /**
- * 计算使用指定SOL数量买入时能获得的Token数量
- * @param {bigint|string} price - 当前交易价格 (u128格式)
- * @param {bigint|string|number} buySolAmount - 需要花费的SOL数量 (lamports, 9位精度)
- * @param {Array} orders - 锁定流动性的订单数组
- * @param {number} onceMaxOrder - 单次循环最大订单数
- * @param {string|number|null} passOrderID - 需要跳过的订单ID（与order_id字段比较）
- * @param {string|number|null} initialVirtualSol - 流动池SOL数量
- * @param {string|number|null} initialVirtualToken - 流动池Token数量
+ * Calculate the amount of Token obtainable when buying with a specified amount of SOL
+ * @param {bigint|string} price - Current trade price (u128 format)
+ * @param {bigint|string|number} buySolAmount - Amount of SOL to spend (lamports, 9-digit precision)
+ * @param {Array} orders - Array of orders locking liquidity
+ * @param {number} onceMaxOrder - Maximum number of orders per loop iteration
+ * @param {string|number|null} passOrderID - Order ID to skip (compared against the order_id field)
+ * @param {string|number|null} initialVirtualSol - Liquidity pool SOL amount
+ * @param {string|number|null} initialVirtualToken - Liquidity pool Token amount
  * @returns {Object} { tokenAmount: bigint, msg: string, closedOrdersCount: number }
  */
 function calcLiqSolBuy(price, buySolAmount, orders, onceMaxOrder, passOrderID = null, initialVirtualSol = null, initialVirtualToken = null){
@@ -17,8 +17,8 @@ function calcLiqSolBuy(price, buySolAmount, orders, onceMaxOrder, passOrderID =
 
     //console.log("calcLiqSolBuy: , price, buySolAmount, orders, onceMaxOrder, passOrderID , initialVirtualSol, initialVirtualToken=", price, buySolAmount, orders, onceMaxOrder, passOrderID , initialVirtualSol , initialVirtualToken);
 
-    // 1. 参数验证
-    // 转换为 bigint 以便比较
+    // 1. Parameter validation
+    // Convert to bigint for comparison
     let priceBigInt;
     let buySolAmountBigInt;
 
@@ -33,7 +33,7 @@ function calcLiqSolBuy(price, buySolAmount, orders, onceMaxOrder, passOrderID =
         };
     }
 
-    // 检查价格和金额是否有效
+    // Check whether price and amount are valid
     if (priceBigInt <= 0n) {
         return {
             tokenAmount: 0n,
@@ -50,7 +50,7 @@ function calcLiqSolBuy(price, buySolAmount, orders, onceMaxOrder, passOrderID =
         };
     }
 
-    // 2. 设置默认流动池参数
+    // 2. Set default liquidity pool parameters
     const Decimal = require('decimal.js');
     const virtualSol = initialVirtualSol !== null
         ? new Decimal(initialVirtualSol.toString()).div(CurveAMM.SOL_PRECISION_FACTOR_DECIMAL)
@@ -62,9 +62,9 @@ function calcLiqSolBuy(price, buySolAmount, orders, onceMaxOrder, passOrderID =
     //console.log("calcLiqSolBuy: virtualSol,virtualToken=",virtualSol,virtualToken)
 
 
-    // 3. 处理空订单情况（第一阶段）
+    // 3. Handle the empty orders case (first stage)
     if (!orders || orders.length === 0) {
-        // 直接计算完整流动性下的买入
+        // Directly calculate the buy under full liquidity
         const result = CurveAMM.buyFromPriceWithSolInputWithParams(
             price,
             buySolAmount,
@@ -88,16 +88,16 @@ function calcLiqSolBuy(price, buySolAmount, orders, onceMaxOrder, passOrderID =
         };
     }
 
-    // 4. 处理有订单的情况（第二阶段：分段流动性计算）
+    // 4. Handle the case with orders (second stage: segmented liquidity calculation)
 
-    // 初始化变量
-    let currentPrice = priceBigInt;           // 当前价格指针
-    let remainingSol = buySolAmountBigInt;    // 剩余可用 SOL
-    let totalTokenAmount = 0n;                // 累计获得的 token
-    let closedOrdersCount = 0;                // 平仓订单数量
-    let processedOrders = 0;                  // 已处理订单数
+    // Initialize variables
+    let currentPrice = priceBigInt;           // Current price pointer
+    let remainingSol = buySolAmountBigInt;    // Remaining available SOL
+    let totalTokenAmount = 0n;                // Accumulated tokens obtained
+    let closedOrdersCount = 0;                // Number of closed orders
+    let processedOrders = 0;                  // Number of processed orders
 
-    // 检查当前价格是否高于第一个订单的结束价格
+    // Check whether the current price is higher than the first order's end price
     if (orders.length > 0) {
         const firstOrderEndPrice = typeof orders[0].lock_lp_end_price === 'bigint'
             ? orders[0].lock_lp_end_price
@@ -112,23 +112,23 @@ function calcLiqSolBuy(price, buySolAmount, orders, onceMaxOrder, passOrderID =
         }
     }
 
-    // 遍历订单（最多 onceMaxOrder 个）
+    // Iterate over orders (up to onceMaxOrder)
     for (let i = 0; i < orders.length && processedOrders < onceMaxOrder; i++) {
         const order = orders[i];
 
-        // 检查是否需要跳过此订单
+        // Check whether this order needs to be skipped
         if (passOrderID !== null && order.order_id !== undefined) {
-            // 将两者都转换为字符串进行比较
+            // Convert both to strings for comparison
             const orderIdStr = String(order.order_id);
             const passOrderIdStr = String(passOrderID);
 
             if (orderIdStr === passOrderIdStr) {
-                // 跳过此订单，不处理其锁定区间，继续下一个订单
+                // Skip this order, do not process its lock range, continue to the next order
                 continue;
             }
         }
 
-        // 转换订单价格为 bigint
+        // Convert order prices to bigint
         let lockStartPrice, lockEndPrice;
         try {
             lockStartPrice = typeof order.lock_lp_start_price === 'bigint'
@@ -145,9 +145,9 @@ function calcLiqSolBuy(price, buySolAmount, orders, onceMaxOrder, passOrderID =
             };
         }
 
-        // 步骤1：计算可用区间（currentPrice → lockStartPrice）
+        // Step 1: Calculate the available range (currentPrice → lockStartPrice)
         if (currentPrice < lockStartPrice) {
-            // 1.1 计算这段区间需要多少 SOL 和能获得多少 token
+            // 1.1 Calculate how much SOL this range needs and how many tokens can be obtained
             const result = CurveAMM.buyFromPriceToPriceWithParams(
                 currentPrice,
                 lockStartPrice,
@@ -155,7 +155,7 @@ function calcLiqSolBuy(price, buySolAmount, orders, onceMaxOrder, passOrderID =
                 virtualToken
             );
 
-            // 检查计算是否成功
+            // Check whether the calculation succeeded
             if (result === null) {
                 return {
                     tokenAmount: 0n,
@@ -166,14 +166,14 @@ function calcLiqSolBuy(price, buySolAmount, orders, onceMaxOrder, passOrderID =
 
             const [solNeeded, tokenGained] = result;
 
-            // 1.2 判断剩余 SOL 是否足够
+            // 1.2 Determine whether the remaining SOL is sufficient
             if (remainingSol >= solNeeded) {
-                // 足够：买完这段区间，继续下一段
+                // Sufficient: buy through this range and continue to the next segment
                 remainingSol -= solNeeded;
                 totalTokenAmount += tokenGained;
                 currentPrice = lockStartPrice;
             } else {
-                // 不够：用完剩余 SOL，计算能买多少，然后返回
+                // Insufficient: use up the remaining SOL, calculate how much can be bought, then return
                 const finalResult = CurveAMM.buyFromPriceWithSolInputWithParams(
                     currentPrice,
                     remainingSol,
@@ -200,15 +200,15 @@ function calcLiqSolBuy(price, buySolAmount, orders, onceMaxOrder, passOrderID =
             }
         }
 
-        // 步骤2：跳过锁定区间（lockStartPrice → lockEndPrice）
+        // Step 2: Skip the lock range (lockStartPrice → lockEndPrice)
         currentPrice = lockEndPrice;
         processedOrders++;
 
-        // 步骤3：判断是否平仓
-        // 如果价格到达 lockEndPrice，说明这个订单被平仓
+        // Step 3: Determine whether the order is closed
+        // If the price reaches lockEndPrice, this order is closed
         closedOrdersCount++;
 
-        // 检查 SOL 是否已用完
+        // Check whether SOL has been used up
         if (remainingSol === 0n) {
             return {
                 tokenAmount: totalTokenAmount,
@@ -218,8 +218,8 @@ function calcLiqSolBuy(price, buySolAmount, orders, onceMaxOrder, passOrderID =
         }
     }
 
-    // 步骤4：处理最后的无限流动性区间
-    // 所有订单处理完后，用剩余 SOL 继续买入
+    // Step 4: Handle the final infinite liquidity range
+    // After all orders are processed, continue buying with the remaining SOL
     if (remainingSol > 0n) {
         const finalResult = CurveAMM.buyFromPriceWithSolInputWithParams(
             currentPrice,
@@ -246,7 +246,7 @@ function calcLiqSolBuy(price, buySolAmount, orders, onceMaxOrder, passOrderID =
         };
     }
 
-    // 步骤5：SOL 刚好用完
+    // Step 5: SOL is exactly used up
     return {
         tokenAmount: totalTokenAmount,
         msg: `SOL刚好用完，最终价格: ${currentPrice.toString()}`,

package/src/modules/simulator/close_indices.js

@@ -7,12 +7,11 @@ const CANDIDATE_NODES_EACH_SIDE = Math.floor((MAX_CANDIDATE_INDICES - 1) / 2);
 const NO_ORDER = 65535;
 
 /**
- * 根据 index 在订单数组中查找订单
  * Find order in array by its index field
  *
- * @param {Array} orders - 订单数组 / Orders array
- * @param {number} index - 订单的 index 字段值 / Order's index field value
- * @returns {Object|null} 找到的订单对象，找不到返回 null / Found order object or null
+ * @param {Array} orders - Orders array
+ * @param {number} index - Order's index field value
+ * @returns {Object|null} Found order object or null
  */
 function findOrderByIndex(orders, index) {
   for (let i = 0; i < orders.length; i++) {
@@ -24,28 +23,27 @@ function findOrderByIndex(orders, index) {
 }
 
 /**
- * 为做多平仓生成候选插入索引
  * Generate candidate insertion indices for closing long position
  *
- * @param {string} mint - 代币地址 / Token address
- * @param {number|string|anchor.BN} closeOrderId - 要平仓的订单ID (order_id, 不是 index) / Order ID to close (order_id, not index)
- * @param {Object|null} ordersData - 订单数据（可选，如果不提供会自动获取）/ Orders data (optional, will fetch if not provided)
- * @returns {Promise<Object>} 返回包含候选索引数组的对象 / Returns object containing candidate indices array
- *   - closeOrderIndices: {number[]} 候选插入位置索引数组 / Candidate insertion position indices array
+ * @param {string} mint - Token address
+ * @param {number|string|anchor.BN} closeOrderId - Order ID to close (order_id, not index)
+ * @param {Object|null} ordersData - Orders data (optional, will fetch if not provided)
+ * @returns {Promise<Object>} Returns object containing candidate indices array
+ *   - closeOrderIndices: {number[]} Candidate insertion position indices array
  *
- * @throws {Error} 如果找不到对应的 closeOrderId / If closeOrderId is not found
+ * @throws {Error} If closeOrderId is not found
  *
  * @example
- * // 平仓做多订单
+ * // Close a long position order
  * const result = await sdk.simulator.simulateLongClose(
  *   'HG9R8CE9N18U8zYqo6cqS4bFaCAzHbAhaAe1zq8Hq7PF',
  *   1090  // order_id
  * );
- * console.log('候选索引:', result.closeOrderIndices);
- * // 输出: { closeOrderIndices: [25, 15, 35, 5, 45, ...] }
+ * console.log('Candidate indices:', result.closeOrderIndices);
+ * // Output: { closeOrderIndices: [25, 15, 35, 5, 45, ...] }
  */
 async function simulateLongClose(mint, closeOrderId, ordersData = null) {
-  // 1. 获取 down_orders 数据（做多订单在 down_orders 中）
+  // 1. Fetch down_orders data (long orders are in down_orders)
   if (!ordersData) {
     ordersData = await this.sdk.data.orders(mint, { type: 'down_orders' });
   }
@@ -56,10 +54,10 @@ async function simulateLongClose(mint, closeOrderId, ordersData = null) {
 
   const orders = ordersData.data.orders;
 
-  // 2. 将 closeOrderId 转换为字符串（因为 API 返回的 order_id 是字符串）
+  // 2. Convert closeOrderId to string (since order_id returned by the API is a string)
   const targetOrderId = closeOrderId.toString();
 
-  // 3. 在订单列表中查找匹配的订单
+  // 3. Find the matching order in the order list
   let targetOrderIndex = -1;
   for (let i = 0; i < orders.length; i++) {
     if (orders[i].order_id === targetOrderId) {
@@ -68,78 +66,77 @@ async function simulateLongClose(mint, closeOrderId, ordersData = null) {
     }
   }
 
-  // 4. 如果找不到订单，抛出错误
+  // 4. If the order is not found, throw an error
   if (targetOrderIndex === -1) {
     throw new Error(`Order with order_id ${targetOrderId} not found in down_orders`);
   }
 
-  // 5. 获取目标订单的 OrderBook index
+  // 5. Get the OrderBook index of the target order
   const targetOrder = orders[targetOrderIndex];
   const mainIndex = targetOrder.index;
 
-  // 6. 生成候选索引数组（通过链表结构遍历前后节点）
+  // 6. Generate the candidate indices array (traverse prev/next nodes via the linked list structure)
   const indices = [];
 
-  // 添加主位置
+  // Add the main position
   indices.push(mainIndex);
 
-  // 通过链表结构添加前后节点的索引
+  // Add indices of prev/next nodes via the linked list structure
   let prevNode = targetOrder;
   let nextNode = targetOrder;
 
   for (let offset = 1; offset <= CANDIDATE_NODES_EACH_SIDE; offset++) {
-    // 添加前面第 offset 个节点（通过 prev_order 链表指针）
+    // Add the offset-th preceding node (via the prev_order linked list pointer)
     if (prevNode.prev_order !== NO_ORDER) {
       const prevOrder = findOrderByIndex(orders, prevNode.prev_order);
       if (prevOrder && prevOrder.index !== undefined) {
         indices.push(prevOrder.index);
-        prevNode = prevOrder; // 继续向前遍历
+        prevNode = prevOrder; // Continue traversing backward
       } else {
-        prevNode = { prev_order: NO_ORDER }; // 找不到则停止
+        prevNode = { prev_order: NO_ORDER }; // Stop if not found
       }
     }
 
-    // 添加后面第 offset 个节点（通过 next_order 链表指针）
+    // Add the offset-th following node (via the next_order linked list pointer)
     if (nextNode.next_order !== NO_ORDER) {
       const nextOrder = findOrderByIndex(orders, nextNode.next_order);
       if (nextOrder && nextOrder.index !== undefined) {
         indices.push(nextOrder.index);
-        nextNode = nextOrder; // 继续向后遍历
+        nextNode = nextOrder; // Continue traversing forward
       } else {
-        nextNode = { next_order: NO_ORDER }; // 找不到则停止
+        nextNode = { next_order: NO_ORDER }; // Stop if not found
       }
     }
   }
 
-  // 7. 返回结果
+  // 7. Return the result
   return {
     closeOrderIndices: indices
   };
 }
 
 /**
- * 为做空平仓生成候选插入索引
  * Generate candidate insertion indices for closing short position
  *
- * @param {string} mint - 代币地址 / Token address
- * @param {number|string|anchor.BN} closeOrderId - 要平仓的订单ID (order_id, 不是 index) / Order ID to close (order_id, not index)
- * @param {Object|null} ordersData - 订单数据（可选，如果不提供会自动获取）/ Orders data (optional, will fetch if not provided)
- * @returns {Promise<Object>} 返回包含候选索引数组的对象 / Returns object containing candidate indices array
- *   - closeOrderIndices: {number[]} 候选插入位置索引数组 / Candidate insertion position indices array
+ * @param {string} mint - Token address
+ * @param {number|string|anchor.BN} closeOrderId - Order ID to close (order_id, not index)
+ * @param {Object|null} ordersData - Orders data (optional, will fetch if not provided)
+ * @returns {Promise<Object>} Returns object containing candidate indices array
+ *   - closeOrderIndices: {number[]} Candidate insertion position indices array
  *
- * @throws {Error} 如果找不到对应的 closeOrderId / If closeOrderId is not found
+ * @throws {Error} If closeOrderId is not found
  *
  * @example
- * // 平仓做空订单
+ * // Close a short position order
  * const result = await sdk.simulator.simulateShortClose(
  *   'HG9R8CE9N18U8zYqo6cqS4bFaCAzHbAhaAe1zq8Hq7PF',
  *   1090  // order_id
  * );
- * console.log('候选索引:', result.closeOrderIndices);
- * // 输出: { closeOrderIndices: [25, 15, 35, 5, 45, ...] }
+ * console.log('Candidate indices:', result.closeOrderIndices);
+ * // Output: { closeOrderIndices: [25, 15, 35, 5, 45, ...] }
  */
 async function simulateShortClose(mint, closeOrderId, ordersData = null) {
-  // 1. 获取 up_orders 数据（做空订单在 up_orders 中）
+  // 1. Fetch up_orders data (short orders are in up_orders)
   if (!ordersData) {
     ordersData = await this.sdk.data.orders(mint, { type: 'up_orders' });
   }
@@ -150,10 +147,10 @@ async function simulateShortClose(mint, closeOrderId, ordersData = null) {
 
   const orders = ordersData.data.orders;
 
-  // 2. 将 closeOrderId 转换为字符串（因为 API 返回的 order_id 是字符串）
+  // 2. Convert closeOrderId to string (since order_id returned by the API is a string)
   const targetOrderId = closeOrderId.toString();
 
-  // 3. 在订单列表中查找匹配的订单
+  // 3. Find the matching order in the order list
   let targetOrderIndex = -1;
   for (let i = 0; i < orders.length; i++) {
     if (orders[i].order_id === targetOrderId) {
@@ -162,50 +159,50 @@ async function simulateShortClose(mint, closeOrderId, ordersData = null) {
     }
   }
 
-  // 4. 如果找不到订单，抛出错误
+  // 4. If the order is not found, throw an error
   if (targetOrderIndex === -1) {
     throw new Error(`Order with order_id ${targetOrderId} not found in up_orders`);
   }
 
-  // 5. 获取目标订单的 OrderBook index
+  // 5. Get the OrderBook index of the target order
   const targetOrder = orders[targetOrderIndex];
   const mainIndex = targetOrder.index;
 
-  // 6. 生成候选索引数组（通过链表结构遍历前后节点）
+  // 6. Generate the candidate indices array (traverse prev/next nodes via the linked list structure)
   const indices = [];
 
-  // 添加主位置
+  // Add the main position
   indices.push(mainIndex);
 
-  // 通过链表结构添加前后节点的索引
+  // Add indices of prev/next nodes via the linked list structure
   let prevNode = targetOrder;
   let nextNode = targetOrder;
 
   for (let offset = 1; offset <= CANDIDATE_NODES_EACH_SIDE; offset++) {
-    // 添加前面第 offset 个节点（通过 prev_order 链表指针）
+    // Add the offset-th preceding node (via the prev_order linked list pointer)
     if (prevNode.prev_order !== NO_ORDER) {
       const prevOrder = findOrderByIndex(orders, prevNode.prev_order);
       if (prevOrder && prevOrder.index !== undefined) {
         indices.push(prevOrder.index);
-        prevNode = prevOrder; // 继续向前遍历
+        prevNode = prevOrder; // Continue traversing backward
       } else {
-        prevNode = { prev_order: NO_ORDER }; // 找不到则停止
+        prevNode = { prev_order: NO_ORDER }; // Stop if not found
       }
     }
 
-    // 添加后面第 offset 个节点（通过 next_order 链表指针）
+    // Add the offset-th following node (via the next_order linked list pointer)
     if (nextNode.next_order !== NO_ORDER) {
       const nextOrder = findOrderByIndex(orders, nextNode.next_order);
       if (nextOrder && nextOrder.index !== undefined) {
         indices.push(nextOrder.index);
-        nextNode = nextOrder; // 继续向后遍历
+        nextNode = nextOrder; // Continue traversing forward
       } else {
-        nextNode = { next_order: NO_ORDER }; // 找不到则停止
+        nextNode = { next_order: NO_ORDER }; // Stop if not found
       }
     }
   }
 
-  // 7. 返回结果
+  // 7. Return the result
   return {
     closeOrderIndices: indices
   };