Loan Health

Technical explanation of Lotus loan health checks, oracle integration, modular liquidation architecture, and the Oracle Incentive Liquidation Module.

Loan health determines whether a borrower's position is safe or eligible for liquidation. This page explains how Lotus evaluates health using oracles, LLTVs, and modular liquidation logic.

Lotus modularizes liquidation policy: the core contract handles health checks and accounting, while pluggable liquidation modules handle pricing and execution.

---

Oracles

Lotus is oracle‑agnostic. Markets specify an oracle per tranche, and Lotus only assumes it can retrieve a price for collateral/loan valuation.

Health Check

Oracles are used to evaluate borrower health during:

• borrow()

• withdrawCollateral()

• liquidate()

Healthy means maxBorrow ≥ borrowed for the tranche (see LLTV).

Borrowed amount

Borrowed amount is derived from the borrower's borrowShares at trancheIndex, converted into assets using tranche borrow totals.

Max borrow

Max borrow is derived from collateral amount, oracle price, and the tranche LLTV.

---

Liquidations

Lotus modularizes liquidation policy:

• The core Lotus contract is responsible for:

  • health checks

  • interest accrual

  • collateral approvals

  • position updates

  • bad debt accounting and cascading

• A protocol-approved Liquidation Module is responsible for:

  • liquidation pricing (calculateLiquidation)

  • liquidation execution (executeLiquidation)

Liquidation flow

1. Accrue interest locally for the tranche.

2. Fetch price from oracle; verify the position is unhealthy.

3. Liquidation Module quotes seized collateral vs debt repaid.

4. Update the borrower’s position and compute any bad debt.

5. If bad debt > 0, accrue interest for the full market and cascade loss to current and junior suppliers by utilization.

6. Approve collateral to the module and execute the swap/transfer.

Liquidation Modules are pluggable. The protocol owner enables modules, and new markets choose among them at creation.

---

Oracle Incentive Liquidation Module

The OracleIncentiveLiquidationModule stores a per-tranche liquidationIncentiveFactor and applies it when quoting seized collateral vs repaid debt. It supports both collateral-first and debt-first quote modes.

Worked example. Collateral: 1 WETH. Debt: 2,000 USDC. Oracle price: 1 WETH = 2,100 USDC. LLTV: 90%. Liquidation incentive factor: 1.05 (5% bonus to liquidator).

Health check: maxBorrow = (1 WETH × 2,100 USDC) × 90% = 1,890 USDC. Actual borrow = 2,000 USDC. Since 2,000 > 1,890, the position is unhealthy and eligible for liquidation.

Mode 1: Collateral-first (liquidator specifies seized amount)

Input: seizedCollateral = 1 WETH (liquidate entire position).

Liquidator receives 1 WETH (worth 2,100 USDC), pays 2,000 USDC, and profits 100 USDC (5% incentive).

Mode 2: Debt-first (liquidator specifies repaid amount)

Input: repaidDebt = 1,000 USDC (partial liquidation).

Liquidator receives 0.5 WETH (worth 1,050 USDC), pays 1,000 USDC, and profits 50 USDC (5% incentive).

Comparison:

	Collateral-First	Debt-First
Liquidator sets	Seized amount	Repaid amount
Module computes	Repaid amount	Seized amount
Use case	Full liquidation	Partial liquidation
Risk	More collateral exposure	More predictable capital needs

See Also

• Build → Liquidation Bot for implementing an automated liquidation system

• Build → Liquidation Modules for custom module development

• Learn → Liquidations and Bad Debt for the introductory explanation