Liquidation

Liquidation is a critical mechanism in the Flux protocol that protects liquidity providers' capital by ensuring managers maintain healthy collateral positions. Flux uses a simplified liquidation system with configurable profit margins.

Overview

Liquidation in Flux serves two purposes:

1. Protect LPs: Ensure borrowed capital is adequately collateralized

2. Maintain Solvency: Prevent vault insolvency through timely position closure

Flux offers a single, unified liquidation approach with configurable profit margins instead of complex bonding curves or Dutch auctions.

---

Understanding Position Health

Health Ratio

The Health Ratio is the key metric determining if a position can be liquidated:

Health Ratio = Total Position Value / True Debt

Where:

• Total Position Value = Bond + Working Capital + All Wrapper Positions (USD)

• True Debt = Principal Debt + Accrued Interest

Liquidation Threshold

Positions become liquidatable when:

Health Ratio < Liquidation Threshold

The liquidation threshold is derived from strategy parameters:

liquidationThreshold = 1e18 + minBondRatio - liquidationBuffer

// Example:
// minBondRatio = 0.2e18 (20%)
// liquidationBuffer = 0.1e18 (10%)
// liquidationThreshold = 1.0 + 0.2 - 0.1 = 1.1 (110%)

Example Calculation

Manager Position:

• Bond: 20K USDC

• Working Capital: 5K USDC

• WETH Position: 25K USDC (via oracle)

• Total Position Value: 50K USDC

• Principal Debt: 90K USDC

• Accrued Interest: 10K USDC

• True Debt: 100K USDC

Health Calculation:

Health Ratio = 50K / 100K = 0.5 (50%)
Liquidation Threshold = 1.1 (110%)

0.5 < 1.1 → Position is liquidatable ✗

---

When Is a Position Liquidatable?

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

(bool canLiquidate, uint256 minPayment,) =
    strategy.evaluateLiquidation(vault, manager);

if (canLiquidate) {
    // Position can be liquidated
}

The strategy can use any logic to make this determination. Common triggers include:

• Health ratio drops below threshold (standard implementation)

• Liquidity depth insufficient for safe unwinding

• High market volatility requiring higher collateralization

• Off-chain risk indicators signaling position risk

• Time-based conditions (e.g., circuit breakers during market stress)

With the standard ImmutableFixedRateStrategy, positions become liquidatable when the health ratio drops below the threshold due to:

• Collateral value decreasing (price drops)

• Debt increasing (interest accrual)

• Manager withdrew too much collateral

• Manager took on more debt

---

Liquidation Bonus Model

Unlike complex liquidation systems with Dutch auctions or bonding curves, Flux uses a simplified profit margin model.

Healthy Liquidations (Collateral ≥ Debt)

When position is liquidatable but still has enough collateral:

Liquidator Payment = Full True Debt
Liquidator Bonus = 0% (zero bonus)

Example:

• Total Collateral: 105K USDC

• True Debt: 100K USDC

• Health Ratio: 1.05 (105%) → Liquidatable (below 110% threshold)

Liquidation:

• Liquidator pays: 100K USDC (full debt)

• Liquidator receives: 105K USDC (all collateral)

• Liquidator profit: 5K USDC (5%)

• Manager receives: 0 (position fully closed)

Underwater Liquidations (Collateral < Debt)

When position has insufficient collateral to cover debt:

Liquidator Payment = Collateral Value × (1 - liquidationProfitMargin)
Liquidator Bonus = Collateral Value × liquidationProfitMargin

Example (1% profit margin):

• Total Collateral: 45K USDC

• True Debt: 50K USDC

• Health Ratio: 0.9 (90%) → Liquidatable

• Liquidation Profit Margin: 0.01e18 (1%)

Liquidation:

• Liquidator pays: 45K × (1 - 0.01) = 44.55K USDC

• Liquidator receives: 45K USDC (all collateral)

• Liquidator profit: 45K - 44.55K = 450 USDC (1%)

• Vault bad debt: 50K - 44.55K = 5.45K USDC

Configurable Profit Margins

Strategies can set liquidationProfitMargin from 0% to 20%:

Profit Margin	Liquidator Pays	Use Case
0% (altruistic)	100% of collateral	Public goods vaults, break-even liquidations
1% (default)	99% of collateral	Standard vaults, 1% incentive
5%	95% of collateral	Higher incentive for fast liquidations
10%	90% of collateral	Aggressive incentives
20% (maximum)	80% of collateral	Maximum incentive, higher bad debt risk

Why Configurable?

• Public goods vaults: Can set 0% for altruistic liquidators

• Competitive markets: Higher margins incentivize faster liquidations

• Risk management: Lower margins minimize LP losses from bad debt

---

How Liquidations Work

Liquidation Flow

1. Liquidator identifies unhealthy position
   ↓
2. Liquidator calls vault.liquidate(manager, additionalWrappers, data)
   ↓
3. Vault checks position is liquidatable via strategy
   ↓
4. Vault calls liquidator's callback (IFluxUnlockCallback)
   ↓
5. Liquidator performs operations:
   - Borrow capital (capital-free liquidation!)
   - Extract seized collateral
   - Swap/sell collateral
   - Pay vault minimum payment
   ↓
6. Vault validates minimum payment received
   ↓
7. Vault closes manager position
   ↓
8. Liquidator keeps profit

Code Example

// Liquidator initiates liquidation
vault.liquidate(manager, additionalWrappers, weirollScript);

// Inside liquidator's callback
function fluxUnlockCallback(bytes calldata data) external {
    require(msg.sender == address(vault), "Unauthorized");

    // Decode liquidation data
    (address manager, uint256 minPayment) = abi.decode(data, (address, uint256));

    // ============================================================================
    // CAPITAL-FREE LIQUIDATION PATTERN
    // ============================================================================

    // 1. Borrow capital from vault (no upfront capital needed!)
    vault.locked_borrow(minPayment);

    // 2. Pay vault immediately
    baseAsset.transfer(address(vault), minPayment);

    // 3. Extract seized collateral from manager's positions
    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
        );
    }

    // 4. Now liquidator has:
    //    - Borrowed minPayment from vault (debt position)
    //    - Seized collateral in liquidator's wallet
    //    - Can swap collateral for profit

    // 5. Swap collateral to base asset (example: WETH → USDC)
    uint256 swapAmount = WETH.balanceOf(address(this));
    uint256 usdcReceived = swapWETHForUSDC(swapAmount);

    // 6. Repay borrowed amount
    vault.locked_repay(minPayment);

    // 7. Keep remaining profit
    uint256 profit = usdcReceived - minPayment;
    // Profit automatically stays in liquidator wallet

    // Callback ends, vault validates position is closed
}

---

Capital-Free Liquidations

Flux's unique locked_borrow() function enables capital-free liquidations:

Traditional Liquidation (Capital Required)

Liquidator needs:
1. Borrow 100K USDC from external source
2. Pay vault 100K USDC
3. Receive collateral
4. Swap collateral → USDC
5. Repay loan + interest
6. Keep profit

Problem: Requires upfront capital or flash loan.

Flux Capital-Free Liquidation

Liquidator needs:
1. Call locked_borrow(minPayment) inside callback
2. Pay vault with borrowed funds
3. Extract collateral
4. Swap collateral
5. Repay vault
6. Keep profit

Benefit: No upfront capital or external flash loan needed!

Example Implementation

// Weiroll script for capital-free liquidation
WeirollPlanner planner;

// 1. Borrow capital
planner.add(vault.locked_borrow(minPayment));

// 2. Pay vault
planner.add(baseAsset.transfer(vault, minPayment));

// 3. Extract collateral (automatically done by vault during liquidation)

// Execute liquidation
bytes32[] memory commands = planner.plan();
vault.liquidate(manager, additionalWrappers, abi.encode(commands));

---

Step-by-Step Liquidation Example

Initial Position

• Manager borrowed: 100K USDC

• Manager bond: 20K USDC (20%)

• WETH position: 30K USDC value

• Total Position Value: 50K USDC

• True Debt (with interest): 100K USDC

• Health Ratio: 50K / 100K = 0.5 (50%) ✗ Liquidatable!

Liquidation Process

Step 1: Liquidator Identifies Position

// Query position health
(bool canLiquidate, uint256 minPayment,) =
    vault.STRATEGY().evaluateLiquidation(address(vault), manager);

console.log("Can liquidate:", canLiquidate);  // true
console.log("Min payment:", minPayment);      // 49.5K USDC (1% margin)

Calculation:

• Collateral Value: 50K USDC

• Liquidation Profit Margin: 1%

• Min Payment: 50K × (1 - 0.01) = 49.5K USDC

Step 2: Liquidator Calls liquidate()

vault.liquidate(manager, [], weirollScript);

Step 3: Inside Callback

function fluxUnlockCallback(bytes calldata data) external {
    // Borrow 49.5K USDC from vault
    vault.locked_borrow(49_500e6);

    // Pay vault
    USDC.transfer(address(vault), 49_500e6);

    // Extract collateral
    vault.locked_withdrawFromWrapper(wethWrapper, bytes32(0), type(uint256).max);
    // Liquidator receives ~16.67 WETH (worth 50K USDC)

    // Swap WETH → USDC
    uint256 usdcFromSwap = swapWETHForUSDC(16.67e18);
    // Assume minimal slippage: 49.8K USDC received

    // Repay vault
    vault.locked_repay(49_500e6);

    // Profit: 49,800 - 49,500 = 300 USDC
}

Step 4: After Liquidation

Manager:

• Position completely closed

• Lost 50K USDC in collateral

• Debt cleared (was 100K USDC)

• Net loss: 50K USDC

Liquidator:

• Borrowed 49.5K USDC

• Seized 50K USDC collateral

• Swapped to ~49.8K USDC

• Repaid 49.5K USDC

• Profit: ~300 USDC (after gas fees)

Vault/LPs:

• Received 49.5K USDC from liquidator

• Manager debt was 100K USDC

• Bad debt: 100K - 49.5K = 50.5K USDC

• Bad debt socialized across all LPs

---

Liquidator Tools & Strategies

1. Monitor Unhealthy Positions

// Query all managers in vault
address[] memory managers = getVaultManagers(vault);

for (uint i = 0; i < managers.length; i++) {
    (bool canLiquidate, uint256 minPayment,) =
        vault.STRATEGY().evaluateLiquidation(address(vault), managers[i]);

    if (canLiquidate) {
        // Liquidate or queue for later
        queueLiquidation(managers[i], minPayment);
    }
}

2. Profit Calculation

Before liquidating, calculate expected profit:

function calculateLiquidationProfit(address manager)
    public view returns (int256 expectedProfit)
{
    // Get liquidation details
    (bool canLiquidate, uint256 minPayment,) =
        strategy.evaluateLiquidation(vault, manager);

    if (!canLiquidate) return 0;

    // Get collateral value
    uint256 collateralValue = vault.getTotalPositionValue(manager);

    // Estimate swap output (accounting for slippage)
    uint256 estimatedOutput = estimateSwapOutput(collateral, baseAsset);

    // Calculate profit
    // profit = swapOutput - minPayment - gasCosts
    expectedProfit = int256(estimatedOutput) - int256(minPayment) - int256(estimatedGasCost);
}

3. Gas Optimization

// Batch liquidate multiple managers
function batchLiquidate(address[] calldata managers) external {
    for (uint i = 0; i < managers.length; i++) {
        try vault.liquidate(managers[i], [], data) {
            // Success
        } catch {
            // Skip failed liquidations
        }
    }
}

4. Flash Loan Alternative

Instead of locked_borrow(), use external flash loans:

// Using Aave flash loan
function executeOperation(
    address[] calldata assets,
    uint256[] calldata amounts,
    uint256[] calldata premiums,
    address initiator,
    bytes calldata params
) external returns (bool) {
    // 1. Received flash loaned USDC
    uint256 borrowed = amounts[0];

    // 2. Liquidate position on Flux
    vault.liquidate(manager, [], liquidationData);

    // 3. Inside liquidation callback, pay vault
    // and extract collateral

    // 4. Swap collateral to USDC

    // 5. Repay flash loan
    uint256 totalDebt = borrowed + premiums[0];
    IERC20(assets[0]).approve(address(AAVE_POOL), totalDebt);

    return true;
}

---

Bad Debt Handling

What Is Bad Debt?

Bad debt occurs when liquidation payment < manager's true debt:

Bad Debt = True Debt - Liquidation Payment

Example:

• True Debt: 100K USDC

• Collateral Value: 45K USDC

• Liquidation Payment: 44.55K USDC (1% margin)

• Bad Debt: 100K - 44.55K = 55.45K USDC

Bad Debt Socialization

Bad debt is socialized across all LPs:

// Vault tracks total bad debt
totalBadDebt += badDebtFromLiquidation;

// Share price automatically adjusts
sharePrice = (totalAssets - totalBadDebt) / totalShares;

Impact on LPs:

• Share value decreases proportionally

• All LPs bear the loss equally

• No individual LP loses everything

Example:

• Vault has 1M USDC in assets, 1M shares (1:1 ratio)

• Bad debt: 50K USDC

• New share price: (1M - 50K) / 1M = 0.95 USDC per share

• Each LP lost 5% of value

Minimizing Bad Debt

Strategy Parameters:

• Higher liquidation buffer: More cushion before liquidation

• Lower profit margin: Less LP loss per liquidation

• Conservative bond ratio: More collateral per borrowed amount

Oracle Quality:

• Use reliable oracles (Chainlink > Uniswap TWAP)

• Monitor for manipulation

• Fast liquidation response times

Liquidator Incentives:

• Higher profit margins attract more liquidators

• Faster liquidations → less bad debt

---

Auto-Deleveraging (ADL)

In addition to standard liquidation, Flux supports Auto-Deleveraging for high-utilization scenarios.

When ADL Triggers

ADL can occur when:

vaultUtilization > adlUtilizationThreshold
AND
healthRatio < adlThreshold

Example Parameters:

• ADL Utilization Threshold: 95%

• ADL Threshold: 120% (higher than liquidation threshold)

ADL vs Liquidation

Feature	Liquidation	ADL
Trigger	Health < 110%	Health < 120% AND utilization > 95%
Purpose	Prevent insolvency	Free up vault liquidity
Urgency	High	Medium
Manager Impact	Position closed	Position partially closed

ADL Example

Vault State:

• Total Assets: 1M USDC

• Total Debt: 960K USDC

• Utilization: 96% (above 95% threshold)

Manager Position:

• Total Value: 55K USDC

• True Debt: 50K USDC

• Health Ratio: 1.1 (110%)

• Normal liquidation: ✓ Healthy

• ADL: ✗ Can be ADL'd (below 120% threshold)

ADL Process:

1. ADL'er calls adl(manager)

2. Vault forces partial position closure

3. Vault utilization reduces

4. Manager health improves (lower debt)

---

Liquidation Best Practices

For Liquidators

1. Monitor continuously: Run bots to detect liquidatable positions

2. Calculate profit: Ensure profit exceeds gas costs

3. Use capital-free: Leverage locked_borrow() for efficiency

4. Optimize gas: Batch liquidations when possible

5. Handle failures: Gracefully handle reverts

6. Account for slippage: Estimate swap outputs conservatively

For Managers

1. Maintain buffer: Keep health ratio well above liquidation threshold

2. Monitor positions: Track health ratio constantly

3. Add collateral proactively: Don't wait until near liquidation

4. Understand oracles: Know how your positions are priced

5. Have alerts: Set up notifications for health ratio drops

6. Plan exits: Know how to quickly close positions if needed

For LPs

1. Understand risk: Bad debt can reduce share value

2. Vet strategies: Choose vaults with conservative parameters

3. Monitor utilization: High utilization = higher risk

4. Diversify: Don't put all capital in one vault

5. Emergency exit: Use emergency withdrawal if needed

For Vault Creators

1. Conservative thresholds: Higher liquidation buffers reduce bad debt

2. Quality oracles: Use reliable price feeds

3. Balanced margins: Balance liquidator incentives vs LP losses

4. Test thoroughly: Simulate liquidations before launch

5. Monitor health: Track overall vault health and liquidation rates

---

Comparison with Other Protocols

Feature	Flux Liquidation	Morpho Liquidation	Aave Liquidation
Bonus Model	Configurable margin (0-20%)	Fixed LIF based on LLTV	Fixed bonus (varies by asset)
Capital Required	✗ None (locked_borrow)	✓ Yes or flash loan	✓ Yes or flash loan
Partial Liquidation	✓ Yes	✓ Yes	✓ Yes (50% max)
Bad Debt	Socialized across LPs	Per-market isolation	Pool-wide socialization
Threshold	Derived from strategy	Per-market LLTV	Per-asset LTV
Altruistic Option	✓ Yes (0% margin)	✗ No	✗ No

---

Advanced Topics

Custom Liquidation Strategies

Liquidators can implement complex strategies:

// Multi-hop liquidation with DEX aggregator
function liquidateWithAggregator(address manager) external {
    vault.liquidate(manager, [], data);
    // Inside callback:
    // 1. locked_borrow()
    // 2. Extract collateral
    // 3. Use 1inch/ParaSwap for best swap rates
    // 4. Repay vault
    // 5. Keep profit
}

Liquidation Monitoring

Build monitoring systems:

// Monitor all vaults for liquidation opportunities
async function monitorLiquidations() {
  const vaults = await getAllVaults();

  for (const vault of vaults) {
    const managers = await getVaultManagers(vault);

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

      if (canLiquidate) {
        const profit = await estimateProfit(vault, manager, minPayment);

        if (profit > gasCost) {
          await liquidate(vault, manager);
        }
      }
    }
  }
}