Contract Architecture

The CLOB system is composed of multiple contracts with clearly defined responsibilities and interactions.

Contract Hierarchy


Contract Responsibilities

ContractLayerResponsibility
CLOBRouterEntryUser-facing API for orders, deposits, withdrawals
CLOBSwapRouterEntryOptimized swap execution across pools
PoolManagerManagementPool lifecycle, trading rules, OrderBook deployment
OrderBookCoreOrder matching, price trees, trade execution
BalanceManagerCoreFund custody, locking, fee collection
HooksRegistryExtensionCustom hook registration and execution
MarketMakingVaultExtensionAutomated market making strategies
VaultGaugeExtensionIncentive distribution for LPs

Beacon Proxy Pattern

OrderBook contracts are deployed as Beacon Proxies, allowing efficient upgrades across all trading pairs. Benefits:
  • Single upgrade transaction affects all pools
  • Lower deployment cost per pool (proxy is minimal)
  • Consistent behavior across all trading pairs

Authorization Model

The system implements a strict authorization hierarchy:

Caller Authorization

ContractAuthorized Callers
OrderBookCLOBRouter, PoolManager
BalanceManagerCLOBRouter, OrderBook
HooksRegistryOrderBook

Role-Based Access

RolePermissions
OwnerUpgrade contracts, configure fees, pause trading
OperatorCreate pools, modify trading rules
RouterPlace/cancel orders, manage balances
OrderBookLock/unlock funds, execute transfers

Storage Layout (ERC-7201)

The contracts use namespaced storage following ERC-7201 for safe upgrades.
// Storage namespace calculation
bytes32 constant STORAGE_SLOT = keccak256(
    abi.encode(
        uint256(keccak256("muchfi.clob.orderbook.storage")) - 1
    )
) & ~bytes32(uint256(0xff));

OrderBook Storage

struct OrderBookStorage {
    // Pool configuration
    PoolKey poolKey;
    TradingRules tradingRules;

    // Order data
    mapping(uint256 => Order) orders;
    uint256 nextOrderId;

    // Price trees
    RedBlackTree buyTree;
    RedBlackTree sellTree;

    // Order queues at each price level
    mapping(uint256 => OrderQueue) buyQueues;
    mapping(uint256 => OrderQueue) sellQueues;
}

BalanceManager Storage

struct BalanceManagerStorage {
    // User balances: user => currency => amount
    mapping(address => mapping(address => uint256)) balances;

    // Locked balances: user => operator => currency => amount
    mapping(address => mapping(address => mapping(address => uint256))) lockedBalances;

    // Fee configuration
    uint256 feeMaker;
    uint256 feeTaker;
    address feeReceiver;
}

Contract Addresses

ContractAddress
CLOBRouter0x29BF83fF2bb9E0c5C273b0B118C465D6c602C173
CLOBPoolManager0x9C6B7292a52ea1Ca2A19B45E041d8653A4aD534f
CLOBBalanceManager0xE75E8b4861D9cC5Da3bbF6C7f280A8E163dD8554

Upgradeability Considerations

What Can Be Upgraded

  • OrderBook implementation (via beacon)
  • Router logic
  • BalanceManager logic
  • Hooks implementation

What Cannot Be Changed

  • Storage slot locations (would corrupt data)
  • Core authorization relationships
  • Fund custody guarantees

Upgrade Process

  1. Deploy new implementation contract
  2. Verify implementation correctness
  3. Update beacon to point to new implementation
  4. All proxies immediately use new logic