Liquidate function on

Liquidate: Sanity check and setup

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

We are entering the liquidate function with the code below:

Liquidator is sending:

debtAmt_ -> amount of debt to liquidate
colPerUnitDebt_ -> min amount of collateral per one unit of debt that liquidator is expecting to get in return
to_ -> where to send collateral tokens
absorb_ -> whether liquidation should first consume absorbed debt (or better known as bad debt)

Upon entering the function, we first perform the standard reentrancy check:

Liquidate: Calculate liquidation and max ratio

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

We are looking at this piece of code:

This part of code calculates 2 things:

liquidation tick
max tick

The part for liquidation tick calculation is something we already covered when we were checking user health position here.

The only thing left to answer is what is max tick?

Max tick is the upper limit where positions above it get 100% liquidated immediately. This limit is primarily used as the last line of defense against bad debt and has a separate flow.

Liquidate: Setup for liquidation loop

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

We are looking at this code:

This code is just setup code with no new logic, so we will quickly run over it.

We first validate that the input amount for debt to liquidate is not too low or too high:

if (debtAmt_ < 10000 || debtAmt_ > X128) {
 revert FluidVaultError(ErrorTypes.Vault__InvalidLiquidationAmt);
}

Then we set up memory variables that will be used later:

// setting up status if top tick is liquidated or not
currentData_.tickStatus = vaultVariables_ & 2 == 0 ? 1 : 2;
// Tick info is mainly used as a place holder to store temporary tick related data
// (it can be current or ref using same memory variable)
TickData memory tickInfo_;
tickInfo_.tick = currentData_.tick;

After this, we load the current branch data to memory:

Liquidate: Liquidation loop

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

Finally, we are arriving at the core liquidation loop that will be the heart of this vault liquidate function.

As seen on the image above, we can divide this function into different logical parts which we will analyze separately:

Setup of local vars
Calculation of current tick ratio
Addition of new debt and collateral for liquidation
Update of tickHasDebt and next active tick search
Finding the reference tick
Finding the reference ratio
Calculation of debt and collateral to liquidate
Finish of liquidation loop
Updating amounts and factors for next iteration
Merging branches
Updating tick and ratio for next iteration

Setup of local vars

uint debtLiquidated_;
uint colLiquidated_;
uint debtFactor_ = BigMathVault.TWO_POWER_64;

TickHasDebt memory tickHasDebt_;
unchecked {
 tickHasDebt_.mapId = (currentData_.tick < 0)
 ? (((currentData_.tick + 1) / 256) - 1)
 : (currentData_.tick / 256);
}

We start slowly by setting a few local variables that will be used later. Then we find the mapId of the tickHasDebt mapping for current topTick.

Liquidate: Calculate net token amounts

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

We are mostly done with this function. We finished the liquidation loop, and now we need to calculate the exact amounts that need to be transferred to the liquidator.

First, we convert amounts to net amounts by multiplying with exchange prices:

actualDebtAmt_ = (currentData_.totalDebtLiq * memoryVars_.borrowExPrice) / EXCHANGE_PRICES_PRECISION;
actualColAmt_ = (currentData_.totalColLiq * memoryVars_.supplyExPrice) / EXCHANGE_PRICES_PRECISION;

The reason for doing this is that we previously converted from net to raw before we started the liquidation loop, as ratio calculation works with raw amounts:

Liquidate: Token transfers

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

Once we have net token amounts, let’s perform liquidity transfers:

We first check if debt token is native token, in which case we refund back to liquidator any tokens not spent on liquidation:

SafeTransfer.safeTransferNative(msg.sender, msg.value - actualDebtAmt_);

After that, we perform the payback to liquidity layer, where debt tokens will be pulled from liquidator:

// payback at liquidity
LIQUIDITY.operate{ value: temp_ }(
 BORROW_TOKEN,
 0,
 -int(actualDebtAmt_),
 address(0),
 address(0),
 abi.encode(msg.sender)
);

And finally, we withdraw collateral tokens back to liquidator, again using liquidity layer:

Liquidate: Vault variables storage update

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

Finally, all that’s left to do for this liquidate function is to update total vault supply and debt by lowering the liquidated amounts.

Note that vaultVariables will already contain updated branch data info after liquidation.

After we perform the update, we emit the LogLiquidate event with liquidated amounts:

emit LogLiquidate(msg.sender, actualColAmt_, actualDebtAmt_, to_);