IRM Authoring

Complete guide to designing, configuring, and operating custom interest rate models for Lotus markets including adaptive, managed, and fixed rate curves.

Lotus lets markets choose their interest rate model (IRM). This page covers how to author and operate IRMs safely.

Custom IRMs must enforce guardrails (min/max rates, max per-update delta, min update intervals) to prevent runaway rate behavior. See the configuration bounds below.

When to Build a Custom IRM

Build a custom IRM when the default adaptive linear kink model does not match your market's rate dynamics:

• You need a distinct rate policy per collateral or market structure.

• You want managed parameters (operator‑driven) vs adaptive (signal‑driven).

Design Choices

• Curve family: linear kink, exponential, fixed, or hybrid.

• Control strategy: adaptive (auto‑tuning) vs managed (operator updates).

• Guardrails: min/max rates, max per‑update delta, min update interval, grace periods.

Configuration Bounds

• Target utilization: choose ranges that reflect realistic liquidity goals.

• Base/target rates: express in per‑second wads; cap global maxima.

• Slopes: enforce non‑negative slopes; cap steep region aggressiveness.

Operational Safeguards

• Timelocks or staged changes for managed models.

• Pausable adaptation for adaptive models.

• Eventing for visibility (config changes, updates, out‑of‑band corrections).

Minimal IRM Implementation

Every IRM must implement the IIrm interface: initialize for setup and getTrancheBorrowRate for rate computation.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import {IIrm} from "lotus/src/interfaces/IIrm.sol";
import {Id} from "lotus/src/interfaces/ILotus.sol";

/// @notice A fixed-rate IRM that returns a constant borrow rate per tranche.
contract SimpleFixedRateIrm is IIrm {
    /// @dev Per-market, per-tranche fixed rate in WAD per second.
    mapping(Id => mapping(uint256 => uint256)) public rates;

    function initialize(Id id, bytes calldata irmParams) external override {
        uint256[] memory trancheRates = abi.decode(irmParams, (uint256[]));
        for (uint256 i = 0; i < trancheRates.length; i++) {
            rates[id][i] = trancheRates[i];
        }
    }

    function getTrancheBorrowRate(
        Id id,
        uint256 trancheIndex,
        uint256, /* trancheUtilization */
        bytes calldata /* irmData */
    ) external view override returns (uint256) {
        return rates[id][trancheIndex];
    }
}

Function	Purpose
initialize	Called once at market creation; decode irmParams and store config
getTrancheBorrowRate	Called on every interest accrual; return rate in WAD per second

Testing Checklist

• Low/mid/high utilization scenarios; kink transition continuity.

• Stress tests for update cadence and max change bounds.

• Interaction with tranche utilization computation and accrual cadence.

Guardrails applied:

• Grace period: dampens updates for new markets.

• Min update interval: prevents rapid-fire rate changes.

• Max rate change: caps delta per update for stability.

• Rate bounds: absolute min/max rate limits.

• Interaction count: optional seeding protection.

See Also

• Learn → Interest Rate Models (IRMs) for conceptual background

• Build → Market Creation for encoding IRM parameters at market creation