Last active
March 30, 2026 08:07
-
-
Save Aboudjem/4836733856d24d01b554f49cc41bef62 to your computer and use it in GitHub Desktop.
Integra PRD: 32-liquidator (HTML)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| <!DOCTYPE html><html lang="en"><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width,initial-scale=1.0"><title>PRD: Liquidator</title><style>*{margin:0;padding:0;box-sizing:border-box}body{background:#0A0A1A;color:#E8E8F0;font-family:'Inter',system-ui,sans-serif;line-height:1.7}a{color:#00CEC9;text-decoration:none}a:hover{text-decoration:underline}.hero{padding:48px 32px 36px;border-bottom:1px solid #2A2A4A;background:linear-gradient(135deg,#0A0A1A 0%,#1A1040 50%,#0A0A1A 100%)}.hero h1{font-size:2rem;font-weight:800;color:#fff;margin-bottom:8px}.hero .meta{display:flex;gap:10px;flex-wrap:wrap;margin-bottom:12px}.badge{display:inline-block;padding:4px 12px;border-radius:6px;font-size:12px;font-weight:700}.badge-owner{background:rgba(108,92,231,0.15);color:#A29BFE;border:1px solid rgba(108,92,231,0.3)}.badge-week{background:rgba(0,206,201,0.15);color:#00CEC9;border:1px solid rgba(0,206,201,0.3)}.badge-est{background:rgba(0,184,148,0.15);color:#00B894;border:1px solid rgba(0,184,148,0.3)}.container{max-width:900px;margin:0 auto;padding:32px 24px}.section{background:#12122A;border:1px solid #2A2A4A;border-radius:12px;padding:24px;margin-bottom:20px}.section h2{font-size:0.8rem;font-weight:700;color:#8888AA;text-transform:uppercase;letter-spacing:1.5px;margin-bottom:14px;padding-bottom:8px;border-bottom:1px solid #2A2A4A}.section h3{font-size:0.95rem;font-weight:600;color:#E8E8F0;margin:12px 0 6px}.section p{font-size:0.95rem;margin-bottom:8px}.section ul{list-style:none;padding:0}.section ul li{padding:6px 0 6px 20px;position:relative;font-size:0.95rem}.section ul li::before{content:'>';position:absolute;left:0;color:#A29BFE;font-weight:700;font-family:monospace}.section code{background:rgba(108,92,231,0.1);padding:2px 6px;border-radius:4px;font-size:0.88rem;color:#A29BFE}table{width:100%;border-collapse:collapse;font-size:0.9rem;margin:8px 0}th{text-align:left;padding:8px 12px;background:rgba(108,92,231,0.08);color:#A29BFE;font-size:0.75rem;text-transform:uppercase;letter-spacing:1px;border-bottom:1px solid #2A2A4A}td{padding:8px 12px;border-bottom:1px solid rgba(42,42,74,0.5)}.checklist li::before{content:'\2610' !important;color:#8888AA !important;font-family:inherit !important}.back{display:inline-block;margin-bottom:16px;color:#8888AA;font-size:0.9rem}.footer{text-align:center;padding:24px;color:#555577;font-size:0.82rem;border-top:1px solid #2A2A4A;margin-top:32px}</style></head><body><div class="hero"><a class="back" href="https://gist.githack.com/Aboudjem/0af8c2ce9d5b62038a18eeff09603553/raw/integra-testnet-master-plan.html">← Back to Master Plan</a><h1>Liquidator</h1><div class="meta"><span class="badge badge-owner">Nawar</span><span class="badge badge-week">Week 3-4</span><span class="badge badge-est">0.5-1 day</span></div><p style="color:#8888AA;font-size:0.9rem">liquidator.integralayer.com</p></div><div class="container"><div class="section"><h2>Overview</h2><div class=""><p>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.</p></div></div> | |
| <div class="section"><h2>Features</h2><div class=""><ul><li><strong>Liquidation Dashboard</strong> — Lists all positions approaching liquidation, sorted by health factor (most urgent first)</li></ul><ul><li><strong>Position Detail View</strong> — Shows borrower address, collateral type and value, debt amount, current LTV, health factor, and projected liquidation bonus</li></ul><ul><li><strong>One-Click Liquidate</strong> — User repays a portion of the borrower's debt and receives collateral plus 5% bonus in a single transaction</li></ul><ul><li><strong>Profit Preview</strong> — Calculates expected return before executing, accounting for gas costs and bonus</li></ul><ul><li><strong>Auto-Liquidate Mode</strong> — User deposits IRL and enables a bot that autonomously liquidates profitable positions as they appear</li></ul><ul><li><strong>Agent Mode</strong> — AgentAuth-authorized bot runs liquidations 24/7 without Web3Auth, fully autonomous</li></ul><ul><li><strong>Liquidation History</strong> — Past liquidations with full breakdown: borrower, collateral seized, debt repaid, bonus earned, net profit</li></ul><ul><li><strong>Health Factor Monitor</strong> — Real-time tracking of all positions with health factor below 1.2 (approaching danger)</li></ul><ul><li><strong>Max Liquidation Cap</strong> — 50% of borrower's debt per liquidation call to prevent full wipeout</li></ul><ul><li><strong>Configurable Bonus</strong> — 5% default liquidation bonus, configurable per collateral asset type</li></ul><ul><li><strong>PT Token Support</strong> — Handles PT tokens from Yield Splitter as collateral during liquidation</li></ul><ul><li><strong>Price Feed Integration</strong> — Reads collateral prices from DEX TWAP or oracle for accurate health factor calculation</li></ul><ul><li><strong>Gas-Aware Execution</strong> — Auto-liquidate respects a max gas price setting to ensure profitability</li></ul></div></div> | |
| <div class="section"><h2>Functions</h2><div class=""><ul><li><code>liquidate(borrower, collateralAsset, debtToCover)</code> — Repays debt, seizes collateral plus bonus</li></ul><ul><li><code>getLiquidatablePositions()</code> — Returns all addresses with health factor below 1.0, sorted by urgency</li></ul><ul><li><code>getPositionHealth(borrower)</code> — Returns health factor, LTV, and liquidation threshold for a borrower</li></ul><ul><li><code>getLiquidationBonus(collateralAsset)</code> — Returns the bonus percentage for a given collateral type</li></ul><ul><li><code>getProfit(borrower, collateralAsset, debtToCover)</code> — Previews profit before executing (bonus minus gas)</li></ul><ul><li><code>setAutoLiquidate(enabled, maxGasPrice)</code> — Toggles auto-liquidation mode for the caller's address</li></ul><ul><li><code>getAutoLiquidateStatus(user)</code> — Returns whether auto-liquidate is enabled and current settings</li></ul><ul><li><code>getLiquidationHistory(liquidator)</code> — Returns past liquidation records with profit/loss per tx</li></ul></div></div> | |
| <div class="section"><h2>User Flow</h2><div class=""><ul><li>User connects wallet via Web3Auth</li></ul><ul><li>Dashboard shows all positions approaching liquidation sorted by health factor</li></ul><ul><li>User clicks a position to see full details: borrower, collateral, debt, LTV, bonus</li></ul><ul><li>User clicks "Preview Profit" to see expected return after gas</li></ul><ul><li>User clicks "Liquidate" -- repays portion of debt, receives collateral + 5% bonus</li></ul><ul><li>Alternatively, user enables auto-liquidate: deposits IRL, sets max gas price, bot handles the rest</li></ul><ul><li>History tab shows all past liquidations with realized profit per tx</li></ul><ul><li>Agent mode: an AgentAuth bot runs liquidations autonomously around the clock</li></ul></div></div> | |
| <div class="section"><h2>Deliverables</h2><div class="checklist"><ul class="checklist"><li>Liquidation dashboard with real-time health factor monitoring (positions below 1.2)</li></ul><ul class="checklist"><li>Position detail view with borrower info, collateral, debt, LTV, and bonus display</li></ul><ul class="checklist"><li>One-click liquidation flow with profit preview</li></ul><ul class="checklist"><li>Auto-liquidate mode (deposit IRL, set max gas, bot runs autonomously)</li></ul><ul class="checklist"><li>Agent mode via AgentAuth for 24/7 autonomous liquidation</li></ul><ul class="checklist"><li>50% max debt cap per liquidation call</li></ul><ul class="checklist"><li>Liquidation history page with per-tx profit breakdown</li></ul><ul class="checklist"><li>Price feed integration (DEX TWAP or oracle)</li></ul><ul class="checklist"><li>PT token collateral support (from Yield Splitter)</li></ul><ul class="checklist"><li>Event logging for all liquidations (borrower, liquidator, collateral seized, debt repaid, bonus)</li></ul></div></div> | |
| <div class="section"><h2>Integration Points</h2><div class=""><ul><li><strong>Depends on:</strong> LendingPool.sol (position data, health factors), DEX (collateral price feeds via TWAP or oracle), Yield Splitter (PT token collateral), AgentAuth (autonomous bot permissions)</li></ul><ul><li><strong>Used by:</strong> Lending App (keeps it solvent), DEX (liquidators sell seized collateral), Agent Arena (agent mode monitoring)</li></ul><ul><li><strong>Explorer:</strong> Integra Explorer (all liquidation txs indexed with event data)</li></ul></div></div> | |
| <div class="section"><h2>XP Rewards</h2><div class=""><table><thead><tr><th>Action</th><th>Points</th></tr></thead><tbody><tr><td>Liquidate a position</td><td>+30 XP</td></tr><tr><td>Early liquidation (before health factor drops below 0.8)</td><td>+50 XP bonus</td></tr><tr><td>Enable auto-liquidate mode</td><td>+20 XP</td></tr><tr><td>First liquidation on a new collateral type</td><td>+40 XP bonus</td></tr><tr><td>Cumulative 10 liquidations</td><td>+100 XP badge</td></tr></tbody></table></div></div> | |
| <div class="section"><h2>Success Metrics</h2><div class=""><table><thead><tr><th>Metric</th><th>Target</th></tr></thead><tbody><tr><td>Positions liquidated before bad debt occurs</td><td>100%</td></tr><tr><td>Average time from health factor <1.0 to liquidation</td><td><5 minutes</td></tr><tr><td>Unique liquidators (manual + agent)</td><td>20+</td></tr><tr><td>Auto-liquidate mode activations</td><td>10+</td></tr><tr><td>Total liquidation volume in first month</td><td>50,000+ IRL</td></tr></tbody></table></div></div> | |
| </div><div class="footer">Integra Testnet PRD — Liquidator — Chain: integra-testnet-1 (EVM 26218)</div></body></html> |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment