In Aave V3, the close factor limits debt repayable in one liquidation, while the liquidation bonus sets the extra collateral exchanged for that repayment. They use different bases: the close factor constrains debt; the bonus applies to its collateral equivalent. Actual repayment also depends on the selected debt, available collateral and leftover-balance rules.
A “50% close factor and 8% bonus” therefore does not mean taking 58% of the collateral. Work through the repayment ceiling first, translate the accepted repayment into collateral, then check the fee split and what remains.
This article follows the EVM implementation of Aave V3 Origin 3.7 at commit cff15de, inspected on 28 October 2026. Applying it to a real account requires checking that pool's deployed implementation and parameters at the relevant block.
Give each control its own job
Aave's V3 overview describes liquidation eligibility when health factor falls below 1. Eligibility alone does not establish how much a particular transaction will repay.
| Control | Question it answers | Relevant base |
|---|---|---|
| Liquidation threshold | Is collateral support sufficient? | Eligible collateral value |
| Close factor | How much debt may this call cover? | Debt value under the applicable branch |
| Liquidation bonus | How much extra collateral accompanies repayment? | Collateral equivalent of debt repaid |
| Liquidation protocol fee | How is the bonus divided? | Bonus collateral |
The distinction between LTV and liquidation threshold belongs before this calculation. Once eligibility is established, the close factor and bonus determine different parts of the settlement.
The selected revision uses an account-wide denominator for the default debt ceiling. That redesign dates to V3.3: it replaced the earlier per-reserve application of the default fraction. The V3.3 feature specification explains the change. “Half the debt” needs an explicit answer to “which debt?”
Select the branch before calculating collateral
In the pinned V3 liquidation logic, the initial ceiling is the entire selected debt balance. The default cap applies only when both selected reserve values are at least $2,000 and health factor is strictly greater than 0.95.
The $2,000 size boundary and $1,000 leftover minimum come from constants that assume an eight-decimal USD oracle base. For a pool using another base, check its implementation's adjusted constants before interpreting these amounts.
| Account and selected reserves | Initial repayment ceiling |
|---|---|
| Health factor at or below 0.95 | Entire selected debt |
| Selected collateral or selected debt below $2,000 | Entire selected debt |
| Otherwise, with health factor below 1 | Smaller of selected debt and 50% of total account debt value, converted into the selected debt token |
The caller may request less. Available collateral can reduce repayment further, and the dust check can reject a candidate. A 100% ceiling permits coverage of the selected debt; it does not require repayment of every asset in the account.
Equality matters: health factor exactly 0.95 bypasses the default cap; selected reserve values exactly $2,000 satisfy the size conditions. Use full precision rather than a rounded dashboard label.
An illustrative call that repays two thirds of one debt
Consider a constructed account with invented tokens C, D and E. Every price, balance, threshold and fee below is a teaching assumption, not a live reserve configuration.
The borrower has 145.5 C at $100 each, 9,000 D of debt at $1 each, and 3,000 E of debt at $1 each. C is the only collateral, with an 80% liquidation threshold. Ordinary mode applies. Set the gross liquidation bonus to 8% and the protocol's share of that bonus to 15%. The bonus multiplier is 1.08: in the code's percentage units, 10,800 represents 108% of base collateral.
Assume current accrued balances, sufficient D spending allowance and no other restriction. The liquidator requests underlying C rather than aTokens; assume enough C is available for that delivery. Let C have 18 decimals, D and E six decimals, and relevant supply and debt indices equal one at this illustrative snapshot. The scaled-balance explanation shows why real indexed balances need another conversion.
The starting health factor is ($14,550 × 80%) ÷ $12,000 = 0.97. Liquidation is eligible. Both selected reserve values exceed $2,000, so the default branch applies.
The liquidator selects D debt and C collateral, requesting repayment of 7,000 D. Half the total $12,000 debt is $6,000. With D at $1, the cap reduces the requested repayment to 6,000 D. That is two thirds of D's 9,000-token balance. Applying 50% only to D would incorrectly produce 4,500 D.
The collateral equivalent is 60 C. Adding 8% gives 64.8 C removed from the borrower's supply claim. The bonus portion is 4.8 C, and its 15% protocol allocation is 0.72 C. The liquidator receives 64.08 C of underlying. The protocol receives aTokens representing 0.72 C at the assumed index, through the pinned treasury-transfer path.
| Component | Quantity | Value at assumed prices |
|---|---|---|
| Requested debt coverage | 7,000 D | $7,000 |
| Actual debt repaid | 6,000 D | $6,000 |
| Collateral equivalent of repayment | 60 C | $6,000 |
| Gross extra collateral | 4.8 C | $480 |
| Total borrower collateral reduction | 64.8 C | $6,480 |
| Treasury aToken allocation | 0.72 C equivalent | $72 |
| Liquidator allocation | 64.08 C | $6,408 |
The transfer identity in C-equivalent units is 64.8 C = 64.08 C + 0.72 C. The $72 allocation is already inside the $480 gross bonus; adding it again would overstate the borrower's penalty. The liquidator's $408 valuation uplift is 6.8% of repayment before gas, financing and disposal costs. The bonus-versus-penalty ledger explains why that uplift does not establish profit.
The account retains 80.7 C worth $8,070, 3,000 D debt and 3,000 E debt. The selected collateral and selected D debt both remain above $1,000, so this candidate passes the leftover check. At unchanged inputs, health factor becomes ($8,070 × 80%) ÷ $6,000 = 1.076.
That outcome is calculated, not promised by the default close factor. Another collateral threshold, bonus or price snapshot can produce a different remaining health factor.
A repayment below the ceiling can still fail
The V3.3 cleanup specification explains the separate leftover rule. In the pinned revision, when neither selected debt nor selected collateral is fully cleared, both remaining values must be at least $1,000. A failed check reverts the call; it does not automatically enlarge the requested repayment.
Use a second, independent illustrative account: 23.0375 C worth $2,303.75, a single 1,900 D debt, and the same prices, 80% threshold and 8% bonus. Its health factor is also 0.97. Since selected debt is below $2,000, the initial ceiling permits all 1,900 D.
Each row starts from that account afresh. Collateral reduction includes the protocol allocation; splitting it between recipients does not change the amount left for the borrower.
| Requested repayment | Gross C reduction | Debt left | Collateral value left | Leftover check |
|---|---|---|---|---|
| 900 D | 9.72 C | $1,000 | $1,331.75 | Passes: both meet minimum |
| 1,000 D | 10.8 C | $900 | $1,223.75 | Reverts: debt below minimum |
| 1,900 D | 20.52 C | $0 | $251.75 | Passes: selected debt cleared |
Repaying more can therefore turn a permissible partial candidate into a rejected one before full repayment becomes permissible. The middle row describes rejected candidate balances. After its revert, the liquidation has not changed the starting balances.
In the last row, $251.75 of collateral may remain because the selected debt is fully cleared. The minimum is conditional, rather than a universal ban on every balance below $1,000.
Resolve amounts that diverge from an estimate
The selected collateral is insufficient. A debt ceiling does not prove enough collateral exists to deliver the corresponding bonus. The implementation can consume the available collateral and recalculate the debt needed. Reconcile the executed amount rather than copying the request into the repayment ledger.
The fee base is wrong. With an 8% gross bonus and 15% protocol share, the protocol allocation in the main example is 1.2% of repayment value. It is not 15% of the $6,480 collateral reduction.
Small-unit rounding differs. V3.7's rounding specification documents floor rounding for gross collateral multiplication and the base portion used to derive bonus collateral, plus ceiling rounding for the protocol fee. Real indices introduce further conversions. The constructed examples divide exactly under the stated units; a real account may not.
Delivery is mistaken for redemption. The liquidator can receive aTokens or underlying collateral. Identify which asset actually arrived. The withdrawal-liquidity and headroom guide separates an account's collateral permission from available underlying liquidity.
V4 guidance is applied to V3. Current V4 liquidation documentation describes bonuses that rise as health factor falls. Aave Labs' V4 engine explanation also describes a target health factor. Those mechanisms are separate from the pinned V3 branches used here.
Reconstruct one call with a compact worksheet
For a real transaction, preserve the chain, pool, implementation, borrower, block and transaction hash. Read prices and configuration from the relevant execution state, including the effective bonus when a special mode applies.
| Field | What to preserve |
|---|---|
| Eligibility | Full-precision health factor and active rules |
| Debt cap | Total account debt, selected debt value and branch |
| Request | Selected assets and caller's requested amount |
| Settlement | Actual repayment and gross collateral reduction |
| Split | Liquidator allocation plus treasury allocation |
| Residuals | Selected remaining debt and collateral; pass or revert |
| Account result | All remaining balances and recomputed health factor |
In the pinned source, LiquidationCall reports the liquidator's collateral allocation, while the protocol allocation moves separately to the treasury as aTokens. Treating that event field as the whole borrower reduction omits the fee. Check corresponding token movements and scaled balances for exact reconciliation.
A complete record should answer three separate questions: what limited repayment, how the accepted repayment became collateral, and why the remaining position passed validation. Keep those answers separate, and the close factor and liquidation bonus become reproducible amounts instead of percentages added to the wrong base.