​
Order Flow

This document describes the lifecycle of orders in the CLOB system from a user’s perspective.

​
Order Placement

​
Limit Orders

Place an order at a specific price. The order rests in the book until filled or cancelled. 
placeOrder(
    PoolKey pool,
    uint256 price,
    uint256 quantity,
    Side side,
    address user
)
What happens:
  1. Funds are verified and locked
  2. Order is checked against existing orders for potential matches
  3. Any matched portion executes immediately
  4. Remaining quantity (if any) rests in the order book
  5. OrderPlaced event is emitted with the order ID

​
Market Orders

Execute immediately at the best available prices. 
placeMarketOrder(
    PoolKey pool,
    uint256 quantity,
    Side side,
    address user,
    uint256 minAmountOut
)
What happens:
  1. Funds are verified and locked
  2. Order executes against available liquidity at best prices
  3. Slippage protection ensures minAmountOut is satisfied
  4. OrderMatched events are emitted for each fill

​
Order Types

TypeDescription
LimitRests at specified price until filled or cancelled
MarketExecutes immediately at best available prices

​
Time In Force Options

The TimeInForce parameter controls how long an order remains active:
TypeBehavior
GTC (Good Till Cancel)Order remains open until filled or explicitly cancelled
IOC (Immediate or Cancel)Execute what’s possible immediately, cancel the rest
FOK (Fill or Kill)Execute entire quantity or cancel completely
PostOnlyOnly add liquidity; cancel if would take liquidity

​
Order Matching

Orders are matched following price-time priority:
  1. Price Priority: Best prices match first
    • Highest bid matches against lowest ask
  2. Time Priority: At the same price level, earlier orders fill first
Trades execute at the maker’s price (the resting order), providing price improvement for aggressive orders.

​
Order Cancellation

​
Single Order Cancellation

cancelOrder(PoolKey pool, uint256 orderId)
What happens:
  1. Ownership is verified
  2. Order is removed from the book
  3. Locked funds are returned to available balance
  4. OrderCancelled event is emitted

​
Batch Cancellation

cancelBatchOrders(PoolKey pool, uint256[] orderIds)
Cancels multiple orders in a single transaction for gas efficiency.

​
Self-Trade Prevention

The system prevents users from trading against their own orders using configurable STP modes:
ModeBehavior
NoneAllow self-trades
CancelTakerCancel incoming order if it would match own order
CancelMakerCancel resting order if incoming order would match
CancelBothCancel both orders

​
Batch Operations

​
Batch Order Placement

placeBatchOrders(BatchOrder[] orders, bool atomic)
ModeBehavior
atomic = trueAll orders succeed or all fail
atomic = falseEach order processed independently
Benefits:
  • Gas savings through amortized transaction costs
  • Atomic updates for market making strategies
  • Place bid/ask pairs in single transaction

​
Error Handling

ErrorCauseResolution
InsufficientBalanceNot enough funds for orderDeposit more funds
InvalidPricePrice is zero or exceeds limitsUse valid price
InvalidPriceIncrementPrice not on valid tickRound to valid tick
OrderTooSmallBelow minimum order sizeIncrease quantity
OrderTooLargeExceeds maximum order sizeReduce quantity
PostOnlyWouldTakePost-only order would cross spreadUse different price
FillOrKillNotFulfilledFOK order can’t fully fillUse IOC or adjust size
SlippageExceededExecution worse than limitIncrease slippage tolerance