refactor(clob): port Openbook v2 critbit slab; rename UserAccount → MarketUser

Replaces the per-side Vec<OrderEntry> order-book backing store with a
critbit (binary radix trie) slab ported from openbook-dex/openbook-v2.
The slab gives the order book O(log N) inserts/deletes/lookups whose
worst case is bounded by the price-key bit width (128 bits), not by
insertion order, so an adversary picking monotonically-increasing prices
can no longer degenerate the book into a linked list.

Why critbit specifically (not red-black): the upstream Openbook v2 slab
already uses critbit, both shapes give the bounds we need, and the
critbit invariants are simpler to port (no recolouring, no rotations).
See the README's new "Why a balanced tree (critbit)?" section for the
DoS framing.

Companion rename: UserAccount → MarketUser

The per-(user, market) state struct was previously named UserAccount,
which falsely suggested a per-user record. Renamed throughout so the
name matches what it scopes to:

  - struct UserAccount → struct MarketUser
  - Accounts context CreateUserAccount → CreateMarketUser
  - PDA seed b"user" → b"market_user"; constant USER_ACCOUNT_SEED →
    MARKET_USER_SEED (breaking change — pre-merge, no live PDAs to
    migrate)
  - File state/user_account.rs → state/market_user.rs
  - File instructions/create_user_account.rs →
    instructions/create_market_user.rs
  - Handler fn create_user_account → create_market_user
  - Variable/field names like buyer_user_account, maker_user_account,
    taker_user_account → buyer_market_user, maker_market_user, etc.
  - README, tests, error messages all updated.

User-owned ATA names (user_base_account, user_quote_account) are NOT
renamed — they're token accounts owned by the human user, not program
state, so the 'user' prefix is correct there. The 'user' signer arg
also stays as 'user'.

Matches the standard pattern: Openbook v2 calls this OpenOrdersAccount,
Phoenix calls it Trader, Serum called it OpenOrders. We use MarketUser
to make the (user, market) scope explicit in the name.

Documentation: new README section §2 'Why per-(user, market) and not
per-user?' (unsettled balances, open-order indexing, lock-contention
isolation). New README section §8 'Why a balanced tree (critbit)?'
with the monotonic-attacker example and Solana CU/DoS framing.

Terminology rule: new TERMINOLOGY.md documents the project-wide rule
to disambiguate overloaded terms in README and code comments — balance
(token vs tree), order vs ordering, key, node, position, settle — so
future contributors don't reintroduce the ambiguity this PR is
removing.

Tests: 24/24 pass under cargo test (LiteSVM).

Author: Edward (Mike's bot)

defi/clob/anchor/README.md

@@ -0,0 +1,79 @@
+# Terminology Rules — CLOB
+
+Project-wide rules for the README and code comments in this crate. Applies
+throughout, not just one section. Audit for these before opening / merging
+any PR that touches docs or comments.
+
+## General rule
+
+> If a word has two meanings within ~1 paragraph of context, use the
+> explicit phrase even if it's a few chars longer.
+
+A wrong or ambiguous statement is worse than no statement.
+
+## Overloaded terms
+
+### "balance" — most important
+
+`balance` is ambiguous in a CLOB context: it can mean token balance,
+account balance, **or** the tree-balancing property (the critbit
+slab is balanced-by-construction). Pick one of:
+
+- ✅ "tree balancing"
+- ✅ "balanced tree shape"
+- ✅ "keeps the tree shape balanced"
+- ❌ "the critbit tree maintains balance"
+
+For money, use **"token balance"** or **"account balance"** explicitly
+whenever it's near a tree discussion.
+
+### "book"
+
+Usually fine in context ("order book"). Be careful in mixed sentences —
+qualify when ambiguity is possible.
+
+### "order" vs "ordering"
+
+`order` = trading order. `ordering` = sort order. When a sentence touches
+both:
+
+- ✅ "price-sorted", "sorted by price"
+- ❌ "in price order"
+
+### "settle"
+
+Be specific:
+
+- ✅ `settle_funds` instruction
+- ✅ "transaction settlement"
+- ❌ bare "settle" / "settlement" when the meaning isn't obvious
+
+### "key"
+
+Never bare `key`. Use:
+
+- "address" (a Solana public key used as an address)
+- "public key" (a cryptographic key)
+- "sort key" (the value the tree is sorted on)
+
+### "node"
+
+Qualify:
+
+- "validator node" (Solana cluster)
+- "tree node" / "slab node" (data structure)
+
+### "position"
+
+Qualify:
+
+- "trading position" (financial)
+- "slot position" / "array index" (slab / array)
+
+## Reviewer checklist
+
+Before approving a doc/comment PR:
+
+- [ ] No bare "balance" when the critbit tree is in scope.
+- [ ] No bare "key", "node", "position", "settle" in ambiguous contexts.
+- [ ] "Order" / "ordering" disambiguated when both senses appear nearby.

defi/clob/anchor/TERMINOLOGY.md

@@ -22,6 +22,12 @@ custom-panic = []
 [dependencies]
 anchor-lang = "1.0.0"
 anchor-spl = "1.0.0"
+# Used by the ported Openbook slab — `bytemuck::Pod` / `Zeroable` on every node
+# variant + `min_const_generics` so `[AnyNode; 1024]` can derive Pod without
+# hitting bytemuck's default-32 array cap. `static_assertions` keeps the slab
+# layout asserts (node size, alignment) compile-time, matching upstream.
+bytemuck = { version = "1.18", features = ["derive", "min_const_generics"] }
+static_assertions = "1.1"
 
 [dev-dependencies]
 # Match the test stack used by tokens/escrow, defi/asset-leasing, and the

defi/clob/anchor/programs/clob/Cargo.toml

@@ -20,7 +20,7 @@ pub enum ErrorCode {
     #[msg("Order book is full")]
     OrderBookFull,
 
-    #[msg("User account has too many open orders")]
+    #[msg("MarketUser has too many open orders")]
     TooManyOpenOrders,
 
     #[msg("Price does not align with tick size")]
@@ -59,9 +59,12 @@ pub enum ErrorCode {
     #[msg("Not enough maker accounts supplied to cross the incoming order")]
     MissingMakerAccounts,
 
-    #[msg("Maker order and maker user account owner mismatch")]
+    #[msg("Maker order and maker MarketUser owner mismatch")]
     MakerOwnerMismatch,
 
     #[msg("Only the market authority can withdraw fees")]
     NotMarketAuthority,
+
+    #[msg("Order book account does not match the market's order book")]
+    InvalidOrderBook,
 }

defi/clob/anchor/programs/clob/src/errors.rs

@@ -2,8 +2,8 @@ use anchor_lang::prelude::*;
 
 use crate::errors::ErrorCode;
 use crate::state::{
-    remaining_quantity, remove_open_order, remove_order, Market, Order, OrderBook, OrderSide,
-    OrderStatus, UserAccount, ORDER_BOOK_SEED, ORDER_SEED, USER_ACCOUNT_SEED,
+    remaining_quantity, remove_open_order, Market, Order, OrderBook, OrderSide, OrderStatus,
+    MarketUser, ORDER_SEED, MARKET_USER_SEED,
 };
 
 pub fn handle_cancel_order(context: Context<CancelOrder>) -> Result<()> {
@@ -24,33 +24,37 @@ pub fn handle_cancel_order(context: Context<CancelOrder>) -> Result<()> {
     // those funds from the vault to the owner's token account.
     let remaining = remaining_quantity(order);
     if remaining > 0 {
-        let user_account = &mut context.accounts.user_account;
+        let market_user = &mut context.accounts.market_user;
         match order.side {
             OrderSide::Bid => {
                 let quote_amount = order
                     .price
                     .checked_mul(remaining)
                     .ok_or(ErrorCode::NumericalOverflow)?;
-                user_account.unsettled_quote = user_account
+                market_user.unsettled_quote = market_user
                     .unsettled_quote
                     .checked_add(quote_amount)
                     .ok_or(ErrorCode::NumericalOverflow)?;
             }
             OrderSide::Ask => {
-                user_account.unsettled_base = user_account
+                market_user.unsettled_base = market_user
                     .unsettled_base
                     .checked_add(remaining)
                     .ok_or(ErrorCode::NumericalOverflow)?;
             }
         }
     }
 
-    let order_book = &mut context.accounts.order_book;
-    let removed = remove_order(order_book, order.order_id);
+    // Remove the leaf from the slab. The current cancel API doesn't tell us
+    // which side the order is on without reading the Order PDA — which we
+    // already have, so use it.
+    let mut order_book = context.accounts.order_book.load_mut()?;
+    let removed = order_book.remove_from(order.side, order.order_id).is_some();
     require!(removed, ErrorCode::OrderNotFound);
+    drop(order_book);
 
-    let user_account = &mut context.accounts.user_account;
-    remove_open_order(user_account, order.order_id);
+    let market_user = &mut context.accounts.market_user;
+    remove_open_order(market_user, order.order_id);
 
     order.status = OrderStatus::Cancelled;
 
@@ -59,14 +63,12 @@ pub fn handle_cancel_order(context: Context<CancelOrder>) -> Result<()> {
 
 #[derive(Accounts)]
 pub struct CancelOrder<'info> {
+    #[account(has_one = order_book @ ErrorCode::InvalidOrderBook)]
     pub market: Account<'info, Market>,
 
-    #[account(
-        mut,
-        seeds = [ORDER_BOOK_SEED, market.key().as_ref()],
-        bump = order_book.bump
-    )]
-    pub order_book: Account<'info, OrderBook>,
+    // Not a PDA (see initialize_market.rs); bound to `market` via has_one.
+    #[account(mut)]
+    pub order_book: AccountLoader<'info, OrderBook>,
 
     #[account(
         mut,
@@ -77,10 +79,10 @@ pub struct CancelOrder<'info> {
 
     #[account(
         mut,
-        seeds = [USER_ACCOUNT_SEED, market.key().as_ref(), owner.key().as_ref()],
-        bump = user_account.bump
+        seeds = [MARKET_USER_SEED, market.key().as_ref(), owner.key().as_ref()],
+        bump = market_user.bump
     )]
-    pub user_account: Account<'info, UserAccount>,
+    pub market_user: Account<'info, MarketUser>,
 
     pub owner: Signer<'info>,
 }

defi/clob/anchor/programs/clob/src/instructions/cancel_order.rs

@@ -0,0 +1,34 @@
+use anchor_lang::prelude::*;
+
+use crate::state::{Market, MarketUser, MARKET_USER_SEED};
+
+pub fn handle_create_market_user(context: Context<CreateMarketUser>) -> Result<()> {
+    let market_user = &mut context.accounts.market_user;
+    market_user.market = context.accounts.market.key();
+    market_user.owner = context.accounts.owner.key();
+    market_user.unsettled_base = 0;
+    market_user.unsettled_quote = 0;
+    market_user.open_orders = Vec::new();
+    market_user.bump = context.bumps.market_user;
+
+    Ok(())
+}
+
+#[derive(Accounts)]
+pub struct CreateMarketUser<'info> {
+    #[account(
+        init,
+        payer = owner,
+        space = MarketUser::DISCRIMINATOR.len() + MarketUser::INIT_SPACE,
+        seeds = [MARKET_USER_SEED, market.key().as_ref(), owner.key().as_ref()],
+        bump
+    )]
+    pub market_user: Account<'info, MarketUser>,
+
+    pub market: Account<'info, Market>,
+
+    #[account(mut)]
+    pub owner: Signer<'info>,
+
+    pub system_program: Program<'info, System>,
+}

defi/clob/anchor/programs/clob/src/instructions/create_market_user.rs

@@ -2,7 +2,7 @@ use anchor_lang::prelude::*;
 use anchor_spl::token_interface::{Mint, TokenAccount, TokenInterface};
 
 use crate::errors::ErrorCode;
-use crate::state::{Market, OrderBook, MARKET_SEED, ORDER_BOOK_SEED};
+use crate::state::{Market, OrderBook, MARKET_SEED};
 
 // Basis points are hundredths of a percent; 10000 bps == 100%. Fees above 100%
 // would be nonsensical, so we cap here.
@@ -35,13 +35,12 @@ pub fn handle_initialize_market(
     market.is_active = true;
     market.bump = context.bumps.market;
 
-    let order_book = &mut context.accounts.order_book;
-    order_book.market = context.accounts.market.key();
-    order_book.bids = Vec::new();
-    order_book.asks = Vec::new();
-    // Start at 1 so order_id == 0 can stand for "no order" in clients if needed.
-    order_book.next_order_id = 1;
-    order_book.bump = context.bumps.order_book;
+    // Zero-copy account: initialize the slab in place. `load_init` is the
+    // first-write path — every subsequent handler uses `load` / `load_mut`.
+    // The order book is not a PDA (see the comment on the `order_book`
+    // account below), so `bump` is unused and stored as 0.
+    let mut order_book = context.accounts.order_book.load_init()?;
+    order_book.initialize(context.accounts.market.key(), 0);
 
     Ok(())
 }
@@ -57,14 +56,24 @@ pub struct InitializeMarket<'info> {
     )]
     pub market: Account<'info, Market>,
 
-    #[account(
-        init,
-        payer = authority,
-        space = OrderBook::DISCRIMINATOR.len() + OrderBook::INIT_SPACE,
-        seeds = [ORDER_BOOK_SEED, market.key().as_ref()],
-        bump
-    )]
-    pub order_book: Account<'info, OrderBook>,
+    // The order book is a zero-copy account (~180 KB: two 1024-slot critbit
+    // slabs back to back). Solana's BPF runtime caps inner-CPI account
+    // allocations at 10 KB, so we can't use Anchor's `init` here — the
+    // client must call system_program::create_account directly before this
+    // instruction, sizing the account to ORDER_BOOK_ACCOUNT_SIZE, owned by
+    // this program, and zero-initialized.
+    //
+    // `#[account(zero)]` verifies the account is owned by this program
+    // and has its discriminator unset, which is exactly what a freshly
+    // create_account-d account looks like. The handler then stamps the
+    // discriminator + struct via `load_init()`.
+    //
+    // The account is passed in as a regular Signer (created by the client),
+    // not a PDA. The README documents the (program_id, MARKET_SEED + market)
+    // PDA derivation that clients should still use for the account address
+    // — we just have to allocate it ourselves.
+    #[account(zero)]
+    pub order_book: AccountLoader<'info, OrderBook>,
 
     pub base_mint: InterfaceAccount<'info, Mint>,
 

defi/clob/anchor/programs/clob/src/instructions/create_user_account.rs

@@ -1,12 +1,12 @@
 pub mod cancel_order;
-pub mod create_user_account;
+pub mod create_market_user;
 pub mod initialize_market;
 pub mod place_order;
 pub mod settle_funds;
 pub mod withdraw_fees;
 
 pub use cancel_order::*;
-pub use create_user_account::*;
+pub use create_market_user::*;
 pub use initialize_market::*;
 pub use place_order::*;
 pub use settle_funds::*;