* 1. # Yearn System Specification (DRAFT)`**[](https://)**`[](https://)* 1. # Yearn System Specification (DRAFT)`**[](https://)**`[](https://)

### Definitions
TODO: fill these definitions
- VAULT:
- ASSET:TUSD
- SHARE:
- DEPOSITOR:
- STRATEGY:
- ROLES:
- role_manager
- ACCOUNTING_MANAGER
- DEBT_MANAGER
- STRATEGY_MANAGER
- EMERGENCY_MANAGER

## Vault Specification

### 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 point in 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 https://hackmd.io/cOFvpyR-SxWArfthhLJb5g?both#strategy to withdraw from. If a list of strategies is passed, the vault will try to withdraw from them.

#### Vault Shares
Vault shares are ERC20 transferable 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 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

##### Fees
Fee assessment and distribution is handled by the fee_manager module.

TODO: review this

#### Profit distribution
Profit from different processReport calls will accumulate in a buffer. This buffer will be linearly unlocked over the next `PROFIT_BUFFER_TIME` seconds (e.g. 7 days).

The `unlockingPerSecondPerToken` variable will tell how much profit is unlocked per second. It will be used to calculate unlocked profit since the last harvest. If the last harvest was more than PROFIT_BUFFER_TIME seconds ago, all the profit is unlocked.

This rate needs to change with deposits and withdraws too?

Losses will remove profit from the buffer and, only if losses are bigger than locked profit, will impact price per share. This way, frontrunning losses is more difficult and

### Vault Management
Vault management is split in two fields: strategy management and debt management.

#### Strategy Management
This responsibility is taken by callers with STRATEGY_MANAGER role

A vault can have strategies added, removed and migrated

Added strategies will be eligible to receive funds from the vault.

Revoked strategies will try return all debt and stop being eligible to receive more.

Strategy migration is the process of replacing an existing strategy with a new one, which will inherit all parameters and debt

#### Debt Management
This responsibility is taken by callers with 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
Each strategy has a maximum amount of debt the vault will send. This amount is specified in amount of ASSET tokens.
Function updateMaxDebtForStrategy

TODO: review a middle approach with maxDebtPerStrategy and updateDebt(strategy, debt)

##### Rebalance Debt
The vault sends and receives funds to/from strategies. The function updateDebt(strategy) will compare the current debt with the maxDebt.

If the strategy currently has less debt than the maxDebt, 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 maxDebt, 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.

TODO: add forcedFreeFunds

TODO: add maxDebt + targetDebt? updateDebt(strategy, debt)

### Roles
Vault functions that are permissioned will be callable by accounts that hold specific roles.

These are:
- STRATEGY_MANAGER: TODO
- DEBT_MANAGER: TODO
- EMERGENCY_MANAGER: TODO
- ACCOUNTING_MANAGER: TODO

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:
- freeFunds()
- totalAssets()
- withdrawable()
- investable()
- asset()
- vault()

Anything else is left to the strategy writer. However, to make security review easier, the Yearn's template has the following optional functions:
- harvest(): maintain position
- invest(): deposit funds into underlying protocol
- emergencyFreeFunds()
-

TODO: complete this

### 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 just be the one in the vault. No strategies will be passed to the redeem function to withdraw from.

### Emergency Operation

#### Shutdown mode
In the case the current roles stop fulfilling their responsibilities or something else's happen, 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 by any role

#### 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's happen, 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.

TODO: keep it irreversible?

TODO: emergencyFreeFunds: implement a way to force wind down of a strategy (even taking losses) only callable by EMERGENCY_MANAGER?

# Yearn Registry Specification

TODO