Liquidation Modules

Guide to building custom liquidation modules for Lotus including BaseLiquidationParams encoding, lmData structure, and the OracleIncentive module.

Liquidation Modules price and execute liquidations for a market. The core protocol verifies health, accrues interest, updates positions, and accounts for bad debt; your module focuses on pricing and settlement.

When to Build a Custom Module

Build a custom liquidation module when the default pricing logic does not fit your market's needs:

• Collateral needs a bespoke pricing path (e.g., onchain oracle basket, TWAPs, RFQ).

• You want to embed incentives/penalties tailored to the asset or venue.

• You need callbacks to external venues or routers.

Module Interface

Every liquidation module must implement three functions:

• initializeMarket: accept ABI‑encoded params and store per‑market/tranche config.

• calculateLiquidation: quote seized collateral and debt repaid given tranche state and a price.

• executeLiquidation: settle the transfer(s) using approvals from Lotus.

Design Tips

• Pricing: prefer robust sources (medianized or bounded) and clear incentive factors.

• Liveness: handle edge cases when liquidity is thin; fail gracefully with clear errors.

• Reentrancy: treat callbacks and external calls as untrusted; use checks‑effects‑interactions.

• Allowlisting: consider limiting venues or tokens to reduce routing risk.

• Param bounds: enforce safe ranges; expose events for offchain monitoring.

Testing and Security

Testing checklist:

• Healthy vs unhealthy gating; partial vs full liquidation.

• Incentive behavior across price shocks.

• Fallback paths and revert reasons.

• Interaction with interest accrual and bad debt cascade.

Security notes:

• Avoid token approvals that persist beyond call scope; reset to zero when practical.

• Do not assume token transfer return values; use safe transfer libs.

• Consider pausing logic or controllers for venues.

┌─────────────────────────────────────────────────────────────────────┐
│         Liquidation Module: Pricing and Execution Flow              │
└─────────────────────────────────────────────────────────────────────┘

 Liquidator        Lotus Core          Liquidation Module       Oracle
 ──────────        ──────────          ──────────────────       ──────
      │                 │                      │                  │
      │  liquidate(     │                      │                  │
      │    borrower,    │                      │                  │
      │    seized/repaid│                      │                  │
      │    amounts)     │                      │                  │
      ├────────────────►│                      │                  │
      │                 │                      │                  │
      │                 │  [1] Accrue interest │                  │
      │                 │      for tranche     │                  │
      │                 │                      │                  │
      │                 │  [2] Get price       │                  │
      │                 ├─────────────────────────────────────────►│
      │                 │                      │                  │
      │                 │      Return price    │                  │
      │                 │◄─────────────────────────────────────────┤
      │                 │                      │                  │
      │                 │  [3] Check health    │                  │
      │                 │      (must be unhealthy)                │
      │                 │                      │                  │
      │                 │  calculateLiquidation(                  │
      │                 │    marketParams,     │                  │
      │                 │    trancheIndex,     │                  │
      │                 │    borrower,         │                  │
      │                 │    seized/repaid,    │                  │
      │                 │    price)            │                  │
      │                 ├─────────────────────►│                  │
      │                 │                      │                  │
      │                 │             Apply incentive factor:     │
      │                 │             Quote seized collateral     │
      │                 │             vs repaid debt              │
      │                 │                      │                  │
      │                 │  Return quote        │                  │
      │                 │  (seized, repaid)    │                  │
      │                 │◄─────────────────────┤                  │
      │                 │                      │                  │
      │                 │  [4] Update position │                  │
      │                 │      Reduce collateral                  │
      │                 │      Reduce debt     │                  │
      │                 │                      │                  │
      │                 │  [5] Calculate bad debt                 │
      │                 │      If debt > collateral value:        │
      │                 │      - Accrue full market               │
      │                 │      - Cascade loss to suppliers        │
      │                 │                      │                  │
      │                 │  [6] Approve collateral                 │
      │                 │      to module       │                  │
      │                 │                      │                  │
      │                 │  executeLiquidation( │                  │
      │                 │    collateralToken,  │                  │
      │                 │    seized,           │                  │
      │                 │    liquidator)       │                  │
      │                 ├─────────────────────►│                  │
      │                 │                      │                  │
      │                 │           Transfer collateral           │
      │                 │           to liquidator                 │
      │                 │                      │                  │
      │                 │      Complete        │                  │
      │                 │◄─────────────────────┤                  │
      │                 │                      │                  │
      │  Success ✓      │                      │                  │
      │  (collateral    │                      │                  │
      │   received)     │                      │                  │
      │◄────────────────┤                      │                  │
      │                 │                      │                  │

Module Responsibilities:
┌──────────────────────────────────────────────────────────────┐
│ calculateLiquidation(): Pricing logic                       │
│  - Apply incentive factors                                  │
│  - Support collateral-first or debt-first modes             │
│  - Return seized collateral and repaid debt amounts         │
│                                                              │
│ executeLiquidation(): Settlement logic                      │
│  - Transfer seized collateral to liquidator                 │
│  - Handle routing (direct transfer, DEX swap, etc.)         │
│  - Emit events for transparency                             │
└──────────────────────────────────────────────────────────────┘

Encoding lmData

When calling lotus.liquidate(), the lmData parameter is an opaque bytes payload decoded by the market's liquidation module. The BaseLiquidationModule base class decodes it into a BaseLiquidationParams struct:

struct BaseLiquidationParams {
    uint256 seizedAssets;    // Collateral to seize (0 if using repaidShares)
    uint256 repaidShares;    // Borrow shares to repay (0 if using seizedAssets)
    bytes callbackData;      // Optional data for ILotusLiquidateCallback
}

Exactly one of seizedAssets or repaidShares must be non-zero. The module uses the non-zero value to compute the other via the oracle price and incentive factor.

Solidity encoding:

// Asset-based: specify collateral to seize
bytes memory lmData = abi.encode(BaseLiquidationParams({
    seizedAssets: 5e18,
    repaidShares: 0,
    callbackData: ""
}));

// Share-based: specify debt shares to repay
bytes memory lmData = abi.encode(BaseLiquidationParams({
    seizedAssets: 0,
    repaidShares: borrowSharesToRepay,
    callbackData: ""
}));

TypeScript encoding:

const lmData = ethers.AbiCoder.defaultAbiCoder().encode(
  ["tuple(uint256 seizedAssets, uint256 repaidShares, bytes callbackData)"],
  [{ seizedAssets: 0n, repaidShares: sharesToRepay, callbackData: "0x" }]
);

For a complete liquidation bot implementation using lmData, see Build → Liquidation Bot.

See also:

• Learn → Advanced → Loan Health for liquidation flow.

• Build → Liquidation Bot for a complete liquidation recipe.

• Reference → Security & Risk for systemic considerations.