Markets & Tranches

Technical specification of Lotus market parameters, tranche indexing, market ID derivation, and tranche state variables for developers.

What is a Lotus Market?

A Lotus Market is a single lending market composed of N tranches, ordered from most senior (index 0) to most junior (index N-1).

• All tranches in the market share:

  • loanToken: the ERC-20 asset that lenders supply and borrowers borrow

  • IRM (Interest Rate Model): computes borrow rates for each tranche based on utilization

  • liquidationModule: determines liquidation pricing and executes liquidations

• Each tranche can have its own risk configuration:

  • collateralToken: the asset posted as collateral by borrowers in that tranche

  • oracle: price feed used to evaluate account health

  • LLTV: liquidation loan-to-value threshold for that tranche

Important: The tranche index is the canonical identifier for “seniority” inside a market. Any per-tranche parameter arrays are parallel arrays indexed by tranche.

Market Parameters

Each market specifies:

• loanToken: ERC-20 asset for lending and borrowing

• irm: interest rate model that computes tranche borrow rates

• liquidationModule: module that prices and executes liquidations

• collateralTokens[]: per‑tranche collateral token

• oracles[]: per‑tranche price oracle

• lltvs[]: per‑tranche liquidation loan‑to‑value

Market ID

Markets use a deterministic id derived from the full set of market parameters.

Derivation (canonical intent)

• Inputs: loanToken, irm, liquidationModule, and per‑tranche arrays collateralTokens[], oracles[], lltvs[].

• The trancheIndex is implicit via array order (index 0 = most senior).

• The marketId is computed by hashing an ABI‑encoded struct of the above.

Notes

• Exact encoding (types and packing) follows the onchain MarketParams definition. Once published in Reference → Builder Data Directory, mirror the struct there and include worked examples.

• Builders should treat marketId as immutable for a given parameter set. Any parameter change implies a new market.

• Refer to Reference → Markets for the authoritative list of active marketId values per chain.

Example outline (pseudocode)

bytes32 marketId = keccak256(
  abi.encode(
    loanToken,
    irm,
    liquidationModule,
    collateralTokens, // dynamic array order defines trancheIndex
    oracles,
    lltvs
  )
);

Tranche Parameters & Indexing Rules

A market has N tranches, where:

• N == collateralTokens.length == oracles.length == lltvs.length

• tranche i uses:

  • collateralTokens[i]

  • oracles[i]

  • lltvs[i]

Market Creation

When a market is created, the protocol stores the parameters, initializes the IRM with its config, and initializes the liquidation module. From that point, users can lend and borrow across the configured tranches.

Tranche State

Each tranche maintains its own accounting for lender deposits and borrower debt.

Each tranche tracks supply assets/shares, borrow assets/shares, pendingInterest for supplier distribution, a protocol fee (0–25%), and a lastUpdate timestamp.

┌─────────────────────────────────────────────────────────────────────┐
│              Tranche State and Flows                                │
└─────────────────────────────────────────────────────────────────────┘

Per-Tranche State Variables:
═════════════════════════════

┌───────────────────────────────────────────────────────────┐
│                    Tranche i                              │
├───────────────────────────────────────────────────────────┤
│  SUPPLY SIDE:                                             │
│  • supplyAssets: Total loan tokens supplied (with        │
│    distributed interest)                                  │
│  • supplyShares: Total supply shares outstanding         │
│  • pendingInterest: Accrued interest not yet distributed │
│                                                           │
│  BORROW SIDE:                                             │
│  • borrowAssets: Total loan tokens borrowed (with        │
│    accrued interest)                                      │
│  • borrowShares: Total borrow shares outstanding         │
│                                                           │
│  GOVERNANCE:                                              │
│  • fee: Protocol fee rate (0-25%) on supplier interest   │
│  • lastUpdate: Last timestamp interest was accrued       │
└───────────────────────────────────────────────────────────┘

Flow Example (3-Tranche Market):
═════════════════════════════════

 Tranche 0 (Senior)      Tranche 1 (Mid)       Tranche 2 (Junior)
 ─────────────────       ───────────────       ──────────────────

  supplyAssets:           supplyAssets:          supplyAssets:
    10,000                  8,000                  6,000
  supplyShares:           supplyShares:          supplyShares:
    10,000                  8,000                  6,000

  borrowAssets:           borrowAssets:          borrowAssets:
    5,000                   4,000                  3,000
  borrowShares:           borrowShares:          borrowShares:
    5,000                   4,000                  3,000

  pendingInterest:        pendingInterest:       pendingInterest:
    50                      30                     20

  fee:                    fee:                   fee:
    5%                      5%                     5%

  lastUpdate:             lastUpdate:            lastUpdate:
    T1                      T2                     T2

Interest Distribution Flow:
════════════════════════════

When borrow interest accrues (e.g., T0 borrowers):

  1. borrowAssets[0] += newInterest
  2. newInterest → pendingInterest[0]

When supplier-side operation occurs (e.g., supply to T2):

  1. Accrue all tranches 0→2:
     - For each tranche i:
       a. Pull pendingInterest[i] into cascadingInterest
       b. Distribute to tranche i suppliers by utilization
       c. Apply protocol fee (inflate shares to feeRecipient)
       d. Cascade remainder to next junior tranche

  2. Update supplyAssets[i] and supplyShares[i]

Fee Accrual:
════════════

  Protocol receives fees via share inflation:

    feeShares = (supplierInterest × fee) / sharePrice

  feeShares minted to feeRecipient address
  Does NOT reduce supplier returns (fees taken from interest)