# 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)*.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.trendle.fi/product/liquidation-engine.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.