Core Interactions

Technical reference for all Lotus core interactions including supply, withdraw, borrow, repay, collateral management, and the shouldAccrueInterest tradeoff.

Lotus exposes six core operations: supply, withdraw, borrow, repay, supply collateral, and withdraw collateral. Each operates on a specific market and tranche, and most trigger interest accrual. Rounding and accrual scope details are in Reference → Contract API.

┌─────────────────────────────────────────────────────────────────────┐
│              User Flows Across Tranches                             │
└─────────────────────────────────────────────────────────────────────┘

LENDER FLOW:
════════════

  Lender                Lotus Market (USDC/WETH)
  ──────                ────────────────────────
                        Tranche 0 (LLTV 80%) ← Senior
                        Tranche 1 (LLTV 85%)
                        Tranche 2 (LLTV 90%) ← Junior
    │
    │  supply(market, tranche=2, 1000 USDC)
    ├─────────────────────────────────────────►
    │                   │
    │                   │ Accrue interest (0→2)
    │                   │ Mint supply shares
    │                   │ Update tranche 2 supply
    │                   │
    │  Receive shares   │
    │◄──────────────────┤
    │                   │
    │                   ▼ Interest cascade:
    │                   ┌────────────────────┐
    │                   │ T0 borrows → T0,T1,T2 suppliers
    │                   │ T1 borrows → T1,T2 suppliers
    │                   │ T2 borrows → T2 suppliers only
    │                   └────────────────────┘
    │
    │  withdraw(market, tranche=2, shares)
    ├─────────────────────────────────────────►
    │                   │
    │                   │ Accrue interest (0→2) [if enabled]
    │                   │ Check [free supply](../../reference/glossary.md#free-supply)
    │                   │ Burn shares, transfer assets
    │                   │
    │  Receive USDC     │
    │◄──────────────────┤

BORROWER FLOW:
══════════════

  Borrower              Lotus Market (USDC/WETH)
  ────────              ────────────────────────
                        Tranche 1 (LLTV 85%, collateral: WETH)
    │
    │  supplyCollateral(market, tranche=1, 10 WETH)
    ├─────────────────────────────────────────►
    │                   │
    │                   │ Update collateral balance
    │                   │
    │                   │
    │  borrow(market, tranche=1, 15,000 USDC)
    ├─────────────────────────────────────────►
    │                   │
    │                   │ Accrue interest (tranche 1)
    │                   │ Check free supply ≥ 15,000
    │                   │ Check health (WETH value vs LLTV)
    │                   │ Mint borrow shares
    │                   │
    │  Receive USDC     │
    │◄──────────────────┤
    │                   │
    │                   ▼ Position active:
    │                   ┌────────────────────┐
    │                   │ 10 WETH collateral │
    │                   │ 15,000 USDC debt   │
    │                   │ Health: 1.42x      │
    │                   └────────────────────┘
    │
    │  repay(market, tranche=1, 15,000 USDC + interest)
    ├─────────────────────────────────────────►
    │                   │
    │                   │ Accrue interest (tranche 1)
    │                   │ Burn borrow shares
    │                   │
    │                   │
    │  withdrawCollateral(market, tranche=1, 10 WETH)
    ├─────────────────────────────────────────►
    │                   │
    │                   │ Accrue interest (tranche 1)
    │                   │ Check health (must remain healthy)
    │                   │ Transfer collateral
    │                   │
    │  Receive WETH     │
    │◄──────────────────┤

Lending

Lenders supply the market's loan token into a specific tranche to earn yield. Supplied liquidity can also be used by borrowers in more senior tranches (lower index).

Supply

• Specify either assets or shares (the other is set to 0).

• Supplying accrues interest for all tranches up to and including your tranche, so supplier balances used in the operation are up to date.

• Optional: pass callback data for advanced, atomic strategies.

Withdraw

• Specify either assets or shares (the other is set to 0).

• Choose a gas/accuracy tradeoff via shouldAccrueInterest:

  • true: accrue interest for all tranches up to and including your tranche (most accurate; higher gas).

  • false: skip accrual (cheaper); share price may be slightly stale so you may receive fewer assets than in fully accrued state.

Note: Available withdrawal is bounded by the tranche’s current free supply, which reflects liquidity sharing across tranches.

Borrowing

Borrowers post collateral into a specific tranche and borrow the market's loan token against it. Each tranche has its own collateral token, oracle, and liquidation loan-to-value (LLTV).

Borrow

• Specify either assets or shares (the other set to 0).

• Interest accrues only for the specified tranche.

• Constraints: requested borrow must be ≤ the tranche's free supply, and the position must remain healthy under that tranche's oracle and LLTV.

Repay

• Specify either assets or shares (the other set to 0).

• Accrues interest only for the specified tranche.

• Optional: pass callback data for atomic strategies (e.g., refinance).

Collateral Management

Supply Collateral

• Increases borrowing capacity in the specified tranche.

• Does not accrue interest.

Withdraw Collateral

• Reduces borrowing capacity in the specified tranche.

• Accrues interest only for the specified tranche and must leave the position healthy after withdrawal.

The shouldAccrueInterest Tradeoff

The shouldAccrueInterest parameter on withdraw() controls whether Lotus accrues interest across all tranches up to the target tranche before computing the withdrawal.

• true — distributes pending interest before burning shares, giving the most accurate share-to-asset conversion. Higher gas.

• false — skips accrual and uses stale state. Cheaper, but the lender receives slightly fewer assets because undistributed interest is not yet reflected in the share price.

Use true for large or infrequent withdrawals. Use false when a recent operation has already triggered accrual. If significant time has passed since the last accrual, true is the safer default. See Reference → Contract API for the full signature.

See also

• Learn → Advanced → Protocol Accounting for how free supply and interest routing work.

• Build → Flash Actions for callbacks and atomic patterns.