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.

Custom liquidation modules handle real funds. Prefer audited, manipulation-resistant oracle sources, enforce safe parameter ranges, and treat all external calls as untrusted.

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 audited, manipulation-resistant 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 Checklist

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.

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 → Loan Health for liquidation flow

• Build → Liquidation Bot for a complete liquidation recipe