Markets & Tranches

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

This page covers the technical details of Lotus market parameters, tranche indexing, market ID derivation, and tranche state variables.

A market's identity is fully determined by its parameters. Any change creates an entirely new market with a new market ID.

---

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.

Per-tranche state variables:

Side	Variable	Description
Supply	supplyAssets	Total loan tokens supplied (with distributed interest)
Supply	supplyShares	Total supply shares outstanding
Supply	pendingInterest	Accrued interest not yet distributed
Borrow	borrowAssets	Total loan tokens borrowed (with accrued interest)
Borrow	borrowShares	Total borrow shares outstanding
Governance	fee	Protocol fee rate (0–25%) on supplier interest
Governance	lastUpdate	Last timestamp interest was accrued

Flow example (3-tranche market):

Variable	Tranche 0 (Senior)	Tranche 1 (Mid)	Tranche 2 (Junior)
supplyAssets	10,000	8,000	6,000
supplyShares	10,000	8,000	6,000
borrowAssets	5,000	4,000	3,000
borrowShares	5,000	4,000	3,000
pendingInterest	50	30	20
fee	5%	5%	5%
lastUpdate	T1	T2	T2

Interest distribution flow:

When borrow interest accrues (e.g., T0 borrowers): borrowAssets[0] increases by newInterest, which is stored in pendingInterest[0].

When a supplier-side operation occurs (e.g., supply to T2), Lotus accrues all tranches 0→2. For each tranche i: pull pendingInterest[i] into cascadingInterest, distribute to tranche i suppliers by utilization, apply the protocol fee (inflate shares to feeRecipient), and cascade any remainder to the next junior tranche. Then update supplyAssets[i] and supplyShares[i].

Fee accrual:

The protocol receives fees via share inflation: feeShares = (supplierInterest × fee) / sharePrice. The feeShares are minted to the feeRecipient address. This does not reduce supplier returns. Fees are taken from interest.