Skip to content

Commit

Permalink
Merge pull request #161 from balancer/router-updates
Browse files Browse the repository at this point in the history 
Composite Liquidity Router
  • Loading branch information
@mkflow27
mkflow27 authored Oct 17, 2024
2 parents 8b8b31b + f9c0d56 commit f41ef25
Show file tree
Hide file tree
Showing 4 changed files with 298 additions and 4 deletions.
4 changes: 2 additions & 2 deletions docs/concepts/router/overview.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,10 +32,10 @@ Balancer has developed, audited and deployed Router contracts with the goal of p
- [Code](https://github.com/balancer/balancer-v3-monorepo/blob/main/pkg/vault/contracts/BatchRouter.sol)

### Composite Liquidity Router
- ERC4626 buffer and nested swaps
- Liquidity operations on pools containing ERC4626 tokens, and nested pools (i.e. pools containing the BPT of other pools)
- [API](../../developer-reference/contracts/composite-liquidity-router-api.md)
- [Code](https://github.com/balancer/balancer-v3-monorepo/blob/main/pkg/vault/contracts/CompositeLiquidityRouter.sol)

Additionally, all Routers expose [Query Functions](./queries.md) providing the ability to query the result of an operation using the latest onchain state.
Additionally all Routers expose [Query Functions](./queries.md) providing the ability to query the result of an operation using the latest onchain state.

Latest deployment of the Routers can be found in the [deployments section](/developer-reference/contracts/deployment-addresses/mainnet.html).
294 changes: 294 additions & 0 deletions docs/developer-reference/contracts/composite-liquidity-router-api.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,294 @@
---
order: 1
title: Composite Liquidity Router API
---

# Composite Liquidity Router API

The Composite Liquidity Router can be used to interact with Balancer onchain via [state changing](/concepts/router/onchain-api/composite-liquidity-router-api.html#state-changing-functions) operations or used to [query operations](/concepts/router/onchain-api/composite-liquidity-router-api.html#query-functions) in an off-chain context.

This is not the final version; more operations will likely be added.

## State-changing functions

## Composite Liquidity operations on ERC4626 pools

### `addLiquidityUnbalancedToERC4626Pool`

```solidity
function addLiquidityUnbalancedToERC4626Pool(
address pool,
uint256[] memory exactUnderlyingAmountsIn,
uint256 minBptAmountOut,
bool wethIsEth,
bytes memory userData
) external payable returns (uint256 bptAmountOut);
```
Add arbitrary amounts of underlying tokens to an ERC4626 pool through the buffer. An "ERC4626 pool" contains IERC4626 yield-bearing tokens (e.g., waDAI).

**Parameters:**

| Name | Type | Description |
|------------|------------------------------------|----------------------------------------------------------------------------------------------|
| pool | address | Address of the liquidity pool |
| exactUnderlyingAmountsIn | uint256[] memory | Exact amounts of underlying tokens in, sorted in token registration order of wrapped tokens in the pool |
| minBptAmountOut | uint256 | Minimum amount of pool tokens to be received |
| wethIsEth | bool | If true, incoming ETH will be wrapped to WETH and outgoing WETH will be unwrapped to ETH |
| userData | bytes calldata | Additional (optional) data required for the operation |

**Returns:**

| Name | Type | Description |
|------------------|------------------------|----------------------------------------------------------------------------------------------|
| bptAmountOut | uint256 | Actual amount of pool tokens received |

### `addLiquidityProportionalToERC4626Pool`

```solidity
function addLiquidityProportionalToERC4626Pool(
address pool,
uint256[] memory maxUnderlyingAmountsIn,
uint256 exactBptAmountOut,
bool wethIsEth,
bytes memory userData
) external payable returns (uint256[] memory underlyingAmountsIn);
```
Add proportional amounts of underlying tokens to an ERC4626 pool through the buffer. An "ERC4626 pool" contains IERC4626 yield-bearing tokens (e.g., waDAI).

**Parameters:**

|------------|------------------------------------|----------------------------------------------------------------------------------------------|
| pool | address | Address of the liquidity pool |
| maxUnderlyingAmountsIn | uint256[] memory | Maximum amounts of underlying tokens in, sorted in token registration order of wrapped tokens in the pool |
| exactBptAmountOut | uint256 | Exact amount of pool tokens to be received |
| wethIsEth | bool | If true, incoming ETH will be wrapped to WETH and outgoing WETH will be unwrapped to ETH |
| userData | bytes calldata | Additional (optional) data required for the operation |

**Returns:**

| Name | Type | Description |
|------------------|------------------------|----------------------------------------------------------------------------------------------|
| underlyingAmountsIn | uint256[] memory | Calculated amounts of input tokens corresponding to the first step of each given path |

### `removeLiquidityProportionalFromERC4626Pool`

```solidity
function removeLiquidityProportionalFromERC4626Pool(
address pool,
uint256 exactBptAmountIn,
uint256[] memory minUnderlyingAmountsOut,
bool wethIsEth,
bytes memory userData
) external payable returns (uint256[] memory underlyingAmountsOut);
```
Remove proportional amounts of underlying from an ERC4626 pool, burning an exact pool token amount. An "ERC4626 pool" contains IERC4626 yield-bearing tokens (e.g., waDAI).

**Parameters:**

|------------|------------------------------------|----------------------------------------------------------------------------------------------|
| pool | address | Address of the liquidity pool |
| exactBptAmountIn | uint256 | Exact amount of pool tokens provided |
| minUnderlyingAmountsOut | uint256[] memory | Minimum amounts of underlying tokens out, sorted in token registration order of wrapped tokens in the pool |
| wethIsEth | bool | If true, incoming ETH will be wrapped to WETH and outgoing WETH will be unwrapped to ETH |
| userData | bytes calldata | Additional (optional) data required for the operation |

**Returns:**

| Name | Type | Description |
|------------------|------------------------|----------------------------------------------------------------------------------------------|
| underlyingAmountsOut | uint256[] memory | Actual amounts of tokens received, sorted in token registration order of wrapped wrapped tokens in the pool |

## Composite Liquidity operations on nested pools

### `addLiquidityUnbalancedNestedPool`

```solidity
function addLiquidityUnbalancedNestedPool(
address parentPool,
address[] memory tokensIn,
uint256[] memory exactAmountsIn,
uint256 minBptAmountOut,
bytes memory userData
) external returns (uint256 bptAmountOut);
```
Adds liquidity unbalanced to a nested pool. 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 given, so the user must specify the preferred order to inform the token in amounts.

**Parameters:**

| Name | Type | Description |
|------------|------------------------------------|----------------------------------------------------------------------------------------------|
| parentPool | address | Address of the highest level pool (which contains BPTs of other pools) |
| tokensIn | uint256[] memory | Input token addresses, sorted by user preference. `tokensIn` array must have all tokens from child pools and all tokens that are not BPTs from the nested pool (parent pool). |
| exactAmountsIn | uint256[] memory | Amount of each underlying token in, sorted according to tokensIn array |
| minBptAmountOut | uint256 | Expected minimum amount of parent pool tokens to receive |
| userData | bytes calldata | Additional (optional) data required for the operation |

**Returns:**

| Name | Type | Description |
|------------------|------------------------|----------------------------------------------------------------------------------------------|
| bptAmountOut | uint256 | Expected amount of parent pool tokens to receive |

### `removeLiquidityProportionalNestedPool`

```solidity
function removeLiquidityProportionalNestedPool(
address parentPool,
uint256 exactBptAmountIn,
address[] memory tokensOut,
uint256[] memory minAmountsOut,
bytes memory userData
) external returns (uint256[] memory amountsOut);
```
Adds liquidity unbalanced to a nested pool. 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 given, so the user must specify the preferred order to inform the token in amounts.

**Parameters:**

| Name | Type | Description |
|------------|------------------------------------|----------------------------------------------------------------------------------------------|
| parentPool | address | Address of the highest level pool (which contains BPTs of other pools) |
| exactBptAmountIn | uint256 | Exact amount of `parentPool` tokens provided |
| tokensOut | uint256[] memory | Output token addresses, sorted by user preference. `tokensOut` array must have all tokens from child pools and all tokens that are not BPTs from the nested pool (parent pool). If not all tokens are informed, balances are not settled and the operation reverts. Tokens that repeat must be informed only once. |
| minAmountsOut | uint256[] memory | Amount of each underlying token in, sorted according to tokensIn array |
| userData | bytes calldata | Additional (optional) data required for the operation |

**Returns:**

| Name | Type | Description |
|------------------|------------------------|----------------------------------------------------------------------------------------------|
| amountsOut | uint256[] memory | Actual amounts of tokens received, parallel to `tokensOut` |

## Queries

### `queryAddLiquidityUnbalancedToERC4626Pool`

```solidity
function queryAddLiquidityUnbalancedToERC4626Pool(
address pool,
uint256[] memory exactUnderlyingAmountsIn,
bytes memory userData
) external returns (uint256 bptAmountOut);
```
Query an `addLiquidityUnbalancedToERC4626Pool` operation.

**Parameters:**

| Name | Type | Description |
|------------|------------------------------------|----------------------------------------------------------------------------------------------|
| pool | address | Address of the liquidity pool |
| exactUnderlyingAmountsIn | uint256[] memory | Exact amounts of underlying tokens in, sorted in token registration order of wrapped tokens in the pool |
| userData | bytes calldata | Additional (optional) data required for the operation |

**Returns:**

| Name | Type | Description |
|------------------|------------------------|----------------------------------------------------------------------------------------------|
| bptAmountOut | uint256 | Actual amount of pool tokens received |

### `queryAddLiquidityProportionalToERC4626Pool`

```solidity
function queryAddLiquidityProportionalToERC4626Pool(
address pool,
uint256 exactBptAmountOut,
bytes memory userData
) external returns (uint256[] memory underlyingAmountsIn);
```
Query an `addLiquidityProportionalToERC4626Pool` operation.

**Parameters:**

|------------|------------------------------------|----------------------------------------------------------------------------------------------|
| pool | address | Address of the liquidity pool |
| exactBptAmountOut | uint256 | Exact amount of pool tokens to be received |
| userData | bytes calldata | Additional (optional) data required for the operation |

**Returns:**

| Name | Type | Description |
|------------------|------------------------|----------------------------------------------------------------------------------------------|
| underlyingAmountsIn | uint256[] memory | Calculated amounts of input tokens corresponding to the first step of each given path |

### `queryRemoveLiquidityProportionalFromERC4626Pool`

```solidity
function queryRemoveLiquidityProportionalFromERC4626Pool(
address pool,
uint256 exactBptAmountIn,
bytes memory userData
) external returns (uint256[] memory underlyingAmountsOut);
```
Query a `removeLiquidityProportionalFromERC4626Pool` operation.

**Parameters:**

|------------|------------------------------------|----------------------------------------------------------------------------------------------|
| pool | address | Address of the liquidity pool |
| exactBptAmountIn | uint256 | Exact amount of pool tokens provided |
| userData | bytes calldata | Additional (optional) data required for the operation |

**Returns:**

| Name | Type | Description |
|------------------|------------------------|----------------------------------------------------------------------------------------------|
| underlyingAmountsOut | uint256[] memory | Actual amounts of tokens received, sorted in token registration order of wrapped wrapped tokens in the pool |


### `queryAddLiquidityUnbalancedNestedPool`

```solidity
function queryAddLiquidityUnbalancedNestedPool(
address pool,
address[] memory tokensIn,
uint256[] memory exactAmountsIn,
bytes memory userData
) external returns (uint256 bptAmountOut);
```
Query an `addLiquidityUnbalancedNestedPool` operation.

**Parameters:**

| Name | Type | Description |
|------------|------------------------------------|----------------------------------------------------------------------------------------------|
| pool | address | Address of the liquidity pool |
| tokensIn | address[] memory | Input token addresses, sorted by user preference. `tokensIn` array must have all tokens from child pools and all tokens that are not BPTs from the nested pool (parent pool). |
| exactAmountsIn | uint256[] memory | Amount of each underlying token in, sorted according to tokensIn array |
| userData | bytes calldata | Additional (optional) data required for the operation |

**Returns:**

| Name | Type | Description |
|------------------|------------------------|----------------------------------------------------------------------------------------------|
| bptAmountOut | uint256 | Expected amount of parent pool tokens to receive |

### `queryRemoveLiquidityProportionalNestedPool`

```solidity
function queryRemoveLiquidityProportionalNestedPool(
address parentPool,
uint256 exactBptAmountIn,
address[] memory tokensOut,
bytes memory userData
) external returns (uint256[] memory amountsOut);
```
Query a `removeLiquidityProportionalNestedPool` operation.

**Parameters:**

| Name | Type | Description |
|------------|------------------------------------|----------------------------------------------------------------------------------------------|
| parentPool | address | Address of the highest level pool (which contains BPTs of other pools) |
| exactBptAmountIn | uint256 | Exact amount of `parentPool` tokens provided |
| tokensOut | address[] memory | Output token addresses, sorted by user preference. `tokensOut` array must have all tokens from child pools and all tokens that are not BPTs from the nested pool (parent pool). If not all tokens are informed, balances are not settled and the operation reverts. Tokens that repeat must be informed only once. |
| userData | bytes calldata | Additional (optional) data required for the operation |

**Returns:**

| Name | Type | Description |
|------------------|------------------------|----------------------------------------------------------------------------------------------|
| amountsOut | uint256[] memory | Actual amounts of tokens received, parallel to `tokensOut` |


## Router common

See the bottom of the [Router](./router-api.md#router-common) for functions common to `Router`, `BatchRouter`, and `CompositeLiquidityRouter`.
2 changes: 1 addition & 1 deletion docs/developer-reference/contracts/router-api.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -757,7 +757,7 @@ Queries an `swapSingleTokenExactOut` operation without actually executing it.

## Router common

These functions are shared between the `Router` and `BatchRouter` (defined in `RouterCommon`).
These functions are shared between the `Router`, `BatchRouter`, and `CompositeLiquidityRouter` (defined in `RouterCommon`).

### `permitBatchAndCall`

Expand Down
2 changes: 1 addition & 1 deletion docs/partner-onboarding/onboarding-overview/introduction.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ With a vastly simplified developer experience, 100% boosted pools, LST base pair
Want to learn more about Balancer? Click [here](../../concepts/core-concepts/introduction.md)
:::

### Unique AMM Designs & Products
### Unique AMM Designs and Products

Balancer Technology provides innovative AMM designs such as

Expand Down

0 comments on commit f41ef25

Please sign in to comment.