Liquidation

Cross Margin Liquidation

When the 'health factor' of an account's total loans is below 1, anyone can make a liquidation call to the contract, pay back part of the debt owed and receive discounted collateral in return (also known as the liquidation bonus).

This incentivises third parties to participate in the health of the overall protocol, by acting in their own interest (to receive the discounted collateral) and as a result, ensure borrows are sufficiently collateralize.

There are multiple ways to participate in liquidations:

  • Calling the liquidation methods directly in the contract.

  • Creating your own automated bot or system to liquidate loans.

Prerequisites

When making a liquidation call, you must:

  • Know the account (i.e. the ethreum address: user) whose health factor is below 1.

  • Know the valid debt amount and asset (i.e. debtToCover & debtAsset).

  • If the HF is above CLOSE_FACTOR_HF_THRESHOLD, then only a maximum of 50% (i.e. DEFAULT_LIQUIDATION_CLOSE_FACTOR) of the debt can be liquidated.

  • If the HF is below CLOSE_FACTOR_HF_THRESHOLD, then 100% (i.e. MAX_LIQUIDATION_CLOSE_FACTOR) of the debt can be liquidated.

  • You must already have sufficient balance of the debt asset, which will be used by the liquidation method to pay back the debt.

  • Know the collateral asset collateralAsset you closing, i.e. the asset that the user has backing their outstanding loan that you will receive as a bonus.

Getting accounts to liquidate

Only user accounts that have HF < 1 can be liquidated.

To gather user account data from on-chain data, you need to monitor emitted events from the protocol and keep an up to date index of user data locally.

Events are emitted each time a user interacts with the protocol (deposit, borrow, repay, withdraw etc.)

When you have the user's address, you can simply call getUserAccountData(), to read the user's current healthFactor. If the HF < 1, then the account can be liquidated.

Executing the liquidation call

Once you have the account(s) to liquidate, you will need to calculate the amount of collateral that can be liquidated:

  • Use getUserAssetData().

  • Max debt that be cleared by single liquidation call is given by the DEFAULT_LIQUIDATION_CLOSE_FACTOR(when CLOSE_FACTOR_HF_THRESHOLD < HF < 1) or MAX_LIQUIDATION_CLOSE_FACTOR (when HF < CLOSE_FACTOR_HF_THRESHOLD).

  • debtToCover = totalCrossBorrow * LiquidationCloseFactor.

  • You can pass uint(-1), i.e. MAX_UINT, as the debtToCover to liquidate the maximum amount allowed.

  • Max amount of collateral that can be liquidated to cover debt is given by the current liquidationBonus for the asset.

Liquidation Methods

Last updated