> For the complete documentation index, see [llms.txt](https://docs.trendle.fi/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.trendle.fi/product/liquidation-engine.md).

# Liquidation Engine

The liquidation engine protects the pooled LP and keeps markets solvent by **fully closing** positions that violate margin safety. It acts when a position’s effective equity (collateral adjusted for funding) or status no longer meets requirements, using the DoA index price.

### <mark style="color:yellow;">When a position becomes liquidatable:</mark>

At evaluation time the engine computes:

* Payout at the current index price (includes trading PnL and funding PnL).
* Remaining collateral = `collateralAmount + fundingPnL`.

A position is **LIQUIDATABLE** if any of the following is true:

1. Margin call: `remainingCollateral ≤ 0` or `payout ≤ liquidationThreshold × remainingCollateral` (works with or without leverage).
2. Forced take-profit: `payout ≥ maxPayout` (the configured cap / profit ceiling).
3. Funding drain: funding fees have consumed the user’s entire collateral (or an admin-set fraction), even if price PnL is positive.
4. Index / token delisted: the relevant index or settlement token is no longer in circulation / disabled.
5. Whitelist removal: the trader’s address has been removed from the whitelist.

> The check is performed inside the position evaluation routine; if any rule trips, status returns **LIQUIDATABLE**.

### <mark style="color:yellow;">Full vs. partial liquidation</mark>

* The current implementation fully closes liquidatable positions *(no partial unwind)*. The trade’s status becomes CLOSED, market open-interest is reduced, and reserves are reconciled in the Pool.
* Reserve bookkeeping happens via the reserve-adjustment path *(unlocking previously locked capacity and settling the LP delta)*.

### <mark style="color:yellow;">Health Factor</mark>

The Health Factor *(HF)* shows how close your position is to liquidation. It ranges from 100% *(completely safe)* to 0% *(fully liquidated)* and updates continuously as the index level changes.

How it’s calculated:

1. Measure both liquidation distances.\
   A position might be liquidated for two MAIN reasons ( there are 5 of them in total) - margin call or forced take-profit. The system measures how far the current index level is from each liquidation point.
2. Convert distances to percentages.\
   Each distance is converted to a scale from 0% to 100%, where:
   * 100% = at entry level *(safe)*
   * 0% = at liquidation level
3. Take the minimum value.\
   The smaller of the two percentage distances determines your Health Factor, since liquidation occurs if either condition is hit first.

$$
\text{Health Factor} = \min\bigl(\text{Margin Distance %},\ \text{Profit Cap Distance %}\bigr)
$$

If you entered a position at level 100 and your liquidation level is 50:

* At level 100, HF = 100% *(fully safe)*
* At level 50, HF = 0% *(liquidated)*\
  Between them, the value decreases linearly.\
  So at level 75, HF = 50%, and at level 62.5, HF = 25%

### <mark style="color:yellow;">Math TL;DR</mark>

* $$Payout = collateral + tradingPnL + fundingPnL$$ capped by `maxPayout`.
* Margin call rule: liquidate if payout is too small relative to equity baseline (`collateral + fundingPnL`) at the configured threshold, or if equity baseline ≤ 0.
* Funding drain rule: liquidate when funding consumes all (or the configured share of) collateral.
* Settlement waterfall: fee is taken from payout and sent to the fee receiver; remainder (if positive) to the trader; Pool reserves are reconciled. The treasury never pays *(it only receives protocol fees)*.