evk-liquidation

name	EVK Liquidation
description	This skill should be used when the user asks about "liquidate", "liquidation", "unhealthy", "underwater", "violator", "seize", "discount", "bad debt", or needs to understand EVault liquidation mechanics.
version	0.1.0

EVK Liquidation

EVaults implement a sophisticated liquidation mechanism using the EVC's controlCollateral feature. Liquidators repay debt and receive collateral at a discount.

Overview

┌──────────────────────────────────────────────────────────────┐
│                   LIQUIDATION FLOW                           │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│  Violator Account (Unhealthy)                                │
│  ├── Collateral: Vault A (e.g., 1000 ETH shares)             │
│  ├── Controller: Vault B (e.g., USDC debt vault)             │
│  └── Health: collateralValue < debtValue                     │
│                                                              │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │              Liquidation Process                        │ │
│  │                                                         │ │
│  │  1. Liquidator calls vault.liquidate()                  │ │
│  │     ├── repayAssets: amount of debt to repay            │ │
│  │     ├── collateral: which collateral vault to seize     │ │
│  │     └── minYieldBalance: min collateral to receive      │ │
│  │                                                         │ │
│  │  2. Vault calculates:                                   │ │
│  │     ├── Discount based on violator health               │ │
│  │     ├── Collateral to seize (repay + discount)          │ │
│  │     └── Debt reduction                                  │ │
│  │                                                         │ │
│  │  3. Via EVC.controlCollateral():                        │ │
│  │     └── Collateral transferred to liquidator            │ │
│  │                                                         │ │
│  │  4. Debt reduced, violator health improved              │ │
│  │                                                         │ │
│  └─────────────────────────────────────────────────────────┘ │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Liquidation Configuration

// RiskManager.sol - LTV configuration

struct LTVConfig {
    uint16 borrowLTV;           // Max LTV for borrowing (e.g., 80%)
    uint16 liquidationLTV;      // LTV threshold for liquidation (e.g., 85%)
    uint16 initialLiquidationLTV;  // Starting LTV during ramp
    uint48 targetTimestamp;     // When ramp completes
    uint32 rampDuration;        // Ramp period for LTV changes
}

// Per-collateral LTV settings
mapping(address collateral => LTVConfig) internal ltvLookup;

// Vault-level liquidation settings
uint16 public maxLiquidationDiscount;  // Max discount for liquidators (e.g., 15%)
uint16 public liquidationCoolOffTime;  // Delay between partial liquidations

/// @notice Set LTV for a collateral
function setLTV(
    address collateral,
    uint16 borrowLTV,
    uint16 liquidationLTV,
    uint32 rampDuration
) external onlyGovernor {
    // borrowLTV must be <= liquidationLTV
    require(borrowLTV <= liquidationLTV, "Invalid LTV");

    LTVConfig memory config;
    config.borrowLTV = borrowLTV;
    config.liquidationLTV = liquidationLTV;
    config.rampDuration = rampDuration;
    // ... set target timestamp for ramp

    ltvLookup[collateral] = config;
}

Health Calculation

// Check if account is liquidatable

/// @notice Get account health factor
/// @dev Returns liability value and collateral value adjusted by liquidation LTV
function checkAccountHealth(address account) public view returns (
    uint256 liabilityValue,
    uint256 collateralValueLiquidation
) {
    // Get debt in unit of account
    uint256 debtAssets = debtOf(account);
    if (debtAssets == 0) return (0, type(uint256).max);

    liabilityValue = oracle.getQuote(debtAssets, asset(), unitOfAccount);

    // Get collateral values with liquidation LTV haircut
    address[] memory collaterals = evc.getCollaterals(account);

    for (uint i = 0; i < collaterals.length; i++) {
        address collateral = collaterals[i];
        LTVConfig memory ltv = ltvLookup[collateral];

        if (ltv.liquidationLTV == 0) continue;

        uint256 balance = IEVault(collateral).balanceOf(account);
        if (balance == 0) continue;

        uint256 value = oracle.getQuote(
            IEVault(collateral).convertToAssets(balance),
            IEVault(collateral).asset(),
            unitOfAccount
        );

        // Apply liquidation LTV (higher than borrow LTV)
        collateralValueLiquidation += value * ltv.liquidationLTV / 1e18;
    }
}

/// @notice Check if account is unhealthy
function isAccountUnhealthy(address account) public view returns (bool) {
    (uint256 liability, uint256 collateral) = checkAccountHealth(account);
    return collateral < liability;
}

Liquidation Discount

// Discount scales with how unhealthy the account is

/// @notice Calculate liquidation discount based on health
function calculateDiscount(
    uint256 liabilityValue,
    uint256 collateralValue
) internal view returns (uint256 discount) {
    if (collateralValue >= liabilityValue) {
        // Healthy - no liquidation possible
        return 0;
    }

    // Health factor = collateral / liability (< 1 when unhealthy)
    uint256 healthFactor = collateralValue * 1e18 / liabilityValue;

    // Discount increases as health decreases
    // At health = 1: discount = 0
    // At health = 0: discount = maxLiquidationDiscount

    discount = maxLiquidationDiscount * (1e18 - healthFactor) / 1e18;

    // Cap at max
    if (discount > maxLiquidationDiscount) {
        discount = maxLiquidationDiscount;
    }
}

Liquidate Function

/// @notice Liquidate an unhealthy account
/// @param violator Account to liquidate
/// @param collateral Collateral vault to seize from
/// @param repayAssets Amount of debt to repay
/// @param minYieldBalance Minimum collateral shares to receive
function liquidate(
    address violator,
    address collateral,
    uint256 repayAssets,
    uint256 minYieldBalance
) external virtual use(MODULE_LIQUIDATION) {}

// In Liquidation.sol module
function liquidate(
    address violator,
    address collateral,
    uint256 repayAssets,
    uint256 minYieldBalance
) external {
    VaultCache memory cache = initOperation(OP_LIQUIDATE);

    address liquidator = msgSender();

    // 1. Verify violator is unhealthy
    (uint256 liabilityValue, uint256 collateralValue) = checkAccountHealth(violator);
    if (collateralValue >= liabilityValue) revert HealthyAccount();

    // 2. Calculate discount
    uint256 discount = calculateDiscount(liabilityValue, collateralValue);

    // 3. Get collateral configuration
    LTVConfig memory ltvConfig = ltvLookup[collateral];
    if (ltvConfig.liquidationLTV == 0) revert InvalidCollateral();

    // 4. Calculate repay value in unit of account
    uint256 repayValue = oracle.getQuote(repayAssets, asset(), unitOfAccount);

    // 5. Calculate collateral to seize (repay value + discount)
    uint256 seizeValue = repayValue * (1e18 + discount) / 1e18;

    // Convert to collateral assets
    uint256 seizeAssets = oracle.getQuote(
        seizeValue,
        unitOfAccount,
        IEVault(collateral).asset()
    );

    // Convert to collateral shares
    uint256 seizeShares = IEVault(collateral).convertToShares(seizeAssets);

    // 6. Verify minimum yield
    if (seizeShares < minYieldBalance) revert InsufficientYield();

    // 7. Cap at violator's balance
    uint256 violatorBalance = IEVault(collateral).balanceOf(violator);
    if (seizeShares > violatorBalance) {
        seizeShares = violatorBalance;
        // Recalculate repay amount based on available collateral
        seizeAssets = IEVault(collateral).convertToAssets(seizeShares);
        seizeValue = oracle.getQuote(seizeAssets, IEVault(collateral).asset(), unitOfAccount);
        repayValue = seizeValue * 1e18 / (1e18 + discount);
        repayAssets = oracle.getQuote(repayValue, unitOfAccount, asset());
    }

    // 8. Reduce violator's debt
    reduceDebt(cache, violator, repayAssets);

    // 9. Transfer underlying from liquidator
    asset().safeTransferFrom(liquidator, address(this), repayAssets);
    cache.cash += repayAssets;

    // 10. Seize collateral via EVC
    // This uses controlCollateral to transfer from violator to liquidator
    bytes memory transferCall = abi.encodeCall(
        IERC20.transfer,
        (liquidator, seizeShares)
    );

    evc.controlCollateral(collateral, violator, 0, transferCall);

    updateVault(cache);

    // 11. Schedule status checks
    requireAccountStatusCheck(violator);
    requireAccountStatusCheck(liquidator);  // Liquidator might be borrower too
    requireVaultStatusCheck();

    emit Liquidate(liquidator, violator, collateral, repayAssets, seizeShares);
}

Control Collateral (EVC)

// EVC.sol - Enables controller to seize collateral

/// @notice Controller vault seizes collateral during liquidation
function controlCollateral(
    address collateralVault,
    address onBehalfOfAccount,
    uint256 value,
    bytes calldata data
) external payable returns (bytes memory) {
    // Only enabled controller can call
    if (!isControllerEnabled(onBehalfOfAccount, msg.sender)) {
        revert ControllerNotEnabled();
    }

    // Set control collateral flag
    executionContext.controlCollateralInProgress = true;

    // Execute call on collateral vault (e.g., transfer)
    (bool success, bytes memory result) = collateralVault.call{value: value}(data);

    executionContext.controlCollateralInProgress = false;

    if (!success) revert ControlCollateralFailed();

    return result;
}

// In collateral vault - allows transfer when controlCollateral in progress
function transfer(address to, uint256 amount) external returns (bool) {
    address from = msgSender();  // Will be violator during liquidation

    // Allow if EVC control collateral is in progress
    if (evc.isControlCollateralInProgress()) {
        // Controller is authorized to transfer on violator's behalf
        _transfer(from, to, amount);
        return true;
    }

    // Normal transfer logic...
}

Bad Debt Handling

// When collateral < debt, bad debt is socialized

/// @notice Socialize bad debt from insolvent account
function socializeLoss(address account) external {
    VaultCache memory cache = initOperation(OP_SOCIALIZE_LOSS);

    // Check account has debt but no collateral
    uint256 debt = debtOf(account);
    if (debt == 0) revert NoDebt();

    address[] memory collaterals = evc.getCollaterals(account);
    for (uint i = 0; i < collaterals.length; i++) {
        if (IEVault(collaterals[i]).balanceOf(account) > 0) {
            revert HasCollateral();  // Must liquidate first
        }
    }

    // Socialize the loss - reduce total borrows without repayment
    // This dilutes existing suppliers
    cache.totalBorrows -= debt;

    // Clear user debt
    users[account].borrowed = 0;

    updateVault(cache);

    emit SocializeLoss(account, debt);
}

Liquidation Incentives

// Liquidation profitability calculation

// Example scenario:
// - Violator has 100 ETH collateral worth $200,000
// - Violator has $180,000 USDC debt
// - Liquidation LTV is 85%, so threshold is $170,000 collateral value
// - Account is unhealthy: $200k * 85% = $170k < $180k debt

// Health factor = $170,000 / $180,000 = 0.944
// With maxLiquidationDiscount = 15%:
// Discount = 15% * (1 - 0.944) = 0.84%

// Liquidator repays $10,000 of debt
// Receives $10,084 worth of ETH (0.84% profit on this liquidation)

// As account becomes more unhealthy, discount increases:
// At health 0.8: discount = 15% * 0.2 = 3%
// At health 0.5: discount = 15% * 0.5 = 7.5%
// At health 0: discount = 15%

Vault Status Check

/// @notice Check vault-level invariants
function checkVaultStatus() external view returns (bytes4) {
    VaultCache memory cache = loadVault();

    // Check supply cap
    if (cache.totalShares > supplyCap()) {
        revert SupplyCapExceeded();
    }

    // Check borrow cap
    if (cache.totalBorrows > borrowCap()) {
        revert BorrowCapExceeded();
    }

    return VAULT_STATUS_CHECK_SELECTOR;
}

Events

event Liquidate(
    address indexed liquidator,
    address indexed violator,
    address indexed collateral,
    uint256 repayAssets,
    uint256 yieldBalance
);

event SocializeLoss(address indexed account, uint256 lossAmount);

Reference Files

• euler-vault-kit/src/EVault/modules/Liquidation.sol - Liquidation module
• euler-vault-kit/src/EVault/shared/LiquidityUtils.sol - Liquidity calculations
• ethereum-vault-connector/src/EthereumVaultConnector.sol - controlCollateral