docs(orderbook): update Clearing section for the four-case clearing price

[claude]

Requested by Shresth Agrawal · Slack thread

Before

The Clearing section of doc/protocol/orderbook.md described the old "average mechanism": the clearing price was simply the midpoint of the marginal matched buy and sell, p = (bk + sk) / 2, with a short note that a marginal market order defers to the other side's limit price and that the previous batch's clearing carries over when no limit orders matched.

After

The section now describes the merged four-case k-double-auction rule and its safety clamp:

• Only limit orders set the price. The clearing range is bounded by the marginal matched limit buy/sell and the best unmatched limit buy/sell still on the book: [max(ps, b'), min(pb, s')].
• Both bounds present → midpoint; one bound → that bound; no limit bound at all → fall back to the previous batch's clearing price (perp markets additionally fall back to the mark price; a spot market with no prior clearing emits no fills and the orders rest).
• The final price is clamped to the matched orders' own prices (market orders included), so no order ever fills worse than its own price.
• Marginal fills at a partially filled price level are allocated deterministically by order ID, so all nodes agree on the allocation.

How

One file touched: doc/protocol/orderbook.md (Clearing section). The text reflects these merged matching-engine changes in podnetwork/pod:

• podnetwork/pod#1083 — feat(clob): four-case k-double-auction clearing price
• podnetwork/pod#1132 — fix(clob): clamp batch clearing price to matched order bounds
• podnetwork/pod#1086 — fix(trading): make spot same-price fill allocation deterministic

The in-flight per-market BatchInput refactor is intentionally not documented here — it is unmerged and handled elsewhere.

🤖 Generated with Claude Code

https://claude.ai/code/session_01A74BZVmHFAksnZWVaGBcgi

---

Generated by Claude Code