# Architecture Overview ## Data Flow Architecture ``` ┌─────────────────┐ │ Users │ └────────┬────────┘ │ ┌───────────────────┼───────────────────┐ │ │ │ ▼ ▼ ▼ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ OrderBook │ │ OrderBook │ │ OrderBook │ │ WETH/USDC │ │ BTC/USDC │ │ USDT/USDC │ │ │ │ │ │ │ │• Order Create │ │• Order Create │ │• Order Create │ │• Matching │ │• Matching │ │• Matching │ │• Settlement │ │• Settlement │ │• Settlement │ │• Collateral │ │• Collateral │ │• Collateral │ └───────┬───────┘ └───────┬───────┘ └───────┬───────┘ │ │ │ └───────────────────┼───────────────────┘ │ ▼ ┌─────────────────┐ │ Manager.sol │ │ │ │ • Fee Calc │ │ • Role Check │ │ • Registration │ │ • Pause Control │ └─────────────────┘ ``` ## System Components ### Manager Contract The `Manager.sol` contract serves as the central coordination layer for the entire Worldbook ecosystem: **Core Responsibilities:** * **Access Control**: Implements role-based permissions (DEFAULT\_ADMIN\_ROLE, ADMIN\_ROLE, PAUSER\_ROLE) * **OrderBook Registry**: Validates and registers new orderbook contracts * **Fee Management**: Handles sophisticated 4-tier fee structure with rebates and discounts * **Emergency Controls**: Provides pause/unpause functionality across all orderbooks * **Quote Token Whitelist**: Manages which tokens can be used as quote assets **Key Features:** * Bytecode verification for security * Multi-tier fee system with user-specific discounts * Emergency pause controls for risk management * Permissionless or admin-controlled registration ### OrderBook Contract The `OrderBook.sol` contract implements the core trading engine: **Core Responsibilities:** * **Order Management**: Creates, stores, and manages all order lifecycles * **Order Matching**: Efficient price-time priority matching algorithm * **Skip List Implementation**: Optimized price level traversal and management * **Collateral Management**: Handles token deposits and withdrawals * **Trade Execution**: Processes fills and settlements **Key Features:** * Gas-optimized skip list data structures * Advanced order types (Limit, Market, Post-Only, IOC/FOK) * FIFO matching within price levels * Sophisticated gas limit controls * Self-trade prevention mechanisms ## ## 📈 Skip List Implementation ### The Secret to Our Gas Efficiency Worldbook's groundbreaking use of probabilistic skip lists enables logarithmic complexity for all order book operations: ### 🎯 Performance Characteristics | Operation | Complexity | vs Linear Search | | --------- | ---------- | ---------------- | | Search | O(log n) | 90% reduction | | Insert | O(log n) | 85% reduction | | Delete | O(log n) | 88% reduction | | Traverse | O(n) | Same | ### 🏗️ Visual Structure ``` BUY SIDE (Descending) SELL SIDE (Ascending) Level 3: ♾️─────────────────────────────────────→ 0️⃣ │ │ Level 2: ♾️──────→ $2050 ───────────────────────→ 0️⃣ │ │ │ Level 1: ♾️──→ $2050 ──→ $2045 ─────────────────→ 0️⃣ │ │ │ │ Level 0: ♾️─→ $2050 ─→ $2045 ─→ $2040 ─→ $2035 ─→ 0️⃣ ♾️ = BUY_SENTINEL (MAX_UINT256) 0️⃣ = SELL_SENTINEL (0) ``` ## Order Matching Algorithm The matching engine follows strict price-time priority: 1. **Price Priority**: Higher buy prices and lower sell prices get priority 2. **Time Priority**: Earlier orders at the same price level get filled first 3. **FIFO Execution**: Uses doubly-linked lists for efficient queue management **Matching Process:** ``` 1. New Order → Validation 2. Validation → Collateral Lock 3. Collateral Lock → Order Storage 4. Order Storage → Matching Engine 5. Matching Engine → Fill Orders 6. Fill Orders → Settlement 7. Settlement → Event Emission ``` ## Fee System Architecture Worldbook implements a sophisticated 4-tier fee structure: 1. **Layer 1 (Base)**: Default maker/taker fees set by protocol 2. **Layer 2 (OrderBook)**: OrderBook-specific fee overrides 3. **Layer 3 (User %)**: User-specific percentage discounts 4. **Layer 4 (User Abs)**: User-specific absolute discounts **Fee Calculation Logic:** ```solidity // Maker Fee Calculation (supports rebates) function _calculateMakerFeeRate(address orderbook, address user) internal view returns (int256) { // Step 1: Get base rate (orderbook override OR default) int256 baseRate = orderbookMakerFeeOverrides[orderbook] != 0 ? orderbookMakerFeeOverrides[orderbook] : makerFee; // Step 2: Apply percentage discount ONLY if base rate is positive int256 afterPercentageDiscount = baseRate; if (baseRate > 0) { uint256 discountFactor = userMakerFeeDiscountFactor[user]; if (discountFactor > 0 && discountFactor < 10000000) { // Allow up to 1000% amplification afterPercentageDiscount = int256(uint256(baseRate) * discountFactor / FEE_DENOM); } } // Step 3: Apply absolute discount (always applied, can turn positive fees negative) uint256 absoluteDiscount = userMakerFeeDiscountAbs[user]; return afterPercentageDiscount - int256(absoluteDiscount); } // Taker Fee Calculation (always non-negative) function _calculateTakerFeeRate(address orderbook, address user) internal view returns (uint256) { // Step 1: Get base rate (orderbook override OR default) uint256 baseRate = orderbookTakerFeeOverrides[orderbook] != 0 ? orderbookTakerFeeOverrides[orderbook] : takerFee; // Step 2: Apply percentage discount uint256 afterPercentageDiscount = baseRate; uint256 discountFactor = userTakerFeeDiscountFactor[user]; if (discountFactor > 0 && discountFactor < 10000000) { // Allow up to 1000% amplification afterPercentageDiscount = baseRate * discountFactor / FEE_DENOM; } // Step 3: Apply absolute discount (ensure result doesn't go below 0) uint256 absoluteDiscount = userTakerFeeDiscountAbs[user]; if (absoluteDiscount >= afterPercentageDiscount) { return 0; // Minimum taker fee is 0 } return afterPercentageDiscount - absoluteDiscount; } ``` ## Security Architecture ### Access Control Hierarchy ``` DEFAULT_ADMIN_ROLE (Role Management) │ ▼ ADMIN_ROLE (Operational Control) │ ▼ PAUSER_ROLE (Emergency Response) ``` ### Security Features * **Bytecode Verification**: Ensures only legitimate contracts are registered * **Reentrancy Protection**: Prevents reentrancy attacks * **Pausable Operations**: Emergency stop functionality * **Role-Based Access**: Granular permission system * **Input Validation**: Comprehensive parameter checking ## Gas Optimization Worldbook is designed for gas efficiency: **Optimization Techniques:** * Skip lists for logarithmic complexity * Batch operations where possible * Efficient storage patterns * Gas limit controls to prevent out-of-gas errors * Minimal external calls **Gas Threshold Management:** * Configurable gas thresholds for matching loops * Order behavior controls (Cancel vs PlaceAtLast) * Protection against gas limit attacks ## Scalability Features ### Modular Design * Independent orderbook contracts for each trading pair * Horizontal scaling through multiple orderbook instances * Shared infrastructure through Manager contract ### Performance Optimizations * Cached best bid/ask prices for O(1) access * Efficient price level cleanup * Optimized data structures for high-frequency operations --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://world-book.gitbook.io/worldbook/technical-documentation/architecture-overview.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.