​
Balance Management

The BalanceManager contract handles all fund custody, balance tracking, and settlement within the CLOB system.

​
Balance States

Funds in the CLOB system exist in two states:
StateDescription
AvailableFunds deposited but not committed to orders
LockedFunds committed to open orders

​
Deposit Flow

​
Token Deposits

​
ETH Deposits

For native ETH, the system wraps to WETH:

​
Withdrawal Flow

Important: Only available (unlocked) funds can be withdrawn. To withdraw locked funds, cancel the associated orders first.

​
Lock/Unlock Mechanism

​
Locking Funds

When an order is placed, funds are moved from available to locked:

​
Unlocking Funds

When an order is cancelled, funds return to available:

​
Trade Settlement

When orders match, locked funds are transferred between parties:

​
Fee Structure

​
Fee Types

Fee TypeWhen AppliedTypical Rate
Maker FeeOrder adds liquidity (resting)Lower
Taker FeeOrder removes liquidity (crossing)Higher

​
Fee Calculation

feeAmount = (tradeAmount * feeRate) / FEE_UNIT
Where FEE_UNIT is the fee denominator (e.g., 1,000,000 for basis point precision).

​
Fee Collection Flow

Fees are deducted atomically during settlement:
  • Maker receives: tradeAmount - makerFee
  • Taker receives: tradeAmount - takerFee
  • Fee receiver accumulates both fees

​
Balance Queries

​
Available Balance

function getBalance(address user, address currency)
    external view returns (uint256)
Returns funds available for new orders or withdrawal.

​
Locked Balance

function getLockedBalance(
    address user,
    address operator,
    address currency
) external view returns (uint256)
Returns funds locked by a specific operator (OrderBook).

​
Total Balance

A user’s total funds = available + sum(locked across all pools)

​
Security Model

​
Fund Isolation

  • Each user’s funds are tracked separately
  • Locked funds are isolated per OrderBook
  • No cross-user fund access

​
Authorization

OperationAuthorized Callers
depositCLOBRouter
withdrawCLOBRouter
lockOrderBook (via Router)
unlockOrderBook
transferLockedFromOrderBook

​
Invariants

The BalanceManager maintains critical invariants:
  1. Token Balance Invariant 
    token.balanceOf(BalanceManager) >=
    sum(balances) + sum(lockedBalances)
  2. User Balance Invariant 
    user.available + user.locked == user.deposited - user.withdrawn
  3. No Negative Balances
    • All balance operations check for sufficient funds
    • Underflow-protected arithmetic

​
Error Handling

ErrorCauseResolution
InsufficientBalanceNot enough available fundsDeposit more or cancel orders
ZeroAmountAttempted zero-value operationUse non-zero amount
UnauthorizedCallerCaller not in authorized listUse authorized entry point
UnauthorizedOperatorOperator not authorized for userCheck operator permissions
TransferErrorToken transfer failedCheck token approval/balance
NativeTransferFailedETH transfer failedCheck recipient can receive ETH

​
Events

EventParametersDescription
Deposituser, currency, amountFunds deposited
Withdrawaluser, currency, amountFunds withdrawn
Lockuser, currency, amountFunds locked for order
Unlockuser, currency, amountFunds unlocked
TransferFromoperator, sender, receiver, currency, amount, feeSettlement transfer
TransferLockedFromoperator, sender, receiver, currency, amount, feeLocked fund transfer