Oracles

Reference for Lotus oracle integration covering IOracle interface, price scale formula, decimal handling, and worked examples for WETH/USDC and wstETH/USDC.

Each tranche specifies an oracle via MarketParams.oracles[trancheIndex]. Oracles must implement IOracle.price().

Price Scale and Decimals

• IOracle.price() returns the price of 1 collateral asset in units of the loan token, scaled by 1e36.

• Interpretation:

  • Let cDec = decimals(collateral), lDec = decimals(loanToken).

  • price() corresponds to 10^cDec collateral priced in 10^lDec loan tokens with 36 + lDec − cDec precision.

• Max borrow uses: maxBorrow = collateralAmount * price / 1e36 * LLTV / 1e18 (see LLTV).

Safety Considerations

• Prefer robust, manipulation‑resistant sources (medianized, TWAPs, bounds).

• Understand update frequency and liveness guarantees.

• Ensure oracle asset pairs match the market’s collateral and loan token semantics.

Responsibilities

• Oracle correctness is critical; users should prefer markets with proven oracle configurations.

• Liquidation modules receive price() to quote seize/repay amounts.

Worked Example — WETH/USDC

WETH collateral, USDC loan token.

Token decimals:

• WETH (collateral): 18 decimals (cDec = 18)

• USDC (loan token): 6 decimals (lDec = 6)

Current ETH price: $2,000 USDC

Step 1 — Oracle price. The oracle returns the price of 10^cDec collateral in 10^lDec loan units, scaled by 10^(36 + lDec - cDec):

• Scale factor: 10^(36 + 6 - 18) = 10^24

• 1 WETH = 2,000 USDC

• oracle.price() = 2000 × 10^24 = 2_000e24

Step 2 — Collateral value. For 10 WETH of collateral:

• collateralAmount = 10e18 (10 WETH in 18 decimal units)

• collateralValue = collateralAmount × price / ORACLE_PRICE_SCALE

• collateralValue = 10e18 × 2_000e24 / 1e36 = 20_000e6 (20,000 USDC in 6 decimal units)

Step 3 — Maximum borrow. With LLTV = 90% (0.9e18):

• maxBorrow = collateralValue × LLTV / WAD

• maxBorrow = 20_000e6 × 0.9e18 / 1e18 = 18_000e6 (18,000 USDC)

Second example — wstETH/USDC. If wstETH also has 18 decimals and prices at $2,300:

• oracle.price() = 2_300e24

• For 5 wstETH: collateralValue = 5e18 × 2_300e24 / 1e36 = 11_500e6

• With LLTV 85%: maxBorrow = 11_500e6 × 0.85e18 / 1e18 = 9_775e6 (9,775 USDC)

The formula generalizes to any decimal pair. The oracle price always has 36 + lDec - cDec digits of precision, and the ORACLE_PRICE_SCALE (1e36) cancels the scaling in the division.

See also

• Reference → Contract API; Admin (enablelists)

• Build → Liquidation Bot for using oracle prices in liquidation logic

• Build → Market Creation for configuring oracles at market creation

• Reference → Glossary (LLTV)