Skip to content

Instantly share code, notes, and snippets.

@Aboudjem

Aboudjem/32-liquidator.md

Last active March 30, 2026 08:00
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save Aboudjem/11b57605ff9f7db933f037b4854017b2 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save Aboudjem/11b57605ff9f7db933f037b4854017b2 to your computer and use it in GitHub Desktop.
Download ZIP
Integra PRD: 32-liquidator
Raw
32-liquidator.md

Liquidator

Owner: Nawar | Ship: Week 3-4 | Est: 0.5-1 day | Chain: integra-testnet-1 (EVM 26218) URL: liquidator.integralayer.com

Overview

Monitors undercollateralized lending positions and liquidates them before they create bad debt. When a borrower's health factor drops below 1.0, anyone can trigger liquidation -- repaying part of the debt and seizing collateral at a 5% bonus. Keeps the lending protocol solvent. Can be operated manually via the dashboard or autonomously via an AgentAuth-authorized bot running 24/7. This is the safety net that protects every lender's deposits.

Features

  • Liquidation Dashboard — Lists all positions approaching liquidation, sorted by health factor (most urgent first)
  • Position Detail View — Shows borrower address, collateral type and value, debt amount, current LTV, health factor, and projected liquidation bonus
  • One-Click Liquidate — User repays a portion of the borrower's debt and receives collateral plus 5% bonus in a single transaction
  • Profit Preview — Calculates expected return before executing, accounting for gas costs and bonus
  • Auto-Liquidate Mode — User deposits IRL and enables a bot that autonomously liquidates profitable positions as they appear
  • Agent Mode — AgentAuth-authorized bot runs liquidations 24/7 without Web3Auth, fully autonomous
  • Liquidation History — Past liquidations with full breakdown: borrower, collateral seized, debt repaid, bonus earned, net profit
  • Health Factor Monitor — Real-time tracking of all positions with health factor below 1.2 (approaching danger)
  • Max Liquidation Cap — 50% of borrower's debt per liquidation call to prevent full wipeout
  • Configurable Bonus — 5% default liquidation bonus, configurable per collateral asset type
  • PT Token Support — Handles PT tokens from Yield Splitter as collateral during liquidation
  • Price Feed Integration — Reads collateral prices from DEX TWAP or oracle for accurate health factor calculation
  • Gas-Aware Execution — Auto-liquidate respects a max gas price setting to ensure profitability

Functions

  • liquidate(borrower, collateralAsset, debtToCover) — Repays debt, seizes collateral plus bonus
  • getLiquidatablePositions() — Returns all addresses with health factor below 1.0, sorted by urgency
  • getPositionHealth(borrower) — Returns health factor, LTV, and liquidation threshold for a borrower
  • getLiquidationBonus(collateralAsset) — Returns the bonus percentage for a given collateral type
  • getProfit(borrower, collateralAsset, debtToCover) — Previews profit before executing (bonus minus gas)
  • setAutoLiquidate(enabled, maxGasPrice) — Toggles auto-liquidation mode for the caller's address
  • getAutoLiquidateStatus(user) — Returns whether auto-liquidate is enabled and current settings
  • getLiquidationHistory(liquidator) — Returns past liquidation records with profit/loss per tx

User Flow

  1. User connects wallet via Web3Auth
  2. Dashboard shows all positions approaching liquidation sorted by health factor
  3. User clicks a position to see full details: borrower, collateral, debt, LTV, bonus
  4. User clicks "Preview Profit" to see expected return after gas
  5. User clicks "Liquidate" -- repays portion of debt, receives collateral + 5% bonus
  6. Alternatively, user enables auto-liquidate: deposits IRL, sets max gas price, bot handles the rest
  7. History tab shows all past liquidations with realized profit per tx
  8. Agent mode: an AgentAuth bot runs liquidations autonomously around the clock

Deliverables

  • Liquidation dashboard with real-time health factor monitoring (positions below 1.2)
  • Position detail view with borrower info, collateral, debt, LTV, and bonus display
  • One-click liquidation flow with profit preview
  • Auto-liquidate mode (deposit IRL, set max gas, bot runs autonomously)
  • Agent mode via AgentAuth for 24/7 autonomous liquidation
  • 50% max debt cap per liquidation call
  • Liquidation history page with per-tx profit breakdown
  • Price feed integration (DEX TWAP or oracle)
  • PT token collateral support (from Yield Splitter)
  • Event logging for all liquidations (borrower, liquidator, collateral seized, debt repaid, bonus)

Integration Points

  • Depends on: LendingPool.sol (position data, health factors), DEX (collateral price feeds via TWAP or oracle), Yield Splitter (PT token collateral), AgentAuth (autonomous bot permissions)
  • Used by: Lending App (keeps it solvent), DEX (liquidators sell seized collateral), Agent Arena (agent mode monitoring)
  • Explorer: Integra Explorer (all liquidation txs indexed with event data)

XP Rewards

Action Points
Liquidate a position +30 XP
Early liquidation (before health factor drops below 0.8) +50 XP bonus
Enable auto-liquidate mode +20 XP
First liquidation on a new collateral type +40 XP bonus
Cumulative 10 liquidations +100 XP badge

Success Metrics

Metric Target
Positions liquidated before bad debt occurs 100%
Average time from health factor <1.0 to liquidation <5 minutes
Unique liquidators (manual + agent) 20+
Auto-liquidate mode activations 10+
Total liquidation volume in first month 50,000+ IRL
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment