feat: add quote_lot_size for full decimal generality

Adopts the Serum/Openbook two-lot model. Previously the program was only
correct when d_base >= d_quote (e.g. NVDAx/USDC), because quote amounts
were computed as price × quantity raw quote tokens with no scaling on the
quote side.

With quote_lot_size, all raw-quote amounts become:
  raw_quote = price × quantity × quote_lot_size

Choosing base_lot_size = 10^max(d_base - d_quote, 0) and
        quote_lot_size = 10^max(d_quote - d_base, 0)
makes price the human-readable quote/base rate and tick_size=1 one atomic
price increment regardless of which mint has more decimals.

NVDAx (8 dec) / USDC (6 dec): base_lot_size=100, quote_lot_size=1 (values unchanged)
WBTC  (8 dec) / HD-USDC (18 dec): base_lot_size=1, quote_lot_size=10^10

Changes: InvalidQuoteLotSize error; quote_lot_size field on Market; new
param in initialize_market; bid lock, gross_quote, and locked_for_this_fill
in place_order all gain x quote_lot_size; bid cancel refund in cancel_order
gains x quote_lot_size; settle_funds untouched (already operates on raw
amounts in unsettled_*). Tests add QUOTE_LOT_SIZE=1, update all call sites
and assertions, add rejection test for zero quote_lot_size.

https://claude.ai/code/session_01G6iaAjzg8aoFwe8ZWWG9VR

Author: claude

defi/order-book/anchor/programs/order-book/src/errors.rs

@@ -26,6 +26,9 @@ pub enum ErrorCode {
     #[msg("Base lot size must be greater than zero")]
     InvalidBaseLotSize,
 
+    #[msg("Quote lot size must be greater than zero")]
+    InvalidQuoteLotSize,
+
     #[msg("Quantity is below minimum order size")]
     BelowMinOrderSize,
 

defi/order-book/anchor/programs/order-book/src/instructions/cancel_order.rs

@@ -27,14 +27,13 @@ pub fn handle_cancel_order(context: Context<CancelOrder>) -> Result<()> {
         let market_user = &mut context.accounts.market_user;
         match order.side {
             OrderSide::Bid => {
-                // u128 intermediate: the lock was originally taken on a
-                // u64 quote balance, so price * remaining must fit u64
-                // — but the multiplication itself can transiently exceed
-                // u64. Mirror the same pattern as place_order: widen,
-                // multiply, narrow.
+                // u128 intermediates mirror the bid-lock formula in place_order:
+                // raw_quote = price × remaining × quote_lot_size
                 let quote_amount: u64 = (order.price as u128)
                     .checked_mul(remaining as u128)
                     .ok_or(ErrorCode::NumericalOverflow)?
+                    .checked_mul(context.accounts.market.quote_lot_size as u128)
+                    .ok_or(ErrorCode::NumericalOverflow)?
                     .try_into()
                     .map_err(|_| error!(ErrorCode::NumericalOverflow))?;
                 market_user.unsettled_quote = market_user

defi/order-book/anchor/programs/order-book/src/instructions/initialize_market.rs

@@ -13,10 +13,12 @@ pub fn handle_initialize_market(
     fee_basis_points: u16,
     tick_size: u64,
     base_lot_size: u64,
+    quote_lot_size: u64,
     min_order_size: u64,
 ) -> Result<()> {
     require!(tick_size > 0, ErrorCode::InvalidTickSize);
     require!(base_lot_size > 0, ErrorCode::InvalidBaseLotSize);
+    require!(quote_lot_size > 0, ErrorCode::InvalidQuoteLotSize);
     require!(min_order_size > 0, ErrorCode::BelowMinOrderSize);
     require!(
         fee_basis_points <= MAX_FEE_BASIS_POINTS,
@@ -34,6 +36,7 @@ pub fn handle_initialize_market(
     market.fee_basis_points = fee_basis_points;
     market.tick_size = tick_size;
     market.base_lot_size = base_lot_size;
+    market.quote_lot_size = quote_lot_size;
     market.min_order_size = min_order_size;
     market.is_active = true;
     market.bump = context.bumps.market;

defi/order-book/anchor/programs/order-book/src/instructions/place_order.rs

@@ -67,6 +67,8 @@ pub fn handle_place_order<'info>(
                 (price as u128)
                     .checked_mul(quantity as u128)
                     .ok_or(ErrorCode::NumericalOverflow)?
+                    .checked_mul(market.quote_lot_size as u128)
+                    .ok_or(ErrorCode::NumericalOverflow)?
                     .try_into()
                     .map_err(|_| error!(ErrorCode::NumericalOverflow))?,
                 context.accounts.quote_vault.to_account_info(),
@@ -194,6 +196,8 @@ pub fn handle_place_order<'info>(
         let gross_quote: u64 = (fill.fill_price as u128)
             .checked_mul(fill.fill_quantity as u128)
             .ok_or(ErrorCode::NumericalOverflow)?
+            .checked_mul(market.quote_lot_size as u128)
+            .ok_or(ErrorCode::NumericalOverflow)?
             .try_into()
             .map_err(|_| error!(ErrorCode::NumericalOverflow))?;
 
@@ -239,6 +243,8 @@ pub fn handle_place_order<'info>(
                 let locked_for_this_fill: u64 = (price as u128)
                     .checked_mul(fill.fill_quantity as u128)
                     .ok_or(ErrorCode::NumericalOverflow)?
+                    .checked_mul(market.quote_lot_size as u128)
+                    .ok_or(ErrorCode::NumericalOverflow)?
                     .try_into()
                     .map_err(|_| error!(ErrorCode::NumericalOverflow))?;
                 let rebate: u64 = locked_for_this_fill

defi/order-book/anchor/programs/order-book/src/lib.rs

@@ -20,13 +20,15 @@ pub mod order_book {
         fee_basis_points: u16,
         tick_size: u64,
         base_lot_size: u64,
+        quote_lot_size: u64,
         min_order_size: u64,
     ) -> Result<()> {
         instructions::initialize_market::handle_initialize_market(
             context,
             fee_basis_points,
             tick_size,
             base_lot_size,
+            quote_lot_size,
             min_order_size,
         )
     }

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

@@ -31,19 +31,35 @@ pub struct Market {
 
     pub tick_size: u64,
 
-    // Number of raw base-token units per lot. Quantities throughout the
-    // program are in lots; this factor converts them to raw token units for
-    // SPL transfers. For a base mint with d_base decimals and quote with
-    // d_quote, set base_lot_size = 10^(d_base - d_quote) so that one raw
-    // quote unit buys exactly one lot of base at price = 1, making `price`
-    // equal to the human-readable USDC-per-token rate.
+    // Two-lot model (mirrors Serum/Openbook): both sides of the book are
+    // denominated in their respective lots rather than raw token units.
+    // This makes `price` and `quantity` human-readable regardless of the
+    // individual mints' decimal counts.
     //
-    // Example — NVDAx (8 dec) / USDC (6 dec):
-    //   base_lot_size = 10^(8-6) = 100 raw NVDAx per lot
-    //   price = 130  →  $130.00 per NVDAx share
-    //   tick_size = 1  →  $1.00 minimum price increment
+    //   raw_base  = quantity  × base_lot_size
+    //   raw_quote = quantity  × price × quote_lot_size
+    //
+    // Choose:
+    //   base_lot_size  = 10^max(d_base  − d_quote, 0)
+    //   quote_lot_size = 10^max(d_quote − d_base,  0)
+    //
+    // so that exactly one of the two is > 1 (or both are 1 when d_base == d_quote).
+    // With those values `price` equals the human-readable quote/base rate and
+    // `tick_size = 1` is a single atomic increment.
+    //
+    // Examples:
+    //   NVDAx (8 dec) / USDC (6 dec):  base_lot_size=100, quote_lot_size=1
+    //     price=130, qty=1 lot  → 130 × 1 × 1 = 130 raw USDC per 100 raw NVDAx
+    //     = $130.00 per NVDAx share ✓
+    //
+    //   WBTC (8 dec) / HD-USDC (18 dec): base_lot_size=1, quote_lot_size=10^10
+    //     price=60_000, qty=1 satoshi-lot → 60_000 × 1 × 10^10 = 6×10^14 raw HD-USDC
+    //     = $60,000 per BTC ✓
     pub base_lot_size: u64,
 
+    // Raw quote-token units per quote lot. See base_lot_size comment above.
+    pub quote_lot_size: u64,
+
     pub min_order_size: u64,
 
     pub is_active: bool,

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

@@ -43,20 +43,20 @@ const MARKET_USER_SEED: &[u8] = b"market_user";
 // `#[account(zero)]` check fails if the account size is wrong.
 const ORDER_BOOK_ACCOUNT_SIZE: u64 = order_book::state::ORDER_BOOK_ACCOUNT_SIZE as u64;
 
-// NVDAx has 8 decimals on-chain; USDC has 6. Because the program stores
-// price as raw_quote per raw_base, one tick = 10^(base_dec - quote_dec) = 100
-// USDC/share — the minimum representable price step with these two mints.
+// NVDAx has 8 decimals on-chain; USDC has 6.
 const BASE_DECIMALS: u8 = 8; // NVDAx (https://explorer.solana.com/address/Xsc9qvGR1efVDFGLrVsmkzv3qi45LTBjeUKSPmx9qEh)
 const QUOTE_DECIMALS: u8 = 6; // USDC
 
-// Market parameters used across every test. `tick_size = 1` and
-// `base_lot_size = 100` match the NVDAx/USDC decimal configuration
-// (BASE_DECIMALS=8, QUOTE_DECIMALS=6): price = human USDC/share,
-// tick = $1.00, 1 lot = 100 raw NVDAx. A dedicated test overrides
-// tick_size to verify the tick check fires.
+// Two-lot model for NVDAx/USDC (d_base=8, d_quote=6):
+//   base_lot_size  = 10^max(8-6, 0) = 100   → 1 lot = 100 raw NVDAx
+//   quote_lot_size = 10^max(6-8, 0) = 1     → 1 quote-lot = 1 raw USDC
+//   raw_base  = quantity × 100
+//   raw_quote = price    × quantity × 1    (= human USDC/share × lots)
+//   tick_size = 1  →  $1.00 minimum price increment
 const FEE_BASIS_POINTS: u16 = 10;
 const TICK_SIZE: u64 = 1;
 const BASE_LOT_SIZE: u64 = 100;
+const QUOTE_LOT_SIZE: u64 = 1;
 const MIN_ORDER_SIZE: u64 = 1;
 
 // Funding for each trader's token accounts. Large enough to cover every
@@ -254,6 +254,7 @@ fn build_initialize_market_ix(
     fee_basis_points: u16,
     tick_size: u64,
     base_lot_size: u64,
+    quote_lot_size: u64,
     min_order_size: u64,
 ) -> Instruction {
     Instruction::new_with_bytes(
@@ -262,6 +263,7 @@ fn build_initialize_market_ix(
             fee_basis_points,
             tick_size,
             base_lot_size,
+            quote_lot_size,
             min_order_size,
         }
         .data(),
@@ -454,7 +456,7 @@ fn initialize_market_and_users(sc: &mut Scenario) {
     // program, zero-initialized) before initialize_market's `#[account(zero)]`
     // check passes.
     let create_ix = build_create_order_book_account_ix(sc, &sc.authority.pubkey());
-    let init_ix = build_initialize_market_ix(sc, FEE_BASIS_POINTS, TICK_SIZE, BASE_LOT_SIZE, MIN_ORDER_SIZE);
+    let init_ix = build_initialize_market_ix(sc, FEE_BASIS_POINTS, TICK_SIZE, BASE_LOT_SIZE, QUOTE_LOT_SIZE, MIN_ORDER_SIZE);
     send_transaction_from_instructions(
         &mut sc.svm,
         vec![create_ix, init_ix],
@@ -497,7 +499,7 @@ fn initialize_market_sets_market_and_order_book() {
     let mut sc = full_setup();
 
     let create_ix = build_create_order_book_account_ix(&sc, &sc.authority.pubkey());
-    let ix = build_initialize_market_ix(&sc, FEE_BASIS_POINTS, TICK_SIZE, BASE_LOT_SIZE, MIN_ORDER_SIZE);
+    let ix = build_initialize_market_ix(&sc, FEE_BASIS_POINTS, TICK_SIZE, BASE_LOT_SIZE, QUOTE_LOT_SIZE, MIN_ORDER_SIZE);
     send_transaction_from_instructions(
         &mut sc.svm,
         vec![create_ix, ix],
@@ -545,7 +547,7 @@ fn create_market_user_tracks_market_and_owner() {
     let mut sc = full_setup();
 
     let create_ix = build_create_order_book_account_ix(&sc, &sc.authority.pubkey());
-    let init_ix = build_initialize_market_ix(&sc, FEE_BASIS_POINTS, TICK_SIZE, BASE_LOT_SIZE, MIN_ORDER_SIZE);
+    let init_ix = build_initialize_market_ix(&sc, FEE_BASIS_POINTS, TICK_SIZE, BASE_LOT_SIZE, QUOTE_LOT_SIZE, MIN_ORDER_SIZE);
     send_transaction_from_instructions(
         &mut sc.svm,
         vec![create_ix, init_ix],
@@ -597,8 +599,8 @@ fn place_bid_locks_quote_in_vault() {
     send_transaction_from_instructions(&mut sc.svm, vec![ix], &[&sc.buyer], &sc.buyer.pubkey())
         .unwrap();
 
-    // A bid locks price * quantity in the quote vault.
-    let locked_quote = BID_PRICE * BID_QUANTITY;
+    // A bid locks price * quantity * quote_lot_size raw quote tokens.
+    let locked_quote = BID_PRICE * BID_QUANTITY * QUOTE_LOT_SIZE;
     assert_eq!(
         get_token_account_balance(&sc.svm, &sc.quote_vault.pubkey()).unwrap(),
         locked_quote
@@ -693,7 +695,7 @@ fn place_order_rejects_unaligned_tick() {
     let unusual_tick_size: u64 = 50;
     let create_ix = build_create_order_book_account_ix(&sc, &sc.authority.pubkey());
     let init_ix =
-        build_initialize_market_ix(&sc, FEE_BASIS_POINTS, unusual_tick_size, BASE_LOT_SIZE, MIN_ORDER_SIZE);
+        build_initialize_market_ix(&sc, FEE_BASIS_POINTS, unusual_tick_size, BASE_LOT_SIZE, QUOTE_LOT_SIZE, MIN_ORDER_SIZE);
     send_transaction_from_instructions(
         &mut sc.svm,
         vec![create_ix, init_ix],
@@ -750,7 +752,7 @@ fn place_order_rejects_below_min_order_size() {
     let elevated_min_order_size: u64 = 10;
     let create_ix = build_create_order_book_account_ix(&sc, &sc.authority.pubkey());
     let init_ix =
-        build_initialize_market_ix(&sc, FEE_BASIS_POINTS, TICK_SIZE, BASE_LOT_SIZE, elevated_min_order_size);
+        build_initialize_market_ix(&sc, FEE_BASIS_POINTS, TICK_SIZE, BASE_LOT_SIZE, QUOTE_LOT_SIZE, elevated_min_order_size);
     send_transaction_from_instructions(
         &mut sc.svm,
         vec![create_ix, init_ix],
@@ -1087,7 +1089,7 @@ fn initialize_market_rejects_zero_tick_size() {
 
     let zero_tick_size: u64 = 0;
     let create_ix = build_create_order_book_account_ix(&sc, &sc.authority.pubkey());
-    let ix = build_initialize_market_ix(&sc, FEE_BASIS_POINTS, zero_tick_size, BASE_LOT_SIZE, MIN_ORDER_SIZE);
+    let ix = build_initialize_market_ix(&sc, FEE_BASIS_POINTS, zero_tick_size, BASE_LOT_SIZE, QUOTE_LOT_SIZE, MIN_ORDER_SIZE);
     let result = send_transaction_from_instructions(
         &mut sc.svm,
         vec![create_ix, ix],
@@ -1108,7 +1110,7 @@ fn initialize_market_rejects_zero_base_lot_size() {
     let mut sc = full_setup();
 
     let create_ix = build_create_order_book_account_ix(&sc, &sc.authority.pubkey());
-    let ix = build_initialize_market_ix(&sc, FEE_BASIS_POINTS, TICK_SIZE, 0, MIN_ORDER_SIZE);
+    let ix = build_initialize_market_ix(&sc, FEE_BASIS_POINTS, TICK_SIZE, 0, QUOTE_LOT_SIZE, MIN_ORDER_SIZE);
     let result = send_transaction_from_instructions(
         &mut sc.svm,
         vec![create_ix, ix],
@@ -1124,6 +1126,27 @@ fn initialize_market_rejects_zero_base_lot_size() {
     assert!(result.is_err(), "base_lot_size == 0 must be rejected");
 }
 
+#[test]
+fn initialize_market_rejects_zero_quote_lot_size() {
+    let mut sc = full_setup();
+
+    let create_ix = build_create_order_book_account_ix(&sc, &sc.authority.pubkey());
+    let ix = build_initialize_market_ix(&sc, FEE_BASIS_POINTS, TICK_SIZE, BASE_LOT_SIZE, 0, MIN_ORDER_SIZE);
+    let result = send_transaction_from_instructions(
+        &mut sc.svm,
+        vec![create_ix, ix],
+        &[
+            &sc.authority,
+            &sc.order_book,
+            &sc.base_vault,
+            &sc.quote_vault,
+            &sc.fee_vault,
+        ],
+        &sc.authority.pubkey(),
+    );
+    assert!(result.is_err(), "quote_lot_size == 0 must be rejected");
+}
+
 #[test]
 fn initialize_market_rejects_oversized_fee() {
     let mut sc = full_setup();
@@ -1136,6 +1159,7 @@ fn initialize_market_rejects_oversized_fee() {
         over_cap_fee_basis_points,
         TICK_SIZE,
         BASE_LOT_SIZE,
+        QUOTE_LOT_SIZE,
         MIN_ORDER_SIZE,
     );
     let result = send_transaction_from_instructions(
@@ -1238,7 +1262,7 @@ fn taker_bid_fully_crosses_best_ask() {
     // that trader starting balances easily cover it.
     const PRICE: u64 = 1000;
     const QUANTITY: u64 = 100;
-    const EXPECTED_GROSS_QUOTE: u64 = PRICE * QUANTITY;
+    const EXPECTED_GROSS_QUOTE: u64 = PRICE * QUANTITY * QUOTE_LOT_SIZE;
     const EXPECTED_FEE: u64 = EXPECTED_GROSS_QUOTE * FEE_BASIS_POINTS as u64 / 10_000;
     const EXPECTED_NET_TO_MAKER: u64 = EXPECTED_GROSS_QUOTE - EXPECTED_FEE;
 
@@ -1316,7 +1340,7 @@ fn taker_ask_fully_crosses_best_bid() {
     const MAKER_BID_ID: u64 = 1;
     const PRICE: u64 = 1000;
     const QUANTITY: u64 = 100;
-    const EXPECTED_GROSS_QUOTE: u64 = PRICE * QUANTITY;
+    const EXPECTED_GROSS_QUOTE: u64 = PRICE * QUANTITY * QUOTE_LOT_SIZE;
     const EXPECTED_FEE: u64 = EXPECTED_GROSS_QUOTE * FEE_BASIS_POINTS as u64 / 10_000;
     const EXPECTED_NET_TO_TAKER: u64 = EXPECTED_GROSS_QUOTE - EXPECTED_FEE;
 
@@ -1618,14 +1642,13 @@ fn taker_crosses_multiple_resting_orders_best_price_first() {
     assert_eq!(buyer_base, TAKER_BID_QUANTITY * BASE_LOT_SIZE);
 
     // Price-improvement rebate: taker locked at 1000/unit but 30 units
-    // filled at 900. Rebate = (1000 - 900) * 30 = 3_000.
-    const PRICE_IMPROVEMENT_REBATE: u64 = (TAKER_BID_PRICE - BEST_ASK_PRICE) * BEST_ASK_QUANTITY;
+    // filled at 900. Rebate = (1000 - 900) * 30 * quote_lot_size.
+    const PRICE_IMPROVEMENT_REBATE: u64 = (TAKER_BID_PRICE - BEST_ASK_PRICE) * BEST_ASK_QUANTITY * QUOTE_LOT_SIZE;
     assert_eq!(buyer_quote_rebate, PRICE_IMPROVEMENT_REBATE);
 
-    // Seller's net unsettled_quote = sum of (fill_price * fill_qty - fee)
-    // across both fills.
-    let gross_one: u64 = BEST_ASK_PRICE * BEST_ASK_QUANTITY;
-    let gross_two: u64 = SECOND_ASK_PRICE * SECOND_ASK_QUANTITY;
+    // Seller's net unsettled_quote = sum of (fill_price * fill_qty * quote_lot_size - fee).
+    let gross_one: u64 = BEST_ASK_PRICE * BEST_ASK_QUANTITY * QUOTE_LOT_SIZE;
+    let gross_two: u64 = SECOND_ASK_PRICE * SECOND_ASK_QUANTITY * QUOTE_LOT_SIZE;
     let fee_one: u64 = gross_one * FEE_BASIS_POINTS as u64 / 10_000;
     let fee_two: u64 = gross_two * FEE_BASIS_POINTS as u64 / 10_000;
     let expected_seller_quote = (gross_one - fee_one) + (gross_two - fee_two);
@@ -1783,16 +1806,15 @@ fn taker_bid_gets_price_improvement_from_resting_ask() {
     .unwrap();
 
     // Maker got 900-per-unit (minus fee), not 1000.
-    let gross_to_maker: u64 = MAKER_ASK_PRICE * QUANTITY;
+    let gross_to_maker: u64 = MAKER_ASK_PRICE * QUANTITY * QUOTE_LOT_SIZE;
     let fee: u64 = gross_to_maker * FEE_BASIS_POINTS as u64 / 10_000;
     let expected_net_to_maker: u64 = gross_to_maker - fee;
     let (_, seller_quote) = read_user_unsettled(&sc.svm, &sc.seller_market_user);
     assert_eq!(seller_quote, expected_net_to_maker);
 
-    // Taker locked (TAKER_BID_PRICE * QUANTITY) of quote up front; only
-    // (MAKER_ASK_PRICE * QUANTITY) was spent. The difference is the
-    // price-improvement rebate.
-    let expected_rebate: u64 = (TAKER_BID_PRICE - MAKER_ASK_PRICE) * QUANTITY;
+    // Taker locked (TAKER_BID_PRICE * QUANTITY * QUOTE_LOT_SIZE) up front;
+    // only (MAKER_ASK_PRICE * QUANTITY * QUOTE_LOT_SIZE) was spent.
+    let expected_rebate: u64 = (TAKER_BID_PRICE - MAKER_ASK_PRICE) * QUANTITY * QUOTE_LOT_SIZE;
     let (buyer_base, buyer_quote) = read_user_unsettled(&sc.svm, &sc.buyer_market_user);
     assert_eq!(buyer_base, QUANTITY * BASE_LOT_SIZE);
     assert_eq!(buyer_quote, expected_rebate);
@@ -1808,7 +1830,7 @@ fn fee_vault_receives_exactly_bps_of_taker_gross() {
     const MAKER_ASK_ID: u64 = 1;
     const PRICE: u64 = 500;
     const QUANTITY: u64 = 200;
-    const GROSS: u64 = PRICE * QUANTITY;
+    const GROSS: u64 = PRICE * QUANTITY * QUOTE_LOT_SIZE;
     const EXPECTED_FEE: u64 = GROSS * FEE_BASIS_POINTS as u64 / 10_000;
 
     let __ix5 = build_place_order_ix(
@@ -1865,7 +1887,7 @@ fn authority_can_withdraw_fees_after_match() {
     const MAKER_ASK_ID: u64 = 1;
     const PRICE: u64 = 2000;
     const QUANTITY: u64 = 50;
-    const GROSS: u64 = PRICE * QUANTITY;
+    const GROSS: u64 = PRICE * QUANTITY * QUOTE_LOT_SIZE;
     const EXPECTED_FEE: u64 = GROSS * FEE_BASIS_POINTS as u64 / 10_000;
 
     let __ix7 = build_place_order_ix(
@@ -1934,7 +1956,7 @@ fn settle_funds_after_match_pays_out_both_unsettled_balances() {
     const MAKER_ASK_ID: u64 = 1;
     const PRICE: u64 = 1000;
     const QUANTITY: u64 = 100;
-    const GROSS: u64 = PRICE * QUANTITY;
+    const GROSS: u64 = PRICE * QUANTITY * QUOTE_LOT_SIZE;
     const EXPECTED_FEE: u64 = GROSS * FEE_BASIS_POINTS as u64 / 10_000;
     const EXPECTED_NET_QUOTE_TO_SELLER: u64 = GROSS - EXPECTED_FEE;