@astonic-io/astonic-router-ts/README.md

Astonic Router

## AstonicRouter

A UniswapRouter-style Router for the Astonic AMM.

### How does it work?

The router's aim is to execute a series of chained swaps on pairs in the Astonic AMM.
As an example we can look at the path USDC->aUSD->aKES. But this can be anything as long as two adjecent assets represent a tradable pair in the Broker.

This path has two swaps or steps: USDC->aUSD and aUSD->aKES.
In order to specificy a path the AstonicRouter defines the following struct (as seen in [IAstonicRouter.sol](./src/IAstonicRouter.sol)):

```solidity
struct Step {
    address exchangeProvider;
    bytes32 exchangeId;
    address assetIn;
    address assetOut;
}
```

So for USDC->aUSD, the step is:

```solidity
IAstonicRouter.Step memory USDC_to_aUSD = IAstonicRouter.Step({
    exchangeProvider: 0x22d9db95E6Ae61c104A7B6F6C78D7993B94ec901,
    exchangeId: 0xacc988382b66ee5456086643dcfd9a5ca43dd8f428f6ef22503d8b8013bcffd7,
    assetIn: 0xcebA9300f2b948710d2653dD7B07f33A8B32118C,
    assetOut: 0x765DE816845861e75A25fCA122bb6898B8B1282a
});
```

And for aUSD->aKES, the step is:

```solidity
IAstonicRouter.Step memory aUSD_to_aKES = IAstonicRouter.Step({
    exchangeProvider: 0x22d9db95E6Ae61c104A7B6F6C78D7993B94ec901,
    exchangeId: 0x89de88b8eb790de26f4649f543cb6893d93635c728ac857f0926e842fb0d298b,
    assetIn: 0x765DE816845861e75A25fCA122bb6898B8B1282a,
    assetOut: 0x456a3D042C0DbD3db53D5489e98dFb038553B0d0
});
```

The parameters to a step are consistent to the parameters needed to call the Astonic Broker.

This lets us build a path:

```solidity
IAstonicRouter.Step[] memory path = new IAstonicRouter.Step[](2);
path[0] = USDC_to_aUSD;
path[1] = aUSD_to_aKES;
```

Now that we have a path thare two ways we can execute it:

- `swapExactTokensForTokens(uint256 amountIn, uint256 amountOutMin, Step[] path)` - which fixes the `amountIn` of input token, in our example USDC, and ensures at least `amountOutMin` of the output token, in our case aKES, is returned.
- `swapTokensForExactTokens(uint256 amountOut, uint256 amountInMax, Step[] path)` - which fixes the `amountOut` of output token, in our example aKES, and ensures at most `amountInMax` of the input token, in our case USDC, is spent.

In order to execute a swap you also need to give approval to the Router for the asset at the begining of the chain and the amount of either `amountIn` for (1) or `amountInMax` for (2).
Full Example:

```solidity
IAstonicRouter.Step[] memory path = new IAstonicRouter.Step[](2);
path[0] = IAstonicRouter.Step({
    exchangeProvider: biPoolManager,
    exchangeId: aUSD_USDC_exchangeID,
    assetIn: USDC,
    assetOut: aUSD
});
path[1] = IAstonicRouter.Step({
    exchangeProvider: bpm,
    exchangeId: aUSD_aKES_exchangeID,
    assetIn: aUSD,
    assetOut: aKES
});

IERC20(USDC).approve(address(astonicRouter), 1e3);
astonicRouter.swapExactTokensForTokens(1e3, 0, path);
```

You can see more examples in the [Swap Script](./script/Swap.s.sol) or the [Test](./test/AstonicRouter.t.sol);

You can also estimate a path by calling one of the two functions:

- `getAmountOut(uint256 amountIn, Step[] path)` - which returns how much of the last asset in the chain you will get for a given amount of the first.
- `getAmountIn(uint256 amuntOut, Step[], path)` - which returns how much of the first asset in the chain is required to get a certain amount of the last asset in the chain.

These functions should be used in conjuction with the `amountInMax` and `amountOutMin` variables of the swap functions in order to control slippage.