Match Limits

Overview

The OrderBook contract implements sophisticated order execution controls including match limits to manage gas consumption and various execution types to meet different trading strategies.

Match Limits

OrderBook now supports limiting the number of matches per transaction to manage gas consumption and provide more control over order execution:

function buyLimit(
    uint256 baseAmount,
    uint256 price,
    bool postOnly,
    ExecutionType executionType,
    MatchLimitBehavior behavior,
    uint256 maxMatches // Maximum number of maker orders to match against
) external

Why Match Limits?

• Gas Management: Prevents transactions from failing due to gas limits when matching against many small orders

• Predictable Costs: Traders can estimate maximum gas costs for their transactions

• MEV Protection: Limits the complexity of sandwich attacks

• Fair Execution: Ensures large orders don't monopolize block space

Match Limit Behaviors

When the match limit is reached, the order behaves according to the specified MatchLimitBehavior:

Cancel

• Cancels the remainder and refunds collateral

• Emits OrderCancelled

PlaceAtLast

• Places the remaining unfilled portion at the last checked price level

• Useful for completing partial fills without moving to worse prices

• The order joins the queue at that specific price level

Match Counting

Each successful match against a maker order counts as one match:

• A match that fully fills a maker order = 1 match

• A match that partially fills a maker order = 1 match

• Skipped orders (due to STP or other reasons) don't count

Execution Types

OrderBook supports three execution types that determine how unfilled portions of orders are handled:

Standard Execution

ExecutionType.Standard

• Order remains on the book if not fully filled

• Becomes a maker order at the specified limit price

• Most common type for limit orders

Immediate-Or-Cancel (IOC)

ExecutionType.IOC

• Executes immediately against available liquidity

• Any unfilled portion is automatically cancelled

• Never becomes a maker order

• Useful for avoiding maker fees or ensuring immediate execution

Fill-Or-Kill (FOK)

ExecutionType.FOK

• Must be completely filled or the entire transaction reverts

• No partial fills allowed

• Guarantees complete execution at specified price or better

• Common for large trades that need full execution

Usage Examples

Example 1: Large Buy Order with Gas Limit

// Buy 1000 tokens, match with max 10 orders, place remainder at best bid
buyLimit(
    1000e18,           // baseAmount
    150e18,            // price (max 150 per token)
    false,             // not postOnly
    ExecutionType.Standard,
    MatchLimitBehavior.PlaceAtBest,
    10                 // maxMatches
);

Example 2: IOC Order with Match Limit

// Sell tokens with immediate execution only, max 5 matches
sellLimit(
    500e18,            // baseAmount
    140e18,            // price (min 140 per token)
    false,             // not postOnly
    ExecutionType.IOC,
    MatchLimitBehavior.RevertOnLimit,
    5                  // maxMatches
);

Example 3: FOK Order for Exact Fill

// Buy exactly 100 tokens or revert
buyLimit(
    100e18,            // baseAmount
    155e18,            // price
    false,             // not postOnly
    ExecutionType.FOK,
    MatchLimitBehavior.RevertOnLimit,
    20                 // maxMatches (high limit for FOK)
);

Self-Trade Prevention Integration

Match limits work seamlessly with STP modes:

• EXPIRE_MAKER: Expired orders count toward match limit

• SKIP: Skipped orders do NOT count toward match limit

• NONE: All matches count normally

Gas Optimization

Recommended maxMatches values:

• Small orders: 5-10 matches

• Medium orders: 10-20 matches

• Large orders: 20-50 matches

• FOK orders: Higher limits (50+) to ensure completion

Events

The OrderBook emits events related to match limits:

event MatchLimitReached(
    uint64 indexed orderId,
    uint256 matchesUsed
);

This event is emitted when an order reaches its match limit, helping track partial executions.

Best Practices

1. Set Reasonable Limits: Balance between execution completeness and gas costs

2. Use PlaceAtBest: For orders that should become makers after partial fills

3. Use RevertOnLimit with FOK: For guaranteed full execution within limits

4. Monitor Events: Track MatchLimitReached events for partial fills

5. Consider Market Depth: Set limits based on typical order book depth

Technical Implementation

The match limit system is implemented in the core matching engine:

1. Match Counter: Tracks matches during order execution

2. Early Termination: Stops matching when limit is reached

3. Behavior Handling: Applies specified behavior for remaining amount

4. State Updates: Properly updates order state and book structure

5. Event Emission: Notifies about limit-related outcomes