Merge pull request #137 from balancer/audit-updates-v2

Second round of audit updates

docs/concepts/vault/buffer.md

@@ -68,8 +68,7 @@ The `pool` param in this particular case is the wrapped Tokens entrypoint. Meani
 struct SwapPathStep {
     address pool;
     IERC20 tokenOut;
-    // if true, pool is a yield-bearing token buffer. Used to wrap/unwrap tokens if pool doesn't have
-    // enough liquidity
+    // If true, pool is an ERC4626 buffer. Used to wrap/unwrap tokens if pool doesn't have enough liquidity.
     bool isBuffer;
 }
 ```
@@ -82,9 +81,9 @@ In the case of trading DAI to USDC via (DAI-waDAI Buffer, waDAI - waUSDC Boosted
 ```solidity
 struct SwapPathExactAmountIn {
         IERC20 tokenIn;
-        // for each step:
-        // if tokenIn == pool, use removeLiquidity SINGLE_TOKEN_EXACT_IN
-        // if tokenOut == pool, use addLiquidity UNBALANCED
+        // For each step:
+        // If tokenIn == pool, use removeLiquidity SINGLE_TOKEN_EXACT_IN.
+        // If tokenOut == pool, use addLiquidity UNBALANCED.
         SwapPathStep[] steps;
         uint256 exactAmountIn;
         uint256 minAmountOut;

docs/concepts/vault/transient-accounting.md

@@ -16,8 +16,8 @@ Upon activation of the transient state, the vault is unlocked and permissions to
 - `addLiquidity`: Adds one or more tokens to a liquidity pool.
 - `removeLiquidity`: Removes one or more tokens from a liquidity pool.
 - `erc4626BufferWrapOrUnwrap`: Wraps/unwraps tokens based on provided parameters.
-- `addLiquidityToBuffer`: Adds liquidity to a yield-bearing token buffer.
-- `removeLiquidityFromBuffer`: Removes liquidity from a yield-bearing token buffer (permissioned).
+- `addLiquidityToBuffer`: Adds liquidity to an ERC4626 buffer.
+- `removeLiquidityFromBuffer`: Removes liquidity from an ERC4626 buffer.
 - `initialize`: Initialize a liquidity pool.
 - `removeLiquidityRecovery`: Removes liquidity proportionally, burning an exact pool token amount (only in Recovery Mode).
 

docs/developer-reference/contracts/router-api.md

@@ -406,18 +406,18 @@ Executes a swap operation specifying an exact output token amount.
 | amountIn    | uint256   | Calculated amount of input tokens to be sent in exchange for the requested output tokens |
 
 
-## Yield-bearing token buffers
+## ERC4626 Buffers
 
-### `addLiquidityToBuffer`
+### `initializeBuffer`
 
 ```solidity
-function addLiquidityToBuffer(
+function initializeBuffer(
     IERC4626 wrappedToken,
     uint256 amountUnderlyingRaw,
     uint256 amountWrappedRaw
 ) external returns (uint256 issuedShares);
 ```
-Adds liquidity to a yield-bearing buffer (one of the Vault's internal ERC4626 token buffers).
+Adds liquidity for the first time to one of the Vault's internal ERC4626 buffers. Buffer operations will revert until the buffer is initialized.
 
 **Parameters:**
 
@@ -426,37 +426,38 @@ Adds liquidity to a yield-bearing buffer (one of the Vault's internal ERC4626 to
 | wrappedToken  | IERC4626  | Address of the wrapped token that implements IERC4626 |
 | amountUnderlyingRaw  | uint256  | Amount of underlying tokens that will be deposited into the buffer |
 | amountWrappedRaw  | uint256  | Amount of wrapped tokens that will be deposited into the buffer |
-| sharesOwner  | address  | Address of the contract that will own the liquidity. Only this contract will be able to remove liquidity from the buffer |
 
 **Returns:**
 
 | Name  | Type  | Description  |
 |---|---|---|
 | issuedShares  | uint256  | The amount of tokens sharesOwner has in the buffer, denominated in underlying tokens (This is the BPT of an internal ERC4626 token buffer) |
 
-### `removeLiquidityFromBuffer`
+
+### `addLiquidityToBuffer`
 
 ```solidity
-function removeLiquidityFromBuffer(
+function addLiquidityToBuffer(
     IERC4626 wrappedToken,
-    uint256 sharesToRemove
-) external returns (uint256 removedUnderlyingBalanceRaw, uint256 removedWrappedBalanceRaw);
+    uint256 amountUnderlyingRaw,
+    uint256 amountWrappedRaw
+) external returns (uint256 issuedShares);
 ```
-Removes liquidity from a yield-bearing token buffer (one of the Vault's internal ERC4626 token buffers).
+Adds liquidity to a yield-bearing buffer (one of the Vault's internal ERC4626 token buffers).
 
 **Parameters:**
 
 | Name  | Type  | Description  |
 |---|---|---|
-| wrappedToken  | IERC4626  | Address of a wrapped token that implements IERC4626 |
-| sharesToRemove  | uint256  | Amount of shares to remove from the buffer. Cannot be greater than sharesOwner total shares |
+| wrappedToken  | IERC4626  | Address of the wrapped token that implements IERC4626 |
+| amountUnderlyingRaw  | uint256  | Amount of underlying tokens that will be deposited into the buffer |
+| amountWrappedRaw  | uint256  | Amount of wrapped tokens that will be deposited into the buffer |
 
 **Returns:**
 
 | Name  | Type  | Description  |
 |---|---|---|
-| removedUnderlyingBalanceRaw  | uint256  | Amount of underlying tokens returned to the user |
-| removedWrappedBalanceRaw  | uint256  | Amount of wrapped tokens returned to the user |
+| issuedShares  | uint256  | The amount of tokens sharesOwner has in the buffer, denominated in underlying tokens (This is the BPT of an internal ERC4626 token buffer) |
 
 ## Queries
 

docs/developer-reference/contracts/vault-api.md

@@ -422,7 +422,8 @@ This `VaultExtension` function gets the current bpt rate of a pool, by dividing
 |---|---|---|
 | rate  | uint256  | BPT rate  |
 
-## Yield-bearing token buffers
+## ERC4626 Buffers
+
 ### `erc4626BufferWrapOrUnwrap`
 
 ```solidity
@@ -460,16 +461,38 @@ function unpauseVaultBuffers() external;
 ```
 This `VaultAdmin` function unpauses native vault buffers globally. When buffers are paused, it's not possible to add liquidity or wrap/unwrap tokens using Vault's `erc4626BufferWrapOrUnwrap` primitive. However, it's still possible to remove liquidity. This is a permissioned call.
 
+### `initializeBuffer`
+
+```solidity
+function initializeBuffer(
+    IERC4626 wrappedToken,
+    uint256 amountUnderlyingRaw,
+    uint256 amountWrappedRaw,
+    address sharesOwner
+) external returns (uint256 issuedShares);
+```
+This `VaultAdmin` function adds liquidity to an internal ERC4626 buffer in the Vault for the first time. And operations involving the buffer will revert until it is initialized.
+
+**Parameters:**
+
+| Name  | Type  | Description  |
+|---|---|---|
+| wrappedToken  | IERC4626  | Address of the wrapped token that implements IERC4626  |
+| amountUnderlyingRaw  | uint256  | Amount of underlying tokens that will be deposited into the buffer  |
+| amountWrappedRaw  | uint256  | Amount of wrapped tokens that will be deposited into the buffer  |
+| sharesOwner  | address  | Address of the contract that will own the liquidity. Only this contract will be able to remove liquidity from the buffer |
+
 ### `addLiquidityToBuffer`
 
 ```solidity
 function addLiquidityToBuffer(
     IERC4626 wrappedToken,
     uint256 amountUnderlyingRaw,
-    uint256 amountWrappedRaw
+    uint256 amountWrappedRaw,
+    address sharesOwner
 ) external returns (uint256 issuedShares);
 ```
-This `VaultAdmin` function adds liquidity to a yield-bearing token buffer (linear pool embedded in the vault).
+This `VaultAdmin` function adds liquidity to an internal ERC4626 buffer in the Vault. Reverts if the buffer has not been initialized.
 
 **Parameters:**
 
@@ -478,26 +501,24 @@ This `VaultAdmin` function adds liquidity to a yield-bearing token buffer (linea
 | wrappedToken  | IERC4626  | Address of the wrapped token that implements IERC4626  |
 | amountUnderlyingRaw  | uint256  | Amount of underlying tokens that will be deposited into the buffer  |
 | amountWrappedRaw  | uint256  | Amount of wrapped tokens that will be deposited into the buffer  |
-| sharesOwner  | address  | Address of contract that will own the deposited liquidity. Only this contract will be able to remove liquidity from the buffer  |
+| sharesOwner  | address  | Address of the contract that will own the liquidity. Only this contract will be able to remove liquidity from the buffer |
 
 ### `removeLiquidityFromBuffer`
 
 ```solidity
 function removeLiquidityFromBuffer(
     IERC4626 wrappedToken,
-    uint256 sharesToRemove,
-    address sharesOwner
+    uint256 sharesToRemove
 ) external returns (uint256 removedUnderlyingBalanceRaw, uint256 removedWrappedBalanceRaw);
 ```
-This `VaultAdmin` function removes liquidity from a yield-bearing token buffer (linear pool embedded in the vault). Only proportional exits are supported.
+This `VaultAdmin` function removes liquidity from an internal ERC4626 buffer in the Vault. Only proportional exits are supported. Note that the `sharesOnwer` here is the msg.sender; unlike initialize, add, and other buffer operations, the entrypoint for this function is the Vault itself.
 
 **Parameters:**
 
 | Name  | Type  | Description  |
 |---|---|---|
 | wrappedToken  | IERC4626  | Address of the wrapped token that implements IERC4626  |
 | sharesToRemove  | uint256  | Amount of shares to remove from the buffer. Cannot be greater than sharesOwner total shares  |
-| sharesOwner  | address  | Address of contract that owns the deposited liquidity.  |
 
 ### `getBufferOwnerShares`