​
Balance Management

The BalanceManager contract handles all fund custody and balance tracking 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

​
Deposits

​
Token Deposits

  1. Approve the BalanceManager to spend your tokens
  2. Call deposit() through the CLOBRouter
  3. Funds become available in your CLOB balance

​
ETH Deposits

For native ETH:
  1. Call depositETH() with value
  2. ETH is wrapped to WETH automatically
  3. WETH becomes available in your CLOB balance

​
Withdrawals

Call withdraw() through the CLOBRouter to move funds back to your wallet. Important: Only available (unlocked) funds can be withdrawn. To withdraw locked funds, cancel the associated orders first.

​
Fund Locking

When you place an order:
  • Required funds move from available to locked
  • Locked funds are reserved for that specific order
When you cancel an order:
  • Locked funds return to available
  • You can then withdraw or use for new orders

​
Trade Settlement

When orders match:
  • Locked funds transfer between buyer and seller
  • Fees are deducted automatically
  • Counterparty receives funds in their available balance

​
Fee Structure

Fee TypeWhen Applied
Maker FeeOrder adds liquidity (resting order)
Taker FeeOrder removes liquidity (crossing order)
Fees are deducted during settlement. The fee receiver accumulates fees from both sides of each trade.

​
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 OrderBook.

​
Total Balance

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

​
Security

​
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
unlockOrderBook
transferLockedFromOrderBook

​
Error Handling

ErrorCauseResolution
InsufficientBalanceNot enough available fundsDeposit more or cancel orders
ZeroAmountAttempted zero-value operationUse non-zero amount
UnauthorizedCallerCaller not authorizedUse CLOBRouter
TransferErrorToken transfer failedCheck token approval/balance
NativeTransferFailedETH transfer failedCheck recipient can receive ETH

​
Events

EventDescription
DepositFunds deposited
WithdrawalFunds withdrawn
LockFunds locked for order
UnlockFunds unlocked
TransferFromSettlement transfer
TransferLockedFromLocked fund transfer