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

Time In Force Options

The TimeInForce parameter controls how long an order remains active:

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:

Batch Operations

Batch Order Placement

placeBatchOrders(BatchOrder[] orders, bool atomic)

Benefits:

• Gas savings through amortized transaction costs
• Atomic updates for market making strategies
• Place bid/ask pairs in single transaction

Error Handling