# The Vault

# Transient accounting

# unlock

function unlock(bytes calldata data) external returns (bytes memory result);

This Vault function creates a context for a sequence of operations, effectively "unlocking" the Vault. It performs a callback on msg.sender with arguments provided in data. The callback is transient, meaning all balances for the caller have to be settled at the end.

Parameters:

Returns:

# settle

function settle(IERC20 token, uint256 amountHint) external returns (uint256 credit);

This Vault function settles deltas for a token. This operation must be successful for the current lock to be released. It returns the credit supplied by the Vault, which can be calculated as min(reserveDifference, amountHint), where the reserve difference equals current balance of the token minus existing reserves of the token when the function is called.

The purpose of the hint is to protect against "donation DDoS attacks," where someone sends extra tokens to the Vault during the transaction (e.g., using reentrancy), which otherwise would cause settlement to fail. If the reserveDifference > amountHint, any "extra" tokens will simply be absorbed by the Vault (and reflected in the reserves), and not affect settlement. (The tokens will not be recoverable, as in V2.)

Parameters:

Returns:

# sendTo

function sendTo(IERC20 token, address to, uint256 amount) external;

This Vault function sends tokens to a recipient. There is no inverse operation for this function. To cancel debts, transfer funds to the Vault and call settle.

Parameters:

# isUnlocked

function isUnlocked() external view returns (bool);

This VaultExtension function returns True if the Vault is unlocked, false otherwise.

Returns:

# getNonzeroDeltaCount

function getNonzeroDeltaCount() external view returns (uint256);

This VaultExtension function returns the count of non-zero deltas.

Returns:

# getTokenDelta

function getTokenDelta(IERC20 token) external view returns (int256);

This VaultExtension function retrieves the token delta for a specific user and token.

Parameters:

Returns:

# getReservesOf

function getReservesOf(IERC20 token) external view returns (uint256);

This VaultExtension function retrieves the reserve (i.e., total Vault balance) of a given token.

Parameters:

Returns:

# getAddLiquidityCalledFlag

function getAddLiquidityCalledFlag(address pool) external view returns (bool);

This VaultExtension function retrieves the value of the flag used to detect and tax "round trip" transactions (adding and removing liquidity in the same pool).

Parameters:

Returns:

# Swaps

# swap

function swap(
    VaultSwapParams memory vaultSwapParams
) external returns (uint256 amountCalculatedRaw, uint256 amountInRaw, uint256 amountOutRaw);

This Vault function swaps tokens based on provided parameters. All parameters are given in raw token decimal encoding.

Parameters:

Returns:

# Add Liquidity

# addLiquidity

function addLiquidity(
    AddLiquidityParams memory params
) external returns (uint256[] memory amountsIn, uint256 bptAmountOut, bytes memory returnData);

This Vault function adds liquidity to a pool. Caution should be exercised when adding liquidity because the Vault has the capability to transfer tokens from any user, given that it holds all allowances. It returns the actual amounts of input tokens, the output pool token amount, and optional data with an encoded response from the pool.

Parameters:

Returns:

# Remove liquidity

# removeLiquidity

function removeLiquidity(
    RemoveLiquidityParams memory params
) external returns (uint256 bptAmountIn, uint256[] memory amountsOut, bytes memory returnData);

This Vault function removes liquidity from a pool. Trusted routers can burn pool tokens belonging to any user and require no prior approval from the user. Untrusted routers require prior approval from the user. This is the only function allowed to call _queryModeBalanceIncrease (and only in a query context).

Parameters:

Returns:

# Pool information

# getPoolTokenCountAndIndexOfToken

function getPoolTokenCountAndIndexOfToken(address pool, IERC20 token) external view returns (uint256, uint256);

This Vault function gets the index of a token in a given pool. It reverts if the pool is not registered, or if the token does not belong to the pool.

Parameters:

Returns:

# isPoolInitialized

function isPoolInitialized(address pool) external view returns (bool);

This VaultExtension function checks whether a pool is initialized.

Parameters:

Returns:

# getPoolTokens

function getPoolTokens(address pool) external view returns (IERC20[] memory);

This VaultExtension function gets the tokens registered to a pool.

Parameters:

Returns:

# getPoolTokenRates

function getPoolTokenRates(address pool) external view returns (uint256[] memory);

This VaultExtension function retrieves the scaling factors from a pool's rate providers. Tokens without rate providers will always return FixedPoint.ONE (1e18).

Parameters:

Returns:

# getPoolData

function getPoolData(address pool) external view returns (PoolData memory);

This VaultExtension function retrieves a PoolData structure, containing comprehensive information about the pool, including the PoolConfig, tokens, tokenInfo, balances, rates and scaling factors.

Parameters:

Returns:

# getPoolTokenInfo

function getPoolTokenInfo(
    address pool
)
    external
    view
    returns (
        IERC20[] memory tokens,
        TokenInfo[] memory tokenInfo,
        uint256[] memory balancesRaw,
        uint256[] memory lastLiveBalances
    );

This VaultExtension function gets the raw data for a pool: tokens, raw and last live balances.

Parameters:

Returns:

# getCurrentLiveBalances

function getCurrentLiveBalances(address pool) external view returns (uint256[] memory balancesLiveScaled18);

This VaultExtension function retrieves the current live balances: i.e., token balances after paying yield fees, applying decimal scaling and rates.

Parameters:

Returns:

# getPoolConfig

function getPoolConfig(address pool) external view returns (PoolConfig memory);

This VaultExtension function gets the configuration parameters of a pool.

Parameters:

Returns:

# getHooksConfig

function getHooksConfig(address pool) external view returns (HooksConfig memory);

This VaultExtension function gets the hooks configuration parameters of a pool.

Parameters:

Returns:

# getBptRate

function getBptRate(address pool) external view returns (uint256 rate);

This VaultExtension function gets the current bpt rate of a pool, by dividing the current invariant by the total supply of BPT.

Parameters:

Returns:

# ERC4626 Buffers

# erc4626BufferWrapOrUnwrap

function erc4626BufferWrapOrUnwrap(
    BufferWrapOrUnwrapParams memory params
) external returns (uint256 amountCalculatedRaw, uint256 amountInRaw, uint256 amountOutRaw);

This Vault function wraps/unwraps tokens based on provided parameters, using the buffer of the wrapped token when it has enough liquidity to avoid external calls. All parameters are given in raw token decimal encoding.

Parameters:

Returns:

# areBuffersPaused

function areBuffersPaused() external view returns (bool);

This VaultAdmin function indicates whether ERC4626 buffers are paused. When buffers are paused, all buffer operations (i.e., calls on the Router with isBuffer true) will revert. Pausing buffers is reversible. Note that ERC4626 buffers and the Vault have separate and independent pausing mechanisms. Pausing the Vault does not also pause buffers (though we anticipate they would likely be paused and unpaused together). Call isVaultPaused to check the pause state of the Vault.

Returns:

# pauseVaultBuffers

function pauseVaultBuffers() external;

This VaultAdmin function pauses 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. Currently it's not possible to pause vault buffers individually. This is a permissioned call, and is reversible (see unpauseVaultBuffers). Note that the Vault has a separate and independent pausing mechanism. It is possible to pause the Vault (i.e. pool operations), without affecting buffers, and vice versa.

# unpauseVaultBuffers

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

function initializeBuffer(
    IERC4626 wrappedToken,
    uint256 amountUnderlyingRaw,
    uint256 amountWrappedRaw,
    uint256 minIssuedShares,
    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:

# addLiquidityToBuffer

function addLiquidityToBuffer(
    IERC4626 wrappedToken,
    uint256 maxAmountUnderlyingInRaw,
    uint256 maxAmountWrappedInRaw,
    uint256 exactSharesToIssue,
    address sharesOwner
) external returns (uint256 amountUnderlyingRaw, uint256 amountWrappedRaw);

This VaultAdmin function adds liquidity proportionally to an internal ERC4626 buffer in the Vault. Reverts if the buffer has not been initialized.

Parameters:

# removeLiquidityFromBuffer

function removeLiquidityFromBuffer(
    IERC4626 wrappedToken,
    uint256 sharesToRemove,
    uint256 minAmountUnderlyingOutRaw,
    uint256 minAmountWrappedOutRaw
) external returns (uint256 removedUnderlyingBalanceRaw, uint256 removedWrappedBalanceRaw);

This VaultAdmin function removes liquidity from an internal ERC4626 buffer in the Vault. Only proportional exits are supported. Note that the sharesOwner here is the msg.sender; unlike initialize, add, and other buffer operations, the entrypoint for this function is the Vault itself.

Parameters:

# getBufferOwnerShares

function getBufferOwnerShares(
    IERC4626 wrappedToken,
    address liquidityOwner
) external view returns (uint256 ownerShares);

This VaultAdmin function returns the shares (internal buffer BPT) of a liquidity owner: a user that deposited assets in the buffer.

Parameters:

Returns:

# getBufferAsset

function getBufferAsset(
    IERC4626 wrappedToken
) external view returns (address underlyingToken);

This VaultAdmin function returns the shares (internal buffer BPT) of a liquidity owner: a user that deposited assets in the buffer.

Parameters:

Returns:

# getBufferTotalShares

function getBufferTotalShares(IERC4626 wrappedToken) external view returns (uint256 bufferShares);

This VaultAdmin function returns the supply shares (internal buffer BPT) of the ERC4626 buffer.

Parameters:

# getBufferBalance

function getBufferBalance(
    IERC4626 wrappedToken
) external view returns (uint256 underlyingBalanceRaw, uint256 wrappedBalanceRaw);

This VaultAdmin function returns the amount of underlying and wrapped tokens deposited in the internal buffer of the vault.

Parameters:

Returns:

# Authentication

# getAuthorizer

function getAuthorizer() external view returns (IAuthorizer);

This VaultExtension function returns the Vault's Authorizer.

Returns:

# setAuthorizer

function setAuthorizer(IAuthorizer newAuthorizer) external;

This VaultAdmin function sets a new Authorizer for the Vault. This is a permissioned call. It emits an AuthorizerChanged event.

Parameters:

# Pool registration

# registerPool

function registerPool(
    address pool,
    TokenConfig[] memory tokenConfig,
    uint256 swapFeePercentage,
    uint32 pauseWindowEndTime,
    bool protocolFeeExempt,
    PoolRoleAccounts calldata roleAccounts,
    address poolHooksContract,
    LiquidityManagement calldata liquidityManagement
) external;

This VaultExtension function registers a pool, associating it with its factory and the tokens it manages.

Parameters:

# isPoolRegistered

function isPoolRegistered(address pool) external view returns (bool);

This VaultExtension function checks whether a pool is registered.

Parameters:

Returns:

# initialize

function initialize(
    address pool,
    address to,
    IERC20[] memory tokens,
    uint256[] memory exactAmountsIn,
    uint256 minBptAmountOut,
    bytes memory userData
) external returns (uint256 bptAmountOut);

This VaultExtension function initializes a registered pool by adding liquidity; mints BPT tokens for the first time in exchange.

Parameters:

Returns:

# Balancer Pool tokens

# totalSupply

function totalSupply(address token) external view returns (uint256);

This VaultExtension function gets the total supply of a given ERC20 token.

Parameters:

Returns:

# balanceOf

function balanceOf(address token, address account) external view returns (uint256);

This VaultExtension function gets the balance of an account for a given ERC20 token.

Parameters:

Returns:

# allowance

function allowance(address token, address owner, address spender) external view returns (uint256);

This VaultExtension function gets the allowance of a spender for a given ERC20 token and owner.

Parameters:

Returns:

# approve

function approve(address owner, address spender, uint256 amount) external returns (bool);

This VaultExtension function approves a spender to spend pool tokens on behalf of sender.

Parameters:

Returns:

# transfer

function transfer(address owner, address to, uint256 amount) external returns (bool);

This Vault function transfers pool token from owner to a recipient.

Parameters:

Returns:

# transferFrom

function transferFrom(address spender, address from, address to, uint256 amount) external returns (bool);

This Vault function transfers pool token from a sender to a recipient using an allowance.

Parameters:

Returns:

# pool pausing

# isPoolPaused

function isPoolPaused(address pool) external view returns (bool);

This VaultExtension function indicates whether a pool is paused.

Parameters:

Returns:

# getPoolPausedState

function getPoolPausedState(address pool) external view returns (bool, uint32, uint32, address);

This VaultExtension function returns the paused status, and end times of the Pool's pause window and buffer period.

Parameters:

Returns:

# ERC4626 Buffers

# isERC4626BufferInitialized

function isERC4626BufferInitialized(IERC4626 wrappedToken) external view returns (bool isBufferInitialized);

This VaultExtension function checks whether initializeBuffer has been called on the given wrappedToken. Buffers must be initialized before use.

Parameters:

Returns:

# Fees

# getAggregateSwapFeeAmount

function getAggregateSwapFeeAmount(address pool, IERC20 token) external view returns (uint256);

This VaultExtension function returns the accumulated swap fees (including aggregate fees) in token collected by the pool.

Parameters:

Returns:

# getAggregateYieldFeeAmount

function getAggregateYieldFeeAmount(address pool, IERC20 token) external view returns (uint256);

This VaultExtension function returns the accumulated yield fees (including aggregate fees) in token collected by the pool.

Parameters:

Returns:

# getStaticSwapFeePercentage

function getStaticSwapFeePercentage(address pool) external view returns (uint256);

This VaultExtension function fetches the static swap fee percentage for a given pool.

Parameters:

Returns:

# getPoolRoleAccounts

function getPoolRoleAccounts(address pool) external view returns (PoolRoleAccounts memory);

This VaultExtension function fetches the role accounts for a given pool (pause manager, swap manager, pool creator).

Parameters:

Returns:

# computeDynamicSwapFeePercentage

function computeDynamicSwapFee(
    address pool,
    PoolSwapParams memory swapParams
) external view returns (uint256);

This VaultExtension function queries the current dynamic swap fee of a pool, given a set of swap parameters.

Parameters:

Returns:

# getProtocolFeeController

function getProtocolFeeController() external view returns (IProtocolFeeController);

This VaultExtension function returns the Protocol Fee Controller address.

Returns:

# setStaticSwapFeePercentage

function setStaticSwapFeePercentage(address pool, uint256 swapFeePercentage) external;

This VaultAdmin function assigns a new static swap fee percentage to the specified pool. This is a permissioned function, disabled if the pool is paused. The swap fee percentage must be within the bounds specified by the pool's implementation of ISwapFeePercentageBounds.

Parameters:

# collectAggregateFees

function collectAggregateFees(address pool) public returns (uint256[] memory totalSwapFees, uint256[] memory totalYieldFees);

This function collects accumulated aggregate swap and yield fees for the specified pool. It can only be called from the ProtocolFeeController, which unlocks the Vault, acting as a Router. In the Vault, it clears the aggregateFeeAmounts storage, supplying credit for each amount which must be settled at the end of the fee controller action.

Parameters:

# updateAggregateSwapFeePercentage

function updateAggregateSwapFeePercentage(address pool, uint256 newAggregateSwapFeePercentage) external;

This VaultAdmin function updates an aggregate swap fee percentage. Can only be called by the current protocol fee controller.

Parameters:

# updateAggregateYieldFeePercentage

function updateAggregateYieldFeePercentage(address pool, uint256 newAggregateYieldFeePercentage) external;

This VaultAdmin function updates an aggregate yield fee percentage. Can only be called by the current protocol fee controller.

Parameters:

# setProtocolFeeController

function setProtocolFeeController(IProtocolFeeController newProtocolFeeController) external;

This VaultAdmin function sets a new Protocol Fee Controller for the Vault. This is a permissioned call.

Parameters:

# Recovery mode

# isPoolInRecoveryMode

function isPoolInRecoveryMode(address pool) external view returns (bool);

This VaultExtension function checks whether a pool is in recovery mode.

Parameters:

Returns:

# removeLiquidityRecovery

function removeLiquidityRecovery(
    address pool,
    address from,
    uint256 exactBptAmountIn,
    uint256[] memory minAmountsOut
) external returns (uint256[] memory amountsOut);

This VaultExtension function removes liquidity from a pool specifying exact pool tokens in, with proportional token amounts out. The request is implemented by the Vault without any interaction with the pool, ensuring that it works the same for all pools, and cannot be disabled by a new pool type.

Parameters:

Returns:

# enableRecoveryMode

function enableRecoveryMode(address pool) external;

This VaultAdmin function enables recovery mode for a pool. This is a permissioned function, but becomes permissionless if the Vault or pool is paused.

Parameters:

# disableRecoveryMode

function disableRecoveryMode(address pool) external;

This VaultAdmin function disables recovery mode for a pool. This is a permissioned function.

Parameters:

# Queries

# quote

function quote(bytes calldata data) external returns (bytes memory result);

This VaultExtension function performs a callback on msg.sender with arguments provided in data. It is used to query a set of operations on the Vault. Only off-chain eth_call are allowed, anything else will revert. Also note that it is non-payable, as the Vault does not allow ETH.

Parameters:

Returns:

# quoteAndRevert

function quoteAndRevert(bytes calldata data) external;

This VaultExtension function performs a callback on msg.sender with arguments provided in data. It is used to query a set of operations on the Vault. Only off-chain eth_call are allowed, anything else will revert. This call always reverts, returning the result in the revert reason. Also note that it is non-payable, as the Vault does not allow ETH.

Parameters:

# isQueryDisabled

function isQueryDisabled() external view returns (bool);

This VaultExtension function checks if the queries reversibly disabled on the Vault.

Returns:

# isQueryDisabledPermanently

function isQueryDisabledPermanently() external view returns (bool);

This VaultExtension function checks if the queries are permanently disabled on the Vault.

Returns:

# emitAuxiliaryEvent

function emitAuxiliaryEvent(string calldata eventKey, bytes calldata eventData) external;

This VaultExtension function checks if the queries are permanently disabled on the Vault.

Returns:

# disableQuery

function disableQuery() external;

This VaultAdmin function reversibly disables query functionality on the Vault. It can only be called by governance.

# disableQueryPermanently

function disableQueryPermanently() external;

This VaultAdmin function permanently disables query functionality on the Vault. It can only be called by governance.

# enableQuery

function enableQuery() external;

This VaultAdmin function re-enables reversibly disabled query functionality on the Vault. It can only be called by governance.

# Constants

# getPauseWindowEndTime

function getPauseWindowEndTime() external view returns (uint32);

This VaultAdmin function returns Vault's pause window end time.

Returns:

# getBufferPeriodDuration

function getBufferPeriodDuration() external view returns (uint32);

This VaultAdmin function returns Vault's buffer period duration.

Returns:

# getBufferPeriodEndTime

function getBufferPeriodEndTime() external view returns (uint32);

This VaultAdmin function returns Vault's buffer period end time.

Returns:

# getMinimumPoolTokens

function getMinimumPoolTokens() external pure returns (uint256);

This VaultAdmin function gets the minimum number of tokens in a pool.

Returns:

# getMaximumPoolTokens

function getMaximumPoolTokens() external pure returns (uint256);

This VaultAdmin function gets the maximum number of tokens in a pool.

Returns:

# getPoolMinimumTotalSupply

function getPoolMinimumTotalSupply() external pure returns (uint256);

This VaultAdmin function gets the minimum total supply of pool tokens (BPT) for an initialized pool. This prevents pools from being completely drained. When the pool is initialized, this minimum amount of BPT is minted to the zero address. This is an 18-decimal floating point number; BPT are always 18 decimals.

Returns:

# getBufferMinimumTotalSupply

function getBufferMinimumTotalSupply() external pure returns (uint256);

This VaultAdmin function gets the minimum total supply of an ERC4626 wrapped token buffer in the Vault. This prevents buffers from being completely drained. When the buffer is initialized, this minimum number of shares is added to the shares resulting from the initial deposit. Buffer total supply accounting is internal to the Vault, as buffers are not tokenized.

Returns:

# getMinimumTradeAmount

function getMinimumTradeAmount() external view returns (uint256);

This VaultAdmin function gets the minimum trade amount in a pool operation. This limit is applied to the 18-decimal "upscaled" amount in any operation (swap, add/remove liquidity).

Returns:

# getMinimumWrapAmount

function getMinimumWrapAmount() external view returns (uint256);

This VaultAdmin function gets the minimum wrap amount in a buffer operation. This limit is applied to the wrap operation amount, in native underlying token decimals.

Returns:

# vault

function vault() external view returns (IVault);

This function (defined on both VaultExtension and VaultAdmin) returns the main Vault address.

Returns:

# Vault pausing

# isVaultPaused

function isVaultPaused() external view returns (bool);

This VaultAdmin function indicates whether the Vault is paused. Note that ERC4626 buffers and the Vault have separate and independent pausing mechanisms. Pausing the Vault does not also pause buffers (though we anticipate they would likely be paused and unpaused together). Call areBuffersPaused to check the pause state of the buffers.

Returns:

# getVaultPausedState

function getVaultPausedState() external view returns (bool, uint32, uint32);

This VaultAdmin function returns the paused status, and end times of the Vault's pause window and buffer period.

Returns:

# pauseVault

function pauseVault() external;

This VaultAdmin function pauses the Vault: an emergency action which disables all operational state-changing functions on pools. This is a permissioned function that will only work during the Pause Window set during deployment. Note that ERC4626 buffer operations have an independent pause mechanism, which is not affected by pausing the Vault. Custom routers could still wrap/unwrap using buffers while the Vault is paused, unless buffers are also paused (with pauseVaultBuffers).

# unpauseVault

function unpauseVault() external;

This VaultAdmin function reverses a pause operation, and restores Vault pool operations to normal functionality. This is a permissioned function that will only work on a paused Vault within the Buffer Period set during deployment. Note that the Vault will automatically unpause after the Buffer Period expires. And as noted above, ERC4626 buffers and Vault operations on pools are independent. Unpausing the Vault does not reverse pauseVaultBuffers. If buffers were also paused, they will remain in that state until explicitly unpaused.

# Pool pausing

# pausePool

function pausePool(address pool) external;

This VaultAdmin function pauses the Pool: an emergency action which disables all pool functions. This is a permissioned function that will only work during the Pause Window set during pool factory deployment.

Parameters:

# unpausePool

function unpausePool(address pool) external;

This VaultAdmin function reverses a pause operation, and restores the Pool to normal functionality. This is a permissioned function that will only work on a paused Pool within the Buffer Period set during deployment. Note that the Pool will automatically unpause after the Buffer Period expires.

Parameters:

# Miscellaneous

# getVaultExtension

function getVaultExtension() external view returns (address);

This Vault function returns the Vault Extension address.

Returns:

# getVaultAdmin

function getVaultAdmin() external view returns (address);

This VaultExtension function returns the Vault Admin contract address.

Returns: