Liquidation System
Liquidations are a critical safety mechanism in ALP that protect the protocol from insolvency. When a position becomes undercollateralized, it can be liquidated to restore the protocol's health and protect lenders.
Understanding Liquidations
What is Liquidation?
Liquidation is the process of forcibly closing or partially closing an undercollateralized position by:
- Seizing some of the borrower's collateral
- Using it to repay outstanding debt
- Returning the position to a healthy state
- Incentivizing the liquidator with a bonus
_10graph LR_10 A[Position<br/>HF < 1.0] --> B[Liquidator<br/>Detected]_10 B --> C[Seize<br/>Collateral]_10 C --> D[Repay<br/>Debt]_10 D --> E[Position<br/>HF = 1.05 ✓]_10 D --> F[Liquidator<br/>Gets Bonus]_10_10 style A fill:#fbb_10 style E fill:#bfb_10 style F fill:#bfb
Why Liquidations are Necessary
Liquidations protect the protocol by preventing insolvency through ensuring debt is always backed by sufficient collateral, protecting lenders by guaranteeing depositors can withdraw their funds, maintaining stability by keeping the system solvent during market volatility, and incentivizing monitoring by rewarding participants who help maintain protocol health.
Liquidation Triggers
Health Factor Threshold
A position becomes liquidatable when its health factor falls below the trigger threshold:
_10Liquidation Trigger: Health Factor < 1.0
_20graph TD_20 subgraph "Health Factor Zones"_20 Safe[HF ≥ 1.1<br/>Safe Zone]_20 Risk[HF: 1.0 - 1.1<br/>At Risk]_20 Liq[HF < 1.0<br/>LIQUIDATABLE]_20 end_20_20 Safe --> Price1[Collateral Price Drop]_20 Safe --> Price2[Interest Accrual]_20 Price1 --> Risk_20 Price2 --> Risk_20 Risk --> Price3[Further Price Drop]_20 Price3 --> Liq_20_20 Liq --> Action[Liquidation<br/>Triggered]_20_20 style Safe fill:#bfb_20 style Risk fill:#ffa_20 style Liq fill:#fbb_20 style Action fill:#f00,color:#fff
What causes health factor to drop:
-
Collateral price decreases
- Your FLOW drops from $1 to $0.80
- Effective collateral value falls
- Health factor decreases proportionally
-
Debt accumulation
- Interest accrues on borrowed amount
- Debt grows over time
- Health factor gradually decreases
-
Combination of factors
- Collateral price drops while interest accrues
- Multiple collateral types move differently
- Debt token price increases relative to collateral
Liquidation Target Health
When a position is liquidated, it's brought to a target health factor:
_10Liquidation Target Health: 1.05
This means not all collateral is seized—only enough to restore the position to a health factor of 1.05. The position remains open after partial liquidation, and the borrower retains their remaining collateral.
Example Liquidation Scenario
_18sequenceDiagram_18 participant Price_18 participant Position_18 participant Liquidator_18 participant Protocol_18_18 Note over Position: Initial: HF = 1.30 ✓<br/>1000 FLOW @ $1<br/>Debt: 615 MOET_18_18 Price->>Position: FLOW drops to $0.75_18 Position->>Position: HF = 0.975 ✗_18_18 Liquidator->>Liquidator: Detect HF < 1.0!_18 Liquidator->>Protocol: Liquidate position_18 Protocol->>Position: Seize ~$146 collateral_18 Protocol->>Position: Repay debt_18 Protocol->>Liquidator: Transfer collateral + bonus_18_18 Note over Position: After: HF = 1.05 ✓<br/>Remaining collateral<br/>Debt partially repaid
Numeric example:
_15Initial State (Healthy):_15- Collateral: 1000 FLOW @ $1 = $1000, factor 0.8 = $800 effective_15- Debt: 615.38 MOET @ $1 = $615.38_15- Health Factor: 800 / 615.38 = 1.30 ✓_15_15After FLOW Price Drops to $0.75:_15- Collateral: 1000 FLOW @ $0.75 = $750, factor 0.8 = $600 effective_15- Debt: 615.38 MOET @ $1 = $615.38_15- Health Factor: 600 / 615.38 = 0.975 ✗ LIQUIDATABLE_15_15After Liquidation to Target HF 1.05:_15- Required effective collateral: 615.38 * 1.05 = $646.15_15- Collateral seized: ~$146.15 worth at market price_15- Remaining collateral: ~$453.85 effective_15- Health Factor: 646.15 / 615.38 = 1.05 ✓
Liquidation Mechanisms
ALP implements three distinct liquidation paths to ensure positions can always be liquidated efficiently.
_24graph TB_24 Liquidatable[Position HF < 1.0]_24_24 Liquidatable --> Path1[Keeper<br/>Repay-for-Seize]_24 Liquidatable --> Path2[Protocol<br/>DEX Liquidation]_24 Liquidatable --> Path3[Auto-Liquidation]_24_24 Path1 --> K1[Keeper repays debt]_24 K1 --> K2[Receives collateral<br/>+ bonus]_24_24 Path2 --> D1[Protocol seizes<br/>collateral]_24 D1 --> D2[Swaps via DEX<br/>for debt token]_24 D2 --> D3[Repays position debt]_24_24 Path3 --> A1[Scheduled scan]_24 A1 --> A2[Batch liquidates<br/>multiple positions]_24 A2 --> A3[Uses DEX path]_24_24 K2 --> Result[Position HF = 1.05 ✓]_24 D3 --> Result_24 A3 --> Result_24_24 style Liquidatable fill:#fbb_24 style Result fill:#bfb
1. Keeper Repay-for-Seize
How it works:
- A keeper (third-party participant) detects an undercollateralized position
- Keeper repays debt with their own funds
- Protocol calculates collateral to seize (debt repaid + liquidation bonus)
- Keeper receives seized collateral
- Position is brought to target health factor (1.05)
_14sequenceDiagram_14 participant Keeper_14 participant Protocol_14 participant Position_14_14 Keeper->>Keeper: Detect position #42<br/>HF = 0.98_14 Keeper->>Protocol: Repay 100 MOET debt_14 Protocol->>Position: Reduce debt by 100_14 Protocol->>Protocol: Calculate:<br/>100 + 10% bonus = 110 value_14 Protocol->>Position: Seize equivalent collateral_14 Position->>Keeper: Transfer ~108 FLOW_14 Protocol->>Position: Update HF = 1.05 ✓_14_14 Note over Keeper,Position: Keeper profits ~8 MOET value
Key characteristics: The system is permissionless—anyone can act as a keeper—and incentivized, with keepers earning a liquidation bonus (typically 5-10%). It's precise, using only the exact amount needed, and instant, with a single transaction resolving the liquidation.
Benefits: This approach enables fast response to undercollateralization, distributed monitoring through many keepers, market-driven efficiency, and eliminates protocol DEX dependency.
2. Protocol DEX Liquidation
How it works:
- Protocol detects undercollateralized position
- Protocol seizes collateral from position
- Protocol swaps collateral via allowlisted DEX
- Swap output is used to repay debt
- Any remainder is returned appropriately
- Position is brought to target health factor
_17sequenceDiagram_17 participant Protocol_17 participant Position_17 participant DEX_17 participant Oracle_17_17 Protocol->>Position: Detect HF = 0.98_17 Protocol->>Oracle: Get FLOW price_17 Oracle-->>Protocol: $0.98 per FLOW_17 Protocol->>Position: Seize 150 FLOW_17 Protocol->>DEX: Swap 150 FLOW_17 DEX-->>Protocol: Return ~147 MOET_17 Protocol->>Protocol: Check slippage<br/>vs oracle price_17 Protocol->>Position: Repay 147 MOET_17 Position->>Position: HF = 1.05 ✓_17_17 Note over Protocol,Position: Slippage protection ensures<br/>fair liquidation price
Key characteristics: Protocol DEX liquidation is protocol-executed (no external keeper needed), integrates with decentralized exchanges for swaps, includes slippage protection through maximum deviation checks versus oracle prices, and can be automated by either the protocol or keepers.
Slippage Protection:
The protocol ensures the DEX price doesn't deviate too much from the oracle price, preventing manipulation and unfair liquidations.
Example Flow:
_10Position #42: 1000 FLOW collateral, 650 MOET debt, HF = 0.98_10↓_10Protocol seizes 150 FLOW_10↓_10Swaps via DEX: 150 FLOW → ~147 MOET (with slippage check)_10↓_10Repays 147 MOET to position debt_10↓_10Position: 850 FLOW collateral, 503 MOET debt, HF = 1.05 ✓
3. Auto-Liquidation
How it works:
- Scheduled automation or keeper triggers scan
- System identifies all undercollateralized positions
- For each position, executes DEX liquidation path
- Subject to same oracle and DEX safety checks
- Events emitted for each liquidation
_11graph TD_11 Timer[Scheduled<br/>Trigger] --> Scan[Scan All<br/>Positions]_11 Scan --> Check{HF < 1.0?}_11 Check -->|Yes| Batch[Add to<br/>Liquidation Batch]_11 Check -->|No| Skip[Skip]_11 Batch --> Max{Reached<br/>max batch?}_11 Max -->|No| Check_11 Max -->|Yes| Execute[Execute DEX<br/>Liquidations]_11 Execute --> Events[Emit<br/>Events]_11_11 style Execute fill:#f9f,stroke:#333,stroke-width:2px
Key characteristics: Auto-liquidation can run on a scheduled timer (e.g., every block or every minute), handle multiple positions through batch processing, apply the same warm-up and deviation safety checks, and provide detailed event logging per position.
Benefits: This mechanism provides hands-free liquidation protection, guaranteed execution that's not dependent on keeper availability, integration capability with off-chain automation, and serves as a protocol safety net.
Safety Features
ALP includes multiple safety mechanisms to ensure liquidations are fair and protect against manipulation.
_23graph TB_23 subgraph "Safety Layers"_23 S1[Oracle Staleness<br/>Checks]_23 S2[Oracle Deviation<br/>Guards]_23 S3[DEX Price<br/>Deviation]_23 S4[Liquidation<br/>Warm-up]_23 S5[Circuit<br/>Breakers]_23 end_23_23 Liquidation[Liquidation<br/>Request] --> S1_23 S1 -->|Pass| S2_23 S2 -->|Pass| S3_23 S3 -->|Pass| S4_23 S4 -->|Pass| S5_23 S5 -->|Pass| Execute[Execute<br/>Liquidation]_23_23 S1 -->|Fail| Revert[Revert:<br/>Stale price]_23 S2 -->|Fail| Revert2[Revert:<br/>Large deviation]_23 S3 -->|Fail| Revert3[Revert:<br/>DEX manipulation]_23 S4 -->|Fail| Revert4[Revert:<br/>Still warming up]_23 S5 -->|Fail| Revert5[Revert:<br/>Paused]_23_23 style Execute fill:#bfb
Oracle Staleness Checks
Prices must be recent and valid:
_10- Maximum age: staleThreshold (typically 5 minutes)_10- If price is too old: liquidation reverts_10- Per-token configuration: different tokens can have different thresholds
Why this matters:
- Prevents liquidations based on stale/incorrect prices
- Ensures fairness during oracle downtime
- Protects borrowers from false liquidations
Oracle Deviation Guards
Large price movements are checked:
_10maxDeviationBps: Maximum change vs last price snapshot_10Example: 1000 bps = 10% maximum deviation_10_10If price moves >10% in single update:_10- Liquidation may be paused or rejected_10- Additional verification required_10- Protects against oracle manipulation
DEX Price Deviation
For DEX-based liquidations, the swap price must align with oracle:
_11dexOracleDeviationBps: Maximum deviation between DEX and oracle_11_11Example:_11- Oracle price: 1 FLOW = 1 MOET_11- DEX swap: 150 FLOW → 145 MOET_11- Deviation: ~3.3% ≈ 333 bps_11_11If deviation > dexOracleDeviationBps:_11- Liquidation reverts_11- Prevents MEV exploitation_11- Ensures fair liquidation prices
Liquidation Warm-up Period
After the protocol is unpaused, liquidations have a warm-up delay:
_10timeline_10 title Protocol Unpause Timeline_10 Paused : Protocol offline_10 : No operations allowed_10 T+0 : Protocol unpauses_10 : Trading resumes_10 : Liquidations still disabled_10 T+300s : Warm-up complete_10 : Liquidations enabled_10 : Full functionality restored
Configuration:
_10liquidationWarmupSec: Delay after unpause before liquidations enabled_10Example: 300 seconds (5 minutes)_10_10Why:_10- Gives borrowers time to add collateral_10- Prevents immediate liquidations after downtime_10- Allows prices to stabilize
Circuit Breakers
Protocol can pause liquidations in emergencies:
_10liquidationsPaused: Boolean flag_10_10When true:_10- All liquidation functions revert_10- Positions cannot be liquidated_10- Borrowing may also be restricted_10- Used during emergencies, upgrades, or oracle issues
Liquidation Incentives
Liquidation Bonus
Keepers earn a bonus for performing liquidations:
_10graph LR_10 Keeper[Keeper Repays<br/>100 MOET] --> Protocol[Protocol<br/>Calculates]_10 Protocol --> Bonus[Seize Value:<br/>108 MOET equivalent]_10 Bonus --> Profit[Keeper Profit:<br/>8 MOET 8% bonus]_10_10 style Profit fill:#bfb,stroke:#333,stroke-width:2px
Example:
_10Typical bonus: 5-10% of repaid debt_10_10- Keeper repays: 100 MOET_10- Collateral value at liquidation bonus: ~108 MOET equivalent_10- Keeper profit: ~8 MOET (8% bonus)_10_10Formula:_10Collateral Seized = (Debt Repaid * (1 + Liquidation Bonus)) / Collateral Price
Economic Dynamics
_14graph TD_14 subgraph "Liquidation Economics"_14 A[Small Position] --> A1[Low profit<br/>after gas]_14 A1 --> A2[May not be liquidated<br/>by keepers]_14_14 B[Large Position] --> B1[High profit<br/>covers gas easily]_14 B1 --> B2[Attractive to keepers]_14_14 A2 --> Backup[Auto-liquidation<br/>provides backup]_14 B2 --> Competition[Multiple keepers<br/>compete]_14 end_14_14 style Backup fill:#bfb_14 style Competition fill:#bbf
Considerations:
- Gas Costs: Profitability = Liquidation Bonus - Gas Costs
- Position Size: Small positions may not be profitable to liquidate
- Competition: Multiple keepers compete for liquidations (first come, first served)
- MEV: Sophisticated keepers may use advanced techniques
- Safety Net: Auto-liquidation provides backup for unprofitable liquidations
Liquidation Events and Monitoring
Monitoring Your Position
_16graph TD_16 Monitor[Monitor Health Factor] --> Check{HF Status?}_16_16 Check -->|HF > 1.3| Safe[Safe<br/>Continue monitoring]_16 Check -->|HF: 1.1-1.3| Warning[Early Warning<br/>Consider adding collateral]_16 Check -->|HF: 1.0-1.1| Urgent[Urgent!<br/>Immediate action needed]_16 Check -->|HF < 1.0| Critical[CRITICAL<br/>Position liquidatable!]_16_16 Warning --> Actions1[Add collateral<br/>or repay debt]_16 Urgent --> Actions2[Add substantial collateral<br/>or repay significant debt]_16 Critical --> Actions3[Emergency measures<br/>May be too late]_16_16 style Safe fill:#bfb_16 style Warning fill:#ffa_16 style Urgent fill:#fbb_16 style Critical fill:#f00,color:#fff
To avoid liquidation, you should set up alerts to monitor when health factor drops below 1.3, watch collateral token prices closely, monitor interest accrual since debt grows over time, use automation through auto-rebalancing or auto-repayment, and maintain a safety buffer by keeping your health factor well above 1.1.
Liquidation Warning Signs
Early warnings (HF = 1.3 → 1.1):
- Time to add collateral or repay debt
- Rebalancing may trigger automatically
- Still safe but approaching risk zone
Urgent warnings (HF = 1.1 → 1.0):
- Immediate action required
- Liquidation imminent if health continues to drop
- Add substantial collateral or repay significant debt
Critical (HF < 1.0):
- Position is liquidatable
- May be liquidated at any moment
- Severe consequences (loss of collateral with liquidation penalty)
Protecting Against Liquidation
Protection Strategies
_16graph LR_16 subgraph "Prevention Strategies"_16 S1[Conservative<br/>Collateralization<br/>HF > 1.5]_16 S2[Diversified<br/>Collateral<br/>Multiple tokens]_16 S3[Regular<br/>Monitoring<br/>Daily checks]_16 S4[Quick Response<br/>TopUpSource<br/>configured]_16 S5[Stable<br/>Collateral<br/>Lower volatility]_16 end_16_16 S1 --> Protection[Liquidation<br/>Protection]_16 S2 --> Protection_16 S3 --> Protection_16 S4 --> Protection_16 S5 --> Protection_16_16 style Protection fill:#bfb,stroke:#333,stroke-width:3px
-
Conservative collateralization:
- Target health factor > 1.5
- Provides buffer against price drops
- Reduces liquidation risk
-
Diversified collateral:
- Use multiple token types
- Reduces impact of single token price drop
- Improves overall stability
-
Regular monitoring:
- Check health factor daily
- Set up alerts and notifications
- Use automation tools
-
Quick response capability:
- Keep liquid funds available
- Set up TopUpSource for auto-repayment
- Have repayment transactions ready
-
Use stable collateral:
- Stablecoins have lower volatility
- Higher collateral factors
- More predictable liquidation risk
Recovery from Near-Liquidation
If your health factor is approaching 1.0, you have three options:
_20graph TD_20 Crisis[Health Factor < 1.1<br/>Approaching Liquidation] --> Option1[Option 1:<br/>Add Collateral]_20 Crisis --> Option2[Option 2:<br/>Repay Debt]_20 Crisis --> Option3[Option 3:<br/>Trigger Rebalancing]_20_20 Option1 --> Deposit[Deposit more tokens]_20 Deposit --> Result1[Increases effective collateral<br/>Improves HF]_20_20 Option2 --> Repay[Repay MOET debt]_20 Repay --> Result2[Decreases debt<br/>Improves HF]_20_20 Option3 --> AutoPull[Auto-pulls from TopUpSource]_20 AutoPull --> Result3[Automatically repays debt<br/>Improves HF]_20_20 Result1 --> Safe[Health Factor > 1.1 ✓]_20 Result2 --> Safe_20 Result3 --> Safe_20_20 style Crisis fill:#fbb_20 style Safe fill:#bfb
_10// Option 1: Add collateral_10position.deposit(collateralVault: <-additionalFLOW)_10_10// Option 2: Repay debt_10position.repay(repaymentVault: <-moetRepayment)_10_10// Option 3: Trigger rebalancing (if TopUpSource configured)_10pool.rebalancePosition(pid: yourPositionID, force: true)
See GitHub for complete API documentation.
Advanced Topics
Partial vs Full Liquidation
_15graph LR_15 Position[Liquidatable<br/>Position] --> Check{Sufficient<br/>collateral?}_15_15 Check -->|Yes| Partial[Partial Liquidation]_15 Partial --> P1[Seize portion<br/>of collateral]_15 P1 --> P2[Repay portion<br/>of debt]_15 P2 --> P3[HF = 1.05<br/>Position remains open]_15_15 Check -->|No| Full[Full Liquidation<br/>Rare case]_15 Full --> F1[Seize all<br/>collateral]_15 F1 --> F2[Repay maximum<br/>possible debt]_15 F2 --> F3[Position closed<br/>Protocol may take loss]_15_15 style Partial fill:#bbf_15 style Full fill:#fbb
- Partial liquidation: Position brought to target health (1.05), remains open (most common)
- Full liquidation: Rare; only if position value can't cover debt + bonus
Multi-Collateral Liquidations
When position has multiple collateral types:
- Liquidation logic prioritizes based on configuration
- May seize from multiple collateral types
- Calculation ensures fair distribution
Flash Loan Liquidations
Advanced keepers may use flash loans for zero-capital liquidations:
_16sequenceDiagram_16 participant Keeper_16 participant FlashLoan_16 participant Protocol_16 participant DEX_16_16 Keeper->>FlashLoan: Flash borrow MOET_16 FlashLoan-->>Keeper: 100 MOET (+ fee)_16 Keeper->>Protocol: Liquidate with borrowed MOET_16 Protocol-->>Keeper: Receive collateral_16 Keeper->>DEX: Swap collateral → MOET_16 DEX-->>Keeper: ~108 MOET_16 Keeper->>FlashLoan: Repay 100 MOET + fee_16 Keeper->>Keeper: Keep profit!_16_16 Note over Keeper: No upfront capital needed!
This allows liquidations without upfront capital.
Summary
Liquidation Triggers:
- 🚨 Health Factor < 1.0 (undercollateralized)
- 📉 Collateral price drops or interest accrual
- 🎯 Target: Restore HF to 1.05 after liquidation
Three Liquidation Paths:
- Keeper Repay-for-Seize: Third parties repay debt, earn bonus
- Protocol DEX Liquidation: Automated swap and repayment
- Auto-Liquidation: Scheduled batch processing
Safety Features:
- ✅ Oracle staleness checks
- ✅ Oracle deviation guards
- ✅ DEX price deviation limits
- ✅ Liquidation warm-up periods
- ✅ Circuit breakers for emergencies
Protection Strategies:
- Maintain HF > 1.5 for safety buffer
- Set up TopUpSource for auto-protection
- Monitor positions regularly
- Use stable collateral when possible
- Diversify collateral types
Mathematical Foundation
For detailed liquidation formulas and calculations:
- Liquidation Trigger Math: Liquidation Mathematics
- Collateral Seized Calculation: Collateral Seized Formula
- Health Factor Formulas: Health Factor Definition
- Maximum Price Drop: Safe Price Drop Calculations
Next Steps
- Understand automation: Rebalancing Mechanics
- See the big picture: Position Lifecycle
- Explore credit mechanics: Credit Market Mechanics
- Learn prevention strategies: FCM Yield-Powered Protection
Liquidations are a last resort safety mechanism. With proper monitoring, conservative collateralization, and automation (especially FCM's yield-powered protection), you can avoid liquidation entirely. The system is designed to give you ample warning and multiple recovery options before liquidation occurs.