Contract API

Exhaustive API reference for every Lotus core contract function including supply, withdraw, borrow, repay, liquidate, flash loan, and view functions.

Every public and external function on the Lotus core contract.

Conventions

Assets vs shares. Functions that move loan tokens accept either assets or shares with the other set to 0. Exactly one must be non-zero.

Rounding. The protocol rounds in its own favor on every conversion:

Operation	Conversion	Direction	Effect
supply	assets → shares	shares rounded DOWN	Fewer shares minted
supply	shares → assets	assets rounded UP	More tokens pulled
withdraw	assets → shares	shares rounded UP	More shares burned
withdraw	shares → assets	assets rounded DOWN	Fewer tokens sent
borrow	assets → shares	shares rounded UP	More debt shares created
borrow	shares → assets	assets rounded DOWN	Fewer tokens sent
repay	assets → shares	shares rounded DOWN	Less debt reduced
repay	shares → assets	assets rounded UP	More tokens pulled
liquidate	bad debt assets	rounded UP	More loss socialized

Accrual scope. Borrow-side accrual is tranche-local (only the target tranche). Supply-side accrual sweeps from tranche 0 up to the target tranche, distributing cascade interest along the way.

Liquidity constraint. Withdraw and borrow are bounded by free supply at the target tranche.

The irmData Parameter

Many functions accept an irmData parameter. This is an opaque bytes payload forwarded to the market's IRM during interest accrual via getTrancheBorrowRate(). The core protocol does not interpret this data. For the AdaptiveLinearKinkIrm (the active IRM at launch), irmData is unused — pass empty bytes ("" in Solidity, "0x" in ethers.js). For ManagedLinearKinkIrm and FixedRateIrm, irmData may encode operator-specific configuration. Check the IRM's documentation for the expected encoding.

The shouldAccrueInterest Parameter

The withdraw function accepts a shouldAccrueInterest boolean. When true, the function sweeps interest from tranche 0 through the target tranche before computing the withdrawal, giving the most accurate share-to-asset conversion. When false, it uses the last-accrued state, which is cheaper in gas but may result in slightly fewer assets received because pending interest has not been distributed yet.

Use true for infrequent, large withdrawals where accuracy matters. Use false for frequent, small withdrawals or when another operation has recently triggered accrual. See Learn → Core Interactions for the conceptual explanation.

---

Lender Functions

supply

function supply(
    MarketParams memory marketParams,
    uint256 trancheIndex,
    uint256 assets,
    uint256 shares,
    address onBehalf,
    bytes calldata data,
    bytes calldata irmData
) external returns (uint256 suppliedAssets, uint256 suppliedShares)

Supplies loan tokens to a tranche, minting supply shares to onBehalf. Accrues interest from tranche 0 through trancheIndex before minting.

Parameter	Type	Description	Required
marketParams	MarketParams	Market configuration identifying the target market	Yes
trancheIndex	uint256	Index of the tranche to supply to (0 = most senior)	Yes
assets	uint256	Amount of loan tokens to supply (0 if using shares)	Exactly one of assets/shares
shares	uint256	Amount of supply shares to mint (0 if using assets)	Exactly one of assets/shares
onBehalf	address	Address to credit with supply shares	Yes
data	bytes	If non-empty, triggers ILotusSupplyCallback.onLotusSupply on msg.sender	No (pass "")
irmData	bytes	Opaque data forwarded to the IRM during accrual	No (pass "")

• Returns: (suppliedAssets, suppliedShares) — actual amounts after rounding

• Reverts: MarketNotCreated, InvalidTrancheIndex, ZeroAddress (if onBehalf is zero), InconsistentInput, InvalidZeroAssetSupply

• Events: Supply(id, msg.sender, onBehalf, trancheIndex, assets, shares)

withdraw

function withdraw(
    MarketParams memory marketParams,
    uint256 trancheIndex,
    uint256 assets,
    uint256 shares,
    address onBehalf,
    address receiver,
    bool shouldAccrueInterest,
    bytes calldata irmData
) external returns (uint256 withdrawnAssets, uint256 withdrawnShares)

Withdraws loan tokens from a tranche, burning supply shares from onBehalf and sending assets to receiver. Caller must be onBehalf or authorized.

Parameter	Type	Description	Required
marketParams	MarketParams	Market configuration identifying the target market	Yes
trancheIndex	uint256	Index of the tranche to withdraw from	Yes
assets	uint256	Amount of loan tokens to withdraw (0 if using shares)	Exactly one of assets/shares
shares	uint256	Amount of supply shares to burn (0 if using assets)	Exactly one of assets/shares
onBehalf	address	Address whose shares are burned	Yes
receiver	address	Address receiving withdrawn tokens	Yes
shouldAccrueInterest	bool	Whether to accrue interest before withdrawal (see above)	Yes
irmData	bytes	Opaque data forwarded to the IRM during accrual	No (pass "")

• Returns: (withdrawnAssets, withdrawnShares) — actual amounts after rounding

• Reverts: MarketNotCreated, InvalidTrancheIndex, ZeroAddress, InconsistentInput, Unauthorized, InvalidZeroAssetWithdrawal, InsufficientLiquidity

• Events: Withdraw(id, msg.sender, onBehalf, trancheIndex, shouldAccrueInterest, assets, shares)

---

Borrower Functions

borrow

function borrow(
    MarketParams memory marketParams,
    uint256 trancheIndex,
    uint256 assets,
    uint256 shares,
    address onBehalf,
    address receiver,
    bytes calldata irmData
) external returns (uint256 borrowedAssets, uint256 borrowedShares)

Borrows loan tokens from a tranche against the borrower's collateral. Accrues interest on the target tranche, checks free supply, and validates that the position remains healthy.

Parameter	Type	Description	Required
marketParams	MarketParams	Market configuration identifying the target market	Yes
trancheIndex	uint256	Index of the tranche to borrow from	Yes
assets	uint256	Amount of loan tokens to borrow (0 if using shares)	Exactly one of assets/shares
shares	uint256	Amount of borrow shares to issue (0 if using assets)	Exactly one of assets/shares
onBehalf	address	Address whose position is debited	Yes
receiver	address	Address receiving borrowed tokens	Yes
irmData	bytes	Opaque data forwarded to the IRM during accrual	No (pass "")

• Returns: (borrowedAssets, borrowedShares) — actual amounts after rounding

• Reverts: MarketNotCreated, InvalidTrancheIndex, ZeroAddress, InconsistentInput, InvalidZeroAssetBorrow, InsufficientLiquidity, UnhealthyAfter

• Events: Borrow(id, msg.sender, onBehalf, receiver, trancheIndex, assets, shares)

repay

function repay(
    MarketParams memory marketParams,
    uint256 trancheIndex,
    uint256 assets,
    uint256 shares,
    address onBehalf,
    bytes calldata data,
    bytes calldata irmData
) external returns (uint256 repaidAssets, uint256 repaidShares)

Repays debt on a tranche, burning borrow shares from onBehalf. Accrues interest on the target tranche only.

Parameter	Type	Description	Required
marketParams	MarketParams	Market configuration identifying the target market	Yes
trancheIndex	uint256	Index of the tranche to repay	Yes
assets	uint256	Amount of loan tokens to repay (0 if using shares)	Exactly one of assets/shares
shares	uint256	Amount of borrow shares to burn (0 if using assets)	Exactly one of assets/shares
onBehalf	address	Address whose debt is being repaid	Yes
data	bytes	If non-empty, triggers ILotusRepayCallback.onLotusRepay on msg.sender	No (pass "")
irmData	bytes	Opaque data forwarded to the IRM during accrual	No (pass "")

• Returns: (repaidAssets, repaidShares) — actual amounts after rounding

• Reverts: MarketNotCreated, InvalidTrancheIndex, ZeroAddress, InconsistentInput, InvalidZeroAssetRepay

• Events: Repay(id, msg.sender, onBehalf, trancheIndex, assets, shares)

supplyCollateral

function supplyCollateral(
    MarketParams memory marketParams,
    uint256 trancheIndex,
    uint256 assets,
    address onBehalf,
    bytes calldata data
) external

Deposits collateral tokens into a tranche. Does not accrue interest or check health (supplying collateral always improves a position).

Parameter	Type	Description	Required
marketParams	MarketParams	Market configuration identifying the target market	Yes
trancheIndex	uint256	Index of the tranche to supply collateral to	Yes
assets	uint256	Amount of collateral tokens to deposit	Yes
onBehalf	address	Address credited with the collateral	Yes
data	bytes	If non-empty, triggers ILotusSupplyCollateralCallback.onLotusSupplyCollateral on msg.sender	No (pass "")

• Reverts: MarketNotCreated, InvalidTrancheIndex, ZeroAddress, InconsistentInput (if assets is zero)

• Events: SupplyCollateral(id, msg.sender, onBehalf, trancheIndex, assets)

withdrawCollateral

function withdrawCollateral(
    MarketParams memory marketParams,
    uint256 trancheIndex,
    uint256 assets,
    address onBehalf,
    address receiver,
    bytes calldata irmData
) external

Withdraws collateral from a tranche. Accrues interest on the target tranche and validates that the position remains healthy after withdrawal. Caller must be onBehalf or authorized.

Parameter	Type	Description	Required
marketParams	MarketParams	Market configuration identifying the target market	Yes
trancheIndex	uint256	Index of the tranche to withdraw collateral from	Yes
assets	uint256	Amount of collateral tokens to withdraw	Yes
onBehalf	address	Address whose collateral is being withdrawn	Yes
receiver	address	Address receiving the collateral	Yes
irmData	bytes	Opaque data forwarded to the IRM during accrual	No (pass "")

• Reverts: MarketNotCreated, InvalidTrancheIndex, ZeroAddress, InconsistentInput, Unauthorized, UnhealthyAfter

• Events: WithdrawCollateral(id, onBehalf, receiver, trancheIndex, assets)

---

Liquidation

liquidate

function liquidate(
    MarketParams memory marketParams,
    uint256 trancheIndex,
    address borrower,
    bytes calldata irmData,
    bytes calldata lmData
) external returns (uint256 seizedAssets, uint256 repaidAssets)

Liquidates an unhealthy position. The liquidation module computes seized collateral and repaid debt. If the borrower's collateral is exhausted but debt remains, the residual is socialized as bad debt across tranches weighted by utilization. Protected by a reentrancy guard.

Parameter	Type	Description	Required
marketParams	MarketParams	Market configuration identifying the target market	Yes
trancheIndex	uint256	Index of the tranche being liquidated	Yes
borrower	address	Address of the borrower to liquidate	Yes
irmData	bytes	Opaque data forwarded to the IRM during accrual	No (pass "")
lmData	bytes	Encoded BaseLiquidationParams for the liquidation module (see below)	Yes

The lmData parameter is decoded by the liquidation module's BaseLiquidationModule base class into:

Field	Type	Description
seizedAssets	uint256	Amount of collateral to seize (0 for share-based mode)
repaidShares	uint256	Amount of borrow shares to repay (0 for asset-based mode)
callbackData	bytes	Optional callback data for ILotusLiquidateCallback

Exactly one of seizedAssets or repaidShares should be non-zero.

• Returns: (seizedAssets, repaidAssets) — collateral seized and debt repaid

• Reverts: MarketNotCreated, InvalidTrancheIndex, ZeroAddress, InvalidCollateralPrice, NotUnderwater, ExcessiveRepay, ExcessiveSeizure

• Events: Liquidate(id, trancheIndex, msg.sender, borrower, repaidAssets, repaidShares, seizedAssets, badDebtAssets, badDebtShares)

---

Market Creation

createMarket

function createMarket(
    MarketParams memory newMarketParams,
    bytes calldata irmParams,
    bytes calldata liquidationParams
) external

Creates a new market. Permissionless — any address can call, but all components must be pre-approved via the admin enablelists. Initializes the IRM and liquidation module for the new market.

Parameter	Type	Description	Required
newMarketParams	MarketParams	Market configuration (see Data Types)	Yes
irmParams	bytes	Encoded initialization parameters for the IRM	Yes
liquidationParams	bytes	Encoded initialization parameters for the liquidation module	Yes

• Reverts: IrmNotEnabled, MarketAlreadyExists, ZeroAddress (liquidation module), LiquidationModuleNotEnabled, InconsistentInput (array length mismatch), LltvNotEnabled

• Events: MarketCreated(Id indexed id, MarketParams marketParams)

• Side effects: Calls IIrm(irm).initialize(id, irmParams) and ILiquidationModule(liquidationModule).initializeMarket(id, liquidationParams)

See Admin for full validation rules and Build → Market Creation for encoding guides.

---

Flash Loans

flashLoan

function flashLoan(address token, uint256 assets, bytes calldata data) external

Transfers assets of token to msg.sender, invokes ILotusFlashLoanCallback.onLotusFlashLoan(assets, data), then pulls assets back. Lotus flash loans charge no fee — the borrower repays exactly the amount borrowed. The flash-loaned token is not restricted to the market's loan token; any ERC-20 held by the contract can be flash-loaned.

Parameter	Type	Description	Required
token	address	ERC-20 token to flash loan	Yes
assets	uint256	Amount to flash loan	Yes
data	bytes	Callback data passed to onLotusFlashLoan	No (pass "")

• Reverts: ZeroValue (if assets is zero)

• Events: FlashLoan(msg.sender, token, assets)

---

Interest Management

accrueInterest

function accrueInterest(MarketParams memory marketParams, bytes calldata irmData) external

Accrues borrow interest and distributes supplier interest across all tranches of the market. Interest cascades from junior tranches to senior tranches via the pending interest mechanism. Protocol fees are distributed as supply shares to the fee recipient.

Parameter	Type	Description	Required
marketParams	MarketParams	Market configuration identifying the target market	Yes
irmData	bytes	Opaque data forwarded to the IRM	No (pass "")

• Reverts: MarketNotCreated

• Events: AccrueInterest(id)

• Note: No-op if block.timestamp equals lastUpdate for all tranches.

accrueInterestAndReturnMaxBorrow

function accrueInterestAndReturnMaxBorrow(
    MarketParams memory marketParams,
    uint256 trancheIndex,
    address onBehalf,
    bytes calldata irmData
) external returns (uint256 borrowed, uint256 maxBorrow)

Accrues interest on the market and returns the borrower's current debt and maximum borrowing capacity for the given tranche. Intended primarily for off-chain queries — call this statically (eth_call) to avoid spending gas on-chain.

Parameter	Type	Description	Required
marketParams	MarketParams	Market configuration identifying the target market	Yes
trancheIndex	uint256	Tranche to check	Yes
onBehalf	address	Borrower address to query	Yes
irmData	bytes	Opaque data forwarded to the IRM	No (pass "")

• Returns:

  • borrowed — current borrow assets after accrual

  • maxBorrow — maximum borrow allowed given collateral, oracle price, and LLTV

• Reverts: MarketNotCreated

• Events: AccrueInterest(id)

---

Authorization

setAuthorization

function setAuthorization(address authorized, bool newIsAuthorized) external

Grants or revokes protocol-wide authorization for authorized to act on behalf of msg.sender. Authorized addresses can call withdraw, borrow, and withdrawCollateral with onBehalf set to the authorizer.

Parameter	Type	Description	Required
authorized	address	Address to authorize or revoke	Yes
newIsAuthorized	bool	true to authorize, false to revoke	Yes

• Reverts: AuthorizationAlreadySet

• Events: SetAuthorization(msg.sender, msg.sender, authorized, newIsAuthorized)

setAuthorizationWithSig

function setAuthorizationWithSig(Authorization memory authorization, Signature calldata signature) external

Grants or revokes authorization using an EIP-712 signed message. See Authorization for the typed data format.

Parameter	Type	Description	Required
authorization	Authorization	Struct: {authorizer, authorized, isAuthorized, nonce, deadline}	Yes
signature	Signature	ECDSA signature: {v, r, s}	Yes

• Reverts: SignatureExpired, InvalidNonce, InvalidSignature

• Events: IncrementNonce(msg.sender, authorizer, nonce), SetAuthorization(msg.sender, authorizer, authorized, isAuthorized)

---

View Functions

View functions return the last-accrued state. If interest has not been accrued recently, supply and borrow asset values may be stale. Call accrueInterest() first for up-to-date values.

Market Structure

getMarketParams(Id id) → MarketParams memory

Returns the full market configuration (loan token, IRM, liquidation module, per-tranche collateral tokens, oracles, and LLTVs).

getMarketTranches(Id id) → Tranche[] memory

Returns the state of every tranche in the market. Each Tranche struct contains:

Field	Type	Description
trancheSupplyAssets	uint128	Total supplied assets
trancheSupplyShares	uint128	Total supply shares
trancheBorrowAssets	uint128	Total borrowed assets
trancheBorrowShares	uint128	Total borrow shares
pendingInterest	uint128	Interest awaiting distribution to suppliers
fee	uint128	Protocol fee fraction (WAD)
lastUpdate	uint128	Timestamp of last interest accrual

getNumMarketTranches(Id id) → uint256

Returns the number of tranches in the market.

getMarketIrm(Id id) → IIrm

Returns the IRM contract address for the market.

lastUpdate(Id id, uint256 trancheIndex) → uint128

Returns the timestamp of the last interest accrual for a specific tranche. Returns 0 if the tranche index is out of bounds.

Positions

getPosition(Id id, address user) → Position memory

Returns the user's position in the market. The Position struct contains:

Field	Type	Description
supplyShares	uint256[]	Supply shares per tranche
borrowShares	uint128[]	Borrow shares per tranche
collateral	uint128[]	Collateral balance per tranche

Array indices correspond to tranche indices. Values reflect the last-accrued state.

Accounting

getJrNetSupply(Id id) → uint256[] memory

Returns an array of junior net supply values, one per tranche. Index i represents the cumulative supply minus cumulative borrow from tranche i through all more junior tranches.

getJrSupply(Id id, uint256 trancheIndex) → uint256

Returns the junior supply at trancheIndex: the total supply from that tranche through all more junior tranches.

getFreeSupply(Id id, uint256 trancheIndex) → uint256

Returns the free supply at trancheIndex: the minimum junior net supply across tranches 0 through trancheIndex. This is the amount available for borrowing or withdrawal.

getTrancheUtilization(Id id, uint256 trancheIndex) → uint256

Returns the utilization of a tranche in WAD (1e18 = 100%). Computed as 1 - freeSupply / jrSupply. Returns 0 if junior supply is zero.

getTrancheUtilization(uint256 jrSupply, uint256 freeSupply) → uint256 (pure)

Helper that computes utilization from raw values without reading state. Same formula: 1 - freeSupply / jrSupply.

Hooks

getMarketHookConfig(Id id) → (address hook, uint256 permissions)

Returns the hook contract address and permissions bitmask for the market. See Admin for permission flag values.

Authorization Views

isAuthorized(address authorizer, address authorized) → bool

Returns whether authorized can act on behalf of authorizer.

nonce(address authorizer) → uint256

Returns the current nonce for EIP-712 signature validation.

Admin Views

owner() → address — current admin address.

feeRecipient() → address — current fee recipient.

isIrmEnabled(address) → bool — whether an IRM is in the enablelist.

isLltvEnabled(uint256) → bool — whether an LLTV value is in the enablelist.

isLiquidationModuleEnabled(address) → bool — whether a liquidation module is in the enablelist.

See Admin for complete admin function documentation.

---

Data Types

MarketParams

Field	Type	Description
loanToken	address	ERC-20 loan token for the market
irm	address	Interest rate model contract
liquidationModule	address	Liquidation module contract
collateralTokens	address[]	Collateral token per tranche
oracles	address[]	Oracle per tranche
lltvs	uint128[]	LLTV per tranche (WAD)

Authorization

Field	Type	Description
authorizer	address	Signer granting authorization
authorized	address	Address being authorized
isAuthorized	bool	true to grant, false to revoke
nonce	uint256	Must match current nonce(authorizer)
deadline	uint256	Signature expiry timestamp

Signature

Field	Type	Description
v	uint8	ECDSA recovery id
r	bytes32	ECDSA r component
s	bytes32	ECDSA s component

---

See Also

• Learn → Core Interactions for conceptual explanation

• Learn → Protocol Accounting for interest cascade mechanics

• Build → Flash Actions for callback patterns

• Reference → Authorization for EIP-712 typed data

• Reference → Admin for admin function documentation

• Reference → Oracles for price scale and decimal handling