> ## Documentation Index > Fetch the complete documentation index at: https://xoxno.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Liquidation math > Liquidation bonus, repayment limits, seizure fees, rounding, and bad-debt index accounting. The liquidation planner uses account health and spoke parameters to size repayment and collateral seizure. Liquidators use [`get_liquidation_estimate`](/docs/stellar-lending/dev/liquidations#estimate-the-result) for concrete amounts; this reference explains the calculations and their rounding constraints. USD values and health factors use WAD (`1e18`), indexes and scaled shares use RAY (`1e27`), and rates use BPS (`10000`). Token amounts use each asset's native decimals. Formulas below describe ratios; fixed-point operations apply the rounding stated alongside them. ## Liquidation curve There is no fixed close factor. The account's health factor and its spoke's curve determine the bonus and ideal repayment. Read live values with `get_spoke(spoke_id)`. | Spoke parameter | Default | Constraint and meaning | | - | - | - | | `liquidation_target_hf_wad` | `1.10e18` | Desired health factor after liquidation; above 1 WAD and at most 10 WAD. | | `hf_for_max_bonus_wad` | `0.80e18` | Health factor where the bonus ramp reaches full scale before the remaining caps; positive and below the target. | | `liquidation_bonus_factor_bps` | `10000` | Scales the bonus increment above its base; in `(0, 10000]`. | ## Bonus calculation The collateral-weighted liquidation threshold controls how much bonus can be paid while preserving health: ```text theme={"system"} proportion_seized = weighted_collateral / total_collateral ``` The base bonus is the USD-weighted average of the collateral positions' stamped `liquidation_bonus`, capped at the threshold-derived maximum. To calculate that maximum, round `proportion_seized` up to BPS and clamp it to `[1, BPS]`: ```text theme={"system"} max_bonus_bps = floor(BPS * (BPS - threshold_bps) / threshold_bps) ``` This bounds `(1 + bonus) * proportion_seized` at 1. A zero seizure proportion has a zero maximum. The bonus increases as health factor falls. With the bonus factor expressed as a ratio, the ramp is: ```text theme={"system"} scale = clamp((target_hf - hf) / (target_hf - hf_for_max_bonus), 0, 1) bonus = base + bonus_factor * (max - base) * scale ``` At or above the target, the ramp returns the base. At or below `hf_for_max_bonus`, the scale is 1. The result is subject to a final HF-preserving cap: ```text theme={"system"} cap_bps = floor(hf * BPS / proportion_seized) - BPS ``` The cap applies when the seizure proportion is positive and HF is below 1. The planner selects the quote as follows: | Account state | Ideal repayment | Bonus | | - | - | - | | Collateral is below debt | `min(debt, floor(collateral / (1 + base)))` | Base bonus. | | Collateral covers debt and `cap < base` | Entire debt. | `max(cap, 0)`. | | Other cases | Target-HF repayment, subject to repayment limits. | Ramped bonus, limited by the cap when it applies. | An ideal equal to the entire debt does not require the offered budgets to cover all debt. Smaller offers can succeed, subject to token rounding and the final plan checks. ## Repayment limit The ideal repayment restores the target health factor at the selected bonus. It is bounded by both total debt and the collateral's repayment capacity: ```text theme={"system"} d_max = total_collateral / (1 + bonus) ``` If the ideal would leave less than \$5 of debt, the planner raises the ideal to a full close. This dust adjustment permits full repayment without making it mandatory by itself. Each offered leg is capped at its ceiling-rounded debt balance. For a partial plan, the planner trims excess from the last repayment leg backward. Insolvent plans floor kept native amounts so repayment stays within the collateral-backed quote. Other partial plans can exceed the ideal slightly through native-unit rounding. Each leg remains within its offered budget. The estimate reports unused budgets as `refunds`. A final full-close plan pulls the entire merged offer and the pool refunds excess. Other plans pull only accepted amounts. Authorize the complete offer when a full-close plan is possible; interest accrual and state changes can alter the plan before execution. ## Low-decimal collateral Assets with 0, 1, or 2 decimals can be supplied but cannot be listed as borrowable. Their listing must use zero liquidation fees. A liquidation quantum is one base unit: 1 token at 0 decimals, 0.1 token at 1 decimal, or 0.01 token at 2 decimals. For a solvent partial quote with one low-decimal collateral leg, the planner can raise the ideal to fund one base unit. Partial seizure rounds down to base units. The planner releases repayment that the dropped fractions no longer back. If the plan repays all debt, partial collateral seizure rounds up, capped at the held claim. A plan with no accepted repayment fails with `InvalidPayments`. The two-base-unit collateral floor applies at post-risk validation gates. It means 2, 0.2, or 0.02 tokens at 0, 1, or 2 decimals. Normal liquidation does not enforce that floor. ## Seizure and fees The planned gross seizure value includes the liquidation bonus: ```text theme={"system"} seizure_usd = repaid_usd * (1 + bonus) ``` Seizure is allocated across the account's collateral by USD value and capped at each held balance. The protocol fee applies to the bonus remaining after those caps. A seizure capped below principal has no remaining bonus fee base. | Mode | Fee calculation | Net proceeds | | - | - | - | | `Transfer` | Apply `liquidation_fees / BPS` to the remaining bonus and floor to native units. A positive fee has a one-base-unit minimum, capped by whole units actually paid above repayment principal. | Actual gross underlying payout less the fee. | | `Credit` | `ceil(bonus_scaled * liquidation_fees / BPS)` in supply shares. | Exact seized shares less the share fee. | The Transfer fee cap prevents fees from consuming repayment principal. Token rounding can still remove a small liquidation's profit. Rounding depends on token decimals, prices, indexes, and position size; simulate the complete transaction and enforce a net proceeds bound. If the debt transfer delivers less than planned, every seizure is reduced proportionally with floor rounding. `LiquidationEvent.repaid_usd_wad` reports the measured repayment, capped at each planned debt leg's USD value. Estimates report gross seizure and fees separately. In Transfer mode their units are native collateral tokens; in Credit mode they are RAY-scaled supply shares. A full Transfer payout floors the held claim, while the estimate can round that claim half up. For example, a claim worth 1.6 base units can appear as 2 in the estimate and pay 1 before fees. Clamp estimated gross to the floor of the held claim before subtracting fees or valuing profit. For Credit proceeds, subtract fee shares from seized shares before converting the net shares once through the supply index. Credit position events report token-unit representations with different rounding, so gross-minus-net event amounts do not give exact fees. See [liquidation reconciliation](/docs/stellar-lending/dev/liquidations#verify-the-liquidation). ## Bad-debt accounting Bad-debt cleanup realizes losses through the affected debt market's supply index. The index reduction applies to all outstanding supply-share claims in that market, including unclaimed protocol revenue shares. After capping the loss at the market's supplied value, the pool computes: ```text theme={"system"} reduction_factor = floor(remaining_value * RAY / total_value) new_supply_index = floor(old_supply_index * reduction_factor / RAY) ``` The two floors compound. Before the final clamp, the resulting index is no greater than the corresponding single-step value. The index is bounded below by `SUPPLY_INDEX_FLOOR_RAW = RAY / 1_000` (0.001). Each debt loss affects its own market. An account with debt in several markets can cause a write-down in each of them. See [cleanup eligibility and calls](/docs/stellar-lending/dev/liquidations#clean-bad-debt) and [interest and revenue](/docs/stellar-lending/dev/interest-and-revenue) for the surrounding accounting model. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.