Skip to main content

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.

info

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:

  1. Setup a router instance
  2. Configuring our ratio calculation
  3. Calculating our currency ratio
  4. 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().

note

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:

Approve SwapRouter to spend our tokens
loading...
View on Github

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:

Creating a router instance
loading...
View on Github

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:

Constructing the two CurrencyAmounts
loading...
View on Github

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:

Constructing the position object
loading...
View on Github

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.
Constructing SwapAndAddConfig
loading...
View on Github

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 the recipient of leftover dust from swap, slippageTolerance and a deadline for the swap.
  • addLiquidityOptions must contain a tokenId to add to an existing position
Constructing SwapAndAddOptions
loading...
View on Github

Calculating our currency ratio​

Having constructed all the parameters we need to call routeToRatio, we can now make the call to the function:

Making the call to routeToRatio
loading...
View on Github

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:

Checking that a route was found
loading...
View on Github

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:

Constructing and sending the transaction
loading...
View on Github

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.