WIP Documentation For Adding New Pool Types To SOR

SOR repo is here. Please make any PRs against develop branch.

New Pool Type:

• A new pool should be added under ./src/pools/newPool implementing PoolBase

• See ./src/pools/weightedPool/weightedPool.ts as an example

• Required maths functions:

  • _exactTokenInForTokenOut - Computes how many tokens can be taken out of a pool if exactTokenIn is sent. Should be EVM equivalent (we are currently moving from BigNumber.js to BigInt for these for more efficiency).

  • _tokenInForExactTokenOut - Computes how many tokens must be sent to a pool in order to take exactTokenOut. Should be EVM equivalent (we are currently moving from BigNumber.js to BigInt for these for more efficiency).

  • Balancer's SOR calculates the mathematically optimal solution that ends up bringing all sources of liquidity used to the same spotPrice after the trade happens. This way there is no arbitrage opportunity possible, which means the trade was the best possible given the liquidity sources used. To make this possible, all pools need to define a method that determines the spotPrice (_spotPriceAfterSwapExactTokenInForTokenOut & _spotPriceAfterSwapTokenInForExactTokenOut) and also the derivative of the spotPrice (_derivativeSpotPriceAfterSwapExactTokenInForTokenOut & _derivativeSpotPriceAfterSwapTokenInForExactTokenOut) after any trade. The derivative is necessary because the SOR uses a newtonian method for efficiency. (For more information on how the SOR works please visit https://docs.balancer.fi/developers/smart-order-router)

    in the case swapExactIn, let's say that the swap outcome function is
    a_out ( a_in )
    The spotPriceAfterSwap function is equal to
    1 / (a_out)'
    which is a function of a_in.
    _derivativeSpotPriceAfterSwap is the derivative of this last function.
    

    in the case swapExactOut, let's say that the swap outcome function is
    a_in ( a_out )
    The spotPriceAfterSwap function is equal to
    (a_in)'
    which is a function of a_out
    _derivativeSpotPriceAfterSwap is the derivative of this last function.
    

  • normalizedLiquidity:

    • Normalized liquidity is just used to select which paths are used in a multihop.
    • For simplification we just use the inverse of slippage which has been called normalized liquidity
    • i.e. if you have two pools with stablecoins but one uses the stablepool maths and the other the weighted pool maths, then even if the latter has more actual liquidity (USD value or number of stablecoins) the former (stablepool) is better because it has lower slippage (better normalized liquidity)

• Tests - at a minimum please add tests based off following template to ./test:

  testTemplate.ts

Onchain Data:

• Multicall should retrieve onchain values for any critical variable, i.e. token balances (we’ve seen issues with Subgraph values in past)
• Example with LinearPool addition
• test/lib/onchainData.ts
  • Add calls specific to new pool type
• Add ABI to ./src/pools/newPool
• tsconfig.json
  • Add abi to “include”

Further Code Updates:

• Balancer devs can help with this
• src/pools/index.ts - add new pool parsing
• Add PoolType to ./types PoolFilter
• Add full swap test

Test/Debug:

Running example in test/testScripts/swapExample.ts is useful to test/debug issues. You can add your own tokens that exist in the custom pool. SUBGRAPH_URLS can be changed to use any beta subgraph url.