From aec3d7c01480101d0079432d496a0d9046a8bd0d Mon Sep 17 00:00:00 2001 From: Marco Worms Date: Fri, 2 Dec 2022 12:30:25 -0300 Subject: [PATCH 01/54] add v3 docs --- docs/getting-started/products/yvaults/v3.md | 240 ++++++++++++++++++++ sidebars/sidebarsGettingStarted.js | 1 + 2 files changed, 241 insertions(+) create mode 100644 docs/getting-started/products/yvaults/v3.md diff --git a/docs/getting-started/products/yvaults/v3.md b/docs/getting-started/products/yvaults/v3.md new file mode 100644 index 0000000000..8d00cabf4d --- /dev/null +++ b/docs/getting-started/products/yvaults/v3.md @@ -0,0 +1,240 @@ +# yVaults V3 + +V3 Vaults iterates on V2 to increase robustness and develop yearn’s path towards further decentralization, while keeping the same proven product (yield-bearing tokens) that abstract builders and users from the hard work of yield farming. V3 will initially have the same functionality as V2, but vaults are more robust and modular. + +V3 Vaults improves on V2 by: +- Increasing vault modularity, allowing for smaller and safer pieces of code. +- Simplify strategy creation, empowering strategists and reducing chance for errors. +- Adding new products like ySwaps that increase swaps efficiency and yJuniorTranches that allow for different risk profiles. + +## Smart Modules + +Smart Modules implement logic to be iterated until it can be made immutable. If any Smart Module fails, the vault can live without them just enough to return funds to depositors. **When V3 launches, the Smart Modules will replicate V2 vault behavior.** + +- **Debt Allocator:** Knows the maximum debt a vault can send to a strategy. +- **Strategy Registry:** Handles adding and removing strategies of a vault. It can also include strategy metadata. +- **Fee Manager:** Handles changing fees for vault operations. +- **HealthCheck:** Guardrails vault operations so that profit & loss reporting is always under acceptable values. + +## Peripheral Modules + +Peripheral Modules are a separate layer of optional functions for the vault and strategies. They are not required but they facilitate building around yVaults and creating new strategies. + +- **yRouter**: Wrapper that handles deposits and withdrawals to/from vault. +- **Yearn Lens:** Information aggregator for off-chain apps. +- **APY TWAP Oracle:** Reliable source of yearn vault’s past performance. +- **ySwaps:** Internal swap system currently being developed. Reduces slippage thus improve net APY. +- And any other you can come up with! + +## V3 yVault Specification + +# Yearn System Specification (DRAFT) + +## Definitions +- **Asset:** Any ERC20-compliant token +- **Shares:** ERC20-compliant token that tracks Asset balance in the vault for every distributor. Named yv +- **Depositor:** Account that holds Shares +- **Strategy:** Smart contract used to deposit in Protocols to generate yield +- **Vault:** ERC4626 compliant Smart contract that receives Assets from Depositors to distribute them among the different Strategies added to the vault, managing accounting and Assets distribution. +- **Role:** Flags that an Account can do specific Vault actions. Can be fulfilled by a smart contract or an EOA. +- **Accountant:** Smart contract that receives P&L reporting and returns shares and refunds to the strategy + +# VaultV3 Specification +The Vault code has been designed as an unopinionated system to distribute depositors funds into different opportunities (aka Strategies) and robustly manage accounting. + +The depositors receive shares of the different investments that can then be redeemed or used as yield-bearing tokens. + +The Vault does not have a preference on any of the dimensions that should be considered when operating a vault: +- **Decentralization**: Roles can be filled by common wallets, smart contracts like multisigs or governance modules. +- **Liquidity**: Vault can have 0 liquidity or be fully liquid. It will depend on the parameters and strategies added. +- **Security**: Vault managers can choose what strategies to add and how to do that process. +- **Automation**: All the required actions to maintain the vault can be called by bots or manually, depending on periphery implementation. + +The compromises will come with implementing periphery contracts fulfilling the roles in the Vault. This allows different players to deploy their own version and implement their own periphery contracts (or not use any at all) + + +## Example periphery contracts: +- **Emergency module:** Receives deposits of Vault Shares and allows the contract to call the shutdown function after a certain % of total Vault Shares have been deposited. +- **Debt Allocator:** Smart contract that incentivizes APY / debt allocation optimization by rewarding the best debt allocation (see [yStarkDebtAllocator](https://github.com/jmonteer/ystarkdebtallocator)). +- **Strategy Staking Module:** Smart contract that allows players to sponsor specific strategies (so that they are added to the vault) by staking their YFI, making money if they do well and losing money if they don't. + +## Deployment +We expect all the vaults available to be deployed from a Factory Contract, publicly available and callable. + +Players deploying "branded" vaults (e.g. Yearn) will use a separate registry to allow permissioned endorsement of vaults for their product + +When deploying a new vault, it requires the following parameters: +- **asset:** Address of the ERC20 token that can be deposited in the vault. +- **name:** Name of Shares as described in ERC20. +- **symbol:** Symbol of Shares ERC20. +- **role_manager:** Account that can assign and revoke Roles. +- **PROFIT_MAX_UNLOCK_TIME:** Max amount of time profit will be distributed over. + +## Normal Operation + +### Deposits / Mints +Users can deposit ASSET tokens to receive yvTokens (SHARES). + +Deposits are limited under `depositLimit` and shutdown parameters. Read below for details. + +### Withdrawals / Redeems +Users can redeem their shares at any time if there is liquidity available. + +The redeem function will check if there are enough idle funds to serve the request. If there are not enough, it will revert. + +Optionally, a user can specify a list of strategies to withdraw from. If a list of strategies is passed, the vault will try to withdraw from them. + +If not enough funds have been recovered to honor the full request, the transaction will revert. + +### Vault Shares +Vault shares are ERC20 transferable yield-bearing tokens. + +They are ERC4626 compliant. Please read [ERC4626 compliance](https://hackmd.io/cOFvpyR-SxWArfthhLJb5g#ERC4626-compliance) to understand the implications. + +### Accounting +The vault will evaluate profit and losses from the strategies. + +This is done by comparing the current debt of the strategy with the total assets the strategy is reporting to have. + +- If `totalAssets < currentDebt`: the vault will record a loss +- If `totalAssets > currentDebt`: the vault will record a profit + +Both loss and profit will impact the strategy's debt, increasing the debt (current debt + profit) if there are profits, and decreasing its debt (current debt - loss) if there are losses. + +#### Fees +The Accountant module handles fee assessment and distribution. It will report the amount of fees that need to be charged, and the vault will issue shares for that amount of fees. + +#### Refunds +Refunds are positive inflows for the vault, and are sent to the vault to reward it or compensate in anyway. The Accountant module will take care of them. + +An example is an insurance mechanism like different risk tranches where the accountant will send assets to the vault to compensate for losses (and, in exchange, take higher fees). + +The refunds are paid in the form of vault shares and will be instantly locked (and released gradually) + +### Profit distribution +Profit from different process_report calls will accumulate in a buffer. This buffer will be linearly unlocked over the locking period seconds at profit_distribution_rate. + +Profits will be locked for a max period of PROFIT_MAX_UNLOCK_TIME seconds and will be gradually distributed. To avoid spending too much gas for profit unlock, the period that profit will be locked for is a weighted average between the new profit and the previous profit. + +- `new_locking_period = locked_profit * pending_time_to_unlock + new_profit * PROFIT_MAX_UNLOCK_TIME / (locked_profit + new_profit)` +- `new_profit_distribution_rate = (locked_profit + new_profit) / new_locking_period` + +Losses will be offset by locked profit, if possible. That makes frontrunning losses impossible (unless loss > locked profit) + +Issue of new shares due to fees will also insta-unlock profit so that price-per-share (pps) does not go down. + +Both of these offsets will prevent frontrunning (as the profit was already earned and was not distributed yet) + +Instead of locking the profit, and in order to be more capital efficient (and avoid complex asset management), the vault issues shares that holds itself. Those shares are gradually burned over time (increasing pps). So instead of releasing assets, the vault will gradually burn shares. + +## Vault Management +Vault management is split into two fields: strategy management and debt management + +### Strategy Management +Callers take this responsibility with the `STRATEGY_MANAGER` role + +A vault can have strategies added, removed and migrated + +Added strategies will be eligible to receive funds from the vault, when the `max_debt` is set to > 0 + +Revoked strategies will return all debt and stop being eligible to receive more. It can only be done when the strategy's `current_debt` is 0 + +Strategy migration is the process of replacing an existing strategy with a new one, which will inherit all parameters, including its debt + +### Debt Management +Callers take this responsibility with the `DEBT_MANAGER` role + +#### Setting minimum idle funds +The debt manager can specify how many funds the vault should try to have reserved to serve withdrawal requests + +These funds will remain in the vault unless requested by a Depositor + +#### Setting maximum debt for a specific strategy +The maximum amount of tokens the vault will allow a strategy to owe at any moment. + +Stored in `strategies[strategy].max_debt` + +When a debt rebalance is triggered, the Vault will cap the new target debt to this number (max_debt) + +#### Rebalance Debt +The vault sends and receives funds to/from strategies. The function updateDebt(strategy, target_debt) will set the current_debt of the strategy to target_debt (if possible) + +If the strategy currently has less debt than the target_debt, the vault will send funds to it. + +The vault checks that the `minimumTotalIdle` parameter is respected (i.e. there's at least a certain amount of funds in the vault). + +The vault will request back funds if the strategy has more debt than the `max_debt`. These funds may be locked in the strategy, which will result in the strategy returning fewer funds than requested by the vault. + +## Roles +Vault functions that are permissioned will be callable by accounts with specific roles. + +These are: +- `STRATEGY_MANAGER:` role for accounts that can add, remove or migrate strategies +- `DEBT_MANAGER:` role for accounts that can rebalance and manage debt related params +- `EMERGENCY_MANAGER:` role for accounts that can activate the shutdown mode +- `ACCOUNTING_MANAGER:` role for accounts that can process reports (save strategy p&l) and change accountant parameters + +Every role can be filled by an EOA, multisig, or other smart contracts. Each role can be filled by several accounts. + +The account that manages roles is a single account, set in `role_manager`. + +This `role_manager` can be an EOA, a multisig, or a Governance Module that relays calls. + +## Strategy Minimum API +Strategies are completely independent smart contracts that can be implemented following the proposed template or in any other way. + +In any case, to be compatible with the vault, they need to implement the following functions, which are a subset of ERC4626 vaults: +- `asset():` View returning underlying asset. +- `vault():` View returning vault this strategy is plugged to. +- `totalAssets():` View returning current amount of assets. It can include rewards valued in `asset`. +- `maxDeposit(address):` View returning the amount max that the strategy can take safely. +- `deposit(assets, receiver):` Deposits `assets` amount of tokens into the strategy. It can be restricted to the vault only or be open. +- `maxWithdraw(address):` View returning how many assets can the vault take from the vault at any given point in time. +- `withdraw(assets, receiver, owner):` Withdraws `assets` amount of tokens from the strategy. +- `balanceOf(address):` Return the number of shares of the strategy that the address has. + +This means that the vault can deposit into any ERC4626 vault and that a non-compliant strategy can be implemented provided that these functions have been implemented (even in a non ERC4626 compliant way). + +Anything else is left to the strategy writer. However, to make security review easier, the Yearn's template has the following optional functions: +- `tend():` a function that will be called by bots. It will do anything to maintain a position, act on certain triggers, ... +- `tendTrigger():` implementation that trigger bots that will call tend function on the contract +- `invest():` deposit funds into underlying protocol +- `emergencyFreeFunds():` close the position and return funds to the strategy. Losses might be accepted here. + + +## ERC4626 compliance +Vault Shares are ERC4626 compliant. + +The most important implication is that `withdraw` and `redeem` functions as presented in ERC4626, the liquidity to redeem shares will be the one in the vault. No strategies will be passed to the redeem function to withdraw from with the ERC4626 compliant `withdraw` and `redeem` function. + +## Emergency Operation + +### Shutdown mode +If the current roles stop fulfilling their responsibilities or something else happens, the `EMERGENCY_MANAGER` can shut down the vault. + +The shutdown mode should be the last option in an emergency, as it is irreversible. + +### Deposits +- **Light emergency:** Deposits can be paused by setting depositLimit to 0 +- **Shutdown mode:** Deposits are not allowed + +### Withdrawals +Withdrawals can't be paused under any circumstance. + +### Accounting +Shutdown mode does not affect accounting. + +### Debt rebalance +- **Light emergency**: Setting minimumTotalIdle to MAX_UINT256 will result in the vault requesting the debt back from strategies. This would stop new strategies from getting funded too, as the vault prioritizes minimumTotalIdle +- **Shutdown mode**: All strategies' `maxDebt` is set to 0. Strategies will return funds as soon as they can. + +### Relevant emergency +If the current roles stop fulfilling their responsibilities or something else happens, the `EMERGENCY_MANAGER` can shut down the vault. + +The shutdown mode should be the last option in an emergency, as it is irreversible. + +During shutdown mode, the vault will try to get funds back from every strategy as soon as possible. + +No strategies can be added during shutdown. + +Any relevant role will start pointing to the `EMERGENCY_MANAGER` in case new permissioned allowed actions need to be taken. \ No newline at end of file diff --git a/sidebars/sidebarsGettingStarted.js b/sidebars/sidebarsGettingStarted.js index 91e3ad317f..c6575bfab8 100644 --- a/sidebars/sidebarsGettingStarted.js +++ b/sidebars/sidebarsGettingStarted.js @@ -13,6 +13,7 @@ module.exports = { 'products/yvaults/overview', 'products/yvaults/vaults-and-strategies', 'products/yvaults/vault-tokens', + 'products/yvaults/v3', ], }, { From 1875a3c2e96476ae541a5f1a64546c080ae87602 Mon Sep 17 00:00:00 2001 From: Marco Worms Date: Fri, 2 Dec 2022 12:36:51 -0300 Subject: [PATCH 02/54] adjust sidebar v3 title --- docs/getting-started/products/yvaults/v3.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/products/yvaults/v3.md b/docs/getting-started/products/yvaults/v3.md index 8d00cabf4d..7e811187a8 100644 --- a/docs/getting-started/products/yvaults/v3.md +++ b/docs/getting-started/products/yvaults/v3.md @@ -1,4 +1,4 @@ -# yVaults V3 +# Vaults V3 V3 Vaults iterates on V2 to increase robustness and develop yearn’s path towards further decentralization, while keeping the same proven product (yield-bearing tokens) that abstract builders and users from the hard work of yield farming. V3 will initially have the same functionality as V2, but vaults are more robust and modular. From cd1cd2c13dd9095bfcb68d811f73f9ae0240acd0 Mon Sep 17 00:00:00 2001 From: Marco Worms Date: Fri, 2 Dec 2022 12:38:31 -0300 Subject: [PATCH 03/54] add quote style to repeated warning --- docs/getting-started/products/yvaults/v3.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/getting-started/products/yvaults/v3.md b/docs/getting-started/products/yvaults/v3.md index 7e811187a8..372c3ca192 100644 --- a/docs/getting-started/products/yvaults/v3.md +++ b/docs/getting-started/products/yvaults/v3.md @@ -210,9 +210,8 @@ The most important implication is that `withdraw` and `redeem` functions as pres ## Emergency Operation ### Shutdown mode -If the current roles stop fulfilling their responsibilities or something else happens, the `EMERGENCY_MANAGER` can shut down the vault. -The shutdown mode should be the last option in an emergency, as it is irreversible. +> If the current roles stop fulfilling their responsibilities or something else happens, the `EMERGENCY_MANAGER` can shut down the vault. The shutdown mode should be the last option in an emergency, as it is irreversible. ### Deposits - **Light emergency:** Deposits can be paused by setting depositLimit to 0 @@ -229,9 +228,8 @@ Shutdown mode does not affect accounting. - **Shutdown mode**: All strategies' `maxDebt` is set to 0. Strategies will return funds as soon as they can. ### Relevant emergency -If the current roles stop fulfilling their responsibilities or something else happens, the `EMERGENCY_MANAGER` can shut down the vault. -The shutdown mode should be the last option in an emergency, as it is irreversible. +> If the current roles stop fulfilling their responsibilities or something else happens, the `EMERGENCY_MANAGER` can shut down the vault. The shutdown mode should be the last option in an emergency, as it is irreversible. During shutdown mode, the vault will try to get funds back from every strategy as soon as possible. From 8d3c4b84b84642511922d1aa2fb04e4cd59b9e44 Mon Sep 17 00:00:00 2001 From: Marco Worms Date: Fri, 2 Dec 2022 12:43:35 -0300 Subject: [PATCH 04/54] improve quoting style --- docs/getting-started/products/yvaults/v3.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/getting-started/products/yvaults/v3.md b/docs/getting-started/products/yvaults/v3.md index 372c3ca192..b5c07efd4e 100644 --- a/docs/getting-started/products/yvaults/v3.md +++ b/docs/getting-started/products/yvaults/v3.md @@ -211,7 +211,9 @@ The most important implication is that `withdraw` and `redeem` functions as pres ### Shutdown mode -> If the current roles stop fulfilling their responsibilities or something else happens, the `EMERGENCY_MANAGER` can shut down the vault. The shutdown mode should be the last option in an emergency, as it is irreversible. +If the current roles stop fulfilling their responsibilities or something else happens, the `EMERGENCY_MANAGER` can shut down the vault. + +The shutdown mode should be the last option in an emergency, as it is irreversible. ### Deposits - **Light emergency:** Deposits can be paused by setting depositLimit to 0 @@ -229,7 +231,9 @@ Shutdown mode does not affect accounting. ### Relevant emergency -> If the current roles stop fulfilling their responsibilities or something else happens, the `EMERGENCY_MANAGER` can shut down the vault. The shutdown mode should be the last option in an emergency, as it is irreversible. +> If the current roles stop fulfilling their responsibilities or something else happens, the `EMERGENCY_MANAGER` can shut down the vault. +> +> The shutdown mode should be the last option in an emergency, as it is irreversible. During shutdown mode, the vault will try to get funds back from every strategy as soon as possible. From a456a377b94b427bdf85fc1a1eed86bfc51b8c04 Mon Sep 17 00:00:00 2001 From: Marco Worms Date: Fri, 2 Dec 2022 12:47:34 -0300 Subject: [PATCH 05/54] fix leftover header --- docs/getting-started/products/yvaults/v3.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/getting-started/products/yvaults/v3.md b/docs/getting-started/products/yvaults/v3.md index b5c07efd4e..9117b6ea36 100644 --- a/docs/getting-started/products/yvaults/v3.md +++ b/docs/getting-started/products/yvaults/v3.md @@ -26,9 +26,7 @@ Peripheral Modules are a separate layer of optional functions for the vault and - **ySwaps:** Internal swap system currently being developed. Reduces slippage thus improve net APY. - And any other you can come up with! -## V3 yVault Specification - -# Yearn System Specification (DRAFT) +# V3 yVault Specification ## Definitions - **Asset:** Any ERC20-compliant token From 9afd4b4254317bd2d9868ceb1d28f5f8393d549b Mon Sep 17 00:00:00 2001 From: Marco Worms Date: Fri, 2 Dec 2022 16:02:05 -0300 Subject: [PATCH 06/54] add read more links to v3 docs --- docs/getting-started/products/yvaults/v3.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/getting-started/products/yvaults/v3.md b/docs/getting-started/products/yvaults/v3.md index 9117b6ea36..f8d0469c4e 100644 --- a/docs/getting-started/products/yvaults/v3.md +++ b/docs/getting-started/products/yvaults/v3.md @@ -237,4 +237,9 @@ During shutdown mode, the vault will try to get funds back from every strategy a No strategies can be added during shutdown. -Any relevant role will start pointing to the `EMERGENCY_MANAGER` in case new permissioned allowed actions need to be taken. \ No newline at end of file +Any relevant role will start pointing to the `EMERGENCY_MANAGER` in case new permissioned allowed actions need to be taken. + +# Read more + +- https://medium.com/iearn/yearnv3-motivation-and-design-107840cb4844 +- https://medium.com/iearn/yearn-vaults-v3-36ce7c468ca0 \ No newline at end of file From c713a4993dc3e6e9e39550215fb18a800b269d40 Mon Sep 17 00:00:00 2001 From: Dark Ghosty <38810205+DarkGhost7@users.noreply.github.com> Date: Thu, 8 Dec 2022 16:39:53 -0500 Subject: [PATCH 07/54] fix: wording --- docs/getting-started/products/yvaults/v3.md | 26 ++++++++++----------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/getting-started/products/yvaults/v3.md b/docs/getting-started/products/yvaults/v3.md index f8d0469c4e..e183666bf6 100644 --- a/docs/getting-started/products/yvaults/v3.md +++ b/docs/getting-started/products/yvaults/v3.md @@ -1,39 +1,39 @@ -# Vaults V3 +# Vaults Version 3 -V3 Vaults iterates on V2 to increase robustness and develop yearn’s path towards further decentralization, while keeping the same proven product (yield-bearing tokens) that abstract builders and users from the hard work of yield farming. V3 will initially have the same functionality as V2, but vaults are more robust and modular. +Version 3 yVaults iterates on Version 2 by increasing robustness and developing yearn’s path towards further decentralization, while keeping the same proven product (yield-bearing tokens) that abstract builders and users from the hard work of yield farming. Version 3 will initially have the same functionality as Version 2, but the vaults are more robust and modular. -V3 Vaults improves on V2 by: +Version 3 yVaults improves on Version 2 by: - Increasing vault modularity, allowing for smaller and safer pieces of code. -- Simplify strategy creation, empowering strategists and reducing chance for errors. -- Adding new products like ySwaps that increase swaps efficiency and yJuniorTranches that allow for different risk profiles. +- Simplify strategy creation, empowering strategists and reducing the chance for errors. +- Adding new products like ySwaps which increases swap efficiency and yJuniorTranches which allows for different risk profiles. ## Smart Modules -Smart Modules implement logic to be iterated until it can be made immutable. If any Smart Module fails, the vault can live without them just enough to return funds to depositors. **When V3 launches, the Smart Modules will replicate V2 vault behavior.** +Smart Modules implement logic to be iterated until it can be made immutable. If any Smart Module fails, the vault can live without them just enough to return funds to depositors. **When Version 3 launches, the Smart Modules will replicate Version 2 vault behavior.** - **Debt Allocator:** Knows the maximum debt a vault can send to a strategy. - **Strategy Registry:** Handles adding and removing strategies of a vault. It can also include strategy metadata. - **Fee Manager:** Handles changing fees for vault operations. -- **HealthCheck:** Guardrails vault operations so that profit & loss reporting is always under acceptable values. +- **HealthCheck:** Guardrail vault operations so that profit & loss reporting is always under acceptable values. ## Peripheral Modules Peripheral Modules are a separate layer of optional functions for the vault and strategies. They are not required but they facilitate building around yVaults and creating new strategies. -- **yRouter**: Wrapper that handles deposits and withdrawals to/from vault. +- **yRouter**: Wrapper that handles deposits and withdrawals to/from the vault. - **Yearn Lens:** Information aggregator for off-chain apps. -- **APY TWAP Oracle:** Reliable source of yearn vault’s past performance. -- **ySwaps:** Internal swap system currently being developed. Reduces slippage thus improve net APY. -- And any other you can come up with! +- **APY TWAP Oracle:** Reliable source of Yearn vaults’ past performance. +- **ySwaps:** Internal swap system currently being developed. Reduces slippage thus improving net APY. +- And any others you can come up with! -# V3 yVault Specification +# Version 3 yVault Specification ## Definitions - **Asset:** Any ERC20-compliant token - **Shares:** ERC20-compliant token that tracks Asset balance in the vault for every distributor. Named yv - **Depositor:** Account that holds Shares - **Strategy:** Smart contract used to deposit in Protocols to generate yield -- **Vault:** ERC4626 compliant Smart contract that receives Assets from Depositors to distribute them among the different Strategies added to the vault, managing accounting and Assets distribution. +- **Vault:** ERC4626 compliant smart contract that receives Assets from Depositors to distribute amongst the different Strategies added to the vault: manages accounting and Assets distribution. - **Role:** Flags that an Account can do specific Vault actions. Can be fulfilled by a smart contract or an EOA. - **Accountant:** Smart contract that receives P&L reporting and returns shares and refunds to the strategy From 6a61bc8815f55f08a18f71c38aeb3f41b75aca98 Mon Sep 17 00:00:00 2001 From: Dark Ghosty <38810205+DarkGhost7@users.noreply.github.com> Date: Thu, 8 Dec 2022 19:27:31 -0500 Subject: [PATCH 08/54] fix: grammar and small fixes --- docs/getting-started/products/yvaults/v3.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/getting-started/products/yvaults/v3.md b/docs/getting-started/products/yvaults/v3.md index e183666bf6..f3ba50dddc 100644 --- a/docs/getting-started/products/yvaults/v3.md +++ b/docs/getting-started/products/yvaults/v3.md @@ -37,8 +37,8 @@ Peripheral Modules are a separate layer of optional functions for the vault and - **Role:** Flags that an Account can do specific Vault actions. Can be fulfilled by a smart contract or an EOA. - **Accountant:** Smart contract that receives P&L reporting and returns shares and refunds to the strategy -# VaultV3 Specification -The Vault code has been designed as an unopinionated system to distribute depositors funds into different opportunities (aka Strategies) and robustly manage accounting. +# Vault Version 3 Specification +The Vault code has been designed as an unopinionated system to distribute depositors' funds into different opportunities (aka Strategies) and robustly manage accounting. The depositors receive shares of the different investments that can then be redeemed or used as yield-bearing tokens. @@ -46,9 +46,9 @@ The Vault does not have a preference on any of the dimensions that should be con - **Decentralization**: Roles can be filled by common wallets, smart contracts like multisigs or governance modules. - **Liquidity**: Vault can have 0 liquidity or be fully liquid. It will depend on the parameters and strategies added. - **Security**: Vault managers can choose what strategies to add and how to do that process. -- **Automation**: All the required actions to maintain the vault can be called by bots or manually, depending on periphery implementation. +- **Automation**: All the required actions to maintain the vault can be called manually or by bots, depending on periphery implementation. -The compromises will come with implementing periphery contracts fulfilling the roles in the Vault. This allows different players to deploy their own version and implement their own periphery contracts (or not use any at all) +The compromises will come with implementing periphery contracts fulfilling the roles in the Vault. This allows different players to deploy their own version and implement their own periphery contracts (or not use any at all). ## Example periphery contracts: From 8a64e395faf8f9b24bad1ca7d1dbc4b9764be2b3 Mon Sep 17 00:00:00 2001 From: Dark Ghosty <38810205+DarkGhost7@users.noreply.github.com> Date: Thu, 8 Dec 2022 19:28:15 -0500 Subject: [PATCH 09/54] fix: space --- docs/getting-started/products/yvaults/v3.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/getting-started/products/yvaults/v3.md b/docs/getting-started/products/yvaults/v3.md index f3ba50dddc..2a940e94c8 100644 --- a/docs/getting-started/products/yvaults/v3.md +++ b/docs/getting-started/products/yvaults/v3.md @@ -50,7 +50,6 @@ The Vault does not have a preference on any of the dimensions that should be con The compromises will come with implementing periphery contracts fulfilling the roles in the Vault. This allows different players to deploy their own version and implement their own periphery contracts (or not use any at all). - ## Example periphery contracts: - **Emergency module:** Receives deposits of Vault Shares and allows the contract to call the shutdown function after a certain % of total Vault Shares have been deposited. - **Debt Allocator:** Smart contract that incentivizes APY / debt allocation optimization by rewarding the best debt allocation (see [yStarkDebtAllocator](https://github.com/jmonteer/ystarkdebtallocator)). From 270bdd5fc33b8676e3b509c3ecbac9e1c5828957 Mon Sep 17 00:00:00 2001 From: Dark Ghosty <38810205+DarkGhost7@users.noreply.github.com> Date: Thu, 8 Dec 2022 19:45:18 -0500 Subject: [PATCH 10/54] fix: more fixes --- docs/getting-started/products/yvaults/v3.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/getting-started/products/yvaults/v3.md b/docs/getting-started/products/yvaults/v3.md index 2a940e94c8..01dfc459b9 100644 --- a/docs/getting-started/products/yvaults/v3.md +++ b/docs/getting-started/products/yvaults/v3.md @@ -58,12 +58,12 @@ The compromises will come with implementing periphery contracts fulfilling the r ## Deployment We expect all the vaults available to be deployed from a Factory Contract, publicly available and callable. -Players deploying "branded" vaults (e.g. Yearn) will use a separate registry to allow permissioned endorsement of vaults for their product +Players deploying "branded" vaults (e.g. Yearn) will use a separate registry to allow permissioned endorsement of vaults for their product. When deploying a new vault, it requires the following parameters: - **asset:** Address of the ERC20 token that can be deposited in the vault. -- **name:** Name of Shares as described in ERC20. -- **symbol:** Symbol of Shares ERC20. +- **name:** Name of Shares as described in the ERC20. +- **symbol:** Symbol of Shares in the ERC20. - **role_manager:** Account that can assign and revoke Roles. - **PROFIT_MAX_UNLOCK_TIME:** Max amount of time profit will be distributed over. @@ -99,16 +99,16 @@ This is done by comparing the current debt of the strategy with the total assets Both loss and profit will impact the strategy's debt, increasing the debt (current debt + profit) if there are profits, and decreasing its debt (current debt - loss) if there are losses. #### Fees -The Accountant module handles fee assessment and distribution. It will report the amount of fees that need to be charged, and the vault will issue shares for that amount of fees. +The Accountant module handles fee assessment and distribution. It will report the fees that need to be charged, and the vault will issue shares for that amount of fees. #### Refunds -Refunds are positive inflows for the vault, and are sent to the vault to reward it or compensate in anyway. The Accountant module will take care of them. +Refunds are positive inflows and are sent to the vault to reward it or compensate the vault in any way. The Accountant module will take care of them. An example is an insurance mechanism like different risk tranches where the accountant will send assets to the vault to compensate for losses (and, in exchange, take higher fees). -The refunds are paid in the form of vault shares and will be instantly locked (and released gradually) +The refunds are paid in the form of vault shares and will be instantly locked (and released gradually). -### Profit distribution +### Profit Distribution Profit from different process_report calls will accumulate in a buffer. This buffer will be linearly unlocked over the locking period seconds at profit_distribution_rate. Profits will be locked for a max period of PROFIT_MAX_UNLOCK_TIME seconds and will be gradually distributed. To avoid spending too much gas for profit unlock, the period that profit will be locked for is a weighted average between the new profit and the previous profit. From e8aa86750dab7882f48d43339a12747c797ebae2 Mon Sep 17 00:00:00 2001 From: Dark Ghosty <38810205+DarkGhost7@users.noreply.github.com> Date: Thu, 8 Dec 2022 19:56:16 -0500 Subject: [PATCH 11/54] fix: various --- docs/getting-started/products/yvaults/v3.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/getting-started/products/yvaults/v3.md b/docs/getting-started/products/yvaults/v3.md index 01dfc459b9..8877d21b8f 100644 --- a/docs/getting-started/products/yvaults/v3.md +++ b/docs/getting-started/products/yvaults/v3.md @@ -104,7 +104,7 @@ The Accountant module handles fee assessment and distribution. It will report th #### Refunds Refunds are positive inflows and are sent to the vault to reward it or compensate the vault in any way. The Accountant module will take care of them. -An example is an insurance mechanism like different risk tranches where the accountant will send assets to the vault to compensate for losses (and, in exchange, take higher fees). +An example is an insurance mechanism like different risk tranches where the Accountant will send assets to the vault to compensate for losses (and, in exchange, take higher fees). The refunds are paid in the form of vault shares and will be instantly locked (and released gradually). @@ -116,13 +116,13 @@ Profits will be locked for a max period of PROFIT_MAX_UNLOCK_TIME seconds and wi - `new_locking_period = locked_profit * pending_time_to_unlock + new_profit * PROFIT_MAX_UNLOCK_TIME / (locked_profit + new_profit)` - `new_profit_distribution_rate = (locked_profit + new_profit) / new_locking_period` -Losses will be offset by locked profit, if possible. That makes frontrunning losses impossible (unless loss > locked profit) +Losses will be offset by locked profit, if possible. That makes frontrunning losses impossible (unless loss > locked profit). -Issue of new shares due to fees will also insta-unlock profit so that price-per-share (pps) does not go down. +Issue of new shares due to fees will also instantly unlocked profit so that price-per-share does not go down. -Both of these offsets will prevent frontrunning (as the profit was already earned and was not distributed yet) +Both of these offsets will prevent frontrunning (as the profit was already earned and was not distributed yet). -Instead of locking the profit, and in order to be more capital efficient (and avoid complex asset management), the vault issues shares that holds itself. Those shares are gradually burned over time (increasing pps). So instead of releasing assets, the vault will gradually burn shares. +Instead of locking the profit, and to be more capital efficient (and avoid complex asset management), the vault issues shares that holds itself. Those shares are gradually burned over time (increasing price-per-share). So instead of releasing assets, the vault will gradually burn shares. ## Vault Management Vault management is split into two fields: strategy management and debt management @@ -130,13 +130,13 @@ Vault management is split into two fields: strategy management and debt manageme ### Strategy Management Callers take this responsibility with the `STRATEGY_MANAGER` role -A vault can have strategies added, removed and migrated +A vault can have strategies added, removed, and migrated. -Added strategies will be eligible to receive funds from the vault, when the `max_debt` is set to > 0 +Added strategies will be eligible to receive funds from the vault when `max_debt` is set to > 0. -Revoked strategies will return all debt and stop being eligible to receive more. It can only be done when the strategy's `current_debt` is 0 +Revoked strategies will return all debt and be ineligible to receive more. This happens when the strategy's `current_debt` is 0. -Strategy migration is the process of replacing an existing strategy with a new one, which will inherit all parameters, including its debt +Strategy migration is the process of replacing an existing strategy with a new one, which will inherit all of the old strategy's parameters, including its debt. ### Debt Management Callers take this responsibility with the `DEBT_MANAGER` role From c81c5b3821876aa45dcb91a257ceace1e294485a Mon Sep 17 00:00:00 2001 From: Dark Ghosty <38810205+DarkGhost7@users.noreply.github.com> Date: Fri, 9 Dec 2022 16:25:34 -0500 Subject: [PATCH 12/54] fixes --- docs/getting-started/products/yvaults/v3.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/products/yvaults/v3.md b/docs/getting-started/products/yvaults/v3.md index 8877d21b8f..499766717e 100644 --- a/docs/getting-started/products/yvaults/v3.md +++ b/docs/getting-started/products/yvaults/v3.md @@ -125,7 +125,7 @@ Both of these offsets will prevent frontrunning (as the profit was already earne Instead of locking the profit, and to be more capital efficient (and avoid complex asset management), the vault issues shares that holds itself. Those shares are gradually burned over time (increasing price-per-share). So instead of releasing assets, the vault will gradually burn shares. ## Vault Management -Vault management is split into two fields: strategy management and debt management +Vault management is split into two fields: strategy management and debt management. ### Strategy Management Callers take this responsibility with the `STRATEGY_MANAGER` role From fc4f4a70adbd42ce004777b600aa9ce819c9f9df Mon Sep 17 00:00:00 2001 From: Dark Ghosty <38810205+DarkGhost7@users.noreply.github.com> Date: Fri, 9 Dec 2022 16:27:59 -0500 Subject: [PATCH 13/54] fix: smart modules Co-authored-by: Marco Guaspari Worms --- docs/getting-started/products/yvaults/v3.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/products/yvaults/v3.md b/docs/getting-started/products/yvaults/v3.md index 499766717e..18201b3c8d 100644 --- a/docs/getting-started/products/yvaults/v3.md +++ b/docs/getting-started/products/yvaults/v3.md @@ -9,7 +9,7 @@ Version 3 yVaults improves on Version 2 by: ## Smart Modules -Smart Modules implement logic to be iterated until it can be made immutable. If any Smart Module fails, the vault can live without them just enough to return funds to depositors. **When Version 3 launches, the Smart Modules will replicate Version 2 vault behavior.** +Smart Modules implement core vault logic that will be iterated until they can be made immutable. If any Smart Module fails, the vault can live without them just enough to return funds to depositors. **When Version 3 launches, the Smart Modules will replicate Version 2 vault behavior.** - **Debt Allocator:** Knows the maximum debt a vault can send to a strategy. - **Strategy Registry:** Handles adding and removing strategies of a vault. It can also include strategy metadata. From e8440830fd9a607f75555de6915c1f47a1b822a5 Mon Sep 17 00:00:00 2001 From: Dark Ghosty <38810205+DarkGhost7@users.noreply.github.com> Date: Fri, 9 Dec 2022 16:36:47 -0500 Subject: [PATCH 14/54] fix: punctuation --- docs/getting-started/products/yvaults/v3.md | 34 ++++++++++----------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/docs/getting-started/products/yvaults/v3.md b/docs/getting-started/products/yvaults/v3.md index 18201b3c8d..472d98e1ad 100644 --- a/docs/getting-started/products/yvaults/v3.md +++ b/docs/getting-started/products/yvaults/v3.md @@ -128,7 +128,7 @@ Instead of locking the profit, and to be more capital efficient (and avoid compl Vault management is split into two fields: strategy management and debt management. ### Strategy Management -Callers take this responsibility with the `STRATEGY_MANAGER` role +Callers take this responsibility with the `STRATEGY_MANAGER` role. A vault can have strategies added, removed, and migrated. @@ -139,22 +139,22 @@ Revoked strategies will return all debt and be ineligible to receive more. This Strategy migration is the process of replacing an existing strategy with a new one, which will inherit all of the old strategy's parameters, including its debt. ### Debt Management -Callers take this responsibility with the `DEBT_MANAGER` role +Callers take this responsibility with the `DEBT_MANAGER` role. #### Setting minimum idle funds -The debt manager can specify how many funds the vault should try to have reserved to serve withdrawal requests +The debt manager can specify how many funds the vault should try to have reserved to serve withdrawal requests. -These funds will remain in the vault unless requested by a Depositor +These funds will remain in the vault unless requested by a Depositor. #### Setting maximum debt for a specific strategy The maximum amount of tokens the vault will allow a strategy to owe at any moment. -Stored in `strategies[strategy].max_debt` +Stored in `strategies[strategy].max_debt`. -When a debt rebalance is triggered, the Vault will cap the new target debt to this number (max_debt) +When a debt rebalance is triggered, the Vault will cap the new target debt to this number (max_debt). #### Rebalance Debt -The vault sends and receives funds to/from strategies. The function updateDebt(strategy, target_debt) will set the current_debt of the strategy to target_debt (if possible) +The vault sends and receives funds to/from strategies. The function updateDebt(strategy, target_debt) will set the current_debt of the strategy to target_debt (if possible). If the strategy currently has less debt than the target_debt, the vault will send funds to it. @@ -166,10 +166,10 @@ The vault will request back funds if the strategy has more debt than the `max_de Vault functions that are permissioned will be callable by accounts with specific roles. These are: -- `STRATEGY_MANAGER:` role for accounts that can add, remove or migrate strategies -- `DEBT_MANAGER:` role for accounts that can rebalance and manage debt related params -- `EMERGENCY_MANAGER:` role for accounts that can activate the shutdown mode -- `ACCOUNTING_MANAGER:` role for accounts that can process reports (save strategy p&l) and change accountant parameters +- `STRATEGY_MANAGER:` role for accounts that can add, remove or migrate strategies. +- `DEBT_MANAGER:` role for accounts that can rebalance and manage debt related params. +- `EMERGENCY_MANAGER:` role for accounts that can activate the shutdown mode. +- `ACCOUNTING_MANAGER:` role for accounts that can process reports (save strategy p&l) and change accountant parameters. Every role can be filled by an EOA, multisig, or other smart contracts. Each role can be filled by several accounts. @@ -193,9 +193,9 @@ In any case, to be compatible with the vault, they need to implement the followi This means that the vault can deposit into any ERC4626 vault and that a non-compliant strategy can be implemented provided that these functions have been implemented (even in a non ERC4626 compliant way). Anything else is left to the strategy writer. However, to make security review easier, the Yearn's template has the following optional functions: -- `tend():` a function that will be called by bots. It will do anything to maintain a position, act on certain triggers, ... -- `tendTrigger():` implementation that trigger bots that will call tend function on the contract -- `invest():` deposit funds into underlying protocol +- `tend():` a function that will be called by bots. It will do anything to maintain a position, such as act on certain triggers. +- `tendTrigger():` implementation that trigger bots that will call tend function on the contract. +- `invest():` deposit funds into underlying protocol. - `emergencyFreeFunds():` close the position and return funds to the strategy. Losses might be accepted here. @@ -213,8 +213,8 @@ If the current roles stop fulfilling their responsibilities or something else ha The shutdown mode should be the last option in an emergency, as it is irreversible. ### Deposits -- **Light emergency:** Deposits can be paused by setting depositLimit to 0 -- **Shutdown mode:** Deposits are not allowed +- **Light emergency:** Deposits can be paused by setting depositLimit to 0. +- **Shutdown mode:** Deposits are not allowed. ### Withdrawals Withdrawals can't be paused under any circumstance. @@ -223,7 +223,7 @@ Withdrawals can't be paused under any circumstance. Shutdown mode does not affect accounting. ### Debt rebalance -- **Light emergency**: Setting minimumTotalIdle to MAX_UINT256 will result in the vault requesting the debt back from strategies. This would stop new strategies from getting funded too, as the vault prioritizes minimumTotalIdle +- **Light emergency**: Setting minimumTotalIdle to MAX_UINT256 will result in the vault requesting the debt back from strategies. This would stop new strategies from getting funded too, as the vault prioritizes minimumTotalIdle. - **Shutdown mode**: All strategies' `maxDebt` is set to 0. Strategies will return funds as soon as they can. ### Relevant emergency From 800e7e7163bceb66a4044674dc1265cad075a118 Mon Sep 17 00:00:00 2001 From: Dark Ghosty <38810205+DarkGhost7@users.noreply.github.com> Date: Fri, 9 Dec 2022 16:40:03 -0500 Subject: [PATCH 15/54] fix: debt manager & update title --- docs/getting-started/products/yvaults/v3.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/getting-started/products/yvaults/v3.md b/docs/getting-started/products/yvaults/v3.md index 472d98e1ad..394263bda0 100644 --- a/docs/getting-started/products/yvaults/v3.md +++ b/docs/getting-started/products/yvaults/v3.md @@ -1,4 +1,4 @@ -# Vaults Version 3 +# Version 3 Version 3 yVaults iterates on Version 2 by increasing robustness and developing yearn’s path towards further decentralization, while keeping the same proven product (yield-bearing tokens) that abstract builders and users from the hard work of yield farming. Version 3 will initially have the same functionality as Version 2, but the vaults are more robust and modular. @@ -142,7 +142,7 @@ Strategy migration is the process of replacing an existing strategy with a new o Callers take this responsibility with the `DEBT_MANAGER` role. #### Setting minimum idle funds -The debt manager can specify how many funds the vault should try to have reserved to serve withdrawal requests. +The `DEBT_MANAGER` can specify how much funds the vault should try to have reserved to serve withdrawal requests. These funds will remain in the vault unless requested by a Depositor. From a878979bf3684f556bca069f969053ac3e640160 Mon Sep 17 00:00:00 2001 From: Dark Ghosty <38810205+DarkGhost7@users.noreply.github.com> Date: Fri, 9 Dec 2022 16:51:00 -0500 Subject: [PATCH 16/54] fix: various fixes, eoa, multisig --- docs/getting-started/products/yvaults/v3.md | 30 ++++++++++----------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/getting-started/products/yvaults/v3.md b/docs/getting-started/products/yvaults/v3.md index 394263bda0..9c57d66b6f 100644 --- a/docs/getting-started/products/yvaults/v3.md +++ b/docs/getting-started/products/yvaults/v3.md @@ -34,7 +34,7 @@ Peripheral Modules are a separate layer of optional functions for the vault and - **Depositor:** Account that holds Shares - **Strategy:** Smart contract used to deposit in Protocols to generate yield - **Vault:** ERC4626 compliant smart contract that receives Assets from Depositors to distribute amongst the different Strategies added to the vault: manages accounting and Assets distribution. -- **Role:** Flags that an Account can do specific Vault actions. Can be fulfilled by a smart contract or an EOA. +- **Role:** Flags that an Account can do specific Vault actions. Can be fulfilled by a smart contract or an externally owned account. - **Accountant:** Smart contract that receives P&L reporting and returns shares and refunds to the strategy # Vault Version 3 Specification @@ -43,7 +43,7 @@ The Vault code has been designed as an unopinionated system to distribute deposi The depositors receive shares of the different investments that can then be redeemed or used as yield-bearing tokens. The Vault does not have a preference on any of the dimensions that should be considered when operating a vault: -- **Decentralization**: Roles can be filled by common wallets, smart contracts like multisigs or governance modules. +- **Decentralization**: Roles can be filled by common wallets, smart contracts like multi-signatures or governance modules. - **Liquidity**: Vault can have 0 liquidity or be fully liquid. It will depend on the parameters and strategies added. - **Security**: Vault managers can choose what strategies to add and how to do that process. - **Automation**: All the required actions to maintain the vault can be called manually or by bots, depending on periphery implementation. @@ -142,40 +142,40 @@ Strategy migration is the process of replacing an existing strategy with a new o Callers take this responsibility with the `DEBT_MANAGER` role. #### Setting minimum idle funds -The `DEBT_MANAGER` can specify how much funds the vault should try to have reserved to serve withdrawal requests. +The `DEBT_MANAGER` specifies how much funds the vault should reserve to serve withdrawal requests. -These funds will remain in the vault unless requested by a Depositor. +These funds will remain in the vault unless requested by a depositor. #### Setting maximum debt for a specific strategy The maximum amount of tokens the vault will allow a strategy to owe at any moment. Stored in `strategies[strategy].max_debt`. -When a debt rebalance is triggered, the Vault will cap the new target debt to this number (max_debt). +When a debt rebalance is triggered, the Vault will cap the new target debt to this number `max_debt`. #### Rebalance Debt -The vault sends and receives funds to/from strategies. The function updateDebt(strategy, target_debt) will set the current_debt of the strategy to target_debt (if possible). +The vault sends and receives funds to/from strategies. The function `updateDebt(strategy, target_debt)` will set the `current_debt` of the strategy to the `target_debt`, if possible. -If the strategy currently has less debt than the target_debt, the vault will send funds to it. +If the strategy currently has less debt than the `target_debt`, the vault will send funds to it. The vault checks that the `minimumTotalIdle` parameter is respected (i.e. there's at least a certain amount of funds in the vault). -The vault will request back funds if the strategy has more debt than the `max_debt`. These funds may be locked in the strategy, which will result in the strategy returning fewer funds than requested by the vault. +The vault will request back funds if the strategy has more debt than `max_debt`. These funds may be locked in the strategy, which would result in the strategy returning fewer funds than requested by the vault. ## Roles Vault functions that are permissioned will be callable by accounts with specific roles. -These are: -- `STRATEGY_MANAGER:` role for accounts that can add, remove or migrate strategies. -- `DEBT_MANAGER:` role for accounts that can rebalance and manage debt related params. -- `EMERGENCY_MANAGER:` role for accounts that can activate the shutdown mode. -- `ACCOUNTING_MANAGER:` role for accounts that can process reports (save strategy p&l) and change accountant parameters. +These roles are: +- `STRATEGY_MANAGER`: role for accounts that can add, remove, or migrate strategies. +- `DEBT_MANAGER`: role for accounts that can rebalance and manage debt-related parameters. +- `EMERGENCY_MANAGER`: role for accounts that can activate the shutdown mode. +- `ACCOUNTING_MANAGER`: role for accounts that can process reports (save strategy p&l) and change accountant parameters. -Every role can be filled by an EOA, multisig, or other smart contracts. Each role can be filled by several accounts. +Every role can be filled by an externally owned account, multi-signature wallet, or other smart contracts. Each role can be filled by several accounts. The account that manages roles is a single account, set in `role_manager`. -This `role_manager` can be an EOA, a multisig, or a Governance Module that relays calls. +This `role_manager` can be an externally owned account, a multi-signature wallet, or a Governance Module that relays calls. ## Strategy Minimum API Strategies are completely independent smart contracts that can be implemented following the proposed template or in any other way. From 5a39f9699d3fbb399acd4b57598545a3d5815f0f Mon Sep 17 00:00:00 2001 From: Dark Ghosty <38810205+DarkGhost7@users.noreply.github.com> Date: Fri, 9 Dec 2022 16:55:40 -0500 Subject: [PATCH 17/54] fix: remove colon outside of special highlighting --- docs/getting-started/products/yvaults/v3.md | 72 ++++++++++----------- 1 file changed, 36 insertions(+), 36 deletions(-) diff --git a/docs/getting-started/products/yvaults/v3.md b/docs/getting-started/products/yvaults/v3.md index 9c57d66b6f..ed87ed3590 100644 --- a/docs/getting-started/products/yvaults/v3.md +++ b/docs/getting-started/products/yvaults/v3.md @@ -11,31 +11,31 @@ Version 3 yVaults improves on Version 2 by: Smart Modules implement core vault logic that will be iterated until they can be made immutable. If any Smart Module fails, the vault can live without them just enough to return funds to depositors. **When Version 3 launches, the Smart Modules will replicate Version 2 vault behavior.** -- **Debt Allocator:** Knows the maximum debt a vault can send to a strategy. -- **Strategy Registry:** Handles adding and removing strategies of a vault. It can also include strategy metadata. -- **Fee Manager:** Handles changing fees for vault operations. -- **HealthCheck:** Guardrail vault operations so that profit & loss reporting is always under acceptable values. +- **Debt Allocator**: Knows the maximum debt a vault can send to a strategy. +- **Strategy Registry**: Handles adding and removing strategies of a vault. It can also include strategy metadata. +- **Fee Manager**: Handles changing fees for vault operations. +- **HealthCheck**: Guardrail vault operations so that profit & loss reporting is always under acceptable values. ## Peripheral Modules Peripheral Modules are a separate layer of optional functions for the vault and strategies. They are not required but they facilitate building around yVaults and creating new strategies. - **yRouter**: Wrapper that handles deposits and withdrawals to/from the vault. -- **Yearn Lens:** Information aggregator for off-chain apps. -- **APY TWAP Oracle:** Reliable source of Yearn vaults’ past performance. -- **ySwaps:** Internal swap system currently being developed. Reduces slippage thus improving net APY. +- **Yearn Lens**: Information aggregator for off-chain apps. +- **APY TWAP Oracle**: Reliable source of Yearn vaults’ past performance. +- **ySwaps**: Internal swap system currently being developed. Reduces slippage thus improving net APY. - And any others you can come up with! # Version 3 yVault Specification ## Definitions -- **Asset:** Any ERC20-compliant token -- **Shares:** ERC20-compliant token that tracks Asset balance in the vault for every distributor. Named yv -- **Depositor:** Account that holds Shares -- **Strategy:** Smart contract used to deposit in Protocols to generate yield -- **Vault:** ERC4626 compliant smart contract that receives Assets from Depositors to distribute amongst the different Strategies added to the vault: manages accounting and Assets distribution. -- **Role:** Flags that an Account can do specific Vault actions. Can be fulfilled by a smart contract or an externally owned account. -- **Accountant:** Smart contract that receives P&L reporting and returns shares and refunds to the strategy +- **Asset**: Any ERC20-compliant token +- **Shares**: ERC20-compliant token that tracks Asset balance in the vault for every distributor. Named yv +- **Depositor**: Account that holds Shares +- **Strategy**: Smart contract used to deposit in Protocols to generate yield +- **Vault**: ERC4626 compliant smart contract that receives Assets from Depositors to distribute amongst the different Strategies added to the vault: manages accounting and Assets distribution. +- **Role**: Flags that an Account can do specific Vault actions. Can be fulfilled by a smart contract or an externally owned account. +- **Accountant**: Smart contract that receives P&L reporting and returns shares and refunds to the strategy # Vault Version 3 Specification The Vault code has been designed as an unopinionated system to distribute depositors' funds into different opportunities (aka Strategies) and robustly manage accounting. @@ -51,9 +51,9 @@ The Vault does not have a preference on any of the dimensions that should be con The compromises will come with implementing periphery contracts fulfilling the roles in the Vault. This allows different players to deploy their own version and implement their own periphery contracts (or not use any at all). ## Example periphery contracts: -- **Emergency module:** Receives deposits of Vault Shares and allows the contract to call the shutdown function after a certain % of total Vault Shares have been deposited. -- **Debt Allocator:** Smart contract that incentivizes APY / debt allocation optimization by rewarding the best debt allocation (see [yStarkDebtAllocator](https://github.com/jmonteer/ystarkdebtallocator)). -- **Strategy Staking Module:** Smart contract that allows players to sponsor specific strategies (so that they are added to the vault) by staking their YFI, making money if they do well and losing money if they don't. +- **Emergency module**: Receives deposits of Vault Shares and allows the contract to call the shutdown function after a certain % of total Vault Shares have been deposited. +- **Debt Allocator**: Smart contract that incentivizes APY / debt allocation optimization by rewarding the best debt allocation (see [yStarkDebtAllocator](https://github.com/jmonteer/ystarkdebtallocator)). +- **Strategy Staking Module**: Smart contract that allows players to sponsor specific strategies (so that they are added to the vault) by staking their YFI, making money if they do well and losing money if they don't. ## Deployment We expect all the vaults available to be deployed from a Factory Contract, publicly available and callable. @@ -61,11 +61,11 @@ We expect all the vaults available to be deployed from a Factory Contract, publi Players deploying "branded" vaults (e.g. Yearn) will use a separate registry to allow permissioned endorsement of vaults for their product. When deploying a new vault, it requires the following parameters: -- **asset:** Address of the ERC20 token that can be deposited in the vault. -- **name:** Name of Shares as described in the ERC20. -- **symbol:** Symbol of Shares in the ERC20. -- **role_manager:** Account that can assign and revoke Roles. -- **PROFIT_MAX_UNLOCK_TIME:** Max amount of time profit will be distributed over. +- **asset**: Address of the ERC20 token that can be deposited in the vault. +- **name**: Name of Shares as described in the ERC20. +- **symbol**: Symbol of Shares in the ERC20. +- **role_manager**: Account that can assign and revoke Roles. +- **PROFIT_MAX_UNLOCK_TIME**: Max amount of time profit will be distributed over. ## Normal Operation @@ -181,22 +181,22 @@ This `role_manager` can be an externally owned account, a multi-signature wallet Strategies are completely independent smart contracts that can be implemented following the proposed template or in any other way. In any case, to be compatible with the vault, they need to implement the following functions, which are a subset of ERC4626 vaults: -- `asset():` View returning underlying asset. -- `vault():` View returning vault this strategy is plugged to. -- `totalAssets():` View returning current amount of assets. It can include rewards valued in `asset`. -- `maxDeposit(address):` View returning the amount max that the strategy can take safely. -- `deposit(assets, receiver):` Deposits `assets` amount of tokens into the strategy. It can be restricted to the vault only or be open. -- `maxWithdraw(address):` View returning how many assets can the vault take from the vault at any given point in time. -- `withdraw(assets, receiver, owner):` Withdraws `assets` amount of tokens from the strategy. -- `balanceOf(address):` Return the number of shares of the strategy that the address has. +- `asset()`: View returning underlying asset. +- `vault()`: View returning vault this strategy is plugged to. +- `totalAssets()`: View returning current amount of assets. It can include rewards valued in `asset`. +- `maxDeposit(address)`: View returning the amount max that the strategy can take safely. +- `deposit(assets, receiver)`: Deposits `assets` amount of tokens into the strategy. It can be restricted to the vault only or be open. +- `maxWithdraw(address)`: View returning how many assets can the vault take from the vault at any given point in time. +- `withdraw(assets, receiver, owner)`: Withdraws `assets` amount of tokens from the strategy. +- `balanceOf(address)`: Return the number of shares of the strategy that the address has. This means that the vault can deposit into any ERC4626 vault and that a non-compliant strategy can be implemented provided that these functions have been implemented (even in a non ERC4626 compliant way). Anything else is left to the strategy writer. However, to make security review easier, the Yearn's template has the following optional functions: -- `tend():` a function that will be called by bots. It will do anything to maintain a position, such as act on certain triggers. -- `tendTrigger():` implementation that trigger bots that will call tend function on the contract. -- `invest():` deposit funds into underlying protocol. -- `emergencyFreeFunds():` close the position and return funds to the strategy. Losses might be accepted here. +- `tend()`: a function that will be called by bots. It will do anything to maintain a position, such as act on certain triggers. +- `tendTrigger()`: implementation that trigger bots that will call tend function on the contract. +- `invest()`: deposit funds into underlying protocol. +- `emergencyFreeFunds()`: close the position and return funds to the strategy. Losses might be accepted here. ## ERC4626 compliance @@ -213,8 +213,8 @@ If the current roles stop fulfilling their responsibilities or something else ha The shutdown mode should be the last option in an emergency, as it is irreversible. ### Deposits -- **Light emergency:** Deposits can be paused by setting depositLimit to 0. -- **Shutdown mode:** Deposits are not allowed. +- **Light emergency**: Deposits can be paused by setting depositLimit to 0. +- **Shutdown mode**: Deposits are not allowed. ### Withdrawals Withdrawals can't be paused under any circumstance. From fb7673ff3bbecda4965f59ffe054ef96a06f5cd5 Mon Sep 17 00:00:00 2001 From: Dark Ghosty <38810205+DarkGhost7@users.noreply.github.com> Date: Fri, 9 Dec 2022 16:57:05 -0500 Subject: [PATCH 18/54] fix: various --- docs/getting-started/products/yvaults/v3.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/products/yvaults/v3.md b/docs/getting-started/products/yvaults/v3.md index ed87ed3590..ff86b63b40 100644 --- a/docs/getting-started/products/yvaults/v3.md +++ b/docs/getting-started/products/yvaults/v3.md @@ -118,7 +118,7 @@ Profits will be locked for a max period of PROFIT_MAX_UNLOCK_TIME seconds and wi Losses will be offset by locked profit, if possible. That makes frontrunning losses impossible (unless loss > locked profit). -Issue of new shares due to fees will also instantly unlocked profit so that price-per-share does not go down. +Issue of new shares due to fees will also instantly unlock profit so that price-per-share does not go down. Both of these offsets will prevent frontrunning (as the profit was already earned and was not distributed yet). From b1a543adb8d08d59cc7aaca947a6b2af9103611d Mon Sep 17 00:00:00 2001 From: Dark Ghosty <38810205+DarkGhost7@users.noreply.github.com> Date: Fri, 9 Dec 2022 17:21:57 -0500 Subject: [PATCH 19/54] fixes --- docs/getting-started/products/yvaults/v3.md | 40 +++++++++------------ 1 file changed, 17 insertions(+), 23 deletions(-) diff --git a/docs/getting-started/products/yvaults/v3.md b/docs/getting-started/products/yvaults/v3.md index ff86b63b40..9f85f91155 100644 --- a/docs/getting-started/products/yvaults/v3.md +++ b/docs/getting-started/products/yvaults/v3.md @@ -1,5 +1,4 @@ # Version 3 - Version 3 yVaults iterates on Version 2 by increasing robustness and developing yearn’s path towards further decentralization, while keeping the same proven product (yield-bearing tokens) that abstract builders and users from the hard work of yield farming. Version 3 will initially have the same functionality as Version 2, but the vaults are more robust and modular. Version 3 yVaults improves on Version 2 by: @@ -8,7 +7,6 @@ Version 3 yVaults improves on Version 2 by: - Adding new products like ySwaps which increases swap efficiency and yJuniorTranches which allows for different risk profiles. ## Smart Modules - Smart Modules implement core vault logic that will be iterated until they can be made immutable. If any Smart Module fails, the vault can live without them just enough to return funds to depositors. **When Version 3 launches, the Smart Modules will replicate Version 2 vault behavior.** - **Debt Allocator**: Knows the maximum debt a vault can send to a strategy. @@ -17,7 +15,6 @@ Smart Modules implement core vault logic that will be iterated until they can be - **HealthCheck**: Guardrail vault operations so that profit & loss reporting is always under acceptable values. ## Peripheral Modules - Peripheral Modules are a separate layer of optional functions for the vault and strategies. They are not required but they facilitate building around yVaults and creating new strategies. - **yRouter**: Wrapper that handles deposits and withdrawals to/from the vault. @@ -181,49 +178,47 @@ This `role_manager` can be an externally owned account, a multi-signature wallet Strategies are completely independent smart contracts that can be implemented following the proposed template or in any other way. In any case, to be compatible with the vault, they need to implement the following functions, which are a subset of ERC4626 vaults: -- `asset()`: View returning underlying asset. -- `vault()`: View returning vault this strategy is plugged to. -- `totalAssets()`: View returning current amount of assets. It can include rewards valued in `asset`. -- `maxDeposit(address)`: View returning the amount max that the strategy can take safely. +- `asset()`: View the returning underlying asset. +- `vault()`: View the returning vault this strategy is plugged into. +- `totalAssets():` View the returning amount of assets. Which can include rewards valued in `asset`. +- `maxDeposit(address)`: View the returning amount max that the strategy can take safely. - `deposit(assets, receiver)`: Deposits `assets` amount of tokens into the strategy. It can be restricted to the vault only or be open. -- `maxWithdraw(address)`: View returning how many assets can the vault take from the vault at any given point in time. +- `maxWithdraw(address)`: View how many assets can be taken from the vault at any given point in time. - `withdraw(assets, receiver, owner)`: Withdraws `assets` amount of tokens from the strategy. -- `balanceOf(address)`: Return the number of shares of the strategy that the address has. +- `balanceOf(address)`: View the number of shares of the strategy that the address has. -This means that the vault can deposit into any ERC4626 vault and that a non-compliant strategy can be implemented provided that these functions have been implemented (even in a non ERC4626 compliant way). +This means that the vault can deposit into any ERC4626 vault and that a non-compliant strategy can be implemented provided that these functions have been implemented (even if they are in a non-ERC4626 compliant way). -Anything else is left to the strategy writer. However, to make security review easier, the Yearn's template has the following optional functions: +Anything else is left to the strategy writer. However, to make security review easier, Yearn's template has the following optional functions: - `tend()`: a function that will be called by bots. It will do anything to maintain a position, such as act on certain triggers. -- `tendTrigger()`: implementation that trigger bots that will call tend function on the contract. -- `invest()`: deposit funds into underlying protocol. -- `emergencyFreeFunds()`: close the position and return funds to the strategy. Losses might be accepted here. - +- `tendTrigger()`: implementation which triggers bots that will call tend function on the contract. +- `invest()`: deposit funds into the underlying protocol. +- `emergencyFreeFunds()`: close the position and return funds to the strategy. Losses can be accepted here. ## ERC4626 compliance Vault Shares are ERC4626 compliant. -The most important implication is that `withdraw` and `redeem` functions as presented in ERC4626, the liquidity to redeem shares will be the one in the vault. No strategies will be passed to the redeem function to withdraw from with the ERC4626 compliant `withdraw` and `redeem` function. +The most important implication is that the `withdraw` and `redeem` functions as presented in ERC4626, the liquidity to redeem shares will be the one in the vault. No strategies will be passed to the redeem function to withdraw from with the ERC4626 compliant `withdraw` and `redeem` function. ## Emergency Operation ### Shutdown mode - If the current roles stop fulfilling their responsibilities or something else happens, the `EMERGENCY_MANAGER` can shut down the vault. -The shutdown mode should be the last option in an emergency, as it is irreversible. +The `Shutdown mode` is a last resort option reserved for an emergency as it is irreversible. ### Deposits -- **Light emergency**: Deposits can be paused by setting depositLimit to 0. +- **Light emergency**: Deposits can be paused by setting `depositLimit` to 0. - **Shutdown mode**: Deposits are not allowed. ### Withdrawals -Withdrawals can't be paused under any circumstance. +Withdrawals cannot be paused under any circumstance. ### Accounting Shutdown mode does not affect accounting. ### Debt rebalance -- **Light emergency**: Setting minimumTotalIdle to MAX_UINT256 will result in the vault requesting the debt back from strategies. This would stop new strategies from getting funded too, as the vault prioritizes minimumTotalIdle. +- **Light emergency**: Setting `minimumTotalIdle` to `MAX_UINT256` will result in the vault requesting the debt back from strategies. This would stop new strategies from getting funded as well as the vault prioritizes `minimumTotalIdle`. - **Shutdown mode**: All strategies' `maxDebt` is set to 0. Strategies will return funds as soon as they can. ### Relevant emergency @@ -232,13 +227,12 @@ Shutdown mode does not affect accounting. > > The shutdown mode should be the last option in an emergency, as it is irreversible. -During shutdown mode, the vault will try to get funds back from every strategy as soon as possible. +During `Shutdown mode`, the vault will try to get funds back from every strategy as soon as possible. No strategies can be added during shutdown. Any relevant role will start pointing to the `EMERGENCY_MANAGER` in case new permissioned allowed actions need to be taken. # Read more - - https://medium.com/iearn/yearnv3-motivation-and-design-107840cb4844 - https://medium.com/iearn/yearn-vaults-v3-36ce7c468ca0 \ No newline at end of file From 47fd01e5bac9ca824929c0205fe21ea0a18df19c Mon Sep 17 00:00:00 2001 From: Dark Ghosty <38810205+DarkGhost7@users.noreply.github.com> Date: Fri, 9 Dec 2022 17:25:08 -0500 Subject: [PATCH 20/54] fix: standardize heading capitialization --- docs/getting-started/products/yvaults/v3.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/getting-started/products/yvaults/v3.md b/docs/getting-started/products/yvaults/v3.md index 9f85f91155..601158181c 100644 --- a/docs/getting-started/products/yvaults/v3.md +++ b/docs/getting-started/products/yvaults/v3.md @@ -47,7 +47,7 @@ The Vault does not have a preference on any of the dimensions that should be con The compromises will come with implementing periphery contracts fulfilling the roles in the Vault. This allows different players to deploy their own version and implement their own periphery contracts (or not use any at all). -## Example periphery contracts: +## Example Periphery Contracts: - **Emergency module**: Receives deposits of Vault Shares and allows the contract to call the shutdown function after a certain % of total Vault Shares have been deposited. - **Debt Allocator**: Smart contract that incentivizes APY / debt allocation optimization by rewarding the best debt allocation (see [yStarkDebtAllocator](https://github.com/jmonteer/ystarkdebtallocator)). - **Strategy Staking Module**: Smart contract that allows players to sponsor specific strategies (so that they are added to the vault) by staking their YFI, making money if they do well and losing money if they don't. @@ -138,12 +138,12 @@ Strategy migration is the process of replacing an existing strategy with a new o ### Debt Management Callers take this responsibility with the `DEBT_MANAGER` role. -#### Setting minimum idle funds +#### Setting Minimum Idle Funds The `DEBT_MANAGER` specifies how much funds the vault should reserve to serve withdrawal requests. These funds will remain in the vault unless requested by a depositor. -#### Setting maximum debt for a specific strategy +#### Setting Maximum Debt for a Specific Strategy The maximum amount of tokens the vault will allow a strategy to owe at any moment. Stored in `strategies[strategy].max_debt`. @@ -195,14 +195,14 @@ Anything else is left to the strategy writer. However, to make security review e - `invest()`: deposit funds into the underlying protocol. - `emergencyFreeFunds()`: close the position and return funds to the strategy. Losses can be accepted here. -## ERC4626 compliance +## ERC4626 Compliance Vault Shares are ERC4626 compliant. The most important implication is that the `withdraw` and `redeem` functions as presented in ERC4626, the liquidity to redeem shares will be the one in the vault. No strategies will be passed to the redeem function to withdraw from with the ERC4626 compliant `withdraw` and `redeem` function. ## Emergency Operation -### Shutdown mode +### Shutdown Mode If the current roles stop fulfilling their responsibilities or something else happens, the `EMERGENCY_MANAGER` can shut down the vault. The `Shutdown mode` is a last resort option reserved for an emergency as it is irreversible. @@ -217,11 +217,11 @@ Withdrawals cannot be paused under any circumstance. ### Accounting Shutdown mode does not affect accounting. -### Debt rebalance +### Debt Rebalance - **Light emergency**: Setting `minimumTotalIdle` to `MAX_UINT256` will result in the vault requesting the debt back from strategies. This would stop new strategies from getting funded as well as the vault prioritizes `minimumTotalIdle`. - **Shutdown mode**: All strategies' `maxDebt` is set to 0. Strategies will return funds as soon as they can. -### Relevant emergency +### Relevant Emergency > If the current roles stop fulfilling their responsibilities or something else happens, the `EMERGENCY_MANAGER` can shut down the vault. > @@ -233,6 +233,6 @@ No strategies can be added during shutdown. Any relevant role will start pointing to the `EMERGENCY_MANAGER` in case new permissioned allowed actions need to be taken. -# Read more +# Read More - https://medium.com/iearn/yearnv3-motivation-and-design-107840cb4844 - https://medium.com/iearn/yearn-vaults-v3-36ce7c468ca0 \ No newline at end of file From f7e1bb8997c20f38895fe5c7bae1b28efb754720 Mon Sep 17 00:00:00 2001 From: MarcoWorms Date: Mon, 9 Jan 2023 10:59:59 -0300 Subject: [PATCH 21/54] fix internal link --- docs/getting-started/products/yvaults/v3.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/products/yvaults/v3.md b/docs/getting-started/products/yvaults/v3.md index 601158181c..3312575756 100644 --- a/docs/getting-started/products/yvaults/v3.md +++ b/docs/getting-started/products/yvaults/v3.md @@ -83,7 +83,7 @@ If not enough funds have been recovered to honor the full request, the transacti ### Vault Shares Vault shares are ERC20 transferable yield-bearing tokens. -They are ERC4626 compliant. Please read [ERC4626 compliance](https://hackmd.io/cOFvpyR-SxWArfthhLJb5g#ERC4626-compliance) to understand the implications. +They are ERC4626 compliant. Please read [ERC4626 compliance](#erc4626-compliance) to understand the implications. ### Accounting The vault will evaluate profit and losses from the strategies. From 0f4a4d03d076677808007228bd6ef7b44266a446 Mon Sep 17 00:00:00 2001 From: MarcoWorms Date: Mon, 9 Jan 2023 11:00:50 -0300 Subject: [PATCH 22/54] fix casing --- docs/getting-started/products/yvaults/v3.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/products/yvaults/v3.md b/docs/getting-started/products/yvaults/v3.md index 3312575756..b48cf5b268 100644 --- a/docs/getting-started/products/yvaults/v3.md +++ b/docs/getting-started/products/yvaults/v3.md @@ -172,7 +172,7 @@ Every role can be filled by an externally owned account, multi-signature wallet, The account that manages roles is a single account, set in `role_manager`. -This `role_manager` can be an externally owned account, a multi-signature wallet, or a Governance Module that relays calls. +This `role_manager` can be an externally owned account, a multi-signature wallet, or governance module that relays calls. ## Strategy Minimum API Strategies are completely independent smart contracts that can be implemented following the proposed template or in any other way. From c737eea4c5fa92cf3d7339b41b6431e5f16321c0 Mon Sep 17 00:00:00 2001 From: MarcoWorms Date: Mon, 9 Jan 2023 11:01:46 -0300 Subject: [PATCH 23/54] fix casing --- docs/getting-started/products/yvaults/v3.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/products/yvaults/v3.md b/docs/getting-started/products/yvaults/v3.md index b48cf5b268..5549110780 100644 --- a/docs/getting-started/products/yvaults/v3.md +++ b/docs/getting-started/products/yvaults/v3.md @@ -196,7 +196,7 @@ Anything else is left to the strategy writer. However, to make security review e - `emergencyFreeFunds()`: close the position and return funds to the strategy. Losses can be accepted here. ## ERC4626 Compliance -Vault Shares are ERC4626 compliant. +Vault shares are ERC4626 compliant. The most important implication is that the `withdraw` and `redeem` functions as presented in ERC4626, the liquidity to redeem shares will be the one in the vault. No strategies will be passed to the redeem function to withdraw from with the ERC4626 compliant `withdraw` and `redeem` function. From 9a61095c730293cc7432f8b0a8b525993814cfd1 Mon Sep 17 00:00:00 2001 From: MarcoWorms Date: Mon, 9 Jan 2023 11:15:35 -0300 Subject: [PATCH 24/54] improve wording --- docs/getting-started/products/yvaults/v3.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/products/yvaults/v3.md b/docs/getting-started/products/yvaults/v3.md index 5549110780..f7b936c500 100644 --- a/docs/getting-started/products/yvaults/v3.md +++ b/docs/getting-started/products/yvaults/v3.md @@ -203,7 +203,7 @@ The most important implication is that the `withdraw` and `redeem` functions as ## Emergency Operation ### Shutdown Mode -If the current roles stop fulfilling their responsibilities or something else happens, the `EMERGENCY_MANAGER` can shut down the vault. +If the current roles stop fulfilling their responsibilities or something bad or unplanned happens, the `EMERGENCY_MANAGER` can shut down the vault. The `Shutdown mode` is a last resort option reserved for an emergency as it is irreversible. From 2775f77b4e068d173409e2a5d8a5644e832c3271 Mon Sep 17 00:00:00 2001 From: MarcoWorms Date: Mon, 9 Jan 2023 11:16:35 -0300 Subject: [PATCH 25/54] improve wording --- docs/getting-started/products/yvaults/v3.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/products/yvaults/v3.md b/docs/getting-started/products/yvaults/v3.md index f7b936c500..cd83a274e6 100644 --- a/docs/getting-started/products/yvaults/v3.md +++ b/docs/getting-started/products/yvaults/v3.md @@ -190,7 +190,7 @@ In any case, to be compatible with the vault, they need to implement the followi This means that the vault can deposit into any ERC4626 vault and that a non-compliant strategy can be implemented provided that these functions have been implemented (even if they are in a non-ERC4626 compliant way). Anything else is left to the strategy writer. However, to make security review easier, Yearn's template has the following optional functions: -- `tend()`: a function that will be called by bots. It will do anything to maintain a position, such as act on certain triggers. +- `tend()`: a function that will be called by bots. It will do whatever is required to maintain a position, such as act on certain triggers. - `tendTrigger()`: implementation which triggers bots that will call tend function on the contract. - `invest()`: deposit funds into the underlying protocol. - `emergencyFreeFunds()`: close the position and return funds to the strategy. Losses can be accepted here. From 9bd08e2707d1e3021d70960a8af4d7185a478d7c Mon Sep 17 00:00:00 2001 From: Dark Ghosty <38810205+DarkGhost7@users.noreply.github.com> Date: Mon, 9 Jan 2023 17:14:03 -0500 Subject: [PATCH 26/54] fix: caps --- docs/getting-started/products/yvaults/v3.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/getting-started/products/yvaults/v3.md b/docs/getting-started/products/yvaults/v3.md index cd83a274e6..028980e49d 100644 --- a/docs/getting-started/products/yvaults/v3.md +++ b/docs/getting-started/products/yvaults/v3.md @@ -1,5 +1,5 @@ # Version 3 -Version 3 yVaults iterates on Version 2 by increasing robustness and developing yearn’s path towards further decentralization, while keeping the same proven product (yield-bearing tokens) that abstract builders and users from the hard work of yield farming. Version 3 will initially have the same functionality as Version 2, but the vaults are more robust and modular. +Version 3 yVaults iterates on Version 2 by increasing robustness and developing Yearn’s path towards further decentralization, while keeping the same proven product (yield-bearing tokens) that abstract builders and users from the hard work of yield farming. Version 3 will initially have the same functionality as Version 2, but the vaults are more robust and modular. Version 3 yVaults improves on Version 2 by: - Increasing vault modularity, allowing for smaller and safer pieces of code. @@ -235,4 +235,4 @@ Any relevant role will start pointing to the `EMERGENCY_MANAGER` in case new per # Read More - https://medium.com/iearn/yearnv3-motivation-and-design-107840cb4844 -- https://medium.com/iearn/yearn-vaults-v3-36ce7c468ca0 \ No newline at end of file +- https://medium.com/iearn/yearn-vaults-v3-36ce7c468ca0 From 37be861fc7965568a2f6541f1af2a40b8b38b22a Mon Sep 17 00:00:00 2001 From: Dark Ghosty <38810205+DarkGhost7@users.noreply.github.com> Date: Mon, 9 Jan 2023 17:30:05 -0500 Subject: [PATCH 27/54] fix: wording --- docs/getting-started/products/yvaults/v3.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/products/yvaults/v3.md b/docs/getting-started/products/yvaults/v3.md index 028980e49d..52b6ec503d 100644 --- a/docs/getting-started/products/yvaults/v3.md +++ b/docs/getting-started/products/yvaults/v3.md @@ -198,7 +198,7 @@ Anything else is left to the strategy writer. However, to make security review e ## ERC4626 Compliance Vault shares are ERC4626 compliant. -The most important implication is that the `withdraw` and `redeem` functions as presented in ERC4626, the liquidity to redeem shares will be the one in the vault. No strategies will be passed to the redeem function to withdraw from with the ERC4626 compliant `withdraw` and `redeem` function. +The most important implication is that the `withdraw` and `redeem` functions as presented in ERC4626, the liquidity to redeem shares will be the one in the vault. No strategies will be passed to the redeem function to withdraw with the `withdraw` and `redeem` function. ## Emergency Operation From 17f76c98307eaa6dfef4bac5c88f6f2e6ca5831d Mon Sep 17 00:00:00 2001 From: Dark Ghosty <38810205+DarkGhost7@users.noreply.github.com> Date: Fri, 20 Jan 2023 13:12:05 -0500 Subject: [PATCH 28/54] feat: add vault factory to sidebar --- sidebars/sidebarsGettingStarted.js | 1 + 1 file changed, 1 insertion(+) diff --git a/sidebars/sidebarsGettingStarted.js b/sidebars/sidebarsGettingStarted.js index c6575bfab8..9aad268440 100644 --- a/sidebars/sidebarsGettingStarted.js +++ b/sidebars/sidebarsGettingStarted.js @@ -14,6 +14,7 @@ module.exports = { 'products/yvaults/vaults-and-strategies', 'products/yvaults/vault-tokens', 'products/yvaults/v3', + 'products/yvaults/vault-factory', ], }, { From bcbc0d526b1ba1cb31434a2f4da84be4f2cd82c7 Mon Sep 17 00:00:00 2001 From: Dark Ghosty <38810205+DarkGhost7@users.noreply.github.com> Date: Fri, 20 Jan 2023 14:01:56 -0500 Subject: [PATCH 29/54] fix: reorder sidebar --- sidebars/sidebarsGettingStarted.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sidebars/sidebarsGettingStarted.js b/sidebars/sidebarsGettingStarted.js index 25871d53f8..6beb9bd772 100644 --- a/sidebars/sidebarsGettingStarted.js +++ b/sidebars/sidebarsGettingStarted.js @@ -13,8 +13,8 @@ module.exports = { 'products/yvaults/overview', 'products/yvaults/vaults-and-strategies', 'products/yvaults/vault-tokens', - 'products/yvaults/v3', 'products/yvaults/vault-factory', + 'products/yvaults/v3', ], }, { From 92afc12d58be9970b26dfc8674b0abfbc873113b Mon Sep 17 00:00:00 2001 From: Schlagonia Date: Wed, 28 Jun 2023 10:40:45 -0600 Subject: [PATCH 30/54] feat: update v3 docs --- docs/getting-started/products/yvaults/v3.md | 556 +++++++++++++++----- 1 file changed, 427 insertions(+), 129 deletions(-) diff --git a/docs/getting-started/products/yvaults/v3.md b/docs/getting-started/products/yvaults/v3.md index 52b6ec503d..b0e622aeac 100644 --- a/docs/getting-started/products/yvaults/v3.md +++ b/docs/getting-started/products/yvaults/v3.md @@ -1,26 +1,34 @@ # Version 3 -Version 3 yVaults iterates on Version 2 by increasing robustness and developing Yearn’s path towards further decentralization, while keeping the same proven product (yield-bearing tokens) that abstract builders and users from the hard work of yield farming. Version 3 will initially have the same functionality as Version 2, but the vaults are more robust and modular. +Version 3 yVaults iterates on Version 2 by increasing robustness and developing Yearn’s path towards further decentralization, while keeping the same proven product (yield-bearing tokens) that abstract builders and users from the hard work of yield farming. Version 3 will both be able to have the same functionality as Version 2, but with many more added benefits and improvements to continue to grow the Yearn ecosystem. + +V3 also sees the introduction of "Tokenized Strategies". In V3 the strategies are now capable of being standalone 4626 vaults themselves. These single strategy vaults can be used as stand alone vaults or due to the 4626 standard easily added as a strategy to any of the multi strategy "Meta Vaults". Version 3 yVaults improves on Version 2 by: - Increasing vault modularity, allowing for smaller and safer pieces of code. - Simplify strategy creation, empowering strategists and reducing the chance for errors. +- More strategy functionality by implementing the Tokenized Strategy. +- All ERC-4626 implementations for easy integrations. +- Decreased gas costs to report profits and update debts. - Adding new products like ySwaps which increases swap efficiency and yJuniorTranches which allows for different risk profiles. ## Smart Modules Smart Modules implement core vault logic that will be iterated until they can be made immutable. If any Smart Module fails, the vault can live without them just enough to return funds to depositors. **When Version 3 launches, the Smart Modules will replicate Version 2 vault behavior.** -- **Debt Allocator**: Knows the maximum debt a vault can send to a strategy. -- **Strategy Registry**: Handles adding and removing strategies of a vault. It can also include strategy metadata. -- **Fee Manager**: Handles changing fees for vault operations. -- **HealthCheck**: Guardrail vault operations so that profit & loss reporting is always under acceptable values. +- **Debt Allocator**: Can efficiently allocate debt to different strategies added to a meta vault to the best yield opportunities. +- **Accountant**: Handles changing fees for vault operations. -## Peripheral Modules -Peripheral Modules are a separate layer of optional functions for the vault and strategies. They are not required but they facilitate building around yVaults and creating new strategies. -- **yRouter**: Wrapper that handles deposits and withdrawals to/from the vault. +## Periphery Contracts +Periphery contracts are a separate layer of optional contracts to use with vaults and strategies. They are not required but they facilitate building around yVaults. + +- **Router**: Wrapper that handles deposits and withdrawals to/from all vaults and strategies. - **Yearn Lens**: Information aggregator for off-chain apps. - **APY TWAP Oracle**: Reliable source of Yearn vaults’ past performance. -- **ySwaps**: Internal swap system currently being developed. Reduces slippage thus improving net APY. +- **ySwaps**: Internal swap system. Reduces slippage thus improving net APY. +- **Registry**: Handles adding and tracking strategies and vaults. +- **HealthCheck**: Guardrail vault operations so that profit & loss reporting is always under acceptable values. +- **Swappers**: Pre-built contracts for strategies to inherit to easily implement their desired swap logic. +- **APR Oracles**: Retrieve the expected current APY on chain for different strategies to properly allocate debt. - And any others you can come up with! # Version 3 yVault Specification @@ -33,205 +41,495 @@ Peripheral Modules are a separate layer of optional functions for the vault and - **Vault**: ERC4626 compliant smart contract that receives Assets from Depositors to distribute amongst the different Strategies added to the vault: manages accounting and Assets distribution. - **Role**: Flags that an Account can do specific Vault actions. Can be fulfilled by a smart contract or an externally owned account. - **Accountant**: Smart contract that receives P&L reporting and returns shares and refunds to the strategy +# Yearn System Specification -# Vault Version 3 Specification -The Vault code has been designed as an unopinionated system to distribute depositors' funds into different opportunities (aka Strategies) and robustly manage accounting. +## V3 "Meta" Vault Specification -The depositors receive shares of the different investments that can then be redeemed or used as yield-bearing tokens. +### Definitions +- Asset: Any ERC20-compliant token +- Shares: ERC20-compliant token that tracks Asset balance in the vault for every distributor. Named yv +- Depositor: Account that holds Shares +- Strategy: Smart contract that is used to deposit in Protocols to generate yield +- Vault: ERC4626 compliant Smart contract that receives Assets from Depositors to then distribute them among the different Strategies added to the vault, managing accounting and Assets distribution. +- Role: the different flags an Account can have in the Vault so that the Account can do certain specific actions. Can be fulfilled by a smart contract or an EOA. +- Accountant: smart contract that receives P&L reporting and returns shares and refunds to the strategy -The Vault does not have a preference on any of the dimensions that should be considered when operating a vault: -- **Decentralization**: Roles can be filled by common wallets, smart contracts like multi-signatures or governance modules. -- **Liquidity**: Vault can have 0 liquidity or be fully liquid. It will depend on the parameters and strategies added. -- **Security**: Vault managers can choose what strategies to add and how to do that process. -- **Automation**: All the required actions to maintain the vault can be called manually or by bots, depending on periphery implementation. - -The compromises will come with implementing periphery contracts fulfilling the roles in the Vault. This allows different players to deploy their own version and implement their own periphery contracts (or not use any at all). +The Vault code has been designed as an non-opinionated system to distribute funds of depositors into different opportunities (aka Strategies) and manage accounting in a robust way. That's all. -## Example Periphery Contracts: -- **Emergency module**: Receives deposits of Vault Shares and allows the contract to call the shutdown function after a certain % of total Vault Shares have been deposited. -- **Debt Allocator**: Smart contract that incentivizes APY / debt allocation optimization by rewarding the best debt allocation (see [yStarkDebtAllocator](https://github.com/jmonteer/ystarkdebtallocator)). -- **Strategy Staking Module**: Smart contract that allows players to sponsor specific strategies (so that they are added to the vault) by staking their YFI, making money if they do well and losing money if they don't. +Depositors receive shares (aka vaults tokens) proportional to their deposit amount. Vault tokens are yield-bearing and can be redeemed at any time to get back deposit plus any yield generated. -## Deployment +The Vault does not have a preference on any of the dimensions that should be considered when operating a vault: +- *Decentralization*: Roles can be filled by any address (e.g. EOA, smart contract, multi-sig). +- *Liquidity*: Vault can have 0 liquidity or be fully liquid. It will depend on parameters and strategies added. +- *Security*: Vault managers can choose what strategies to add and how to do that process. +- *Automation*: All the required actions to maintain the vault can be called by bots or manually, depending on periphery implementation. + +The compromises will come with the implementation of periphery contracts fulfilling the roles in the Vault. + +This allows different players to deploy their own version and implement their own periphery contracts (or not use any at all) + +``` +Example periphery contracts: +- Emergency module: it receives deposits of Vault Shares and allows the contract to call the shutdown function after a certain % of total Vault Shares have been deposited +- Debt Allocator: a smart contract that incentivises APY / debt allocation optimisation by rewarding the best debt allocation (see [yStarkDebtAllocator](https://github.com/jmonteer/ystarkdebtallocator)) +- Strategy Staking Module: a smart contract that allows players to sponsor specific strategies (so that they are added to the vault) by staking their YFI, making money if they do well and losing money if they don't +- ... +``` +### Deployment We expect all the vaults available to be deployed from a Factory Contract, publicly available and callable. -Players deploying "branded" vaults (e.g. Yearn) will use a separate registry to allow permissioned endorsement of vaults for their product. +Players deploying "branded" vaults (e.g. Yearn) will use a separate registry to allow permissioned endorsement of vaults for their product When deploying a new vault, it requires the following parameters: -- **asset**: Address of the ERC20 token that can be deposited in the vault. -- **name**: Name of Shares as described in the ERC20. -- **symbol**: Symbol of Shares in the ERC20. -- **role_manager**: Account that can assign and revoke Roles. -- **PROFIT_MAX_UNLOCK_TIME**: Max amount of time profit will be distributed over. +- asset: address of the ERC20 token that can be deposited in the vault +- name: name of Shares as described in ERC20 +- symbol: symbol of Shares ERC20 +- role_manager: account that can assign and revoke Roles +- profit_max_unlock_time: max amount of time profit will be locked before being distributed -## Normal Operation +### Normal Operation -### Deposits / Mints +#### Deposits / Mints Users can deposit ASSET tokens to receive yvTokens (SHARES). -Deposits are limited under `depositLimit` and shutdown parameters. Read below for details. - -### Withdrawals / Redeems -Users can redeem their shares at any time if there is liquidity available. +Deposits are limited under depositLimit and shutdown parameters. Read below for details. -The redeem function will check if there are enough idle funds to serve the request. If there are not enough, it will revert. +#### Withdrawals / Redeems +Users can redeem their shares at any point in time if there is liquidity available. Optionally, a user can specify a list of strategies to withdraw from. If a list of strategies is passed, the vault will try to withdraw from them. +If a user passed array is not defined, the redeem function will use the default_queue. + If not enough funds have been recovered to honor the full request, the transaction will revert. -### Vault Shares +#### Vault Shares Vault shares are ERC20 transferable yield-bearing tokens. -They are ERC4626 compliant. Please read [ERC4626 compliance](#erc4626-compliance) to understand the implications. +They are ERC4626 compliant. Please read [ERC4626 compliance](https://hackmd.io/cOFvpyR-SxWArfthhLJb5g#ERC4626-compliance) to understand the implications. -### Accounting +#### Accounting The vault will evaluate profit and losses from the strategies. -This is done by comparing the current debt of the strategy with the total assets the strategy is reporting to have. - -- If `totalAssets < currentDebt`: the vault will record a loss -- If `totalAssets > currentDebt`: the vault will record a profit +This is done comparing the current debt of the strategy with the total assets the strategy is reporting to have. -Both loss and profit will impact the strategy's debt, increasing the debt (current debt + profit) if there are profits, and decreasing its debt (current debt - loss) if there are losses. +If totalAssets < currentDebt: the vault will record a loss +If totalAssets > currentDebt: the vault will record a profit -#### Fees -The Accountant module handles fee assessment and distribution. It will report the fees that need to be charged, and the vault will issue shares for that amount of fees. +Both loss and profit will impact strategy's debt, increasing the debt (current debt + profit) if there are profits, decreasing its debt (current debt - loss) if there are losses. -#### Refunds -Refunds are positive inflows and are sent to the vault to reward it or compensate the vault in any way. The Accountant module will take care of them. +##### Fees +Fee assessment and distribution are handled by the Accountant module. -An example is an insurance mechanism like different risk tranches where the Accountant will send assets to the vault to compensate for losses (and, in exchange, take higher fees). +It will report the amount of fees that need to be charged and the vault will issue shares for that amount of fees. -The refunds are paid in the form of vault shares and will be instantly locked (and released gradually). +There is also an optional protocol_fee that can be charged based on the configuration of the VaultFactory.vy -### Profit Distribution +#### Profit distribution Profit from different process_report calls will accumulate in a buffer. This buffer will be linearly unlocked over the locking period seconds at profit_distribution_rate. -Profits will be locked for a max period of PROFIT_MAX_UNLOCK_TIME seconds and will be gradually distributed. To avoid spending too much gas for profit unlock, the period that profit will be locked for is a weighted average between the new profit and the previous profit. +Profits will be locked for a max period of time of profit_max_unlock_time seconds and will be gradually distributed. To avoid spending too much gas for profit unlock, the amount of time a profit will be locked is a weighted average between the new profit and the previous profit. + +new_locking_period = locked_profit * pending_time_to_unlock + new_profit * PROFIT_MAX_UNLOCK_TIME / (locked_profit + new_profit) +new_profit_distribution_rate = (locked_profit + new_profit) / new_locking_period + +Losses will be offset by locked profit, if possible. -- `new_locking_period = locked_profit * pending_time_to_unlock + new_profit * PROFIT_MAX_UNLOCK_TIME / (locked_profit + new_profit)` -- `new_profit_distribution_rate = (locked_profit + new_profit) / new_locking_period` +Issue of new shares due to fees will also unlock profit so that PPS does not go down. -Losses will be offset by locked profit, if possible. That makes frontrunning losses impossible (unless loss > locked profit). +Both of this offsets will prevent front running (as the profit was already earned and was not distributed yet) -Issue of new shares due to fees will also instantly unlock profit so that price-per-share does not go down. +### Vault Management +Vault management is split into function specific roles. Each permissioned function has its own corresponding Role. -Both of these offsets will prevent frontrunning (as the profit was already earned and was not distributed yet). +This means roles can be combined all to one address, each distributed to separate addresses or any combination in between -Instead of locking the profit, and to be more capital efficient (and avoid complex asset management), the vault issues shares that holds itself. Those shares are gradually burned over time (increasing price-per-share). So instead of releasing assets, the vault will gradually burn shares. +### Roles +Vault functions that are permissioned will be callable by accounts that hold specific roles. + +These are: +- ADD_STRATEGY_MANAGER: role than can add strategies to the vault +- REVOKE_STRATEGY_MANAGER: role that can remove strategies from the vault +- FORCE_REVOKE_MANAGER: role that can force remove a strategy causing a loss +- ACCOUNTANT_MANAGER: role that can set the accountant that assesses fees +- QUEUE_MANAGER: role that can set the default_queue +- REPORTING_MANAGER: role that calls report for strategies +- DEBT_MANAGER: role that adds and removes debt from strategies +- MAX_DEBT_MANAGER: role that can set the max debt for a strategy +- DEPOSIT_LIMIT_MANAGER: role that sets deposit limit for the vault +- MINIMUM_IDLE_MANAGER: role that sets the minimum total idle the vault should keep +- PROFIT_UNLOCK_MANAGER: role that sets the profit_max_unlock_time +- DEBT_PURCHASER # can purchase bad debt from the vault +- EMERGENCY_MANAGER: role that can shutdown vault in an emergency + +Every role can be filled by an EOA, multi-sig or other smart contracts. Each role can be filled by several accounts. + +The account that manages roles is a single account, set in `role_manager`. -## Vault Management -Vault management is split into two fields: strategy management and debt management. +This role_manager can be an EOA, a multi-sig or a Governance Module that relays calls. -### Strategy Management -Callers take this responsibility with the `STRATEGY_MANAGER` role. +#### Strategy Management +This responsibility is taken by callers with ADD_STRATEGY_MANAGER, REVOKE_STRATEGY_MANAGER and FORCE_REVOKE_MANAGER roles -A vault can have strategies added, removed, and migrated. +A vault can have strategies added, removed or forcefully removed -Added strategies will be eligible to receive funds from the vault when `max_debt` is set to > 0. +Added strategies will be eligible to receive funds from the vault, when the max_debt is set to > 0 -Revoked strategies will return all debt and be ineligible to receive more. This happens when the strategy's `current_debt` is 0. +Revoked strategies will return all debt and stop being eligible to receive more. It can only be done when the strategy's current_debt is 0 -Strategy migration is the process of replacing an existing strategy with a new one, which will inherit all of the old strategy's parameters, including its debt. +Force revoking a strategy is only used in cases of a faulty strategy that cannot otherwise have its current_debt reduced to 0. Force revoking a strategy will result in a loss being reported by the vault. -### Debt Management -Callers take this responsibility with the `DEBT_MANAGER` role. +##### Setting the periphery contracts +The accountant can each be set by the ACCOUNTANT_MANAGER. -#### Setting Minimum Idle Funds -The `DEBT_MANAGER` specifies how much funds the vault should reserve to serve withdrawal requests. +The contract is not needed for the vault to function but are recommended for optimal use. -These funds will remain in the vault unless requested by a depositor. +##### Reporting profits +The REPORTING_MANAGER is in charge of calling process_report() for each strategy in the vault according to its own timeline -#### Setting Maximum Debt for a Specific Strategy -The maximum amount of tokens the vault will allow a strategy to owe at any moment. +This call will do the necessary accounting and profit locking for the individual strategy as well as charging fees -Stored in `strategies[strategy].max_debt`. +#### Debt Management +This responsibility is taken by callers with DEBT_MANAGER role -When a debt rebalance is triggered, the Vault will cap the new target debt to this number `max_debt`. +This role can increase or decrease strategies specific debt. -#### Rebalance Debt -The vault sends and receives funds to/from strategies. The function `updateDebt(strategy, target_debt)` will set the `current_debt` of the strategy to the `target_debt`, if possible. +The vault sends and receives funds to/from strategies. The function updateDebt(strategy, target_debt) will set the current_debt of the strategy to target_debt (if possible) -If the strategy currently has less debt than the `target_debt`, the vault will send funds to it. +If the strategy currently has less debt than the target_debt, the vault will send funds to it. The vault checks that the `minimumTotalIdle` parameter is respected (i.e. there's at least a certain amount of funds in the vault). -The vault will request back funds if the strategy has more debt than `max_debt`. These funds may be locked in the strategy, which would result in the strategy returning fewer funds than requested by the vault. +If the strategy has more debt than the max_debt, the vault will request the funds back. These funds may be locked in the strategy, which will result in the strategy returning less funds than requested by the vault. -## Roles -Vault functions that are permissioned will be callable by accounts with specific roles. +#### Setting maximum debt for a specific strategy +The MAX_DEBT_MANAGER can set the maximum amount of tokens the vault will allow a strategy to owe at any moment in time. -These roles are: -- `STRATEGY_MANAGER`: role for accounts that can add, remove, or migrate strategies. -- `DEBT_MANAGER`: role for accounts that can rebalance and manage debt-related parameters. -- `EMERGENCY_MANAGER`: role for accounts that can activate the shutdown mode. -- `ACCOUNTING_MANAGER`: role for accounts that can process reports (save strategy p&l) and change accountant parameters. +Stored in strategies[strategy].max_debt -Every role can be filled by an externally owned account, multi-signature wallet, or other smart contracts. Each role can be filled by several accounts. +When a debt re-balance is triggered, the Vault will cap the new target debt to this number (max_debt) -The account that manages roles is a single account, set in `role_manager`. +#### Setting the deposit limit +The DEPOSIT_LIMIT_MANAGER is in charge of setting the deposit_limit for the vault + +On deployment deposit_limit defaults to 0 and will need to be increased to make the vault functional + +#### Setting minimum idle funds +The MINIMUM_IDLE_MANAGER can specify how many funds the vault should try to have reserved to serve withdrawal requests + +These funds will remain in the vault unless requested by a Depositor + +It is recommended that if no queue_manager is set some amount of funds should remain idle to service withdrawals + +#### Setting the profit unlock period +The PROFIT_UNLOCK_MANAGER is in charge of updating and setting the profit_max_unlock_time which controls how fast profits will unlock + +This can be customized based on the vault based on aspects such as number of strategies, TVL, expected returns etc. + +### Setting the default queue +The QUEUE_MANAGER has the option to set a custom default_queue if desired. The vault will arrange the default queue automatically based only on the order that strategies were added to the vault. If a different order is desired the queue manager role can set a custom queue. -This `role_manager` can be an externally owned account, a multi-signature wallet, or governance module that relays calls. +All strategies in the default queue must have been previously added to the vault. -## Strategy Minimum API +#### Buying Debt +The DEBT_PURCHASER role can buy debt from the vault in return for the equal amount of `asset`. + +This should only ever be used in the case where governance wants to purchase a set amount of bade debt from the vault in order to not report a loss. + +It still relies on convertToShares() so will only be viable if the conversion does not reflect and large negative realized loss from the strategy. + + +#### Shutting down the vault +In an emergency the EMERGENCY_MANAGER can shutdown the vault + +This will also give the EMERGENCY_MANAGER the DEBT_MANAGER roles as well so funds can start to be returned from the strategies + +### Strategy Minimum API Strategies are completely independent smart contracts that can be implemented following the proposed template or in any other way. In any case, to be compatible with the vault, they need to implement the following functions, which are a subset of ERC4626 vaults: -- `asset()`: View the returning underlying asset. -- `vault()`: View the returning vault this strategy is plugged into. -- `totalAssets():` View the returning amount of assets. Which can include rewards valued in `asset`. -- `maxDeposit(address)`: View the returning amount max that the strategy can take safely. -- `deposit(assets, receiver)`: Deposits `assets` amount of tokens into the strategy. It can be restricted to the vault only or be open. -- `maxWithdraw(address)`: View how many assets can be taken from the vault at any given point in time. -- `withdraw(assets, receiver, owner)`: Withdraws `assets` amount of tokens from the strategy. -- `balanceOf(address)`: View the number of shares of the strategy that the address has. +- asset(): view returning underlying asset +- vault(): view returning vault this strategy is plugged to +- totalAssets(): view returning current amount of assets. It can include rewards valued in `asset` ¡ +- maxDeposit(address): view returning the amount max that the strategy can take safely +- deposit(assets, receiver): deposits `assets` amount of tokens into the strategy. it can be restricted to vault only or be open +- maxWithdraw(address): view returning how many asset can the vault take from the vault at any given point in time +- withdraw(assets, receiver, owner): withdraws `assets` amount of tokens from the strategy +- balanceOf(address): return the number of shares of the strategy that the address has + +This means that the vault can deposit into any ERC4626 vault but also that a non-compliant strategy can be implemented provided that these functions have been implemented (even in a non ERC4626 compliant way). + +### ERC4626 compliance +Vault Shares are ERC4626 compliant. + +The most important implication is that `withdraw` and `redeem` functions as presented in ERC4626, if no queue_manager is set the liquidity to redeem shares will just be the one in the vault. No strategies will be passed to the redeem function to withdraw from with the ERC4626 compliant `withdraw` and `redeem` function. + +### Emergency Operation + +#### Shutdown mode +In the case the current roles stop fulfilling their responsibilities or something else happens, the EMERGENCY_MANAGER can shutdown the vault. + +The shutdown mode should be the last option in an emergency as it is irreversible. + +#### Deposits +_Light emergency_: Deposits can be paused by setting depositLimit to 0 + +_Shutdown mode_: Deposits are not allowed + +#### Withdrawals +Withdrawals can't be paused under any circumstance + +#### Accounting +Shutdown mode does not affect accounting + +#### Debt rebalance +_Light emergency_: Setting minimumTotalIdle to MAX_UINT256 will result in the vault requesting the debt back from strategies. This would stop new strategies from getting funded too, as the vault prioritizes minimumTotalIdle + +_Shutdown mode_: All strategies maxDebt is set to 0. Strategies will return funds as soon as they can. + +#### Relevant emergency +In the case the current roles stop fulfilling their responsibilities or something else happens, the EMERGENCY_MANAGER can shutdown the vault. + +The shutdown mode should be the last option in an emergency as it is irreversible. + +During shutdown mode, the vault will try to get funds back from every strategy as soon as possible. + +No strategies can be added during shutdown + +Any relevant role will start pointing to the EMERGENCY_MANAGER in case new permissioned allowed actions need to be taken. + + +## V3 Tokenized Strategy Specification + +### Overview +The Yearn V3 "Tokenized Strategy" goal is to make it as easy as possible for any person or protocol to create and deploy their own ERC-4626 compliant single strategy vault. It uses an immutable proxy pattern to outsource all of the standardized 4626 and other vault logic to one implementation contract that all Strategies deployed on a specific chain use through delegatecall. This makes the strategy specific contract as simple and specific to that yield generating task as possible and allows for anyone to simply plug their version into a permissionless, secure and optimized 4626 compliant base that handles all risky and complicated code. + + +### Definitions +- Asset: Any ERC20-compliant token +- Shares: ERC20-compliant token that tracks Asset balance in the strategy for every distributor. +- Strategy: ERC4626 compliant smart contract that receives Assets from Depositors (vault or otherwise) to deposit in any external protocol to generate yield. +- Tokenized Strategy: The implementation contract that all strategies delegateCall to for the standard ERC4626 and profit locking functions. +- BaseTokenizedStrategy: The abstract contract that a strategy should inherit from that handles all communication with the Tokenized Strategy contract. +- Strategist: The developer of a specific strategy. +- Depositor: Account that holds Shares +- Vault: ERC4626 compliant Smart contract that receives Assets from Depositors to then distribute them among the different Strategies added to the vault, managing accounting and Assets distribution. +- Management: The owner of the specific strategy that can set fees, profit unlocking time etc. +- Keeper: the address of a contract allowed to call report() and tend() on a strategy. +- Factory: The factory that all vaults of a specific API version are cloned from that also controls the protocol fee amount and recipient. + +### Storage +In order to standardize all high risk and complex logic associated with ERC4626, ERC20 and profit locking, all core logic has been moved to the 'TokenizedStrategy.sol' and is used by each strategy through a fallback function that delegatecall's this contract to do all necessary checks, logic and storage updates for the strategy. + +The TokenizedStrategy will only need to be deployed once on each chain and can then be used by an unlimited number of strategies. Allowing the BaseTokenizedStrategy.sol to be much smaller, simpler and cheaper to deploy. + +Using delegate call the external TokenizedStrategyy will be able read and write to any and all of the strategies specific storage variables during all calls. This does open the strategy up to the possibility of storage collisions due to non-standardized storage calls and means extra precautions need to be taken when reading and writing to storage. + +In order to limit the strategists need to think about their storage variables all TokenizedStrategy specific variables are held within and controlled by the TokenizedStrategy. A `StrategyData` struct is held at a custom storage location that is high enough that no normal implementation should be worried about hitting. + +This means all high risk storage updates will always be handled by the TokenizedStrategy, should not be able to be overridden by a reckless strategist and will be entirely standardized across every strategy deployed, no matter the chain or specific implementation. + +### BaseTokenizedStrategy + +The base tokenized strategy is a simple abstract contract to be inherited by the strategist that handles all communication with the TokenizedStrategy. + +#### Modifiers +`onlySelf`: This modifier is placed on any callback functions for the TokenizedStrategy to call during deposits, withdraws, reports and tends. The modifier should revert if msg.sender is not equal to itself. In order for a call to be forwarded to the TokenizedStrategy it must not be defined in the Strategy and hit the fallback function which will delegatecall the TokenizedStrategy. If within that call, the TokenizedStrategy makes an external static call back to the BaseTokenizedStrategy the msg.sender of that call will be the original caller, which should be the Strategy itself. + +`OnlyManagement`: Should be placed on function that only the Strategies specific management address can call. This uses the isManagement(address) function defined in TokenizedStrategy by sending the original msg.sender address. + +`onlyKeepers`: Should be placed on functions that only the Strategies specific management or keeper can call. This uses the isManagementOrKeeper(address) defined in TokenizedStrategy sending the original msg.sender address. + +#### Variables + +`tokenizedStrategyAddress`: This is the address the fallback function will use to delegatecall to and is set before deployment to a constant so it can never be changed. + +`TokenizedStrategy`: This is an immutable set on deployment setting an ITokenizedStrategy interface to address(this). The variable should be used in a similar manner as a linked library would be to have a simple method to read from the Strategies storage internally. Setting it to address(this) means anything using this variable will static call itself which should hit the fallback and then delegatecall the TokenizedStrategy retrieving the correct variables. + +`asset`: The immutable address of the underlying asset being used. + +#### Functions + +The majority of function in the BaseTokenizedStrategy are either external functions with onlySelf modifiers used for the TokenizedStrategy to call. Or the internal functions that correspond to those external functions that should or can be overridden by a strategist with the strategy specific logic. + +`deployFunds(uint256)/_DeployFunds(uint256)`: Called by the TokenizedStrategy during deposits into the strategy to tell the strategy it can deposit up to the amount passed in as a parameter if desired. + +`freeFunds(uint256)/_freeFunds(uint256)`: Called by the TokenizedStrategy during withdraws to get the amount of the uint256 parameter freed up in order to process the withdraw. + +`harvestAndReport()/_harvestAndReport()`: Called during reports to tell the strategy a trusted address has called it and to harvest any rewards re-deploy any loose funds and return the actual amount of funds the strategy holds. + +`tendThis(uint256)/_tend(uint256)`: Called by the TokenizedStrategy during tend calls to tell the strategy a trusted address has called tend and it has the uint256 parameter of loose asset available to deposit. NOTE: we use `tendThis` to avoid function signature collisions so that `tend` will be forwarded to the TokenizedStrategy. + +`tendTrigger()`: View function to return if a tend call is needed. + +`availableDepositLimt(address)/availableWithdrawLimit(address)`: Optional functions a strategist can override that default to uint256 max to implement any deposit or withdraw limits. + +`shutdownWithdraw(uint256)/_emergencyWithdraw(uint256)`: Optional function for a strategist to implement that will allow management to manually withdraw a specified amount from the yield source if a strategy is shutdown in the case of emergencies. + +`init(...)`: Used only once during initialization to manually delegatecall the TokenizedStrategy to tell it to set up the storage for a new strategy. + +### TokenizedStrategy + +The tokenized strategy contract should implement all ERC-4626, ERC-20, ERC-2612 and custom TokenizedStrategy specific report and tending logic within it. + +For deposits, withdraws, report, tend and emergency withdraw calls it casts address(this) into a custom IBaseTokenizedStrategy() interface to static call back the initial calling contract when it needs to interact with the Strategy. + +#### Normal Operation + The TokenizedStrategy is responsible for handling the logic associated with all the following functionality. + +##### Deposits / Mints +Users can deposit ASSET tokens to receive shares. + +Deposits are limited by the maxAvailableDeposit function that can be changed by the strategist if non uint256.max values are desired. + +##### Withdrawals / Redeems +Users can redeem their shares at any point in time if there is liquidity available. + +The amount of a withdraw or redeem can be limited by the strategist by overriding the maxAvailableWithdraw function. + +If not enough funds have been recovered to honor the full request, the strategy will pass on the difference to the user as a loss. + +##### Strategy Shares +The strategy issues shares to each depositor to track their relative share of assets. Shares are ERC20 transferable yield-bearing tokens. + +They are ERC4626 compliant. Please read [ERC4626 compliance](https://hackmd.io/cOFvpyR-SxWArfthhLJb5g#ERC4626-compliance) to understand the implications. + +##### Accounting +The strategy will evaluate profit and losses from the yield generating activities. + +This is done comparing the current totalAssets of the strategy with the amount returned from _harvestAndReport() + +If totalAssets < newTotalAssets: the vault will record a loss +If totalAssets > newTotalAssets: the vault will record a profit + +Both loss and profit will impact strategy's totalAssets, increasing if there are profits, decreasing if there are losses. + +##### Fees +Fee assessment and distribution is handled during each `report` call after profits or losses are recorded. + +It will report the amount of fees that need to be charged and the strategy will issue shares for that amount of fees. + +There are two potential fees. Performance fees and protocol fees. Performance fees are configurable by management of the strategy and payed based on the reported profit during each report with a max of 50%. + +Protocol fees are configured by Yearn governance through the Factory and are taken as a percent of the performanceFees charged. I.E. profit = 100, performance fees = 20% protocol fees = 10%. Then total fees charged = 100 * .2 = 20 of which 10% is sent to the protocol fee recipient (2) and 90% (18) is sent the strategy specific `performanceFeeRecipient`. + +#### Profit distribution +Profit from report calls will accumulate in a buffer. This buffer will be linearly unlocked over the locking period seconds at profitUnlockingRate. + +Profits will be locked for a max period of time of profitMaxUnlockTime seconds and will be gradually distributed. To avoid spending too much gas for profit unlock, the amount of time a profit will be locked is a weighted average between the new profit and the previous profit. + +new_locking_period = current_locked_profit * pending_time_to_unlock + new_profit * PROFIT_MAX_UNLOCK_TIME / (current_locked_profit + new_profit) +new_profit_unlocking_rate = (locked_profit + new_profit) / new_locking_period + +Losses will be offset by locked profit, if possible. + +Issue of new shares due to fees will also unlock profit so that PPS does not go down. + +Both of this offsets will prevent front running (as the profit was already earned and was not distributed yet) + +#### Strategy Management +Strategy management is held by the 'management' address that can be updated at any time by the current 'managment' + +Management has the ability to set all the configurable variables for their specific Strategy. + +The base strategy has purposely been written to limit the actual control management has over any important functionality. Meaning they are not capable of stealing any funds from the strategy or otherwise tampering with deposited funds, unless purposefully written in within their specific Strategy. + +The configurable variables within managements control are: + +##### Setting Management +This allows the current management to set a new non-zero address as the management of the strategy. + +##### Setting the keeper +Setting the address that is also allowed to call report and tend functions. + +##### Setting Performance Fee +Setting the percent in terms of Basis points for the amount of profit to be charged as a fee. + +The max this can be 99.99%. + +##### Setting performance fee recipient +Setting the non-zero address that will receive any shares issued as a result of the performance fee. + +##### Setting the profit unlock period +Sets the time in seconds that controls how fast profits will unlock. + +This can be customized based on the strategy. Based on aspects such as TVL, expected returns etc. + +### ERC4626 compliance +Strategy Shares are ERC4626 compliant. + +### Emergency Operation +There is default emergency functions built in. First of which is `shutdownStrategy`. This can only ever be called by the management address and is non-reversible. + +Once this is called it will stop any further deposit or mints but will have no effect on any other functionality including withdraw, redeem, report and tend. This is to all the management to continue potentially recording profits or losses and users to withdraw even post shutdown. + +This can be used in an emergency or simply to retire a vault. + +Once a strategy is shutdown management can also call `emergencyWithdraw(amount)`. Which will tell the strategy to withdraw a specified `amount` from the yield source and keep it as idle in the vault. This function will also do any needed updates to totalDebt and totalIdle, based on amounts withdrawn to assure withdraws continue to function properly. + +All other emergency functionality is left up to the individual strategist. + +#### Withdrawals +Withdrawals can't be paused under any circumstance unless built in a specific implementation. + + +### Use +A strategist can simply inherit the BaseTokenizedStrategy.sol contract and override 3 simple functions with their specific needs. + +The strategies code has been designed as a non-opinionated system to distribute funds of depositors to a single yield generating opportunity while managing accounting in a robust way. + +The depositors receive shares of the strategy representing their relative share that can then be redeemed or used as yield-bearing tokens. + +The Strategy does not have a preference on any of the dimensions that should be considered when operating a strategy: +- *Decentralization*: management and keeper roles can be handled by EOA's, multi-sigs or any other form of governance. +- *Permissionlessness*: The strategies default to be fully permissioned. However, any strategist can easily implement white lists or any other method they desire. +- *Liquidity*: The strategy can be fully liquid at any time or only allow withdraws of idle funds, depending on the strategy implementation. +- *Risk*: Strategy developers can deploy funds into any opportunity they desire no matter the expected risks or returns. +- *Automation*: all the required actions to maintain the vault can be called by bots or manually, depending on periphery implementation + +The compromises will come with the specific yield generating opportunity and parameters used by the strategies management. + +This allows different players to deploy their own version and implement their own constraints (or not use any at all) + -This means that the vault can deposit into any ERC4626 vault and that a non-compliant strategy can be implemented provided that these functions have been implemented (even if they are in a non-ERC4626 compliant way). +Example constraints: +- Illiquid Strategy: A strategy must join AMM pools, which can be sandwiched by permissionless deposits/withdraws. So it only deposits during reports or tend calls from a trusted relay and limits withdraws to the amount of asset currently loose within the contract. +- Permissioned Version: A strategy decides to only allow a certain address deposit into the vault by overriding maxAvailableDeposit. +- Risk: A strategist implements an options strategy that can create large positive gains or potentially loose all deposited funds. +- ... -Anything else is left to the strategy writer. However, to make security review easier, Yearn's template has the following optional functions: -- `tend()`: a function that will be called by bots. It will do whatever is required to maintain a position, such as act on certain triggers. -- `tendTrigger()`: implementation which triggers bots that will call tend function on the contract. -- `invest()`: deposit funds into the underlying protocol. -- `emergencyFreeFunds()`: close the position and return funds to the strategy. Losses can be accepted here. +### Development +Strategists should be able to use a pre-built "Strategy Mix" that will contain the imported BaseTokenizedStrategy.sol as well as standardized tests for any 4626 vault. Developing a strategy can be as simple as overriding three functions, with the potential for any number of other constraints or actions to be built on top of it. The Base implementation is only ~2KB, meaning there is plenty of room for strategists to build complex implementations while not having to be concerned with the generic functionality. -## ERC4626 Compliance -Vault shares are ERC4626 compliant. -The most important implication is that the `withdraw` and `redeem` functions as presented in ERC4626, the liquidity to redeem shares will be the one in the vault. No strategies will be passed to the redeem function to withdraw with the `withdraw` and `redeem` function. +#### Needed to Override -## Emergency Operation +*_deployFunds(uint256 _amount)*: This function is called after every deposit or mint. Its only job is to deposit up to the '_amount' of 'asset'. -### Shutdown Mode -If the current roles stop fulfilling their responsibilities or something bad or unplanned happens, the `EMERGENCY_MANAGER` can shut down the vault. +*_freeFunds(uint256 _amount)*: This function is called during every withdraw or redeem and should attempt to simply withdraw the '_amount' of 'asset'. Any difference between _amount and whats actually withdrawn will be counted as a loss -The `Shutdown mode` is a last resort option reserved for an emergency as it is irreversible. +*_harvestandReport()*: This function is used during a report and should accrue all rewards and return the total amount of 'asset' the strategy currently has in its control. -### Deposits -- **Light emergency**: Deposits can be paused by setting `depositLimit` to 0. -- **Shutdown mode**: Deposits are not allowed. +#### Optional to Override -### Withdrawals -Withdrawals cannot be paused under any circumstance. +While it can be possible to deploy a completely ERC-4626 compliant vault with just those three functions it does allow for further customization if the strategist desires. -### Accounting -Shutdown mode does not affect accounting. +*_tend* and *tendTrigger* can be overridden to signal to keepers the need for any sort of maintenance or reward selling between reports. -### Debt Rebalance -- **Light emergency**: Setting `minimumTotalIdle` to `MAX_UINT256` will result in the vault requesting the debt back from strategies. This would stop new strategies from getting funded as well as the vault prioritizes `minimumTotalIdle`. -- **Shutdown mode**: All strategies' `maxDebt` is set to 0. Strategies will return funds as soon as they can. +*maxAvailableDeposit(address _owner)* can be overridden to implement any type of deposit limit. -### Relevant Emergency +*maxAvailableWithdraw(address _owner)* can be used to limit the amount that a user can withdraw at any given moment. -> If the current roles stop fulfilling their responsibilities or something else happens, the `EMERGENCY_MANAGER` can shut down the vault. -> -> The shutdown mode should be the last option in an emergency, as it is irreversible. +*emergencyWithdra(uint256 _amount)* can be overridden to provide a manual method for management to pull funds from a yield source in an emergency when the vault is shutdown. -During `Shutdown mode`, the vault will try to get funds back from every strategy as soon as possible. +### Deployment +All strategies deployed will have the address of the deployed 'TokenizedStrategy' set as a constant to be used as the address to forward all external calls to that are not defined in the Strategy. -No strategies can be added during shutdown. +When deploying a new Strategy, it requires the following parameters: +- asset: address of the ERC20 token that can be deposited in the strategy +- name: name of Shares as described in ERC20 -Any relevant role will start pointing to the `EMERGENCY_MANAGER` in case new permissioned allowed actions need to be taken. +All other parameters will default to generic values and can be adjusted post deployment by the deployer if desired. # Read More - https://medium.com/iearn/yearnv3-motivation-and-design-107840cb4844 From 3d86073111c2e830cb8fbfc32c049c7be6b63e74 Mon Sep 17 00:00:00 2001 From: Schlagonia Date: Thu, 29 Jun 2023 09:07:48 -0600 Subject: [PATCH 31/54] chore: update the spechs --- docs/getting-started/products/yvaults/v3.md | 179 ++++++++++---------- 1 file changed, 90 insertions(+), 89 deletions(-) diff --git a/docs/getting-started/products/yvaults/v3.md b/docs/getting-started/products/yvaults/v3.md index b0e622aeac..130d5814ed 100644 --- a/docs/getting-started/products/yvaults/v3.md +++ b/docs/getting-started/products/yvaults/v3.md @@ -33,26 +33,7 @@ Periphery contracts are a separate layer of optional contracts to use with vault # Version 3 yVault Specification -## Definitions -- **Asset**: Any ERC20-compliant token -- **Shares**: ERC20-compliant token that tracks Asset balance in the vault for every distributor. Named yv -- **Depositor**: Account that holds Shares -- **Strategy**: Smart contract used to deposit in Protocols to generate yield -- **Vault**: ERC4626 compliant smart contract that receives Assets from Depositors to distribute amongst the different Strategies added to the vault: manages accounting and Assets distribution. -- **Role**: Flags that an Account can do specific Vault actions. Can be fulfilled by a smart contract or an externally owned account. -- **Accountant**: Smart contract that receives P&L reporting and returns shares and refunds to the strategy -# Yearn System Specification - -## V3 "Meta" Vault Specification - -### Definitions -- Asset: Any ERC20-compliant token -- Shares: ERC20-compliant token that tracks Asset balance in the vault for every distributor. Named yv -- Depositor: Account that holds Shares -- Strategy: Smart contract that is used to deposit in Protocols to generate yield -- Vault: ERC4626 compliant Smart contract that receives Assets from Depositors to then distribute them among the different Strategies added to the vault, managing accounting and Assets distribution. -- Role: the different flags an Account can have in the Vault so that the Account can do certain specific actions. Can be fulfilled by a smart contract or an EOA. -- Accountant: smart contract that receives P&L reporting and returns shares and refunds to the strategy +## Overview The Vault code has been designed as an non-opinionated system to distribute funds of depositors into different opportunities (aka Strategies) and manage accounting in a robust way. That's all. @@ -75,7 +56,17 @@ Example periphery contracts: - Strategy Staking Module: a smart contract that allows players to sponsor specific strategies (so that they are added to the vault) by staking their YFI, making money if they do well and losing money if they don't - ... ``` -### Deployment + +## Definitions +- Asset: Any ERC20-compliant token +- Shares: ERC20-compliant token that tracks Asset balance in the vault for every distributor. Named yv +- Depositor: Account that holds Shares +- Strategy: Smart contract that is used to deposit in Protocols to generate yield +- Vault: ERC4626 compliant Smart contract that receives Assets from Depositors to then distribute them among the different Strategies added to the vault, managing accounting and Assets distribution. +- Role: the different flags an Account can have in the Vault so that the Account can do certain specific actions. Can be fulfilled by a smart contract or an EOA. +- Accountant: smart contract that receives P&L reporting and returns shares and refunds to the strategy + +## Deployment We expect all the vaults available to be deployed from a Factory Contract, publicly available and callable. Players deploying "branded" vaults (e.g. Yearn) will use a separate registry to allow permissioned endorsement of vaults for their product @@ -87,28 +78,30 @@ When deploying a new vault, it requires the following parameters: - role_manager: account that can assign and revoke Roles - profit_max_unlock_time: max amount of time profit will be locked before being distributed -### Normal Operation +## Normal Operation -#### Deposits / Mints +### Deposits / Mints Users can deposit ASSET tokens to receive yvTokens (SHARES). Deposits are limited under depositLimit and shutdown parameters. Read below for details. -#### Withdrawals / Redeems +### Withdrawals / Redeems Users can redeem their shares at any point in time if there is liquidity available. Optionally, a user can specify a list of strategies to withdraw from. If a list of strategies is passed, the vault will try to withdraw from them. If a user passed array is not defined, the redeem function will use the default_queue. -If not enough funds have been recovered to honor the full request, the transaction will revert. +In order to properly comply with the ERC-4626 standard and still allow losses, both withdraw and redeem have an additional optional parameter of 'maxLoss' that can be used. The default for 'maxLoss' is 0 (i.e. revert if any loss) for withdraws, and 10_000 (100%) for redeems. + +If not enough funds have been recovered to honor the full request within the maxLoss, the transaction will revert. -#### Vault Shares +### Vault Shares Vault shares are ERC20 transferable yield-bearing tokens. They are ERC4626 compliant. Please read [ERC4626 compliance](https://hackmd.io/cOFvpyR-SxWArfthhLJb5g#ERC4626-compliance) to understand the implications. -#### Accounting +### Accounting The vault will evaluate profit and losses from the strategies. This is done comparing the current debt of the strategy with the total assets the strategy is reporting to have. @@ -118,14 +111,14 @@ If totalAssets > currentDebt: the vault will record a profit Both loss and profit will impact strategy's debt, increasing the debt (current debt + profit) if there are profits, decreasing its debt (current debt - loss) if there are losses. -##### Fees +#### Fees Fee assessment and distribution are handled by the Accountant module. It will report the amount of fees that need to be charged and the vault will issue shares for that amount of fees. There is also an optional protocol_fee that can be charged based on the configuration of the VaultFactory.vy -#### Profit distribution +### Profit distribution Profit from different process_report calls will accumulate in a buffer. This buffer will be linearly unlocked over the locking period seconds at profit_distribution_rate. Profits will be locked for a max period of time of profit_max_unlock_time seconds and will be gradually distributed. To avoid spending too much gas for profit unlock, the amount of time a profit will be locked is a weighted average between the new profit and the previous profit. @@ -139,12 +132,12 @@ Issue of new shares due to fees will also unlock profit so that PPS does not go Both of this offsets will prevent front running (as the profit was already earned and was not distributed yet) -### Vault Management +## Vault Management Vault management is split into function specific roles. Each permissioned function has its own corresponding Role. This means roles can be combined all to one address, each distributed to separate addresses or any combination in between -### Roles +## Roles Vault functions that are permissioned will be callable by accounts that hold specific roles. These are: @@ -152,7 +145,7 @@ These are: - REVOKE_STRATEGY_MANAGER: role that can remove strategies from the vault - FORCE_REVOKE_MANAGER: role that can force remove a strategy causing a loss - ACCOUNTANT_MANAGER: role that can set the accountant that assesses fees -- QUEUE_MANAGER: role that can set the default_queue +- QUEUE_MANAGER: role that can set the default withdrawal queue. - REPORTING_MANAGER: role that calls report for strategies - DEBT_MANAGER: role that adds and removes debt from strategies - MAX_DEBT_MANAGER: role that can set the max debt for a strategy @@ -168,7 +161,7 @@ The account that manages roles is a single account, set in `role_manager`. This role_manager can be an EOA, a multi-sig or a Governance Module that relays calls. -#### Strategy Management +### Strategy Management This responsibility is taken by callers with ADD_STRATEGY_MANAGER, REVOKE_STRATEGY_MANAGER and FORCE_REVOKE_MANAGER roles A vault can have strategies added, removed or forcefully removed @@ -179,17 +172,17 @@ Revoked strategies will return all debt and stop being eligible to receive more. Force revoking a strategy is only used in cases of a faulty strategy that cannot otherwise have its current_debt reduced to 0. Force revoking a strategy will result in a loss being reported by the vault. -##### Setting the periphery contracts +#### Setting the periphery contracts The accountant can each be set by the ACCOUNTANT_MANAGER. The contract is not needed for the vault to function but are recommended for optimal use. -##### Reporting profits +#### Reporting profits The REPORTING_MANAGER is in charge of calling process_report() for each strategy in the vault according to its own timeline This call will do the necessary accounting and profit locking for the individual strategy as well as charging fees -#### Debt Management +### Debt Management This responsibility is taken by callers with DEBT_MANAGER role This role can increase or decrease strategies specific debt. @@ -226,7 +219,7 @@ The PROFIT_UNLOCK_MANAGER is in charge of updating and setting the profit_max_un This can be customized based on the vault based on aspects such as number of strategies, TVL, expected returns etc. -### Setting the default queue +#### Setting the default queue The QUEUE_MANAGER has the option to set a custom default_queue if desired. The vault will arrange the default queue automatically based only on the order that strategies were added to the vault. If a different order is desired the queue manager role can set a custom queue. All strategies in the default queue must have been previously added to the vault. @@ -244,50 +237,54 @@ In an emergency the EMERGENCY_MANAGER can shutdown the vault This will also give the EMERGENCY_MANAGER the DEBT_MANAGER roles as well so funds can start to be returned from the strategies -### Strategy Minimum API +## Strategy Minimum API Strategies are completely independent smart contracts that can be implemented following the proposed template or in any other way. In any case, to be compatible with the vault, they need to implement the following functions, which are a subset of ERC4626 vaults: - asset(): view returning underlying asset -- vault(): view returning vault this strategy is plugged to - totalAssets(): view returning current amount of assets. It can include rewards valued in `asset` ¡ - maxDeposit(address): view returning the amount max that the strategy can take safely - deposit(assets, receiver): deposits `assets` amount of tokens into the strategy. it can be restricted to vault only or be open - maxWithdraw(address): view returning how many asset can the vault take from the vault at any given point in time - withdraw(assets, receiver, owner): withdraws `assets` amount of tokens from the strategy +- redeem(shares, receiver, owner): redeems `shares` of the strategy for the underlying asset. - balanceOf(address): return the number of shares of the strategy that the address has +- convertToAssets(shares: uint256): Converts `shares` into the corresponding amount of asset. +- convertToShares(assets: uint256): Converts `assets` into the corresponding amount of shares. +- previewWithdraw(assets: uint256): Converst `assets` into the corresponding amount of shares rounding up. This means that the vault can deposit into any ERC4626 vault but also that a non-compliant strategy can be implemented provided that these functions have been implemented (even in a non ERC4626 compliant way). -### ERC4626 compliance +## ERC4626 compliance Vault Shares are ERC4626 compliant. -The most important implication is that `withdraw` and `redeem` functions as presented in ERC4626, if no queue_manager is set the liquidity to redeem shares will just be the one in the vault. No strategies will be passed to the redeem function to withdraw from with the ERC4626 compliant `withdraw` and `redeem` function. +The most important implication is that `withdraw` and `redeem` functions as presented in ERC4626, with the ability to add two additional non-standard options. -### Emergency Operation +1. max_loss: The amount in basis points that the withdrawer will accept as a loss. I.E. 100 = 1% loss accepted. +2. strategies: This is an array of strategies to use as the withdrawal queue instead of the default queue. -#### Shutdown mode +### Shutdown mode In the case the current roles stop fulfilling their responsibilities or something else happens, the EMERGENCY_MANAGER can shutdown the vault. The shutdown mode should be the last option in an emergency as it is irreversible. -#### Deposits +### Deposits _Light emergency_: Deposits can be paused by setting depositLimit to 0 _Shutdown mode_: Deposits are not allowed -#### Withdrawals +### Withdrawals Withdrawals can't be paused under any circumstance -#### Accounting +### Accounting Shutdown mode does not affect accounting -#### Debt rebalance +### Debt rebalance _Light emergency_: Setting minimumTotalIdle to MAX_UINT256 will result in the vault requesting the debt back from strategies. This would stop new strategies from getting funded too, as the vault prioritizes minimumTotalIdle _Shutdown mode_: All strategies maxDebt is set to 0. Strategies will return funds as soon as they can. -#### Relevant emergency +### Relevant emergency In the case the current roles stop fulfilling their responsibilities or something else happens, the EMERGENCY_MANAGER can shutdown the vault. The shutdown mode should be the last option in an emergency as it is irreversible. @@ -299,10 +296,12 @@ No strategies can be added during shutdown Any relevant role will start pointing to the EMERGENCY_MANAGER in case new permissioned allowed actions need to be taken. -## V3 Tokenized Strategy Specification +# Yearn V3 Tokenized Strategy Specification -### Overview -The Yearn V3 "Tokenized Strategy" goal is to make it as easy as possible for any person or protocol to create and deploy their own ERC-4626 compliant single strategy vault. It uses an immutable proxy pattern to outsource all of the standardized 4626 and other vault logic to one implementation contract that all Strategies deployed on a specific chain use through delegatecall. This makes the strategy specific contract as simple and specific to that yield generating task as possible and allows for anyone to simply plug their version into a permissionless, secure and optimized 4626 compliant base that handles all risky and complicated code. +## Overview +The Yearn V3 "Tokenized Strategy" goal is to make it as easy as possible for any person or protocol to create and deploy their own ERC-4626 compliant single strategy vault. It uses an immutable proxy pattern to outsource all of the standardized 4626 and other vault logic to one implementation contract that all Strategies deployed on a specific chain use through delegatecall. + +This makes the strategy specific contract as simple and specific to that yield generating task as possible and allows for anyone to simply plug their version into a permissionless, secure and optimized 4626 compliant base that handles all risky and complicated code. ### Definitions @@ -313,12 +312,12 @@ The Yearn V3 "Tokenized Strategy" goal is to make it as easy as possible for any - BaseTokenizedStrategy: The abstract contract that a strategy should inherit from that handles all communication with the Tokenized Strategy contract. - Strategist: The developer of a specific strategy. - Depositor: Account that holds Shares -- Vault: ERC4626 compliant Smart contract that receives Assets from Depositors to then distribute them among the different Strategies added to the vault, managing accounting and Assets distribution. +- Vault: Or "Meta Vault" is an ERC4626 compliant Smart contract that receives Assets from Depositors to then distribute them among the different Strategies added to the vault, managing accounting and Assets distribution. - Management: The owner of the specific strategy that can set fees, profit unlocking time etc. - Keeper: the address of a contract allowed to call report() and tend() on a strategy. -- Factory: The factory that all vaults of a specific API version are cloned from that also controls the protocol fee amount and recipient. +- Factory: The factory that all meta vaults of a specific API version are cloned from that also controls the protocol fee amount and recipient. -### Storage +## Storage In order to standardize all high risk and complex logic associated with ERC4626, ERC20 and profit locking, all core logic has been moved to the 'TokenizedStrategy.sol' and is used by each strategy through a fallback function that delegatecall's this contract to do all necessary checks, logic and storage updates for the strategy. The TokenizedStrategy will only need to be deployed once on each chain and can then be used by an unlimited number of strategies. Allowing the BaseTokenizedStrategy.sol to be much smaller, simpler and cheaper to deploy. @@ -329,18 +328,18 @@ In order to limit the strategists need to think about their storage variables al This means all high risk storage updates will always be handled by the TokenizedStrategy, should not be able to be overridden by a reckless strategist and will be entirely standardized across every strategy deployed, no matter the chain or specific implementation. -### BaseTokenizedStrategy +## BaseTokenizedStrategy The base tokenized strategy is a simple abstract contract to be inherited by the strategist that handles all communication with the TokenizedStrategy. -#### Modifiers +### Modifiers `onlySelf`: This modifier is placed on any callback functions for the TokenizedStrategy to call during deposits, withdraws, reports and tends. The modifier should revert if msg.sender is not equal to itself. In order for a call to be forwarded to the TokenizedStrategy it must not be defined in the Strategy and hit the fallback function which will delegatecall the TokenizedStrategy. If within that call, the TokenizedStrategy makes an external static call back to the BaseTokenizedStrategy the msg.sender of that call will be the original caller, which should be the Strategy itself. `OnlyManagement`: Should be placed on function that only the Strategies specific management address can call. This uses the isManagement(address) function defined in TokenizedStrategy by sending the original msg.sender address. `onlyKeepers`: Should be placed on functions that only the Strategies specific management or keeper can call. This uses the isManagementOrKeeper(address) defined in TokenizedStrategy sending the original msg.sender address. -#### Variables +### Variables `tokenizedStrategyAddress`: This is the address the fallback function will use to delegatecall to and is set before deployment to a constant so it can never be changed. @@ -348,7 +347,7 @@ The base tokenized strategy is a simple abstract contract to be inherited by the `asset`: The immutable address of the underlying asset being used. -#### Functions +### Functions The majority of function in the BaseTokenizedStrategy are either external functions with onlySelf modifiers used for the TokenizedStrategy to call. Or the internal functions that correspond to those external functions that should or can be overridden by a strategist with the strategy specific logic. @@ -366,35 +365,35 @@ The majority of function in the BaseTokenizedStrategy are either external functi `shutdownWithdraw(uint256)/_emergencyWithdraw(uint256)`: Optional function for a strategist to implement that will allow management to manually withdraw a specified amount from the yield source if a strategy is shutdown in the case of emergencies. -`init(...)`: Used only once during initialization to manually delegatecall the TokenizedStrategy to tell it to set up the storage for a new strategy. +`_init(...)`: Used only once during initialization to manually delegatecall the TokenizedStrategy to tell it to set up the storage for a new strategy. -### TokenizedStrategy +## TokenizedStrategy The tokenized strategy contract should implement all ERC-4626, ERC-20, ERC-2612 and custom TokenizedStrategy specific report and tending logic within it. For deposits, withdraws, report, tend and emergency withdraw calls it casts address(this) into a custom IBaseTokenizedStrategy() interface to static call back the initial calling contract when it needs to interact with the Strategy. -#### Normal Operation +### Normal Operation The TokenizedStrategy is responsible for handling the logic associated with all the following functionality. -##### Deposits / Mints +#### Deposits / Mints Users can deposit ASSET tokens to receive shares. Deposits are limited by the maxAvailableDeposit function that can be changed by the strategist if non uint256.max values are desired. -##### Withdrawals / Redeems +#### Withdrawals / Redeems Users can redeem their shares at any point in time if there is liquidity available. The amount of a withdraw or redeem can be limited by the strategist by overriding the maxAvailableWithdraw function. -If not enough funds have been recovered to honor the full request, the strategy will pass on the difference to the user as a loss. +In order to properly comply with the ERC-4626 standard and still allow losses, both withdraw and redeem have an additional optional parameter of 'maxLoss' that can be used. The default for 'maxLoss' is 0 (i.e. revert if any loss) for withdraws, and 10_000 (100%) for redeems. -##### Strategy Shares +#### Strategy Shares The strategy issues shares to each depositor to track their relative share of assets. Shares are ERC20 transferable yield-bearing tokens. They are ERC4626 compliant. Please read [ERC4626 compliance](https://hackmd.io/cOFvpyR-SxWArfthhLJb5g#ERC4626-compliance) to understand the implications. -##### Accounting +#### Accounting The strategy will evaluate profit and losses from the yield generating activities. This is done comparing the current totalAssets of the strategy with the amount returned from _harvestAndReport() @@ -404,16 +403,16 @@ If totalAssets > newTotalAssets: the vault will record a profit Both loss and profit will impact strategy's totalAssets, increasing if there are profits, decreasing if there are losses. -##### Fees +#### Fees Fee assessment and distribution is handled during each `report` call after profits or losses are recorded. It will report the amount of fees that need to be charged and the strategy will issue shares for that amount of fees. -There are two potential fees. Performance fees and protocol fees. Performance fees are configurable by management of the strategy and payed based on the reported profit during each report with a max of 50%. +There are two potential fees. Performance fees and protocol fees. Performance fees are configurable by management of the strategy and payed based on the reported profit during each report with a min of 5% and a max of 50%. Protocol fees are configured by Yearn governance through the Factory and are taken as a percent of the performanceFees charged. I.E. profit = 100, performance fees = 20% protocol fees = 10%. Then total fees charged = 100 * .2 = 20 of which 10% is sent to the protocol fee recipient (2) and 90% (18) is sent the strategy specific `performanceFeeRecipient`. -#### Profit distribution +### Profit distribution Profit from report calls will accumulate in a buffer. This buffer will be linearly unlocked over the locking period seconds at profitUnlockingRate. Profits will be locked for a max period of time of profitMaxUnlockTime seconds and will be gradually distributed. To avoid spending too much gas for profit unlock, the amount of time a profit will be locked is a weighted average between the new profit and the previous profit. @@ -427,8 +426,8 @@ Issue of new shares due to fees will also unlock profit so that PPS does not go Both of this offsets will prevent front running (as the profit was already earned and was not distributed yet) -#### Strategy Management -Strategy management is held by the 'management' address that can be updated at any time by the current 'managment' +### Strategy Management +Strategy management is held by the 'management' address that can be updated by the current 'managment'. Changing 'management' is a two step process, so first the current management will have to set 'pendingManagement' then that pending management will need to accept the role. Management has the ability to set all the configurable variables for their specific Strategy. @@ -436,29 +435,32 @@ The base strategy has purposely been written to limit the actual control managem The configurable variables within managements control are: -##### Setting Management -This allows the current management to set a new non-zero address as the management of the strategy. +#### Setting Pending Management +This allows the current management to set a new non-zero address to take over as the management of the strategy. + +#### Accepting Management +This allows the current 'pendingManagement' to accept the ownership of the contract. -##### Setting the keeper +#### Setting the keeper Setting the address that is also allowed to call report and tend functions. -##### Setting Performance Fee -Setting the percent in terms of Basis points for the amount of profit to be charged as a fee. +#### Setting Performance Fee +Setting the percent in terms of basis points for the amount of profit to be charged as a fee. -The max this can be 99.99%. +This has a minimum of 5% and a maximum of 50%. -##### Setting performance fee recipient +#### Setting performance fee recipient Setting the non-zero address that will receive any shares issued as a result of the performance fee. -##### Setting the profit unlock period +#### Setting the profit unlock period Sets the time in seconds that controls how fast profits will unlock. This can be customized based on the strategy. Based on aspects such as TVL, expected returns etc. -### ERC4626 compliance +## ERC4626 compliance Strategy Shares are ERC4626 compliant. -### Emergency Operation +## Emergency Operation There is default emergency functions built in. First of which is `shutdownStrategy`. This can only ever be called by the management address and is non-reversible. Once this is called it will stop any further deposit or mints but will have no effect on any other functionality including withdraw, redeem, report and tend. This is to all the management to continue potentially recording profits or losses and users to withdraw even post shutdown. @@ -469,11 +471,11 @@ Once a strategy is shutdown management can also call `emergencyWithdraw(amount)` All other emergency functionality is left up to the individual strategist. -#### Withdrawals +### Withdrawals Withdrawals can't be paused under any circumstance unless built in a specific implementation. -### Use +## Use A strategist can simply inherit the BaseTokenizedStrategy.sol contract and override 3 simple functions with their specific needs. The strategies code has been designed as a non-opinionated system to distribute funds of depositors to a single yield generating opportunity while managing accounting in a robust way. @@ -498,11 +500,11 @@ Example constraints: - Risk: A strategist implements an options strategy that can create large positive gains or potentially loose all deposited funds. - ... -### Development +## Development Strategists should be able to use a pre-built "Strategy Mix" that will contain the imported BaseTokenizedStrategy.sol as well as standardized tests for any 4626 vault. Developing a strategy can be as simple as overriding three functions, with the potential for any number of other constraints or actions to be built on top of it. The Base implementation is only ~2KB, meaning there is plenty of room for strategists to build complex implementations while not having to be concerned with the generic functionality. -#### Needed to Override +### Needed to Override *_deployFunds(uint256 _amount)*: This function is called after every deposit or mint. Its only job is to deposit up to the '_amount' of 'asset'. @@ -510,7 +512,7 @@ Strategists should be able to use a pre-built "Strategy Mix" that will contain t *_harvestandReport()*: This function is used during a report and should accrue all rewards and return the total amount of 'asset' the strategy currently has in its control. -#### Optional to Override +### Optional to Override While it can be possible to deploy a completely ERC-4626 compliant vault with just those three functions it does allow for further customization if the strategist desires. @@ -520,9 +522,9 @@ While it can be possible to deploy a completely ERC-4626 compliant vault with ju *maxAvailableWithdraw(address _owner)* can be used to limit the amount that a user can withdraw at any given moment. -*emergencyWithdra(uint256 _amount)* can be overridden to provide a manual method for management to pull funds from a yield source in an emergency when the vault is shutdown. +*_emergencyWithdraw(uint256 _amount)* can be overridden to provide a manual method for management to pull funds from a yield source in an emergency when the vault is shutdown. -### Deployment +## Deployment All strategies deployed will have the address of the deployed 'TokenizedStrategy' set as a constant to be used as the address to forward all external calls to that are not defined in the Strategy. When deploying a new Strategy, it requires the following parameters: @@ -530,7 +532,6 @@ When deploying a new Strategy, it requires the following parameters: - name: name of Shares as described in ERC20 All other parameters will default to generic values and can be adjusted post deployment by the deployer if desired. - # Read More - https://medium.com/iearn/yearnv3-motivation-and-design-107840cb4844 - https://medium.com/iearn/yearn-vaults-v3-36ce7c468ca0 From 16b81c496f934c34b9f73e1bb7d4839a982623f7 Mon Sep 17 00:00:00 2001 From: Marco Guaspari Worms Date: Wed, 26 Jul 2023 14:42:29 -0300 Subject: [PATCH 32/54] Apply suggestions from code review --- docs/getting-started/products/yvaults/v3.md | 114 ++++++++++---------- 1 file changed, 57 insertions(+), 57 deletions(-) diff --git a/docs/getting-started/products/yvaults/v3.md b/docs/getting-started/products/yvaults/v3.md index 130d5814ed..6e77706099 100644 --- a/docs/getting-started/products/yvaults/v3.md +++ b/docs/getting-started/products/yvaults/v3.md @@ -72,18 +72,18 @@ We expect all the vaults available to be deployed from a Factory Contract, publi Players deploying "branded" vaults (e.g. Yearn) will use a separate registry to allow permissioned endorsement of vaults for their product When deploying a new vault, it requires the following parameters: -- asset: address of the ERC20 token that can be deposited in the vault -- name: name of Shares as described in ERC20 -- symbol: symbol of Shares ERC20 -- role_manager: account that can assign and revoke Roles -- profit_max_unlock_time: max amount of time profit will be locked before being distributed +- `asset`: address of the ERC20 token that can be deposited in the vault +- `name`: name of Shares as described in ERC20 +- `symbol`: symbol of Shares ERC20 +- `role_manager`: account that can assign and revoke Roles +- `profit_max_unlock_time`: max amount of time profit will be locked before being distributed ## Normal Operation ### Deposits / Mints -Users can deposit ASSET tokens to receive yvTokens (SHARES). +Users can deposit asset tokens (ASSET) to receive yvTokens (SHARES). -Deposits are limited under depositLimit and shutdown parameters. Read below for details. +Deposits are limited under `depositLimit` and shutdown parameters. Read below for details. ### Withdrawals / Redeems Users can redeem their shares at any point in time if there is liquidity available. @@ -123,17 +123,17 @@ Profit from different process_report calls will accumulate in a buffer. This buf Profits will be locked for a max period of time of profit_max_unlock_time seconds and will be gradually distributed. To avoid spending too much gas for profit unlock, the amount of time a profit will be locked is a weighted average between the new profit and the previous profit. -new_locking_period = locked_profit * pending_time_to_unlock + new_profit * PROFIT_MAX_UNLOCK_TIME / (locked_profit + new_profit) -new_profit_distribution_rate = (locked_profit + new_profit) / new_locking_period +`new_locking_period = locked_profit * pending_time_to_unlock + new_profit * PROFIT_MAX_UNLOCK_TIME / (locked_profit + new_profit)` +`new_profit_distribution_rate = (locked_profit + new_profit) / new_locking_period` Losses will be offset by locked profit, if possible. Issue of new shares due to fees will also unlock profit so that PPS does not go down. -Both of this offsets will prevent front running (as the profit was already earned and was not distributed yet) +Both of this offsets will prevent front running (as the profit was already earned and was not distributed yet). ## Vault Management -Vault management is split into function specific roles. Each permissioned function has its own corresponding Role. +Vault management is split into function specific roles. Each permissioned function has its own corresponding role. This means roles can be combined all to one address, each distributed to separate addresses or any combination in between @@ -141,19 +141,19 @@ This means roles can be combined all to one address, each distributed to separat Vault functions that are permissioned will be callable by accounts that hold specific roles. These are: -- ADD_STRATEGY_MANAGER: role than can add strategies to the vault -- REVOKE_STRATEGY_MANAGER: role that can remove strategies from the vault -- FORCE_REVOKE_MANAGER: role that can force remove a strategy causing a loss -- ACCOUNTANT_MANAGER: role that can set the accountant that assesses fees -- QUEUE_MANAGER: role that can set the default withdrawal queue. -- REPORTING_MANAGER: role that calls report for strategies -- DEBT_MANAGER: role that adds and removes debt from strategies -- MAX_DEBT_MANAGER: role that can set the max debt for a strategy -- DEPOSIT_LIMIT_MANAGER: role that sets deposit limit for the vault -- MINIMUM_IDLE_MANAGER: role that sets the minimum total idle the vault should keep -- PROFIT_UNLOCK_MANAGER: role that sets the profit_max_unlock_time -- DEBT_PURCHASER # can purchase bad debt from the vault -- EMERGENCY_MANAGER: role that can shutdown vault in an emergency +- `ADD_STRATEGY_MANAGER`: role than can add strategies to the vault. +- `REVOKE_STRATEGY_MANAGER`: role that can remove strategies from the vault. +- `FORCE_REVOKE_MANAGER`: role that can force remove a strategy causing a loss. +- `ACCOUNTANT_MANAGER`: role that can set the accountant that assesses fees. +- `QUEUE_MANAGER`: role that can set the default withdrawal queue. +- `REPORTING_MANAGER`: role that calls report for strategies. +- `DEBT_MANAGER`: role that adds and removes debt from strategies. +- `MAX_DEBT_MANAGER`: role that can set the max debt for a strategy. +- `DEPOSIT_LIMIT_MANAGER`: role that sets deposit limit for the vault. +- `MINIMUM_IDLE_MANAGER`: role that sets the minimum total idle the vault should keep. +- `PROFIT_UNLOCK_MANAGER`: role that sets the profit_max_unlock_time. +- `DEBT_PURCHASER`: can purchase bad debt from the vault. +- `EMERGENCY_MANAGER`: role that can shutdown vault in an emergency. Every role can be filled by an EOA, multi-sig or other smart contracts. Each role can be filled by several accounts. @@ -162,7 +162,7 @@ The account that manages roles is a single account, set in `role_manager`. This role_manager can be an EOA, a multi-sig or a Governance Module that relays calls. ### Strategy Management -This responsibility is taken by callers with ADD_STRATEGY_MANAGER, REVOKE_STRATEGY_MANAGER and FORCE_REVOKE_MANAGER roles +This responsibility is taken by callers with `ADD_STRATEGY_MANAGER`, `REVOKE_STRATEGY_MANAGER` and `FORCE_REVOKE_MANAGER` roles A vault can have strategies added, removed or forcefully removed @@ -173,12 +173,12 @@ Revoked strategies will return all debt and stop being eligible to receive more. Force revoking a strategy is only used in cases of a faulty strategy that cannot otherwise have its current_debt reduced to 0. Force revoking a strategy will result in a loss being reported by the vault. #### Setting the periphery contracts -The accountant can each be set by the ACCOUNTANT_MANAGER. +The accountant can each be set by the `ACCOUNTANT_MANAGER`. The contract is not needed for the vault to function but are recommended for optimal use. #### Reporting profits -The REPORTING_MANAGER is in charge of calling process_report() for each strategy in the vault according to its own timeline +The `REPORTING_MANAGER` is in charge of calling process_report() for each strategy in the vault according to its own timeline This call will do the necessary accounting and profit locking for the individual strategy as well as charging fees @@ -196,36 +196,36 @@ The vault checks that the `minimumTotalIdle` parameter is respected (i.e. there' If the strategy has more debt than the max_debt, the vault will request the funds back. These funds may be locked in the strategy, which will result in the strategy returning less funds than requested by the vault. #### Setting maximum debt for a specific strategy -The MAX_DEBT_MANAGER can set the maximum amount of tokens the vault will allow a strategy to owe at any moment in time. +The `MAX_DEBT_MANAGER` can set the maximum amount of tokens the vault will allow a strategy to owe at any moment in time. -Stored in strategies[strategy].max_debt +Stored in `strategies[strategy].max_debt` When a debt re-balance is triggered, the Vault will cap the new target debt to this number (max_debt) #### Setting the deposit limit -The DEPOSIT_LIMIT_MANAGER is in charge of setting the deposit_limit for the vault +The `DEPOSIT_LIMIT_MANAGER` is in charge of setting the deposit_limit for the vault. On deployment deposit_limit defaults to 0 and will need to be increased to make the vault functional #### Setting minimum idle funds -The MINIMUM_IDLE_MANAGER can specify how many funds the vault should try to have reserved to serve withdrawal requests +The `MINIMUM_IDLE_MANAGER` can specify how many funds the vault should try to have reserved to serve withdrawal requests These funds will remain in the vault unless requested by a Depositor It is recommended that if no queue_manager is set some amount of funds should remain idle to service withdrawals #### Setting the profit unlock period -The PROFIT_UNLOCK_MANAGER is in charge of updating and setting the profit_max_unlock_time which controls how fast profits will unlock +The `PROFIT_UNLOCK_MANAGER` is in charge of updating and setting the profit_max_unlock_time which controls how fast profits will unlock This can be customized based on the vault based on aspects such as number of strategies, TVL, expected returns etc. #### Setting the default queue -The QUEUE_MANAGER has the option to set a custom default_queue if desired. The vault will arrange the default queue automatically based only on the order that strategies were added to the vault. If a different order is desired the queue manager role can set a custom queue. +The `QUEUE_MANAGER` has the option to set a custom default_queue if desired. The vault will arrange the default queue automatically based only on the order that strategies were added to the vault. If a different order is desired the queue manager role can set a custom queue. All strategies in the default queue must have been previously added to the vault. #### Buying Debt -The DEBT_PURCHASER role can buy debt from the vault in return for the equal amount of `asset`. +The `DEBT_PURCHASER` role can buy debt from the vault in return for the equal amount of `asset`. This should only ever be used in the case where governance wants to purchase a set amount of bade debt from the vault in order to not report a loss. @@ -233,25 +233,25 @@ It still relies on convertToShares() so will only be viable if the conversion do #### Shutting down the vault -In an emergency the EMERGENCY_MANAGER can shutdown the vault +In an emergency the `EMERGENCY_MANAGER` can shutdown the vault -This will also give the EMERGENCY_MANAGER the DEBT_MANAGER roles as well so funds can start to be returned from the strategies +This will also give the `EMERGENCY_MANAGER` the `DEBT_MANAGER` roles as well so funds can start to be returned from the strategies ## Strategy Minimum API Strategies are completely independent smart contracts that can be implemented following the proposed template or in any other way. In any case, to be compatible with the vault, they need to implement the following functions, which are a subset of ERC4626 vaults: -- asset(): view returning underlying asset -- totalAssets(): view returning current amount of assets. It can include rewards valued in `asset` ¡ -- maxDeposit(address): view returning the amount max that the strategy can take safely -- deposit(assets, receiver): deposits `assets` amount of tokens into the strategy. it can be restricted to vault only or be open -- maxWithdraw(address): view returning how many asset can the vault take from the vault at any given point in time -- withdraw(assets, receiver, owner): withdraws `assets` amount of tokens from the strategy -- redeem(shares, receiver, owner): redeems `shares` of the strategy for the underlying asset. -- balanceOf(address): return the number of shares of the strategy that the address has -- convertToAssets(shares: uint256): Converts `shares` into the corresponding amount of asset. -- convertToShares(assets: uint256): Converts `assets` into the corresponding amount of shares. -- previewWithdraw(assets: uint256): Converst `assets` into the corresponding amount of shares rounding up. +- `asset()`: view returning underlying asset +- `totalAssets()`: view returning current amount of assets. It can include rewards valued in `asset` ¡ +- `maxDeposit(address)`: view returning the amount max that the strategy can take safely +- `deposit(assets, receiver)`: deposits `assets` amount of tokens into the strategy. it can be restricted to vault only or be open +- `maxWithdraw(address)`: view returning how many asset can the vault take from the vault at any given point in time +- `withdraw(assets, receiver, owner)`: withdraws `assets` amount of tokens from the strategy +- `redeem(shares, receiver, owner)`: redeems `shares` of the strategy for the underlying asset. +- `balanceOf(address)`: return the number of shares of the strategy that the address has +- `convertToAssets(shares: uint256)`: Converts `shares` into the corresponding amount of asset. +- `convertToShares(assets: uint256)`: Converts `assets` into the corresponding amount of shares. +- `previewWithdraw(assets: uint256)`: Converst `assets` into the corresponding amount of shares rounding up. This means that the vault can deposit into any ERC4626 vault but also that a non-compliant strategy can be implemented provided that these functions have been implemented (even in a non ERC4626 compliant way). @@ -260,8 +260,8 @@ Vault Shares are ERC4626 compliant. The most important implication is that `withdraw` and `redeem` functions as presented in ERC4626, with the ability to add two additional non-standard options. -1. max_loss: The amount in basis points that the withdrawer will accept as a loss. I.E. 100 = 1% loss accepted. -2. strategies: This is an array of strategies to use as the withdrawal queue instead of the default queue. +1. `max_loss`: The amount in basis points that the withdrawer will accept as a loss. I.E. 100 = 1% loss accepted. +2. `strategies`: This is an array of strategies to use as the withdrawal queue instead of the default queue. ### Shutdown mode In the case the current roles stop fulfilling their responsibilities or something else happens, the EMERGENCY_MANAGER can shutdown the vault. @@ -269,9 +269,9 @@ In the case the current roles stop fulfilling their responsibilities or somethin The shutdown mode should be the last option in an emergency as it is irreversible. ### Deposits -_Light emergency_: Deposits can be paused by setting depositLimit to 0 +`_Light emergency_`: Deposits can be paused by setting depositLimit to 0 -_Shutdown mode_: Deposits are not allowed +`_Shutdown mode_`: Deposits are not allowed ### Withdrawals Withdrawals can't be paused under any circumstance @@ -280,12 +280,12 @@ Withdrawals can't be paused under any circumstance Shutdown mode does not affect accounting ### Debt rebalance -_Light emergency_: Setting minimumTotalIdle to MAX_UINT256 will result in the vault requesting the debt back from strategies. This would stop new strategies from getting funded too, as the vault prioritizes minimumTotalIdle +`_Light emergency_`: Setting minimumTotalIdle to MAX_UINT256 will result in the vault requesting the debt back from strategies. This would stop new strategies from getting funded too, as the vault prioritizes minimumTotalIdle -_Shutdown mode_: All strategies maxDebt is set to 0. Strategies will return funds as soon as they can. +`_Shutdown mode_`: All strategies maxDebt is set to 0. Strategies will return funds as soon as they can. ### Relevant emergency -In the case the current roles stop fulfilling their responsibilities or something else happens, the EMERGENCY_MANAGER can shutdown the vault. +In the case the current roles stop fulfilling their responsibilities or something else happens, the `EMERGENCY_MANAGER` can shutdown the vault. The shutdown mode should be the last option in an emergency as it is irreversible. @@ -293,7 +293,7 @@ During shutdown mode, the vault will try to get funds back from every strategy a No strategies can be added during shutdown -Any relevant role will start pointing to the EMERGENCY_MANAGER in case new permissioned allowed actions need to be taken. +Any relevant role will start pointing to the `EMERGENCY_MANAGER` in case new permissioned allowed actions need to be taken. # Yearn V3 Tokenized Strategy Specification @@ -398,8 +398,8 @@ The strategy will evaluate profit and losses from the yield generating activitie This is done comparing the current totalAssets of the strategy with the amount returned from _harvestAndReport() -If totalAssets < newTotalAssets: the vault will record a loss -If totalAssets > newTotalAssets: the vault will record a profit +If `totalAssets` < `newTotalAssets`: the vault will record a loss +If `totalAssets` > `newTotalAssets`: the vault will record a profit Both loss and profit will impact strategy's totalAssets, increasing if there are profits, decreasing if there are losses. From 5f934f9c7c292fd770f8f64303ba14dc7e3a23f8 Mon Sep 17 00:00:00 2001 From: Marco Guaspari Worms Date: Wed, 26 Jul 2023 14:48:25 -0300 Subject: [PATCH 33/54] grammar fixes --- docs/getting-started/products/yvaults/v3.md | 72 ++++++++++----------- 1 file changed, 36 insertions(+), 36 deletions(-) diff --git a/docs/getting-started/products/yvaults/v3.md b/docs/getting-started/products/yvaults/v3.md index 6e77706099..721b9558b4 100644 --- a/docs/getting-started/products/yvaults/v3.md +++ b/docs/getting-started/products/yvaults/v3.md @@ -1,7 +1,7 @@ # Version 3 Version 3 yVaults iterates on Version 2 by increasing robustness and developing Yearn’s path towards further decentralization, while keeping the same proven product (yield-bearing tokens) that abstract builders and users from the hard work of yield farming. Version 3 will both be able to have the same functionality as Version 2, but with many more added benefits and improvements to continue to grow the Yearn ecosystem. -V3 also sees the introduction of "Tokenized Strategies". In V3 the strategies are now capable of being standalone 4626 vaults themselves. These single strategy vaults can be used as stand alone vaults or due to the 4626 standard easily added as a strategy to any of the multi strategy "Meta Vaults". +V3 also sees the introduction of "Tokenized Strategies". In V3 the strategies are now capable of being standalone 4626 vaults themselves. These single-strategy vaults can be used as stand-alone vaults or due to the 4626 standard easily added as a strategy to any of the multi-strategy "Meta Vaults". Version 3 yVaults improves on Version 2 by: - Increasing vault modularity, allowing for smaller and safer pieces of code. @@ -35,7 +35,7 @@ Periphery contracts are a separate layer of optional contracts to use with vault ## Overview -The Vault code has been designed as an non-opinionated system to distribute funds of depositors into different opportunities (aka Strategies) and manage accounting in a robust way. That's all. +The Vault code has been designed as a non-opinionated system to distribute funds of depositors into different opportunities (aka Strategies) and manage accounting in a robust way. That's all. Depositors receive shares (aka vaults tokens) proportional to their deposit amount. Vault tokens are yield-bearing and can be redeemed at any time to get back deposit plus any yield generated. @@ -52,7 +52,7 @@ This allows different players to deploy their own version and implement their ow ``` Example periphery contracts: - Emergency module: it receives deposits of Vault Shares and allows the contract to call the shutdown function after a certain % of total Vault Shares have been deposited -- Debt Allocator: a smart contract that incentivises APY / debt allocation optimisation by rewarding the best debt allocation (see [yStarkDebtAllocator](https://github.com/jmonteer/ystarkdebtallocator)) +- Debt Allocator: a smart contract that incentivizes APY / debt allocation optimization by rewarding the best debt allocation (see [yStarkDebtAllocator](https://github.com/jmonteer/ystarkdebtallocator)) - Strategy Staking Module: a smart contract that allows players to sponsor specific strategies (so that they are added to the vault) by staking their YFI, making money if they do well and losing money if they don't - ... ``` @@ -104,10 +104,10 @@ They are ERC4626 compliant. Please read [ERC4626 compliance](https://hackmd.io/c ### Accounting The vault will evaluate profit and losses from the strategies. -This is done comparing the current debt of the strategy with the total assets the strategy is reporting to have. +This is done by comparing the current debt of the strategy with the total assets the strategy is reporting to have. -If totalAssets < currentDebt: the vault will record a loss -If totalAssets > currentDebt: the vault will record a profit +If `totalAssets` < `currentDebt`: the vault will record a loss +If `totalAssets` > `currentDebt`: the vault will record a profit Both loss and profit will impact strategy's debt, increasing the debt (current debt + profit) if there are profits, decreasing its debt (current debt - loss) if there are losses. @@ -128,12 +128,12 @@ Profits will be locked for a max period of time of profit_max_unlock_time second Losses will be offset by locked profit, if possible. -Issue of new shares due to fees will also unlock profit so that PPS does not go down. +The issue of new shares due to fees will also unlock profit so that PPS does not go down. -Both of this offsets will prevent front running (as the profit was already earned and was not distributed yet). +Both of these offsets will prevent front running (as the profit was already earned and was not distributed yet). ## Vault Management -Vault management is split into function specific roles. Each permissioned function has its own corresponding role. +Vault management is split into function-specific roles. Each permissioned function has its own corresponding role. This means roles can be combined all to one address, each distributed to separate addresses or any combination in between @@ -141,7 +141,7 @@ This means roles can be combined all to one address, each distributed to separat Vault functions that are permissioned will be callable by accounts that hold specific roles. These are: -- `ADD_STRATEGY_MANAGER`: role than can add strategies to the vault. +- `ADD_STRATEGY_MANAGER`: role that can add strategies to the vault. - `REVOKE_STRATEGY_MANAGER`: role that can remove strategies from the vault. - `FORCE_REVOKE_MANAGER`: role that can force remove a strategy causing a loss. - `ACCOUNTANT_MANAGER`: role that can set the accountant that assesses fees. @@ -153,13 +153,13 @@ These are: - `MINIMUM_IDLE_MANAGER`: role that sets the minimum total idle the vault should keep. - `PROFIT_UNLOCK_MANAGER`: role that sets the profit_max_unlock_time. - `DEBT_PURCHASER`: can purchase bad debt from the vault. -- `EMERGENCY_MANAGER`: role that can shutdown vault in an emergency. +- `EMERGENCY_MANAGER`: role that can shut down vault in an emergency. Every role can be filled by an EOA, multi-sig or other smart contracts. Each role can be filled by several accounts. The account that manages roles is a single account, set in `role_manager`. -This role_manager can be an EOA, a multi-sig or a Governance Module that relays calls. +This `role_manager` can be an EOA, a multi-sig or a Governance Module that relays calls. ### Strategy Management This responsibility is taken by callers with `ADD_STRATEGY_MANAGER`, `REVOKE_STRATEGY_MANAGER` and `FORCE_REVOKE_MANAGER` roles @@ -180,12 +180,12 @@ The contract is not needed for the vault to function but are recommended for opt #### Reporting profits The `REPORTING_MANAGER` is in charge of calling process_report() for each strategy in the vault according to its own timeline -This call will do the necessary accounting and profit locking for the individual strategy as well as charging fees +This call will do the necessary accounting and profit locking for the individual strategy as well as charge fees ### Debt Management -This responsibility is taken by callers with DEBT_MANAGER role +This responsibility is taken by callers with `DEBT_MANAGER` role -This role can increase or decrease strategies specific debt. +This role can increase or decrease strategies-specific debt. The vault sends and receives funds to/from strategies. The function updateDebt(strategy, target_debt) will set the current_debt of the strategy to target_debt (if possible) @@ -225,27 +225,27 @@ The `QUEUE_MANAGER` has the option to set a custom default_queue if desired. The All strategies in the default queue must have been previously added to the vault. #### Buying Debt -The `DEBT_PURCHASER` role can buy debt from the vault in return for the equal amount of `asset`. +The `DEBT_PURCHASER` role can buy debt from the vault in return for an equal amount of `asset`. -This should only ever be used in the case where governance wants to purchase a set amount of bade debt from the vault in order to not report a loss. +This should only ever be used in the case where governance wants to purchase a set amount of bad debt from the vault in order to not report a loss. It still relies on convertToShares() so will only be viable if the conversion does not reflect and large negative realized loss from the strategy. #### Shutting down the vault -In an emergency the `EMERGENCY_MANAGER` can shutdown the vault +In an emergency the `EMERGENCY_MANAGER` can shut down the vault -This will also give the `EMERGENCY_MANAGER` the `DEBT_MANAGER` roles as well so funds can start to be returned from the strategies +This will also give the `EMERGENCY_MANAGER` and the `DEBT_MANAGER` roles as well so funds can start to be returned from the strategies ## Strategy Minimum API Strategies are completely independent smart contracts that can be implemented following the proposed template or in any other way. In any case, to be compatible with the vault, they need to implement the following functions, which are a subset of ERC4626 vaults: - `asset()`: view returning underlying asset -- `totalAssets()`: view returning current amount of assets. It can include rewards valued in `asset` ¡ +- `totalAssets()`: view returning the current amount of assets. It can include rewards valued in `asset` ¡ - `maxDeposit(address)`: view returning the amount max that the strategy can take safely - `deposit(assets, receiver)`: deposits `assets` amount of tokens into the strategy. it can be restricted to vault only or be open -- `maxWithdraw(address)`: view returning how many asset can the vault take from the vault at any given point in time +- `maxWithdraw(address)`: view returning how many assets can the vault take from the vault at any given point in time - `withdraw(assets, receiver, owner)`: withdraws `assets` amount of tokens from the strategy - `redeem(shares, receiver, owner)`: redeems `shares` of the strategy for the underlying asset. - `balanceOf(address)`: return the number of shares of the strategy that the address has @@ -264,12 +264,12 @@ The most important implication is that `withdraw` and `redeem` functions as pres 2. `strategies`: This is an array of strategies to use as the withdrawal queue instead of the default queue. ### Shutdown mode -In the case the current roles stop fulfilling their responsibilities or something else happens, the EMERGENCY_MANAGER can shutdown the vault. +In the case the current roles stop fulfilling their responsibilities or something else happens, the EMERGENCY_MANAGER can shut down the vault. The shutdown mode should be the last option in an emergency as it is irreversible. ### Deposits -`_Light emergency_`: Deposits can be paused by setting depositLimit to 0 +`_Light emergency_`: Deposits can be paused by setting `depositLimit` to 0 `_Shutdown mode_`: Deposits are not allowed @@ -285,13 +285,13 @@ Shutdown mode does not affect accounting `_Shutdown mode_`: All strategies maxDebt is set to 0. Strategies will return funds as soon as they can. ### Relevant emergency -In the case the current roles stop fulfilling their responsibilities or something else happens, the `EMERGENCY_MANAGER` can shutdown the vault. +In case the current roles stop fulfilling their responsibilities or something else happens, the `EMERGENCY_MANAGER` can shut down the vault. The shutdown mode should be the last option in an emergency as it is irreversible. During shutdown mode, the vault will try to get funds back from every strategy as soon as possible. -No strategies can be added during shutdown +No strategies can be added during the shutdown Any relevant role will start pointing to the `EMERGENCY_MANAGER` in case new permissioned allowed actions need to be taken. @@ -301,14 +301,14 @@ Any relevant role will start pointing to the `EMERGENCY_MANAGER` in case new per ## Overview The Yearn V3 "Tokenized Strategy" goal is to make it as easy as possible for any person or protocol to create and deploy their own ERC-4626 compliant single strategy vault. It uses an immutable proxy pattern to outsource all of the standardized 4626 and other vault logic to one implementation contract that all Strategies deployed on a specific chain use through delegatecall. -This makes the strategy specific contract as simple and specific to that yield generating task as possible and allows for anyone to simply plug their version into a permissionless, secure and optimized 4626 compliant base that handles all risky and complicated code. +This makes the strategy-specific contract as simple and specific to that yield-generating task as possible and allows for anyone to simply plug their version into a permissionless, secure and optimized 4626 compliant base that handles all risky and complicated code. ### Definitions - Asset: Any ERC20-compliant token - Shares: ERC20-compliant token that tracks Asset balance in the strategy for every distributor. - Strategy: ERC4626 compliant smart contract that receives Assets from Depositors (vault or otherwise) to deposit in any external protocol to generate yield. -- Tokenized Strategy: The implementation contract that all strategies delegateCall to for the standard ERC4626 and profit locking functions. +- Tokenized Strategy: The implementation contract that all strategies `delegateCall` to for the standard ERC4626 and profit locking functions. - BaseTokenizedStrategy: The abstract contract that a strategy should inherit from that handles all communication with the Tokenized Strategy contract. - Strategist: The developer of a specific strategy. - Depositor: Account that holds Shares @@ -318,7 +318,7 @@ This makes the strategy specific contract as simple and specific to that yield g - Factory: The factory that all meta vaults of a specific API version are cloned from that also controls the protocol fee amount and recipient. ## Storage -In order to standardize all high risk and complex logic associated with ERC4626, ERC20 and profit locking, all core logic has been moved to the 'TokenizedStrategy.sol' and is used by each strategy through a fallback function that delegatecall's this contract to do all necessary checks, logic and storage updates for the strategy. +In order to standardize all high-risk and complex logic associated with ERC4626, ERC20 and profit locking, all core logic has been moved to the 'TokenizedStrategy.sol' and is used by each strategy through a fallback function that delegatecall's this contract to do all necessary checks, logic and storage updates for the strategy. The TokenizedStrategy will only need to be deployed once on each chain and can then be used by an unlimited number of strategies. Allowing the BaseTokenizedStrategy.sol to be much smaller, simpler and cheaper to deploy. @@ -335,7 +335,7 @@ The base tokenized strategy is a simple abstract contract to be inherited by the ### Modifiers `onlySelf`: This modifier is placed on any callback functions for the TokenizedStrategy to call during deposits, withdraws, reports and tends. The modifier should revert if msg.sender is not equal to itself. In order for a call to be forwarded to the TokenizedStrategy it must not be defined in the Strategy and hit the fallback function which will delegatecall the TokenizedStrategy. If within that call, the TokenizedStrategy makes an external static call back to the BaseTokenizedStrategy the msg.sender of that call will be the original caller, which should be the Strategy itself. -`OnlyManagement`: Should be placed on function that only the Strategies specific management address can call. This uses the isManagement(address) function defined in TokenizedStrategy by sending the original msg.sender address. +`OnlyManagement`: Should be placed on functions that only the Strategies specific management address can call. This uses the isManagement(address) function defined in TokenizedStrategy by sending the original msg.sender address. `onlyKeepers`: Should be placed on functions that only the Strategies specific management or keeper can call. This uses the isManagementOrKeeper(address) defined in TokenizedStrategy sending the original msg.sender address. @@ -422,12 +422,12 @@ new_profit_unlocking_rate = (locked_profit + new_profit) / new_locking_period Losses will be offset by locked profit, if possible. -Issue of new shares due to fees will also unlock profit so that PPS does not go down. +The issue of new shares due to fees will also unlock profit so that PPS does not go down. Both of this offsets will prevent front running (as the profit was already earned and was not distributed yet) ### Strategy Management -Strategy management is held by the 'management' address that can be updated by the current 'managment'. Changing 'management' is a two step process, so first the current management will have to set 'pendingManagement' then that pending management will need to accept the role. +Strategy management is held by the 'management' address that can be updated by the current 'managment'. Changing 'management' is a two-step process, so first the current management will have to set 'pendingManagement' then that pending management will need to accept the role. Management has the ability to set all the configurable variables for their specific Strategy. @@ -463,11 +463,11 @@ Strategy Shares are ERC4626 compliant. ## Emergency Operation There is default emergency functions built in. First of which is `shutdownStrategy`. This can only ever be called by the management address and is non-reversible. -Once this is called it will stop any further deposit or mints but will have no effect on any other functionality including withdraw, redeem, report and tend. This is to all the management to continue potentially recording profits or losses and users to withdraw even post shutdown. +Once this is called it will stop any further deposit or mints but will have no effect on any other functionality including withdraw, redeem, report and tend. This is to all the management to continue potentially recording profits or losses and users to withdraw even post shut down. This can be used in an emergency or simply to retire a vault. -Once a strategy is shutdown management can also call `emergencyWithdraw(amount)`. Which will tell the strategy to withdraw a specified `amount` from the yield source and keep it as idle in the vault. This function will also do any needed updates to totalDebt and totalIdle, based on amounts withdrawn to assure withdraws continue to function properly. +Once a strategy is shutdown management can also call `emergencyWithdraw(amount)`. Which will tell the strategy to withdraw a specified `amount` from the yield source and keep it as idle in the vault. This function will also do any needed updates to `totalDebt` and `totalIdle`, based on amounts withdrawn to assure withdraws continue to function properly. All other emergency functionality is left up to the individual strategist. @@ -489,7 +489,7 @@ The Strategy does not have a preference on any of the dimensions that should be - *Risk*: Strategy developers can deploy funds into any opportunity they desire no matter the expected risks or returns. - *Automation*: all the required actions to maintain the vault can be called by bots or manually, depending on periphery implementation -The compromises will come with the specific yield generating opportunity and parameters used by the strategies management. +The compromises will come with the specific yield-generating opportunity and parameters used by the strategies management. This allows different players to deploy their own version and implement their own constraints (or not use any at all) @@ -508,7 +508,7 @@ Strategists should be able to use a pre-built "Strategy Mix" that will contain t *_deployFunds(uint256 _amount)*: This function is called after every deposit or mint. Its only job is to deposit up to the '_amount' of 'asset'. -*_freeFunds(uint256 _amount)*: This function is called during every withdraw or redeem and should attempt to simply withdraw the '_amount' of 'asset'. Any difference between _amount and whats actually withdrawn will be counted as a loss +*_freeFunds(uint256 _amount)*: This function is called during every withdrawal or redemption and should attempt to simply withdraw the '_amount' of 'asset'. Any difference between _amount and whats actually withdrawn will be counted as a loss *_harvestandReport()*: This function is used during a report and should accrue all rewards and return the total amount of 'asset' the strategy currently has in its control. @@ -531,7 +531,7 @@ When deploying a new Strategy, it requires the following parameters: - asset: address of the ERC20 token that can be deposited in the strategy - name: name of Shares as described in ERC20 -All other parameters will default to generic values and can be adjusted post deployment by the deployer if desired. +All other parameters will default to generic values and can be adjusted post-deployment by the deployer if desired. # Read More - https://medium.com/iearn/yearnv3-motivation-and-design-107840cb4844 - https://medium.com/iearn/yearn-vaults-v3-36ce7c468ca0 From ab2d8aa9baecd9e1e8ccad11d20cf0c69c123501 Mon Sep 17 00:00:00 2001 From: Marco Guaspari Worms Date: Wed, 26 Jul 2023 15:41:10 -0300 Subject: [PATCH 34/54] Update v3.md --- docs/getting-started/products/yvaults/v3.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/products/yvaults/v3.md b/docs/getting-started/products/yvaults/v3.md index 721b9558b4..653de5b7da 100644 --- a/docs/getting-started/products/yvaults/v3.md +++ b/docs/getting-started/products/yvaults/v3.md @@ -1,4 +1,4 @@ -# Version 3 +# Vaults Version 3 Version 3 yVaults iterates on Version 2 by increasing robustness and developing Yearn’s path towards further decentralization, while keeping the same proven product (yield-bearing tokens) that abstract builders and users from the hard work of yield farming. Version 3 will both be able to have the same functionality as Version 2, but with many more added benefits and improvements to continue to grow the Yearn ecosystem. V3 also sees the introduction of "Tokenized Strategies". In V3 the strategies are now capable of being standalone 4626 vaults themselves. These single-strategy vaults can be used as stand-alone vaults or due to the 4626 standard easily added as a strategy to any of the multi-strategy "Meta Vaults". From 3f444777191ec5225b71599df72b6eff3867e7c9 Mon Sep 17 00:00:00 2001 From: Marco Guaspari Worms Date: Wed, 26 Jul 2023 15:46:02 -0300 Subject: [PATCH 35/54] Update overview.md --- docs/getting-started/products/yvaults/overview.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/getting-started/products/yvaults/overview.md b/docs/getting-started/products/yvaults/overview.md index 0198c72b9d..08c6720ba0 100644 --- a/docs/getting-started/products/yvaults/overview.md +++ b/docs/getting-started/products/yvaults/overview.md @@ -31,3 +31,7 @@ On the [yearn.finance](https://yearn.finance/) user interface, yield is displaye - **Strategist and Guardian are the new Controllers:** The Controller concept is not available in V2 yVaults and has been replaced by a Guardian and the Strategy creator \(strategist\). These 2 actors oversee strategy performance and are empowered to take action to improve capital management or act on critical situations. - **Automated vault housekeeping \(Keep3r network\):** `harvest()` and `earn()` calls are now automated through the Keep3r bots network. These 2 function calls are used to purchase new underlying collateral by selling the earned tokens while moving the profits back to the vault and later into strategies. The keep3r network takes the heavy lifting of doing these calls and running with the gas costs in exchange for keep3r tokens. This approach unloads humans from these housekeeping tasks. - **No Withdrawal Fee**: The one-time fee charged on balance upon withdrawal has been turned off for all vaults and only existed in the v1 iteration. + +## v3 yVaults + +The newest version of yVaults is EIP-4626 compatible and allows for tokenized strategies, read more: https://docs.yearn.finance/getting-started/products/yvaults/v3 From f14debd1e5223153fec91913c51fcd2bb2b8384c Mon Sep 17 00:00:00 2001 From: Marco Guaspari Worms Date: Wed, 26 Jul 2023 16:03:23 -0300 Subject: [PATCH 36/54] test formula --- docs/getting-started/products/yvaults/v3.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/getting-started/products/yvaults/v3.md b/docs/getting-started/products/yvaults/v3.md index 653de5b7da..13955b5d12 100644 --- a/docs/getting-started/products/yvaults/v3.md +++ b/docs/getting-started/products/yvaults/v3.md @@ -122,9 +122,8 @@ There is also an optional protocol_fee that can be charged based on the configur Profit from different process_report calls will accumulate in a buffer. This buffer will be linearly unlocked over the locking period seconds at profit_distribution_rate. Profits will be locked for a max period of time of profit_max_unlock_time seconds and will be gradually distributed. To avoid spending too much gas for profit unlock, the amount of time a profit will be locked is a weighted average between the new profit and the previous profit. - -`new_locking_period = locked_profit * pending_time_to_unlock + new_profit * PROFIT_MAX_UNLOCK_TIME / (locked_profit + new_profit)` -`new_profit_distribution_rate = (locked_profit + new_profit) / new_locking_period` +$new_locking_period = locked_profit * pending_time_to_unlock + new_profit * PROFIT_MAX_UNLOCK_TIME / (locked_profit + new_profit)$ +$new_profit_distribution_rate = (locked_profit + new_profit) / new_locking_period$ Losses will be offset by locked profit, if possible. From 4dfcaa7fb98ca92e100c3ee1caa9b51f6aa9daba Mon Sep 17 00:00:00 2001 From: Marco Guaspari Worms Date: Wed, 26 Jul 2023 19:11:30 -0300 Subject: [PATCH 37/54] fix math formula --- docs/getting-started/products/yvaults/v3.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/getting-started/products/yvaults/v3.md b/docs/getting-started/products/yvaults/v3.md index 13955b5d12..f1a58383c1 100644 --- a/docs/getting-started/products/yvaults/v3.md +++ b/docs/getting-started/products/yvaults/v3.md @@ -122,8 +122,10 @@ There is also an optional protocol_fee that can be charged based on the configur Profit from different process_report calls will accumulate in a buffer. This buffer will be linearly unlocked over the locking period seconds at profit_distribution_rate. Profits will be locked for a max period of time of profit_max_unlock_time seconds and will be gradually distributed. To avoid spending too much gas for profit unlock, the amount of time a profit will be locked is a weighted average between the new profit and the previous profit. -$new_locking_period = locked_profit * pending_time_to_unlock + new_profit * PROFIT_MAX_UNLOCK_TIME / (locked_profit + new_profit)$ -$new_profit_distribution_rate = (locked_profit + new_profit) / new_locking_period$ + +`new_locking_period = locked_profit * pending_time_to_unlock + new_profit * PROFIT_MAX_UNLOCK_TIME / (locked_profit + new_profit)` + +`new_profit_distribution_rate = (locked_profit + new_profit) / new_locking_period` Losses will be offset by locked profit, if possible. From 000195ed4c26b642bb3cd7009922a096276edc60 Mon Sep 17 00:00:00 2001 From: Marco Guaspari Worms Date: Wed, 26 Jul 2023 19:19:04 -0300 Subject: [PATCH 38/54] apply standard style --- docs/getting-started/products/yvaults/v3.md | 72 ++++++++++----------- 1 file changed, 36 insertions(+), 36 deletions(-) diff --git a/docs/getting-started/products/yvaults/v3.md b/docs/getting-started/products/yvaults/v3.md index f1a58383c1..5fe71f0394 100644 --- a/docs/getting-started/products/yvaults/v3.md +++ b/docs/getting-started/products/yvaults/v3.md @@ -40,10 +40,10 @@ The Vault code has been designed as a non-opinionated system to distribute funds Depositors receive shares (aka vaults tokens) proportional to their deposit amount. Vault tokens are yield-bearing and can be redeemed at any time to get back deposit plus any yield generated. The Vault does not have a preference on any of the dimensions that should be considered when operating a vault: -- *Decentralization*: Roles can be filled by any address (e.g. EOA, smart contract, multi-sig). -- *Liquidity*: Vault can have 0 liquidity or be fully liquid. It will depend on parameters and strategies added. -- *Security*: Vault managers can choose what strategies to add and how to do that process. -- *Automation*: All the required actions to maintain the vault can be called by bots or manually, depending on periphery implementation. +- **Decentralization**: Roles can be filled by any address (e.g. EOA, smart contract, multi-sig). +- **Liquidity**: Vault can have 0 liquidity or be fully liquid. It will depend on parameters and strategies added. +- **Security**: Vault managers can choose what strategies to add and how to do that process. +- **Automation**: All the required actions to maintain the vault can be called by bots or manually, depending on periphery implementation. The compromises will come with the implementation of periphery contracts fulfilling the roles in the Vault. @@ -58,13 +58,13 @@ Example periphery contracts: ``` ## Definitions -- Asset: Any ERC20-compliant token -- Shares: ERC20-compliant token that tracks Asset balance in the vault for every distributor. Named yv -- Depositor: Account that holds Shares -- Strategy: Smart contract that is used to deposit in Protocols to generate yield -- Vault: ERC4626 compliant Smart contract that receives Assets from Depositors to then distribute them among the different Strategies added to the vault, managing accounting and Assets distribution. -- Role: the different flags an Account can have in the Vault so that the Account can do certain specific actions. Can be fulfilled by a smart contract or an EOA. -- Accountant: smart contract that receives P&L reporting and returns shares and refunds to the strategy +- **Asset**: Any ERC20-compliant token +- **Shares**: ERC20-compliant token that tracks Asset balance in the vault for every distributor. Named yv +- **Depositor**: Account that holds Shares +- **Strategy**: Smart contract that is used to deposit in Protocols to generate yield +- **Vault**: ERC4626 compliant Smart contract that receives Assets from Depositors to then distribute them among the different Strategies added to the vault, managing accounting and Assets distribution. +- **Role**: the different flags an Account can have in the Vault so that the Account can do certain specific actions. Can be fulfilled by a smart contract or an EOA. +- **Accountant**: smart contract that receives P&L reporting and returns shares and refunds to the strategy ## Deployment We expect all the vaults available to be deployed from a Factory Contract, publicly available and callable. @@ -306,17 +306,17 @@ This makes the strategy-specific contract as simple and specific to that yield-g ### Definitions -- Asset: Any ERC20-compliant token -- Shares: ERC20-compliant token that tracks Asset balance in the strategy for every distributor. -- Strategy: ERC4626 compliant smart contract that receives Assets from Depositors (vault or otherwise) to deposit in any external protocol to generate yield. -- Tokenized Strategy: The implementation contract that all strategies `delegateCall` to for the standard ERC4626 and profit locking functions. -- BaseTokenizedStrategy: The abstract contract that a strategy should inherit from that handles all communication with the Tokenized Strategy contract. -- Strategist: The developer of a specific strategy. -- Depositor: Account that holds Shares -- Vault: Or "Meta Vault" is an ERC4626 compliant Smart contract that receives Assets from Depositors to then distribute them among the different Strategies added to the vault, managing accounting and Assets distribution. -- Management: The owner of the specific strategy that can set fees, profit unlocking time etc. -- Keeper: the address of a contract allowed to call report() and tend() on a strategy. -- Factory: The factory that all meta vaults of a specific API version are cloned from that also controls the protocol fee amount and recipient. +- **Asset**: Any ERC20-compliant token +- **Shares**: ERC20-compliant token that tracks Asset balance in the strategy for every distributor. +- **Strategy**: ERC4626 compliant smart contract that receives Assets from Depositors (vault or otherwise) to deposit in any external protocol to generate yield. +- **Tokenized Strategy**: The implementation contract that all strategies `delegateCall` to for the standard ERC4626 and profit locking functions. +- **BaseTokenizedStrategy**: The abstract contract that a strategy should inherit from that handles all communication with the Tokenized Strategy contract. +- **Strategist**: The developer of a specific strategy. +- **Depositor**: Account that holds Shares +- **Vault**: Or "Meta Vault" is an ERC4626 compliant Smart contract that receives Assets from Depositors to then distribute them among the different Strategies added to the vault, managing accounting and Assets distribution. +- **Management**: The owner of the specific strategy that can set fees, profit unlocking time etc. +- **Keepe**r: the address of a contract allowed to call report() and tend() on a strategy. +- **Factory**: The factory that all meta vaults of a specific API version are cloned from that also controls the protocol fee amount and recipient. ## Storage In order to standardize all high-risk and complex logic associated with ERC4626, ERC20 and profit locking, all core logic has been moved to the 'TokenizedStrategy.sol' and is used by each strategy through a fallback function that delegatecall's this contract to do all necessary checks, logic and storage updates for the strategy. @@ -484,11 +484,11 @@ The strategies code has been designed as a non-opinionated system to distribute The depositors receive shares of the strategy representing their relative share that can then be redeemed or used as yield-bearing tokens. The Strategy does not have a preference on any of the dimensions that should be considered when operating a strategy: -- *Decentralization*: management and keeper roles can be handled by EOA's, multi-sigs or any other form of governance. -- *Permissionlessness*: The strategies default to be fully permissioned. However, any strategist can easily implement white lists or any other method they desire. -- *Liquidity*: The strategy can be fully liquid at any time or only allow withdraws of idle funds, depending on the strategy implementation. -- *Risk*: Strategy developers can deploy funds into any opportunity they desire no matter the expected risks or returns. -- *Automation*: all the required actions to maintain the vault can be called by bots or manually, depending on periphery implementation +- **Decentralization**: management and keeper roles can be handled by EOA's, multi-sigs or any other form of governance. +- **Permissionlessness**: The strategies default to be fully permissioned. However, any strategist can easily implement white lists or any other method they desire. +- **Liquidity**: The strategy can be fully liquid at any time or only allow withdraws of idle funds, depending on the strategy implementation. +- **Risk**: Strategy developers can deploy funds into any opportunity they desire no matter the expected risks or returns. +- **Automation**: all the required actions to maintain the vault can be called by bots or manually, depending on periphery implementation The compromises will come with the specific yield-generating opportunity and parameters used by the strategies management. @@ -507,30 +507,30 @@ Strategists should be able to use a pre-built "Strategy Mix" that will contain t ### Needed to Override -*_deployFunds(uint256 _amount)*: This function is called after every deposit or mint. Its only job is to deposit up to the '_amount' of 'asset'. +`_deployFunds(uint256 _amount)`: This function is called after every deposit or mint. Its only job is to deposit up to the `_amount` of `asset`. -*_freeFunds(uint256 _amount)*: This function is called during every withdrawal or redemption and should attempt to simply withdraw the '_amount' of 'asset'. Any difference between _amount and whats actually withdrawn will be counted as a loss +`_freeFunds(uint256 _amount)`: This function is called during every withdrawal or redemption and should attempt to simply withdraw the '_amount' of 'asset'. Any difference between _amount and whats actually withdrawn will be counted as a loss -*_harvestandReport()*: This function is used during a report and should accrue all rewards and return the total amount of 'asset' the strategy currently has in its control. +`_harvestandReport()`: This function is used during a report and should accrue all rewards and return the total amount of 'asset' the strategy currently has in its control. ### Optional to Override While it can be possible to deploy a completely ERC-4626 compliant vault with just those three functions it does allow for further customization if the strategist desires. -*_tend* and *tendTrigger* can be overridden to signal to keepers the need for any sort of maintenance or reward selling between reports. +`_tend` and `tendTrigger` can be overridden to signal to keepers the need for any sort of maintenance or reward selling between reports. -*maxAvailableDeposit(address _owner)* can be overridden to implement any type of deposit limit. +`maxAvailableDeposit(address _owner)` can be overridden to implement any type of deposit limit. -*maxAvailableWithdraw(address _owner)* can be used to limit the amount that a user can withdraw at any given moment. +`maxAvailableWithdraw(address _owner)` can be used to limit the amount that a user can withdraw at any given moment. -*_emergencyWithdraw(uint256 _amount)* can be overridden to provide a manual method for management to pull funds from a yield source in an emergency when the vault is shutdown. +`_emergencyWithdraw(uint256 _amount)` can be overridden to provide a manual method for management to pull funds from a yield source in an emergency when the vault is shut down. ## Deployment All strategies deployed will have the address of the deployed 'TokenizedStrategy' set as a constant to be used as the address to forward all external calls to that are not defined in the Strategy. When deploying a new Strategy, it requires the following parameters: -- asset: address of the ERC20 token that can be deposited in the strategy -- name: name of Shares as described in ERC20 +- `asset`: address of the ERC20 token that can be deposited in the strategy +- `name`: name of Shares as described in ERC20 All other parameters will default to generic values and can be adjusted post-deployment by the deployer if desired. # Read More From 5fd5b16378e3eca84c06d9fbab0b46008a0d5778 Mon Sep 17 00:00:00 2001 From: Marco Guaspari Worms Date: Wed, 26 Jul 2023 19:20:05 -0300 Subject: [PATCH 39/54] typos --- docs/getting-started/products/yvaults/v3.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/getting-started/products/yvaults/v3.md b/docs/getting-started/products/yvaults/v3.md index 5fe71f0394..5f19fb95db 100644 --- a/docs/getting-started/products/yvaults/v3.md +++ b/docs/getting-started/products/yvaults/v3.md @@ -230,7 +230,7 @@ The `DEBT_PURCHASER` role can buy debt from the vault in return for an equal amo This should only ever be used in the case where governance wants to purchase a set amount of bad debt from the vault in order to not report a loss. -It still relies on convertToShares() so will only be viable if the conversion does not reflect and large negative realized loss from the strategy. +It still relies on `convertToShares()` so will only be viable if the conversion does not reflect and large negative realized loss from the strategy. #### Shutting down the vault @@ -323,7 +323,7 @@ In order to standardize all high-risk and complex logic associated with ERC4626, The TokenizedStrategy will only need to be deployed once on each chain and can then be used by an unlimited number of strategies. Allowing the BaseTokenizedStrategy.sol to be much smaller, simpler and cheaper to deploy. -Using delegate call the external TokenizedStrategyy will be able read and write to any and all of the strategies specific storage variables during all calls. This does open the strategy up to the possibility of storage collisions due to non-standardized storage calls and means extra precautions need to be taken when reading and writing to storage. +Using delegate call the external TokenizedStrategyy will be able to read and write to any and all of the strategies specific storage variables during all calls. This does open the strategy up to the possibility of storage collisions due to non-standardized storage calls and means extra precautions need to be taken when reading and writing to storage. In order to limit the strategists need to think about their storage variables all TokenizedStrategy specific variables are held within and controlled by the TokenizedStrategy. A `StrategyData` struct is held at a custom storage location that is high enough that no normal implementation should be worried about hitting. From 8adb40b5947d0afa341578d07b63f0887b5abce3 Mon Sep 17 00:00:00 2001 From: 0xBasically <0xBasic@yearn.finance> Date: Wed, 26 Jul 2023 19:03:13 -0400 Subject: [PATCH 40/54] fix: wording --- docs/getting-started/products/yvaults/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/products/yvaults/overview.md b/docs/getting-started/products/yvaults/overview.md index 08c6720ba0..c7935facd2 100644 --- a/docs/getting-started/products/yvaults/overview.md +++ b/docs/getting-started/products/yvaults/overview.md @@ -34,4 +34,4 @@ On the [yearn.finance](https://yearn.finance/) user interface, yield is displaye ## v3 yVaults -The newest version of yVaults is EIP-4626 compatible and allows for tokenized strategies, read more: https://docs.yearn.finance/getting-started/products/yvaults/v3 +The newest version of yVaults are EIP-4626 compatible and allow for tokenized strategies, read more: https://docs.yearn.finance/getting-started/products/yvaults/v3 From 631676ae5b17aaaf6f802f215ef0fe3b5d39f9bb Mon Sep 17 00:00:00 2001 From: 0xBasically <0xBasic@yearn.finance> Date: Fri, 28 Jul 2023 14:00:19 -0400 Subject: [PATCH 41/54] fix: update wording and rephrase info --- docs/getting-started/products/yvaults/v3.md | 115 +++++++++----------- 1 file changed, 49 insertions(+), 66 deletions(-) diff --git a/docs/getting-started/products/yvaults/v3.md b/docs/getting-started/products/yvaults/v3.md index 5f19fb95db..de75678e3a 100644 --- a/docs/getting-started/products/yvaults/v3.md +++ b/docs/getting-started/products/yvaults/v3.md @@ -1,25 +1,28 @@ # Vaults Version 3 Version 3 yVaults iterates on Version 2 by increasing robustness and developing Yearn’s path towards further decentralization, while keeping the same proven product (yield-bearing tokens) that abstract builders and users from the hard work of yield farming. Version 3 will both be able to have the same functionality as Version 2, but with many more added benefits and improvements to continue to grow the Yearn ecosystem. -V3 also sees the introduction of "Tokenized Strategies". In V3 the strategies are now capable of being standalone 4626 vaults themselves. These single-strategy vaults can be used as stand-alone vaults or due to the 4626 standard easily added as a strategy to any of the multi-strategy "Meta Vaults". +V3 also sees the introduction of "Tokenized Strategies". In V3 the strategies are now capable of being standalone 4626 vaults themselves. These single-strategy vaults can be used as stand-alone vaults or as a function of the 4626 standard easily added as a strategy to any of the multi-strategy "Meta Vaults". Version 3 yVaults improves on Version 2 by: - Increasing vault modularity, allowing for smaller and safer pieces of code. - Simplify strategy creation, empowering strategists and reducing the chance for errors. - More strategy functionality by implementing the Tokenized Strategy. -- All ERC-4626 implementations for easy integrations. +- ERC-4626 compatible for easy integrations. - Decreased gas costs to report profits and update debts. - Adding new products like ySwaps which increases swap efficiency and yJuniorTranches which allows for different risk profiles. -## Smart Modules +## Modules +Extensible code that can be attached to a yVault to extend functionality over and beyond core base logic. + +### Smart Modules Smart Modules implement core vault logic that will be iterated until they can be made immutable. If any Smart Module fails, the vault can live without them just enough to return funds to depositors. **When Version 3 launches, the Smart Modules will replicate Version 2 vault behavior.** -- **Debt Allocator**: Can efficiently allocate debt to different strategies added to a meta vault to the best yield opportunities. -- **Accountant**: Handles changing fees for vault operations. +- **Debt Allocator**: Can efficiently allocate debt to different strategies. Added to a Meta Vault for the best yield opportunities. +- **Accountant**: Handles changing fees for vault operations. -## Periphery Contracts -Periphery contracts are a separate layer of optional contracts to use with vaults and strategies. They are not required but they facilitate building around yVaults. +### Periphery Modules +Periphery Modules are a separate layer of optional contracts to use with vaults and strategies. They are not required but facilitate building around yVaults. - **Router**: Wrapper that handles deposits and withdrawals to/from all vaults and strategies. - **Yearn Lens**: Information aggregator for off-chain apps. @@ -28,110 +31,90 @@ Periphery contracts are a separate layer of optional contracts to use with vault - **Registry**: Handles adding and tracking strategies and vaults. - **HealthCheck**: Guardrail vault operations so that profit & loss reporting is always under acceptable values. - **Swappers**: Pre-built contracts for strategies to inherit to easily implement their desired swap logic. -- **APR Oracles**: Retrieve the expected current APY on chain for different strategies to properly allocate debt. +- **APR Oracles**: Retrieve the expected current APY on-chain for different strategies to properly allocate debt. - And any others you can come up with! # Version 3 yVault Specification ## Overview -The Vault code has been designed as a non-opinionated system to distribute funds of depositors into different opportunities (aka Strategies) and manage accounting in a robust way. That's all. +The Vault code has been designed as a non-opinionated system to distribute funds of depositors into different opportunities (aka Strategies) and robustly manage accounting. -Depositors receive shares (aka vaults tokens) proportional to their deposit amount. Vault tokens are yield-bearing and can be redeemed at any time to get back deposit plus any yield generated. +Depositors receive shares (aka vaults tokens) proportional to their deposited amount. Vault tokens are yield-bearing and can be redeemed, to get back the initial deposit plus or minus any yield or losses realized by the vault. -The Vault does not have a preference on any of the dimensions that should be considered when operating a vault: +Vaults do not have a preference on any of the dimensions that can be considered when creating and operating them: - **Decentralization**: Roles can be filled by any address (e.g. EOA, smart contract, multi-sig). -- **Liquidity**: Vault can have 0 liquidity or be fully liquid. It will depend on parameters and strategies added. -- **Security**: Vault managers can choose what strategies to add and how to do that process. -- **Automation**: All the required actions to maintain the vault can be called by bots or manually, depending on periphery implementation. +- **Liquidity**: the Vault can have 0 liquidity or be fully liquid. It will depend on the parameters and strategies added. +- **Security**: Vault managers can choose which strategies to add. +- **Automation**: All the required actions to maintain the Vault can be called by bots or manually, depending on periphery implementation. -The compromises will come with the implementation of periphery contracts fulfilling the roles in the Vault. - -This allows different players to deploy their own version and implement their own periphery contracts (or not use any at all) +Trade-offs will come with the implementation of Periphery Modules fulfilling different roles in the Vault. This allows different Vault creators to deploy their own versions and implement custom Periphery Modules (or not use any at all). ``` -Example periphery contracts: -- Emergency module: it receives deposits of Vault Shares and allows the contract to call the shutdown function after a certain % of total Vault Shares have been deposited -- Debt Allocator: a smart contract that incentivizes APY / debt allocation optimization by rewarding the best debt allocation (see [yStarkDebtAllocator](https://github.com/jmonteer/ystarkdebtallocator)) -- Strategy Staking Module: a smart contract that allows players to sponsor specific strategies (so that they are added to the vault) by staking their YFI, making money if they do well and losing money if they don't -- ... +Examples of Periphery Modules: +- Emergency Module: Receives deposits of Vault Shares and allows the contract to call the shutdown function after a certain % of total Vault Shares have been deposited. +- Debt Allocator: Module which incentivizes APY / debt allocation optimization by rewarding the best debt allocator (see [yStarkDebtAllocator](https://github.com/jmonteer/ystarkdebtallocator)). +- Strategy Staking Module: Module allows people to sponsor specific strategies (so that they are added to the vault) by staking their YFI, making money if they do well and losing money if they don't. ``` ## Definitions -- **Asset**: Any ERC20-compliant token -- **Shares**: ERC20-compliant token that tracks Asset balance in the vault for every distributor. Named yv -- **Depositor**: Account that holds Shares -- **Strategy**: Smart contract that is used to deposit in Protocols to generate yield -- **Vault**: ERC4626 compliant Smart contract that receives Assets from Depositors to then distribute them among the different Strategies added to the vault, managing accounting and Assets distribution. -- **Role**: the different flags an Account can have in the Vault so that the Account can do certain specific actions. Can be fulfilled by a smart contract or an EOA. -- **Accountant**: smart contract that receives P&L reporting and returns shares and refunds to the strategy +- **Account**: Any blockchain address for the network the vault is deployed on. +- **Asset**: Any ERC20-compliant token. +- **Shares**: ERC20-compliant token that tracks Asset balance in the vault for every distributor. Named yv. +- **Depositor**: Account that holds Shares. +- **Strategy**: Smart contract that is used to deposit in protocols to generate yield. +- **Vault**: ERC4626 compliant smart contract which receives Assets from Depositors to then distribute them among the different Strategies added to the Vault, managing accounting and Assets distribution. +- **Role**: Different flags an Account can have in the Vault so that the Account can do certain specific actions. Can be fulfilled by a smart contract or an EOA. +- **Accountant**: Smart contract which receives P&L reporting and returns shares/refunds to the strategy. ## Deployment -We expect all the vaults available to be deployed from a Factory Contract, publicly available and callable. - -Players deploying "branded" vaults (e.g. Yearn) will use a separate registry to allow permissioned endorsement of vaults for their product +We expect all the vaults available to be deployed from a Factory Contract, publicly available and callable. People deploying "branded" vaults (e.g. Yearn) will use a separate registry to allow permissioned endorsement of vaults for their product. -When deploying a new vault, it requires the following parameters: -- `asset`: address of the ERC20 token that can be deposited in the vault -- `name`: name of Shares as described in ERC20 -- `symbol`: symbol of Shares ERC20 -- `role_manager`: account that can assign and revoke Roles -- `profit_max_unlock_time`: max amount of time profit will be locked before being distributed +When deploying a new Vault, the following parameters are required: +- `asset`: Address of the ERC20 token that can be deposited into the vault +- `name`: Name of Shares as described in ERC20 +- `symbol`: Symbol of Shares ERC20 +- `role_manager`: Account that can assign and revoke Roles +- `profit_max_unlock_time`: Max amount of time profit will be locked before being distributed ## Normal Operation ### Deposits / Mints -Users can deposit asset tokens (ASSET) to receive yvTokens (SHARES). +Users can deposit asset tokens (Asset) to receive yvTokens (Shares). -Deposits are limited under `depositLimit` and shutdown parameters. Read below for details. +Deposits are limited under `depositLimit` and shutdown parameters. ### Withdrawals / Redeems -Users can redeem their shares at any point in time if there is liquidity available. - -Optionally, a user can specify a list of strategies to withdraw from. If a list of strategies is passed, the vault will try to withdraw from them. +Users can redeem their Shares at any point in time if there is liquidity available. Optionally, a user can specify a list of strategies to withdraw from. If a list of strategies is passed, the vault will try to withdraw from them. If a user-passed array is not defined, the redeem function will use the default_queue. -If a user passed array is not defined, the redeem function will use the default_queue. +To properly comply with the ERC-4626 standard and still allow losses, both withdraw and redeem have an additional optional parameter of 'maxLoss' that can be used. The default for 'maxLoss' is 0 (i.e. revert if any loss) for withdraws, and 10_000 (100%) for redeems. -In order to properly comply with the ERC-4626 standard and still allow losses, both withdraw and redeem have an additional optional parameter of 'maxLoss' that can be used. The default for 'maxLoss' is 0 (i.e. revert if any loss) for withdraws, and 10_000 (100%) for redeems. - -If not enough funds have been recovered to honor the full request within the maxLoss, the transaction will revert. +If not enough funds can be withdrawn to honor the full request within the maxLoss parameter given, the transaction will revert. ### Vault Shares -Vault shares are ERC20 transferable yield-bearing tokens. - -They are ERC4626 compliant. Please read [ERC4626 compliance](https://hackmd.io/cOFvpyR-SxWArfthhLJb5g#ERC4626-compliance) to understand the implications. +Vault shares are ERC20 transferable yield-bearing tokens and ERC4626 compliant. Please read [ERC-4626 Ethereum Improvement Proposals](https://eips.ethereum.org/EIPS/eip-4626) for more information about ERC4626. ### Accounting -The vault will evaluate profit and losses from the strategies. - -This is done by comparing the current debt of the strategy with the total assets the strategy is reporting to have. +The vault will evaluate profit and losses from the strategies. This is done by comparing the current debt of the strategy with the total assets the strategy is reporting to have. If `totalAssets` < `currentDebt`: the vault will record a loss If `totalAssets` > `currentDebt`: the vault will record a profit -Both loss and profit will impact strategy's debt, increasing the debt (current debt + profit) if there are profits, decreasing its debt (current debt - loss) if there are losses. +Both loss and profit will impact a strategy's debt. Debt will be increased (current debt + profit) if there are profits and decreased (current debt - loss) if there are losses. #### Fees -Fee assessment and distribution are handled by the Accountant module. - -It will report the amount of fees that need to be charged and the vault will issue shares for that amount of fees. - -There is also an optional protocol_fee that can be charged based on the configuration of the VaultFactory.vy +Fee assessment and distribution are handled by the Accountant Module. It will report the amount of fees that need to be charged and the vault will issue shares for that amount of fees. There is also an optional protocol_fee that can be charged based on the configuration of the VaultFactory.vy ### Profit distribution Profit from different process_report calls will accumulate in a buffer. This buffer will be linearly unlocked over the locking period seconds at profit_distribution_rate. -Profits will be locked for a max period of time of profit_max_unlock_time seconds and will be gradually distributed. To avoid spending too much gas for profit unlock, the amount of time a profit will be locked is a weighted average between the new profit and the previous profit. +Profits will be locked for a max time of profit_max_unlock_time seconds and will be gradually distributed. To avoid spending too much gas for profit unlock, the amount of time a profit will be locked is the weighted average between the new profit and the previous profit. `new_locking_period = locked_profit * pending_time_to_unlock + new_profit * PROFIT_MAX_UNLOCK_TIME / (locked_profit + new_profit)` `new_profit_distribution_rate = (locked_profit + new_profit) / new_locking_period` -Losses will be offset by locked profit, if possible. - -The issue of new shares due to fees will also unlock profit so that PPS does not go down. - -Both of these offsets will prevent front running (as the profit was already earned and was not distributed yet). +Losses will be offset by locked profit, if possible. The issuance of new shares due to fees will also unlock profit so that pricePerShare does not go down. Both of these offsets will prevent front running (as the profit was already earned and was not distributed yet). ## Vault Management Vault management is split into function-specific roles. Each permissioned function has its own corresponding role. @@ -173,7 +156,7 @@ Revoked strategies will return all debt and stop being eligible to receive more. Force revoking a strategy is only used in cases of a faulty strategy that cannot otherwise have its current_debt reduced to 0. Force revoking a strategy will result in a loss being reported by the vault. -#### Setting the periphery contracts +#### Setting the Periphery modules The accountant can each be set by the `ACCOUNTANT_MANAGER`. The contract is not needed for the vault to function but are recommended for optimal use. From 668eebecaa1abd763a10d61579a31c4d125dfd84 Mon Sep 17 00:00:00 2001 From: 0xBasically <0xBasic@yearn.finance> Date: Fri, 28 Jul 2023 14:11:10 -0400 Subject: [PATCH 42/54] fix: roles --- docs/getting-started/products/yvaults/v3.md | 30 ++++++++++----------- 1 file changed, 14 insertions(+), 16 deletions(-) diff --git a/docs/getting-started/products/yvaults/v3.md b/docs/getting-started/products/yvaults/v3.md index de75678e3a..19f22cb720 100644 --- a/docs/getting-started/products/yvaults/v3.md +++ b/docs/getting-started/products/yvaults/v3.md @@ -117,27 +117,25 @@ Profits will be locked for a max time of profit_max_unlock_time seconds and will Losses will be offset by locked profit, if possible. The issuance of new shares due to fees will also unlock profit so that pricePerShare does not go down. Both of these offsets will prevent front running (as the profit was already earned and was not distributed yet). ## Vault Management -Vault management is split into function-specific roles. Each permissioned function has its own corresponding role. - -This means roles can be combined all to one address, each distributed to separate addresses or any combination in between +Vault management is split into function-specific roles. Each permissioned function has its own corresponding role. This means roles can be combined all to one address, distributed to separate addresses, or any combination in between. ## Roles Vault functions that are permissioned will be callable by accounts that hold specific roles. These are: -- `ADD_STRATEGY_MANAGER`: role that can add strategies to the vault. -- `REVOKE_STRATEGY_MANAGER`: role that can remove strategies from the vault. -- `FORCE_REVOKE_MANAGER`: role that can force remove a strategy causing a loss. -- `ACCOUNTANT_MANAGER`: role that can set the accountant that assesses fees. -- `QUEUE_MANAGER`: role that can set the default withdrawal queue. -- `REPORTING_MANAGER`: role that calls report for strategies. -- `DEBT_MANAGER`: role that adds and removes debt from strategies. -- `MAX_DEBT_MANAGER`: role that can set the max debt for a strategy. -- `DEPOSIT_LIMIT_MANAGER`: role that sets deposit limit for the vault. -- `MINIMUM_IDLE_MANAGER`: role that sets the minimum total idle the vault should keep. -- `PROFIT_UNLOCK_MANAGER`: role that sets the profit_max_unlock_time. -- `DEBT_PURCHASER`: can purchase bad debt from the vault. -- `EMERGENCY_MANAGER`: role that can shut down vault in an emergency. +- `ADD_STRATEGY_MANAGER`: Role that adds strategies to the vault +- `REVOKE_STRATEGY_MANAGER`: Role that removes strategies from the vault +- `FORCE_REVOKE_MANAGER`: Role that can forcefully remove a strategy causing a loss +- `ACCOUNTANT_MANAGER`: Role that can set the Accountant which assesses fees +- `QUEUE_MANAGER`: Role that sets the default withdrawal queue +- `REPORTING_MANAGER`: Role that calls report for strategies +- `DEBT_MANAGER`: Role that adds and removes debt from strategies +- `MAX_DEBT_MANAGER`: Role that sets the max debt for a strategy +- `DEPOSIT_LIMIT_MANAGER`: Role that sets the deposit limit for the vault +- `MINIMUM_IDLE_MANAGER`: Role that sets the minimum_total_idle the vault should keep +- `PROFIT_UNLOCK_MANAGER`: Role that sets the profit_max_unlock_time +- `DEBT_PURCHASER`: Role that purchases bad debt from the vault +- `EMERGENCY_MANAGER`: Role that can shut down the vault in an emergency Every role can be filled by an EOA, multi-sig or other smart contracts. Each role can be filled by several accounts. From a62366d6ddd4429d9021784891264dcff6c71f0b Mon Sep 17 00:00:00 2001 From: 0xBasically <0xBasic@yearn.finance> Date: Fri, 28 Jul 2023 14:25:44 -0400 Subject: [PATCH 43/54] updates --- docs/getting-started/products/yvaults/v3.md | 44 +++++---------------- 1 file changed, 10 insertions(+), 34 deletions(-) diff --git a/docs/getting-started/products/yvaults/v3.md b/docs/getting-started/products/yvaults/v3.md index 19f22cb720..327899a0d6 100644 --- a/docs/getting-started/products/yvaults/v3.md +++ b/docs/getting-started/products/yvaults/v3.md @@ -137,59 +137,35 @@ These are: - `DEBT_PURCHASER`: Role that purchases bad debt from the vault - `EMERGENCY_MANAGER`: Role that can shut down the vault in an emergency -Every role can be filled by an EOA, multi-sig or other smart contracts. Each role can be filled by several accounts. - -The account that manages roles is a single account, set in `role_manager`. - -This `role_manager` can be an EOA, a multi-sig or a Governance Module that relays calls. +Every role can be filled by an EOA, multi-sig or other smart contracts. Each role can be filled by several accounts. The account that manages roles is a single account, set in `role_manager`. This `role_manager` can be an EOA, a multi-sig or a Governance Module that relays calls. ### Strategy Management -This responsibility is taken by callers with `ADD_STRATEGY_MANAGER`, `REVOKE_STRATEGY_MANAGER` and `FORCE_REVOKE_MANAGER` roles - -A vault can have strategies added, removed or forcefully removed - -Added strategies will be eligible to receive funds from the vault, when the max_debt is set to > 0 - -Revoked strategies will return all debt and stop being eligible to receive more. It can only be done when the strategy's current_debt is 0 - -Force revoking a strategy is only used in cases of a faulty strategy that cannot otherwise have its current_debt reduced to 0. Force revoking a strategy will result in a loss being reported by the vault. +This responsibility is taken by callers with `ADD_STRATEGY_MANAGER`, `REVOKE_STRATEGY_MANAGER` and `FORCE_REVOKE_MANAGER` roles. A vault can have strategies added, removed, or forcefully removed. Added strategies will be eligible to receive funds from the vault, when the max_debt is set to > 0. Revoked strategies will return all debt and stop being eligible to receive more. It can only be done when the strategy's current_debt is 0. Force revoking a strategy is only used in cases of a faulty strategy that cannot otherwise have its current_debt reduced to 0. Force revoking a strategy will result in a loss being reported by the vault. -#### Setting the Periphery modules -The accountant can each be set by the `ACCOUNTANT_MANAGER`. - -The contract is not needed for the vault to function but are recommended for optimal use. +#### Setting the Periphery Modules +The Accountant can be set by the `ACCOUNTANT_MANAGER`. The contract is not needed for the vault to function but is recommended for optimal use. #### Reporting profits -The `REPORTING_MANAGER` is in charge of calling process_report() for each strategy in the vault according to its own timeline - -This call will do the necessary accounting and profit locking for the individual strategy as well as charge fees +The `REPORTING_MANAGER` is in charge of calling process_report() for each strategy in the vault according to its own timeline. This call will do the necessary accounting and profit locking for the individual strategy as well as charge fees. ### Debt Management -This responsibility is taken by callers with `DEBT_MANAGER` role - -This role can increase or decrease strategies-specific debt. - -The vault sends and receives funds to/from strategies. The function updateDebt(strategy, target_debt) will set the current_debt of the strategy to target_debt (if possible) - -If the strategy currently has less debt than the target_debt, the vault will send funds to it. - -The vault checks that the `minimumTotalIdle` parameter is respected (i.e. there's at least a certain amount of funds in the vault). +This responsibility is taken by callers with the `DEBT_MANAGER` role. This role can increase or decrease strategy-specific debt. The function updateDebt(strategy, target_debt) will set the current_debt of the strategy to target_debt (if possible). If the strategy currently has less debt than the target_debt, the vault will send funds to it. -If the strategy has more debt than the max_debt, the vault will request the funds back. These funds may be locked in the strategy, which will result in the strategy returning less funds than requested by the vault. +The vault checks that the `minimumTotalIdle` parameter is respected (i.e. there's at least a certain amount of funds in the vault). If the strategy has more debt than the max_debt, the vault will request the funds back. These funds may be locked in the strategy, which will result in the strategy returning less funds than requested by the vault. -#### Setting maximum debt for a specific strategy +#### Setting Maximum Debt for a Specific Strategy The `MAX_DEBT_MANAGER` can set the maximum amount of tokens the vault will allow a strategy to owe at any moment in time. Stored in `strategies[strategy].max_debt` When a debt re-balance is triggered, the Vault will cap the new target debt to this number (max_debt) -#### Setting the deposit limit +#### Setting the Deposit Limit The `DEPOSIT_LIMIT_MANAGER` is in charge of setting the deposit_limit for the vault. On deployment deposit_limit defaults to 0 and will need to be increased to make the vault functional -#### Setting minimum idle funds +#### Setting Minimum Idle Funds The `MINIMUM_IDLE_MANAGER` can specify how many funds the vault should try to have reserved to serve withdrawal requests These funds will remain in the vault unless requested by a Depositor From 7d4dfab821f9412086e4d65f4d3d4dcd6ee18d65 Mon Sep 17 00:00:00 2001 From: 0xBasically <0xBasic@yearn.finance> Date: Fri, 28 Jul 2023 14:31:18 -0400 Subject: [PATCH 44/54] chore: update title caps --- docs/getting-started/products/yvaults/v3.md | 34 ++++++++++----------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/docs/getting-started/products/yvaults/v3.md b/docs/getting-started/products/yvaults/v3.md index 327899a0d6..1924afc5c1 100644 --- a/docs/getting-started/products/yvaults/v3.md +++ b/docs/getting-started/products/yvaults/v3.md @@ -105,7 +105,7 @@ Both loss and profit will impact a strategy's debt. Debt will be increased (curr #### Fees Fee assessment and distribution are handled by the Accountant Module. It will report the amount of fees that need to be charged and the vault will issue shares for that amount of fees. There is also an optional protocol_fee that can be charged based on the configuration of the VaultFactory.vy -### Profit distribution +### Profit Distribution Profit from different process_report calls will accumulate in a buffer. This buffer will be linearly unlocked over the locking period seconds at profit_distribution_rate. Profits will be locked for a max time of profit_max_unlock_time seconds and will be gradually distributed. To avoid spending too much gas for profit unlock, the amount of time a profit will be locked is the weighted average between the new profit and the previous profit. @@ -145,13 +145,13 @@ This responsibility is taken by callers with `ADD_STRATEGY_MANAGER`, `REVOKE_STR #### Setting the Periphery Modules The Accountant can be set by the `ACCOUNTANT_MANAGER`. The contract is not needed for the vault to function but is recommended for optimal use. -#### Reporting profits +#### Reporting Profits The `REPORTING_MANAGER` is in charge of calling process_report() for each strategy in the vault according to its own timeline. This call will do the necessary accounting and profit locking for the individual strategy as well as charge fees. ### Debt Management This responsibility is taken by callers with the `DEBT_MANAGER` role. This role can increase or decrease strategy-specific debt. The function updateDebt(strategy, target_debt) will set the current_debt of the strategy to target_debt (if possible). If the strategy currently has less debt than the target_debt, the vault will send funds to it. -The vault checks that the `minimumTotalIdle` parameter is respected (i.e. there's at least a certain amount of funds in the vault). If the strategy has more debt than the max_debt, the vault will request the funds back. These funds may be locked in the strategy, which will result in the strategy returning less funds than requested by the vault. +The vault checks that the `minimumTotalIdle` parameter is respected (i.e. there's at least a certain amount of funds in the vault). If the strategy has more debt than the max_debt, the vault will request the funds back. These funds may be locked in the strategy, which will result in the strategy returning less funds than requested by the vault. #### Setting Maximum Debt for a Specific Strategy The `MAX_DEBT_MANAGER` can set the maximum amount of tokens the vault will allow a strategy to owe at any moment in time. @@ -172,12 +172,12 @@ These funds will remain in the vault unless requested by a Depositor It is recommended that if no queue_manager is set some amount of funds should remain idle to service withdrawals -#### Setting the profit unlock period +#### Setting the Profit Unlock Period The `PROFIT_UNLOCK_MANAGER` is in charge of updating and setting the profit_max_unlock_time which controls how fast profits will unlock This can be customized based on the vault based on aspects such as number of strategies, TVL, expected returns etc. -#### Setting the default queue +#### Setting the Default Queue The `QUEUE_MANAGER` has the option to set a custom default_queue if desired. The vault will arrange the default queue automatically based only on the order that strategies were added to the vault. If a different order is desired the queue manager role can set a custom queue. All strategies in the default queue must have been previously added to the vault. @@ -190,7 +190,7 @@ This should only ever be used in the case where governance wants to purchase a s It still relies on `convertToShares()` so will only be viable if the conversion does not reflect and large negative realized loss from the strategy. -#### Shutting down the vault +#### Shutting Down the Vault In an emergency the `EMERGENCY_MANAGER` can shut down the vault This will also give the `EMERGENCY_MANAGER` and the `DEBT_MANAGER` roles as well so funds can start to be returned from the strategies @@ -213,7 +213,7 @@ In any case, to be compatible with the vault, they need to implement the followi This means that the vault can deposit into any ERC4626 vault but also that a non-compliant strategy can be implemented provided that these functions have been implemented (even in a non ERC4626 compliant way). -## ERC4626 compliance +## ERC4626 Compliance Vault Shares are ERC4626 compliant. The most important implication is that `withdraw` and `redeem` functions as presented in ERC4626, with the ability to add two additional non-standard options. @@ -221,7 +221,7 @@ The most important implication is that `withdraw` and `redeem` functions as pres 1. `max_loss`: The amount in basis points that the withdrawer will accept as a loss. I.E. 100 = 1% loss accepted. 2. `strategies`: This is an array of strategies to use as the withdrawal queue instead of the default queue. -### Shutdown mode +### Shutdown Mode In the case the current roles stop fulfilling their responsibilities or something else happens, the EMERGENCY_MANAGER can shut down the vault. The shutdown mode should be the last option in an emergency as it is irreversible. @@ -232,17 +232,17 @@ The shutdown mode should be the last option in an emergency as it is irreversibl `_Shutdown mode_`: Deposits are not allowed ### Withdrawals -Withdrawals can't be paused under any circumstance +Withdrawals can't be paused under any circumstance. ### Accounting -Shutdown mode does not affect accounting +Shutdown mode does not affect the accounting. -### Debt rebalance +### Debt Rebalancing `_Light emergency_`: Setting minimumTotalIdle to MAX_UINT256 will result in the vault requesting the debt back from strategies. This would stop new strategies from getting funded too, as the vault prioritizes minimumTotalIdle `_Shutdown mode_`: All strategies maxDebt is set to 0. Strategies will return funds as soon as they can. -### Relevant emergency +### Relevant Emergency In case the current roles stop fulfilling their responsibilities or something else happens, the `EMERGENCY_MANAGER` can shut down the vault. The shutdown mode should be the last option in an emergency as it is irreversible. @@ -370,7 +370,7 @@ There are two potential fees. Performance fees and protocol fees. Performance fe Protocol fees are configured by Yearn governance through the Factory and are taken as a percent of the performanceFees charged. I.E. profit = 100, performance fees = 20% protocol fees = 10%. Then total fees charged = 100 * .2 = 20 of which 10% is sent to the protocol fee recipient (2) and 90% (18) is sent the strategy specific `performanceFeeRecipient`. -### Profit distribution +### Profit Distribution Profit from report calls will accumulate in a buffer. This buffer will be linearly unlocked over the locking period seconds at profitUnlockingRate. Profits will be locked for a max period of time of profitMaxUnlockTime seconds and will be gradually distributed. To avoid spending too much gas for profit unlock, the amount of time a profit will be locked is a weighted average between the new profit and the previous profit. @@ -399,7 +399,7 @@ This allows the current management to set a new non-zero address to take over as #### Accepting Management This allows the current 'pendingManagement' to accept the ownership of the contract. -#### Setting the keeper +#### Setting the Keeper Setting the address that is also allowed to call report and tend functions. #### Setting Performance Fee @@ -407,15 +407,15 @@ Setting the percent in terms of basis points for the amount of profit to be char This has a minimum of 5% and a maximum of 50%. -#### Setting performance fee recipient +#### Setting Performance Fee Recipient Setting the non-zero address that will receive any shares issued as a result of the performance fee. -#### Setting the profit unlock period +#### Setting the Profit Unlock Period Sets the time in seconds that controls how fast profits will unlock. This can be customized based on the strategy. Based on aspects such as TVL, expected returns etc. -## ERC4626 compliance +## ERC4626 Compliance Strategy Shares are ERC4626 compliant. ## Emergency Operation From 04dcc7edc907491b9e4855ba19c029a94fe40b36 Mon Sep 17 00:00:00 2001 From: 0xBasically <0xBasic@yearn.finance> Date: Fri, 28 Jul 2023 15:13:39 -0400 Subject: [PATCH 45/54] updates and fixes --- docs/getting-started/products/yvaults/v3.md | 76 +++++++-------------- 1 file changed, 26 insertions(+), 50 deletions(-) diff --git a/docs/getting-started/products/yvaults/v3.md b/docs/getting-started/products/yvaults/v3.md index 1924afc5c1..a9a5e2ae80 100644 --- a/docs/getting-started/products/yvaults/v3.md +++ b/docs/getting-started/products/yvaults/v3.md @@ -18,7 +18,6 @@ Extensible code that can be attached to a yVault to extend functionality over an Smart Modules implement core vault logic that will be iterated until they can be made immutable. If any Smart Module fails, the vault can live without them just enough to return funds to depositors. **When Version 3 launches, the Smart Modules will replicate Version 2 vault behavior.** - **Debt Allocator**: Can efficiently allocate debt to different strategies. Added to a Meta Vault for the best yield opportunities. - - **Accountant**: Handles changing fees for vault operations. ### Periphery Modules @@ -38,9 +37,7 @@ Periphery Modules are a separate layer of optional contracts to use with vaults ## Overview -The Vault code has been designed as a non-opinionated system to distribute funds of depositors into different opportunities (aka Strategies) and robustly manage accounting. - -Depositors receive shares (aka vaults tokens) proportional to their deposited amount. Vault tokens are yield-bearing and can be redeemed, to get back the initial deposit plus or minus any yield or losses realized by the vault. +The Vault code has been designed as a non-opinionated system to distribute funds of depositors into different opportunities (aka Strategies) and robustly manage accounting. Depositors receive shares (aka vaults tokens) proportional to their deposited amount. Vault tokens are yield-bearing and can be redeemed, to get back the initial deposit plus or minus any yield or losses realized by the vault. Vaults do not have a preference on any of the dimensions that can be considered when creating and operating them: - **Decentralization**: Roles can be filled by any address (e.g. EOA, smart contract, multi-sig). @@ -119,7 +116,7 @@ Losses will be offset by locked profit, if possible. The issuance of new shares ## Vault Management Vault management is split into function-specific roles. Each permissioned function has its own corresponding role. This means roles can be combined all to one address, distributed to separate addresses, or any combination in between. -## Roles +### Roles Vault functions that are permissioned will be callable by accounts that hold specific roles. These are: @@ -142,7 +139,7 @@ Every role can be filled by an EOA, multi-sig or other smart contracts. Each rol ### Strategy Management This responsibility is taken by callers with `ADD_STRATEGY_MANAGER`, `REVOKE_STRATEGY_MANAGER` and `FORCE_REVOKE_MANAGER` roles. A vault can have strategies added, removed, or forcefully removed. Added strategies will be eligible to receive funds from the vault, when the max_debt is set to > 0. Revoked strategies will return all debt and stop being eligible to receive more. It can only be done when the strategy's current_debt is 0. Force revoking a strategy is only used in cases of a faulty strategy that cannot otherwise have its current_debt reduced to 0. Force revoking a strategy will result in a loss being reported by the vault. -#### Setting the Periphery Modules +#### Setting the Accountant Module The Accountant can be set by the `ACCOUNTANT_MANAGER`. The contract is not needed for the vault to function but is recommended for optimal use. #### Reporting Profits @@ -154,64 +151,43 @@ This responsibility is taken by callers with the `DEBT_MANAGER` role. This role The vault checks that the `minimumTotalIdle` parameter is respected (i.e. there's at least a certain amount of funds in the vault). If the strategy has more debt than the max_debt, the vault will request the funds back. These funds may be locked in the strategy, which will result in the strategy returning less funds than requested by the vault. #### Setting Maximum Debt for a Specific Strategy -The `MAX_DEBT_MANAGER` can set the maximum amount of tokens the vault will allow a strategy to owe at any moment in time. - -Stored in `strategies[strategy].max_debt` - -When a debt re-balance is triggered, the Vault will cap the new target debt to this number (max_debt) +The `MAX_DEBT_MANAGER` can set the maximum amount of tokens the vault will allow a strategy to owe at any moment in time. Stored in `strategies[strategy].max_debt`. When a debt re-balance is triggered, the Vault will cap the new target debt to this number (max_debt). #### Setting the Deposit Limit -The `DEPOSIT_LIMIT_MANAGER` is in charge of setting the deposit_limit for the vault. - -On deployment deposit_limit defaults to 0 and will need to be increased to make the vault functional +The `DEPOSIT_LIMIT_MANAGER` is in charge of setting the deposit_limit for the vault. On deployment deposit_limit defaults to 0 and will need to be increased to make the vault functional. #### Setting Minimum Idle Funds -The `MINIMUM_IDLE_MANAGER` can specify how many funds the vault should try to have reserved to serve withdrawal requests - -These funds will remain in the vault unless requested by a Depositor - -It is recommended that if no queue_manager is set some amount of funds should remain idle to service withdrawals +The `MINIMUM_IDLE_MANAGER` can specify how much funds the vault should try to have reserved to serve withdrawal requests. These funds will remain in the vault unless requested by a depositor. It is recommended that if no queue_manager is set, some amount of funds should remain idle to service withdrawals. #### Setting the Profit Unlock Period -The `PROFIT_UNLOCK_MANAGER` is in charge of updating and setting the profit_max_unlock_time which controls how fast profits will unlock - -This can be customized based on the vault based on aspects such as number of strategies, TVL, expected returns etc. +The `PROFIT_UNLOCK_MANAGER` is in charge of updating and setting the profit_max_unlock_time which controls how fast profits unlock. This can be customized based on aspects such as the number of strategies, total value locked, expected returns, etc. #### Setting the Default Queue -The `QUEUE_MANAGER` has the option to set a custom default_queue if desired. The vault will arrange the default queue automatically based only on the order that strategies were added to the vault. If a different order is desired the queue manager role can set a custom queue. - -All strategies in the default queue must have been previously added to the vault. +The `QUEUE_MANAGER` can set a custom default_queue if desired. The vault will arrange the default queue automatically based on the order in which strategies were added to the vault. If a different order is desired, the `QUEUE_MANAGER` can set a custom queue. All strategies in the default queue must have been previously added to the vault. #### Buying Debt -The `DEBT_PURCHASER` role can buy debt from the vault in return for an equal amount of `asset`. - -This should only ever be used in the case where governance wants to purchase a set amount of bad debt from the vault in order to not report a loss. - -It still relies on `convertToShares()` so will only be viable if the conversion does not reflect and large negative realized loss from the strategy. - +The `DEBT_PURCHASER` role can buy debt from the vault in return for an equal amount of `asset`. This should only ever be used in the case when governance wants to purchase a set amount of bad debt from the vault to not report a loss. It still relies on `convertToShares()` so will only be viable if the conversion does not reflect and large negative realized loss from the strategy. #### Shutting Down the Vault -In an emergency the `EMERGENCY_MANAGER` can shut down the vault - -This will also give the `EMERGENCY_MANAGER` and the `DEBT_MANAGER` roles as well so funds can start to be returned from the strategies +In an emergency, the `EMERGENCY_MANAGER` can shut down the vault. This will also give the `EMERGENCY_MANAGER` and the `DEBT_MANAGER` roles as well so funds can start to be returned from the strategies. ## Strategy Minimum API -Strategies are completely independent smart contracts that can be implemented following the proposed template or in any other way. - -In any case, to be compatible with the vault, they need to implement the following functions, which are a subset of ERC4626 vaults: -- `asset()`: view returning underlying asset -- `totalAssets()`: view returning the current amount of assets. It can include rewards valued in `asset` ¡ -- `maxDeposit(address)`: view returning the amount max that the strategy can take safely -- `deposit(assets, receiver)`: deposits `assets` amount of tokens into the strategy. it can be restricted to vault only or be open -- `maxWithdraw(address)`: view returning how many assets can the vault take from the vault at any given point in time -- `withdraw(assets, receiver, owner)`: withdraws `assets` amount of tokens from the strategy -- `redeem(shares, receiver, owner)`: redeems `shares` of the strategy for the underlying asset. -- `balanceOf(address)`: return the number of shares of the strategy that the address has -- `convertToAssets(shares: uint256)`: Converts `shares` into the corresponding amount of asset. -- `convertToShares(assets: uint256)`: Converts `assets` into the corresponding amount of shares. -- `previewWithdraw(assets: uint256)`: Converst `assets` into the corresponding amount of shares rounding up. - -This means that the vault can deposit into any ERC4626 vault but also that a non-compliant strategy can be implemented provided that these functions have been implemented (even in a non ERC4626 compliant way). +Strategies are completely independent smart contracts that can be implemented following the proposed template. + +To be compatible with the vault, they need to implement the following functions, which are a subset of ERC4626 vaults: +- `asset()`: View returning underlying asset +- `totalAssets()`: View returning the current amount of assets. It can include rewards valued in `asset` +- `maxDeposit(address)`: View returning the amount max that the strategy can take safely +- `deposit(assets, receiver)`: Deposits `assets` amount of tokens into the strategy. it can be restricted to vault only or be open +- `maxWithdraw(address)`: View returning how many assets can the vault take from the vault at any given point in time +- `withdraw(assets, receiver, owner)`: Withdraws `assets` amount of tokens from the strategy +- `redeem(shares, receiver, owner)`: Redeems `shares` of the strategy for the underlying asset +- `balanceOf(address)`: Return the number of shares of the strategy that the address has +- `convertToAssets(shares: uint256)`: Converts `shares` into the corresponding amount of asset +- `convertToShares(assets: uint256)`: Converts `assets` into the corresponding amount of shares +- `previewWithdraw(assets: uint256)`: Converts `assets` into the corresponding amount of shares rounding up + +This means that the vault can deposit into any ERC4626 vault but also that a non-compliant strategy can be implemented provided that these functions have been implemented (even if in a non-ERC4626 compliant way). ## ERC4626 Compliance Vault Shares are ERC4626 compliant. From 96545038167807a5608501b6711e54a911547ce6 Mon Sep 17 00:00:00 2001 From: 0xBasically <0xBasic@yearn.finance> Date: Fri, 28 Jul 2023 18:17:00 -0400 Subject: [PATCH 46/54] updates and fixes --- docs/getting-started/products/yvaults/v3.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/getting-started/products/yvaults/v3.md b/docs/getting-started/products/yvaults/v3.md index a9a5e2ae80..6ffd21ab1a 100644 --- a/docs/getting-started/products/yvaults/v3.md +++ b/docs/getting-started/products/yvaults/v3.md @@ -166,10 +166,10 @@ The `PROFIT_UNLOCK_MANAGER` is in charge of updating and setting the profit_max_ The `QUEUE_MANAGER` can set a custom default_queue if desired. The vault will arrange the default queue automatically based on the order in which strategies were added to the vault. If a different order is desired, the `QUEUE_MANAGER` can set a custom queue. All strategies in the default queue must have been previously added to the vault. #### Buying Debt -The `DEBT_PURCHASER` role can buy debt from the vault in return for an equal amount of `asset`. This should only ever be used in the case when governance wants to purchase a set amount of bad debt from the vault to not report a loss. It still relies on `convertToShares()` so will only be viable if the conversion does not reflect and large negative realized loss from the strategy. +The `DEBT_PURCHASER` role can buy debt from the vault in return for an equal amount of `asset`. This should only ever be used in the case when governance wants to purchase a set amount of bad debt from the vault to not report a loss. It still relies on `convertToShares()` so will only be viable if the conversion does not reflect a large negative realized loss from the strategy. #### Shutting Down the Vault -In an emergency, the `EMERGENCY_MANAGER` can shut down the vault. This will also give the `EMERGENCY_MANAGER` and the `DEBT_MANAGER` roles as well so funds can start to be returned from the strategies. +In an emergency, the `EMERGENCY_MANAGER` can shut down the vault. This will also give the `EMERGENCY_MANAGER` and the `DEBT_MANAGER` role as well so funds can start to be returned from the strategies. ## Strategy Minimum API Strategies are completely independent smart contracts that can be implemented following the proposed template. @@ -178,14 +178,14 @@ To be compatible with the vault, they need to implement the following functions, - `asset()`: View returning underlying asset - `totalAssets()`: View returning the current amount of assets. It can include rewards valued in `asset` - `maxDeposit(address)`: View returning the amount max that the strategy can take safely -- `deposit(assets, receiver)`: Deposits `assets` amount of tokens into the strategy. it can be restricted to vault only or be open +- `deposit(assets, receiver)`: Deposits `assets` amount of tokens into the strategy, can be restricted to the Vault only or be open - `maxWithdraw(address)`: View returning how many assets can the vault take from the vault at any given point in time - `withdraw(assets, receiver, owner)`: Withdraws `assets` amount of tokens from the strategy - `redeem(shares, receiver, owner)`: Redeems `shares` of the strategy for the underlying asset - `balanceOf(address)`: Return the number of shares of the strategy that the address has - `convertToAssets(shares: uint256)`: Converts `shares` into the corresponding amount of asset - `convertToShares(assets: uint256)`: Converts `assets` into the corresponding amount of shares -- `previewWithdraw(assets: uint256)`: Converts `assets` into the corresponding amount of shares rounding up +- `previewWithdraw(assets: uint256)`: Converts `assets` into the corresponding amount of shares rounded up This means that the vault can deposit into any ERC4626 vault but also that a non-compliant strategy can be implemented provided that these functions have been implemented (even if in a non-ERC4626 compliant way). From afc3ea9c2ad4d737c10e2af25af07fed4a2a3606 Mon Sep 17 00:00:00 2001 From: 0xBasically <0xBasic@yearn.finance> Date: Fri, 28 Jul 2023 18:25:33 -0400 Subject: [PATCH 47/54] updates --- docs/getting-started/products/yvaults/v3.md | 28 +++++++-------------- 1 file changed, 9 insertions(+), 19 deletions(-) diff --git a/docs/getting-started/products/yvaults/v3.md b/docs/getting-started/products/yvaults/v3.md index 6ffd21ab1a..9dabb34446 100644 --- a/docs/getting-started/products/yvaults/v3.md +++ b/docs/getting-started/products/yvaults/v3.md @@ -192,15 +192,13 @@ This means that the vault can deposit into any ERC4626 vault but also that a non ## ERC4626 Compliance Vault Shares are ERC4626 compliant. -The most important implication is that `withdraw` and `redeem` functions as presented in ERC4626, with the ability to add two additional non-standard options. +The most important implication is that `withdraw` and `redeem` functions are as presented in ERC4626, with the ability to add two additional non-standard options. -1. `max_loss`: The amount in basis points that the withdrawer will accept as a loss. I.E. 100 = 1% loss accepted. -2. `strategies`: This is an array of strategies to use as the withdrawal queue instead of the default queue. +1. `max_loss`: The amount in basis points that the withdrawer will accept as a loss. ie, 100 = 1% loss accepted +2. `strategies`: This is an array of strategies to use as the withdrawal queue instead of the default queue ### Shutdown Mode -In the case the current roles stop fulfilling their responsibilities or something else happens, the EMERGENCY_MANAGER can shut down the vault. - -The shutdown mode should be the last option in an emergency as it is irreversible. +In the case that current Roles stop fulfilling their responsibilities or something else happens, the EMERGENCY_MANAGER can shut down the vault. This shutdown mode should be the last option in an emergency as it is irreversible. ### Deposits `_Light emergency_`: Deposits can be paused by setting `depositLimit` to 0 @@ -208,26 +206,18 @@ The shutdown mode should be the last option in an emergency as it is irreversibl `_Shutdown mode_`: Deposits are not allowed ### Withdrawals -Withdrawals can't be paused under any circumstance. +Withdrawals cannot be paused under any circumstance. ### Accounting -Shutdown mode does not affect the accounting. +Shutdown mode does not affect accounting. ### Debt Rebalancing -`_Light emergency_`: Setting minimumTotalIdle to MAX_UINT256 will result in the vault requesting the debt back from strategies. This would stop new strategies from getting funded too, as the vault prioritizes minimumTotalIdle +`_Light emergency_`: Setting minimumTotalIdle to MAX_UINT256 will result in the vault requesting the debt back from strategies. This would stop new strategies from getting funded as well, as the vault prioritizes minimumTotalIdle -`_Shutdown mode_`: All strategies maxDebt is set to 0. Strategies will return funds as soon as they can. +`_Shutdown mode_`: All strategies maxDebt is set to 0. Strategies will return funds as soon as they can ### Relevant Emergency -In case the current roles stop fulfilling their responsibilities or something else happens, the `EMERGENCY_MANAGER` can shut down the vault. - -The shutdown mode should be the last option in an emergency as it is irreversible. - -During shutdown mode, the vault will try to get funds back from every strategy as soon as possible. - -No strategies can be added during the shutdown - -Any relevant role will start pointing to the `EMERGENCY_MANAGER` in case new permissioned allowed actions need to be taken. +In case the current Roles stop fulfilling their responsibilities or something else happens, the `EMERGENCY_MANAGER` can shut down the vault. The shutdown mode should be the last option in an emergency as it is irreversible. During shutdown mode, the vault will try to get funds back from every strategy as soon as possible. No strategies can be added during shutdown. Any relevant Role will start pointing to the `EMERGENCY_MANAGER` in case new permissioned allowed actions need to be taken. # Yearn V3 Tokenized Strategy Specification From b2f0ab15ea30be395e17a652147250e7d5e0d614 Mon Sep 17 00:00:00 2001 From: 0xBasically <0xBasic@yearn.finance> Date: Fri, 28 Jul 2023 18:26:58 -0400 Subject: [PATCH 48/54] updates --- docs/getting-started/products/yvaults/v3.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/getting-started/products/yvaults/v3.md b/docs/getting-started/products/yvaults/v3.md index 9dabb34446..f1cf947806 100644 --- a/docs/getting-started/products/yvaults/v3.md +++ b/docs/getting-started/products/yvaults/v3.md @@ -223,10 +223,9 @@ In case the current Roles stop fulfilling their responsibilities or something el # Yearn V3 Tokenized Strategy Specification ## Overview -The Yearn V3 "Tokenized Strategy" goal is to make it as easy as possible for any person or protocol to create and deploy their own ERC-4626 compliant single strategy vault. It uses an immutable proxy pattern to outsource all of the standardized 4626 and other vault logic to one implementation contract that all Strategies deployed on a specific chain use through delegatecall. - -This makes the strategy-specific contract as simple and specific to that yield-generating task as possible and allows for anyone to simply plug their version into a permissionless, secure and optimized 4626 compliant base that handles all risky and complicated code. +The Yearn V3 "Tokenized Strategy" goal is to make it as easy as possible for any person or protocol to create and deploy their own ERC-4626 compliant single-strategy vault. It uses an immutable proxy pattern to outsource all of the standardized 4626 and other vault logic to one implementation contract that all strategies deployed on a specific chain use through delegatecall. +This makes the strategy-specific contract as simple and specific to that yield-generating task as possible which allows for anyone to simply plug their version into a permissionless, secure, and optimized 4626-compliant base that handles all risky and complicated code. ### Definitions - **Asset**: Any ERC20-compliant token From aeea95551b3d892ab6387de15e5642a6d68d23c4 Mon Sep 17 00:00:00 2001 From: 0xBasically <0xBasic@yearn.finance> Date: Fri, 28 Jul 2023 18:27:23 -0400 Subject: [PATCH 49/54] mistake --- docs/getting-started/products/yvaults/v3.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/products/yvaults/v3.md b/docs/getting-started/products/yvaults/v3.md index f1cf947806..4d07fea74c 100644 --- a/docs/getting-started/products/yvaults/v3.md +++ b/docs/getting-started/products/yvaults/v3.md @@ -237,7 +237,7 @@ This makes the strategy-specific contract as simple and specific to that yield-g - **Depositor**: Account that holds Shares - **Vault**: Or "Meta Vault" is an ERC4626 compliant Smart contract that receives Assets from Depositors to then distribute them among the different Strategies added to the vault, managing accounting and Assets distribution. - **Management**: The owner of the specific strategy that can set fees, profit unlocking time etc. -- **Keepe**r: the address of a contract allowed to call report() and tend() on a strategy. +- **Keeper**: the address of a contract allowed to call report() and tend() on a strategy. - **Factory**: The factory that all meta vaults of a specific API version are cloned from that also controls the protocol fee amount and recipient. ## Storage From 0a1c17b07c1660854c178b30098312db746fd402 Mon Sep 17 00:00:00 2001 From: 0xBasically <0xBasic@yearn.finance> Date: Fri, 28 Jul 2023 18:28:31 -0400 Subject: [PATCH 50/54] add: links --- docs/getting-started/products/yvaults/v3.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/getting-started/products/yvaults/v3.md b/docs/getting-started/products/yvaults/v3.md index 4d07fea74c..e9f382824b 100644 --- a/docs/getting-started/products/yvaults/v3.md +++ b/docs/getting-started/products/yvaults/v3.md @@ -458,3 +458,5 @@ All other parameters will default to generic values and can be adjusted post-dep # Read More - https://medium.com/iearn/yearnv3-motivation-and-design-107840cb4844 - https://medium.com/iearn/yearn-vaults-v3-36ce7c468ca0 +- https://erc4626.info/ +- https://eips.ethereum.org/EIPS/eip-4626 From 2f024bf8c08b80dc91319e2bbb080f42c7221b46 Mon Sep 17 00:00:00 2001 From: 0xBasically <0xBasic@yearn.finance> Date: Fri, 28 Jul 2023 18:29:17 -0400 Subject: [PATCH 51/54] fix: typo --- docs/getting-started/products/yvaults/v3.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/products/yvaults/v3.md b/docs/getting-started/products/yvaults/v3.md index e9f382824b..991749f36b 100644 --- a/docs/getting-started/products/yvaults/v3.md +++ b/docs/getting-started/products/yvaults/v3.md @@ -179,7 +179,7 @@ To be compatible with the vault, they need to implement the following functions, - `totalAssets()`: View returning the current amount of assets. It can include rewards valued in `asset` - `maxDeposit(address)`: View returning the amount max that the strategy can take safely - `deposit(assets, receiver)`: Deposits `assets` amount of tokens into the strategy, can be restricted to the Vault only or be open -- `maxWithdraw(address)`: View returning how many assets can the vault take from the vault at any given point in time +- `maxWithdraw(address)`: View returning how many assets can the vault take from the strategy at any given point in time - `withdraw(assets, receiver, owner)`: Withdraws `assets` amount of tokens from the strategy - `redeem(shares, receiver, owner)`: Redeems `shares` of the strategy for the underlying asset - `balanceOf(address)`: Return the number of shares of the strategy that the address has From 72b251c7a85deca887c71036e258d7abd2bde42c Mon Sep 17 00:00:00 2001 From: 0xBasically <0xBasic@yearn.finance> Date: Fri, 28 Jul 2023 18:30:04 -0400 Subject: [PATCH 52/54] fix: duplicate info --- docs/getting-started/products/yvaults/v3.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/getting-started/products/yvaults/v3.md b/docs/getting-started/products/yvaults/v3.md index 991749f36b..d2f46815fe 100644 --- a/docs/getting-started/products/yvaults/v3.md +++ b/docs/getting-started/products/yvaults/v3.md @@ -197,9 +197,6 @@ The most important implication is that `withdraw` and `redeem` functions are as 1. `max_loss`: The amount in basis points that the withdrawer will accept as a loss. ie, 100 = 1% loss accepted 2. `strategies`: This is an array of strategies to use as the withdrawal queue instead of the default queue -### Shutdown Mode -In the case that current Roles stop fulfilling their responsibilities or something else happens, the EMERGENCY_MANAGER can shut down the vault. This shutdown mode should be the last option in an emergency as it is irreversible. - ### Deposits `_Light emergency_`: Deposits can be paused by setting `depositLimit` to 0 From 96a737c4d8d2ad30290fbaa3214931e5d65f6119 Mon Sep 17 00:00:00 2001 From: 0xBasically <0xBasic@yearn.finance> Date: Fri, 28 Jul 2023 18:30:27 -0400 Subject: [PATCH 53/54] fix: duplicate info --- docs/getting-started/products/yvaults/v3.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/products/yvaults/v3.md b/docs/getting-started/products/yvaults/v3.md index d2f46815fe..2fb359776c 100644 --- a/docs/getting-started/products/yvaults/v3.md +++ b/docs/getting-started/products/yvaults/v3.md @@ -213,7 +213,7 @@ Shutdown mode does not affect accounting. `_Shutdown mode_`: All strategies maxDebt is set to 0. Strategies will return funds as soon as they can -### Relevant Emergency +### Shutdown Mode In case the current Roles stop fulfilling their responsibilities or something else happens, the `EMERGENCY_MANAGER` can shut down the vault. The shutdown mode should be the last option in an emergency as it is irreversible. During shutdown mode, the vault will try to get funds back from every strategy as soon as possible. No strategies can be added during shutdown. Any relevant Role will start pointing to the `EMERGENCY_MANAGER` in case new permissioned allowed actions need to be taken. From 86156fb5020dd39ff2217204513fd1a4ce36ef2e Mon Sep 17 00:00:00 2001 From: 0xBasically <0xBasic@yearn.finance> Date: Fri, 28 Jul 2023 18:30:49 -0400 Subject: [PATCH 54/54] fix: spacing --- docs/getting-started/products/yvaults/v3.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/getting-started/products/yvaults/v3.md b/docs/getting-started/products/yvaults/v3.md index 2fb359776c..28af9690a2 100644 --- a/docs/getting-started/products/yvaults/v3.md +++ b/docs/getting-started/products/yvaults/v3.md @@ -216,7 +216,6 @@ Shutdown mode does not affect accounting. ### Shutdown Mode In case the current Roles stop fulfilling their responsibilities or something else happens, the `EMERGENCY_MANAGER` can shut down the vault. The shutdown mode should be the last option in an emergency as it is irreversible. During shutdown mode, the vault will try to get funds back from every strategy as soon as possible. No strategies can be added during shutdown. Any relevant Role will start pointing to the `EMERGENCY_MANAGER` in case new permissioned allowed actions need to be taken. - # Yearn V3 Tokenized Strategy Specification ## Overview