feat(defi): add CLOB example ported from mikemaccana/anchor-decentralized-exchange-clob

Adds a teaching-grade central limit order book under defi/clob/anchor.
The port brings the source program from Anchor 0.32.1 to Anchor 1.0.0 and
conforms it to the solana-anchor-claude-skill ruleset so it can sit
alongside the other Financial Software examples.

Why this example belongs in program-examples:
- The existing DeFi corpus covers constant-product AMMs and peer-to-peer
  escrow; a CLOB rounds out the set so readers can see how limit-order
  exchanges work on Solana without having to read Openbook/Phoenix's much
  larger zero-copy codebases.
- It demonstrates several patterns the simpler examples don't: PDAs
  authoring token vaults, per-user per-market state, and an unsettled-
  balance + settle step that mirrors how real exchanges decouple
  matching from fund movement.

Program side (Anchor 1.0 migration + skill rules):
- declare_id! kept; every handler uses `context` rather than `ctx`.
- `context.bumps.x` direct field access, no `.get("x").unwrap()`.
- All #[account] structs derive InitSpace and store `pub bump: u8`,
  saved in the init handler.
- Every `space = ...` uses `T::DISCRIMINATOR.len() + T::INIT_SPACE` —
  no magic 8, no hand-sized byte math, no custom discriminator consts.
- Clock::get()? instead of the anchor_lang::solana_program path.
- Token accounts use anchor_spl::token_interface for Token-2022 support.
- PlaceOrderAccountConstraints and SettleFundsAccountConstraints box
  their InterfaceAccount fields — without boxing the BPF frame exceeds
  the 4 KB stack-offset limit. A comment on each documents the reason.
- CpiContext::new / new_with_signer now take `token_program.key()`,
  matching the Anchor 1.0 signature change.
- MAX_ORDERS_PER_SIDE and MAX_OPEN_ORDERS_PER_USER are named
  constants with rationale, instead of the magic 100 / 20 in the source.
- Dead matching-engine helpers from the upstream `utils/matching.rs`
  are removed: they were never invoked by place_order and contained an
  obvious quantity-accounting bug. The README's "Scope note" flags that
  a real matching engine is the natural next extension — better to be
  honest about the limit than to ship broken code.

Test side (Mike-canonical pattern):
- node:test via `npx tsx --test --test-reporter=spec`.
- solana-kite `connect()` / `createWallets` / `createTokenMint` /
  `sendTransactionFromInstructions` — no @coral-xyz/anchor, no
  web3.js v1, no ts-mocha, no chai, no bs58.
- @solana/kit types (TransactionSigner, Address, lamports).
- Codama-generated TS client under dist/clob-client (built by the
  Anchor.toml `test` script via `npx create-codama-clients`).
- TOKEN_EXTENSIONS_PROGRAM from solana-kite, PDAs via
  `connection.getPDAAndBump`, token accounts via
  `connection.getTokenAccountAddress`.
- 9 tests cover the full happy path (initialize, create user, bid,
  ask, cancel, settle, cancel+settle buyer) plus two failure cases
  (invalid price, non-owner cancel).

Known limitation called out in the README: surfpool (Anchor 1.0's
default local validator) does not accept the websocket RPC methods
Kit uses for transaction confirmation; `anchor test --validator legacy`
is required until surfpool catches up.

Author: mikemaccana-edwardbot

README.md

@@ -22,6 +22,12 @@ Constant product AMM (x·y=k) — create liquidity pools, deposit and withdraw l
 
 [⚓ Anchor](./tokens/token-swap/anchor) [💫 Quasar](./tokens/token-swap/quasar)
 
+### Central Limit Order Book
+
+Order-book exchange — users post limit bids and asks at chosen prices, tokens are locked in program vaults, and orders can be cancelled and funds settled back. A minimal teaching example of the mechanics behind Openbook and Phoenix.
+
+[⚓ Anchor](./defi/clob/anchor)
+
 ### Escrow
 
 Peer-to-peer OTC trade — one user deposits token A and specifies how much token B they want. A counterparty fulfils the offer and both sides receive their tokens atomically.

defi/clob/anchor/.gitignore

@@ -0,0 +1,8 @@
+.anchor
+.DS_Store
+target
+**/*.rs.bk
+node_modules
+test-ledger
+.yarn
+dist

defi/clob/anchor/Anchor.toml

@@ -0,0 +1,34 @@
+[toolchain]
+anchor_version = "1.0.0"
+solana_version = "3.1.8"
+# pnpm matches the program-examples root package manager.
+package_manager = "pnpm"
+
+[features]
+resolution = true
+skip-lint = false
+
+[programs.localnet]
+clob = "C69UJ8irfmHq5ysyLek7FKApHR86FBeupiz4JnoyPzzx"
+
+[provider]
+cluster = "localnet"
+wallet = "~/.config/solana/id.json"
+
+[scripts]
+# Generate the Codama TS client from the built IDL, then run node:test tests
+# via tsx. Run with: `anchor test --validator legacy`
+#
+# The `legacy` flag selects `solana-test-validator`, which Kit can talk to.
+# Anchor 1.0's default "surfpool" validator does not accept the websocket RPC
+# methods Kit uses for confirmation, so tests time out waiting for their
+# first transaction. Revisit when surfpool adds full Kit support.
+test = "npx create-codama-clients && npx tsx --test --test-reporter=spec tests/*.ts"
+
+[hooks]
+
+[test]
+# Give the local validator enough time to become reachable before tests start.
+startup_wait = 10000
+shutdown_wait = 2000
+upgradeable = false

defi/clob/anchor/Cargo.toml

@@ -0,0 +1,13 @@
+[workspace]
+members = ["programs/*"]
+resolver = "2"
+
+[profile.release]
+overflow-checks = true
+lto = "fat"
+codegen-units = 1
+
+[profile.release.build-override]
+opt-level = 3
+incremental = false
+codegen-units = 1

defi/clob/anchor/README.md

@@ -0,0 +1,46 @@
+# Anchor CLOB
+
+A minimal **Central Limit Order Book** (CLOB) on Solana. Users place limit buy (bid) or sell (ask) orders at a chosen price; their tokens sit in a program-owned vault until the order is cancelled. Cancellation credits the refund to an internal balance and a later `settle_funds` call moves those tokens back to the user.
+
+This is a teaching example. It is deliberately small — the real CLOBs on Solana (Openbook, Phoenix) use zero-copy slab data structures and much more sophisticated matching and fee logic.
+
+## Concepts
+
+- **Market** — one trading pair, e.g. `BASE/QUOTE`. Stored at a PDA seeded by the two mints. The market account is the signer of its two token vaults.
+- **Order Book** — a PDA per market holding two `Vec<OrderEntry>`s: bids (sorted descending by price) and asks (sorted ascending). Price-time priority is implicit in the order they are inserted.
+- **User Account** — one per user per market. Tracks the user's open order ids and two "unsettled" balances (base and quote) representing tokens the program owes the user but has not yet transferred back.
+- **Order** — a PDA per placed order, seeded by `(market, order_id)`. Stores price, original and filled quantity, status (`Open`, `PartiallyFilled`, `Filled`, `Cancelled`) and the owner.
+
+## Instructions
+
+| Name                  | What it does |
+|-----------------------|--------------|
+| `initialize_market`   | Create the market, order book and two token vaults for a `base/quote` pair. Sets fee (bps), tick size and minimum order size. |
+| `create_user_account` | Initialise the caller's per-market user account. |
+| `place_order`         | Add a limit order to the book and lock the funds it would need if filled: bids lock `price × quantity` of quote; asks lock `quantity` of base. |
+| `cancel_order`        | Close an open (or partially filled) order. Credits the still-locked amount to the owner's `unsettled_base` / `unsettled_quote`. |
+| `settle_funds`        | Move all unsettled base and quote from the market's vaults back to the owner's token accounts. Signs with the market PDA. |
+
+### Scope note
+
+The program stores the book and locks funds on placement, but does **not** currently run a matching engine inside `place_order`. Crossed orders (a bid at or above the best ask) will sit side-by-side in the book rather than trade. Adding matching requires passing the opposing orders (and their owners' user accounts and token accounts) as remaining accounts and clearing the filled amounts across both sides; it's a natural next extension.
+
+## Build
+
+```shell
+anchor build
+```
+
+## Test
+
+```shell
+anchor test --validator legacy
+```
+
+The `--validator legacy` flag is required: Anchor 1.0's default "surfpool" validator does not yet accept the websocket RPC methods Solana Kit uses for transaction confirmation, so tests hang waiting for their first transaction. `solana-test-validator` works.
+
+The test script (defined in `Anchor.toml`) first runs `npx create-codama-clients` to generate a TypeScript client from the built IDL into `dist/clob-client/`, then executes the `node:test` suite with `tsx`.
+
+## Credit
+
+Ported and modernised from [anchor-decentralized-exchange-clob](https://github.com/mikemaccana/anchor-decentralized-exchange-clob). Migrated from Anchor 0.32.1 to Anchor 1.0.0 and conformed to the [Solana Anchor coding skill](https://github.com/mikemaccana/solana-anchor-claude-skill) (Kit + Kite + Codama, `node:test`, no `@coral-xyz/anchor`, no magic numbers, `Box`-ed interface accounts to keep BPF stack size within budget).

defi/clob/anchor/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "clob",
+  "version": "0.1.0",
+  "license": "ISC",
+  "type": "module",
+  "scripts": {
+    "build": "anchor build",
+    "codama": "npx create-codama-clients",
+    "test": "npx create-codama-clients && npx tsx --test --test-reporter=spec tests/*.ts"
+  },
+  "dependencies": {
+    "@solana/kit": "^6.1.0"
+  },
+  "devDependencies": {
+    "@codama/nodes-from-anchor": "^1.3.8",
+    "@codama/renderers": "^1.0.34",
+    "@codama/renderers-js": "^1.7.0",
+    "@types/node": "^20.11.0",
+    "codama": "^1.5.0",
+    "solana-kite": "^3.2.1",
+    "tsx": "^4.7.0",
+    "typescript": "^5.7.3"
+  }
+}

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

@@ -0,0 +1,27 @@
+[package]
+name = "clob"
+version = "0.1.0"
+description = "Central limit order book on Solana"
+edition = "2021"
+
+[lib]
+crate-type = ["cdylib", "lib"]
+name = "clob"
+
+[features]
+default = []
+cpi = ["no-entrypoint"]
+no-entrypoint = []
+no-idl = []
+no-log-ix-name = []
+idl-build = ["anchor-lang/idl-build", "anchor-spl/idl-build"]
+anchor-debug = []
+custom-heap = []
+custom-panic = []
+
+[dependencies]
+anchor-lang = "1.0.0"
+anchor-spl = "1.0.0"
+
+[lints.rust]
+unexpected_cfgs = { level = "warn", check-cfg = ['cfg(target_os, values("solana"))'] }

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

@@ -0,0 +1,40 @@
+use anchor_lang::prelude::*;
+
+#[error_code]
+pub enum ErrorCode {
+    #[msg("Invalid price provided")]
+    InvalidPrice,
+
+    #[msg("Invalid quantity provided")]
+    InvalidQuantity,
+
+    #[msg("Order not found")]
+    OrderNotFound,
+
+    #[msg("Market is currently paused")]
+    MarketPaused,
+
+    #[msg("Unauthorized action")]
+    Unauthorized,
+
+    #[msg("Order book is full")]
+    OrderBookFull,
+
+    #[msg("User account has too many open orders")]
+    TooManyOpenOrders,
+
+    #[msg("Price does not align with tick size")]
+    InvalidTickSize,
+
+    #[msg("Quantity is below minimum order size")]
+    BelowMinOrderSize,
+
+    #[msg("Order is not cancellable in current status")]
+    OrderNotCancellable,
+
+    #[msg("Numerical overflow occurred")]
+    NumericalOverflow,
+
+    #[msg("Fee basis points out of range")]
+    InvalidFeeBasisPoints,
+}

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

@@ -0,0 +1,86 @@
+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,
+};
+
+pub fn cancel_order(context: Context<CancelOrderAccountConstraints>) -> Result<()> {
+    let order = &mut context.accounts.order;
+
+    require!(
+        order.owner == context.accounts.owner.key(),
+        ErrorCode::Unauthorized
+    );
+
+    require!(
+        order.status == OrderStatus::Open || order.status == OrderStatus::PartiallyFilled,
+        ErrorCode::OrderNotCancellable
+    );
+
+    // Funds the order had locked in the vault are now owed back to the
+    // owner. Credit the appropriate unsettled balance; settle_funds moves
+    // 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;
+        match order.side {
+            OrderSide::Bid => {
+                let quote_amount = order
+                    .price
+                    .checked_mul(remaining)
+                    .ok_or(ErrorCode::NumericalOverflow)?;
+                user_account.unsettled_quote = user_account
+                    .unsettled_quote
+                    .checked_add(quote_amount)
+                    .ok_or(ErrorCode::NumericalOverflow)?;
+            }
+            OrderSide::Ask => {
+                user_account.unsettled_base = user_account
+                    .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);
+    require!(removed, ErrorCode::OrderNotFound);
+
+    let user_account = &mut context.accounts.user_account;
+    remove_open_order(user_account, order.order_id);
+
+    order.status = OrderStatus::Cancelled;
+
+    Ok(())
+}
+
+#[derive(Accounts)]
+pub struct CancelOrderAccountConstraints<'info> {
+    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>,
+
+    #[account(
+        mut,
+        seeds = [ORDER_SEED, market.key().as_ref(), order.order_id.to_le_bytes().as_ref()],
+        bump = order.bump
+    )]
+    pub order: Account<'info, Order>,
+
+    #[account(
+        mut,
+        seeds = [USER_ACCOUNT_SEED, market.key().as_ref(), owner.key().as_ref()],
+        bump = user_account.bump
+    )]
+    pub user_account: Account<'info, UserAccount>,
+
+    pub owner: Signer<'info>,
+}

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

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