1use std::{
19 cmp::Ordering,
20 collections::{BTreeMap, HashMap},
21 fmt::{Debug, Display},
22};
23
24use nautilus_core::{
25 UnixNanos,
26 correctness::{CorrectnessError, CorrectnessResult},
27};
28
29use crate::{
30 data::order::{BookOrder, OrderId},
31 enums::{BookType, OrderSide, RecordFlag},
32 orderbook::BookLevel,
33 types::{Price, Quantity},
34};
35
36#[derive(Clone, Copy, Debug, Eq)]
48#[cfg_attr(
49 feature = "python",
50 pyo3::pyclass(module = "nautilus_trader.model", from_py_object)
51)]
52pub struct BookPrice {
53 pub value: Price,
54 pub side: OrderSide,
55}
56
57impl BookPrice {
58 #[must_use]
60 pub fn new(value: Price, side: OrderSide) -> Self {
61 Self { value, side }
62 }
63}
64
65impl PartialOrd for BookPrice {
66 fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
67 Some(self.cmp(other))
68 }
69}
70
71impl PartialEq for BookPrice {
72 fn eq(&self, other: &Self) -> bool {
73 self.side == other.side && self.value == other.value
74 }
75}
76
77impl Ord for BookPrice {
78 fn cmp(&self, other: &Self) -> Ordering {
79 assert_eq!(
80 self.side, other.side,
81 "BookPrice compared across sides: {:?} vs {:?}",
82 self.side, other.side
83 );
84
85 match self.side {
86 OrderSide::Buy => other.value.cmp(&self.value),
87 OrderSide::Sell => self.value.cmp(&other.value),
88 }
89 }
90}
91
92impl Display for BookPrice {
93 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
94 write!(f, "{}", self.value)
95 }
96}
97
98#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
107#[repr(u8)]
108enum L1BatchState {
109 #[default]
111 None = 0,
112 MbpBatch = 1,
114 SnapshotBatch = 2,
116}
117
118#[derive(Clone, Debug)]
120pub(crate) struct BookLadder {
121 pub side: OrderSide,
122 pub book_type: BookType,
123 pub levels: BTreeMap<BookPrice, BookLevel>,
124 pub cache: HashMap<u64, BookPrice>,
128 batch_state: L1BatchState,
129}
130
131impl BookLadder {
132 #[must_use]
134 pub(crate) fn new(side: OrderSide, book_type: BookType) -> Self {
135 Self {
136 side,
137 book_type,
138 levels: BTreeMap::new(),
139 cache: HashMap::new(),
140 batch_state: L1BatchState::None,
141 }
142 }
143
144 #[must_use]
146 pub(crate) fn len(&self) -> usize {
147 self.levels.len()
148 }
149
150 #[must_use]
152 #[allow(dead_code)]
153 pub(crate) fn is_empty(&self) -> bool {
154 self.levels.is_empty()
155 }
156
157 #[must_use]
158 pub(crate) fn batch_state_code(&self) -> u8 {
159 self.batch_state as u8
160 }
161
162 pub(crate) fn set_batch_state_code(&mut self, code: u8) -> CorrectnessResult<()> {
168 let batch_state = match code {
169 0 => L1BatchState::None,
170 1 => L1BatchState::MbpBatch,
171 2 => L1BatchState::SnapshotBatch,
172 _ => {
173 return Err(CorrectnessError::PredicateViolation {
174 message: format!("Invalid L1 batch state code: {code}"),
175 });
176 }
177 };
178
179 if self.book_type != BookType::L1_MBP && batch_state != L1BatchState::None {
180 return Err(CorrectnessError::PredicateViolation {
181 message: format!(
182 "Cannot restore L1 batch state for book type {:?}",
183 self.book_type
184 ),
185 });
186 }
187
188 self.batch_state = batch_state;
189 Ok(())
190 }
191
192 pub(crate) fn clear(&mut self) {
196 self.levels.clear();
197 self.cache.clear();
198 self.batch_state = L1BatchState::None;
199 }
200
201 pub(crate) fn replace_l1(&mut self, order: BookOrder) {
202 debug_assert_eq!(self.book_type, BookType::L1_MBP);
203
204 let reusable_level = self.levels.pop_first().map(|(_, level)| level);
205 self.clear();
206
207 if !order.size.is_positive() {
208 let side = self.side;
209 log::debug!("L1 zero-size add cleared ladder: side={side:?}");
210 return;
211 }
212
213 let book_price = order.to_book_price();
214 self.cache.insert(order.order_id, book_price);
215
216 if let Some(mut level) = reusable_level {
217 level.price = book_price;
218
219 let same_id = level.orders.len() == 1
222 && level
223 .orders
224 .get_index(0)
225 .is_some_and(|(id, _)| *id == order.order_id);
226
227 if same_id {
228 let (_, existing) = level
229 .orders
230 .get_index_mut(0)
231 .expect("single L1 order exists");
232 *existing = order;
233 } else {
234 level.orders.clear();
235 level.add(order);
236 }
237
238 self.levels.insert(book_price, level);
239 } else {
240 self.levels.insert(book_price, BookLevel::from_order(order));
241 }
242 }
243
244 pub(crate) fn add(&mut self, order: BookOrder, flags: u8) {
260 if self.book_type == BookType::L1_MBP && !self.handle_l1_add(&order, flags) {
261 return;
262 }
263
264 if self.book_type != BookType::L1_MBP && !order.size.is_positive() {
265 log::warn!(
266 "Attempted to add order with non-positive size: order_id={}, size={}, ignoring",
267 order.order_id,
268 order.size,
269 );
270 return;
271 }
272
273 let book_price = order.to_book_price();
274
275 if self.book_type != BookType::L1_MBP
276 && let Some(existing_price) = self.cache.get(&order.order_id).copied()
277 && existing_price != book_price
278 && let Some(existing_level) = self.levels.get_mut(&existing_price)
279 {
280 existing_level.delete(&order);
281 if existing_level.is_empty() {
282 self.levels.remove(&existing_price);
283 }
284 }
285
286 self.cache.insert(order.order_id, book_price);
287
288 if let Some(level) = self.levels.get_mut(&book_price) {
289 level.add(order);
290 } else {
291 let level = BookLevel::from_order(order);
292 self.levels.insert(book_price, level);
293 }
294
295 let is_batch = RecordFlag::F_MBP.matches(flags) || RecordFlag::F_SNAPSHOT.matches(flags);
298 if self.book_type == BookType::L1_MBP && is_batch {
299 self.retain_best_only();
300
301 if RecordFlag::F_LAST.matches(flags) {
302 self.batch_state = L1BatchState::None;
303 }
304 }
305 }
306
307 fn handle_l1_add(&mut self, order: &BookOrder, flags: u8) -> bool {
323 if !order.size.is_positive() {
324 self.clear();
325 let side = self.side;
326 log::debug!("L1 zero-size add cleared ladder: side={side:?}");
327 return false;
328 }
329
330 let is_mbp = RecordFlag::F_MBP.matches(flags);
331 let is_snapshot = RecordFlag::F_SNAPSHOT.matches(flags);
332 let is_last = RecordFlag::F_LAST.matches(flags);
333
334 if is_snapshot && is_last {
335 if self.batch_state != L1BatchState::SnapshotBatch {
339 self.clear();
340 }
341 } else if is_snapshot {
342 if self.batch_state != L1BatchState::SnapshotBatch {
344 self.clear();
345 self.batch_state = L1BatchState::SnapshotBatch;
346 }
347 } else if is_mbp && is_last {
348 if self.batch_state != L1BatchState::MbpBatch {
350 self.clear();
351 }
352 } else if is_mbp {
353 self.clear();
355 self.batch_state = L1BatchState::MbpBatch;
356 } else {
357 self.clear();
359 }
360
361 true
362 }
363
364 pub(crate) fn update(&mut self, order: BookOrder, flags: u8) {
366 let price = self.cache.get(&order.order_id).copied();
367 if let Some(price) = price
368 && let Some(level) = self.levels.get_mut(&price)
369 {
370 if order.price == level.price.value {
371 let level_len_before = level.len();
372 level.update(order);
373
374 if order.size.is_zero() {
376 self.cache.remove(&order.order_id);
377 debug_assert_eq!(
378 level.len(),
379 level_len_before - 1,
380 "Level should have one less order after zero-size update"
381 );
382 } else {
383 debug_assert!(
384 self.cache.contains_key(&order.order_id),
385 "Cache should still contain order {0} after update",
386 order.order_id
387 );
388 }
389
390 if level.is_empty() {
391 self.levels.remove(&price);
392 debug_assert!(
393 !self.cache.values().any(|p| *p == price),
394 "Cache should not contain removed price level {price:?}"
395 );
396 }
397
398 debug_assert_eq!(
399 self.cache.len(),
400 self.levels.values().map(BookLevel::len).sum::<usize>(),
401 "Cache size should equal total orders across all levels"
402 );
403 return;
404 }
405
406 self.cache.remove(&order.order_id);
408 level.delete(&order);
409
410 if level.is_empty() {
411 self.levels.remove(&price);
412 debug_assert!(
413 !self.cache.values().any(|p| *p == price),
414 "Cache should not contain removed price level {price:?}"
415 );
416 }
417 }
418
419 if order.size.is_positive() {
421 self.add(order, flags);
422 }
423
424 debug_assert_eq!(
426 self.cache.len(),
427 self.levels.values().map(BookLevel::len).sum::<usize>(),
428 "Cache size should equal total orders across all levels"
429 );
430 }
431
432 pub(crate) fn delete(&mut self, order: BookOrder, sequence: u64, ts_event: UnixNanos) {
434 self.remove_order(order.order_id, sequence, ts_event);
435 }
436
437 pub(crate) fn remove_order(&mut self, order_id: OrderId, sequence: u64, ts_event: UnixNanos) {
439 if let Some(price) = self.cache.get(&order_id).copied()
440 && let Some(level) = self.levels.get_mut(&price)
441 {
442 if level.orders.contains_key(&order_id) {
444 let level_len_before = level.len();
445
446 self.cache.remove(&order_id);
448 level.remove_by_id(order_id, sequence, ts_event);
449
450 debug_assert_eq!(
451 level.len(),
452 level_len_before - 1,
453 "Level should have exactly one less order after removal"
454 );
455
456 if level.is_empty() {
457 self.levels.remove(&price);
458 debug_assert!(
459 !self.cache.values().any(|p| *p == price),
460 "Cache should not contain removed price level {price:?}"
461 );
462 }
463 }
464 }
465
466 debug_assert_eq!(
468 self.cache.len(),
469 self.levels.values().map(BookLevel::len).sum::<usize>(),
470 "Cache size should equal total orders across all levels"
471 );
472 }
473
474 pub(crate) fn remove_level(&mut self, price: BookPrice) -> Option<BookLevel> {
476 if let Some(level) = self.levels.remove(&price) {
477 for order_id in level.orders.keys() {
479 self.cache.remove(order_id);
480 }
481
482 debug_assert_eq!(
483 self.cache.len(),
484 self.levels.values().map(BookLevel::len).sum::<usize>(),
485 "Cache size should equal total orders across all levels"
486 );
487
488 Some(level)
489 } else {
490 None
491 }
492 }
493
494 fn retain_best_only(&mut self) {
500 if self.levels.len() <= 1 {
501 return;
502 }
503
504 let best_price = match self.levels.keys().next().copied() {
505 Some(price) => price,
506 None => return,
507 };
508
509 self.levels.retain(|price, _| *price == best_price);
512
513 self.cache.clear();
516
517 for (book_price, level) in &self.levels {
518 for order_id in level.orders.keys() {
519 self.cache.insert(*order_id, *book_price);
520 }
521 }
522
523 debug_assert!(
524 self.levels.len() <= 1,
525 "L1 ladder should have at most 1 level after retain_best_only"
526 );
527 debug_assert_eq!(
528 self.cache.len(),
529 self.levels.values().map(BookLevel::len).sum::<usize>(),
530 "Cache size should equal total orders across all levels"
531 );
532 }
533
534 #[must_use]
536 #[allow(dead_code)]
537 pub(crate) fn sizes(&self) -> f64 {
538 self.levels.values().map(BookLevel::size).sum()
539 }
540
541 #[must_use]
543 #[allow(dead_code)]
544 pub(crate) fn exposures(&self) -> f64 {
545 self.levels.values().map(BookLevel::exposure).sum()
546 }
547
548 #[must_use]
550 pub(crate) fn top(&self) -> Option<&BookLevel> {
551 self.levels.values().next()
552 }
553
554 #[must_use]
557 pub(crate) fn simulate_fills(&self, order: &BookOrder) -> Vec<(Price, Quantity)> {
558 let is_reversed = self.side == OrderSide::Buy;
559 let mut fills = Vec::new();
560 let mut cumulative_denominator = Quantity::zero(order.size.precision);
561 let target = order.size;
562
563 for level in self.levels.values() {
564 if (is_reversed && level.price.value < order.price)
565 || (!is_reversed && level.price.value > order.price)
566 {
567 break;
568 }
569
570 for book_order in level.orders.values() {
571 let current = book_order.size;
572 let remainder = target - cumulative_denominator;
573 if current >= remainder {
574 if remainder.is_positive() {
576 fills.push((book_order.price, remainder));
577 }
578 return fills;
579 }
580
581 fills.push((book_order.price, current));
583 cumulative_denominator = cumulative_denominator + current;
584 }
585 }
586
587 fills
588 }
589}
590
591impl Display for BookLadder {
592 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
593 writeln!(f, "{}(side={})", stringify!(BookLadder), self.side)?;
594 for (price, level) in &self.levels {
595 writeln!(f, " {} -> {} orders", price, level.len())?;
596 }
597 Ok(())
598 }
599}
600
601#[cfg(test)]
602impl BookLadder {
603 pub(crate) fn add_bulk(&mut self, orders: &[BookOrder]) {
605 for order in orders {
606 self.add(*order, 0);
607 }
608 }
609}
610
611#[cfg(test)]
612mod tests {
613 use nautilus_core::correctness::CorrectnessError;
614 use rstest::rstest;
615
616 use crate::{
617 data::order::BookOrder,
618 enums::{BookType, OrderSide, RecordFlag},
619 orderbook::{
620 ladder::{BookLadder, BookPrice},
621 level::BookLevel,
622 },
623 types::{Price, Quantity},
624 };
625
626 #[rstest]
627 fn test_is_empty_after_add() {
628 let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L3_MBO);
629 assert!(ladder.is_empty(), "Ladder should start empty");
630 let order = BookOrder::new(OrderSide::Buy, Price::from("10.00"), Quantity::from(100), 1);
631 ladder.add(order, 0);
632 assert!(
633 !ladder.is_empty(),
634 "Ladder should not be empty after adding an order"
635 );
636 }
637
638 #[rstest]
639 fn test_add_bulk_empty() {
640 let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L3_MBO);
641 ladder.add_bulk(&[]);
642 assert!(
643 ladder.is_empty(),
644 "Adding an empty vector should leave the ladder empty"
645 );
646 }
647
648 #[rstest]
649 fn test_add_bulk_orders() {
650 let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L3_MBO);
651 let orders = [
652 BookOrder::new(OrderSide::Buy, Price::from("10.00"), Quantity::from(20), 1),
653 BookOrder::new(OrderSide::Buy, Price::from("10.00"), Quantity::from(30), 2),
654 BookOrder::new(OrderSide::Buy, Price::from("10.00"), Quantity::from(50), 3),
655 ];
656 ladder.add_bulk(&orders);
657 assert_eq!(ladder.len(), 1, "Ladder should have one price level");
659 let orders_in_level = ladder.top().unwrap().get_orders();
660 assert_eq!(
661 orders_in_level.len(),
662 3,
663 "Price level should contain all bulk orders"
664 );
665 }
666
667 #[rstest]
668 #[case::bid(OrderSide::Buy, "4.0")]
669 #[case::ask(OrderSide::Sell, "1.0")]
670 fn test_book_price_sorting(#[case] side: OrderSide, #[case] expected_top: &str) {
671 let mut prices = [
672 BookPrice::new(Price::from("2.0"), side),
673 BookPrice::new(Price::from("4.0"), side),
674 BookPrice::new(Price::from("1.0"), side),
675 BookPrice::new(Price::from("3.0"), side),
676 ];
677
678 prices.sort();
679
680 assert_eq!(prices[0].value, Price::from(expected_top));
681 }
682
683 #[rstest]
684 fn test_add_single_order() {
685 let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L3_MBO);
686 let order = BookOrder::new(OrderSide::Buy, Price::from("10.00"), Quantity::from(20), 0);
687
688 ladder.add(order, 0);
689 assert_eq!(ladder.len(), 1);
690 assert_eq!(ladder.sizes(), 20.0);
691 assert_eq!(ladder.exposures(), 200.0);
692 assert_eq!(ladder.top().unwrap().price.value, Price::from("10.0"));
693 }
694
695 #[rstest]
696 fn test_add_multiple_buy_orders() {
697 let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L3_MBO);
698 let order1 = BookOrder::new(OrderSide::Buy, Price::from("10.00"), Quantity::from(20), 0);
699 let order2 = BookOrder::new(OrderSide::Buy, Price::from("9.00"), Quantity::from(30), 1);
700 let order3 = BookOrder::new(OrderSide::Buy, Price::from("9.00"), Quantity::from(50), 2);
701 let order4 = BookOrder::new(OrderSide::Buy, Price::from("8.00"), Quantity::from(200), 3);
702
703 ladder.add_bulk(&[order1, order2, order3, order4]);
704 assert_eq!(ladder.len(), 3);
705 assert_eq!(ladder.sizes(), 300.0);
706 assert_eq!(ladder.exposures(), 2520.0);
707 assert_eq!(ladder.top().unwrap().price.value, Price::from("10.0"));
708 }
709
710 #[rstest]
711 fn test_add_multiple_sell_orders() {
712 let mut ladder = BookLadder::new(OrderSide::Sell, BookType::L3_MBO);
713 let order1 = BookOrder::new(OrderSide::Sell, Price::from("11.00"), Quantity::from(20), 0);
714 let order2 = BookOrder::new(OrderSide::Sell, Price::from("12.00"), Quantity::from(30), 1);
715 let order3 = BookOrder::new(OrderSide::Sell, Price::from("12.00"), Quantity::from(50), 2);
716 let order4 = BookOrder::new(
717 OrderSide::Sell,
718 Price::from("13.00"),
719 Quantity::from(200),
720 3,
721 );
722
723 ladder.add_bulk(&[order1, order2, order3, order4]);
724 assert_eq!(ladder.len(), 3);
725 assert_eq!(ladder.sizes(), 300.0);
726 assert_eq!(ladder.exposures(), 3780.0);
727 assert_eq!(ladder.top().unwrap().price.value, Price::from("11.0"));
728 }
729
730 #[rstest]
731 fn test_add_to_same_price_level() {
732 let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L3_MBO);
733 let order1 = BookOrder::new(OrderSide::Buy, Price::from("10.00"), Quantity::from(20), 1);
734 let order2 = BookOrder::new(OrderSide::Buy, Price::from("10.00"), Quantity::from(30), 2);
735
736 ladder.add(order1, 0);
737 ladder.add(order2, 0);
738
739 assert_eq!(ladder.len(), 1);
740 assert_eq!(ladder.sizes(), 50.0);
741 assert_eq!(ladder.exposures(), 500.0);
742 }
743
744 #[rstest]
745 #[case::bid(OrderSide::Buy, "9.00", "8.00", "9.00")]
746 #[case::ask(OrderSide::Sell, "8.00", "9.00", "8.00")]
747 fn test_add_orders_preserves_top(
748 #[case] side: OrderSide,
749 #[case] first_price: &str,
750 #[case] second_price: &str,
751 #[case] expected_top: &str,
752 ) {
753 let mut ladder = BookLadder::new(side, BookType::L3_MBO);
754 let order1 = BookOrder::new(side, Price::from(first_price), Quantity::from(20), 1);
755 let order2 = BookOrder::new(side, Price::from(second_price), Quantity::from(30), 2);
756
757 ladder.add(order1, 0);
758 ladder.add(order2, 0);
759
760 assert_eq!(ladder.top().unwrap().price.value, Price::from(expected_top));
761 }
762
763 #[rstest]
764 #[case::bid(OrderSide::Buy)]
765 #[case::ask(OrderSide::Sell)]
766 fn test_update_order_price(#[case] side: OrderSide) {
767 let mut ladder = BookLadder::new(side, BookType::L3_MBO);
768 let order = BookOrder::new(side, Price::from("11.00"), Quantity::from(20), 1);
769
770 ladder.add(order, 0);
771 let order = BookOrder::new(side, Price::from("11.10"), Quantity::from(20), 1);
772
773 ladder.update(order, 0);
774 assert_eq!(ladder.len(), 1);
775 assert_eq!(ladder.sizes(), 20.0);
776 assert_eq!(ladder.exposures(), 222.0);
777 assert_eq!(ladder.top().unwrap().price.value, Price::from("11.1"));
778 }
779
780 #[rstest]
781 #[case::bid(OrderSide::Buy)]
782 #[case::ask(OrderSide::Sell)]
783 fn test_update_order_size(#[case] side: OrderSide) {
784 let mut ladder = BookLadder::new(side, BookType::L3_MBO);
785 let order = BookOrder::new(side, Price::from("11.00"), Quantity::from(20), 1);
786
787 ladder.add(order, 0);
788 let order = BookOrder::new(side, Price::from("11.00"), Quantity::from(10), 1);
789
790 ladder.update(order, 0);
791 assert_eq!(ladder.len(), 1);
792 assert_eq!(ladder.sizes(), 10.0);
793 assert_eq!(ladder.exposures(), 110.0);
794 assert_eq!(ladder.top().unwrap().price.value, Price::from("11.0"));
795 }
796
797 #[rstest]
798 fn test_delete_non_existing_order() {
799 let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L3_MBO);
800 let order = BookOrder::new(OrderSide::Buy, Price::from("10.00"), Quantity::from(20), 1);
801
802 ladder.delete(order, 0, 0.into());
803
804 assert_eq!(ladder.len(), 0);
805 }
806
807 #[rstest]
808 #[case::bid(OrderSide::Buy, "11.00", "20", "10")]
809 #[case::ask(OrderSide::Sell, "10.00", "10", "10")]
810 fn test_delete_order(
811 #[case] side: OrderSide,
812 #[case] price: &str,
813 #[case] stored_size: &str,
814 #[case] delete_size: &str,
815 ) {
816 let mut ladder = BookLadder::new(side, BookType::L3_MBO);
817 let order = BookOrder::new(side, Price::from(price), Quantity::from(stored_size), 1);
818
819 ladder.add(order, 0);
820 let delete = BookOrder::new(side, Price::from(price), Quantity::from(delete_size), 1);
821
822 ladder.delete(delete, 0, 0.into());
823 assert_eq!(ladder.len(), 0);
824 assert_eq!(ladder.sizes(), 0.0);
825 assert_eq!(ladder.exposures(), 0.0);
826 assert_eq!(ladder.top(), None);
827 }
828
829 #[rstest]
830 fn test_ladder_totals_empty() {
831 let ladder = BookLadder::new(OrderSide::Buy, BookType::L3_MBO);
832 assert_eq!(ladder.sizes(), 0.0);
833 assert_eq!(ladder.exposures(), 0.0);
834 }
835
836 #[rstest]
837 fn test_ladder_totals() {
838 let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L3_MBO);
839 let order1 = BookOrder::new(OrderSide::Buy, Price::from("10.00"), Quantity::from(20), 1);
840 let order2 = BookOrder::new(OrderSide::Buy, Price::from("9.50"), Quantity::from(30), 2);
841 ladder.add(order1, 0);
842 ladder.add(order2, 0);
843
844 let expected_size = 20.0 + 30.0;
845 let expected_exposure = 10.00 * 20.0 + 9.50 * 30.0;
846
847 assert_eq!(ladder.sizes(), expected_size);
848 assert_eq!(ladder.exposures(), expected_exposure);
849 }
850
851 #[rstest]
852 fn test_iter_returns_fifo() {
853 let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L3_MBO);
854 let order1 = BookOrder::new(OrderSide::Buy, Price::from("10.00"), Quantity::from(20), 1);
855 let order2 = BookOrder::new(OrderSide::Buy, Price::from("10.00"), Quantity::from(30), 2);
856 ladder.add(order1, 0);
857 ladder.add(order2, 0);
858 let orders: Vec<BookOrder> = ladder.top().unwrap().iter().copied().collect();
859 assert_eq!(
860 orders,
861 vec![order1, order2],
862 "Iterator should return orders in FIFO order"
863 );
864 }
865
866 #[rstest]
867 fn test_update_missing_order_inserts() {
868 let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L3_MBO);
869 let order = BookOrder::new(OrderSide::Buy, Price::from("10.00"), Quantity::from(20), 1);
870 ladder.update(order, 0);
872 assert_eq!(
873 ladder.len(),
874 1,
875 "Ladder should have one level after upsert update"
876 );
877 let orders = ladder.top().unwrap().get_orders();
878 assert_eq!(
879 orders.len(),
880 1,
881 "Price level should contain the inserted order"
882 );
883 assert_eq!(orders[0], order, "The inserted order should match");
884 }
885
886 #[rstest]
887 fn test_cache_consistency_after_operations() {
888 let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L3_MBO);
889 let order1 = BookOrder::new(OrderSide::Buy, Price::from("10.00"), Quantity::from(20), 1);
890 let order2 = BookOrder::new(OrderSide::Buy, Price::from("9.00"), Quantity::from(30), 2);
891 ladder.add(order1, 0);
892 ladder.add(order2, 0);
893
894 for (order_id, price) in &ladder.cache {
896 let level = ladder
897 .levels
898 .get(price)
899 .expect("Every price in the cache should have a corresponding level");
900 assert!(
901 level.orders.contains_key(order_id),
902 "Order id {order_id} should be present in the level for price {price}",
903 );
904 }
905 }
906
907 #[rstest]
908 fn test_simulate_fills_with_empty_book() {
909 let ladder = BookLadder::new(OrderSide::Buy, BookType::L3_MBO);
910 let order = BookOrder::new(OrderSide::Buy, Price::max(2), Quantity::from(500), 1);
911
912 let fills = ladder.simulate_fills(&order);
913
914 assert!(fills.is_empty());
915 }
916
917 #[rstest]
918 #[case(OrderSide::Buy, Price::max(2), OrderSide::Sell)]
919 #[case(OrderSide::Sell, Price::min(2), OrderSide::Buy)]
920 fn test_simulate_order_fills_with_no_size(
921 #[case] side: OrderSide,
922 #[case] price: Price,
923 #[case] ladder_side: OrderSide,
924 ) {
925 let ladder = BookLadder::new(ladder_side, BookType::L3_MBO);
926 let order = BookOrder {
927 price, size: Quantity::from(500),
929 side: side.into(),
930 order_id: 2,
931 };
932
933 let fills = ladder.simulate_fills(&order);
934
935 assert!(fills.is_empty());
936 }
937
938 #[rstest]
939 #[case(OrderSide::Buy, OrderSide::Sell, Price::from("60.0"))]
940 #[case(OrderSide::Sell, OrderSide::Buy, Price::from("40.0"))]
941 fn test_simulate_order_fills_buy_when_far_from_market(
942 #[case] order_side: OrderSide,
943 #[case] ladder_side: OrderSide,
944 #[case] ladder_price: Price,
945 ) {
946 let mut ladder = BookLadder::new(ladder_side, BookType::L3_MBO);
947
948 ladder.add(
949 BookOrder {
950 price: ladder_price,
951 size: Quantity::from(100),
952 side: ladder_side.into(),
953 order_id: 1,
954 },
955 0,
956 );
957
958 let order = BookOrder {
959 price: Price::from("50.00"),
960 size: Quantity::from(500),
961 side: order_side.into(),
962 order_id: 2,
963 };
964
965 let fills = ladder.simulate_fills(&order);
966
967 assert!(fills.is_empty());
968 }
969
970 #[rstest]
971 fn test_simulate_order_fills_sell_when_far_from_market() {
972 let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L3_MBO);
973
974 ladder.add(
975 BookOrder {
976 price: Price::from("100.00"),
977 size: Quantity::from(100),
978 side: OrderSide::Buy.into(),
979 order_id: 1,
980 },
981 0,
982 );
983
984 let order = BookOrder {
985 price: Price::from("150.00"), size: Quantity::from(500),
987 side: OrderSide::Buy.into(),
988 order_id: 2,
989 };
990
991 let fills = ladder.simulate_fills(&order);
992
993 assert!(fills.is_empty());
994 }
995
996 #[rstest]
997 fn test_simulate_order_fills_buy() {
998 let mut ladder = BookLadder::new(OrderSide::Sell, BookType::L3_MBO);
999
1000 ladder.add_bulk(&[
1001 BookOrder {
1002 price: Price::from("100.00"),
1003 size: Quantity::from(100),
1004 side: OrderSide::Sell.into(),
1005 order_id: 1,
1006 },
1007 BookOrder {
1008 price: Price::from("101.00"),
1009 size: Quantity::from(200),
1010 side: OrderSide::Sell.into(),
1011 order_id: 2,
1012 },
1013 BookOrder {
1014 price: Price::from("102.00"),
1015 size: Quantity::from(400),
1016 side: OrderSide::Sell.into(),
1017 order_id: 3,
1018 },
1019 ]);
1020
1021 let order = BookOrder {
1022 price: Price::max(2), size: Quantity::from(500),
1024 side: OrderSide::Buy.into(),
1025 order_id: 4,
1026 };
1027
1028 let fills = ladder.simulate_fills(&order);
1029
1030 assert_eq!(fills.len(), 3);
1031
1032 let (price1, size1) = fills[0];
1033 assert_eq!(price1, Price::from("100.00"));
1034 assert_eq!(size1, Quantity::from(100));
1035
1036 let (price2, size2) = fills[1];
1037 assert_eq!(price2, Price::from("101.00"));
1038 assert_eq!(size2, Quantity::from(200));
1039
1040 let (price3, size3) = fills[2];
1041 assert_eq!(price3, Price::from("102.00"));
1042 assert_eq!(size3, Quantity::from(200));
1043 }
1044
1045 #[rstest]
1046 fn test_simulate_order_fills_sell() {
1047 let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L3_MBO);
1048
1049 ladder.add_bulk(&[
1050 BookOrder {
1051 price: Price::from("102.00"),
1052 size: Quantity::from(100),
1053 side: OrderSide::Buy.into(),
1054 order_id: 1,
1055 },
1056 BookOrder {
1057 price: Price::from("101.00"),
1058 size: Quantity::from(200),
1059 side: OrderSide::Buy.into(),
1060 order_id: 2,
1061 },
1062 BookOrder {
1063 price: Price::from("100.00"),
1064 size: Quantity::from(400),
1065 side: OrderSide::Buy.into(),
1066 order_id: 3,
1067 },
1068 ]);
1069
1070 let order = BookOrder {
1071 price: Price::min(2), size: Quantity::from(500),
1073 side: OrderSide::Sell.into(),
1074 order_id: 4,
1075 };
1076
1077 let fills = ladder.simulate_fills(&order);
1078
1079 assert_eq!(fills.len(), 3);
1080
1081 let (price1, size1) = fills[0];
1082 assert_eq!(price1, Price::from("102.00"));
1083 assert_eq!(size1, Quantity::from(100));
1084
1085 let (price2, size2) = fills[1];
1086 assert_eq!(price2, Price::from("101.00"));
1087 assert_eq!(size2, Quantity::from(200));
1088
1089 let (price3, size3) = fills[2];
1090 assert_eq!(price3, Price::from("100.00"));
1091 assert_eq!(size3, Quantity::from(200));
1092 }
1093
1094 #[rstest]
1095 fn test_simulate_order_fills_sell_with_size_at_limit_of_precision() {
1096 let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L3_MBO);
1097
1098 ladder.add_bulk(&[
1099 BookOrder {
1100 price: Price::from("102.00"),
1101 size: Quantity::from("100.000000000"),
1102 side: OrderSide::Buy.into(),
1103 order_id: 1,
1104 },
1105 BookOrder {
1106 price: Price::from("101.00"),
1107 size: Quantity::from("200.000000000"),
1108 side: OrderSide::Buy.into(),
1109 order_id: 2,
1110 },
1111 BookOrder {
1112 price: Price::from("100.00"),
1113 size: Quantity::from("400.000000000"),
1114 side: OrderSide::Buy.into(),
1115 order_id: 3,
1116 },
1117 ]);
1118
1119 let order = BookOrder {
1120 price: Price::min(2), size: Quantity::from("699.999999999"), side: OrderSide::Sell.into(),
1123 order_id: 4,
1124 };
1125
1126 let fills = ladder.simulate_fills(&order);
1127
1128 assert_eq!(fills.len(), 3);
1129
1130 let (price1, size1) = fills[0];
1131 assert_eq!(price1, Price::from("102.00"));
1132 assert_eq!(size1, Quantity::from("100.000000000"));
1133
1134 let (price2, size2) = fills[1];
1135 assert_eq!(price2, Price::from("101.00"));
1136 assert_eq!(size2, Quantity::from("200.000000000"));
1137
1138 let (price3, size3) = fills[2];
1139 assert_eq!(price3, Price::from("100.00"));
1140 assert_eq!(size3, Quantity::from("399.999999999"));
1141 }
1142
1143 #[rstest]
1144 fn test_boundary_prices() {
1145 let max_price = Price::max(1);
1146 let min_price = Price::min(1);
1147
1148 let mut ladder_buy = BookLadder::new(OrderSide::Buy, BookType::L3_MBO);
1149 let mut ladder_sell = BookLadder::new(OrderSide::Sell, BookType::L3_MBO);
1150
1151 let order_buy = BookOrder::new(OrderSide::Buy, min_price, Quantity::from(1), 1);
1152 let order_sell = BookOrder::new(OrderSide::Sell, max_price, Quantity::from(1), 1);
1153
1154 ladder_buy.add(order_buy, 0);
1155 ladder_sell.add(order_sell, 0);
1156
1157 assert_eq!(ladder_buy.top().unwrap().price.value, min_price);
1158 assert_eq!(ladder_sell.top().unwrap().price.value, max_price);
1159 }
1160
1161 #[rstest]
1162 fn test_l1_single_delta_batches_replace_each_other() {
1163 let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L1_MBP);
1166 let side_constant = OrderSide::Buy as u64;
1167
1168 let batch_flags = RecordFlag::F_MBP as u8 | RecordFlag::F_LAST as u8;
1170
1171 let order1 = BookOrder {
1173 side: OrderSide::Buy.into(),
1174 price: Price::from("100.00"),
1175 size: Quantity::from(50),
1176 order_id: side_constant,
1177 };
1178 ladder.add(order1, batch_flags);
1179
1180 assert_eq!(ladder.len(), 1, "Should have one level after first add");
1181 assert_eq!(
1182 ladder.top().unwrap().price.value,
1183 Price::from("100.00"),
1184 "Top level should be at 100.00"
1185 );
1186
1187 let order2 = BookOrder {
1188 side: OrderSide::Buy.into(),
1189 price: Price::from("101.00"),
1190 size: Quantity::from(60),
1191 order_id: side_constant,
1192 };
1193 ladder.add(order2, batch_flags);
1194
1195 assert_eq!(ladder.len(), 1, "Should have only one level");
1196 assert_eq!(
1197 ladder.top().unwrap().price.value,
1198 Price::from("101.00"),
1199 "Top level should be at 101.00"
1200 );
1201
1202 let order3 = BookOrder {
1204 side: OrderSide::Buy.into(),
1205 price: Price::from("100.50"),
1206 size: Quantity::from(70),
1207 order_id: side_constant,
1208 };
1209 ladder.add(order3, batch_flags);
1210
1211 assert_eq!(ladder.len(), 1, "Should have only one level");
1212 assert_eq!(
1213 ladder.top().unwrap().price.value,
1214 Price::from("100.50"),
1215 "Top level should be at 100.50 (new batch replaced old)"
1216 );
1217 }
1218
1219 #[rstest]
1220 fn test_l2_orders_create_multiple_levels() {
1221 let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L2_MBP);
1222
1223 let order1 = BookOrder {
1224 side: OrderSide::Buy.into(),
1225 price: Price::from("100.00"),
1226 size: Quantity::from(50),
1227 order_id: Price::from("100.00").raw() as u64,
1228 };
1229 ladder.add(order1, 0);
1230
1231 let order2 = BookOrder {
1232 side: OrderSide::Buy.into(),
1233 price: Price::from("99.00"),
1234 size: Quantity::from(60),
1235 order_id: Price::from("99.00").raw() as u64,
1236 };
1237 ladder.add(order2, 0);
1238
1239 assert_eq!(ladder.len(), 2, "L2 orders should create multiple levels");
1240 assert_eq!(
1241 ladder.top().unwrap().price.value,
1242 Price::from("100.00"),
1243 "Top level should be best bid"
1244 );
1245 }
1246
1247 #[rstest]
1248 fn test_zero_size_l1_order_clears_top() {
1249 let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L1_MBP);
1251 let side_constant = OrderSide::Buy as u64;
1252
1253 let order1 = BookOrder {
1254 side: OrderSide::Buy.into(),
1255 price: Price::from("100.00"),
1256 size: Quantity::from(50),
1257 order_id: side_constant,
1258 };
1259 ladder.add(order1, 0);
1260
1261 assert_eq!(ladder.len(), 1);
1262 assert_eq!(ladder.top().unwrap().price.value, Price::from("100.00"));
1263 assert!(ladder.top().unwrap().first().is_some());
1264
1265 let order2 = BookOrder {
1267 side: OrderSide::Buy.into(),
1268 price: Price::from("101.00"),
1269 size: Quantity::zero(9), order_id: side_constant,
1271 };
1272 ladder.add(order2, 0);
1273
1274 assert_eq!(ladder.len(), 0, "Zero-size L1 add should clear the book");
1276 assert!(ladder.top().is_none(), "Book should be empty after clear");
1277
1278 assert!(
1280 ladder.cache.is_empty(),
1281 "Cache should be empty after L1 clear"
1282 );
1283 }
1284
1285 #[rstest]
1286 fn test_zero_size_order_to_empty_ladder() {
1287 let mut ladder = BookLadder::new(OrderSide::Sell, BookType::L1_MBP);
1289 let side_constant = OrderSide::Sell as u64;
1290
1291 let order = BookOrder {
1292 side: OrderSide::Sell.into(),
1293 price: Price::from("100.00"),
1294 size: Quantity::zero(9),
1295 order_id: side_constant,
1296 };
1297 ladder.add(order, 0);
1298
1299 assert_eq!(ladder.len(), 0, "Empty ladder should remain empty");
1300 assert!(ladder.top().is_none(), "Top should be None");
1301 assert!(
1302 ladder.cache.is_empty(),
1303 "Cache should remain empty for zero-size add"
1304 );
1305 }
1306
1307 #[rstest]
1308 fn test_l3_order_id_collision_moves_order() {
1309 let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L3_MBO);
1310
1311 let order1 = BookOrder {
1313 side: OrderSide::Buy.into(),
1314 price: Price::from("100.00"),
1315 size: Quantity::from(50),
1316 order_id: 1, };
1318 ladder.add(order1, 0);
1319
1320 assert_eq!(ladder.len(), 1);
1321
1322 let order2 = BookOrder {
1323 side: OrderSide::Buy.into(),
1324 price: Price::from("99.00"),
1325 size: Quantity::from(60),
1326 order_id: 1,
1327 };
1328 ladder.add(order2, 0);
1329
1330 assert_eq!(ladder.len(), 1, "Order ID 1 must live at exactly one level");
1331 assert_eq!(
1332 ladder.top().unwrap().price.value,
1333 Price::from("99.00"),
1334 "Order should have moved to 99.00"
1335 );
1336 assert_eq!(
1337 ladder.top().unwrap().first().unwrap().size,
1338 Quantity::from(60),
1339 "Size should come from the re-added order"
1340 );
1341 assert_eq!(
1342 ladder.cache.len(),
1343 1,
1344 "Cache should track exactly one entry for the moved order"
1345 );
1346 }
1347
1348 #[rstest]
1349 fn test_l3_duplicate_order_id_update_and_delete_leave_no_ghost() {
1350 let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L3_MBO);
1351
1352 let order1 = BookOrder {
1353 side: OrderSide::Buy.into(),
1354 price: Price::from("100.00"),
1355 size: Quantity::from(50),
1356 order_id: 1,
1357 };
1358 ladder.add(order1, 0);
1359
1360 let order2 = BookOrder {
1361 side: OrderSide::Buy.into(),
1362 price: Price::from("99.00"),
1363 size: Quantity::from(60),
1364 order_id: 1,
1365 };
1366 ladder.add(order2, 0);
1367
1368 let zero_update = BookOrder {
1369 side: OrderSide::Buy.into(),
1370 price: Price::from("99.00"),
1371 size: Quantity::zero(9),
1372 order_id: 1,
1373 };
1374 ladder.update(zero_update, 0);
1375
1376 assert!(
1377 ladder.is_empty(),
1378 "Zero-size update must not ghost the order"
1379 );
1380 assert!(ladder.cache.is_empty());
1381
1382 ladder.add(order1, 0);
1383 ladder.add(order2, 0);
1384 ladder.delete(order2, 0, 0.into());
1385
1386 assert!(ladder.is_empty(), "Delete must not ghost the order");
1387 assert!(ladder.cache.is_empty());
1388 }
1389
1390 #[rstest]
1391 #[case::bids(OrderSide::Buy, Some(OrderSide::Buy), "100.00", "99.00")]
1392 #[case::asks(OrderSide::Sell, Some(OrderSide::Sell), "100.00", "101.00")]
1393 fn test_move_leaves_other_orders_at_old_level(
1394 #[case] side_spec: OrderSide,
1395 #[case] side: Option<OrderSide>,
1396 #[case] old_price: &str,
1397 #[case] new_price: &str,
1398 #[values(false, true)] via_update: bool,
1399 ) {
1400 let mut ladder = BookLadder::new(side_spec, BookType::L3_MBO);
1401
1402 let moved = BookOrder {
1403 side,
1404 price: Price::from(old_price),
1405 size: Quantity::from(50),
1406 order_id: 1,
1407 };
1408 let staying = BookOrder {
1409 side,
1410 price: Price::from(old_price),
1411 size: Quantity::from(30),
1412 order_id: 2,
1413 };
1414 ladder.add(moved, 0);
1415 ladder.add(staying, 0);
1416
1417 let moved_new = BookOrder {
1418 side,
1419 price: Price::from(new_price),
1420 size: Quantity::from(60),
1421 order_id: 1,
1422 };
1423
1424 if via_update {
1425 ladder.update(moved_new, 0);
1426 } else {
1427 ladder.add(moved_new, 0);
1428 }
1429
1430 assert_eq!(
1431 ladder.len(),
1432 2,
1433 "Old level must survive with the remaining order"
1434 );
1435 let old_level = ladder
1436 .levels
1437 .get(&BookPrice::new(Price::from(old_price), side_spec))
1438 .expect("Old level should remain");
1439 let new_level = ladder
1440 .levels
1441 .get(&BookPrice::new(Price::from(new_price), side_spec))
1442 .expect("New level should exist");
1443
1444 let fields = |level: &BookLevel| {
1446 level
1447 .iter()
1448 .map(|order| (order.order_id, order.price, order.size))
1449 .collect::<Vec<_>>()
1450 };
1451
1452 assert_eq!(
1453 fields(old_level),
1454 vec![(2, Price::from(old_price), Quantity::from(30))]
1455 );
1456 assert_eq!(
1457 fields(new_level),
1458 vec![(1, Price::from(new_price), Quantity::from(60))]
1459 );
1460 assert_eq!(ladder.cache.len(), 2);
1461 assert_eq!(ladder.cache[&1], new_level.price);
1462 assert_eq!(ladder.cache[&2], old_level.price);
1463 }
1464
1465 #[rstest]
1466 fn test_l1_vs_l3_duplicate_order_id_replacement() {
1467 let mut l1_ladder = BookLadder::new(OrderSide::Buy, BookType::L1_MBP);
1469 let side_constant = OrderSide::Buy as u64;
1470
1471 let order1 = BookOrder {
1472 side: OrderSide::Buy.into(),
1473 price: Price::from("100.00"),
1474 size: Quantity::from(50),
1475 order_id: side_constant,
1476 };
1477 l1_ladder.add(order1, 0);
1478
1479 let order2 = BookOrder {
1480 side: OrderSide::Buy.into(),
1481 price: Price::from("101.00"),
1482 size: Quantity::from(60),
1483 order_id: side_constant, };
1485 l1_ladder.add(order2, 0);
1486
1487 assert_eq!(l1_ladder.len(), 1, "L1 should have only 1 level");
1488 assert_eq!(
1489 l1_ladder.top().unwrap().price.value,
1490 Price::from("101.00"),
1491 "L1 should have replaced the old level"
1492 );
1493
1494 let mut l3_ladder = BookLadder::new(OrderSide::Buy, BookType::L3_MBO);
1495
1496 let order3 = BookOrder {
1497 side: OrderSide::Buy.into(),
1498 price: Price::from("100.00"),
1499 size: Quantity::from(50),
1500 order_id: 1, };
1502 l3_ladder.add(order3, 0);
1503
1504 let order4 = BookOrder {
1505 side: OrderSide::Buy.into(),
1506 price: Price::from("101.00"),
1507 size: Quantity::from(60),
1508 order_id: 1,
1509 };
1510 l3_ladder.add(order4, 0);
1511
1512 assert_eq!(
1513 l3_ladder.len(),
1514 1,
1515 "L3 should move the order to its new price level"
1516 );
1517 assert_eq!(
1518 l3_ladder.top().unwrap().price.value,
1519 Price::from("101.00"),
1520 "L3 order should have moved to 101.00"
1521 );
1522 }
1523
1524 #[rstest]
1525 #[case::bids_worst_to_best(OrderSide::Buy, Some(OrderSide::Buy), &["99.00", "100.00", "101.00", "102.00"], "102.00")]
1526 #[case::bids_best_to_worst(OrderSide::Buy, Some(OrderSide::Buy), &["102.00", "101.00", "100.00", "99.00"], "100.00")]
1527 #[case::asks_worst_to_best(OrderSide::Sell, Some(OrderSide::Sell), &["105.00", "104.00", "103.00", "102.00"], "102.00")]
1528 #[case::asks_best_to_worst(OrderSide::Sell, Some(OrderSide::Sell), &["102.00", "103.00", "104.00", "105.00"], "104.00")]
1529 fn test_l1_multi_delta_batch_keeps_best_of_final_two(
1530 #[case] side_spec: OrderSide,
1531 #[case] side: Option<OrderSide>,
1532 #[case] prices: &[&str],
1533 #[case] expected_best: &str,
1534 ) {
1535 let mut ladder = BookLadder::new(side_spec, BookType::L1_MBP);
1538
1539 let batch_size = prices.len();
1540 for (i, price_str) in prices.iter().enumerate() {
1541 let order = BookOrder {
1542 side,
1543 price: Price::from(*price_str),
1544 size: Quantity::from((i + 1) as u64 * 10),
1545 order_id: (i + 100) as u64,
1546 };
1547 let flags = if i == batch_size - 1 {
1548 RecordFlag::F_MBP as u8 | RecordFlag::F_LAST as u8
1549 } else {
1550 RecordFlag::F_MBP as u8
1551 };
1552 ladder.add(order, flags);
1553 }
1554
1555 assert_eq!(ladder.len(), 1, "L1 should have only 1 level");
1556 assert_eq!(
1557 ladder.top().unwrap().price.value,
1558 Price::from(expected_best),
1559 "Should keep best of final two deltas"
1560 );
1561 }
1562
1563 #[rstest]
1564 fn test_l1_retain_best_only_cache_consistency() {
1565 let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L1_MBP);
1567 let batch_flags = RecordFlag::F_MBP as u8 | RecordFlag::F_LAST as u8;
1568 let prices = ["100.00", "101.00", "102.00", "103.00", "104.00"];
1569
1570 for (i, price_str) in prices.iter().enumerate() {
1571 let order = BookOrder {
1572 side: OrderSide::Buy.into(),
1573 price: Price::from(*price_str),
1574 size: Quantity::from(10),
1575 order_id: (i + 1) as u64,
1576 };
1577 ladder.add(order, batch_flags);
1578 }
1579
1580 assert_eq!(ladder.len(), 1);
1581 assert_eq!(
1582 ladder.cache.len(),
1583 1,
1584 "Cache should have exactly 1 entry for L1"
1585 );
1586
1587 let total_orders: usize = ladder.levels.values().map(BookLevel::len).sum();
1588 assert_eq!(
1589 ladder.cache.len(),
1590 total_orders,
1591 "Cache should be consistent with levels"
1592 );
1593 }
1594
1595 #[rstest]
1596 fn test_l1_sequential_replacement_allows_price_degradation() {
1597 let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L1_MBP);
1600 let side_constant = OrderSide::Buy as u64;
1601
1602 let order1 = BookOrder {
1604 side: OrderSide::Buy.into(),
1605 price: Price::from("101.00"),
1606 size: Quantity::from(50),
1607 order_id: side_constant,
1608 };
1609 ladder.add(order1, 0); assert_eq!(ladder.len(), 1);
1612 assert_eq!(
1613 ladder.top().unwrap().price.value,
1614 Price::from("101.00"),
1615 "Should have bid at 101.00"
1616 );
1617
1618 let order2 = BookOrder {
1621 side: OrderSide::Buy.into(),
1622 price: Price::from("100.00"),
1623 size: Quantity::from(60),
1624 order_id: side_constant,
1625 };
1626 ladder.add(order2, 0); assert_eq!(ladder.len(), 1);
1629 assert_eq!(
1630 ladder.top().unwrap().price.value,
1631 Price::from("100.00"),
1632 "Sequential replacement should allow price to degrade from 101 to 100"
1633 );
1634
1635 assert_eq!(
1637 ladder.top().unwrap().first().unwrap().size,
1638 Quantity::from(60),
1639 "Size should be from the new order"
1640 );
1641 }
1642
1643 #[rstest]
1644 #[case::bids(OrderSide::Buy, Some(OrderSide::Buy), &["100.00", "101.00", "102.00"], "102.00", &["97.00", "98.00", "99.00"], "99.00")]
1645 #[case::asks(OrderSide::Sell, Some(OrderSide::Sell), &["100.00", "101.00", "102.00"], "101.00", &["103.00", "104.00", "105.00"], "104.00")]
1646 fn test_l1_consecutive_batches_clear_between(
1647 #[case] side_spec: OrderSide,
1648 #[case] side: Option<OrderSide>,
1649 #[case] batch1_prices: &[&str],
1650 #[case] expected1: &str,
1651 #[case] batch2_prices: &[&str],
1652 #[case] expected2: &str,
1653 ) {
1654 let mut ladder = BookLadder::new(side_spec, BookType::L1_MBP);
1656
1657 for (i, price_str) in batch1_prices.iter().enumerate() {
1659 let order = BookOrder {
1660 side,
1661 price: Price::from(*price_str),
1662 size: Quantity::from(10),
1663 order_id: (i + 100) as u64,
1664 };
1665 let flags = if i == batch1_prices.len() - 1 {
1666 RecordFlag::F_MBP as u8 | RecordFlag::F_LAST as u8
1667 } else {
1668 RecordFlag::F_MBP as u8
1669 };
1670 ladder.add(order, flags);
1671 }
1672
1673 assert_eq!(ladder.len(), 1);
1674 assert_eq!(
1675 ladder.top().unwrap().price.value,
1676 Price::from(expected1),
1677 "After batch 1"
1678 );
1679
1680 for (i, price_str) in batch2_prices.iter().enumerate() {
1682 let order = BookOrder {
1683 side,
1684 price: Price::from(*price_str),
1685 size: Quantity::from(20),
1686 order_id: (i + 200) as u64,
1687 };
1688 let flags = if i == batch2_prices.len() - 1 {
1689 RecordFlag::F_MBP as u8 | RecordFlag::F_LAST as u8
1690 } else {
1691 RecordFlag::F_MBP as u8
1692 };
1693 ladder.add(order, flags);
1694 }
1695
1696 assert_eq!(ladder.len(), 1);
1697 assert_eq!(
1698 ladder.top().unwrap().price.value,
1699 Price::from(expected2),
1700 "After batch 2: batch 1 data cleared"
1701 );
1702 }
1703
1704 #[rstest]
1705 fn test_l1_zero_size_clears_regardless_of_order_id() {
1706 let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L1_MBP);
1709
1710 let batch_flags = RecordFlag::F_MBP as u8 | RecordFlag::F_LAST as u8;
1712 let order = BookOrder {
1713 side: OrderSide::Buy.into(),
1714 price: Price::from("100.00"),
1715 size: Quantity::from(50),
1716 order_id: 12345, };
1718 ladder.add(order, batch_flags);
1719 assert_eq!(ladder.len(), 1);
1720
1721 let clear_order = BookOrder {
1723 side: OrderSide::Buy.into(),
1724 price: Price::from("100.00"),
1725 size: Quantity::zero(9),
1726 order_id: OrderSide::Buy as u64, };
1728 ladder.add(clear_order, 0);
1729
1730 assert_eq!(
1732 ladder.len(),
1733 0,
1734 "Zero-size should clear L1 regardless of order_id"
1735 );
1736 assert!(ladder.cache.is_empty(), "Cache should be empty after clear");
1737 }
1738
1739 #[rstest]
1740 fn test_l1_f_mbp_without_f_last_does_not_accumulate() {
1741 let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L1_MBP);
1744 let flags = RecordFlag::F_MBP as u8; let prices = [
1748 "100.00", "99.00", "98.00", "97.00", "96.00", "95.00", "94.00", "93.00", "92.00",
1749 "91.00",
1750 ];
1751
1752 for (i, price_str) in prices.iter().enumerate() {
1753 let order = BookOrder {
1754 side: OrderSide::Buy.into(),
1755 price: Price::from(*price_str),
1756 size: Quantity::from(10),
1757 order_id: (i + 100) as u64,
1758 };
1759 ladder.add(order, flags);
1760
1761 assert_eq!(
1762 ladder.len(),
1763 1,
1764 "L1 should always have at most 1 level, iteration {i}"
1765 );
1766 }
1767
1768 assert_eq!(
1770 ladder.top().unwrap().price.value,
1771 Price::from("91.00"),
1772 "Should show last price (91), allowing degradation"
1773 );
1774 }
1775
1776 #[rstest]
1777 fn test_l1_f_mbp_two_delta_batch_retains_best() {
1778 let mut ladder = BookLadder::new(OrderSide::Sell, BookType::L1_MBP);
1780
1781 let order1 = BookOrder {
1783 side: OrderSide::Sell.into(),
1784 price: Price::from("100.00"),
1785 size: Quantity::from(10),
1786 order_id: 100,
1787 };
1788 ladder.add(order1, RecordFlag::F_MBP as u8);
1789
1790 let order2 = BookOrder {
1793 side: OrderSide::Sell.into(),
1794 price: Price::from("101.00"),
1795 size: Quantity::from(20),
1796 order_id: 101,
1797 };
1798 ladder.add(order2, RecordFlag::F_MBP as u8 | RecordFlag::F_LAST as u8);
1799
1800 assert_eq!(ladder.len(), 1);
1801 assert_eq!(
1802 ladder.top().unwrap().price.value,
1803 Price::from("100.00"),
1804 "2-delta batch keeps best ask (100) from both deltas"
1805 );
1806 }
1807
1808 #[rstest]
1809 fn test_l1_snapshot_batch_accumulates_all_levels_bids() {
1810 let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L1_MBP);
1812 let prices = ["98.00", "99.00", "100.00", "101.00"];
1813 let batch_size = prices.len();
1814
1815 for (i, price_str) in prices.iter().enumerate() {
1816 let order = BookOrder {
1817 side: OrderSide::Buy.into(),
1818 price: Price::from(*price_str),
1819 size: Quantity::from(10),
1820 order_id: (i + 100) as u64,
1821 };
1822 let flags = if i == batch_size - 1 {
1823 RecordFlag::F_SNAPSHOT as u8 | RecordFlag::F_LAST as u8
1824 } else {
1825 RecordFlag::F_SNAPSHOT as u8
1826 };
1827 ladder.add(order, flags);
1828 }
1829
1830 assert_eq!(
1831 ladder.len(),
1832 1,
1833 "L1 should have only 1 level after snapshot"
1834 );
1835 assert_eq!(
1836 ladder.top().unwrap().price.value,
1837 Price::from("101.00"),
1838 "F_SNAPSHOT batch should keep best bid (101) from ALL deltas"
1839 );
1840 }
1841
1842 #[rstest]
1843 fn test_l1_snapshot_batch_accumulates_all_levels_asks() {
1844 let mut ladder = BookLadder::new(OrderSide::Sell, BookType::L1_MBP);
1846 let prices = ["104.00", "103.00", "102.00", "101.00"];
1847 let batch_size = prices.len();
1848
1849 for (i, price_str) in prices.iter().enumerate() {
1850 let order = BookOrder {
1851 side: OrderSide::Sell.into(),
1852 price: Price::from(*price_str),
1853 size: Quantity::from(10),
1854 order_id: (i + 100) as u64,
1855 };
1856 let flags = if i == batch_size - 1 {
1857 RecordFlag::F_SNAPSHOT as u8 | RecordFlag::F_LAST as u8
1858 } else {
1859 RecordFlag::F_SNAPSHOT as u8
1860 };
1861 ladder.add(order, flags);
1862 }
1863
1864 assert_eq!(
1865 ladder.len(),
1866 1,
1867 "L1 should have only 1 level after snapshot"
1868 );
1869 assert_eq!(
1870 ladder.top().unwrap().price.value,
1871 Price::from("101.00"),
1872 "F_SNAPSHOT batch should keep best ask (101) from ALL deltas"
1873 );
1874 }
1875
1876 #[rstest]
1877 #[case::bids(OrderSide::Buy, ["101.00", "100.00", "99.00"], "101.00")]
1878 #[case::asks(OrderSide::Sell, ["99.00", "100.00", "101.00"], "99.00")]
1879 fn test_l1_snapshot_batch_keeps_best_when_delivered_first(
1880 #[case] side: OrderSide,
1881 #[case] prices: [&str; 3],
1882 #[case] expected_best: &str,
1883 ) {
1884 let mut ladder = BookLadder::new(side, BookType::L1_MBP);
1885 let batch_size = prices.len();
1886
1887 for (i, price_str) in prices.iter().enumerate() {
1888 let order = BookOrder {
1889 side: side.into(),
1890 price: Price::from(*price_str),
1891 size: Quantity::from(10),
1892 order_id: side as u64,
1893 };
1894
1895 let flags = if i == batch_size - 1 {
1896 RecordFlag::F_SNAPSHOT as u8 | RecordFlag::F_LAST as u8
1897 } else {
1898 RecordFlag::F_SNAPSHOT as u8
1899 };
1900
1901 ladder.add(order, flags);
1902 }
1903
1904 assert_eq!(ladder.len(), 1);
1905 assert_eq!(
1906 ladder.top().unwrap().price.value,
1907 Price::from(expected_best)
1908 );
1909 assert_eq!(ladder.cache.len(), 1);
1910 }
1911
1912 #[rstest]
1913 fn test_display() {
1914 let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L3_MBO);
1915 ladder.add_bulk(&[
1916 BookOrder::new(OrderSide::Buy, Price::from("100.00"), Quantity::from(10), 1),
1917 BookOrder::new(OrderSide::Buy, Price::from("100.00"), Quantity::from(20), 2),
1918 BookOrder::new(OrderSide::Buy, Price::from("99.00"), Quantity::from(30), 3),
1919 ]);
1920
1921 assert_eq!(
1922 ladder.to_string(),
1923 "BookLadder(side=BUY)\n 100.00 -> 2 orders\n 99.00 -> 1 orders\n"
1924 );
1925 }
1926
1927 #[rstest]
1928 fn test_batch_state_code_round_trips_on_l1_ladder(#[values(0, 1, 2)] code: u8) {
1929 let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L1_MBP);
1930
1931 ladder.set_batch_state_code(code).unwrap();
1932
1933 assert_eq!(ladder.batch_state_code(), code);
1934 }
1935
1936 #[rstest]
1937 #[case::unknown_code(BookType::L1_MBP, 3, "Invalid L1 batch state code: 3")]
1938 #[case::non_l1_batch(
1939 BookType::L2_MBP,
1940 1,
1941 "Cannot restore L1 batch state for book type L2_MBP"
1942 )]
1943 fn test_set_batch_state_code_rejects_invalid_state(
1944 #[case] book_type: BookType,
1945 #[case] code: u8,
1946 #[case] message: &str,
1947 ) {
1948 let mut ladder = BookLadder::new(OrderSide::Buy, book_type);
1949
1950 let result = ladder.set_batch_state_code(code);
1951
1952 assert_eq!(
1953 result,
1954 Err(CorrectnessError::PredicateViolation {
1955 message: message.to_string(),
1956 })
1957 );
1958 assert_eq!(ladder.batch_state_code(), 0);
1959 }
1960
1961 #[rstest]
1962 fn test_set_batch_state_code_accepts_no_batch_on_non_l1_ladder() {
1963 let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L2_MBP);
1964
1965 assert_eq!(ladder.set_batch_state_code(0), Ok(()));
1966 assert_eq!(ladder.batch_state_code(), 0);
1967 }
1968
1969 #[rstest]
1970 fn test_l1_snapshot_vs_mbp_different_accumulation_behavior() {
1971 let mut mbp_ladder = BookLadder::new(OrderSide::Buy, BookType::L1_MBP);
1973 let prices = ["98.00", "99.00", "100.00", "101.00"];
1974 for (i, price_str) in prices.iter().enumerate() {
1975 let order = BookOrder {
1976 side: OrderSide::Buy.into(),
1977 price: Price::from(*price_str),
1978 size: Quantity::from(10),
1979 order_id: (i + 100) as u64,
1980 };
1981 let flags = if i == prices.len() - 1 {
1982 RecordFlag::F_MBP as u8 | RecordFlag::F_LAST as u8
1983 } else {
1984 RecordFlag::F_MBP as u8
1985 };
1986 mbp_ladder.add(order, flags);
1987 }
1988 assert_eq!(
1989 mbp_ladder.top().unwrap().price.value,
1990 Price::from("101.00"),
1991 "F_MBP keeps best of final two (100, 101)"
1992 );
1993
1994 let mut snapshot_ladder = BookLadder::new(OrderSide::Buy, BookType::L1_MBP);
1995
1996 for (i, price_str) in prices.iter().enumerate() {
1997 let order = BookOrder {
1998 side: OrderSide::Buy.into(),
1999 price: Price::from(*price_str),
2000 size: Quantity::from(10),
2001 order_id: (i + 200) as u64,
2002 };
2003 let flags = if i == prices.len() - 1 {
2004 RecordFlag::F_SNAPSHOT as u8 | RecordFlag::F_LAST as u8
2005 } else {
2006 RecordFlag::F_SNAPSHOT as u8
2007 };
2008 snapshot_ladder.add(order, flags);
2009 }
2010 assert_eq!(
2011 snapshot_ladder.top().unwrap().price.value,
2012 Price::from("101.00"),
2013 "F_SNAPSHOT keeps best of ALL deltas (98, 99, 100, 101)"
2014 );
2015 }
2016
2017 #[rstest]
2018 fn test_l1_snapshot_after_incomplete_mbp_stream() {
2019 let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L1_MBP);
2021
2022 let stale_order = BookOrder {
2024 side: OrderSide::Buy.into(),
2025 price: Price::from("101.00"),
2026 size: Quantity::from(10),
2027 order_id: 100,
2028 };
2029 ladder.add(stale_order, RecordFlag::F_MBP as u8);
2030 assert_eq!(ladder.top().unwrap().price.value, Price::from("101.00"));
2031
2032 ladder.clear();
2034
2035 for (i, price_str) in ["98.00", "99.00", "100.00"].iter().enumerate() {
2037 let order = BookOrder {
2038 side: OrderSide::Buy.into(),
2039 price: Price::from(*price_str),
2040 size: Quantity::from(10),
2041 order_id: (i + 200) as u64,
2042 };
2043 let flags = if i == 2 {
2044 RecordFlag::F_SNAPSHOT as u8 | RecordFlag::F_LAST as u8
2045 } else {
2046 RecordFlag::F_SNAPSHOT as u8
2047 };
2048 ladder.add(order, flags);
2049 }
2050
2051 assert_eq!(
2052 ladder.top().unwrap().price.value,
2053 Price::from("100.00"),
2054 "Snapshot replaces stale MBP state: best is 100, not stale 101"
2055 );
2056 }
2057
2058 #[rstest]
2059 fn test_l1_snapshot_clears_previous_batch() {
2060 let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L1_MBP);
2062
2063 for (i, price_str) in ["100.00", "101.00", "102.00"].iter().enumerate() {
2064 let order = BookOrder {
2065 side: OrderSide::Buy.into(),
2066 price: Price::from(*price_str),
2067 size: Quantity::from(10),
2068 order_id: (i + 100) as u64,
2069 };
2070 let flags = if i == 2 {
2071 RecordFlag::F_SNAPSHOT as u8 | RecordFlag::F_LAST as u8
2072 } else {
2073 RecordFlag::F_SNAPSHOT as u8
2074 };
2075 ladder.add(order, flags);
2076 }
2077 assert_eq!(ladder.top().unwrap().price.value, Price::from("102.00"));
2078
2079 for (i, price_str) in ["95.00", "96.00", "97.00"].iter().enumerate() {
2081 let order = BookOrder {
2082 side: OrderSide::Buy.into(),
2083 price: Price::from(*price_str),
2084 size: Quantity::from(20),
2085 order_id: (i + 200) as u64,
2086 };
2087 let flags = if i == 2 {
2088 RecordFlag::F_SNAPSHOT as u8 | RecordFlag::F_LAST as u8
2089 } else {
2090 RecordFlag::F_SNAPSHOT as u8
2091 };
2092 ladder.add(order, flags);
2093 }
2094 assert_eq!(
2095 ladder.top().unwrap().price.value,
2096 Price::from("97.00"),
2097 "Second batch clears first: best is 97, not 102"
2098 );
2099 }
2100
2101 #[rstest]
2102 fn test_l1_single_delta_snapshot_after_mbp_batch() {
2103 let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L1_MBP);
2105
2106 let mbp_order1 = BookOrder {
2107 side: OrderSide::Buy.into(),
2108 price: Price::from("100.00"),
2109 size: Quantity::from(10),
2110 order_id: 1,
2111 };
2112 let mbp_order2 = BookOrder {
2113 side: OrderSide::Buy.into(),
2114 price: Price::from("101.00"),
2115 size: Quantity::from(10),
2116 order_id: 2,
2117 };
2118 ladder.add(mbp_order1, RecordFlag::F_MBP as u8);
2119 ladder.add(
2120 mbp_order2,
2121 RecordFlag::F_MBP as u8 | RecordFlag::F_LAST as u8,
2122 );
2123
2124 assert_eq!(ladder.top().unwrap().price.value, Price::from("101.00"));
2125
2126 let snapshot_order = BookOrder {
2128 side: OrderSide::Buy.into(),
2129 price: Price::from("95.00"),
2130 size: Quantity::from(20),
2131 order_id: 100,
2132 };
2133 ladder.add(
2134 snapshot_order,
2135 RecordFlag::F_SNAPSHOT as u8 | RecordFlag::F_LAST as u8,
2136 );
2137
2138 assert_eq!(
2139 ladder.top().unwrap().price.value,
2140 Price::from("95.00"),
2141 "Single-delta snapshot clears MBP state: best is 95, not stale 101"
2142 );
2143 assert_eq!(ladder.len(), 1);
2144 }
2145
2146 #[rstest]
2147 fn test_replace_l1_same_id_updates_price_in_place() {
2148 let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L1_MBP);
2149 let first = BookOrder::new(OrderSide::Buy, Price::from("10.00"), Quantity::from(20), 1);
2150 ladder.replace_l1(first);
2151 assert_eq!(ladder.len(), 1);
2152
2153 let second = BookOrder::new(OrderSide::Buy, Price::from("11.00"), Quantity::from(30), 1);
2154 ladder.replace_l1(second);
2155
2156 assert_eq!(ladder.len(), 1);
2157 let top = ladder.top().unwrap();
2158 assert_eq!(top.price.value, Price::from("11.00"));
2159 assert_eq!(top.len(), 1);
2160 let orders = top.get_orders();
2161 assert_eq!(orders.len(), 1);
2162 assert_eq!(orders[0].order_id, 1);
2163 assert_eq!(orders[0].price, Price::from("11.00"));
2164 assert_eq!(orders[0].size, Quantity::from(30));
2165 assert_eq!(ladder.cache.len(), 1);
2166 assert_eq!(ladder.cache.get(&1).unwrap().value, Price::from("11.00"));
2167 }
2168
2169 #[rstest]
2170 fn test_replace_l1_different_id_falls_back_to_clear_and_add() {
2171 let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L1_MBP);
2172 let first = BookOrder::new(OrderSide::Buy, Price::from("10.00"), Quantity::from(20), 1);
2173 ladder.replace_l1(first);
2174
2175 let second = BookOrder::new(OrderSide::Buy, Price::from("11.00"), Quantity::from(30), 2);
2176 ladder.replace_l1(second);
2177
2178 assert_eq!(ladder.len(), 1);
2179 let top = ladder.top().unwrap();
2180 assert_eq!(top.price.value, Price::from("11.00"));
2181 assert_eq!(top.len(), 1);
2182 let orders = top.get_orders();
2183 assert_eq!(orders.len(), 1);
2184 assert_eq!(orders[0].order_id, 2);
2185 assert_eq!(ladder.cache.len(), 1);
2186 assert!(!ladder.cache.contains_key(&1));
2187 assert_eq!(ladder.cache.get(&2).unwrap().value, Price::from("11.00"));
2188 }
2189
2190 #[rstest]
2191 fn test_replace_l1_multi_order_level_falls_back_to_clear_and_add() {
2192 let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L1_MBP);
2193 let price = BookPrice::new(Price::from("10.00"), OrderSide::Buy);
2194 let mut level = BookLevel::new(price);
2195 level.add(BookOrder::new(
2196 OrderSide::Buy,
2197 Price::from("10.00"),
2198 Quantity::from(20),
2199 1,
2200 ));
2201 level.add(BookOrder::new(
2202 OrderSide::Buy,
2203 Price::from("10.00"),
2204 Quantity::from(25),
2205 2,
2206 ));
2207 ladder.levels.insert(price, level);
2208 ladder.cache.insert(1, price);
2209 ladder.cache.insert(2, price);
2210 assert_eq!(ladder.top().unwrap().len(), 2);
2211
2212 let replacement =
2213 BookOrder::new(OrderSide::Buy, Price::from("11.00"), Quantity::from(30), 1);
2214 ladder.replace_l1(replacement);
2215
2216 assert_eq!(ladder.len(), 1);
2217 let top = ladder.top().unwrap();
2218 assert_eq!(top.price.value, Price::from("11.00"));
2219 assert_eq!(top.len(), 1);
2220 let orders = top.get_orders();
2221 assert_eq!(orders.len(), 1);
2222 assert_eq!(orders[0].order_id, 1);
2223 assert_eq!(ladder.cache.len(), 1);
2224 assert_eq!(ladder.cache.get(&1).unwrap().value, Price::from("11.00"));
2225 }
2226}