Skip to main content

Matching Engine & Cross Matching

The matching engine is the core of Astromarkets: an order book built on red-black trees, extended with cross-matching semantics for prediction markets.

Every place_order runs in two phases.

Phase 1 — Direct Matching (same token, Bid ↔ Ask)​

BidYes ↔ AskYes, BidNo ↔ AskNo — identical to a traditional CLOB: price priority, then time priority (FIFO); the taker gets price improvement (fills at the maker's quote).

Phase 2 — Cross Matching (complementary tokens, implied mint/redeem)​

This is what separates Astromarkets from an ordinary order book. Exploiting the Yes + No = 1 equivalence, buyers of Yes and buyers of No become direct counterparties:

Cross directionBoth partiesProtocol action
BidYes ↔ BidNoboth buying, both paying USDCMint a complete set, deliver one side to each
AskYes ↔ AskNoboth selling, each holding one tokenRedeem a complete set

Cross Conditions​

With COMPLEMENT_PRICE_TICKS = 1000 (1.000 USDC) as the base:

  • Bid side: p_taker + q_maker ≥ 1000
  • Ask side: p_taker + q_maker ≤ 1000

Fill Pricing (symmetric with direct matching; taker gets improvement)​

taker's effective price = 1000 − maker's quote
maker fills at their own quote
any surplus goes to the protocol (counted as fees)

Example​

A taker's BidYes @ 800 ticks (willing to pay 0.80 for Yes) meets a resting BidNo @ 300 ticks (willing to pay 0.30 for No).

800 + 300 = 1100 ≥ 1000, so they cross. The protocol mints one complete set:

  • the taker pays 1000 − 300 = 700 ticks (0.70 — better than their 0.80 quote) and receives YES;
  • the maker pays 0.30 and receives NO;
  • together they pay 0.70 + 0.30 = 1.00 USDC, exactly covering the minted set; any spread surplus goes to the protocol.

After the fill the maker's trader state is updated (funds move between locked and free). Fees are computed uniformly over direct + cross volume and accrue to the book's unclaimed_quote_lot_fees.

Why This Is a Moat​

  1. Liquidity merging: traditionally the "buy Yes" and "buy No" books are two disconnected sides; Astromarkets merges them into one depth pool — the same resting size provides roughly 2× fillable depth, crucial for bootstrapping long-tail / new markets;
  2. Better execution: cross matching lets two buyers who could never trade satisfy each other, both potentially filling better than their quotes;
  3. Capital efficiency: makers don't need to pre-hold both token inventories; a resting order can be crossed directly.