> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devnet.perp.ordr.trade/llms.txt
> Use this file to discover all available pages before exploring further.

# Batching and Liquidations

> How the crank clears queued orders and keeps the book solvent

A trader's order never fills the instant it's submitted. It locks margin,
checked conservatively enough that a later fill can never make the position
immediately underwater, and then queues. Clearing is a separate step, run by
a permissionless crank, once per slot at most, for one market at a time.

## Queueing

`submit_order` (isolated) or `submit_cross` drops a trader's order into one
of a market's **8 queue shards**, 32 orders each, 256 in flight per market.
Before it queues, the margin it reserves is checked against the worst price
the next batch could realistically give it:

```
worst   = long ? limit : max(limit, best_bid)
imr_req = worst price's margin requirement
adverse = how far the limit sits on the losing side of the oracle
imr_o   = the oracle price's margin requirement

margin must cover both imr_req, and (margin - adverse) must cover imr_o
```

Checking both the worst fill price and the oracle price, with the gap
between them, up front means a batch fill never has to be undone later for
being under-margined. If the trader's free balance alone falls short, the
difference is pulled automatically from their cross collateral, if they
have any.

## What one `uncross` call does

Clearing a market's queue is one instruction, `uncross`. It can run at most
once per slot per market, enforced on-chain, and in practice a reference
crank only calls it when there's something to do: orders are actually
queued, a liquidation heap looks crossed, or funding is due a sample. Each
call, in order:

1. **Fetches a fresh oracle price.** A price no newer than the last one
   already used is rejected outright.
2. **Collects every maker's mid that is still fresh.** A stale mid just
   drops that maker out of this batch, see
   [The Shared Book](https://docs.devnet.perp.ordr.trade/architecture/shared-book.md).
3. **Merges every included maker's resting orders into one ladder** and
   finds the real best bid, best ask, and a mark price: the midpoint of the
   two, valid only when the book is two-sided, uncrossed, inside the oracle
   band, and at least 10 lots deep on both sides. Otherwise there's no mark
   this pass, and funding doesn't accrue.
4. **Samples funding** from that mark against the oracle, carrying the
   remainder forward so a quiet market still accrues the right amount over
   time.
5. **Steps the liquidation brake price** toward the oracle by at most 1% per
   second, never further.
6. **Scans cross accounts**, if this market allows cross margin: refreshes
   this market's row in the shared cross price table, then checks the next
   64 cross accounts in line and force-closes part of any that's gone under
   maintenance, filled by this same batch.
7. **Liquidates**, up to 8 positions per side per call: while this market's
   long or short liquidation heap has a top position crossed by the braked
   price, it's closed, partially if that alone restores health, in full
   only once equity is gone.
8. **Clears the batch auction**, the actual matching step, described below.
9. **Rolls this market's solvency numbers into the pool**, and advances the
   batch counter.

## The batch auction

For each side, asks against buy demand and bids against sell demand, the
same idea runs:

```
walk the merged ladder, best price first:
  demand(px) = everyone's size whose limit accepts px
  supply    += this level's size
  stop at the first level where supply >= demand

clear price = that level's price
every eligible order fills at clear price,
  in full if supply covered demand,
  pro-rata, rounded down to a lot, at the last level if it didn't
```

Every fill at a given clearing price pays the same batch VWAP, rounded up
for buys and down for sells, and clamped so no fill is ever worse for the
trader than the live oracle or spot. A maker's own depth in the ladder is
capped by what their capital can actually cover, not unlimited; only orders
from a strictly earlier slot are eligible at all, which is what makes
sandwiching a taker's own order impossible, there is no same-slot fill to
front-run.

If demand still outstrips every maker's available depth after the ladder is
exhausted, the remainder isn't left queued. It fills anyway, at a separately
computed, penalized exit price (spot or EMA, moved about 1% against the
trader), spread proportionally across the whole maker pool's capital. A
taker's order is always fully resolved in the batch it's eligible for, never
left half-filled waiting on liquidity that didn't show up.

## Getting paid

A `DONE` queued order still has to be settled, and that's its own
permissionless step, `claim`. It releases any unused locked margin back to
the trader on an open, or on a close, pays profit out of the pool first,
then the market's insurance fund if the pool alone falls short, and if even
that's not enough, leaves the remainder as an IOU the trader can claim later
once the pool's balance recovers. Every settled fill pays a 1 basis point
keeper fee to whoever called the `uncross` or `claim` that touched it, free
if a trader settles their own order.

A liquidated or partially liquidated position settles through
`settle_liquidation` instead: 4% of what was liquidated goes to whoever ran
the crank, 1% to the market's insurance fund, and the rest back to the
trader's free balance, with the market maker side absorbing the loss up to
the position's margin. A self-liquidation sends the keeper's cut to
insurance instead of to the trader's own transaction.

Running the crank is not a privileged role. Anyone can run it, and anyone
who does earns these fees for doing so.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.