Loan Health

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

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.

┌─────────────────────────────────────────────────────────────────────┐
│    Liquidation Quote Paths with Incentive Factor                    │
│           (Oracle Incentive Liquidation Module)                     │
└─────────────────────────────────────────────────────────────────────┘

Position Details:
  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)

Position Health Check:
──────────────────────
  maxBorrow = (1 WETH × 2,100 USDC) × 90% = 1,890 USDC
  actualBorrow = 2,000 USDC

  2,000 > 1,890 → UNHEALTHY → Eligible for liquidation

MODE 1: COLLATERAL-FIRST (liquidator specifies seized amount)
══════════════════════════════════════════════════════════════

  Input: seizedCollateral = 1 WETH (liquidate entire position)

  Calculation flow:
  ┌─────────────┐
  │   Oracle    │
  │ 1 WETH =    │
  │ 2,100 USDC  │
  └──────┬──────┘
         │
         ▼
  ┌───────────────────────────────────────┐
  │  Base collateral value (no incentive) │
  │  1 WETH × 2,100 = 2,100 USDC          │
  └──────────────┬────────────────────────┘
                 │
                 ▼
  ┌───────────────────────────────────────┐
  │  Apply liquidation incentive factor   │
  │  repaidDebt = 2,100 / 1.05            │
  │            = 2,000 USDC               │
  └──────────────┬────────────────────────┘
                 │
                 ▼
  Output: { seized: 1 WETH, repaid: 2,000 USDC }

  Liquidator receives: 1 WETH (worth 2,100 USDC)
  Liquidator pays: 2,000 USDC
  Liquidator profit: 100 USDC (5% incentive)

MODE 2: DEBT-FIRST (liquidator specifies repaid amount)
════════════════════════════════════════════════════════

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

  Calculation flow:
  ┌───────────────────────────────────────┐
  │  Calculate base collateral needed     │
  │  baseValue = 1,000 USDC               │
  └──────────────┬────────────────────────┘
                 │
                 ▼
  ┌───────────────────────────────────────┐
  │  Apply liquidation incentive factor   │
  │  incentivizedValue = 1,000 × 1.05     │
  │                   = 1,050 USDC        │
  └──────────────┬────────────────────────┘
                 │
                 ▼
  ┌───────────────────────────────────────┐
  │  Convert to collateral at oracle price│
  │  seized = 1,050 / 2,100               │
  │        = 0.5 WETH                     │
  └──────────────┬────────────────────────┘
                 │
                 ▼
  Output: { seized: 0.5 WETH, repaid: 1,000 USDC }

  Liquidator receives: 0.5 WETH (worth 1,050 USDC)
  Liquidator pays: 1,000 USDC
  Liquidator profit: 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 liq      │
│ Risk            │ More collateral  │ More predictable │
│                 │ exposure         │ capital needs    │
└─────────────────┴──────────────────┴──────────────────┘