​
Order Flow

This document details the lifecycle of orders in the CLOB system, from placement through matching to settlement.

​
Order Placement

​
Limit Order Flow

​
Market Order Flow

​
Order Types

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

​
Market Orders

Execute immediately at the best available prices. 
placeMarketOrder(
    PoolKey pool,
    uint256 quantity,
    Side side,
    address user,
    uint256 minAmountOut
)

​
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

​
TimeInForce Sequence

​
Order Matching

​
Matching Sequence

​
Price-Time Priority

Orders are matched following strict price-time priority:
  1. Price Priority: Best prices match first
    • Highest bid vs lowest ask
  2. Time Priority: At the same price level, earlier orders fill first (FIFO)

​
Order Cancellation

​
Single Order Cancellation

​
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

struct BatchOrder {
    PoolKey pool;
    uint256 price;
    uint256 quantity;
    Side side;
    TimeInForce timeInForce;
}

placeBatchOrders(
    BatchOrder[] orders,
    bool atomic
)
ModeBehavior
atomic = trueAll orders succeed or all fail
atomic = falseEach order processed independently

​
Benefits of Batching

  • Gas savings: Amortize fixed transaction costs
  • Atomic updates: Update multiple price levels together
  • Market making: 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 crossUse different price
FillOrKillNotFulfilledFOK order can’t fully fillUse IOC or adjust size
SlippageExceededExecution worse than limitIncrease slippage tolerance