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

# How the Matching Engine Works

> Specifies the execution architecture, order lifecycle, and deterministic matching logic underpinning the protocol.

### 3.1 Design Objectives

The Parallelshots matching engine is designed to satisfy four primary constraints: low-latency execution, deterministic ordering, strict risk pre-validation, and seamless on-chain settlement. Unlike AMM-based systems, where execution price is a function of pool state, Parallelshots enforces explicit price discovery through discrete orders, enabling tighter spreads, reduced slippage, and sophisticated trading strategies.

The engine is logically off-chain for performance reasons, but **economically and cryptographically subordinate** to the on-chain protocol. All matches are considered provisional until finalized through on-chain settlement logic. This design ensures that execution speed does not come at the cost of trust assumptions around custody, balances, or margin enforcement.

***

### 3.2 Order Representation

Each order is represented as a structured object with immutable and mutable fields:

```
Order {
  order_id: uint64
  trader: address
  market_id: uint32
  side: enum { BUY, SELL }
  price: uint256
  quantity: uint256
  leverage: uint8
  timestamp: uint64
  status: enum { OPEN, PARTIALLY_FILLED, FILLED, CANCELLED }
}
```

Orders are indexed by `(market_id, price, timestamp)` to enforce strict **price-time priority**. No discretionary reordering is permitted.

***

### 3.3 Pre-Trade Risk Validation

Before an order is admitted into the order book, the engine performs deterministic risk checks against the on-chain risk model:

```
require(
  available_margin(trader) ≥ initial_margin(order),
  "INSUFFICIENT_MARGIN"
)

require(
  leverage ≤ max_leverage(market_id),
  "LEVERAGE_EXCEEDED"
)
```

These checks prevent invalid orders from entering the matching pipeline and ensure that every executable order is solvent at submission time.

***

### 3.4 Matching Algorithm

The engine operates a continuous matching loop per market:

```
while best_bid.price ≥ best_ask.price:
    trade_price = determine_execution_price(best_bid, best_ask)
    trade_qty = min(best_bid.qty, best_ask.qty)

    emit Match(best_bid.order_id, best_ask.order_id, trade_price, trade_qty)

    update_order_states()
```

Execution price determination follows price-time priority, favoring the resting order’s price.

***

### 3.5 Partial Fills and State Transitions

Orders may be partially filled across multiple matches. Each fill generates a discrete execution event that is later settled on-chain. State transitions are monotonic and irreversible:

```
OPEN → PARTIALLY_FILLED → FILLED
OPEN → CANCELLED
```

At no point can an order revert to a prior state.

***

### 3.6 On-Chain Settlement Hook

Matched trades are batch-submitted to the settlement contract across chains:

```
function settleTrade(
  address traderA,
  address traderB,
  uint256 price,
  uint256 quantity
) external onlyEngine;
```

Settlement updates:

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

The matching engine **cannot** mutate balances directly. All economic finality occurs on-chain.

***

### 3.7 Failure and Recovery Model

If the engine halts or disconnects:

* Open orders remain valid
* On-chain state is unchanged
* No funds are at risk

The system is designed to tolerate engine restarts without requiring reconciliation or rollback, as the chain remains the source of truth.

***