Struct OrderBook 

pub struct OrderBook {
    pub token_id: String,
    pub token_id_hash: u64,
    pub sequence: u64,
    pub last_delta_sequence: u64,
    pub last_snapshot_timestamp_ms: u64,
    pub timestamp: DateTime<Utc>,
    /* private fields */
}

High-performance order book implementation

This is the core data structure that holds all the live buy/sell orders for a token. The efficiency of this code is critical as the order book is constantly being updated as orders are added and removed.

PERFORMANCE OPTIMIZATION: This struct now uses fixed-point integers internally instead of Decimal for maximum speed. The performance difference is dramatic:

Before (Decimal): ~100ns per operation + memory allocation After (fixed-point): ~5ns per operation, zero allocations

Fields

token_id: String

Token ID this book represents (like “123456” for a specific prediction market outcome)

token_id_hash: u64

Hash of token_id for fast lookups (avoids string comparisons in hot path)

sequence: u64

Legacy delta sequence number.

Kept as a compatibility alias for Self::last_delta_sequence. WebSocket snapshot timestamps are tracked separately in Self::last_snapshot_timestamp_ms.

last_delta_sequence: u64

Last accepted legacy/incremental delta sequence number.

Delta sequences are a different clock from WebSocket snapshot timestamps and must not be compared against millisecond timestamps.

last_snapshot_timestamp_ms: u64

Last accepted full-book snapshot timestamp in milliseconds.

Used for WebSocket book snapshots and serde BookUpdate snapshots.

timestamp: DateTime<Utc>

Last update timestamp - when we last got new data for this book

Implementations

impl OrderBook

pub fn new(token_id: String, max_depth: usize) -> Self

Create a new order book Just sets up empty bid/ask maps and basic metadata

pub fn set_tick_size(&mut self, tick_size: Decimal) -> Result<()>

Set the tick size for this book This tells us the minimum price increment allowed We store it in ticks for fast validation without conversion overhead

pub fn set_tick_size_ticks(&mut self, tick_size_ticks: Price)

Set the tick size directly in ticks (even faster) Use this when you already have the tick size in our internal format

pub fn best_bid(&self) -> Option<BookLevel>

Get the current best bid (highest price someone is willing to pay) Bids are stored highest price first.

PERFORMANCE: Now returns data in external format but internally uses fast lookups

pub fn best_ask(&self) -> Option<BookLevel>

Get the current best ask (lowest price someone is willing to sell at) Asks are stored lowest price first.

PERFORMANCE: Now returns data in external format but internally uses fast lookups

pub fn best_bid_fast(&self) -> Option<FastBookLevel>

Get the current best bid in fast internal format Use this for internal calculations to avoid conversion overhead

pub fn best_ask_fast(&self) -> Option<FastBookLevel>

Get the current best ask in fast internal format Use this for internal calculations to avoid conversion overhead

pub fn spread(&self) -> Option<Decimal>

Get the current spread (difference between best ask and best bid) This tells us how “tight” the market is - smaller spread = more liquid market

PERFORMANCE: Now uses fast internal calculations, only converts to Decimal at the end

pub fn mid_price(&self) -> Option<Decimal>

Get the current mid price (halfway between best bid and ask) This is often used as the “fair value” of the market

PERFORMANCE: Now uses fast internal calculations, only converts to Decimal at the end

pub fn spread_pct(&self) -> Option<Decimal>

Get the spread as a percentage (relative to the bid price) Useful for comparing spreads across different price levels

PERFORMANCE: Now uses fast internal calculations and returns basis points

pub fn spread_fast(&self) -> Option<Price>

Get the current spread in fast internal format (PERFORMANCE OPTIMIZED) Returns spread in ticks - use this for internal calculations

pub fn mid_price_fast(&self) -> Option<Price>

Get the current mid price in fast internal format (PERFORMANCE OPTIMIZED) Returns mid price in ticks - use this for internal calculations

pub fn bids(&self, depth: Option<usize>) -> Vec<BookLevel>

Get all bids up to a certain depth (top N price levels) Returns them in descending price order (best bids first)

PERFORMANCE: Converts from internal fixed-point to external Decimal format Only call this when you need to return data to external APIs

pub fn asks(&self, depth: Option<usize>) -> Vec<BookLevel>

Get all asks up to a certain depth (top N price levels) Returns them in ascending price order (best asks first)

PERFORMANCE: Converts from internal fixed-point to external Decimal format Only call this when you need to return data to external APIs

pub fn bids_fast(&self, depth: Option<usize>) -> Vec<FastBookLevel>

Get all bids in fast internal format Use this for internal calculations to avoid conversion overhead

pub fn asks_fast(&self, depth: Option<usize>) -> Vec<FastBookLevel>

Get all asks in fast internal format (PERFORMANCE OPTIMIZED) Use this for internal calculations to avoid conversion overhead

pub fn snapshot(&self) -> OrderBook

Get the full book snapshot Creates a copy of the current state that can be safely passed around without worrying about the original book changing

pub fn apply_delta(&mut self, delta: OrderDelta) -> Result<()>

Apply a delta update to the book (LEGACY VERSION - for external API compatibility) A “delta” is an incremental change - like “add 100 tokens at $0.65” or “remove all at $0.70”

This method converts the external Decimal delta to our internal fixed-point format and then calls the fast version. Use apply_delta_fast() directly when possible.

pub fn apply_delta_fast(&mut self, delta: FastOrderDelta) -> Result<()>

Apply a delta update to the book

This is the high-performance version that works directly with fixed-point data. It includes tick alignment validation and is much faster than the Decimal version.

Performance improvement: ~50x faster than the old Decimal version!

• No Decimal conversions in the hot path
• Integer comparisons instead of Decimal comparisons
• No memory allocations for price/size operations

pub fn apply_book_update(&mut self, update: &BookUpdate) -> Result<()>

Apply a WebSocket book update for this token.

The official Polymarket CLOB WebSocket book event is a full snapshot. Unlike apply_delta_fast, this method can apply many levels that share the same message timestamp.

Notes:

• This replaces the snapshot for both sides.
• Levels omitted from the message are removed.
• Insertions of new price levels may allocate or shift vector entries.

pub fn calculate_market_impact( &self, side: Side, size: Decimal, ) -> Option<MarketImpact>

Calculate the market impact for a given order size This is exactly why we don’t need deep levels - if your order would require hitting prices way off the current market (like $0.95 when best ask is $0.67), you’d never actually place that order. You’d either:

1. Break it into smaller pieces over time
2. Use a different trading strategy
3. Accept that there’s not enough liquidity right now

pub fn is_stale(&self, max_age: Duration) -> bool

Check if the book is stale (no recent updates) Useful for detecting when we’ve lost connection to live data

pub fn liquidity_at_price(&self, price: Decimal, side: Side) -> Decimal

Get the total liquidity at a given price level Tells you how much you can buy/sell at exactly this price

pub fn liquidity_in_range( &self, min_price: Decimal, max_price: Decimal, side: Side, ) -> Decimal

Get the total liquidity within a price range Useful for understanding how much depth exists in a certain price band

pub fn is_valid(&self) -> bool

Validate that prices are properly ordered A healthy book should have best bid < best ask (otherwise there’s an arbitrage opportunity)

impl OrderBook

pub fn analytics(&self) -> BookAnalytics

Calculate analytics for this book Gives you a quick health check of the market

Trait Implementations

impl Clone for OrderBook

fn clone(&self) -> OrderBook

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for OrderBook

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.