From 9ca6ab05054d4d948aa7e8871fad36dc934460df Mon Sep 17 00:00:00 2001 From: baileyspraggins Date: Mon, 22 May 2023 11:23:10 -0500 Subject: [PATCH 1/2] MP swap fee docs --- docs/concepts/pools/managed.md | 38 ++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/docs/concepts/pools/managed.md b/docs/concepts/pools/managed.md index 71131b41..f38c9521 100644 --- a/docs/concepts/pools/managed.md +++ b/docs/concepts/pools/managed.md @@ -22,3 +22,41 @@ Managed Pools are feature rich. Some of the features include: - Change token weights - Circuit Breakers to protect from malicious/compromised tokens +## Swap Fees + +Swap fees are taken during joins, exits and regular token swaps. They are payed out between Liquidity Providers and the Protocol. For a current break down of swap fee distribution see [Governable Protocol Fees](https://docs.balancer.fi/concepts/governance/protocol-fees.html#swap-fees). + +Managers can adjust swap fee percentages in order to influencing the economic activity and incentives around a Managed Pool. The fluxuation of swap fee percentages is a key driver in adding/removing tokens, changing weights and guiding transaction volume. + +### Limits +[ManagedPoolSettings.sol](https://github.com/balancer/balancer-v2-monorepo/blob/master/pkg/pool-weighted/contracts/managed/ManagedPoolSettings.sol) defines `_MAX_SWAP_FEE_PERCENTAGE = 95e16` or 95% and `_MIN_SWAP_FEE_PERCENTAGE = 1e12` or 0.0001%. A maximum swap fee is set in order to safe guard from potential reverts during division and that may occur when performing joins and exits on a pool, in the case that a pool's token balance is less than the fee amount. The minimum swap fee prevents the pool from being drained due to the presence of transaction costs, while also incentivizing liquidity providers to provide and maintain liquidity in the pool. Managers can set custom swap fee percentages in their own implementations as long as they are in the bounds of `_MAX_SWAP_FEE_PERCENTAGE` and `_MIN_SWAP_FEE_PERCENTAGE`. + +### Gradual Updates +Gradually updating swap fees over a set period of time is the recommended method for adjusting swap fee percentages. The concept is to implement a linear shift in swap fees, starting from the maximum swap fee set by the manager and gradually reducing it to a nominal or near 0% fee. This approach promotes healthy interactions with the pool and enables arbitragers to adjust the pool's weights gradually over time without the risk of completely draining liquidity. + +### Instantaneous Updates +Instantaneous updates occur when swap fees are updated immediately instead of on a slow, gradual basis. This approach is not recommended as it can lead to significant slippage, giving arbitragers an opportunity to completely drain the pool. + +### Examples: +[ManagedPoolSetting.sol](https://github.com/baileyspraggins/balancer-v2-monorepo/blob/master/pkg/pool-weighted/contracts/managed/ManagedPoolSettings.sol) provides the necessary logic for viewing and updating swap fees within a Managed Pool. Below are a few basic examples of how a Manager can interact with swap fees on a Managed Pool. + +```sol +// Set custom swap fees (Must be >= 1e12 and <>= 95e16) +uint256 private constant _MAX_SWAP_FEE_PERCENTAGE = 92e16 +uint256 private constant _MIN_SWAP_FEE_PERCENTAGE = 2e12 +``` + +```sol +// Update swap fees from max fee to min fee +_managedPool.updateSwapFeeGradually( + block.timestamp, + block.timestamp + _REBALANCE_DURATION, + _MAX_SWAP_FEE_PERCENTAGE, + _MIN_SWAP_FEE_PERCENTAGE +); +``` + +```sol +// Get the current value of the swap fee percentage +uint256 swapFeePercentage = _managedPool.getSwapFeePercentage(); +``` From dfcf48d39cd22b5736eb1f394f7238e84f9ab26a Mon Sep 17 00:00:00 2001 From: baileyspraggins Date: Mon, 22 May 2023 14:54:14 -0500 Subject: [PATCH 2/2] Edits to Swap Fee docs --- docs/concepts/pools/managed.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/concepts/pools/managed.md b/docs/concepts/pools/managed.md index f38c9521..50ce2bd7 100644 --- a/docs/concepts/pools/managed.md +++ b/docs/concepts/pools/managed.md @@ -24,39 +24,39 @@ Managed Pools are feature rich. Some of the features include: ## Swap Fees -Swap fees are taken during joins, exits and regular token swaps. They are payed out between Liquidity Providers and the Protocol. For a current break down of swap fee distribution see [Governable Protocol Fees](https://docs.balancer.fi/concepts/governance/protocol-fees.html#swap-fees). +Swap fees are collected during token swaps (as well as some joins and exits: specifically when the transactions are not proportional with the rest of the pool). Swap fees accrue to the pool, and therefore increase the amount of underlying tokens in the pool. This in turn translates to collected fees going to Liquidity Providers by means of increasing the value of their LP tokens (BPT). Unlike most other Balancer pools, Managed Pools do not split swap fees with the protocol. -Managers can adjust swap fee percentages in order to influencing the economic activity and incentives around a Managed Pool. The fluxuation of swap fee percentages is a key driver in adding/removing tokens, changing weights and guiding transaction volume. +Managers can adjust swap fee percentages in order to influencing the economic activity and incentives around a Managed Pool. For example, when re-enabling swaps in a previously paused pool, running a swap fee update from a very high swap fee to a low swap fee can help mitigate arbitrage losses. ### Limits -[ManagedPoolSettings.sol](https://github.com/balancer/balancer-v2-monorepo/blob/master/pkg/pool-weighted/contracts/managed/ManagedPoolSettings.sol) defines `_MAX_SWAP_FEE_PERCENTAGE = 95e16` or 95% and `_MIN_SWAP_FEE_PERCENTAGE = 1e12` or 0.0001%. A maximum swap fee is set in order to safe guard from potential reverts during division and that may occur when performing joins and exits on a pool, in the case that a pool's token balance is less than the fee amount. The minimum swap fee prevents the pool from being drained due to the presence of transaction costs, while also incentivizing liquidity providers to provide and maintain liquidity in the pool. Managers can set custom swap fee percentages in their own implementations as long as they are in the bounds of `_MAX_SWAP_FEE_PERCENTAGE` and `_MIN_SWAP_FEE_PERCENTAGE`. +[ManagedPoolSettings.sol](https://github.com/balancer/balancer-v2-monorepo/blob/master/pkg/pool-weighted/contracts/managed/ManagedPoolSettings.sol) defines `_MAX_SWAP_FEE_PERCENTAGE = 95e16` or 95% and `_MIN_SWAP_FEE_PERCENTAGE = 1e12` or 0.0001%. Swap fee limits exist to safeguard from potential math errors and to incentivize Liquidity Providers to join pools. Managers can set custom swap fee percentages in their own implementations as long as they are in the bounds of `_MAX_SWAP_FEE_PERCENTAGE` and `_MIN_SWAP_FEE_PERCENTAGE`. ### Gradual Updates -Gradually updating swap fees over a set period of time is the recommended method for adjusting swap fee percentages. The concept is to implement a linear shift in swap fees, starting from the maximum swap fee set by the manager and gradually reducing it to a nominal or near 0% fee. This approach promotes healthy interactions with the pool and enables arbitragers to adjust the pool's weights gradually over time without the risk of completely draining liquidity. +Gradually updating swap fees over a set period of time is the recommended method for adjusting swap fee percentages, especially if the manager is _lowering_ fees. An example concept is to implement a linear shift in swap fees, starting from the upper value swap fee set by the manager and gradually reducing it to a nominal or near 0% fee. This approach promotes healthy interactions with the pool and enables arbitragers to adjust the pool's balances gradually over time mitigating arbitrage losses. ### Instantaneous Updates -Instantaneous updates occur when swap fees are updated immediately instead of on a slow, gradual basis. This approach is not recommended as it can lead to significant slippage, giving arbitragers an opportunity to completely drain the pool. +Instantaneous updates occur when swap fees are updated immediately instead of on a slow, gradual basis. Lowering fees instantaneously is generally not recommended as it can lead to instantaneous arbitrage opportunities, giving arbitragers an opportunity to extract value. Instantaneous swap fee increases are generally considered safe. ### Examples: [ManagedPoolSetting.sol](https://github.com/baileyspraggins/balancer-v2-monorepo/blob/master/pkg/pool-weighted/contracts/managed/ManagedPoolSettings.sol) provides the necessary logic for viewing and updating swap fees within a Managed Pool. Below are a few basic examples of how a Manager can interact with swap fees on a Managed Pool. -```sol +```solidity // Set custom swap fees (Must be >= 1e12 and <>= 95e16) -uint256 private constant _MAX_SWAP_FEE_PERCENTAGE = 92e16 -uint256 private constant _MIN_SWAP_FEE_PERCENTAGE = 2e12 +uint256 private constant _INITIAL_SWAP_FEE_PERCENTAGE = 92e16 +uint256 private constant _FINAL_SWAP_FEE_PERCENTAGE = 2e12 ``` -```sol +```solidity // Update swap fees from max fee to min fee _managedPool.updateSwapFeeGradually( block.timestamp, block.timestamp + _REBALANCE_DURATION, - _MAX_SWAP_FEE_PERCENTAGE, - _MIN_SWAP_FEE_PERCENTAGE + _INITIAL_SWAP_FEE_PERCENTAGE, + _FINAL_SWAP_FEE_PERCENTAGE ); ``` -```sol +```solidity // Get the current value of the swap fee percentage uint256 swapFeePercentage = _managedPool.getSwapFeePercentage(); ```