clob_sync/

order.rs

use fastnum::D128 as Dec;
use fastnum::decimal::Context;
use std::convert::TryFrom;
use std::fmt::Debug;
use std::sync::LazyLock;

use crate::error::Error;
use derive_more::Display;
use uuid7::uuid7;

use ustr::Ustr;

static DECIMAL_CONTEXT: LazyLock<Context> = LazyLock::new(Context::default);

/// A trading order in the Central Limit Order Book.
///
/// # Example
///
/// ```
/// use clob_sync::order::{Order, OrderType, OrderSide, Quantity, Price, Symbol};
/// use fastnum::D128 as Dec;
/// use fastnum::decimal::Context;
/// use std::str::FromStr;
///
/// let order = Order::new(
///     OrderType::Limit(Price::try_from("50000.50").unwrap()),
///     Quantity::try_from("1.5").unwrap(),
///     OrderSide::Buy,
///     Symbol::from("BTC-USD"),
/// );
/// ```
#[derive(PartialEq, Eq, Debug, Clone)]
pub struct Order {
    pub id: Option<OrderId>,
    pub order_type: OrderType,
    pub quantity: Quantity,
    pub side: OrderSide,
    pub symbol: Symbol,
}
impl Order {
    /// Creates a new order without an ID. The order must be assigned an ID
    /// before it can be executed.
    ///
    /// # Arguments
    ///
    /// * `order_type` - The type of order (Limit or Market)
    /// * `quantity` - The quantity to trade
    /// * `side` - Whether this is a Buy or Sell order
    /// * `symbol` - The trading symbol (e.g., "BTC-USD")
    ///
    /// # Example
    ///
    /// ```
    /// use clob_sync::order::{Order, OrderType, OrderSide, Quantity, Price, Symbol};
    /// use fastnum::D128 as Dec;
    /// use fastnum::decimal::Context;
    /// use std::str::FromStr;
    ///
    /// let order = Order::new(
    ///     OrderType::Limit(Price::try_from("50000.00").unwrap()),
    ///     Quantity::from(1u64),
    ///     OrderSide::Buy,
    ///     Symbol::from("BTC-USD"),
    /// );
    /// assert!(order.id.is_none());
    /// ```
    pub fn new(
        order_type: OrderType,
        quantity: Quantity,
        side: OrderSide,
        symbol: Symbol,
    ) -> Order {
        Order {
            id: None,
            order_type,
            quantity,
            side,
            symbol,
        }
    }

    /// Assigns a time-based UUIDv7 order ID to this order.
    ///
    /// UUIDv7 guarantees monotonic ordering within the same millisecond,
    /// making it suitable for order priority determination.
    ///
    /// # Example
    ///
    /// ```
    /// use clob_sync::order::{Order, OrderType, OrderSide, Quantity, Price, Symbol};
    /// use fastnum::D128 as Dec;
    /// use fastnum::decimal::Context;
    /// use std::str::FromStr;
    ///
    /// let mut order = Order::new(
    ///     OrderType::Limit(Price::try_from("50000.00").unwrap()),
    ///     Quantity::from(1u64),
    ///     OrderSide::Buy,
    ///     Symbol::from("BTC-USD"),
    /// );
    /// order = order.with_id();
    /// assert!(order.id.is_some());
    /// ```
    pub fn with_id(mut self) -> Self {
        self.id = Some(OrderId::default());
        self
    }

    /// Returns the order ID.
    ///
    /// # Panics
    ///
    /// Panics if the order has not been assigned an ID via [`with_id`][Order::with_id].
    ///
    /// # Example
    ///
    /// ```
    /// use clob_sync::order::{Order, OrderType, OrderSide, Quantity, Price, Symbol};
    /// use fastnum::D128 as Dec;
    /// use fastnum::decimal::Context;
    /// use std::str::FromStr;
    ///
    /// let order = Order::new(
    ///     OrderType::Limit(Price::try_from("50000.00").unwrap()),
    ///     Quantity::from(1u64),
    ///     OrderSide::Buy,
    ///     Symbol::from("BTC-USD"),
    /// ).with_id();
    ///
    /// let _id = order.get_id();
    /// ```
    pub fn get_id(&self) -> OrderId {
        self.id
            .expect("unexpected condition: order not marked with id")
    }

    /// Creates a new order with the quantity reduced by the specified amount.
    ///
    /// This is useful when an order is partially filled and the remaining
    /// quantity needs to be tracked.
    ///
    /// # Arguments
    ///
    /// * `quantity` - The quantity to subtract from this order's quantity
    ///
    /// # Example
    ///
    /// ```
    /// use clob_sync::order::{Order, OrderType, OrderSide, Quantity, Price, Symbol};
    /// use fastnum::D128 as Dec;
    /// use fastnum::decimal::Context;
    /// use std::str::FromStr;
    ///
    /// let order = Order::new(
    ///     OrderType::Limit(Price::try_from("50000.00").unwrap()),
    ///     Quantity::try_from("10.0").unwrap(),
    ///     OrderSide::Buy,
    ///     Symbol::from("BTC-USD"),
    /// );
    ///
    /// let remaining = order.with_reduced_quantity(&Quantity::try_from("3.0").unwrap());
    /// assert_eq!(remaining.quantity, Quantity::try_from("7.0").unwrap());
    /// ```
    pub fn with_reduced_quantity(&self, quantity: &Quantity) -> Order {
        Order {
            quantity: self.quantity.reduced_by(quantity),
            ..self.clone()
        }
    }
}

/// A time-based UUIDv7 order identifier.
///
/// UUIDv7 provides monotonic ordering within the same millisecond,
/// ensuring deterministic order prioritization in the order book.
/// The internal UUID is sortable and suitable for trading applications.
#[derive(PartialEq, Eq, PartialOrd, Ord, Display, Clone, Copy)]
// #[display("{}", 0)]
pub struct OrderId(
    // time orderable v7, see https://www.ietf.org/rfc/rfc9562.html#name-uuid-version-7
    pub uuid7::Uuid,
);
impl Default for OrderId {
    fn default() -> Self {
        // uuid7 guarantees monotonic ordering within same millisecond (uuid does not)
        Self(uuid7())
    }
}
impl Debug for OrderId {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "OrderId({})", self.0)
    }
}

/// A type-safe quantity wrapper for financial instruments.
///
/// # Example
///
/// ```
/// use clob_sync::order::Quantity;
///
/// let qty = Quantity::try_from("100.5").unwrap();
/// assert!(!qty.is_zero());
/// ```
#[derive(PartialEq, Eq, PartialOrd, Ord, Debug, Display, Copy, Clone)]
pub struct Quantity(pub Dec);
impl Quantity {
    /// Creates a new Quantity from an f64 value.
    pub fn new(value: f64) -> Quantity {
        Quantity(Dec::from(value))
    }

    /// Returns a new Quantity reduced by the specified amount.
    ///
    /// # Example
    ///
    /// ```
    /// use clob_sync::order::Quantity;
    ///
    /// let qty = Quantity::try_from("100.0").unwrap();
    /// let reduced = qty.reduced_by(&Quantity::try_from("30.0").unwrap());
    /// assert_eq!(reduced, Quantity::try_from("70.0").unwrap());
    /// ```
    pub fn reduced_by(&self, quantity: &Quantity) -> Quantity {
        Quantity(self.0 - quantity.0)
    }

    /// Reduces this quantity in place by the specified amount.
    ///
    /// # Example
    ///
    /// ```
    /// use clob_sync::order::Quantity;
    ///
    /// let mut qty = Quantity::try_from("100.0").unwrap();
    /// qty.reduce_by(&Quantity::try_from("30.0").unwrap());
    /// assert_eq!(qty, Quantity::try_from("70.0").unwrap());
    /// ```
    pub fn reduce_by(&mut self, quantity: &Quantity) {
        self.0 -= quantity.0
    }

    /// Sets the quantity to zero.
    ///
    /// # Example
    ///
    /// ```
    /// use clob_sync::order::Quantity;
    ///
    /// let mut qty = Quantity::new(100.0);
    /// qty.clear();
    /// assert!(qty.is_zero());
    /// ```
    pub fn clear(&mut self) {
        self.0 = Dec::from(0i32)
    }

    /// Returns true if the quantity is zero.
    pub fn is_zero(&self) -> bool {
        self.0 == Dec::from(0i32)
    }
}
impl From<u64> for Quantity {
    fn from(value: u64) -> Self {
        Quantity(Dec::from(value))
    }
}
impl TryFrom<&str> for Quantity {
    type Error = Error;
    fn try_from(value: &str) -> Result<Self, Self::Error> {
        Ok(Quantity(Dec::from_str(value, *DECIMAL_CONTEXT)?))
    }
}
impl TryFrom<String> for Quantity {
    type Error = Error;
    fn try_from(value: String) -> Result<Self, Self::Error> {
        Quantity::try_from(value.as_str())
    }
}
impl From<f32> for Quantity {
    fn from(value: f32) -> Self {
        Quantity(Dec::from(value as f64))
    }
}
impl From<usize> for Quantity {
    fn from(value: usize) -> Self {
        Quantity(Dec::from(value))
    }
}

macro_rules! impl_quantity_from_integer {
    ($($t:ty),*) => {
        $(
            impl From<$t> for Quantity {
                fn from(value: $t) -> Self {
                    Quantity(Dec::try_from(value).expect(concat!("cannot convert ", stringify!($t), " to Dec19x19")))
                }
            }
        )*
    }
}
impl_quantity_from_integer!(u8, u16, u32, u128);

/// A trading symbol (e.g., "BTC-USD", "AAPL").
///
/// Symbols are interned using [`Ustr`] for efficient comparison and storage.
///
/// # Example
///
/// ```
/// use clob_sync::order::Symbol;
///
/// let symbol = Symbol::from("BTC-USD");
/// assert_eq!(symbol, Symbol::from("BTC-USD"));
/// ```
#[derive(PartialEq, Eq, PartialOrd, Ord, Debug, Clone, Copy, Display)]
pub struct Symbol(pub Ustr);
impl From<&str> for Symbol {
    fn from(value: &str) -> Self {
        Self(Ustr::from(value))
    }
}

/// The side of an order - Buy or Sell.
///
/// # Example
///
/// ```
/// use clob_sync::order::OrderSide;
///
/// assert_eq!(*OrderSide::Buy.opposite(), OrderSide::Sell);
/// assert_eq!(*OrderSide::Sell.opposite(), OrderSide::Buy);
/// ```
#[derive(PartialEq, Eq, PartialOrd, Ord, Debug, Copy, Clone, Display)]
#[repr(u8)] // Explicit discriminants for predictable indexing (0 and 1)
pub enum OrderSide {
    /// A buy order (bid)
    Buy = 0,
    /// A sell order (ask)
    Sell = 1,
}

impl OrderSide {
    /// Returns the opposite side of this order.
    ///
    /// # Example
    ///
    /// ```
    /// use clob_sync::order::OrderSide;
    ///
    /// assert_eq!(*OrderSide::Buy.opposite(), OrderSide::Sell);
    /// ```
    pub fn opposite(&self) -> &Self {
        match self {
            OrderSide::Buy => &OrderSide::Sell,
            OrderSide::Sell => &Self::Buy,
        }
    }
}

/// A type-safe price wrapper for financial instruments.
///
/// Prices use high-precision Dec19x19 decimal representation to avoid
/// floating-point inaccuracies in financial calculations.
///
/// # Example
///
/// ```
/// use clob_sync::order::Price;
/// use fastnum::D128 as Dec;
/// use fastnum::decimal::Context;
/// use std::str::FromStr;
///
/// let price = Price::try_from("50000.50").unwrap();
/// assert_eq!(price.to_string(), "50000.50");
/// ```
/// A type-safe price wrapper for financial instruments.
///
/// Prices use high-precision Dec19x19 decimal representation to avoid
/// floating-point inaccuracies in financial calculations.
///
/// # Example
///
/// ```
/// use clob_sync::order::Price;
/// use fastnum::D128 as Dec;
/// use fastnum::decimal::Context;
/// use std::str::FromStr;
///
/// let price = Price::try_from("50000.50").unwrap();
/// assert_eq!(price.to_string(), "50000.50");
/// ```
#[derive(PartialEq, Eq, PartialOrd, Ord, Debug, Clone, Copy, Display)]
pub struct Price(pub Dec);
impl Price {
    /// Creates a Price from an f64 value.
    pub fn new(value: f64) -> Price {
        Price(Dec::from(value))
    }
}
macro_rules! impl_price_from_integer {
    ($($t:ty),*) => {
        $(
            impl From<$t> for Price {
                fn from(value: $t) -> Self {
                    Price(Dec::from(value))
                }
            }
        )*
    }
}
impl_price_from_integer!(u8, u16, u32, i8, i16, i32, i64);

macro_rules! impl_price_from_large_integer {
    ($($t:ty),*) => {
        $(
            impl From<$t> for Price {
                fn from(value: $t) -> Self {
                    Price(Dec::try_from(value).expect(concat!("cannot convert ", stringify!($t), " to Dec19x19")))
                }
            }
        )*
    }
}
impl_price_from_large_integer!(u64, u128, i128);

impl TryFrom<&str> for Price {
    type Error = Error;

    fn try_from(value: &str) -> Result<Self, Self::Error> {
        Ok(Price(
            Dec::from_str(value, *DECIMAL_CONTEXT)
                .map_err(Error::DecimalParseError)?,
        ))
    }
}

impl TryFrom<String> for Price {
    type Error = Error;

    fn try_from(value: String) -> Result<Self, Self::Error> {
        Price::try_from(value.as_str())
    }
}

impl From<f32> for Price {
    fn from(value: f32) -> Self {
        Price(Dec::from(value as f64))
    }
}
impl From<usize> for Price {
    fn from(value: usize) -> Self {
        Price(Dec::from(value))
    }
}

/// The type of an order - Limit or Market.
///
/// # Example
///
/// ```
/// use clob_sync::order::{OrderType, Price};
/// use fastnum::D128 as Dec;
/// use fastnum::decimal::Context;
/// use std::str::FromStr;
///
/// let limit = OrderType::Limit(Price::try_from("50000.00").unwrap());
/// let market = OrderType::Market;
/// ```
#[derive(PartialEq, Eq, PartialOrd, Ord, Debug, Clone)]
pub enum OrderType {
    /// A limit order with a specific price
    Limit(Price),
    /// A market order that executes immediately at the best available price
    Market,
}

#[cfg(test)]
mod tests {
    use super::*;

    use insta::assert_debug_snapshot;

    #[test]
    fn test_price_from_str() {
        assert_debug_snapshot!(Price::try_from("123.45").unwrap(), @r"
        Price(
            D128(12345e-2),
        )
        ");
        assert_debug_snapshot!(Price::try_from(String::from("123.45")).unwrap(), @r"
        Price(
            D128(12345e-2),
        )
        ");
    }

    #[test]
    fn test_price_from_number() {
        assert_debug_snapshot!(Price::from(123), @r"
        Price(
            D128(123e0),
        )
        ");
        assert_debug_snapshot!(Price::from(123_u64), @r"
        Price(
            D128(123e0),
        )
        ");
    }
}