Vault Protocol on

Vaults

Mon, 01 Jan 0001 00:00:00 +0000

Fluid has 4 types of vaults:

T1 vaults -> 1 collateral token / 1 debt token
T2 vaults -> 2 collateral tokens (smart collateral) / 1 debt token
T3 vaults -> 1 collateral token / 2 debt tokens (smart debt)
T4 vaults -> 2 collateral tokens (smart collateral) / 2 debt tokens (smart debt)

We are going to analyze only T1 vaults for this module, as that’s enough to understand the core idea behind managing positions and the liquidation engine.

1st supply/withdraw no debt

Mon, 01 Jan 0001 00:00:00 +0000

To keep things simpler at the start, let’s just completely ignore the borrow side at the moment, and only analyze how user interaction with the vault protocol works on plain supply and withdraw.

In the code below, we will hide all code that triggers on borrow behind ... and only focus on supply/withdrawal operations.

We can divide this flow into 11 steps:

Sanity checks
Setup of memory vars
Creation of new position
Update of exchange prices
Calculation of supply or withdrawal amounts
Assign of new tick
Calculation of health factor
Update of user position in storage
Withdrawal gap check
Execution of operation
Update of vault variables in storage

1. Sanity checks

We first check for reentrancy.

2nd supply/withdraw no debt

Mon, 01 Jan 0001 00:00:00 +0000

Everything stays the same, the only difference is that now we are working with existing NFT, meaning we are not passing 0 to main operate function.

If we look at the implementation, we see that we only unlock this new code below in second if case during position fetching:

Code:

Checks nft ownership if we are doing withdraw or borrow as those operations affect health factor
Checks if there exists valid non empty position for passed NFT. This ensures that NFT is from this vault we are interacting with
Fetch and convert supply amount and store it in temp struct for memory variables
Fetch and convert debt amount and store it in temp struct for memory variables
Assign new tick. Note because this is supply only position, tick get’s default value of type(int).min just like on first supply

Ticks

Mon, 01 Jan 0001 00:00:00 +0000

On the previous pages, we were ignoring ticks as we weren’t dealing with debt, but what are the ticks?

If you are familiar with ticks from Uniswap V3, then the same thing ticks are for concentrated liquidity there, here they are for separating positions by their ratio.

ratio = 1.0015^tick

Where ratio is:

ratio = debt / coll

This means:

higher the ratio -> higher the tick -> higher the risk of liquidation

and vice versa

Ticks data structures

Mon, 01 Jan 0001 00:00:00 +0000

Before we dive into borrow flow, let’s quickly introduce some tick data structures that will help us later to understand the code better.

Note that we will analyze liquidations in depth later, so some of these concepts will only make sense then, but I want to introduce them now so we conceptually know what is going on.

TickData

/// mapping tickId => tickData
/// Tick related data. Total debt & other things
/// First bit => 0 => If 1 then liquidated else not liquidated
/// Next 24 bits => 1-24 => Total IDs. ID should start from 1.
/// If not liquidated:
/// Next 64 bits => 25-88 => raw debt
/// If liquidated
/// The below 3 things are of last ID. This is to be updated when user creates a new position
/// Next 1 bit => 25 => Is 100% liquidated? If this is 1 meaning it was above max tick when it got liquidated (100% liquidated)
/// Next 30 bits => 26-55 => branch ID where this tick got liquidated
/// Next 50 bits => 56-105 => debt factor 50 bits (35 bits coefficient | 15 bits expansion)
mapping(int256 => uint256) internal tickData;

TickData describes the latest info for some tick. We will call that info the latest epoch.

Borrow for the first time

Mon, 01 Jan 0001 00:00:00 +0000

We are doing borrow for the first time. We still only have a supply position, and our tick has the initial value of type(int).min.

We are only going to scan relevant code that we deliberately skipped during the first supply scan of the main operate function: Supply/Withdraw for the first

Calculate debt raw

(o_.liquidityExPrice, , o_.supplyExPrice, o_.borrowExPrice) = updateExchangePrices(o_.vaultVariables2);

{
 // supply or withdraw
 ...
}

// borrow or payback
if (newDebt_ > 0) {
 // borrow new debt, rounding up adding extra wei in debt
 temp_ = ((uint(newDebt_) * EXCHANGE_PRICES_PRECISION) / o_.borrowExPrice) + 1;
 // if borrow fee is 0 then it'll become temp_ + 0.
 // Only adding fee in o_.debtRaw and not in newDebt_ as newDebt_ is debt that needs to be borrowed from Liquidity
 // as we have added fee in debtRaw hence it will get added in user's position & vault's total borrow.
 // It can be collected with rebalance function.
 o_.debtRaw += temp_ + (temp_ * ((o_.vaultVariables2 >> 82) & X10)) / 10000;
 // final user's debt should not be above 2**128 bits
 if (o_.debtRaw > X128) {
 revert FluidVaultError(ErrorTypes.Vault__UserCollateralDebtExceed);
 }
}

We calculated exchange prices and want to calculate the debt raw amount.