Skip to content

Commit 7c3f9c8

Browse files
author
Edward (Mike's bot)
committed
docs(order-book): reserve "CLOB" for teaching/ecosystem context only
Audit pass to align with the project rule: use "order book" / "order-book" by default; reserve "CLOB" for the introductory acronym definition, the H1 heading (searchability for finance-literate readers), the Cargo package description first-mention, and ecosystem-mapping references to other CLOBs (Phoenix, Openbook v2). Replaced "CLOB" with "order book" / "order-book" in: - README §1 "What does this program do?" passing reference ("runs an onchain order book for a single pair of token mints") - README §6.2 "This is the standard order-book rule" - README §6.2 "...of an order book." - README §6.3 "A production order book would add:" - README §8 "For a production order book it's wrong" - README §8 "In an order book an attacker chooses the inputs" - test_order_book.rs doc-comment header, scenario comments, and create_market_user / matching engine comments - matching.rs "standard order-book rule" - slab/nodes.rs ("this order book is fixed-price only") - slab/ordertree.rs ("Callers in this order book embed a...") - TERMINOLOGY.md title and the "balance" example phrasing Kept as "CLOB": - README H1 "Order Book \u2014 Central Limit Order Book (CLOB)" (searchability) - README §1 first-mention teaching pattern - README §1 "production Solana CLOBs to read alongside it" (ecosystem) - README §1 "Real Solana CLOBs (Openbook v2, Phoenix)" (ecosystem) - place_order.rs comment "Real CLOBs (Openbook v2, Phoenix) use a similar" (ecosystem) - Cargo.toml package description (one mention for crates.io searchability) Tests: 24/24 still pass (comment-only changes).
1 parent 4a792de commit 7c3f9c8

6 files changed

Lines changed: 16 additions & 16 deletions

File tree

defi/order-book/anchor/README.md

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
This is an **order book** — specifically, a **central limit order
44
book (CLOB)**, the standard piece of market infrastructure used by
55
NYSE, NASDAQ, LSE, CME, and every major crypto venue. An Anchor
6-
program that runs an onchain CLOB for a single pair of token mints:
6+
program that runs an onchain order book for a single pair of token mints:
77
users post buy or sell offers at the prices they want, the program
88
matches crossing offers in price-time priority, and settles the
99
resulting token movements.
@@ -1106,8 +1106,8 @@ From [`errors.rs`](programs/order-book/src/errors.rs):
11061106
- **Matching applies at the maker's price, not the taker's.** The
11071107
fill price is always the resting order's price. Takers that cross
11081108
deeper into the book get price improvement, refunded to
1109-
`unsettled_quote` (for taker bids). This is the standard CLOB
1110-
rule.
1109+
`unsettled_quote` (for taker bids). This is the standard
1110+
order-book rule.
11111111
11121112
- **Fees come out of the gross.** The maker receives `gross - fee`,
11131113
not `gross`; the fee lives on for a while in `quote_vault` before
@@ -1144,11 +1144,11 @@ From [`errors.rs`](programs/order-book/src/errors.rs):
11441144
check happens at the end. A bid that clears enough asks to free
11451145
up 3 slots can then rest its own 1-slot remainder even on a
11461146
previously-full book — matching the "liquidity-positive" spirit
1147-
of a CLOB.
1147+
of an order book.
11481148
11491149
### 6.3 Things this example does *not* do
11501150
1151-
A production CLOB would add:
1151+
A production order book would add:
11521152
11531153
- **Zero-copy OrderBook.** 100 entries per side deserialised every
11541154
call limits both throughput and maximum book size.
@@ -1328,12 +1328,12 @@ Ordered by difficulty.
13281328

13291329
The current example stores each side of the book as a `Vec<OrderEntry>`
13301330
sorted by price. That's fine for a teaching example with a few dozen
1331-
resting orders. For a production CLOB it's wrong, and the reason is
1331+
resting orders. For a production order book it's wrong, and the reason is
13321332
worth understanding before the "Zero-copy slabs" bullet below.
13331333

13341334
**Tree balancing must be guaranteed, not assumed.** A plain binary
13351335
search tree only keeps a roughly-balanced shape when its inputs arrive
1336-
in random order. In a CLOB an attacker chooses the inputs — the prices
1336+
in random order. In an order book an attacker chooses the inputs — the prices
13371337
of their orders — so nothing they choose can be allowed to determine
13381338
the tree's shape. A *balanced-by-construction* tree (red-black,
13391339
critbit / binary radix trie, AVL, …) enforces a bounded shape via

defi/order-book/anchor/TERMINOLOGY.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Terminology Rules — CLOB
1+
# Terminology Rules — Order Book
22

33
Project-wide rules for the README and code comments in this crate. Applies
44
throughout, not just one section. Audit for these before opening / merging
@@ -15,7 +15,7 @@ A wrong or ambiguous statement is worse than no statement.
1515

1616
### "balance" — most important
1717

18-
`balance` is ambiguous in a CLOB context: it can mean token balance,
18+
`balance` is ambiguous in an order-book context: it can mean token balance,
1919
account balance, **or** the tree-balancing property (the critbit
2020
slab is balanced-by-construction). Pick one of:
2121

defi/order-book/anchor/programs/order-book/src/state/matching.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ pub struct Fill {
2929
pub fill_quantity: u64,
3030

3131
/// Price at which the fill clears. Always the resting (maker) order's
32-
/// price — standard CLOB rule: maker's posted price wins; the taker
32+
/// price — standard order-book rule: maker's posted price wins; the taker
3333
/// gets price improvement vs their limit on bids, and a higher payout
3434
/// vs their limit on asks. Also the high 64 bits of the tree key when
3535
/// we look the leaf up again at apply time.

defi/order-book/anchor/programs/order-book/src/state/slab/nodes.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
// MIT-licensed. See LICENSE-OPENBOOK in this directory.
33
//
44
// Trimmed from the upstream nodes.rs:
5-
// - dropped oracle-pegged price helpers (this CLOB is fixed-price only)
5+
// - dropped oracle-pegged price helpers (this order book is fixed-price only)
66
// - dropped time-in-force / expiry tracking (no IOC/post-only here)
77
// - dropped client_order_id and owner_slot (the on-chain `Order` PDA
88
// already owns that bookkeeping)

defi/order-book/anchor/programs/order-book/src/state/slab/ordertree.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -245,7 +245,7 @@ impl OrderTreeNodes {
245245
/// Insert `new_leaf` into the tree rooted at `root`.
246246
///
247247
/// Returns the handle of the new leaf and, when a duplicate key collided,
248-
/// the leaf that got overwritten. (Callers in this CLOB embed a
248+
/// the leaf that got overwritten. (Callers in this order book embed a
249249
/// monotonically increasing seq_num in every key, so collisions cannot
250250
/// actually happen — the case is kept just to match the upstream API.)
251251
pub fn insert_leaf(

defi/order-book/anchor/programs/order-book/tests/test_order_book.rs

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
//! LiteSVM tests for the CLOB program.
1+
//! LiteSVM tests for the order-book program.
22
//!
33
//! Covers the full lifecycle that the program supports: initialise a market,
44
//! create user accounts, place bids/asks (locking the appropriate vault),
@@ -152,7 +152,7 @@ fn full_setup() -> Scenario {
152152
let quote_mint = create_token_mint(&mut svm, &authority, MINT_DECIMALS, None).unwrap();
153153

154154
// Create and fund every trader's ATAs up-front so individual tests do
155-
// not need to worry about mint/ATA side effects, only about CLOB state.
155+
// not need to worry about mint/ATA side effects, only about order-book state.
156156
let buyer_base_ata =
157157
create_associated_token_account(&mut svm, &buyer.pubkey(), &base_mint, &payer).unwrap();
158158
let buyer_quote_ata =
@@ -219,7 +219,7 @@ fn full_setup() -> Scenario {
219219

220220
/// Build the `system_program::CreateAccount` instruction the client must run
221221
/// to allocate the ~180 KB OrderBook account before calling
222-
/// `initialize_market`. The new account is owned by the CLOB program and
222+
/// `initialize_market`. The new account is owned by the order-book program and
223223
/// zero-initialized; the program then runs `load_init` against it in the
224224
/// next instruction.
225225
///
@@ -331,7 +331,7 @@ fn build_place_order_ix(
331331
}
332332

333333
/// Build a `place_order` instruction with maker (order, market_user) PDA
334-
/// pairs appended as remaining accounts. The CLOB expects them in the same
334+
/// pairs appended as remaining accounts. The order-book program expects them in the same
335335
/// order the resting book will be walked — best-priced first (lowest ask
336336
/// for a taker bid, highest bid for a taker ask), and within a price level
337337
/// earliest-first. Every maker pair must be writable: the program mutates

0 commit comments

Comments
 (0)