Skip to main content

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