@hikaru-fi/swap-router/README.md

Package for calculating optimal path for executing swaps

# swap-router
Router for swaps

# Backend usage

Import ```getSwaps``` function from package:

```js
const { getSwap } = require('hikaru-swap-router');

function calculateSwaps() {
  ...
  const result = getSwap(tokenIn, tokenOut, swapAmount, swapType, pools, options);
  ...
}
```

# Input

To get required path you need to provide four arguments:
- ```tokenIn```: token that user will pay
- ```tokenOut```: token that user will receive
- ```swapType```: what kind of swap user wants (Sell/Buy)
- ```swapAmount```: amount of tokens that user wants to sell/buy

Swap types:
```js
const SwapTypes = {
    // main swap types
    Sell: 'SellTokens',
    Buy: 'BuyTokens',

    VirtualSwap: 'VirtualSwap',
    None: 'None',
}
```

# Output

If everything is ok, you will receive object with payload that can be used to call smart contracts:
```js
/**
 * @typedef RouteInfo
 * @property {String} swapType
 * @property {String} expectedResult
 * @property {SellTokens | BuyTokens | VirtualSwap} swapRoute
 */
```

Where:
- swapType - type of swap that determines what contract functions you need to call
- expectedResult - expected result of swap (expected receive/pay amount of tokens)
- swapRoute - Object containing required information for calculating/performing swaps

There are three swapTypes:
- SellTokens:
  - function for swap result calculation: ```calculateSellTokens```
  - function for performing swap: ```sellTokens```
  - Object with parameters for router smart contract - ```SellTokens``` type:
```js  
/**
 * @typedef SellTokens
 * @property {String} vault
 * @property {String} pool
 * @property {String} tokenIn
 * @property {String} tokenOut
 * @property {String} amountIn
 * @property {String} minAmountOut
 * @property {String} deadline
 */
```

- BuyTokens:
  - function for swap result calculation: ```calculateBuyTokens```
  - function for performing swap: ```buyTokens```
  - Object with parameters for router smart contract - ```BuyTokens``` type:
```js
/**
 * @typedef BuyTokens
 * @property {String} vault
 * @property {String} pool
 * @property {String} tokenIn
 * @property {String} tokenOut
 * @property {String} amountToBuy
 * @property {String} maxAmountIn
 * @property {String} deadline
 */
```

- VirtualSwap:
  - function for swap result calculation: ```calculateVirtualSwap```
  - function for performing swap: ```virtualSwap```
  - Object with parameters for router smart contract ```VirtualSwap``` type:

```js
/**
 * @typedef VirtualSwapInfo
 * @property {String} pool
 * @property {String} tokenIn
 * @property {String} tokenOut
 */

/**
 * @typedef VirtualSwap
 * @property {String} vault
 * @property {VirtualSwapInfo[]} swapRoute
 * @property {String} amountIn
 * @property {String} minAmountOut
 * @property {String} deadline
 */
```




If something goes wrong you will receive object:

```js
/**
 * @typedef FailReason
 * @property {String} swapType
 * @property {String} reason
 */
```

Where:
- swapType == 'None', alerts that there is no available path for swap and in cannot be performed
- reason - string containing reason why swap cannot be performed