Contract Architecture
The CLOB system is composed of multiple contracts with clearly defined responsibilities and interactions.Contract Hierarchy
Contract Responsibilities
| Contract | Layer | Responsibility |
|---|---|---|
| CLOBRouter | Entry | User-facing API for orders, deposits, withdrawals |
| CLOBSwapRouter | Entry | Optimized swap execution across pools |
| PoolManager | Management | Pool lifecycle, trading rules, OrderBook deployment |
| OrderBook | Core | Order matching, price trees, trade execution |
| BalanceManager | Core | Fund custody, locking, fee collection |
| HooksRegistry | Extension | Custom hook registration and execution |
| MarketMakingVault | Extension | Automated market making strategies |
| VaultGauge | Extension | Incentive 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
| Contract | Authorized Callers |
|---|---|
| OrderBook | CLOBRouter, PoolManager |
| BalanceManager | CLOBRouter, OrderBook |
| HooksRegistry | OrderBook |
Role-Based Access
| Role | Permissions |
|---|---|
| Owner | Upgrade contracts, configure fees, pause trading |
| Operator | Create pools, modify trading rules |
| Router | Place/cancel orders, manage balances |
| OrderBook | Lock/unlock funds, execute transfers |
Storage Layout (ERC-7201)
The contracts use namespaced storage following ERC-7201 for safe upgrades.OrderBook Storage
BalanceManager Storage
Contract Addresses
| Contract | Address |
|---|---|
| CLOBRouter | 0x29BF83fF2bb9E0c5C273b0B118C465D6c602C173 |
| CLOBPoolManager | 0x9C6B7292a52ea1Ca2A19B45E041d8653A4aD534f |
| CLOBBalanceManager | 0xE75E8b4861D9cC5Da3bbF6C7f280A8E163dD8554 |
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
- Deploy new implementation contract
- Verify implementation correctness
- Update beacon to point to new implementation
- All proxies immediately use new logic