# Turbo Docs

Tribe Turbo is an innovative mechanism for issuing stablecoins and earning yield.

* [Announcement](https://medium.com/fei-protocol/the-tribe-dao-strongly-believes-that-a-healthy-and-thriving-defi-ecosystem-needs-a-robust-platform-b1faea700dfa)
* [Audit Guide](https://hackmd.io/rYfLz--qTnW_4Ays5FL6zQ)
* [Code](https://github.com/fei-protocol/tribe-turbo)
* [Dili audit](https://consensys.net/diligence/audits/private/3wmfeucqds486i/) - password: `W|@Izw;e56`
* [Code4rena Findings](https://github.com/code-423n4/2022-02-tribe-turbo-findings)

This guide contains docs for turbo consumers, keepers, DAO Operators, and interface developers.

# Turbo User Guide

From a user perspective, Turbo is basically a wrapper (Safe) around a collaeralized Fuse lending position. The borrowed asset is FEI at 0% APR, and that FEI is then resupplied to earn yield into ERC-4626 strategies.

Definitions:
* [Fuse](https://v2.rari.capital/fuse) - a lending market platform where users can supply collateral and borrow any supported asset with liquidity.
* Turbo Safe - an ERC-4626 Vault which can boost FEI and share revenue. Safe's have a single collateral but can support many yield strategies.
* [ERC-4626](https://eips.ethereum.org/EIPS/eip-4626) - a new standard for Tokenized Vaults. It represents a strategy which is itself also tokenized.

Supported collateral types and yield strategies need to be added by Tribe Governance.

Initial Collaterals:
* TRIBE
* BAL
* gOHM

Initial yield strategies
* Fuse FEI from approved pools

Users of Turbo become joint issuers of FEI with the Tribe DAO, deciding which markets to supply newly minted FEI to and splitting the revenue. They generally want one or both of:
1. additional yield on tokens
2. Liquidity on FEI in a specific market

Revenue splits are calculated as follows:
1. If the Safe has a custom revenue split set by governance, use that.
2. If the Collateral associated with the Safe has a custom revenue split, use that
3. Use the default revenue split.

Safes are created with a default access control which allows the creator (user), router, and savior to access the safe. The router allows the user to perform multiple actions at once. The Savior allows any EOA to delever the vault when it exceeds a safe collateralization threshold.

See advanced operations for how to override this access control.

## Basic Operations

Turbo users can perform the following basic actions on their Safes:

### Deposit/Withdraw
Add and remove collateral which can be used to boost or improve borrowing health factor. This is always denominated in a single token per Safe e.g. TRIBE or BAL.

These follow the ERC-4626 interface and include mint/redeem as well.

### Boost/Less

    /// @notice Borrow Fei from the Turbo Fuse Pool and deposit it into an authorized Vault.
    /// @param vault The Vault to deposit the borrowed Fei into.
    /// @param feiAmount The amount of Fei to borrow and supply into the Vault.
    function boost(ERC4626 vault, uint256 feiAmount) external

Boosting is borrowing FEI and depositing it into a yield strategy.

    /// @notice Withdraw Fei from a deposited Vault and use it to repay debt in the Turbo Fuse Pool.
    /// @param vault The Vault to withdraw the Fei from.
    /// @param feiAmount The amount of Fei to withdraw from the Vault and repay in the Turbo Fuse Pool.
    function less(ERC4626 vault, uint256 feiAmount) external;

Lessing is the inverse of boosting.

Note that Tribe governance can less any Safe at any time to contract the FEI supply. This would be a matter of monetary policy to protect the FEI peg in the event of a demand shock.

### Slurp/Sweep

/// @notice Accrue any interest earned by the Safe in the Vault.
/// @param vault The Vault to accrue interest from, if any.
/// @dev Sends a portion of the interest to the Master, as determined by the Clerk.
function slurp(ERC4626 vault) external;

Slurp - accrues fees earned on the FEI yield strategies on the safe. This operation is done per safe. The Tribe governance share of the revenue split FEI is sent there. The Safe owner's share is withdrawn to the Safe where it can then be swept.

NOTE Tribe Governance can slurp on a Safe at any time to claim its fees.

/// @notice Claim tokens sitting idly in the Safe.
/// @param to The recipient of the sweeped tokens.
/// @param token The token to sweep and send.
/// @param amount The amount of the token to sweep.
function sweep(
    address to,
    ERC20 token,
    uint256 amount
) external;

Sweep - withdraw fei accrued as interest or other tokens laying idle in a safe. To get FEI interest into the Safe, first less the entire balance. ([TODO](https://linear.app/fei/issue/DEV-2678/add-skim-to-turbo) consider adding a skim method to free up surplus FEI).

## Risks
The risks of using Turbo are similar to a normal lending market, with some risks reduced and other unique Turbo-specific risks.

There are two different types of risks to the Safe holder, collateral risk and yield strategy risk.

### Collateral Risk
A collateral can be liquidated like a normal Fuse position. If this happens, all FEI debt would be repayed by the safe. This means the boosted amount becomes equity which the Safe holder can sweep.

In other words, liquidation effectively means the user's collateral was force sold into the FEI yield strategies the Safe is holding. The revenue split will continue to apply to all interest.

### Yield Strategy Risk
The yield strategy where FEI is deployed may become insolvent due to bad debt or some kind of vulnerability. Because the vault can no longer "less", the Turbo Safe begins to incur the risk of this bad debt. If the vault holder cannot repay, Tribe Governance can repay and sieze the collateral using the `gib` operation.

## Advanced Operations

Safe holders can expose the basic operations to smart contracts or other users according to arbitrary logic by replacing the Safe's [Authority](https://github.com/Rari-Capital/solmate/blob/main/src/auth/Auth.sol)

This would remove the Router and Savior's access unless it is re-granted in the new authority.

Only replace the Authority if you are sure you know what you are doing, this operation can risk the user's collateral if done incorrectly.

# Keepers Guide
## Savior

The [Turbo Savior](https://github.com/fei-protocol/tribe-turbo/blob/main/src/modules/TurboSavior.sol) is an optional module which is included by default. It allows any EOA to deleverage a vault by calling `less` on any boosted strategy once the Safe hits 80% of its credit line (customizeable by governance, call `minDebtPercentageForSaving` to check).

To save a vault, call

/// @notice Save a Safe (call less on owner's behalf to prevent liquidation).
/// @param safe The Safe to be saved.
/// @param vault The Vault to less from.
/// @param feiAmount The amount of Fei to less from the Safe.
function save(
    TurboSafe safe,
    ERC4626 vault,
    uint256 feiAmount
) external

and input the desired safe, vault, and fei amount. If the vault is over the 80%, it will be lessed by the input amount.

## Liquidator

Liquidations on the turbo pool will use a custom liquidator, the [B Protocol BAMM](https://github.com/backstop-protocol/dev/blob/ctoken_as_backstop/packages/contracts/contracts/B.Protocol/BAMM.sol):

To liquidate call

The borrower is the Safe and the collateral is the underlying asset of the Safe.

Note: the code above currently holds cTokens not underlyings but this will be changed before it is implemented.

TODO: Liquidator bots for this.

# DAO Operators

## Adding new collaterals
1. `TurboAdmin.addCollateral()`
2. `TurboBooster.setBoostCapForCollateral()`
3. (Optional) `TurboClerk.setCustomFeePercentageForCollateral()`

## Adding new strategies
1. `TurboBooster.setBoostCapForVault()`

## Setting custom Safe revenue split
1. `TurboClerk.setCustomFeePercentageForSafe()`

## Executing Gibber
1. `TurboAdmin.schedule(gibber, abi.encodeWithSignature("impoundAll(address,address)",safe,to))`. Use https://ethtx.info/ to read tx data and save the salt.
2. Wait 15 day timelock
3. `TurboAdmin.execute(gibber,abi.encodeWithSignature("impoundAll(address,address)",safe,to), salt)` (get salt from tx data of 1.)

## Access Control Summary
These are the roles which are in Tribe Turbo, their powers, and their default owners.

### GIBBER_ROLE
HIGH CLEARANCE. capable of calling `gib` to impound collateral. 

Powers:
* `TurboSafe.gib`

Owners:
* gibber
    
### ROUTER_ROLE
HIGH CLEARANCE. Optional module which can interact with any user's vault by default.

The router itself replicates access control so that other users can't interact

Powers:
* `TurboSafe.boost`
* `TurboSafe.less`
* `TurboSafe.slurp`
* `TurboSafe.sweep`
* `TurboSafe.deposit`
* `TurboSafe.mint`
* `TurboSafe.withdraw`
* `TurboSafe.redeem`

Owners:
* router

### SAVIOR_ROLE 
Capable of lessing any vault. Exposed on optional TurboSavior module.

Powers:
* `TurboSafe.less`

Owners:
* savior

### TURBO_ADMIN_ROLE
Operational admin of Turbo, can whitelist collaterals, strategies, and configure most parameters.

Powers:
* `TurboSafe.slurp`
* `TurboSafe.less`
* `TurboMaster.createSafe`
* `TurboMaster.setBooster`
* `TurboMaster.setDefaultSafeAuthority`
* `TurboMaster.sweep`
* `TurboClerk.setDefaultFeePercentage`
* `TurboClerk.setCustomFeePercentageForCollateral`
* `TurboClerk.setCustomFeePercentageForSafe`
* `TurboBooster.setFreezeStatus`
* `TurboBooster.setBoostCapForVault`
* `TurboBooster.setBoostCapForCollateral`
* `TurboSavior.setMinDebtPercentageForSaving`
* `TurboAdmin._setMarketSupplyCaps`
* `TurboAdmin._setMarketSupplyCapsByUnderlying`
* `TurboAdmin._setMarketBorrowCaps`
* `TurboAdmin._setMarketBorrowCapsByUnderlying`
* `TurboAdmin._setMintPausedByUnderlying`
* `TurboAdmin._setMintPaused`
* `TurboAdmin._setBorrowPaused`
* `TurboAdmin._setBorrowPausedByUnderlying`
* `TurboAdmin.oracleAdd`
* `TurboAdmin.addCollateral`
* `TurboAdmin._deployMarket`
* `TurboAdmin._addRewardsDistributor`
* `TurboAdmin._setCloseFactor`
* `TurboAdmin._setCollateralFactor`
* `TurboAdmin._setLiquidationIncentive`
* `TurboAdmin.schedule`
       
Owners:
* fei dao timelock
* turbo pod if [FIP-82](https://tribe.fei.money/t/fip-82-governance-enhancements/3945/23) passes
* master
* admin

### GUARDIAN_ROLE
Pause and security Guardian role.
   
Powers:
* `TurboSafe.less`
* `TurboBooster.setFreezeStatus`
* `TurboAdmin._setMarketSupplyCaps`
* `TurboAdmin._setMarketSupplyCapsByUnderlying`
* `TurboAdmin._setMarketBorrowCaps`
* `TurboAdmin._setMarketBorrowCapsByUnderlying`
* `TurboAdmin._setMintPausedByUnderlying`
* `TurboAdmin._setMintPaused`
* `TurboAdmin._setBorrowPaused`
* `TurboAdmin._setBorrowPausedByUnderlying`
* `TurboAdmin._setTransferPaused`
* `TurboAdmin._setSeizePaused`
       
Owners:
* Tribe Security Guardian

### GOVERN_ROLE
HIGH CLEARANCE. Capable of critical governance functionality on TurboAdmin such as oracle upgrades. 

Powers:
* `TurboAdmin._setBorrowCapGuardian`
* `TurboAdmin._setPauseGuardian`
* `TurboAdmin.oracleChangeAdmin`
* `TurboAdmin._setWhitelistEnforcement`
* `TurboAdmin._setPriceOracle`
* `TurboAdmin._setMintPaused`
* `TurboAdmin._unsupportMarket`
* `TurboAdmin._toggleAutoImplementations`
* `TurboAdmin.scheduleSetPendingAdmin`
* `TurboAdmin.schedule`
* `TurboAdmin.cancel`
       
Owners:
* Fei DAO Timelock

### TURBO_STRATEGIST_ROLE
Limited version of TURBO_ADMIN_ROLE which can manage collateral and vault parameters.

Powers:
* `TurboBooster.setBoostCapForVault`
* `TurboBooster.setBoostCapForCollateral`
* `TurboAdmin._setMarketSupplyCaps`
* `TurboAdmin._setMarketSupplyCapsByUnderlying`
* `TurboAdmin.addCollateral`
       
Owners:
* None initially

# Interface Developent Docs 
## ENS
The tribe is the proud owner of `turbo.eth`. As such, important turbo contracts will be given an ens subdomain.

TODO assign the ENS's

`router.turbo.eth` - TurboRouter.sol
`master.turbo.eth` - TurboMaster.sol
`authority.turbo.eth` - default authority
`timelock.turbo.eth` - Turbo Timelock
`comptroller.turbo.eth` - Turbo Fuse Pool Comptroller
`gibber.turbo.eth` - Turbo Gibber
`booster.turbo.eth` - Turbo Booster
`clerk.turbo.eth` - Turbo Clerk
`savior.turbo.eth` - Turbo Savior
`admin.turbo.eth` - TurboAdmin


## Turbo Router

The Turbo Router allows users to perform multiple operations simultaneously using a multicall.

The user must approve the router before interacting, this can be done atomically with an EIP-2612 permit using [SelfPermit](https://github.com/fei-protocol/ERC4626/blob/main/src/external/SelfPermit.sol).

The router must have approved the Turbo Safe as well. This is done atomically in createSafeAndDeposit.

[TODO](https://linear.app/fei/issue/DEV-2682/add-approvals-and-skim-to-router) fix approval bug. https://github.com/fei-protocol/tribe-turbo/issues/72

[PeripheryPayments](https://github.com/fei-protocol/ERC4626/blob/main/src/external/PeripheryPayments.sol) is used to pull in tokens for deposits, wrap/unwrap weth, or withdraw accrued fees and collateral.

Common user flows:
1. "open position" Deposit + Boost
2. "accrue" Slurp all (all boosted safes)
3. "close vault" Slurp all + less + sweep + withdraw
4. "change strategy" Less + boost

## Turbo Lens

    struct StrategyInfo {
        /// @notice the fei strategy boosted by the safe
        ERC4626 strategy;
        
        /// @notice the amount of fei boosted by the safe to this strategy
        uint256 boostedAmount;
        
        /// @notice the amount of fei held by the safe in this strategy
        uint256 feiAmount;
    }

    struct SafeInfo {
        /// @notice the safe collateral
        ERC20 collateralAsset;

        /// @notice the balance of collateral assets held by the safe
        uint256 collateralAmount;
        
        /// @notice the collateral value of assets
        uint256 collateralValue;

        /// @notice the FEI debt held by safe
        uint256 debtAmount;

        /// @notice the value of FEI deby held by safe
        uint256 debtValue;

        /// @notice the total FEI boosted value
        uint256 boostedAmount;

        /// @notice the total amount of FEI held by all strategies in the Safe
        uint256 feiAmount;

        /// @notice fee split to TRIBE dao scaled by 1e18
        uint256 tribeDAOFee;

        StrategyInfo[] strategyInfo;
    }
    
    function getAllUserSafes(address owner) external returns (SafeInfo[] memory)
    
    function getSafeInfo(TurboSafe safe) external returns(SafeInfo memory)

User FEI owed =
(boostedAmount - debtAmount) + ((feiAmount - boostedAmount) * (1 - fee split to tribe dao)) + fei.balanceOf(safe)

Boosting cap for (safe,strategy):
min(fei.balanceOf(fFEI), booster.getBoostCapForVault(strategy) - master.getTotalBoostedForVault(strategy), booster.getBoostCapForCollateral(safe.asset()) - master.getTotalBoostedAgainstCollateral(safe.asset()))

Deployment steps:
PR: https://github.com/fei-protocol/tribe-turbo/pull/80

After cloning tribe-turbo and running devnet on http://127.0.0.1:8545/
1. git checkout feat/setup
2. sh scripts/setup.sh

Output contains something like:

master=0xd1328acdc70a9f4bb0aeccd1defc3e2bdfb209e6 router=0xdef5f531fbbd6122519899c8954caaeb05bd38d4 lens=0xefcf95fe6b297fe43ffd357145d94b25b2929d6b strategy=0x358307ad592d4577b9a2afc4681830ee017c7ccd

booster=0x31249a4408b09d9af21dc3b5e92d81728d66b57b clerk=0xb1920e0fd2cf2402528118121727c7f9d1400c7a comptroller=0x07f01026738f35f0e0855a81335360e3d7d587d0

Can use these contracts to completely locally test UI.