CLOB Architecture Overview
The MuchFi Central Limit Order Book (CLOB) is a fully on-chain order book implementation designed for efficient, transparent, and secure spot trading. The architecture emphasizes modularity, upgradeability, and gas efficiency.System Architecture
Core Components
CLOBRouter
The primary entry point for all trading operations. Handles order placement, cancellation, and batch operations while managing deposits and withdrawals in a single transaction. Key Responsibilities:- Order placement with optional deposits
- Order cancellation
- Batch order operations
- Quote generation
PoolManager
Manages the lifecycle of trading pools (order books). Each pool represents a trading pair with its own OrderBook contract instance. Key Responsibilities:- Pool creation and configuration
- Trading rules management
- Pool state management
- OrderBook beacon proxy deployment
OrderBook
The core matching engine for each trading pair. Implements price-time priority matching with support for multiple order types. Key Responsibilities:- Order storage and management
- Price level organization (Red-Black trees)
- Order matching execution
- Trade settlement coordination
BalanceManager
Handles all fund custody, locking, and transfers within the CLOB system. Key Responsibilities:- User balance accounting
- Fund locking for open orders
- Trade settlement transfers
- Fee collection and distribution
Design Principles
Modularity
Each component has a single, well-defined responsibility. This separation allows for:- Independent upgrades of individual components
- Easier testing and auditing
- Flexible integration with external systems
Upgradeability
The system uses the Beacon Proxy Pattern for OrderBook contracts:- All OrderBooks share a single implementation
- Upgrades affect all pools simultaneously
- Storage layout follows ERC-7201 namespaced storage
Security
Multiple layers of security are implemented:- Authorization checks at each contract boundary
- Fund isolation per user and per pool
- Reentrancy protection on all state-changing operations
- Hooks system for custom validation logic
Gas Efficiency
Optimizations include:- Efficient data structures (Red-Black trees for price levels)
- Batch operations to amortize fixed costs
- Iteration limits to cap gas consumption
- Minimal storage operations
Component Interactions
| Source | Target | Interaction |
|---|---|---|
| Router | PoolManager | Pool queries, trading rules |
| Router | OrderBook | Order placement/cancellation |
| Router | BalanceManager | Deposits, withdrawals |
| PoolManager | OrderBook | Pool initialization |
| OrderBook | BalanceManager | Fund locks, transfers |
| OrderBook | HooksRegistry | Pre/post trade hooks |
Extension Points
Hooks System
The HooksRegistry allows custom logic to be executed at key points:- Before order placement
- After order matching
- On order cancellation
Market Making Vaults
MarketMakingVault contracts can provide automated liquidity:- Deposit funds into vault
- Vault places orders on behalf of depositors
- Profits distributed proportionally