Recipes

Canonical patterns for composing Lotus actions including leveraged loops, tranche refinancing, collateral swaps, and liquidation bot recipes with code examples.

This page outlines canonical flows using Lotus building blocks. Use them as starting points and adapt to your needs.

All recipes use flash loans and callbacks. Ensure callback contracts are minimal, non-reentrant, and validate amounts and health before finalizing.

Leveraged Loop with Flash Actions

A leveraged loop increases position size atomically without interim risk by borrowing via a flash loan and immediately collateralizing the proceeds.

• Steps: flashLoan loan token → supply collateral → borrow → repay flash → optional rebalance.

• Notes: cap leverage; set slippage and price bounds; validate post-state.

The following contract uses supplyCollateral's callback to borrow and swap inside a single transaction.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import {ILotus, MarketParams} from "lotus/src/interfaces/ILotus.sol";
import {ILotusSupplyCollateralCallback} from "lotus/src/interfaces/ILotusCallbacks.sol";
import {IERC20} from "openzeppelin/token/ERC20/IERC20.sol";

contract LeverageLoop is ILotusSupplyCollateralCallback {
    ILotus public immutable lotus;
    address public immutable dex; // swap router

    struct Params {
        MarketParams marketParams;
        uint256 trancheIndex;
        uint256 borrowAmount;
        uint256 minCollateralOut;
        address user;
    }

    constructor(address _lotus, address _dex) {
        lotus = ILotus(_lotus);
        dex = _dex;
    }

    /// @notice Open a leveraged position in one transaction.
    function lever(
        MarketParams memory mp,
        uint256 trancheIndex,
        uint256 initialCollateral,
        uint256 borrowAmount,
        uint256 minCollateralOut
    ) external {
        bytes memory data = abi.encode(Params(mp, trancheIndex, borrowAmount, minCollateralOut, msg.sender));
        lotus.supplyCollateral(mp, trancheIndex, initialCollateral, msg.sender, data);
    }

    function onLotusSupplyCollateral(uint256 assets, bytes calldata data) external {
        require(msg.sender == address(lotus), "unauthorized");
        Params memory p = abi.decode(data, (Params));

        address collateralToken = p.marketParams.collateralTokens[p.trancheIndex];

        // 1. Borrow loan tokens against the collateral being supplied.
        lotus.borrow(p.marketParams, p.trancheIndex, p.borrowAmount, 0, p.user, address(this), "");

        // 2. Swap borrowed loan tokens → collateral token via DEX.
        IERC20(p.marketParams.loanToken).approve(dex, p.borrowAmount);
        // swapExactIn(tokenIn, tokenOut, amountIn, minOut, receiver)
        // Replace with your router's interface.

        // 3. Transfer initial collateral from user and approve Lotus.
        IERC20(collateralToken).transferFrom(p.user, address(this), assets);
        IERC20(collateralToken).approve(address(lotus), type(uint256).max);

        // 4. Supply additional collateral from swap proceeds.
        // lotus.supplyCollateral(p.marketParams, p.trancheIndex, additionalCollateral, p.user, "");
    }
}

Step	Action	Notes
1	borrow inside the callback	Creates debt on behalf of the user
2	Swap loan token → collateral	Enforce minCollateralOut for slippage
3	Transfer user's initial collateral	User must have pre-approved this contract
4	supplyCollateral with swap proceeds	Increases collateral, reducing LTV

Refinance Across Tranches

Refinancing moves debt from a junior tranche to a more senior tranche in a single transaction, lowering the borrow rate without closing the position.

• Steps: flashLoan → repay junior → borrow senior → repay flash.

• Notes: check free supply constraints; accrue interest for accuracy if needed.

Collateral Swap with Bounds

A collateral swap replaces the collateral asset backing a position while maintaining loan health throughout the transaction.

• Steps: flashLoan → repay → withdraw old collateral → swap → supply new collateral → borrow → repay flash.

• Notes: enforce swap slippage limits; recheck health after each leg.

Security Tips

• Keep callbacks minimal and non‑reentrant; whitelist tokens and markets.

• Validate amounts, health, and free supply before finalizing.

• Prefer pull patterns and safe transfer libraries.

Liquidation Bot

A liquidation bot monitors borrower positions and executes profitable liquidations when positions become unhealthy.

• Steps: index borrowers → compute health per tranche → encode lmData with BaseLiquidationParams → call liquidate → optionally use flash-funded callback.

• Notes: see Liquidation Bot for a complete implementation with code.

See Also

• Build → Flash Actions for atomic strategy patterns

• Build → Liquidation Bot for a complete liquidation implementation

• Build → Market Creation for end-to-end market setup

• Learn → Core Interactions for protocol operation details