Liquidator Bot Guide

This guide covers everything you need to build and run a profitable liquidation bot for Flux Protocol. Learn how to monitor positions, execute capital-free liquidations, and optimize for maximum profit.

Overview

As a liquidator in Flux, you:

• Monitor manager positions for unhealthy health ratios

• Execute liquidations when positions become underwater

• Profit from liquidations based on strategy-specific pricing logic

• Need zero upfront capital thanks to locked_borrow()

• Protect the protocol by maintaining vault solvency

Key Innovation: Flux's locked_borrow() enables capital-free liquidations—no flash loans required!

---

How Liquidations Work in Flux

Liquidation Triggers

A position becomes liquidatable when the strategy's evaluateLiquidation() function returns canLiquidate = true.

The strategy can use any logic to determine this. The standard ImmutableFixedRateStrategy uses:

Health Ratio < Liquidation Threshold

Where:
Health Ratio = Total Position Value / True Debt
Liquidation Threshold = 1 + minBondRatio - liquidationBuffer

Example with ImmutableFixedRateStrategy:

• Manager's collateral: 50K USDC

• True debt: 48K USDC

• Health ratio: 50K / 48K = 1.042 (104.2%)

• Liquidation threshold: 1.1 (110%)

• Result: Liquidatable (104.2% < 110%)

Note: Custom strategies can implement different liquidation logic considering liquidity depth, volatility, off-chain data, or other factors beyond simple health ratios.

Liquidation Payment Calculation

Note: The payment calculation is strategy-specific. Each strategy implements evaluateLiquidation() to determine the minPayment. The examples below show how the standard ImmutableFixedRateStrategy calculates liquidation payments, but custom strategies can implement different pricing logic.

Case 1: Healthy Position (Collateral ≥ Debt)

Liquidator Pays: Full debt amount
Liquidator Bonus: 0% (zero bonus)

Case 2: Underwater Position (Collateral < Debt)

Liquidator Pays: Collateral Value × (1 - liquidationProfitMargin)
Liquidator Profit: Collateral Value × liquidationProfitMargin

Examples with different margins:
- 1% margin: Pay 99% of collateral, keep 1%
- 5% margin: Pay 95% of collateral, keep 5%
- 10% margin: Pay 90% of collateral, keep 10%

Example:

• Collateral value: 45K USDC (underwater!)

• True debt: 50K USDC

• Liquidation profit margin: 1%

• Liquidator pays: 45K × 0.99 = 44.55K USDC

• Liquidator receives: 45K USDC collateral

• Liquidator profit: 450 USDC (1%)

---

Setting Up Your Liquidation Bot

Step 1: Deploy Executor

Liquidators need an executor to handle the callback:

import {IFluxVaultFactory} from "flux-v1-contracts/interfaces/IFluxVaultFactory.sol";
import {WeirollExecutor} from "flux-v1-contracts/weiroll/WeirollExecutor.sol";

contract LiquidatorSetup {
    function deployExecutor(IFluxVaultFactory factory) external returns (address) {
        // Deploy Weiroll executor for liquidations
        return factory.deployWeirollExecutor();
    }
}

Step 2: Monitor for Liquidatable Positions

// Off-chain monitoring script
interface ManagerPosition {
  vault: string;
  manager: string;
  healthRatio: bigint;
  totalValue: bigint;
  trueDebt: bigint;
  canLiquidate: boolean;
  minPayment: bigint;
  expectedProfit: bigint;
}

async function scanForLiquidations(
  vaults: string[]
): Promise<ManagerPosition[]> {
  const liquidatablePositions: ManagerPosition[] = [];

  for (const vaultAddress of vaults) {
    const vault = await getVaultContract(vaultAddress);
    const strategy = await vault.STRATEGY();

    // Get all managers (track onchain or via events)
    const managers = await getVaultManagers(vaultAddress);

    for (const manager of managers) {
      // Check if liquidatable
      const { canLiquidate, minPayment, oraclePrices } =
        await strategy.evaluateLiquidation(vaultAddress, manager);

      if (canLiquidate) {
        const totalValue = await vault.getTotalPositionValue(manager);
        const trueDebt = await vault.getManagerTrueDebt(manager);
        const healthRatio = (totalValue * 1e18) / trueDebt;

        const expectedProfit = await estimateProfit(
          vault,
          manager,
          minPayment,
          totalValue
        );

        liquidatablePositions.push({
          vault: vaultAddress,
          manager,
          healthRatio,
          totalValue,
          trueDebt,
          canLiquidate: true,
          minPayment,
          expectedProfit,
        });
      }
    }
  }

  return liquidatablePositions;
}

// Run continuously
setInterval(async () => {
  const opportunities = await scanForLiquidations(MONITORED_VAULTS);
  for (const opp of opportunities) {
    await attemptLiquidation(opp);
  }
}, 12000); // Every block

Step 3: Estimate Profitability

async function estimateProfit(
  vault: Contract,
  manager: string,
  minPayment: bigint,
  collateralValue: bigint
): Promise<bigint> {
  // Get gas cost estimate
  const gasPrice = await provider.getGasPrice();
  const estimatedGas = 500000n; // Estimate based on historical data
  const gasCost = gasPrice * estimatedGas;

  // Estimate swap slippage (collateral → base asset)
  const wrappers = await vault.getRegisteredWrappers(manager);
  let totalSlippage = 0n;

  for (const wrapper of wrappers) {
    const balance = await wrapper.getBalance(vault.address, manager, 0n);
    if (balance > 0n) {
      const asset = await wrapper.underlyingAsset();
      const slippage = await estimateSwapSlippage(asset, balance);
      totalSlippage += slippage;
    }
  }

  // Calculate net profit
  const grossProfit = collateralValue - minPayment;
  const netProfit = grossProfit - gasCost - totalSlippage;

  return netProfit;
}

async function isProfitable(
  minProfit: bigint,
  estimatedProfit: bigint
): Promise<boolean> {
  return estimatedProfit >= minProfit;
}

---

Executing Liquidations

Capital-Free Liquidation Pattern

The key innovation: use locked_borrow() to liquidate without upfront capital!

contract CapitalFreeLiquidator is IFluxUnlockCallback {
    address public immutable owner;

    function liquidate(
        IFluxVault vault,
        address manager
    ) external {
        // Get liquidation details
        IStrategy strategy = vault.STRATEGY();
        (bool canLiquidate, uint256 minPayment,) =
            strategy.evaluateLiquidation(address(vault), manager);

        require(canLiquidate, "Not liquidatable");

        // Encode liquidation data
        bytes memory data = abi.encode(manager, minPayment);

        // Execute liquidation (vault calls our callback)
        vault.liquidate(manager, new IAsset[](0), data);
    }

    function fluxUnlockCallback(bytes calldata data) external override {
        IFluxVault vault = IFluxVault(msg.sender);
        (address manager, uint256 minPayment) = abi.decode(data, (address, uint256));

        // ================================================================
        // CAPITAL-FREE LIQUIDATION FLOW
        // ================================================================

        // 1. Borrow the payment amount from vault
        //    (This is the magic - no upfront capital needed!)
        vault.locked_borrow(minPayment);

        // 2. Pay the vault immediately
        IERC20 baseAsset = IERC20(vault.asset());
        baseAsset.transfer(address(vault), minPayment);

        // 3. Vault automatically transfers seized collateral to us
        //    (We now have manager's positions)

        // 4. Extract collateral from wrappers
        IAsset[] memory wrappers = vault.getRegisteredWrappers(manager);
        for (uint i = 0; i < wrappers.length; i++) {
            vault.locked_withdrawFromWrapper(
                wrappers[i],
                bytes32(0),
                type(uint256).max // Withdraw all
            );
            // Assets sent to this contract
        }

        // 5. Swap all collateral back to base asset
        uint256 totalReceived = _swapAllToBaseAsset(wrappers);

        // 6. Repay the borrowed amount
        baseAsset.approve(address(vault), minPayment);
        vault.locked_repay(minPayment);

        // 7. Keep the profit!
        uint256 profit = totalReceived - minPayment;
        baseAsset.transfer(owner, profit);

        // Done! Liquidation complete with zero upfront capital
    }

    function _swapAllToBaseAsset(IAsset[] memory wrappers) internal returns (uint256 total) {
        for (uint i = 0; i < wrappers.length; i++) {
            address asset = wrappers[i].underlyingAsset();
            uint256 balance = IERC20(asset).balanceOf(address(this));

            if (balance > 0) {
                uint256 received = _swap(asset, vault.asset(), balance);
                total += received;
            }
        }
    }

    function _swap(address from, address to, uint256 amount) internal returns (uint256) {
        // Implement swap logic (Uniswap, 1inch, etc.)
        // Return amount received
    }
}

Alternative: Flash Loan Liquidation

If you prefer using external flash loans:

contract FlashLoanLiquidator {
    function liquidateWithFlashLoan(
        IFluxVault vault,
        address manager,
        uint256 minPayment
    ) external {
        // 1. Take Aave flash loan for minPayment
        aaveLendingPool.flashLoan(
            address(this),
            assets,
            amounts,
            modes,
            address(this),
            params,
            0
        );
    }

    function executeOperation(
        address[] calldata assets,
        uint256[] calldata amounts,
        uint256[] calldata premiums,
        address initiator,
        bytes calldata params
    ) external returns (bool) {
        // 2. Use flash loaned funds to liquidate
        (IFluxVault vault, address manager) = abi.decode(params, (IFluxVault, address));

        // Pay vault
        IERC20(assets[0]).approve(address(vault), amounts[0]);
        vault.liquidate(manager, new IAsset[](0), "");

        // 3. In callback: extract collateral and swap

        // 4. Repay flash loan
        uint256 totalDebt = amounts[0] + premiums[0];
        IERC20(assets[0]).approve(address(aaveLendingPool), totalDebt);

        return true;
    }
}

---

Optimizing Liquidation Profits

1. Gas Optimization

// Batch liquidate multiple managers in one transaction
function batchLiquidate(
    IFluxVault vault,
    address[] calldata managers
) external {
    for (uint i = 0; i < managers.length; i++) {
        try vault.liquidate(managers[i], new IAsset[](0), "") {
            // Success
        } catch {
            // Skip failed liquidations, continue with others
        }
    }
}

2. Swap Optimization

async function findBestSwapRoute(
  tokenIn: string,
  tokenOut: string,
  amountIn: bigint
): Promise<SwapRoute> {
  // Check multiple DEX aggregators
  const routes = await Promise.all([
    oneInch.getQuote(tokenIn, tokenOut, amountIn),
    paraSwap.getQuote(tokenIn, tokenOut, amountIn),
    cowSwap.getQuote(tokenIn, tokenOut, amountIn),
  ]);

  // Return best route
  return routes.reduce((best, current) =>
    current.outputAmount > best.outputAmount ? current : best
  );
}

3. MEV Protection

async function submitLiquidationWithMEV(
  liquidationTx: Transaction
): Promise<TransactionReceipt> {
  // Use Flashbots to protect from frontrunning
  const flashbotsProvider = await FlashbotsBundleProvider.create(
    provider,
    signer,
    FLASHBOTS_RELAY_URL
  );

  const signedBundle = await flashbotsProvider.signBundle([
    {
      signer: wallet,
      transaction: liquidationTx,
    },
  ]);

  // Submit bundle
  const simulation = await flashbotsProvider.simulate(signedBundle, targetBlock);

  if (simulation.firstRevert) {
    console.error("Simulation failed:", simulation.firstRevert);
    return null;
  }

  return await flashbotsProvider.sendRawBundle(signedBundle, targetBlock);
}

4. Partial Liquidations

For very large positions, liquidate partially to minimize market impact:

function partialLiquidate(
    IFluxVault vault,
    address manager,
    uint256 liquidatePercent // e.g., 50% = 0.5e18
) external {
    // Calculate partial amounts
    IAsset[] memory wrappers = vault.getRegisteredWrappers(manager);

    // Build asset list with percentages
    uint256[] memory percentages = new uint256[](wrappers.length);
    for (uint i = 0; i < wrappers.length; i++) {
        percentages[i] = liquidatePercent;
    }

    // Liquidate partial position
    bytes memory data = abi.encode(manager, percentages);
    vault.liquidate(manager, wrappers, data);
}

---

Monitoring and Alerting

Real-Time Position Monitoring

class LiquidationMonitor {
  private positions: Map<string, ManagerPosition> = new Map();

  async monitorContinuously() {
    // Subscribe to relevant events
    this.subscribeToEvents();

    // Poll for updates
    setInterval(() => this.updatePositions(), 12000);
  }

  private subscribeToEvents() {
    // Listen for position changes
    vault.on("Borrowed", (manager, amount) => {
      this.updatePosition(vault.address, manager);
    });

    vault.on("Repaid", (manager, amount) => {
      this.updatePosition(vault.address, manager);
    });

    // Listen for price updates (oracle events)
    oracleRegistry.on("PriceUpdated", (asset, price) => {
      this.updateAllPositionsWithAsset(asset);
    });
  }

  private async updatePosition(vault: string, manager: string) {
    const position = await this.fetchPosition(vault, manager);

    if (position.canLiquidate) {
      await this.attemptLiquidation(position);
    }

    this.positions.set(`${vault}-${manager}`, position);
  }

  private async attemptLiquidation(position: ManagerPosition) {
    // Check profitability
    const profit = await estimateProfit(
      position.vault,
      position.manager,
      position.minPayment,
      position.totalValue
    );

    if (profit < MIN_PROFIT_THRESHOLD) {
      console.log(
        `Skipping unprofitable liquidation: ${position.manager} (profit: ${profit})`
      );
      return;
    }

    // Execute liquidation
    try {
      const tx = await liquidator.liquidate(position.vault, position.manager);
      const receipt = await tx.wait();

      console.log(
        `✅ Liquidated ${position.manager} - Profit: ${profit} - Gas: ${receipt.gasUsed}`
      );

      // Track stats
      this.recordLiquidation(position, profit, receipt.gasUsed);
    } catch (error) {
      console.error(`❌ Liquidation failed:`, error);
    }
  }
}

Profitability Dashboard

interface LiquidationStats {
  totalLiquidations: number;
  totalProfit: bigint;
  totalGasCost: bigint;
  averageProfit: bigint;
  profitableCount: number;
  unprofitableCount: number;
}

class LiquidationAnalytics {
  private stats: LiquidationStats = {
    totalLiquidations: 0,
    totalProfit: 0n,
    totalGasCost: 0n,
    averageProfit: 0n,
    profitableCount: 0,
    unprofitableCount: 0,
  };

  recordLiquidation(profit: bigint, gasCost: bigint) {
    this.stats.totalLiquidations++;
    this.stats.totalProfit += profit;
    this.stats.totalGasCost += gasCost;

    if (profit > gasCost) {
      this.stats.profitableCount++;
    } else {
      this.stats.unprofitableCount++;
    }

    this.stats.averageProfit =
      this.stats.totalProfit / BigInt(this.stats.totalLiquidations);
  }

  getStats(): LiquidationStats {
    return { ...this.stats };
  }

  displayDashboard() {
    console.log("=== Liquidation Bot Stats ===");
    console.log(`Total Liquidations: ${this.stats.totalLiquidations}`);
    console.log(
      `Total Profit: ${ethers.formatEther(this.stats.totalProfit)} ETH`
    );
    console.log(
      `Total Gas Cost: ${ethers.formatEther(this.stats.totalGasCost)} ETH`
    );
    console.log(
      `Average Profit: ${ethers.formatEther(this.stats.averageProfit)} ETH`
    );
    console.log(`Profitable: ${this.stats.profitableCount}`);
    console.log(`Unprofitable: ${this.stats.unprofitableCount}`);
  }
}

---

Complete Liquidation Bot Example

// main.ts - Complete liquidation bot
import { ethers } from "ethers";
import { FlashbotsBundleProvider } from "@flashbots/ethers-provider-bundle";

class FluxLiquidationBot {
  private provider: ethers.Provider;
  private wallet: ethers.Wallet;
  private liquidator: ethers.Contract;
  private vaults: string[];
  private minProfitThreshold: bigint;

  constructor(config: BotConfig) {
    this.provider = new ethers.JsonRpcProvider(config.rpcUrl);
    this.wallet = new ethers.Wallet(config.privateKey, this.provider);
    this.liquidator = new ethers.Contract(
      config.liquidatorAddress,
      LIQUIDATOR_ABI,
      this.wallet
    );
    this.vaults = config.vaults;
    this.minProfitThreshold = ethers.parseEther(config.minProfitEth);
  }

  async start() {
    console.log("🚀 Starting Flux Liquidation Bot...");

    // Monitor positions
    await this.monitorPositions();
  }

  private async monitorPositions() {
    while (true) {
      try {
        for (const vaultAddress of this.vaults) {
          await this.checkVaultLiquidations(vaultAddress);
        }

        // Wait 12 seconds (1 block)
        await sleep(12000);
      } catch (error) {
        console.error("Error in monitoring loop:", error);
        await sleep(12000);
      }
    }
  }

  private async checkVaultLiquidations(vaultAddress: string) {
    const vault = new ethers.Contract(vaultAddress, VAULT_ABI, this.provider);
    const strategy = await vault.STRATEGY();
    const strategyContract = new ethers.Contract(
      strategy,
      STRATEGY_ABI,
      this.provider
    );

    // Get all managers
    const managers = await this.getVaultManagers(vaultAddress);

    for (const manager of managers) {
      const { canLiquidate, minPayment } =
        await strategyContract.evaluateLiquidation(vaultAddress, manager);

      if (canLiquidate) {
        await this.attemptLiquidation(vault, manager, minPayment);
      }
    }
  }

  private async attemptLiquidation(
    vault: ethers.Contract,
    manager: string,
    minPayment: bigint
  ) {
    // Estimate profit
    const totalValue = await vault.getTotalPositionValue(manager);
    const profit = await this.estimateProfit(vault, manager, minPayment, totalValue);

    if (profit < this.minProfitThreshold) {
      console.log(`⏭️  Skipping unprofitable liquidation: ${manager}`);
      return;
    }

    console.log(
      `💰 Liquidating ${manager} - Expected profit: ${ethers.formatEther(profit)} ETH`
    );

    // Execute liquidation
    try {
      const tx = await this.liquidator.liquidate(vault.address, manager, {
        gasLimit: 1000000,
      });

      const receipt = await tx.wait();
      const actualProfit = await this.calculateActualProfit(receipt);

      console.log(`✅ Liquidation successful!`);
      console.log(`   Profit: ${ethers.formatEther(actualProfit)} ETH`);
      console.log(`   Gas used: ${receipt.gasUsed}`);
    } catch (error) {
      console.error(`❌ Liquidation failed:`, error);
    }
  }

  private async estimateProfit(
    vault: ethers.Contract,
    manager: string,
    minPayment: bigint,
    totalValue: bigint
  ): Promise<bigint> {
    // Gas cost
    const gasPrice = (await this.provider.getFeeData()).gasPrice || 0n;
    const estimatedGas = 500000n;
    const gasCost = gasPrice * estimatedGas;

    // Slippage estimate
    const slippage = (totalValue * 5n) / 1000n; // 0.5% slippage

    // Net profit
    const grossProfit = totalValue - minPayment;
    return grossProfit - gasCost - slippage;
  }

  private async getVaultManagers(vaultAddress: string): Promise<string[]> {
    // Query events or maintain off-chain index
    // Return list of active managers
    return [];
  }

  private async calculateActualProfit(
    receipt: ethers.TransactionReceipt
  ): Promise<bigint> {
    // Parse events to get actual profit
    return 0n;
  }
}

// Run bot
const config = {
  rpcUrl: process.env.RPC_URL!,
  privateKey: process.env.PRIVATE_KEY!,
  liquidatorAddress: process.env.LIQUIDATOR_ADDRESS!,
  vaults: process.env.VAULTS!.split(","),
  minProfitEth: "0.01", // Minimum 0.01 ETH profit
};

const bot = new FluxLiquidationBot(config);
bot.start();

---

Best Practices

1. Always Verify Profitability First

const MIN_PROFIT = ethers.parseEther("0.01"); // 0.01 ETH minimum

if (estimatedProfit < MIN_PROFIT) {
  console.log("Skipping: profit too low");
  return;
}

2. Handle Failed Liquidations Gracefully

try vault.liquidate(manager, [], data) {
    // Success
    emit LiquidationSuccess(manager, profit);
} catch Error(string memory reason) {
    // Log and continue
    emit LiquidationFailed(manager, reason);
} catch {
    emit LiquidationFailed(manager, "Unknown error");
}

3. Monitor Gas Prices

const currentGasPrice = await provider.getFeeData();

// Only liquidate if gas price is reasonable
if (currentGasPrice.gasPrice > MAX_GAS_PRICE) {
  console.log("Gas price too high, waiting...");
  return;
}

4. Keep Detailed Logs

interface LiquidationLog {
  timestamp: number;
  vault: string;
  manager: string;
  healthRatio: bigint;
  minPayment: bigint;
  profit: bigint;
  gasUsed: bigint;
  txHash: string;
}

// Store all liquidations for analysis
const logLiquidation = async (log: LiquidationLog) => {
  await database.insert("liquidations", log);
};

---

Troubleshooting

Common Issues

Issue: "Position not liquidatable"

• Cause: Health ratio still above threshold

• Solution: Wait for health to drop further or oracle prices to update

Issue: "Insufficient profit"

• Cause: Liquidation margin too low or gas costs too high

• Solution: Only target larger positions or wait for better gas prices

Issue: "Transaction reverted"

• Cause: Position already liquidated or health improved

• Solution: Check position status before executing

Issue: "Swap slippage too high"

• Cause: Low liquidity for seized collateral

• Solution: Use DEX aggregators or split swaps

---

Read More

• Liquidation Concepts

• Position Health

• Oracle Pricing