Liquity Protocol — DeFi Protocol Explained from Its Smart Contracts (Part 1)

Considering how much we have to learn about DeFi protocols in order to improve our auditing skills, here is the first part about Liquity protocol — explained directly from its smart contracts.

Content

• Introduction
• Tokens
• What is a Trove?
• Borrowing
• PriceFeed and Oracle

Introduction

Tokens

What is LUSD?

1function mint(address _account, uint256 _amount) external override {
2    _requireCallerIsBorrowerOperations();
3    _mint(_account, _amount);
4}

What is LQTY?

1function issueLQTY() external override returns (uint) {
2    _requireCallerIsStabilityPool();
3
4    uint latestTotalLQTYIssued = LQTYSupplyCap
5        .mul(_getCumulativeIssuanceFraction())
6        .div(DECIMAL_PRECISION);
7    uint issuance = latestTotalLQTYIssued.sub(totalLQTYIssued);
8
9    totalLQTYIssued = latestTotalLQTYIssued;
10    emit TotalLQTYIssuedUpdated(latestTotalLQTYIssued);
11
12    return issuance;
13}

1function sendLQTY(address _account, uint _LQTYamount) external override {
2    _requireCallerIsStabilityPool();
3    lqtyToken.transfer(_account, _LQTYamount);
4}

1// Allocate 2 million for bounties/hackathons
2_mint(_bountyAddress, bountyEntitlement);
3uint bountyEntitlement = _1_MILLION.mul(2);
4
5// Allocate 32 million to the algorithmic issuance schedule
6uint depositorsAndFrontEndsEntitlement = _1_MILLION.mul(32);
7_mint(_communityIssuanceAddress, depositorsAndFrontEndsEntitlement);
8
9// Allocate 1.33 million for LP rewards
10uint _lpRewardsEntitlement = _1_MILLION.mul(4).div(3);
11lpRewardsEntitlement = _lpRewardsEntitlement;
12_mint(_lpRewardsAddress, _lpRewardsEntitlement);
13
14// Allocate the remainder to the LQTY Multisig:
15// (100 - 2 - 32 - 1.33) million = 64.66 million
16uint multisigEntitlement = _1_MILLION.mul(100)
17    .sub(bountyEntitlement)
18    .sub(depositorsAndFrontEndsEntitlement)
19    .sub(_lpRewardsEntitlement);
20
21_mint(_multisigAddress, multisigEntitlement);

What is a Trove?

1struct Trove {
2    uint debt;
3    uint coll;
4    uint stake;
5    Status status;
6    uint128 arrayIndex;
7}

TroveManager.sol

1enum TroveManagerOperation {
2    applyPendingRewards,
3    liquidateInNormalMode,
4    liquidateInRecoveryMode,
5    redeemCollateral
6}

1// Single liquidation function.
2// Closes the trove if its ICR is lower than the minimum collateral ratio.
3function liquidate(address _borrower) external
4
5// Liquidate one trove, in Normal Mode.
6function _liquidateNormalMode(
7    IActivePool _activePool,
8    IDefaultPool _defaultPool,
9    address _borrower,
10    uint _LUSDInStabPool
11) internal returns (LiquidationValues memory singleLiquidation)
12
13// Liquidate one trove, in Recovery Mode.
14function _liquidateRecoveryMode(
15    IActivePool _activePool,
16    IDefaultPool _defaultPool,
17    address _borrower,
18    uint _ICR,
19    uint _LUSDInStabPool,
20    uint _TCR,
21    uint _price
22) internal returns (LiquidationValues memory singleLiquidation)
23
24/*
25 * Liquidate a sequence of troves. Closes a maximum number of
26 * n under-collateralized Troves, starting from the one with
27 * the lowest collateral ratio in the system, and moving upwards.
28 */
29function liquidateTroves(uint _n) external

1function redeemCollateral(
2    uint _LUSDamount,
3    address _firstRedemptionHint,
4    address _upperPartialRedemptionHint,
5    address _lowerPartialRedemptionHint,
6    uint _partialRedemptionHintNICR,
7    uint _maxIterations,
8    uint _maxFeePercentage
9) external

1ContractsCache memory contractsCache = ContractsCache(
2    activePool,
3    defaultPool,
4    lusdToken,
5    lqtyStaking,
6    sortedTroves,
7    collSurplusPool,
8    gasPoolAddress
9);

1// To confirm redeemer's balance is less than total LUSD supply
2assert(
3    contractsCache.lusdToken.balanceOf(msg.sender)
4        <= totals.totalLUSDSupplyAtStart
5);
6
7// To add the borrower's coll and debt rewards earned
8// from redistributions, to their Trove
9_applyPendingRewards(
10    contractsCache.activePool,
11    contractsCache.defaultPool,
12    currentBorrower
13);
14
15// To send the ETH fee to the LQTY staking contract
16contractsCache.activePool.sendETH(
17    address(contractsCache.lqtyStaking),
18    totals.ETHFee
19);
20contractsCache.lqtyStaking.increaseF_ETH(totals.ETHFee);

1enum Status {
2    nonExistent,
3    active,
4    closedByOwner,
5    closedByLiquidation,
6    closedByRedemption
7}

SortedTroves.sol

1function _insert(
2    ITroveManager _troveManager,
3    address _id,
4    uint256 _NICR,
5    address _prevId,
6    address _nextId
7) internal

1// List must not be full
2require(!isFull(), "SortedTroves: List is full");
3// List must not already contain node
4require(!contains(_id), "SortedTroves: List already contains the node");
5// Node id must not be null
6require(_id != address(0), "SortedTroves: Id cannot be zero");
7// NICR must be non-zero
8require(_NICR > 0, "SortedTroves: NICR must be positive");

Borrowing

How is the borrowing fee calculated?

BorrowerOperations.sol

1enum BorrowerOperation {
2    openTrove,
3    closeTrove,
4    adjustTrove
5}

1struct ContractsCache {
2    ITroveManager troveManager;
3    IActivePool activePool;
4    ILUSDToken lusdToken;
5}

openTrove()

1function openTrove(
2    uint _maxFeePercentage,
3    uint _LUSDAmount,
4    address _upperHint,
5    address _lowerHint
6) external payable

1function _requireValidMaxFeePercentage(
2    uint _maxFeePercentage,
3    bool _isRecoveryMode
4) internal pure {
5    if (_isRecoveryMode) {
6        require(
7            _maxFeePercentage <= DECIMAL_PRECISION,
8            "Max fee percentage must less than or equal to 100%"
9        );
10    } else {
11        require(
12            _maxFeePercentage >= BORROWING_FEE_FLOOR
13                && _maxFeePercentage <= DECIMAL_PRECISION,
14            "Max fee percentage must be between 0.5% and 100%"
15        );
16    }
17}

1function _requireTroveisNotActive(
2    ITroveManager _troveManager,
3    address _borrower
4) internal view {
5    uint status = _troveManager.getTroveStatus(_borrower);
6    require(status != 1, "BorrowerOps: Trove is active");
7}

1contractsCache.troveManager.setTroveStatus(msg.sender, 1);
2contractsCache.troveManager.increaseTroveColl(msg.sender, msg.value);
3contractsCache.troveManager.increaseTroveDebt(msg.sender, vars.compositeDebt);

1sortedTroves.insert(msg.sender, vars.NICR, _upperHint, _lowerHint);
2vars.arrayIndex = contractsCache.troveManager.addTroveOwnerToArray(msg.sender);

1// Move the ether to the Active Pool, and mint the LUSDAmount to the borrower
2_activePoolAddColl(contractsCache.activePool, msg.value);
3_withdrawLUSD(
4    contractsCache.activePool,
5    contractsCache.lusdToken,
6    msg.sender,
7    _LUSDAmount,
8    vars.netDebt
9);

1// Move the LUSD gas compensation to the Gas Pool
2_withdrawLUSD(
3    contractsCache.activePool,
4    contractsCache.lusdToken,
5    gasPoolAddress,
6    LUSD_GAS_COMPENSATION,
7    LUSD_GAS_COMPENSATION
8);

closeTrove()

1function closeTrove() external

1_requireTroveisActive(troveManagerCached, msg.sender);
2uint price = priceFeed.fetchPrice();
3_requireNotInRecoveryMode(price);

1troveManagerCached.removeStake(msg.sender);
2troveManagerCached.closeTrove(msg.sender);

1_repayLUSD(activePoolCached, lusdTokenCached, msg.sender,
2    debt.sub(LUSD_GAS_COMPENSATION));
3_repayLUSD(activePoolCached, lusdTokenCached, gasPoolAddress,
4    LUSD_GAS_COMPENSATION);

1activePoolCached.sendETH(msg.sender, coll);

PriceFeed and Oracle

• Frozen (for both oracles): last price update more than 4 hours ago
• Broken (for both oracles): response call reverted, invalid timeStamp that is either 0 or in the future, or reported price is non-positive (Chainlink) or zero (Tellor). Chainlink is considered broken if either the response for the latest round or the response for the round before the latest fails one of these conditions.
• PriceChangeAboveMax (Chainlink only): higher than 50% deviation between two consecutive price updates

Get in touch