# Composite Liquidity Router API

The Composite Liquidity Router can be used to interact with Balancer onchain via state changing operations or used to query operations in an off-chain context.

Specialized router for two complex scenarios:

1. ERC4626 Pools: Pools containing yield-bearing tokens (e.g., waDAI, waUSDC)
2. Nested Pools: Pools where one or more tokens are BPTs from other pools

# State-changing functions

# ERC4626 Pool Operations

ERC4626 pools contain wrapped yield-bearing tokens. This router allows you to interact with them using only underlying tokens, automatically handling wrapping/unwrapping through Vault buffers.

# addLiquidityUnbalancedToERC4626Pool

function addLiquidityUnbalancedToERC4626Pool(
    address pool,
    bool[] memory wrapUnderlying,
    uint256[] memory exactAmountsIn,
    uint256 minBptAmountOut,
    bool wethIsEth,
    bytes memory userData
) external payable returns (uint256 bptAmountOut);

Adds liquidity to an ERC4626 pool using underlying or wrapped tokens.

Example: Add liquidity to a [waDAI, waUSDC] pool using only DAI and USDC. The router automatically:

1. Swaps DAI for waDAI through the Vault buffer
2. Swaps USDC for waUSDC through the Vault buffer
3. Adds liquidity to the pool

Note: Ensure that any buffers associated with the wrapped tokens in the ERC4626 pool have been initialized before initializing or adding liquidity to the "parent" pool, and also make sure limits are set properly.

Parameters:

Returns:

# addLiquidityProportionalToERC4626Pool

function addLiquidityProportionalToERC4626Pool(
    address pool,
    bool[] memory wrapUnderlying,
    uint256[] memory maxAmountsIn,
    uint256 exactBptAmountOut,
    bool wethIsEth,
    bytes memory userData
) external payable returns (uint256[] memory amountsIn);

Adds liquidity proportionally to an ERC4626 pool using underlying or wrapped tokens.

Note: Ensure that any buffers associated with the wrapped tokens in the ERC4626 pool have been initialized before initializing or adding liquidity to the "parent" pool, and also make sure limits are set properly.

Parameters:

Returns:

# removeLiquidityProportionalFromERC4626Pool

function removeLiquidityProportionalFromERC4626Pool(
    address pool,
    bool[] memory unwrapWrapped,
    uint256 exactBptAmountIn,
    uint256[] memory minAmountsOut,
    bool wethIsEth,
    bytes memory userData
) external payable returns (uint256[] memory amountsOut);

Removes liquidity proportionally from an ERC4626 pool, receiving underlying or wrapped tokens.

Parameters:

Returns:

# Nested Pool Operations

Nested pools contain BPTs from other pools as tokens. This router handles the complexity of traversing multiple pool levels.

Important: Pools with "overlapping" tokens (where both parent and child pools contain the same token) are not supported.

# addLiquidityUnbalancedNestedPool

function addLiquidityUnbalancedNestedPool(
    address parentPool,
    address[] memory tokensIn,
    uint256[] memory exactAmountsIn,
    address[] memory tokensToWrap,
    uint256 minBptAmountOut,
    bool wethIsEth,
    bytes memory userData
) external payable returns (uint256 bptAmountOut);

Adds liquidity to a nested pool using only the leaf tokens (tokens from child pools).

Example:

• Parent pool: [BPT_A, BPT_B, USDC]
• Child pool A: [DAI, USDT]
• Child pool B: [WETH, WBTC]
• tokensIn could be: [DAI, USDT, WETH, WBTC, USDC]

The router:

1. Adds DAI and USDT to pool A to get BPT_A
2. Adds WETH and WBTC to pool B to get BPT_B
3. Adds BPT_A, BPT_B, and USDC to parent pool

Note: A nested pool is one in which one or more tokens are BPTs from another pool (child pool). Since there are multiple pools involved, the token order is not well-defined, and must be specified by the caller. If the parent or nested pools contain ERC4626 tokens that appear in the tokensToWrap list, they will be wrapped and their underlying tokens pulled as input, and expected to appear in tokensIn. Otherwise, they will be treated as regular tokens.

Parameters:

Returns:

# removeLiquidityProportionalNestedPool

function removeLiquidityProportionalNestedPool(
    address parentPool,
    uint256 exactBptAmountIn,
    address[] memory tokensOut,
    uint256[] memory minAmountsOut,
    address[] memory tokensToUnwrap,
    bool wethIsEth,
    bytes memory userData
) external payable returns (uint256[] memory amountsOut);

Removes liquidity from a nested pool, receiving the leaf tokens.

The router automatically:

1. Exits the parent pool to get child BPTs
2. Exits each child pool to get leaf tokens
3. Unwraps ERC4626 tokens if requested

Note: A nested pool is one in which one or more tokens are BPTs from another pool (child pool). Since there are multiple pools involved, the token order is not well-defined, and must be specified by the caller. If the parent or nested pools contain ERC4626 tokens that appear in the tokensToUnwrap list, they will be unwrapped and their underlying tokens sent to the output. Otherwise, they will be treated as regular tokens.

Parameters:

Returns:

# Queries

# queryAddLiquidityUnbalancedToERC4626Pool

function queryAddLiquidityUnbalancedToERC4626Pool(
    address pool,
    bool[] memory wrapUnderlying,
    uint256[] memory exactAmountsIn,
    address sender,
    bytes memory userData
) external returns (uint256 bptAmountOut);

Queries an addLiquidityUnbalancedToERC4626Pool operation without actually executing it.

Parameters:

Returns:

# queryAddLiquidityProportionalToERC4626Pool

function queryAddLiquidityProportionalToERC4626Pool(
    address pool,
    bool[] memory wrapUnderlying,
    uint256 exactBptAmountOut,
    address sender,
    bytes memory userData
) external returns (uint256[] memory amountsIn);

Queries an addLiquidityProportionalToERC4626Pool operation without actually executing it.

Parameters:

Returns:

# queryRemoveLiquidityProportionalFromERC4626Pool

function queryRemoveLiquidityProportionalFromERC4626Pool(
    address pool,
    bool[] memory unwrapWrapped,
    uint256 exactBptAmountIn,
    address sender,
    bytes memory userData
) external returns (uint256[] memory amountsOut);

Queries a removeLiquidityProportionalFromERC4626Pool operation without actually executing it.

Parameters:

Returns:

# queryAddLiquidityUnbalancedNestedPool

function queryAddLiquidityUnbalancedNestedPool(
    address parentPool,
    address[] memory tokensIn,
    uint256[] memory exactAmountsIn,
    address[] memory tokensToWrap,
    address sender,
    bytes memory userData
) external returns (uint256 bptAmountOut);

Queries an addLiquidityUnbalancedNestedPool operation without actually executing it.

Parameters:

Returns:

# queryRemoveLiquidityProportionalNestedPool

function queryRemoveLiquidityProportionalNestedPool(
    address parentPool,
    uint256 exactBptAmountIn,
    address[] memory tokensOut,
    address[] memory tokensToUnwrap,
    address sender,
    bytes memory userData
) external returns (uint256[] memory amountsOut);

Queries a removeLiquidityProportionalNestedPool operation without actually executing it.

Parameters:

Returns: