feat: use decimal instead of native float types and optimize matching order

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "oxide-arbiter"
-version = "0.1.1-beta.2"
+version = "0.2.0-beta.2"
 edition = "2024"
 description = "A CLOB order matching engine with price-time priority, limit/market orders, and four time-in-force policies."
 license = "MIT"
@@ -12,4 +12,5 @@ readme = "README.md"
 [dependencies]
 chrono = "0.4.43"
 ordered-float = "5.1.0"
+rust_decimal = "1.40.0"
 uuid = { version = "1.20.0", features = ["v4"] }

README.md

@@ -28,8 +28,8 @@ oxide-arbiter implements a Centralized Limit Order Book (CLOB) with price-time p
 ```
 orders: HashMap<Uuid, Order>               // source of truth; O(1) lookup by ID
 
-buy_orders:  HashMap<item_id, BTreeMap<OrderedFloat<f32>, VecDeque<Order>>>
-sell_orders: HashMap<item_id, BTreeMap<OrderedFloat<f32>, VecDeque<Order>>>
+buy_orders:  HashMap<item_id, BTreeMap<Decimal, VecDeque<Uuid>>>
+sell_orders: HashMap<item_id, BTreeMap<Decimal, VecDeque<Uuid>>>
 
 trades: Vec<Trade>                          // append-only execution history
 ```
@@ -83,9 +83,9 @@ enum TimeInForce { GTC, IOC, FOK, DAY }
 | `order_side` | `OrderSide` | Buy or Sell |
 | `order_type` | `OrderType` | Limit or Market |
 | `time_in_force` | `TimeInForce` | Execution policy |
-| `price` | `f32` | Limit price (market orders normalized to resting price) |
-| `quantity` | `f32` | Requested quantity |
-| `quantity_filled` | `f32` | Executed quantity |
+| `price` | `Decimal` | Limit price (market orders normalized to resting price) |
+| `quantity` | `Decimal` | Requested quantity |
+| `quantity_filled` | `Decimal` | Executed quantity |
 | `status` | `OrderStatus` | Current lifecycle state |
 | `created_at` | `DateTime<Utc>` | Creation timestamp |
 | `updated_at` | `DateTime<Utc>` | Last modification timestamp |
@@ -99,8 +99,8 @@ enum TimeInForce { GTC, IOC, FOK, DAY }
 | `buy_order_id` | `Uuid` | Matched buy order |
 | `sell_order_id` | `Uuid` | Matched sell order |
 | `item_id` | `Uuid` | Asset matched |
-| `quantity` | `f32` | Execution size |
-| `price` | `f32` | Execution price (resting order's price) |
+| `quantity` | `Decimal` | Execution size |
+| `price` | `Decimal` | Execution price (resting order's price) |
 | `timestamp` | `DateTime<Utc>` | Execution timestamp |
 
 ### CreateOrderRequest
@@ -111,8 +111,8 @@ enum TimeInForce { GTC, IOC, FOK, DAY }
 | `user_id` | `Uuid` |
 | `order_side` | `OrderSide` |
 | `order_type` | `OrderType` |
-| `price` | `f32` |
-| `quantity` | `f32` |
+| `price` | `Decimal` |
+| `quantity` | `Decimal` |
 | `time_in_force` | `TimeInForce` |
 
 ---
@@ -129,13 +129,13 @@ add_order(&mut self, req: CreateOrderRequest) -> Result<Order, String>
 // Queries
 get_orders(&self) -> &HashMap<Uuid, Order>
 get_order_by_id(&self, order_id: Uuid) -> Option<&Order>
-get_current_market_price(&self, item_id: Uuid, side: OrderSide) -> Option<f32>
+get_current_market_price(&self, item_id: Uuid, side: OrderSide) -> Option<Decimal>
 
 // Mutations
 cancel_order(&mut self, order_id: Uuid) -> bool
 update_order_status(&mut self, order_id: Uuid, status: OrderStatus) -> Option<&Order>
-update_order_quantity(&mut self, order_id: Uuid, quantity: f32) -> Option<&Order>
-update_order_price(&mut self, order_id: Uuid, price: f32) -> Option<&Order>
+update_order_quantity(&mut self, order_id: Uuid, quantity: Decimal) -> Option<&Order>
+update_order_price(&mut self, order_id: Uuid, price: Decimal) -> Option<&Order>
 
 // Trade history (public field)
 trades: Vec<Trade>
@@ -171,6 +171,8 @@ oxide-arbiter = "0.1.0-beta.1"
 
 ```rust
 use oxide_arbiter::{CreateOrderRequest, OrderBookService, OrderSide, OrderType, TimeInForce};
+use rust_decimal::Decimal;
+use std::str::FromStr;
 
 let mut book = OrderBookService::new();
 let asset_id = uuid::Uuid::new_v4();
@@ -183,8 +185,8 @@ let buy = book.add_order(CreateOrderRequest {
     order_side: OrderSide::Buy,
     order_type: OrderType::Limit,
     time_in_force: TimeInForce::GTC,
-    price: 100.0,
-    quantity: 50.0,
+    price: Decimal::from_str("100.0").unwrap(),
+    quantity: Decimal::from_str("50.0").unwrap(),
 }).unwrap();
 
 // Incoming sell limit order — matches immediately
@@ -194,8 +196,8 @@ let sell = book.add_order(CreateOrderRequest {
     order_side: OrderSide::Sell,
     order_type: OrderType::Limit,
     time_in_force: TimeInForce::GTC,
-    price: 100.0,
-    quantity: 50.0,
+    price: Decimal::from_str("100.0").unwrap(),
+    quantity: Decimal::from_str("50.0").unwrap(),
 }).unwrap();
 
 // Inspect executed trades
@@ -226,7 +228,7 @@ cargo test
 
 ---
 
-## Roadmap
+## Todos
 
 ### Indexing & Queries
 
@@ -251,3 +253,4 @@ Every query other than lookup-by-ID currently requires an O(n) scan of the full
 | Item | Detail |
 |------|--------|
 | Thread safety | `OrderBookService` is not `Sync`. An `Arc<Mutex<OrderBookService>>` wrapper or a channel-based design is needed for concurrent order acceptance. |
+| Benchmarks | No performance benchmarks exist. A `criterion`-based suite would establish baseline throughput and catch regressions. |

examples/basic_usage.rs

@@ -1,4 +1,6 @@
 use oxide_arbiter::{CreateOrderRequest, OrderBookService, OrderSide, OrderType, TimeInForce};
+use rust_decimal::Decimal;
+use std::str::FromStr;
 
 fn main() {
     let mut order_book = OrderBookService::new();
@@ -8,20 +10,18 @@ fn main() {
         order_side: OrderSide::Buy,
         order_type: OrderType::Limit,
         time_in_force: TimeInForce::DAY,
-        price: 10.0,
-        quantity: 100.0,
+        price: Decimal::from_str("10.0").unwrap(),
+        quantity: Decimal::from_str("100.0").unwrap(),
     });
-
     let _ = order_book.add_order(CreateOrderRequest {
         item_id: uuid::Uuid::new_v4(),
         user_id: uuid::Uuid::new_v4(),
         order_side: OrderSide::Sell,
         order_type: OrderType::Limit,
         time_in_force: TimeInForce::DAY,
-        price: 12.0,
-        quantity: 50.0,
+        price: Decimal::from_str("12.0").unwrap(),
+        quantity: Decimal::from_str("50.0").unwrap(),
     });
-
     for (_, order_book_order) in order_book.get_orders() {
         println!("--- Order Details ---");
         println!("Order ID: {}", order_book_order.id);
@@ -34,7 +34,7 @@ fn main() {
         println!("Order Updated At: {}", order_book_order.updated_at);
         println!("---------------------");
     }
-
     println!("OrderBookService created successfully.");
     println!("Hello, world!");
 }
+

examples/order_matching.rs

@@ -1,11 +1,12 @@
 use oxide_arbiter::{
     CreateOrderRequest, OrderBookService, OrderSide, OrderStatus, OrderType, TimeInForce,
 };
+use rust_decimal::Decimal;
+use std::str::FromStr;
 
 fn print_orders(book: &OrderBookService) {
     let mut orders: Vec<_> = book.get_orders().values().collect();
     orders.sort_by_key(|o| o.created_at);
-
     for order in orders {
         println!(
             "  [{:?}] {:?} {:?} — {}/{} units @ {} — created {}",
@@ -22,108 +23,91 @@ fn print_orders(book: &OrderBookService) {
 
 fn main() {
     let mut book = OrderBookService::new();
-
     println!("=== Full Fill ===");
-
     let item_a = uuid::Uuid::new_v4();
-
     book.add_order(CreateOrderRequest {
         item_id: item_a,
         user_id: uuid::Uuid::new_v4(),
         order_side: OrderSide::Sell,
         order_type: OrderType::Limit,
-        price: 50.0,
-        quantity: 100.0,
+        price: Decimal::from_str("50.0").unwrap(),
+        quantity: Decimal::from_str("100.0").unwrap(),
         time_in_force: TimeInForce::GTC,
     })
     .unwrap();
-
     book.add_order(CreateOrderRequest {
         item_id: item_a,
         user_id: uuid::Uuid::new_v4(),
         order_side: OrderSide::Buy,
         order_type: OrderType::Limit,
-        price: 50.0,
-        quantity: 100.0,
+        price: Decimal::from_str("50.0").unwrap(),
+        quantity: Decimal::from_str("100.0").unwrap(),
         time_in_force: TimeInForce::GTC,
     })
     .unwrap();
-
     println!("Trades produced:");
     for trade in &book.trades {
         println!(
             "  trade {} — {} units @ {}",
             trade.id, trade.quantity, trade.price
         );
     }
-
     println!("\nOrders:");
     print_orders(&book);
-
     // --- Partial fill ---
     println!("\n=== Partial Fill ===");
-
     let item_b = uuid::Uuid::new_v4();
-
     book.add_order(CreateOrderRequest {
         item_id: item_b,
         user_id: uuid::Uuid::new_v4(),
         order_side: OrderSide::Buy,
         order_type: OrderType::Limit,
-        price: 30.0,
-        quantity: 200.0,
+        price: Decimal::from_str("30.0").unwrap(),
+        quantity: Decimal::from_str("200.0").unwrap(),
         time_in_force: TimeInForce::GTC,
     })
     .unwrap();
-
     // Sell fills only part of the resting buy — buy stays PartiallyFilled
     book.add_order(CreateOrderRequest {
         item_id: item_b,
         user_id: uuid::Uuid::new_v4(),
         order_side: OrderSide::Sell,
         order_type: OrderType::Limit,
-        price: 30.0,
-        quantity: 80.0,
+        price: Decimal::from_str("30.0").unwrap(),
+        quantity: Decimal::from_str("80.0").unwrap(),
         time_in_force: TimeInForce::GTC,
     })
     .unwrap();
-
     println!("Trades produced:");
     for trade in &book.trades {
         println!(
             "  trade {} — {} units @ {}",
             trade.id, trade.quantity, trade.price
         );
     }
-
     println!("\nOrders:");
     print_orders(&book);
-
     // --- Summary: filter by fill status ---
     println!("\n=== Filled Orders ===");
-
     let mut closed: Vec<_> = book
         .get_orders()
         .values()
         .filter(|o| matches!(o.status, OrderStatus::Closed))
         .collect();
     closed.sort_by_key(|o| o.created_at);
-
     println!("Fully filled ({}):", closed.len());
     for order in &closed {
         println!(
             "  {:?} {} units @ {}",
             order.order_side, order.quantity_filled, order.price
         );
     }
-
     let mut partial: Vec<_> = book
         .get_orders()
         .values()
         .filter(|o| matches!(o.status, OrderStatus::PartiallyFilled))
         .collect();
     partial.sort_by_key(|o| o.created_at);
-
     println!("Partially filled ({}):", partial.len());
     for order in &partial {
         println!(
@@ -135,11 +119,11 @@ fn main() {
             order.quantity - order.quantity_filled,
         );
     }
-
     let open_count = book
         .get_orders()
         .values()
         .filter(|o| matches!(o.status, OrderStatus::Open))
         .count();
     println!("Open: {open_count}");
 }
+