balancer / balancer-sor

Smart order router: off-chain linear optimization of routing orders across pools for best price execution

Smart Order Router (SOR)

Smart Order Router, or SOR, is an off-chain linear optimization of routing orders across pools for best price execution.

SOR exists in the Bronze release as a way to aggregate liquidity across all Balancer pools. Future releases of Balancer will accomplish this on-chain and allow aggregate contract fillable liquidity.

Liquidity aggregators are free to use the SOR npm package or create their own order routing across pools.

Read More

Overview Of Use And Example

There are two types of swap available:

swapExactIn - i.e. You want to swap exactly 1 ETH as input and SOR will calculate X amount of BAL you receive in return.
or
swapExactOut - i.e. You want to receive exactly 1 BAL and SOR will calculate X amount of ETH you must input.

The SOR will return totalReturn/totalInput as well as a list swaps to achieve the total. Swaps can be through direct pools, i.e. A > POOL1 > B, or via a multihop pool, i.e. A > POOL1 > C > POOL2 > B. The swaps are returned in a format that can be directly to the Vault to execute the trade.

The example file swapExample.ts in: ./testScripts, demonstrates full examples with comments.

To Run:

Create a .env file in root dir. Depending on network being used add an RPC URL (e.g. Alchemy, Infura), e.g.: RPC_URL_MAINNET=alchemy/infura

Supported networks out of box for example are:

RPC_URL_MAINNET
RPC_URL_POLYGON
RPC_URL_ARBITRUM
RPC_URL_GNOSIS
RPC_URL_ZKEVM
RPC_URL_GOERLI

Install dependencies: $ yarn install

Run example: $ ts-node ./test/testScripts/swapExample.ts

Contributing/Adding New Pools

Running tests locally:

1. Add .env and add following RPC URLs (e.g. Alchemy, Infura)

RPC_URL_MAINNET=
RPC_URL_POLYGON=

2. Start local forked nodes to test against:

$ yarn run node

$ yarn run node:polygon

3. Run tests: $ yarn test

To run a single test file use test:only, e.g.:

$ yarn test:only test/composableStable.integration.spec.ts

Adding New Pools:

See info here

Environment Variables

Optional config values can be set in the .env file:

PRICE_ERROR_TOLERANCE - how close we expect prices after swap to be in SOR suggested paths. Defaults 0.00001.

INFINITESIMAL - Infinitesimal is an amount that's used to initialize swap amounts so they are not zero or the path's limit. Defaults 0.000001.

Example:

PRICE_ERROR_TOLERANCE=0.00001
INFINITESIMAL=0.000001

Note on Licensing

Except where indicated otherwise, the code in this repository is licensed GPLv3.

Superluminal Labs Ltd. is the owner of the directories balancer-sor/src/pools/gyro2Pool/, balancer-sor/src/pools/gyro3Pool/, balancer-sor/src/pools/gyroEPool/, balancer-sor/src/pools/gyro2V2Pool/, and balancer-sor/src/pools/gyroEV2Pool/ and any accompanying files contained herein (collectively, these “Software”). Use of these Software is exclusively subject to the Gyroscope Pool License, which is available at the provided link (the “Gyroscope Pool License”). These Software are not covered by the General Public License and do not confer any rights to the user other than the limited rights specified in the Gyroscope Pool License. A special hybrid license between Superluminal Labs Ltd and Balancer Labs OÜ governs Superluminal Labs Ltd's use of the Balancer Labs OÜ code Special License, which is available at the provided link. By using these Software, you agree to be bound by the terms and conditions of the Gyroscope Pool License. If you do not agree to all terms and conditions of the Gyroscope Pool License, do not use any of these Software.

balancer-sor's Issues

Reduce bundle size

From @gmbronco:

gm gents! @balancer-labs/sor package bundles the test and src folders. could you remove it from the build? it will save us a lot of bundle size (~200MB)

Question: when will this be done on-chain

Hey I am a bit confused about how smart order routing currently works. This repo seems to suggest this is done off chain. Do you guys know when Balancer v2 will do this order routing on chain?

Add Gyro2 v2 Pool

SOR cannot find pool ID

When trying to use sor.smartOrderRouter, it mis-computes the pool ID and fails.

Error log:

TypeError: Cannot read property 'spotPrice' of undefined
    at /Users/xianny/src/balancer/node_modules/@balancer-labs/sor/dist/sor.js:250:58
    at Array.forEach (<anonymous>)
    at getInputAmountsForEp (/Users/xianny/src/balancer/node_modules/@balancer-labs/sor/dist/sor.js:246:10)
    at /Users/xianny/src/balancer/node_modules/@balancer-labs/sor/dist/sor.js:22:21
    at Array.forEach (<anonymous>)
    at Object.exports.smartOrderRouter (/Users/xianny/src/balancer/node_modules/@balancer-labs/sor/dist/sor.js:19:19)
    at sor.getPoolsWithTokens.then.data (/Users/xianny/src/balancer/test.js:14:26)
    at process._tickCallback (internal/process/next_tick.js:68:7)

Code lifted from https://docs.balancer.finance/sor/development#example

// test.js
// dependencies": {
//     "@balancer-labs/sor": "^0.2.7",
//     "bignumber.js": "^9.0.0",
//     "ethers": "^4.0.47"
// }

const sor = require('@balancer-labs/sor');
const BigNumber = require('bignumber.js');
const ethers = require('ethers');


const MAX_UINT = ethers.constants.MaxUint256;

// MAINNET
const tokenIn = '0x6B175474E89094C44Da98b954EedeAC495271d0F' // DAI
const tokenOut = '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2' // WETH

sor.getPoolsWithTokens(tokenIn, tokenOut).then(data => {
    const poolData = sor.parsePoolData(data.pools, tokenIn, tokenOut);
    const sorSwaps = sor.smartOrderRouter(
        poolData,
        'swapExactIn',
        new BigNumber('10000000000000000000'),
        new BigNumber('10'),
        0
    );

});

Error is being thrown when this line returns balancer = undefined:

Pushing to NPM

Is there a reason this isn't pushed to npm? Or if it is, it isn't published under @balancer-labs. I'd like to use the latest version that follows the example code but unless I'm building it inside my project, seems to be unavailable.

gas inputs as params

gasPrice, gasPerTrade, outTokenEthPrice are currently hardcoded

these should be passed into linearizedSolution as parameters

Add min / max requirements

SOR needs to account for MIN_BALANCE, MAX_BALANCE, MAX_IN_RATIO, MAX_OUT_RATIO

Supporting Uniswap V3

I've figured out how to represent Uniswap V2 and Curve pools as Balancer pools. How would I got about implementing a Uniswap V3 pool within SOR? Let's assume I can perform the swap estimations synchronously/offchain.

Refactor input/output in SOR code context to something different to avoid confusion with tokenIn and tokenOut

Add config for Base

command line test

In this repository, I am getting whole code execution regardless What I command I am typing
What if I want to run specific file or function ...
whatever command I run it is running this line..

@balancer-labs/[email protected] test
TS_NODE_PROJECT='tsconfig.testing.json' nyc mocha -r ts-node/register test/*.spec.ts --timeout 20000

Use bignumber.js

Move all calculations to use bignumbers to prevent javascript math craziness

Handle unknown pool types gracefully

SOR pool fetching has started throwing errors the last few days since the pool type HighAmpComposableStable was added to the graph. Some errors from the API fetching pools from our main subgraph:

ERROR	Unknown pool type: HighAmpComposableStable 0xea912e1afa137c15f1638142e32f978e92fbce390000000000000000000003b4
ERROR	Unknown pool type: HighAmpComposableStable 0x1d1b44a4c5a047bdc9b3f06842566e5ea9c1966d0000000000000000000003b3

This is also currently happening on the Balancer App Frontend.

https://github.com/balancer-labs/balancer-sor/pull/304/ has been done to fix this error. But the bigger issue is that SOR should be able to gracefully handle new pool types and just ignore them instead of crashing, so that older versions of SOR don't break whenever we add a new pool type.

This issue is to create a test to reproduce error'ing with a pool with an unknown type and a fix for that test so it ignores the pool instead of crashing.

Typo in example-swapExactOut

According to what I understand for swapExactOut in the function getCostOutputToken we need to pass tokenIn. If so there is a typo in the below code. It should be USDC instead of DAI

https://github.com/balancer-labs/balancer-sor/blob/1d06567831ec688b98026b20057b8557b786daac/test/testScripts/example-swapExactOut.ts#L25

Swap Limit Error

Instead of throwing an error "Swap amount exceeds the pool limit" - exclude the pool from the pool from the path building. (and maybe log an error, so we know about it with a poolId)

fetchPools() issue with Polygon Mainnet

Hi,

Ethereum works great, but Polygon gives the following error when calling fetchPools().
Does anyone know how to make it work with Polygon as well?

2023-07-10 02:16:21 calling swaps.fetchPools()
2023-07-10 02:16:21 137 fetching pools...
Error: fetchPools(): Error: Issue with pool onchain data: Error: invalid BigNumber value (argument="value", value=undefined, code=INVALID_ARGUMENT, version=bignumber/5.7.0)

getSwaps() returnAmount mismatch with on-chain result

I recently updated from balancer-sor 2.0.0-beta.0 to 4.0.1-beta.13 to get off-chain quote. It used to work properly(matched on/off chain quote) before the update, and no logic has been changed apart from the upgrade. Followings are the code that I am using to call getSwap() function and error examples.

const swapInfo = await sor.getSwaps(token0Address, token1Address, SwapTypes.SwapExactIn, swapAmount, { gasPrice: BigNumber.from('40000000000'), maxPools: 4, poolTypeFilter: PoolFilter.All, forceRefresh: false, });

{ "poolId": "0x2f4eb100552ef93840d5adc30560e5513dfffacb000000000000000000000334", "failMessage": "should swap 1.0 USDT for bb-a-USDT", "errorMessage": "[BalancerV2-bb-a-USDT-USDT-0x2f4eb100552ef93840d5adc30560e5513dfffacb000000000000000000000334] expected: 0.996741477812543832 bb-a-USDT - actual: 0.996741471157526565 bb-a-USDT - error: -0.000000006655017267 bb-a-USDT: Expected \"996741471157526565\" to be equal 996741477812543832" }, { "poolId": "0x25accb7943fd73dda5e23ba6329085a3c24bfb6a000200000000000000000387", "failMessage": "should swap 1.0 wstETH for bb-a-USD", "errorMessage": "[BalancerV2-wstETH-bb-a-USD-0x25accb7943fd73dda5e23ba6329085a3c24bfb6a000200000000000000000387] expected: 1258.805945837242429336 bb-a-USD - actual: 1258.805945977795458677 bb-a-USD - error: 0.000000140553029341 bb-a-USD: Expected \"1258805945977795458677\" to be equal 1258805945837242429336" },

Would be much appreciative if the team can provide some suspicious point that I can take a look.

Thank you in advance!

Add calculation tests

Use a variety of sample pool data and compare to python SOR results