Merge pull request #180 from balancer/buffer-updates

Cumulative update, mostly of buffer functionality

docs/concepts/core-concepts/architecture.md

@@ -9,7 +9,7 @@ order: 1
 
 The Balancer protocol architecture comprises three primary components, each strategically designed to enhance flexibility and minimize the intricacies involved in constructing pools. By distributing responsibilities across these components, Balancer simplifies pool development, empowering builders to focus on innovation rather than grappling with complex code.
 
-- Router: Serves as the user's gateway to the protocol, offering straightforward interfaces for executing operations. (This includes the basic Router, BatchRouter, and CompositeLiquidityRouter.)
+- Router: Serves as the user's gateway to the protocol, offering straightforward interfaces for executing operations. (This includes the basic Router, BatchRouter, BufferRouter, and CompositeLiquidityRouter.)
 - Vault: Centralizes liquidity operations and manages accounting, streamlining the handling of token balances across multiple pools.
 - Pool: Exposes precise pool mathematics through invariant calculations, enabling developers to harness powerful functionalities without delving into intricate details.
 

docs/concepts/router/overview.md

@@ -31,6 +31,11 @@ Balancer has developed, audited and deployed Router contracts with the goal of p
 - [API](../../developer-reference/contracts/batch-router-api.md)
 - [Code](https://github.com/balancer/balancer-v3-monorepo/blob/main/pkg/vault/contracts/BatchRouter.sol)
 
+### Buffer Router
+- Liquidity operations on buffers
+- [API](../../developer-reference/contracts/buffer-router-api.md)
+- [Code](https://github.com/balancer/balancer-v3-monorepo/blob/main/pkg/vault/contracts/BufferRouter.sol)
+
 ### Composite Liquidity Router
 - 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)

docs/concepts/router/queries.md

@@ -25,6 +25,13 @@ The detailed Router API description can be found in the [Batch Router API sectio
 - `querySwapExactIn`
 - `querySwapExactOut`
 
+## Buffer Router queries
+The detailed Buffer Router API description can be found in the [Buffer Router API section](/concepts/router/onchain-api/buffer-router-api.html).
+
+- `queryInitializeBuffer`
+- `queryAddLiquidityToBuffer`
+- `queryRemoveLiquidityToBuffer`
+
 ## Composite Liquidity Router queries
 
 The detailed Router API description can be found in the [Composite Liquidity Router API section](/concepts/router/onchain-api/composite-liquidity-router-api.html).

docs/concepts/vault/buffer.md

@@ -24,18 +24,24 @@ If your organization is a DAO and you're seeking to enhance liquidity for your E
 
 
 ## Adding liquidity to a buffer
-Liquidity can be added to a buffer for a specific token pair. This is done by invoking the `addLiquidityToBuffer` function, where you designate the ERC4626 Token as the buffer reference. Note that for security reasons, liquidity can only be added (or removed) proportionally. It's important to note that a buffer can still function with zero liquidity. It can be used to wrap and unwrap assets, meaning that even an empty buffer can facilitate swaps through the Vault.
+Liquidity can be added to a buffer for a specific token pair. This is done by invoking the `addLiquidityToBuffer` function in the [Buffer Router](https://github.com/balancer/balancer-v3-monorepo/blob/main/pkg/vault/contracts/BufferRouter.sol), where you designate the ERC4626 Token as the buffer reference. Note that for security reasons, liquidity can only be added (or removed) proportionally. It's important to note that a buffer can still function with zero liquidity. It can be used to wrap and unwrap assets, meaning that even an empty buffer can facilitate swaps through the Vault.
 ```solidity
 /**
- * @notice Adds liquidity to a yield-bearing buffer (one of the Vault's internal ERC4626 token buffers).
+ * @notice Adds liquidity proportionally to an internal ERC4626 buffer in the Vault.
+ * @dev Requires the buffer to be initialized beforehand. Restricting adds to proportional simplifies the Vault
+ * code, avoiding rounding issues and minimum amount checks. It is possible to add unbalanced by interacting
+ * with the wrapper contract directly.
  * @param wrappedToken Address of the wrapped token that implements IERC4626
- * @param exactSharesToIssue The value in underlying tokens that `sharesOwner` wants to add to the buffer,
- * in underlying token decimals
- * @return amountUnderlyingRaw Amount of underlying tokens deposited into the buffer
- * @return amountWrappedRaw Amount of wrapped tokens deposited into the buffer
-*/
+ * @param maxAmountUnderlyingIn Maximum amount of underlying tokens to add to the buffer. It is expressed in underlying token native decimals
+ * @param maxAmountWrappedIn Maximum amount of wrapped tokens to add to the buffer. It is expressed in wrapped token native decimals
+ * @param exactSharesToIssue The amount of shares that `sharesOwner` wants to add to the buffer, in underlying token decimals
+ * @return amountUnderlyingIn Amount of underlying tokens deposited into the buffer
+ * @return amountWrappedIn Amount of wrapped tokens deposited into the buffer
+ */
 function addLiquidityToBuffer(
     IERC4626 wrappedToken,
+    uint256 maxAmountUnderlyingIn,
+    uint256 maxAmountWrappedIn,
     uint256 exactSharesToIssue
 ) external returns (uint256 amountUnderlyingRaw, uint256 amountWrappedRaw);
 ```
@@ -60,14 +66,18 @@ In order to keep it permissionless, `removeLiquidityFromBuffer` was moved to the
  * - The buffer needs to have some liquidity and have its asset registered in `_bufferAssets` storage.
  *
  * @param wrappedToken Address of the wrapped token that implements IERC4626
- * @param sharesToRemove Amount of shares to remove from the buffer. Cannot be greater than sharesOwner's
- * total shares. It is expressed in underlying token native decimals.
+ * @param sharesToRemove Amount of shares to remove from the buffer. Cannot be greater than sharesOwner's total shares. It is expressed in underlying token native decimals
+ * @param minAmountUnderlyingOutRaw Minimum amount of underlying tokens to receive from the buffer. It is expressed in underlying token native decimals
+ * @param minAmountWrappedOutRaw Minimum amount of wrapped tokens to receive from the buffer. It is expressed in
+ * wrapped token native decimals
  * @return removedUnderlyingBalanceRaw Amount of underlying tokens returned to the user
  * @return removedWrappedBalanceRaw Amount of wrapped tokens returned to the user
-*/
+ */
 function removeLiquidityFromBuffer(
     IERC4626 wrappedToken,
-    uint256 sharesToRemove
+    uint256 sharesToRemove,
+    uint256 minAmountUnderlyingOutRaw,
+    uint256 minAmountWrappedOutRaw
 ) external returns (uint256 removedUnderlyingBalanceRaw, uint256 removedWrappedBalanceRaw);
 ``` 
 

docs/concepts/vault/erc20-multi-token.md

@@ -39,9 +39,13 @@ function _approve(address token, address owner, address spender, uint256 amount)
     _allowances[token][owner][spender] = amount;
     
     emit Approval(token, owner, spender, amount);
-    // We also emit the "approve" event on the pool token to ensure full compliance with ERC20 standards.
 
-    BalancerPoolToken(token).emitApproval(owner, spender, amount);
+    // We also emit the "approve" event on the pool token to ensure full compliance with the ERC20 standard.
+    // If this function fails we keep going, as this is used in recovery mode.
+    // Well-behaved pools will just emit an event here, so they should never fail.
+    try BalancerPoolToken(pool).emitApproval(owner, spender, amount) {} catch {
+        // solhint-disable-previous-line no-empty-blocks
+    }
 }
 ```
 

docs/developer-reference/contracts/abi/README.md

@@ -9,5 +9,6 @@ You can find relevant Abis here:
 
 - [Router](./router.md)
 - [Batch Router](./batch-router.md)
+- [Buffer Router](./buffer-router.md)
 - [Composite Liquidity Router](./composite-liquidity-router.md)