Added more comments

balancer · Dec 4, 2020 · 9e297e8 · 9e297e8
1 parent 873d480
commit 9e297e8
Show file tree

Hide file tree

Showing 2 changed files with 20 additions and 2 deletions.
diff --git a/src/sor.ts b/src/sor.ts
@@ -192,6 +192,8 @@ export const smartOrderRouterMultiHopEpsOfInterest = (
         totalReturn = 0;
 
         let priceBefore, swapAmountsPriceBefore, swapAmountsPriceAfter;
+
+        // Sweep all pricesOfInterest until we reach the amount we aim for (totalSwapAmount) 
         for (let i = 0; i < pricesOfInterest.length; i++) {
             if (i === 0) {
                 priceBefore = pricesOfInterest[i];
@@ -203,6 +205,9 @@ export const smartOrderRouterMultiHopEpsOfInterest = (
                 .slice(0, b)
                 .reduce((a, b) => a.plus(b));
 
+            // If totalInputAmountAfter is greater than totalSwapAmount we know 
+            // we found a solution to trade, now all we need to do is interpolate
+            // between swapAmountsPriceBefore and swapAmountsPriceAfter
             if (totalInputAmountAfter.isGreaterThan(totalSwapAmount)) {
                 pathIds = priceBefore.bestPathsIds.slice(0, b);
                 swapAmountsPriceBefore = priceBefore.amounts.slice(0, b);
@@ -214,13 +219,17 @@ export const smartOrderRouterMultiHopEpsOfInterest = (
                     totalSwapAmount
                 );
 
+                // We found a priceOfInterest that can yield enough amount for trade
                 highestPoiNotEnough = false;
                 break;
             }
 
             priceBefore = pricesOfInterest[i];
         }
 
+        // If we swept the whole table with pricesOfInterest and didn't get enough amounts
+        // it means that Balancer does not have enough liquidity for this totalSwapAmount.
+        // We return an empty list of swaps to represent this exception case.
         if (highestPoiNotEnough) {
             pathIds = [];
             swapAmounts = [];

diff --git a/test/testScripts/example-swapExactIn.ts b/test/testScripts/example-swapExactIn.ts
@@ -92,16 +92,25 @@ async function swapExactIn() {
     // The limit amount is due to the fact that Balancer protocol limits a trade to 50% of the pool 
     // balance of tokenIn (for swapExactIn) and 33.33% of the pool balance of tokenOut (for 
     // swapExactOut)
+    // 'paths' are ordered by ascending spot price
     let paths = sor.processPaths(pathData, pools, swapType);
 
-
+    // epsOfInterest stores a list of all relevant prices: these are either 
+    // 1) Spot prices of a path
+    // 2) Prices where paths cross, meaning they would move to the same spot price after trade
+    //    for the same amount traded.
+    // For each price of interest we have:
+    //   - 'bestPathsIds' a list of the id of the best paths to get to this price and
+    //   - 'amounts' a list of how much each path would need to trade to get to that price of
+    //     interest
     let epsOfInterest = sor.processEpsOfInterestMultiHop(
         paths,
         swapType,
         noPools
     );
 
-    // Returns  total amount of DAI swapped and list of swaps to make
+    // Returns 'swaps' which is the optimal list of swaps to make and 
+    // 'totalReturnWei' which is the total amount of tokenOut (eg. DAI) will be returned 
     let swaps, totalReturnWei;
     [swaps, totalReturnWei] = sor.smartOrderRouterMultiHopEpsOfInterest(
         pools,