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

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:

Price Priority: Higher buy prices and lower sell prices get priority
Time Priority: Earlier orders at the same price level get filled first
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:

Layer 1 (Base): Default maker/taker fees set by protocol
Layer 2 (OrderBook): OrderBook-specific fee overrides
Layer 3 (User %): User-specific percentage discounts
Layer 4 (User Abs): User-specific absolute discounts

Fee Calculation Logic:

// 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

PreviousContract Deployments NextManager Contract

Last updated 3 days ago