orderbook-rs 0.8.0

/******************************************************************************
   Author: Joaquín Béjar García
   Email: jb@taunais.com
   Date: 2/10/25
******************************************************************************/
use crate::orderbook::fees::FeeSchedule;
use pricelevel::MatchResult;
use serde::{Deserialize, Serialize};
use std::sync::Arc;

/// Enhanced trade result that includes symbol information and fee details
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct TradeResult {
    /// The symbol this trade result belongs to
    pub symbol: String,
    /// The underlying match result from the pricelevel crate
    pub match_result: MatchResult,
    /// Total maker fees across all transactions in this trade, in the same
    /// unit as the notional (price × quantity). Negative values represent
    /// rebates. Zero when no `FeeSchedule` is configured.
    pub total_maker_fees: i128,
    /// Total taker fees across all transactions in this trade, in the same
    /// unit as the notional (price × quantity). Zero when no `FeeSchedule`
    /// is configured.
    pub total_taker_fees: i128,
    /// Strictly monotonic global sequence number across every outbound
    /// stream of this `OrderBook<T>` instance: the `TradeListener`
    /// callback, the `PriceLevelChangedListener` callback, and the NATS
    /// publishers. Use it for cross-stream gap detection and temporal
    /// ordering. Always strictly increasing within a single book; replay
    /// into a fresh book yields fresh seqs, not the originals. Stamped at
    /// emission time by `OrderBook::next_engine_seq`.
    ///
    /// Defaults to `0` when deserializing payloads from format versions
    /// that pre-date `engine_seq` so existing consumers keep parsing.
    #[serde(default)]
    pub engine_seq: u64,
    /// Total quote-asset notional consumed by this trade, computed as
    /// `Σ price × quantity` across every transaction. Populated for both
    /// base-quantity (`match_market_order`) and quote-notional
    /// (`match_market_order_by_amount`) market-order paths so consumers
    /// have the field uniformly available without recomputing per-trade.
    ///
    /// Defaults to `0` when deserializing payloads from format versions
    /// that pre-date `quote_notional` so existing consumers keep parsing.
    #[serde(default)]
    pub quote_notional: u128,
}

impl TradeResult {
    /// Create a new `TradeResult` with zero fees
    ///
    /// Use this constructor when no `FeeSchedule` is configured.
    /// Fees default to zero for backward compatibility. The
    /// `quote_notional` field is populated from the supplied
    /// `match_result` (sum of `price × quantity` across every trade).
    pub fn new(symbol: String, match_result: MatchResult) -> Self {
        let quote_notional = compute_quote_notional(&match_result);
        Self {
            symbol,
            match_result,
            total_maker_fees: 0,
            total_taker_fees: 0,
            engine_seq: 0,
            quote_notional,
        }
    }

    /// Create a new `TradeResult` with fees calculated from the given schedule
    ///
    /// For each transaction in the match result, the maker and taker fees
    /// are computed using `FeeSchedule::calculate_fee` with the transaction
    /// notional value (price × quantity).
    ///
    /// # Arguments
    ///
    /// * `symbol` - The trading symbol
    /// * `match_result` - The matching engine result containing transactions
    /// * `fee_schedule` - Optional fee schedule; `None` results in zero fees
    pub fn with_fees(
        symbol: String,
        match_result: MatchResult,
        fee_schedule: Option<FeeSchedule>,
    ) -> Self {
        let (total_maker_fees, total_taker_fees) = match fee_schedule {
            Some(schedule) if !schedule.is_zero_fee() => {
                let mut maker_sum: i128 = 0;
                let mut taker_sum: i128 = 0;
                for tx in match_result.trades().as_vec() {
                    let notional = tx
                        .price()
                        .as_u128()
                        .saturating_mul(tx.quantity().as_u64() as u128);
                    maker_sum = maker_sum
                        .checked_add(schedule.calculate_fee(notional, true))
                        .unwrap_or(maker_sum);
                    taker_sum = taker_sum
                        .checked_add(schedule.calculate_fee(notional, false))
                        .unwrap_or(taker_sum);
                }
                (maker_sum, taker_sum)
            }
            _ => (0, 0),
        };

        let quote_notional = compute_quote_notional(&match_result);
        Self {
            symbol,
            match_result,
            total_maker_fees,
            total_taker_fees,
            engine_seq: 0,
            quote_notional,
        }
    }

    /// Returns the sum of all fees (maker + taker) for this trade
    ///
    /// A positive value means net fees charged; a negative value means
    /// the maker rebate exceeds the taker fee (unusual but possible).
    #[must_use]
    #[inline]
    pub fn total_fees(&self) -> i128 {
        self.total_maker_fees
            .checked_add(self.total_taker_fees)
            .unwrap_or(i128::MAX)
    }
}

/// Sum of `price × quantity` across every trade in `match_result`.
///
/// Saturates on overflow rather than panicking — overflow on `u128` can
/// only occur in adversarial fixtures with prices near `u128::MAX`, and
/// the matching path already saturates equivalent multiplications.
#[inline]
#[must_use]
fn compute_quote_notional(match_result: &MatchResult) -> u128 {
    let mut total: u128 = 0;
    for tx in match_result.trades().as_vec() {
        let notional = tx
            .price()
            .as_u128()
            .saturating_mul(u128::from(tx.quantity().as_u64()));
        total = total.saturating_add(notional);
    }
    total
}

/// Trade listener specification using Arc for shared ownership
pub type TradeListener = Arc<dyn Fn(&TradeResult) + Send + Sync>;

/// A trade event that includes additional metadata for processing
#[derive(Debug, Clone)]
pub struct TradeEvent {
    /// The trading symbol for this event
    pub symbol: String,
    /// The trade result containing match details
    pub trade_result: TradeResult,
    /// Unix timestamp in milliseconds when the trade occurred
    pub timestamp: u64,
    /// Mirrors [`TradeResult::engine_seq`]. Exposed on the envelope so the
    /// outbound payload carries the engine sequence directly without
    /// forcing consumers to reach into `trade_result`.
    pub engine_seq: u64,
}

/// Structure to store trade information for later display
#[derive(Debug, Clone)]
pub struct TradeInfo {
    /// The trading symbol
    pub symbol: String,
    /// The order identifier as a string
    pub order_id: String,
    /// Total quantity executed in this trade
    pub executed_quantity: u64,
    /// Remaining quantity not yet filled
    pub remaining_quantity: u64,
    /// Whether the order was completely filled
    pub is_complete: bool,
    /// Number of individual transactions that occurred
    pub transaction_count: usize,
    /// Detailed information about each transaction
    pub transactions: Vec<TransactionInfo>,
}

/// Information about a single transaction within a trade
#[derive(Debug, Clone)]
pub struct TransactionInfo {
    /// The price at which the transaction occurred
    pub price: u128,
    /// The quantity traded in this transaction
    pub quantity: u64,
    /// Unique identifier for this transaction
    pub transaction_id: String,
    /// Order ID of the maker (passive) side
    pub maker_order_id: String,
    /// Order ID of the taker (aggressive) side
    pub taker_order_id: String,
    /// Fee charged to the maker for this transaction, in the same unit
    /// as the notional (price × quantity). Negative values represent
    /// rebates.
    pub maker_fee: i128,
    /// Fee charged to the taker for this transaction, in the same unit
    /// as the notional (price × quantity). Always non-negative.
    pub taker_fee: i128,
}

#[cfg(test)]
mod tests {
    use super::*;
    use pricelevel::{Id, MatchResult, Price, Quantity, Trade};

    fn make_match_result_with_trades(trades: Vec<Trade>) -> MatchResult {
        let order_id = Id::new_uuid();
        let total_qty: u64 = trades.iter().map(|t| t.quantity().as_u64()).sum();
        let initial_qty = if trades.is_empty() { 100 } else { total_qty };
        let mut mr = MatchResult::new(order_id, initial_qty);
        for trade in trades {
            let _ = mr.add_trade(trade);
        }
        mr
    }

    fn make_trade(price: u128, quantity: u64) -> Trade {
        Trade::new(
            Id::new_uuid(),
            Id::new_uuid(),
            Id::new_uuid(),
            Price::new(price),
            Quantity::new(quantity),
            pricelevel::Side::Buy,
        )
    }

    #[test]
    fn test_trade_result_new_has_zero_fees() {
        let mr = make_match_result_with_trades(vec![make_trade(1000, 10)]);
        let tr = TradeResult::new("BTC/USD".to_string(), mr);

        assert_eq!(tr.total_maker_fees, 0);
        assert_eq!(tr.total_taker_fees, 0);
        assert_eq!(tr.total_fees(), 0);
    }

    #[test]
    fn test_trade_result_with_fees_none_schedule() {
        let mr = make_match_result_with_trades(vec![make_trade(1000, 10)]);
        let tr = TradeResult::with_fees("BTC/USD".to_string(), mr, None);

        assert_eq!(tr.total_maker_fees, 0);
        assert_eq!(tr.total_taker_fees, 0);
        assert_eq!(tr.total_fees(), 0);
    }

    #[test]
    fn test_trade_result_with_fees_zero_schedule() {
        let schedule = FeeSchedule::zero_fee();
        let mr = make_match_result_with_trades(vec![make_trade(1000, 10)]);
        let tr = TradeResult::with_fees("BTC/USD".to_string(), mr, Some(schedule));

        assert_eq!(tr.total_maker_fees, 0);
        assert_eq!(tr.total_taker_fees, 0);
        assert_eq!(tr.total_fees(), 0);
    }

    #[test]
    fn test_trade_result_with_fees_single_transaction() {
        // 5 bps taker, -2 bps maker rebate
        let schedule = FeeSchedule::new(-2, 5);
        // notional = 1000 * 10 = 10_000
        let mr = make_match_result_with_trades(vec![make_trade(1000, 10)]);
        let tr = TradeResult::with_fees("BTC/USD".to_string(), mr, Some(schedule));

        // maker fee: 10_000 * -2 / 10_000 = -2
        assert_eq!(tr.total_maker_fees, -2);
        // taker fee: 10_000 * 5 / 10_000 = 5
        assert_eq!(tr.total_taker_fees, 5);
        // total = -2 + 5 = 3
        assert_eq!(tr.total_fees(), 3);
    }

    #[test]
    fn test_trade_result_with_fees_multiple_transactions() {
        let schedule = FeeSchedule::new(-2, 5);
        let mr = make_match_result_with_trades(vec![
            make_trade(1000, 10), // notional = 10_000
            make_trade(2000, 20), // notional = 40_000
        ]);
        let tr = TradeResult::with_fees("BTC/USD".to_string(), mr, Some(schedule));

        // maker fees: (-2 * 10_000 / 10_000) + (-2 * 40_000 / 10_000) = -2 + -8 = -10
        assert_eq!(tr.total_maker_fees, -10);
        // taker fees: (5 * 10_000 / 10_000) + (5 * 40_000 / 10_000) = 5 + 20 = 25
        assert_eq!(tr.total_taker_fees, 25);
        assert_eq!(tr.total_fees(), 15);
    }

    #[test]
    fn test_trade_result_with_fees_no_transactions() {
        let schedule = FeeSchedule::new(-2, 5);
        let mr = make_match_result_with_trades(vec![]);
        let tr = TradeResult::with_fees("BTC/USD".to_string(), mr, Some(schedule));

        assert_eq!(tr.total_maker_fees, 0);
        assert_eq!(tr.total_taker_fees, 0);
        assert_eq!(tr.total_fees(), 0);
    }

    #[test]
    fn test_trade_result_with_maker_rebate() {
        let schedule = FeeSchedule::with_maker_rebate(5, 10);
        // notional = 100_000 * 50 = 5_000_000
        let mr = make_match_result_with_trades(vec![make_trade(100_000, 50)]);
        let tr = TradeResult::with_fees("BTC/USD".to_string(), mr, Some(schedule));

        // maker: -5 * 5_000_000 / 10_000 = -2_500
        assert_eq!(tr.total_maker_fees, -2_500);
        // taker: 10 * 5_000_000 / 10_000 = 5_000
        assert_eq!(tr.total_taker_fees, 5_000);
        assert_eq!(tr.total_fees(), 2_500);
        assert!(tr.total_maker_fees < 0); // rebate
    }

    #[test]
    fn test_trade_result_symbol_preserved() {
        let mr = make_match_result_with_trades(vec![]);
        let tr = TradeResult::with_fees("ETH/USDT".to_string(), mr, None);
        assert_eq!(tr.symbol, "ETH/USDT");
    }

    #[test]
    fn test_transaction_info_fee_fields() {
        let info = TransactionInfo {
            price: 50_000,
            quantity: 10,
            transaction_id: "tx-1".to_string(),
            maker_order_id: "maker-1".to_string(),
            taker_order_id: "taker-1".to_string(),
            maker_fee: -25,
            taker_fee: 50,
        };

        assert_eq!(info.maker_fee, -25);
        assert_eq!(info.taker_fee, 50);
    }

    #[test]
    fn test_trade_result_engine_seq_default_zero() {
        let mr = make_match_result_with_trades(vec![make_trade(1000, 10)]);
        let tr = TradeResult::new("BTC/USD".to_string(), mr);
        assert_eq!(tr.engine_seq, 0);
    }

    #[test]
    fn test_trade_result_json_roundtrip_preserves_engine_seq() {
        let mr = make_match_result_with_trades(vec![make_trade(1000, 10)]);
        let mut tr = TradeResult::new("BTC/USD".to_string(), mr);
        tr.engine_seq = 42;

        let json = serde_json::to_vec(&tr).expect("serialize trade");
        let decoded: TradeResult = serde_json::from_slice(&json).expect("deserialize trade");

        assert_eq!(decoded.engine_seq, 42);
        assert_eq!(decoded.symbol, tr.symbol);
        assert_eq!(decoded.total_maker_fees, tr.total_maker_fees);
        assert_eq!(decoded.total_taker_fees, tr.total_taker_fees);
    }

    #[test]
    fn test_trade_result_json_missing_engine_seq_defaults_zero() {
        // Build a JSON payload that mirrors the pre-engine_seq schema by
        // first serializing a TradeResult and then stripping the field.
        let mr = make_match_result_with_trades(vec![make_trade(1000, 10)]);
        let mut tr = TradeResult::new("BTC/USD".to_string(), mr);
        tr.engine_seq = 99;

        let mut value: serde_json::Value =
            serde_json::to_value(&tr).expect("serialize trade to value");
        // Remove the field to simulate a payload from before engine_seq.
        if let Some(map) = value.as_object_mut() {
            map.remove("engine_seq");
        }
        let bytes = serde_json::to_vec(&value).expect("serialize stripped value");

        let decoded: TradeResult =
            serde_json::from_slice(&bytes).expect("deserialize stripped trade");
        assert_eq!(
            decoded.engine_seq, 0,
            "missing engine_seq must default to 0 via #[serde(default)]"
        );
    }

    #[test]
    fn test_trade_result_new_populates_quote_notional() {
        // single trade: 1000 * 10 = 10_000
        let mr = make_match_result_with_trades(vec![make_trade(1000, 10)]);
        let tr = TradeResult::new("BTC/USD".to_string(), mr);
        assert_eq!(tr.quote_notional, 10_000);
    }

    #[test]
    fn test_trade_result_with_fees_populates_quote_notional_multi_trade() {
        // 1000*10 + 2000*20 = 10_000 + 40_000 = 50_000
        let mr = make_match_result_with_trades(vec![make_trade(1000, 10), make_trade(2000, 20)]);
        let tr = TradeResult::with_fees("BTC/USD".to_string(), mr, None);
        assert_eq!(tr.quote_notional, 50_000);
    }

    #[test]
    fn test_trade_result_quote_notional_zero_when_no_trades() {
        let mr = make_match_result_with_trades(vec![]);
        let tr = TradeResult::new("BTC/USD".to_string(), mr);
        assert_eq!(tr.quote_notional, 0);
    }

    #[test]
    fn test_trade_result_json_missing_quote_notional_defaults_zero() {
        // Pre-quote_notional payload: serialize, strip the field, decode.
        let mr = make_match_result_with_trades(vec![make_trade(1000, 10)]);
        let tr = TradeResult::new("BTC/USD".to_string(), mr);

        let mut value: serde_json::Value =
            serde_json::to_value(&tr).expect("serialize trade to value");
        if let Some(map) = value.as_object_mut() {
            map.remove("quote_notional");
        }
        let bytes = serde_json::to_vec(&value).expect("serialize stripped value");

        let decoded: TradeResult =
            serde_json::from_slice(&bytes).expect("deserialize stripped trade");
        assert_eq!(
            decoded.quote_notional, 0,
            "missing quote_notional must default to 0 via #[serde(default)]"
        );
    }

    #[test]
    fn test_trade_result_json_roundtrip_preserves_quote_notional() {
        let mr = make_match_result_with_trades(vec![make_trade(1000, 10), make_trade(2000, 5)]);
        let tr = TradeResult::new("BTC/USD".to_string(), mr);
        let original = tr.quote_notional;
        assert_eq!(original, 20_000);

        let json = serde_json::to_vec(&tr).expect("serialize trade");
        let decoded: TradeResult = serde_json::from_slice(&json).expect("deserialize trade");
        assert_eq!(decoded.quote_notional, original);
    }

    #[cfg(feature = "bincode")]
    #[test]
    fn test_trade_result_bincode_roundtrip_preserves_quote_notional() {
        use bincode::config::standard;
        use bincode::serde::{decode_from_slice, encode_to_vec};

        let mr = make_match_result_with_trades(vec![make_trade(1234, 7)]);
        let tr = TradeResult::new("BTC/USD".to_string(), mr);
        let original = tr.quote_notional;
        assert_eq!(original, 8_638);

        let bytes = encode_to_vec(&tr, standard()).expect("bincode encode");
        let (decoded, consumed): (TradeResult, usize) =
            decode_from_slice(&bytes, standard()).expect("bincode decode");
        assert_eq!(consumed, bytes.len());
        assert_eq!(decoded.quote_notional, original);
    }

    #[cfg(feature = "bincode")]
    #[test]
    fn test_trade_result_bincode_roundtrip_preserves_engine_seq() {
        use bincode::config::standard;
        use bincode::serde::{decode_from_slice, encode_to_vec};

        let mr = make_match_result_with_trades(vec![make_trade(1000, 10)]);
        let mut tr = TradeResult::new("BTC/USD".to_string(), mr);
        tr.engine_seq = 7;

        let bytes = encode_to_vec(&tr, standard()).expect("bincode encode");
        let (decoded, consumed): (TradeResult, usize) =
            decode_from_slice(&bytes, standard()).expect("bincode decode");
        assert_eq!(consumed, bytes.len(), "no trailing bytes expected");
        assert_eq!(decoded.engine_seq, 7);
        assert_eq!(decoded.symbol, tr.symbol);
    }
}