Merge pull request #34 from securesecrets/add-router

Add router

docs/calculations/routing.md

@@ -1,3 +1,102 @@
-# ShadeSwap multi-hop routing
+# ShadeSwap Multi-Hop Routing
+
+This page contains an example router that determines the optimal path for maximizing the users output tokens received
+
+## Router
+
+### Determine Possible Paths
+Returns possible paths through one or multiple pools to complete a trade of two tokens.
+```ts
+function getPossiblePaths({
+  inputTokenContractAddress,
+  outputTokenContractAddress,
+  maxHops,
+  pairs,
+}:{
+  inputTokenContractAddress:string,
+  outputTokenContractAddress:string
+  maxHops: number // max number of pairs used
+  pairs: BatchPairsInfo
+}): string[][]
+```
+See [Batch Pairs Query](../queries/swap.html#pairs-info) for input type BatchPairsInfo.
+
+::: warning
+Increasing the max hops too much can cause decreased performance due to the large amount of computations required to calculate all routes. The current recommendation is 4 max based on the route paths available, but this is subject to change as more pairs are supported over time.
+:::
+
+### Calculate Route
+Calculates the output amount received for a given path
+
+```ts
+function calculateRoute({
+  inputTokenAmount,
+  inputTokenContractAddress,
+  path,
+  pairs,
+  tokens,
+}:{
+  inputTokenAmount: BigNumber,
+  inputTokenContractAddress: string,
+  path: string[], // path determined by getPossiblePaths
+  pairs: BatchPairsInfo,
+  tokens: TokensConfig, // list of all possible swap tokens
+}): Route
+```
+
+::: tip
+We pass in a list of all possible tokens (TokensConfig) so that we have access to their decimals for uDenom conversions. This is not the most elegant solution as it may be preferrable to reference your own data store for token data. In that case, you can create your own route calculator and use the ShadeJS one as a guide.
+:::
+```ts
+type TokenConfig = {
+  tokenContractAddress: string,
+  decimals: number,
+}
+
+type TokensConfig = TokenConfig[]
+```
+**output**
+
+```ts
+type Route = {
+  inputAmount: BigNumber,
+  quoteOutputAmount: BigNumber,
+  quoteShadeDaoFee: BigNumber,
+  quoteLPFee: BigNumber,
+  priceImpact: BigNumber,
+  inputTokenContractAddress: string,
+  outputTokenContractAddress: string,
+  path: string[],
+  gasMultiplier: number, // multiplier which is to be applied 
+  // to the base gas cost of a swap
+};
+```
+
+
+### Calculate All Possible Routes
+Retrieves all potential route options and the outputs of each route.
+Returns an array of routes in the order that will give the highest quoted
+output amount. This function utilizes both getPossiblePaths and calculateRoute.
+
+```ts
+function getRoutes({
+  inputTokenAmount,
+  inputTokenContractAddress,
+  outputTokenContractAddress,
+  maxHops,
+  pairs,
+  tokens,
+}: {
+  inputTokenAmount: BigNumber,
+  inputTokenContractAddress: string,
+  outputTokenContractAddress: string,
+  maxHops: number,
+  pairs: BatchPairsInfo,
+  tokens: TokensConfig,
+}): Route[] 
+```
+
+::: warning
+This function optimizes for maximizing the output token amount only. It does NOT factor in the value of the gas for the extra hops (i.e. gas multiplier) relative to the value of tokens received. This will especially impact small trades where there is perceived arbitrage opportunities through certain paths, without factoring in the gas cost to perform the arbitrage. It is recommended that you create your own route calculator to handle token values and use the one provided here as a guide.
+:::
 
-Coming Soon...

docs/calculations/swap.md

@@ -2,6 +2,9 @@
 
 This page demonstrates how to calculate outputs of a single pair swap on ShadeSwap
 
+## BigNumber.js
+<a href="https://github.com/MikeMcl/bignumber.js" target="_blank">bignumber.js</a> is used on all computations to prevent loss of precision that normally happens with standard javascript math
+
 ## Constant Product (CPMM)
 
 ### Forward Swap
@@ -47,7 +50,7 @@ function constantProductSwapToken1for0({
 ```
 
 ### Reverse Swap
-Backwards calcuation for determining a token input amount for a given output amount.
+Backwards calculation for determining a token input amount for a given output amount.
 ```ts
 /**
 * returns input of a simulated swap from token0 to token1 using the constant
@@ -162,7 +165,7 @@ function stableSwapToken1for0({
 ```
 
 ### Reverse Swap
-Backwards calcuation for determining a token input amount for a given output amount.
+Backwards calculation for determining a token input amount for a given output amount.
 ```ts
 /**
 * returns input of a simulated swap of token0 for 

docs/queries/batch-query.md

@@ -2,15 +2,15 @@
 
 This page demonstrates how to query using a smart contract batch query router. The purposes of a query router is to combine multiple queries to one or more contracts into a single http request. This reduces load on the node infrastructure and is faster for retrieving data than would otherwise be obtained by individual contract queries.
 
-The batch query function is generalized to work with any contract queries. Miscellaneous ShadeJS services already implement the batch query router, for example the <a href="/swap.html#pairs-info" target="_blank">Pairs Info Query</a>
+The batch query function is generalized to work with any contract queries. Miscellaneous ShadeJS services already implement the batch query router, for example the <a href="./swap.html#pairs-info" target="_blank">Pairs Info Query</a>
 
 
 ## Performance 
 All of the following results are run with 500 total queries
 
 | Batch Size | RPC Queries | Time  | Success |
 |------------|-------------|-------|---------|
-| N/A        | 500         | 5.56s | 26.6%   |
+| 1          | 500         | 5.56s | 26.6%   |
 | 5          | 100         | 6.51s | 100%    |
 | 10         | 50          | 9.24s | 100%    |
 | 25         | 20          | 7.27s | 100%    |

docs/queries/swap.md

@@ -327,18 +327,14 @@ type PairInfo = {
   isStable: boolean,
   token0Amount: string,
   token1Amount: string,
-  priceRatio: string | null,
-  pairSettings: {
-    lpFee: number,
-    daoFee: number,
-    stableLpFee: number,
-    stableDaoFee: number,
-    stableParams: StableParams | null
-  },
+  lpFee: number,
+  daoFee: number,
+  stableParams: StableParams | null
   contractVersion: number,
 }
 
 type StableParams = {
+  priceRatio: string,
   alpha: string,
   gamma1: string,
   gamma2: string,
@@ -413,14 +409,9 @@ console.log(output)
             "token0Amount": "4268251730565",
             "token1Amount": "365239579269",
             "lpTokenAmount": "487393298891",
-            "priceRatio": null,
-            "pairSettings": {
-                "lpFee": 0.0029,
-                "daoFee": 0.0001,
-                "stableLpFee": 0.000483,
-                "stableDaoFee": 0.000017,
-                "stableParams": null
-            },
+            "lpFee": 0.0029,
+            "daoFee": 0.0001,
+            "stableParams": null
             "contractVersion": 1
         }
     },
@@ -448,14 +439,9 @@ console.log(output)
             "token0Amount": "95199329571",
             "token1Amount": "377657768",
             "lpTokenAmount": "5708789507",
-            "priceRatio": null,
-            "pairSettings": {
-                "lpFee": 0.0029,
-                "daoFee": 0.0001,
-                "stableLpFee": 0.000483,
-                "stableDaoFee": 0.000017,
-                "stableParams": null
-            },
+            "lpFee": 0.0029,
+            "daoFee": 0.0001,
+            "stableParams": null
             "contractVersion": 1
         }
     }

src/config.ts

@@ -1,5 +1,5 @@
 // default endpoint to be used when alternative endpoint is not provided
-// this is a public endpoint and not guarantees can be provided about the performance
+// this is a public endpoint and no guarantees can be provided about the performance
 const DEFAULT_SECRET_LCD_ENDPOINT = 'https://lcd.secret.express/';
 const SECRET_MAINNET_CHAIN_ID = 'secret-4';
 

src/contracts/definitions/index.ts

@@ -0,0 +1,4 @@
+export * from './batchQuery';
+export * from './oracle';
+export * from './snip20';
+export * from './swap';

src/contracts/definitions/snip20.test.ts

@@ -136,13 +136,15 @@ test('it checks the shape of the snip20 increase allowance', () => {
 
 test('it checks the shape of the snip20 viewing', () => {
   const viewingKey = 'MOCK_VIEWING_KEY';
+  const padding = 'PADDING';
 
   const output = {
     msg: {
       set_viewing_key: {
         key: viewingKey,
+        padding,
       },
     },
   };
-  expect(snip20.messages.createViewingKey(viewingKey)).toStrictEqual(output);
+  expect(snip20.messages.createViewingKey(viewingKey, padding)).toStrictEqual(output);
 });

src/contracts/definitions/snip20.ts

@@ -29,7 +29,7 @@ const snip20 = {
       recipientCodeHash?: string,
       amount: string,
       handleMsg: any,
-      padding: string,
+      padding?: string,
     }): Snip20MessageRequest {
       const msg = {
         send: {
@@ -52,7 +52,7 @@ const snip20 = {
     }: {
       recipient: string,
       amount: string,
-      padding: string,
+      padding?: string,
     }): Snip20MessageRequest {
       const msg = {
         transfer: {
@@ -85,7 +85,7 @@ const snip20 = {
     }:{
       amount: string,
       denom: string,
-      padding: string,
+      padding?: string,
     }): Snip20MessageRequest {
       const msg = {
         redeem: {
@@ -108,7 +108,7 @@ const snip20 = {
       spender: string,
       amount: string,
       expiration?: number,
-      padding: string,
+      padding?: string,
     }): Snip20MessageRequest {
       const msg = {
         increase_allowance: {
@@ -123,10 +123,11 @@ const snip20 = {
       };
     },
 
-    createViewingKey(viewingKey: string): Snip20MessageRequest {
+    createViewingKey(viewingKey: string, padding?: string): Snip20MessageRequest {
       const msg = {
         set_viewing_key: {
           key: viewingKey,
+          padding,
         },
       };
       return {

src/contracts/definitions/swap.test.ts

@@ -23,7 +23,7 @@ vi.mock('~/contracts/definitions/snip20', () => ({
 }));
 
 vi.mock('~/lib/utils', () => ({
-  randomPadding: vi.fn(() => 'RANDOM_PADDING'),
+  generatePadding: vi.fn(() => 'RANDOM_PADDING'),
 }));
 
 test('it tests the form of the query factory config msg', () => {

src/contracts/definitions/swap.ts

@@ -3,7 +3,7 @@ import {
   Path,
   Paths,
 } from '~/types/contracts/swap/model';
-import { randomPadding } from '~/lib/utils';
+import { generatePadding } from '~/lib/utils';
 import { snip20 } from './snip20';
 
 /**
@@ -75,7 +75,7 @@ function msgSwap({
     recipientCodeHash: routerCodeHash,
     amount: sendAmount,
     handleMsg: swapParamsMessage,
-    padding: randomPadding(),
+    padding: generatePadding(),
   }).msg;
 }
 

src/contracts/index.ts

@@ -0,0 +1,2 @@
+export * from './definitions';
+export * from './services';

src/contracts/services/index.ts

@@ -0,0 +1,4 @@
+export * from './batchQuery';
+export * from './oracle';
+export * from './snip20';
+export * from './swap';

src/contracts/services/swap.ts

@@ -187,39 +187,37 @@ function parsePairInfo(
     token0Amount: pairInfo.amount_0,
     token1Amount: pairInfo.amount_1,
     lpTokenAmount: pairInfo.total_liquidity,
-    priceRatio: stableInfo ? stableInfo.p : null,
-    pairSettings: {
-      lpFee: fees.lp_fee.nom / fees.lp_fee.denom,
-      daoFee: fees.shade_dao_fee.nom / fees.shade_dao_fee.denom,
-      stableLpFee: fees.stable_lp_fee.nom / fees.stable_lp_fee.denom,
-      stableDaoFee: fees.stable_shade_dao_fee.nom / fees.stable_shade_dao_fee.denom,
-
-      stableParams: stableInfo ? {
-        alpha: stableInfo.stable_params.a,
-        gamma1: stableInfo.stable_params.gamma1,
-        gamma2: stableInfo.stable_params.gamma2,
-        oracle: {
-          address: stableInfo.stable_params.oracle.address,
-          codeHash: stableInfo.stable_params.oracle.code_hash,
-        },
-        token0Data: {
-          oracleKey: stableInfo.stable_token0_data.oracle_key,
-          decimals: stableInfo.stable_token0_data.decimals,
-        },
-        token1Data: {
-          oracleKey: stableInfo.stable_token1_data.oracle_key,
-          decimals: stableInfo.stable_token1_data.decimals,
-        },
-        minTradeSizeXForY: stableInfo.stable_params.min_trade_size_x_for_y,
-        minTradeSizeYForX: stableInfo.stable_params.min_trade_size_y_for_x,
-        maxPriceImpactAllowed: stableInfo.stable_params.max_price_impact_allowed,
-        customIterationControls: stableInfo.stable_params.custom_iteration_controls ? {
-          epsilon: stableInfo.stable_params.custom_iteration_controls.epsilon,
-          maxIteratorNewton: stableInfo.stable_params.custom_iteration_controls.max_iter_newton,
-          maxIteratorBisect: stableInfo.stable_params.custom_iteration_controls.max_iter_bisect,
-        } : null,
+    lpFee: pairInfo.pair[2] ? fees.stable_lp_fee.nom / fees.stable_lp_fee.denom
+      : fees.lp_fee.nom / fees.lp_fee.denom,
+    daoFee: pairInfo.pair[2] ? fees.stable_shade_dao_fee.nom / fees.stable_shade_dao_fee.denom
+      : fees.shade_dao_fee.nom / fees.shade_dao_fee.denom,
+    stableParams: stableInfo ? {
+      priceRatio: stableInfo.p!, // if stable params exist, we know price ratio will be available
+      alpha: stableInfo.stable_params.a,
+      gamma1: stableInfo.stable_params.gamma1,
+      gamma2: stableInfo.stable_params.gamma2,
+      oracle: {
+        address: stableInfo.stable_params.oracle.address,
+        codeHash: stableInfo.stable_params.oracle.code_hash,
+      },
+      token0Data: {
+        oracleKey: stableInfo.stable_token0_data.oracle_key,
+        decimals: stableInfo.stable_token0_data.decimals,
+      },
+      token1Data: {
+        oracleKey: stableInfo.stable_token1_data.oracle_key,
+        decimals: stableInfo.stable_token1_data.decimals,
+      },
+      minTradeSizeXForY: stableInfo.stable_params.min_trade_size_x_for_y,
+      minTradeSizeYForX: stableInfo.stable_params.min_trade_size_y_for_x,
+      maxPriceImpactAllowed: stableInfo.stable_params.max_price_impact_allowed,
+      customIterationControls: stableInfo.stable_params.custom_iteration_controls ? {
+        epsilon: stableInfo.stable_params.custom_iteration_controls.epsilon,
+        maxIteratorNewton: stableInfo.stable_params.custom_iteration_controls.max_iter_newton,
+        maxIteratorBisect: stableInfo.stable_params.custom_iteration_controls.max_iter_bisect,
       } : null,
-    },
+    } : null,
+
     contractVersion: pairInfo.contract_version,
   };
 }