> ## Documentation Index
> Fetch the complete documentation index at: https://learn.parallelshots.us/llms.txt
> Use this file to discover all available pages before exploring further.

# Central Limit Order Book (CLOB)

> Specifies the on-chain–settled, off-chain–matched order book model used for deterministic price discovery and leveraged execution.

### 6.1 Rationale for a CLOB Architecture

Parallelshots adopts a Central Limit Order Book rather than an automated market maker in order to achieve explicit price discovery, reduced slippage under size, and compatibility with professional trading strategies. In memecoin markets, where liquidity is often discontinuous and volatility is extreme, AMM-based curves introduce nonlinear execution costs and reflexive price distortions. A CLOB provides discrete pricing, transparent depth, and strict execution ordering, all of which are critical for leveraged trading systems.

The CLOB is implemented as a logical construct maintained by the matching engine, while its economic effects are enforced by on-chain settlement. The blockchain remains the system of record for balances, margin, and positions, while the order book itself is treated as ephemeral state that can be reconstructed from signed orders and execution events.

***

### 6.2 Order Book Structure

For each market `m`, the order book is defined as two priority queues:

```
Bids[m] := max-heap ordered by (price DESC, time ASC)
Asks[m] := min-heap ordered by (price ASC, time ASC)
```

Each price level may contain multiple orders sorted by submission timestamp.

An order is defined as:

```
Order {
  order_id: uint64
  trader: address
  market_id: uint32
  side: {BUY, SELL}
  price: uint256
  quantity: uint256
  remaining_quantity: uint256
  leverage: uint8
  timestamp: uint64
}
```

Orders are immutable after submission except for `remaining_quantity`.

***

### 6.3 Price-Time Priority Enforcement

Execution priority is strictly defined as:

```
Primary key: better price
Secondary key: earlier timestamp
```

Formally, for two orders `o1` and `o2` on the same side:

```
o1 precedes o2 if:
  (o1.price > o2.price) OR
  (o1.price == o2.price AND o1.timestamp < o2.timestamp)
```

No discretionary reordering or batching is permitted.

***

### 6.4 Matching Conditions

A match is executable when:

```
best_bid.price ≥ best_ask.price
```

Execution proceeds iteratively:

```
while best_bid.price ≥ best_ask.price:
    exec_price = resting_order.price
    exec_qty   = min(bid.remaining_qty, ask.remaining_qty)

    emit Trade(market_id, bid_id, ask_id, exec_price, exec_qty)

    decrement remaining quantities
    update order states
```

The resting order defines the execution price to prevent price manipulation by aggressive orders.

***

### 6.5 Market Orders

Market orders are represented internally as limit orders with extreme price bounds:

```
BUY market order  → price = +∞
SELL market order → price = 0
```

They consume available liquidity until fully filled or until margin constraints are violated.

***

### 6.6 Risk-Gated Order Admission

Before insertion into the order book, each order must satisfy:

```
initial_margin_required :=
  (price * quantity) / leverage

require(
  free_margin(trader) ≥ initial_margin_required,
  "MARGIN_INSUFFICIENT"
)
```

Orders failing pre-trade checks are rejected and never enter the book.

***

### 6.7 On-Chain Settlement Interface

Each executed trade is settled via a canonical interface:

```
function settleExecution(
  uint32 marketId,
  address maker,
  address taker,
  uint256 price,
  uint256 quantity
) external onlyEngine;
```

Settlement updates:

* Position size
* Average entry price
* Locked margin
* Unrealized PnL

The CLOB itself cannot mutate balances.

***

### 6.8 Failure and Recovery Guarantees

If the matching engine halts:

* No orders are lost
* No balances are affected
* On-chain state remains authoritative

The order book can be reconstructed deterministically from signed orders and executed trades.

***