Swapping and Adding Liquidity
Introduction
This guide will cover how to execute a swap-and-add operation in a single atomic transaction. It is based on the swap-and-add example, found in the Uniswap code examples repository. To run this example, check out the examples's README and follow the setup instructions.
If you need a briefer on the SDK and to learn more about how these guides connect to the examples repository, please visit our background page!
When adding liquidity to a Pegasys v3 pool, you must provide two assets in a particular ratio. In many cases, your contract or the user's wallet hold a different ratio of those two assets. In order to deposit 100% of your assets, you must first swap your assets to the optimal ratio and then add liquidity.
However, the swap may shift the balance of the pool and thus change the optimal ratio. To avoid that, we can execute this swap-and-add liquidity operation in an atomic fashion, using a router. The inputs to our guide are the two tokens that we are pooling for, the amount of each token we are pooling for, the amount of each token to swap-and-add, and the Pool fee.
The guide will cover:
- Setup a router instance
- Configuring our ratio calculation
- Calculating our currency ratio
- Constructing and executing our swap-and-add transaction
At the end of the guide, given the inputs above, we should be able swap-and-add liquidity using 100% of the input assets with the press of a button and see the change reflected in our position and the balance of our tokens.
For this guide, the following Pegasys packages are used:
The core code of this guide can be found in swapAndAddLiquidity()
.
This guide assumes you are familiar with our Minting a Position guide. A minted position is required to add or remove liquidity from, so the buttons will be disabled until a position is minted.
Also note that we do not need to give approval to the NonfungiblePositionManager
to transfer our tokens as we will have already done that when minting our position.
Setup a router instance
The first step is to approve the SwapRouter
smart contract to spend our tokens for us in order for us to add liquidity to our position:
loading...
The we can setup our router, the AlphaRouter
, which is part of the smart-order-router package. The router requires a chainId
and a provider
to be initialized. Note that routing is not supported for local forks, so we will use a mainnet provider even when swapping on a local fork:
loading...
For a more detailed example, check out our routing guide.
Configuring our ratio calculation
Having created the router, we now need to construct the parameters required to make a call to its routeToRatio
function, which will ensure the ratio of currency used matches the pool's required ratio to add our total liquidity. This will require the following parameters:
The first two parameters are the currency amounts we use as input to the routeToRatio
algorithm:
loading...
Next, we will create a placeholder position with a liquidity of 1
since liquidity is still unknown and will be set inside the call to routeToRatio
:
loading...
We then need to create an instance of SwapAndAddConfig
which will set additional configuration parameters for the routeToRatio
algorithm:
ratioErrorTolerance
determines the margin of error the resulting ratio can have from the optimal ratio.maxIterations
determines the maximum times the algorithm will iterate to find a ratio within error tolerance. If max iterations is exceeded, an error is returned. The benefit of running the algorithm more times is that we have more chances to find a route, but more iterations will longer to execute. We've used a default of 6 in our example.
loading...
Finally, we will create an instance of SwapAndAddOptions
to configure which position we are adding liquidity to and our defined swapping parameters in two different objects:
swapConfig
configures therecipient
of leftover dust from swap,slippageTolerance
and adeadline
for the swap.addLiquidityOptions
must contain atokenId
to add to an existing position
loading...
Calculating our currency ratio
Having constructed all the parameters we need to call routeToRatio
, we can now make the call to the function:
loading...
The return type of the function call is SwapToRatioResponse. If a route was found successfully, this object will have two fields: the status (success) and the SwapToRatioRoute
object. We check to make sure that both of those conditions hold true before we construct and submit the transaction:
loading...
In case a route was not found, we return from the function a Failed
state for the transaction.
Constructing and executing our swap-and-add transaction
After making sure that a route was successfully found, we can now construct and send the transaction. The response (SwapToRatioRoute
) will have the properties we need to construct our transaction object:
loading...
If the transaction was successful, our swap-and-add will be completed! We should see our input token balances decrease and our position balance should be increased accordingly.