Liquidation & keepers

Liquidation protects the protocol's solvency by closing positions in accounts whose free balance has fallen below their locked-margin requirement. The process is permissioned to a whitelist of keeper addresses but is otherwise fully on-chain and deterministic.

When is an account liquidatable?

An account is eligible for liquidation when:

Account.balance_quote < Account.locked_margin

This condition is evaluated on-chain inside the liquidation entry. If it does not hold at execution time, the transaction aborts — there is no race condition where a healthy account can be erroneously liquidated.

Additional preconditions enforced on-chain:

• The caller's address is in registry.liquidators (whitelist check).
• The target market is in Listed state and the target series is Active.
• The registry is not paused.
• The account holds a non-zero position in the specified series.

The liquidation entry

auth_entry::liquidate_v2<Quote>(
    registry,
    market,
    accounts,
    account_id,
    snapshot,
    strike,
    is_call,
    qty
)

Execution steps:

1. Verify the account is underwater (abort if not).
2. Clamp qty to the account's actual position size in the series.
3. Place an IOC (immediate-or-cancel) market order on the series' embedded DeepBook orderbook.
4. Reconcile the fill: reduce the position, update balances, recompute margin.
5. Charge the liquidation fee: notional × 50 / 10_000 (50 bps) from the liquidated account's balance, paid to the liquidator's on-chain address.
6. If the fee exceeds the account's remaining balance, draw the shortfall from the protocol fee pool.

If the IOC order does not fill (no liquidity on the other side), the position is unchanged. The liquidator can retry when liquidity returns, or another keeper can attempt the same position.

Shorts-closed-first convention

When an account is undercollateralized and holds multiple series positions, keepers prioritize closing short positions first. Short positions are the source of margin requirement; closing them reduces the requirement faster than closing longs. The on-chain entry does not enforce this order, but the Phasis liquidator service follows this heuristic when selecting which series to target.

Keeper architecture

Four keeper services participate in the liquidation lifecycle:

stress-publisher (stateless, polled every ~30 s)

Publishes a fresh StressSnapshot on-chain whenever spot prices move. Each new snapshot triggers MarginRecomputed events for all accounts whose margin requirement changes — this is the primary signal that feeds the liquidator.

liquidator (event-driven, single instance)

At startup, bootstraps a full mirror of all account states and the latest stress snapshot. Then subscribes to four event streams:

• MarginRecomputed — margin requirement changed.
• Deposited — account balance increased.
• Withdrew — account balance decreased.
• StressSnapshotUpdated — new stress grid published.

When any event causes a tracked account to become underwater, the liquidator immediately submits a liquidation PTB. This zero-RPC steady-state design avoids polling every account on every block.

cranker (polled every ~60 s)

Advances market state machines. Relevant to liquidation: the cranker halts markets before expiry, which prevents new orders but does not block liquidation entries — keepers may continue to close underwater positions even in Halted state.

market-maker (single instance per vault)

Places two-sided quotes continuously. Deeper books mean liquidation IOC orders are more likely to fill at reasonable prices, reducing slippage and bad-debt risk.

Liquidator incentive

The 50 bps liquidation fee is paid from the underwater account's balance to the liquidator's address at fill time. This creates a direct financial incentive for external parties to run keeper bots. Phasis operates its own liquidator but the whitelist can include third-party liquidators.

See Fees for the complete fee schedule.