book

Documentation

Overview

Package book provides the core order book implementation using efficient B-Tree data structures.

The order book maintains buy and sell orders with O(log n) price level operations and O(1) order lookups. It uses separate trees for bids (descending) and asks (ascending) to optimize for best price retrieval.

Key features:

• Zero-allocation best price lookups (23ns)
• FIFO ordering within price levels
• Efficient order addition/removal
• Iceberg order support with replenishment
• Fast order lookup via hash index

Example usage:

book := book.NewOrderBook("BTC-USDT")
order := &order.Order{
    OrderID:  "order-1",
    Side:     order.Buy,
    Price:    decimal.NewFromInt(50000),
    Quantity: decimal.NewFromFloat(0.1),
}
book.Add(order)
bestBid := book.BestBid()

Index

• type OrderBook
  • func NewOrderBook(symbol string) *OrderBook
  • func (b *OrderBook) Add(o *order.Order)
  • func (b *OrderBook) AskCount() int
  • func (b *OrderBook) BestAsk() *PriceLevel
  • func (b *OrderBook) BestBid() *PriceLevel
  • func (b *OrderBook) BidCount() int
  • func (b *OrderBook) Clear()
  • func (b *OrderBook) FindOrder(orderID string) *order.Order
  • func (b *OrderBook) GetDepth(levels int) (bids, asks []*PriceLevel)
  • func (b *OrderBook) GetLevel(side order.Side, price decimal.Decimal) *PriceLevel
  • func (b *OrderBook) RemoveFilledOrders(side order.Side)
  • func (b *OrderBook) RemoveLevel(side order.Side, price decimal.Decimal)
  • func (b *OrderBook) RemoveOrder(o *order.Order) bool
• type PriceItem
  • func (p *PriceItem) Less(than btree.Item) bool
• type PriceLevel
  • func NewPriceLevel(price decimal.Decimal) *PriceLevel
  • func (p *PriceLevel) Add(o *order.Order)
  • func (p *PriceLevel) Head() *order.Order
  • func (p *PriceLevel) IsEmpty() bool
  • func (p *PriceLevel) MoveToTail(o *order.Order)
  • func (p *PriceLevel) ProcessReplenishments() []*order.Order
  • func (p *PriceLevel) RemoveFilledOrders()
  • func (p *PriceLevel) RemoveOrder(target *order.Order) bool
  • func (p *PriceLevel) RemoveVolume(qty decimal.Decimal)
• type PriceTree
  • func NewPriceTree(descending bool) *PriceTree
  • func (p *PriceTree) Add(level *PriceLevel)
  • func (p *PriceTree) Ascend(iterator func(*PriceLevel) bool)
  • func (p *PriceTree) AscendGreaterOrEqual(minPrice decimal.Decimal, iterator func(*PriceLevel) bool)
  • func (p *PriceTree) Best() *PriceLevel
  • func (p *PriceTree) Clear()
  • func (p *PriceTree) DescendLessOrEqual(maxPrice decimal.Decimal, iterator func(*PriceLevel) bool)
  • func (p *PriceTree) Get(price decimal.Decimal) *PriceLevel
  • func (p *PriceTree) Len() int
  • func (p *PriceTree) Remove(price decimal.Decimal)

Types

type OrderBook

type OrderBook struct {
	Symbol     string
	BidTree    *PriceTree              // Descending order (highest price first)
	AskTree    *PriceTree              // Ascending order (lowest price first)
	MinLotSize decimal.Decimal         // Minimum trade unit for this market
	OrderIndex map[string]*order.Order // Fast order lookup by OrderID
}

OrderBook maintains buy and sell orders using efficient B-Tree structure

func NewOrderBook

func NewOrderBook(symbol string) *OrderBook

NewOrderBook creates a new order book for a symbol

func (*OrderBook) Add

func (b *OrderBook) Add(o *order.Order)

Add adds an order to the appropriate side of the book

func (*OrderBook) AskCount

func (b *OrderBook) AskCount() int

AskCount returns the number of ask price levels

func (*OrderBook) BestAsk

func (b *OrderBook) BestAsk() *PriceLevel

BestAsk returns the lowest ask price level (O(1) with B-Tree)

func (*OrderBook) BestBid

func (b *OrderBook) BestBid() *PriceLevel

BestBid returns the highest bid price level (O(1) with B-Tree)

func (*OrderBook) BidCount

func (b *OrderBook) BidCount() int

BidCount returns the number of bid price levels

func (*OrderBook) Clear

func (b *OrderBook) Clear()

Clear removes all orders from the book

func (*OrderBook) FindOrder

func (b *OrderBook) FindOrder(orderID string) *order.Order

FindOrder finds an order by OrderID

func (*OrderBook) GetDepth

func (b *OrderBook) GetDepth(levels int) (bids, asks []*PriceLevel)

GetDepth returns market depth up to specified levels

func (*OrderBook) GetLevel

func (b *OrderBook) GetLevel(side order.Side, price decimal.Decimal) *PriceLevel

GetLevel retrieves a specific price level

func (*OrderBook) RemoveFilledOrders

func (b *OrderBook) RemoveFilledOrders(side order.Side)

RemoveFilledOrders removes filled orders and empty price levels

func (*OrderBook) RemoveLevel

func (b *OrderBook) RemoveLevel(side order.Side, price decimal.Decimal)

RemoveLevel removes a price level completely

func (*OrderBook) RemoveOrder

func (b *OrderBook) RemoveOrder(o *order.Order) bool

RemoveOrder removes a specific order from the book Returns true if the order was found and removed

type PriceItem

type PriceItem struct {
	Price decimal.Decimal
	Level *PriceLevel
}

PriceItem wraps a price level for storage in B-Tree

func (*PriceItem) Less

func (p *PriceItem) Less(than btree.Item) bool

Less implements btree.Item interface for ascending order (asks) Returns true if this item should sort before the other item

type PriceLevel

type PriceLevel struct {
	Price      decimal.Decimal
	Orders     []*order.Order
	Volume     decimal.Decimal
	OrderCount int // Total count of orders at this price level
}

func NewPriceLevel

func NewPriceLevel(price decimal.Decimal) *PriceLevel

func (*PriceLevel) Add

func (p *PriceLevel) Add(o *order.Order)

func (*PriceLevel) Head

func (p *PriceLevel) Head() *order.Order

Head returns the first order (highest priority)

func (*PriceLevel) IsEmpty

func (p *PriceLevel) IsEmpty() bool

IsEmpty returns true if there are no orders at this price level

func (*PriceLevel) MoveToTail

func (p *PriceLevel) MoveToTail(o *order.Order)

MoveToTail moves an order to the end of the queue (used for iceberg replenishment)

func (*PriceLevel) ProcessReplenishments

func (p *PriceLevel) ProcessReplenishments() []*order.Order

ProcessReplenishments checks all orders for replenishment and moves them to tail Returns list of orders that were replenished

func (*PriceLevel) RemoveFilledOrders

func (p *PriceLevel) RemoveFilledOrders()

RemoveFilledOrders removes all fully filled orders from the level

func (*PriceLevel) RemoveOrder

func (p *PriceLevel) RemoveOrder(target *order.Order) bool

RemoveOrder removes a specific order from the level

func (*PriceLevel) RemoveVolume

func (p *PriceLevel) RemoveVolume(qty decimal.Decimal)

type PriceTree

type PriceTree struct {
	// contains filtered or unexported fields
}

PriceTree provides an ordered index of price levels using B-Tree Supports both ascending (asks) and descending (bids) order

func NewPriceTree

func NewPriceTree(descending bool) *PriceTree

NewPriceTree creates a new price tree descending=true for bids (highest price first) descending=false for asks (lowest price first)

func (*PriceTree) Add

func (p *PriceTree) Add(level *PriceLevel)

Add inserts or updates a price level in the tree

func (*PriceTree) Ascend

func (p *PriceTree) Ascend(iterator func(*PriceLevel) bool)

Ascend iterates over all price levels in order For bids: highest to lowest price For asks: lowest to highest price

func (*PriceTree) AscendGreaterOrEqual

func (p *PriceTree) AscendGreaterOrEqual(minPrice decimal.Decimal, iterator func(*PriceLevel) bool)

AscendGreaterOrEqual iterates over price levels >= minPrice in ascending order

func (*PriceTree) Best

func (p *PriceTree) Best() *PriceLevel

Best returns the best price level (min for asks, max for bids)

func (*PriceTree) Clear

func (p *PriceTree) Clear()

Clear removes all price levels

func (*PriceTree) DescendLessOrEqual

func (p *PriceTree) DescendLessOrEqual(maxPrice decimal.Decimal, iterator func(*PriceLevel) bool)

DescendLessOrEqual iterates over price levels <= maxPrice in descending order

func (*PriceTree) Get

func (p *PriceTree) Get(price decimal.Decimal) *PriceLevel

Get retrieves a price level by exact price

func (*PriceTree) Len

func (p *PriceTree) Len() int

Len returns the number of price levels

func (*PriceTree) Remove

func (p *PriceTree) Remove(price decimal.Decimal)

Remove deletes a price level from the tree