Liquidations in the Borrowing Module

Angle Borrowing Module has not yet been deployed and will soon be open-sourced.
The health of Angle Protocol borrowing module is dependent on the health of the positions (or vaults) within the system, also known as the health factor. When the health factor of a vault is below 1, anyone can make a liquidate call to the VaultManager contract where the vault is, paying back a portion of the debt owed by the vault and receiving discounted collateral in return.
This incentivises third parties to participate in the health of the overall protocol, by acting on their own interest (to receive the discounted collateral) and as a result, ensure AgTokens in circulation from this module are sufficiently collateralised.
What's similar/different with Angle Borrowing Module Liquidations?
Liquidations are quite-common in DeFi. There are however some peculiarities within the Angle system liquidators should have in mind before engaging with the Angle Protocol:
It is possible to liquidate multiple positions/vaults in just one transaction with Angle. If different positions of the same VaultManager can be liquidated, then both of them can liquidated in one transaction with just one stablecoin transfer from the liquidator and collateral transfer to it.
Liquidations have been designed to be capital-efficient meaning that you can liquidate with no upfront capital: discounted collateral is given first to the liquidator which can in the same transaction swap it to stablecoins to then repay the debt. This is however an optional feature and liquidators could proceed as they normally do in other protocols.
The protocol proposes two different liquidation interfaces for liquidators: one that lets them specify a contract address and data to process a swap if needed, and one which enables them to proceed without this logic. The two different options correspond to the two different liquidate functions in the VaultManager contract.
Discount given to liquidators is not fixed and is a dynamic variable of the health ratio of a vault. Basically the smaller a health ratio, the bigger the discount of a liquidator is.
In some situations, there may be boosts that is to say higher discounts given to liquidators which own veANGLE tokens.
For more details on the Angle Borrowing Module smart contracts and on the contracts affected by liquidation, you can look at this page on the module architecture here and on VaultManager contracts here. All VaultManager addresses can be obtained here.
0. Prerequisites
When making a liquidate() call, you must:
Know the vaults (i.e. the uint256 defining the ID of vaults) which health factor are below 1.
Know the VaultManager (that is the contract corresponding to a collateral type-stablecoin pair in Angle Borrowing Module) in which liquidation should take place: this is the contract in which you will have to call the liquidate function
Choose if you want to swap the collateral obtained from liquidations to stablecoins using some sort of Swapper contract or directly bring the stablecoins to repay. In the first case, you may want to look at our guide here to see how to use Swapper contract in your Angle execution flow.
Know the amount of stablecoins you want to repay in these vaults. There are several ways in which you can estimate this. The optimal way is to rely on the function checkLiquidation defined in each VaultManager contract. When called on a given vaultID that is liquidable, this function returns several elements which can be used in a subsequent liquidation call:
maxStablecoinAmountToRepay: Maximum stablecoin amount that can be repaid by liquidators upon liquidating the vault
maxCollateralAmountToGive: This is the amount of collateral you would receive if you were to repay maxStablecoinAmountToRepay
thresholdRepayAmount: For some vaults, if liquidators were to liquidate a certain portion of their debt, then these vaults may end up with a "dusty" amount of debt of collateral in it. The protocol prevents liquidators from putting vaults in situations like that. As such, a non-null thresholdRepayAmount means that you can repay an amount of the debt either smaller to this thresholdRepayAmount or exactly equal to the maxStablecoinAmountToRepay
discount: Discount you will get on the oracle value price of the collateral
currentDebt: Total amount of debt in the vault
These values may vary in time, as such if you're running a smart contract you may want to embed your call to checkLiquidation in the same transaction as the liquidate call. If you're not sure about the maxStablecoinAmountToRepay, the protocol will round the amount value you pass in the liquidation function to the maxStablecoinAmountToRepay if it is superior to the thresholdRepayAmount in case it is not null or to the maxStablecoinAmountToRepay.
1. Getting vaults to liquidate
Only vaults that have a health factor below 1 can be liquidated. There are multiple ways you can get the health factor of a vault.
The easiest way to identify liquidable vaults is to call in a given VaultManager contract checkLiquidation for all existing vaults (you may simply iterate over the vaultIDCount variable to get all these vaults). Since this just requires repeatedly calling a view function, it does not incur any cost.
2. Executing the liquidation call
As explained above, There are two functions that you can call to liquidate:
1
    function liquidate(
2
        uint256[] memory vaultIDs,
3
        uint256[] memory amounts,
4
        address from,
5
        address to
6
    ) external returns (LiquidatorData memory)
Copied!
And:
1
    function liquidate(
2
        uint256[] memory vaultIDs,
3
        uint256[] memory amounts,
4
        address from,
5
        address to,
6
        address who,
7
        bytes memory data
8
    ) public returns (LiquidatorData memory liqData)
Copied!
Upon choosing the amount of debt of a vault you want to repay, you have the possibility to specify a from address from which stablecoins should be taken. This address should have approved for the stablecoin the address used to trigger the liquidation. You can also specify a to address to which collateral will be sent.
In the second option, you can specify a who contract as well as some data to swap the obtained collateral for stablecoins (or just a portion of it to minimize slippage) efficiently.
3. Processing liquidations result
If you are using a smart contract to liquidate, then you may want to process the results obtained from the liquidation you performed. You basically get different returned values:
stablecoinAmountToReceive: This is the amount of stablecoins you have given for the liquidation
collateralAmountToGive: Current amount of collateral you've gotten from the contract
Note that these returned values are denominated from a protocol perspective and they could be named differently. The contract also returns some utility values which may be less useful to the liquidator:
badDebtFromLiquidation: Bad debt accrued across the liquidation process
oracleValue: Oracle value at which the liquidation took place
newInterestAccumulator: Value of the interestAccumulator at the time of the call (this is a value used to track vaults outstanding debt)
4. Setting up a bot
Depending on your environment, preferred programming tools and languages, your bot should:
Ensure it has enough (or access to enough) funds when liquidating or that it is able to correctly swap the collateral obtained for stablecoins
Calculate the profitability of liquidating loans vs gas costs, taking into account the most lucrative collateral to liquidate.
Ensure it has access to the latest protocol data.
Have the usual fail safes and security you'd expect for any production service.
Calculating profitability vs gas cost.
Be able to estimate slippage in the case where collateral is swapped for stablecoins (or used to mint stablecoins).
Appendix
How is the health factor computed?
The health factor of a vault is computed from the vault's collateral amount (in stablecoin value) multiplied by the current collateral factor divided by the vault's current debt. This debt can be obtained on-chain by querying the function: getVaultDebt.
The forumula for the health factor is then the following:
Health Factor=Collateral Amount (in Stablecoin Value)×Collateral FactorDebt\texttt{Health Factor} = \frac{\texttt{Collateral Amount (in Stablecoin Value)}\times \texttt{Collateral Factor}}{\texttt{Debt}}Health Factor=DebtCollateral Amount (in Stablecoin Value)×Collateral Factor​
To get the necessary values, you can do the following:
1
const collateralAmount = (await vaultManager.vaultData(vaultID))
2
  .collateralAmount
3
const oracleValue = await(await vaultManager.oracle()).read()
4
const collatBase = await collateral.decimals()
5
const collateralFactor = await vaultManager.collateralFactor()
6
const collateralAmountInStablecoinValue = collateralAmount
7
  .mul(oracleValue)
8
  .div(10 ** collatBase)
9
const debt = await vaultManager.getVaultDebt(vaultID)
10
const healthFactor = collateralAmountInStablecoinValue
11
  .mul(collateralFactor)
12
  .div(debt)
Copied!
How is the liquidation discount determined?
The liquidation discount given to liquidators is a function of the health factor of the liquidated vault.
Discount=f(veANGLE delegated balance)(1−Health Factor)\texttt{Discount} = f(\texttt{veANGLE delegated balance})(1-\texttt{Health Factor})Discount=f(veANGLE delegated balance)(1−Health Factor)
This discount is always capped by a maximum discount value defined in each VaultManager contract.
Governance has the opportunity to make the function f(veANGLE delegated balance) constant for all liquidators. To see if this is not the case, you should check the xLiquidationBoost and yLiquidationBoost fields of the corresponding VaultManager contract.
Price oracles
Angle Protocol uses Chainlink as a price oracle. You may find the list of oracle contracts used here.
Flash-Loans
Auto-Leverage and Capital-Efficiency in the Borrowing Module
Last modified 10d ago
Copy link
Contents
0. Prerequisites
1. Getting vaults to liquidate
2. Executing the liquidation call
3. Processing liquidations result
4. Setting up a bot
Appendix
How is the health factor computed?
How is the liquidation discount determined?
Price oracles