spotPriceAfterSwap
functions.tokenIn
: the address of the token being sold by usertokenOut
: the address of the token being bought by userswapType
< 'swapExactIn'
, 'swapExactOut'
>: the type of swap being done. The user can select the amount they want to sell (in tokenIn
) or the amount they want to buy (in tokenOut
)targetAmountSwap
: the amount the user wants to buy OR sell, depending on swapType
. If swapType
is 'swapExactIn'
, then targetAmountSwap
is the amount the user wants to sell. Conversely, if swapType
is 'swapExactOut'
, then targetAmountSwap
is the amount the user wants to buy.pools
: is a dictionary that is loaded from subgraph with all the pools available on Balancerpaths
: a path is a sequence of pools that enable the trade tokenIn
to tokenOut
to happen. Paths can contain one hop (direct trades) or two hops. For example a trade of DAI for BAL could have direct trades with pools that contain both DAI and BAL and also multihop paths, for example DAI→WETH→BAL or DAI→USDC→BAL.pairType
< 'token->token'
, 'token->BPT'
,'BPT->token'
>: This is something new to SOR v2. Join/Exit pools with a single token are considered by SOR as a swap just like a swap between two underlying tokens in a pool. This allows for cool use cases like swapping DAI for GUSD in two hops if there is a big stable pool (say pool A) with <DAI, USDT, USDC> and another stable pool with <BPTA, GUSD>, BPTA being the BPT of pool A. So if a hop involves joining a pool, i.e. DAI for BPTA, this pairType
would be 'token->BPT'
maxPools
: is the maximum number of swaps the final solution of SOR can have. A multihop has two swaps, for example.returnToken
: is the token whose amount is unknown for the swap and SOR is calculating. Simply put, if swapType
is 'swapExactIn'
the user is inputting how much they want to sell (targetAmountSwap
is in tokenIn
) and will get from SOR a returnAmount
which is how much they will get back in tokenOut
. Conversely, if swapType
is 'swapExactOut'
, then the user is inputting how much they want to buy (targetAmountSwap
is in tokenOut
) and will get from SOR a returnAmount
which is how much they have to pay in tokenIn
.costReturnToken
: is how much an additional swap would add in gas costs in terms of returnToken
. For example, for a 'swapExactIn'
swap of DAI for BAL, costReturnToken
could be 0.1 BAL (BAL is the returnToken
). This is simply calculated by:initialNumPaths
) of the most liquid pools we need to be able to trade the targetAmountSwap
. Usually targetAmountSwap
is much lower than the liquidity available in the largest pools so this is usually 1. Start with next step with b = initialNumPaths
where b is the number of paths being considered.b
paths and the best distribution of targetAmountSwap
which is a list called swapAmounts
with b
amounts to be swapped in each of the b
paths. The sum of all amounts in swapAmounts
is always targetAmountSwap
. This step also calculates the returnAmount
the suggested swaps return.returnAmount
of previous step with bestReturnAmount
(which is the best return amount so far) considering the additional costs of adding an extra path (costReturnToken * nSwapsInPath
). If the returnAmount
is better than bestReturnAmount
then increment b
and return to step 2). If not the algorithm has found the final solution. IMPORTANT: notice that if swapType
is 'swapExactIn'
having a better returnAmount
means that it is higher than bestReturnAmount
, i.e. the user is getting more tokenOut
. Conversely, if swapType
is 'swapExactOut'
having a better returnAmount
means that it is lower than bestReturnAmount
, i.e. the user is paying less tokenIn
for the desired amount (targetAmountSwap
) of tokenOut
they want to buy.b
mentioned above).swapAmounts
list based on the previous bestSwapAmounts
by adding another element to the list which is defined as targetAmountSwap/b
and scale down all the elements of bestSwapAmounts
by 1-1/b
so that the sum still is equal to targetAmountSwap
. For example, if the previous bestSwapAmounts
for b=2
were [150, 30]
then the new initial swapAmounts
for b=3
will be [100, 20, 60]
swapAmounts
from above, find the best paths using getBestPathIds()
(see detailed information about this function in appendix below).swapAmounts
and bestPathIds
find new swapAmounts
that maximize the return for the given bestPathIds
swapAmounts
and check if function getBestPathIds()
returns the same bestPathIds
. If yes, this means that we have converged to the best paths and swapAmounts and step 2) is finalized. If not, then go to step 2.3) againswapAmounts
that will maximize the returns given an initial guess of swapAmounts
and the list of paths that should be used (bestPathIds
). This is all done in function iterateSwapAmounts()
which will be described below in its different steps.iterateSwapAmountsApproximation()
and which does a first iteration in approximating swapAmounts
to the optimal ones (this function is explained in detail in the appendix below). This function returns prices
which are the prices after swap for each of the paths considering their respective amountSwap
in swapAmounts
as long as that amountSwap
is NOT at the limit of the path (i.e. equal to path.limitAmount
) AND is not zero.prices
are the same within a given error margin. If this is true, then the objective of not leaving paths in a state that can be arbed has been achieved and the optimal distribution of swap amounts for these paths has been found. If prices are still not close enough to each other go back to step 2.3.1.getBestPathIds()
takes as inputs swapAmounts
and all available paths
and is expected to find the paths that give the best return for the given swapAmounts
. The algorithm to do so is very simple: sort the swapAmounts
by descending order and starting with the largest swapAmount
, find the path that has the best return. Select this path and remove it from the list of available paths as we do not want to use the same path twice (as using it the first time would affect its price and slippage). The continue for each subsequent swapAmount
until we chose a path for each swapAmount
iterateSwapAmountsApproximation()
takes as inputs swapAmounts
and bestPathIds
and is expected to find new swapAmounts
that have spot prices after swap as close as possible.swapAmounts
equal to targetAmountSwap
. targetSP
) and targetSP
we need to use the derivatives of targetSP
it's easy to replace it in the equations above to find each swapAmounts
. Function redistributeInputAmounts()
does exactly that. Let's take a look at it into more detail below.iterateSwapAmountsApproximation()
above we end up with targetAmountSwap
as it should.redistributeInputAmounts()
might need to be calculated several times in a row because as the excesses are redistributed to paths that are viable, their swap amounts might go below zero or beyond the limit. We call redistributeInputAmounts()
iteratively until all swap amounts are above or equal to zero and below or equal to their path limit amounts.