Skip to main content

nautilus_backtest/
exchange.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
3//  https://nautechsystems.io
4//
5//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
6//  You may not use this file except in compliance with the License.
7//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
8//
9//  Unless required by applicable law or agreed to in writing, software
10//  distributed under the License is distributed on an "AS IS" BASIS,
11//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12//  See the License for the specific language governing permissions and
13//  limitations under the License.
14// -------------------------------------------------------------------------------------------------
15
16//! Provides a `SimulatedExchange` venue for backtesting on historical data.
17
18use std::{
19    cell::{Cell, RefCell},
20    cmp::Reverse,
21    collections::{BTreeMap, BTreeSet, BinaryHeap, VecDeque},
22    fmt::Debug,
23    rc::Rc,
24};
25
26use ahash::AHashMap;
27use indexmap::IndexMap;
28use nautilus_common::{
29    cache::Cache,
30    clients::ExecutionClient,
31    clock::{Clock, VirtualClock},
32    messages::execution::{ModifyOrder, TradingCommand},
33    msgbus::{self, MessagingSwitchboard, TypedHandler, switchboard},
34};
35use nautilus_core::{
36    DurationNanos, UUID4, UnixNanos,
37    correctness::{CorrectnessResultExt, FAILED, check_equal},
38};
39use nautilus_execution::{
40    matching::RestingOrder,
41    matching_engine::{
42        OrderMatchingEngine,
43        config::{OrderMatchingEngineConfig, OrderPriorityResetPolicy},
44        inflight::InflightOrders,
45        orders::{MatchingOrders, OtoCommand},
46    },
47    models::{
48        fee::FeeModelHandle,
49        fill::FillModelHandle,
50        latency::{LatencyModel, LatencyModelHandle},
51    },
52};
53use nautilus_model::{
54    accounts::{Account, AccountAny, margin_model::MarginModelHandle},
55    data::{
56        Bar, BarType, Data, FundingRateUpdate, InstrumentClose, InstrumentStatus, MarkPriceUpdate,
57        OrderBookDelta, OrderBookDeltas, OrderBookDepth, QuoteTick, TradeTick,
58    },
59    enums::{
60        AccountType, AggregationSource, AggressorSide, BookType, OmsType, OrderStatus,
61        PositionAdjustmentType, PositionSide, PriceType,
62    },
63    events::{FundingSettlement, OrderEventAny, OrderUpdated, PositionAdjusted, PositionEvent},
64    identifiers::{AccountId, InstrumentId, Venue},
65    instruments::{Instrument, InstrumentAny},
66    orderbook::OrderBook,
67    orders::{Order, OrderAny},
68    position::Position,
69    types::{AccountBalance, Currency, Money, Price, Quantity},
70};
71use rust_decimal::Decimal;
72use ustr::Ustr;
73
74use crate::{
75    config::SimulatedVenueConfig,
76    modules::{
77        AccountAdjustmentError, AccountAdjustmentOutcome, ExchangeContext, SimulationModule,
78        SimulationModuleHandle, SimulationModuleResult,
79    },
80};
81
82/// Represents commands with simulated network latency in a min-heap priority queue.
83/// The commands are ordered by timestamp for FIFO processing, with the
84/// earliest timestamp having the highest priority in the queue.
85#[derive(Debug, Eq, PartialEq)]
86struct InflightCommand {
87    timestamp: UnixNanos,
88    counter: u32,
89    command: TradingCommand,
90}
91
92impl InflightCommand {
93    const fn new(timestamp: UnixNanos, counter: u32, command: TradingCommand) -> Self {
94        Self {
95            timestamp,
96            counter,
97            command,
98        }
99    }
100
101    fn matches_scope(&self, ts_now: UnixNanos, scope: SettlementScope) -> bool {
102        match scope {
103            SettlementScope::All => true,
104            SettlementScope::Data(instrument_id) => {
105                self.command.ts_init() == ts_now
106                    || instrument_id.is_some_and(|id| self.command.instrument_id() == id)
107            }
108        }
109    }
110}
111
112impl Ord for InflightCommand {
113    fn cmp(&self, other: &Self) -> std::cmp::Ordering {
114        // Reverse ordering for min-heap (earliest timestamp first then lowest counter)
115        other
116            .timestamp
117            .cmp(&self.timestamp)
118            .then_with(|| other.counter.cmp(&self.counter))
119    }
120}
121
122impl PartialOrd for InflightCommand {
123    fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
124        Some(self.cmp(other))
125    }
126}
127
128/// Simulated exchange venue for realistic trading execution during backtesting.
129///
130/// The `SimulatedExchange` provides a simulation of a trading venue,
131/// including order matching engines, account management, and realistic execution
132/// models. It maintains order books, processes market data, and executes trades
133/// with configurable latency and fill models to accurately simulate real market
134/// conditions during backtesting.
135///
136/// Key features:
137/// - Multi-instrument order matching with realistic execution
138/// - Configurable fee, fill, and latency models
139/// - Support for various order types and execution options
140/// - Account balance and position management
141/// - Market data processing and order book maintenance
142/// - Simulation modules for custom venue behaviors
143#[expect(
144    clippy::struct_excessive_bools,
145    reason = "exchange state mirrors the existing venue configuration flags"
146)]
147pub struct SimulatedExchange {
148    /// The venue identifier.
149    pub id: Venue,
150    /// The order management system type.
151    pub oms_type: OmsType,
152    /// The account type for the venue.
153    pub account_type: AccountType,
154    /// The optional base currency for single-currency accounts.
155    pub base_currency: Option<Currency>,
156    starting_balances: Vec<Money>,
157    book_type: BookType,
158    default_leverage: Decimal,
159    exec_client: Option<Rc<dyn ExecutionClient>>,
160    event_handler: Option<Rc<dyn Fn(OrderEventAny)>>,
161    /// Set only while a trading command is being processed synchronously, which is the
162    /// window in which the execution engine holds a borrow and a re-entrant event would
163    /// panic. Outside it (market data, iteration, expiration, liquidation, open-order
164    /// loading) events dispatch directly, so immediate mode keeps its synchronous timing.
165    deferring_events: Rc<Cell<bool>>,
166    fill_model: FillModelHandle,
167    fee_model: FeeModelHandle,
168    margin_model: Option<MarginModelHandle>,
169    latency_model: Option<LatencyModelHandle>,
170    instruments: AHashMap<InstrumentId, InstrumentAny>,
171    initial_instruments: AHashMap<InstrumentId, InstrumentAny>,
172    matching_engines: IndexMap<InstrumentId, OrderMatchingEngine>,
173    last_raw_id: u32,
174    pending_funding_rates: BTreeMap<(UnixNanos, InstrumentId), FundingRateUpdate>,
175    funding_settlements: BTreeSet<(UnixNanos, InstrumentId)>,
176    leverages: AHashMap<InstrumentId, Decimal>,
177    modules: Vec<SimulationModuleHandle>,
178    callback_error: Option<String>,
179    clock: Rc<RefCell<dyn Clock>>,
180    cache: Rc<RefCell<Cache>>,
181    message_queue: VecDeque<TradingCommand>,
182    inflight_queue: BinaryHeap<InflightCommand>,
183    inflight_orders: InflightOrders,
184    matching_orders: MatchingOrders,
185    inflight_counter: AHashMap<UnixNanos, u32>,
186    bar_execution: bool,
187    bar_adaptive_high_low_ordering: bool,
188    trade_execution: bool,
189    liquidity_consumption: bool,
190    reject_stop_orders: bool,
191    support_gtd_orders: bool,
192    support_contingent_orders: bool,
193    use_position_ids: bool,
194    use_random_ids: bool,
195    use_reduce_only: bool,
196    use_message_queue: bool,
197    use_market_order_acks: bool,
198    allow_cash_borrowing: bool,
199    frozen_account: bool,
200    queue_position: bool,
201    order_priority_reset_policy: OrderPriorityResetPolicy,
202    oto_full_trigger: bool,
203    defer_option_settlement: bool,
204    price_protection_points: u32,
205    liquidation_enabled: bool,
206    liquidation_trigger_ratio: f64,
207    liquidation_cancel_open_orders: bool,
208}
209
210impl Debug for SimulatedExchange {
211    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
212        f.debug_struct(stringify!(SimulatedExchange))
213            .field("id", &self.id)
214            .field("account_type", &self.account_type)
215            .finish_non_exhaustive()
216    }
217}
218
219impl SimulatedExchange {
220    /// Creates a new [`SimulatedExchange`] instance from a venue configuration.
221    ///
222    /// # Errors
223    ///
224    /// Returns an error if:
225    /// - `starting_balances` is empty.
226    /// - `base_currency` is `Some` but `starting_balances` contains multiple currencies.
227    pub fn new(
228        config: SimulatedVenueConfig,
229        cache: Rc<RefCell<Cache>>,
230        clock: Rc<RefCell<dyn Clock>>,
231    ) -> anyhow::Result<Self> {
232        if config.starting_balances.is_empty() {
233            anyhow::bail!("Starting balances must be provided")
234        }
235
236        if config.base_currency.is_some() && config.starting_balances.len() > 1 {
237            anyhow::bail!("single-currency account has multiple starting currencies")
238        }
239
240        let default_leverage = config.default_leverage.unwrap_or_else(|| {
241            if config.account_type == AccountType::Margin {
242                Decimal::from(10)
243            } else {
244                Decimal::from(1)
245            }
246        });
247
248        Ok(Self {
249            id: config.venue,
250            oms_type: config.oms_type,
251            account_type: config.account_type,
252            base_currency: config.base_currency,
253            starting_balances: config.starting_balances,
254            book_type: config.book_type,
255            default_leverage,
256            exec_client: None,
257            event_handler: None,
258            deferring_events: Rc::new(Cell::new(false)),
259            fill_model: config.fill_model,
260            fee_model: config.fee_model,
261            margin_model: config.margin_model,
262            latency_model: config.latency_model,
263            instruments: AHashMap::new(),
264            initial_instruments: AHashMap::new(),
265            matching_engines: IndexMap::new(),
266            last_raw_id: 0,
267            pending_funding_rates: BTreeMap::new(),
268            funding_settlements: BTreeSet::new(),
269            leverages: config.leverages,
270            modules: config.modules,
271            callback_error: None,
272            clock,
273            cache,
274            message_queue: VecDeque::new(),
275            inflight_queue: BinaryHeap::new(),
276            inflight_orders: InflightOrders::default(),
277            matching_orders: MatchingOrders::default(),
278            inflight_counter: AHashMap::new(),
279            bar_execution: config.bar_execution,
280            bar_adaptive_high_low_ordering: config.bar_adaptive_high_low_ordering,
281            trade_execution: config.trade_execution,
282            liquidity_consumption: config.liquidity_consumption,
283            reject_stop_orders: config.reject_stop_orders,
284            support_gtd_orders: config.support_gtd_orders,
285            support_contingent_orders: config.support_contingent_orders,
286            use_position_ids: config.use_position_ids,
287            use_random_ids: config.use_random_ids,
288            use_reduce_only: config.use_reduce_only,
289            use_message_queue: config.use_message_queue,
290            use_market_order_acks: config.use_market_order_acks,
291            allow_cash_borrowing: config.allow_cash_borrowing,
292            frozen_account: config.frozen_account,
293            queue_position: config.queue_position,
294            order_priority_reset_policy: config.order_priority_reset_policy,
295            oto_full_trigger: config.oto_full_trigger,
296            defer_option_settlement: config.defer_option_settlement,
297            price_protection_points: config.price_protection_points,
298            liquidation_enabled: config.liquidation_enabled,
299            liquidation_trigger_ratio: config.liquidation_trigger_ratio,
300            liquidation_cancel_open_orders: config.liquidation_cancel_open_orders,
301        })
302    }
303
304    /// Registers the execution client for the exchange.
305    pub fn register_client(&mut self, client: Rc<dyn ExecutionClient>) {
306        self.exec_client = Some(client);
307    }
308
309    /// Registers the spread quote endpoint used by the data engine.
310    pub fn register_spread_quote_endpoint(exchange: &Rc<RefCell<Self>>) {
311        let venue = exchange.borrow().id;
312        let endpoint = format!("SimulatedExchange.process_new_quote.{venue}");
313        let handler_id = endpoint.clone();
314        let exchange = Rc::clone(exchange);
315        let handler = TypedHandler::from_with_id(handler_id, move |quote: &QuoteTick| {
316            if let Err(e) = exchange.borrow_mut().process_quote_tick(quote) {
317                log::error!("{e:#}");
318            }
319        });
320
321        msgbus::register_quote_endpoint(endpoint.into(), handler);
322    }
323
324    /// Sets the fill model for the exchange.
325    pub fn set_fill_model(&mut self, fill_model: FillModelHandle) {
326        for matching_engine in self.matching_engines.values_mut() {
327            matching_engine.set_fill_model(fill_model.clone());
328            log::info!("Setting fill model for {}", matching_engine.venue);
329        }
330        self.fill_model = fill_model;
331    }
332
333    /// Sets the latency model for the exchange.
334    pub fn set_latency_model(&mut self, latency_model: LatencyModelHandle) {
335        self.latency_model = Some(latency_model);
336    }
337
338    #[must_use]
339    pub(crate) const fn has_modules(&self) -> bool {
340        !self.modules.is_empty()
341    }
342
343    #[must_use]
344    pub(crate) const fn liquidation_enabled(&self) -> bool {
345        self.liquidation_enabled
346    }
347
348    pub(crate) fn check_callback_error(&self) -> anyhow::Result<()> {
349        if let Some(error) = &self.callback_error {
350            anyhow::bail!("Simulation callback failure requires exchange reset: {error}");
351        }
352        Ok(())
353    }
354
355    #[must_use]
356    pub(crate) const fn has_callback_error(&self) -> bool {
357        self.callback_error.is_some()
358    }
359
360    fn store_module_error(
361        &mut self,
362        module_index: usize,
363        method: &str,
364        error: &anyhow::Error,
365    ) -> anyhow::Error {
366        let error = format!("Simulation module {module_index} {method} failed: {error:#}");
367        self.callback_error = Some(error.clone());
368        anyhow::anyhow!(error)
369    }
370
371    fn pre_process_modules(&mut self, data: &Data) -> anyhow::Result<()> {
372        self.check_callback_error()?;
373
374        for module_index in 0..self.modules.len() {
375            if let Err(e) = self.modules[module_index].pre_process(data) {
376                return Err(self.store_module_error(module_index, "pre_process", &e));
377            }
378        }
379        Ok(())
380    }
381
382    /// Returns the configured book type for this venue.
383    #[must_use]
384    pub const fn book_type(&self) -> BookType {
385        self.book_type
386    }
387
388    /// Returns an iterator over the instrument IDs registered with this exchange.
389    pub fn instrument_ids(&self) -> impl Iterator<Item = &InstrumentId> {
390        self.instruments.keys()
391    }
392
393    /// Returns whether `instrument` is already registered with this exchange, failing when its
394    /// ID is registered with a different definition.
395    ///
396    /// Definitions are compared without their event timestamps.
397    ///
398    /// # Errors
399    ///
400    /// Returns an error if an instrument with the same ID is registered with a
401    /// different definition.
402    pub(crate) fn is_instrument_registered(
403        &self,
404        instrument: &InstrumentAny,
405    ) -> anyhow::Result<bool> {
406        match self.instruments.get(&instrument.id()) {
407            None => Ok(false),
408            Some(existing) if instrument_definitions_match(existing, instrument) => Ok(true),
409            Some(_) => anyhow::bail!(
410                "Instrument {} is already registered with a different definition",
411                instrument.id()
412            ),
413        }
414    }
415
416    pub fn initialize_account(&mut self) {
417        self.generate_fresh_account_state();
418    }
419
420    /// Loads non-emulated open orders from the cache into matching engines.
421    pub fn load_open_orders(&mut self) {
422        let mut open_orders: Vec<(OrderAny, AccountId)> = {
423            let cache = self.cache.as_ref().borrow();
424            cache
425                .orders_open(Some(&self.id), None, None, None, None)
426                .into_iter()
427                .filter(|order| !order.is_emulated())
428                .filter_map(|order| {
429                    order
430                        .account_id()
431                        .map(|account_id| (order.clone(), account_id))
432                })
433                .collect()
434        };
435
436        // Sort for deterministic insertion order
437        open_orders.sort_by(|(a, _), (b, _)| {
438            a.ts_init()
439                .cmp(&b.ts_init())
440                .then_with(|| a.client_order_id().cmp(&b.client_order_id()))
441        });
442
443        for (mut order, account_id) in open_orders {
444            let instrument_id = order.instrument_id();
445            if let Some(matching_engine) = self.matching_engines.get_mut(&instrument_id) {
446                matching_engine.process_order(&mut order, account_id);
447            } else {
448                log::error!(
449                    "No matching engine for {instrument_id} to load open order {}",
450                    order.client_order_id()
451                );
452            }
453
454            self.drain_oto_commands();
455        }
456    }
457
458    // panics-doc-ok (transitive via expect_display on venue mismatch)
459    /// Adds an instrument to the simulated exchange and initializes its matching engine.
460    ///
461    /// Adding an instrument that is already registered with the same definition is a
462    /// no-op, so its matching engine and generated ID sequences are preserved.
463    ///
464    /// # Errors
465    ///
466    /// Returns an error if:
467    /// - An instrument with the same ID is already registered with a different definition.
468    /// - The exchange account type is `Cash` and the instrument is a `CryptoPerpetual`,
469    ///   `CryptoFuture`, `FuturesContract`, or `PerpetualContract`.
470    /// - The matching engine raw ID is exhausted.
471    ///
472    /// # Panics
473    ///
474    /// Panics if the instrument cannot be added to the exchange.
475    pub fn add_instrument(&mut self, instrument: InstrumentAny) -> anyhow::Result<()> {
476        check_equal(
477            &instrument.id().venue,
478            &self.id,
479            "Venue of instrument id",
480            "Venue of simulated exchange",
481        )
482        .expect_display(FAILED);
483
484        if self.is_instrument_registered(&instrument)? {
485            return Ok(());
486        }
487
488        if self.account_type == AccountType::Cash
489            && (matches!(instrument, InstrumentAny::CryptoPerpetual(_))
490                || matches!(instrument, InstrumentAny::CryptoFuture(_))
491                || matches!(instrument, InstrumentAny::FuturesContract(_))
492                || matches!(instrument, InstrumentAny::PerpetualContract(_)))
493        {
494            anyhow::bail!("Cash account cannot trade futures or perpetuals")
495        }
496
497        let price_protection = if self.price_protection_points == 0 {
498            None
499        } else {
500            Some(self.price_protection_points)
501        };
502
503        let matching_engine_config = OrderMatchingEngineConfig::builder()
504            .bar_execution(self.bar_execution)
505            .bar_adaptive_high_low_ordering(self.bar_adaptive_high_low_ordering)
506            .trade_execution(self.trade_execution)
507            .liquidity_consumption(self.liquidity_consumption)
508            .reject_stop_orders(self.reject_stop_orders)
509            .support_gtd_orders(self.support_gtd_orders)
510            .support_contingent_orders(self.support_contingent_orders)
511            .use_position_ids(self.use_position_ids)
512            .use_random_ids(self.use_random_ids)
513            .use_reduce_only(self.use_reduce_only)
514            .use_market_order_acks(self.use_market_order_acks)
515            .queue_position(self.queue_position)
516            .order_priority_reset_policy(self.order_priority_reset_policy)
517            .oto_full_trigger(self.oto_full_trigger)
518            .defer_option_settlement(self.defer_option_settlement)
519            .maybe_price_protection_points(price_protection)
520            .build();
521        let instrument_id = instrument.id();
522        let raw_id = self
523            .last_raw_id
524            .checked_add(1)
525            .ok_or_else(|| anyhow::anyhow!("matching engine raw ID exhausted at u32::MAX"))?;
526        self.last_raw_id = raw_id;
527        let mut matching_engine = OrderMatchingEngine::new(
528            instrument.clone(),
529            raw_id,
530            self.fill_model.clone(),
531            self.fee_model.clone(),
532            self.book_type,
533            self.oms_type,
534            self.account_type,
535            self.clock.clone(),
536            Rc::clone(&self.cache),
537            matching_engine_config,
538        );
539
540        if let Some(handler) = &self.event_handler {
541            matching_engine.set_event_handler(Rc::clone(handler));
542        }
543        self.instruments.insert(instrument_id, instrument);
544        matching_engine.set_inflight_orders(self.inflight_orders.clone());
545        matching_engine.set_matching_orders(self.matching_orders.clone());
546        self.matching_engines.insert(instrument_id, matching_engine);
547
548        log::info!("Added instrument {instrument_id} and created matching engine");
549        Ok(())
550    }
551
552    /// Applies replay definitions using the existing matching engine lifecycle.
553    pub(crate) fn update_instrument(&mut self, instrument: &InstrumentAny) -> anyhow::Result<()> {
554        let instrument_id = instrument.id();
555        if let Some(engine) = self.matching_engines.get_mut(&instrument_id) {
556            anyhow::ensure!(
557                instrument.expiration_ns() == engine.instrument.expiration_ns()
558                    || matches!(
559                        (&engine.instrument, instrument),
560                        (
561                            InstrumentAny::BinaryOption(_),
562                            InstrumentAny::BinaryOption(_)
563                        )
564                    ),
565                "Cannot change expiration for instrument {instrument_id} during replay"
566            );
567            self.cache.borrow_mut().add_instrument(instrument.clone())?;
568            self.initial_instruments
569                .entry(instrument_id)
570                .or_insert_with(|| engine.instrument.clone());
571            engine.update_instrument(instrument.clone())?;
572            self.instruments.insert(instrument_id, instrument.clone());
573            let ts_now = self.clock.borrow().timestamp_ns();
574
575            if instrument.expiration_ns().is_some_and(|ns| ns < ts_now) {
576                engine.process_instrument_expiration(ts_now);
577            }
578        }
579
580        self.drain_oto_commands();
581        Ok(())
582    }
583
584    /// Sets the deferred event handler used while a trading command is processed
585    /// synchronously.
586    ///
587    /// The supplied handler is wrapped so it applies only inside that window; outside it
588    /// events go straight to the execution engine as before.
589    pub(crate) fn set_event_handler(&mut self, handler: Rc<dyn Fn(OrderEventAny)>) {
590        let deferring = Rc::clone(&self.deferring_events);
591        let gated: Rc<dyn Fn(OrderEventAny)> = Rc::new(move |event| {
592            if deferring.get() {
593                handler(event);
594            } else {
595                msgbus::send_order_event(MessagingSwitchboard::exec_engine_process(), event);
596            }
597        });
598
599        for matching_engine in self.matching_engines.values_mut() {
600            matching_engine.set_event_handler(Rc::clone(&gated));
601        }
602        self.event_handler = Some(gated);
603    }
604
605    /// Returns the best bid price for the given instrument, if available.
606    #[must_use]
607    pub fn best_bid_price(&self, instrument_id: InstrumentId) -> Option<Price> {
608        self.matching_engines
609            .get(&instrument_id)
610            .and_then(OrderMatchingEngine::best_bid_price)
611    }
612
613    /// Returns the best ask price for the given instrument, if available.
614    #[must_use]
615    pub fn best_ask_price(&self, instrument_id: InstrumentId) -> Option<Price> {
616        self.matching_engines
617            .get(&instrument_id)
618            .and_then(OrderMatchingEngine::best_ask_price)
619    }
620
621    /// Returns a reference to the order book for the given instrument, if available.
622    pub fn get_book(&self, instrument_id: InstrumentId) -> Option<&OrderBook> {
623        self.matching_engines
624            .get(&instrument_id)
625            .map(OrderMatchingEngine::get_book)
626    }
627
628    /// Returns a reference to the matching engine for the given instrument, if available.
629    #[must_use]
630    pub fn get_matching_engine(
631        &self,
632        instrument_id: &InstrumentId,
633    ) -> Option<&OrderMatchingEngine> {
634        self.matching_engines.get(instrument_id)
635    }
636
637    /// Returns a reference to all matching engines keyed by instrument ID.
638    #[must_use]
639    pub const fn get_matching_engines(&self) -> &IndexMap<InstrumentId, OrderMatchingEngine> {
640        &self.matching_engines
641    }
642
643    /// Returns all order books keyed by instrument ID.
644    #[must_use]
645    pub fn get_books(&self) -> AHashMap<InstrumentId, OrderBook> {
646        let mut books = AHashMap::new();
647        for (instrument_id, matching_engine) in &self.matching_engines {
648            books.insert(*instrument_id, matching_engine.get_book().clone());
649        }
650        books
651    }
652
653    /// Returns all open orders, optionally filtered by instrument ID.
654    ///
655    /// An instrument ID with no matching engine returns no orders.
656    #[must_use]
657    pub fn get_open_orders(&self, instrument_id: Option<InstrumentId>) -> Vec<RestingOrder> {
658        match instrument_id {
659            Some(id) => self
660                .matching_engines
661                .get(&id)
662                .map_or_else(Vec::new, OrderMatchingEngine::get_open_orders),
663            None => self
664                .matching_engines
665                .values()
666                .flat_map(OrderMatchingEngine::get_open_orders)
667                .collect(),
668        }
669    }
670
671    /// Returns all open bid orders, optionally filtered by instrument ID.
672    ///
673    /// An instrument ID with no matching engine returns no orders.
674    #[must_use]
675    pub fn get_open_bid_orders(&self, instrument_id: Option<InstrumentId>) -> Vec<RestingOrder> {
676        match instrument_id {
677            Some(id) => self
678                .matching_engines
679                .get(&id)
680                .map_or_else(Vec::new, OrderMatchingEngine::get_open_bid_orders),
681            None => self
682                .matching_engines
683                .values()
684                .flat_map(OrderMatchingEngine::get_open_bid_orders)
685                .collect(),
686        }
687    }
688
689    /// Returns all open ask orders, optionally filtered by instrument ID.
690    ///
691    /// An instrument ID with no matching engine returns no orders.
692    #[must_use]
693    pub fn get_open_ask_orders(&self, instrument_id: Option<InstrumentId>) -> Vec<RestingOrder> {
694        match instrument_id {
695            Some(id) => self
696                .matching_engines
697                .get(&id)
698                .map_or_else(Vec::new, OrderMatchingEngine::get_open_ask_orders),
699            None => self
700                .matching_engines
701                .values()
702                .flat_map(OrderMatchingEngine::get_open_ask_orders)
703                .collect(),
704        }
705    }
706
707    /// Returns the account for this exchange, if an execution client is registered.
708    #[must_use]
709    pub fn get_account(&self) -> Option<AccountAny> {
710        self.exec_client
711            .as_ref()
712            .and_then(|client| client.get_account())
713    }
714
715    /// Returns a reference to the cache.
716    #[must_use]
717    pub fn cache(&self) -> &Rc<RefCell<Cache>> {
718        &self.cache
719    }
720
721    /// Adjusts the account balance by the given amount.
722    ///
723    /// Returns whether the adjustment was applied successfully.
724    pub fn adjust_account(&mut self, adjustment: Money) -> bool {
725        self.adjust_account_balance(adjustment, false)
726    }
727
728    fn adjust_account_balance(&self, adjustment: Money, lock_margins: bool) -> bool {
729        if self.frozen_account {
730            // Nothing to adjust
731            return true;
732        }
733
734        if let Some(exec_client) = &self.exec_client {
735            log::debug!("Adjusting account for venue {}", exec_client.venue());
736        }
737
738        match self.try_adjust_account_balance(adjustment, lock_margins) {
739            Ok(()) => true,
740            Err(e) => {
741                log::error!("{e}");
742                false
743            }
744        }
745    }
746
747    /// Tries to adjust the account balance by the given amount without logging failures.
748    ///
749    /// # Errors
750    ///
751    /// Returns an error if the account or currency balance is unavailable, the
752    /// resulting balance exceeds [`Money`] bounds, or account state generation fails.
753    pub fn try_adjust_account(&mut self, adjustment: Money) -> Result<(), AccountAdjustmentError> {
754        self.try_adjust_account_balance(adjustment, false)
755    }
756
757    // With `lock_margins`, a margin account that calculates its own state locks its margins the
758    // way `MarginAccount::recalculate_balance` does, capped at the new total.
759    fn try_adjust_account_balance(
760        &self,
761        adjustment: Money,
762        lock_margins: bool,
763    ) -> Result<(), AccountAdjustmentError> {
764        if self.frozen_account {
765            // Nothing to adjust
766            return Ok(());
767        }
768
769        if let Some(exec_client) = &self.exec_client {
770            let venue = exec_client.venue();
771            let account_state = {
772                let cache = self.cache.borrow();
773                if let Some(account) = cache.account_for_venue(&venue) {
774                    if let Some(balance) = account.balance(Some(adjustment.currency)) {
775                        let mut current_balance = *balance;
776                        let Some(total) = current_balance.total.checked_add(adjustment) else {
777                            return Err(AccountAdjustmentError::TotalOverflow(adjustment.currency));
778                        };
779
780                        match &*account {
781                            AccountAny::Margin(margin_account)
782                                if lock_margins && margin_account.calculate_account_state =>
783                            {
784                                current_balance = margin_account.balance_locking_margins(total);
785                            }
786                            _ => {
787                                let Some(free) = current_balance.free.checked_add(adjustment)
788                                else {
789                                    return Err(AccountAdjustmentError::FreeBalanceOverflow(
790                                        adjustment.currency,
791                                    ));
792                                };
793                                current_balance.total = total;
794                                current_balance.free = free;
795                            }
796                        }
797
798                        // Carry account-wide margins too, applying the state replaces both sets
799                        let margins = match &*account {
800                            AccountAny::Margin(margin_account) => margin_account
801                                .margins
802                                .values()
803                                .chain(margin_account.account_margins.values())
804                                .copied()
805                                .collect(),
806                            _ => Vec::new(),
807                        };
808
809                        Some((
810                            vec![current_balance],
811                            margins,
812                            self.clock.borrow().timestamp_ns(),
813                        ))
814                    } else {
815                        return Err(AccountAdjustmentError::MissingBalance(adjustment.currency));
816                    }
817                } else {
818                    return Err(AccountAdjustmentError::MissingAccount(venue));
819                }
820            };
821
822            if let Some((balances, margins, ts_event)) = account_state {
823                exec_client
824                    .generate_account_state(balances, margins, true, ts_event, None)
825                    .map_err(|e| AccountAdjustmentError::AccountStateGeneration(e.to_string()))?;
826            }
827        }
828        Ok(())
829    }
830
831    /// Returns whether there are pending commands at or before `ts_now`.
832    #[must_use]
833    pub fn has_pending_commands(&self, ts_now: UnixNanos) -> bool {
834        if !self.message_queue.is_empty() {
835            return true;
836        }
837        self.inflight_queue
838            .peek()
839            .is_some_and(|inflight| inflight.timestamp <= ts_now)
840    }
841
842    pub(crate) fn has_pending_commands_for_scope(
843        &self,
844        ts_now: UnixNanos,
845        scope: SettlementScope,
846    ) -> bool {
847        if matches!(scope, SettlementScope::All) {
848            return self.has_pending_commands(ts_now);
849        }
850
851        if !self.message_queue.is_empty() {
852            return true;
853        }
854
855        self.inflight_queue
856            .iter()
857            .any(|inflight| inflight.timestamp <= ts_now && inflight.matches_scope(ts_now, scope))
858    }
859
860    /// Returns the latest arrival timestamp across all latency-deferred
861    /// inflight commands, or `None` when the inflight queue is empty.
862    ///
863    /// Used at shutdown to advance the clock past the configured `LatencyModel`
864    /// delay so trailing commands (those emitted on the final data tick or
865    /// in `on_stop`) settle before the engines stop.
866    #[must_use]
867    pub fn max_inflight_command_ts(&self) -> Option<UnixNanos> {
868        self.inflight_queue.iter().map(|c| c.timestamp).max()
869    }
870
871    /// Iterates all matching engines so newly submitted orders can match
872    /// against the current market state.
873    pub fn iterate_matching_engines(&mut self, ts_now: UnixNanos) {
874        for index in 0..self.matching_engines.len() {
875            if let Some((_, engine)) = self.matching_engines.get_index_mut(index) {
876                engine.iterate(ts_now, AggressorSide::NoAggressor);
877            }
878
879            self.drain_oto_commands();
880        }
881    }
882
883    /// Processes instrument expirations due at the given timestamp.
884    pub fn process_instrument_expirations(&mut self, ts_now: UnixNanos) {
885        for matching_engine in self.matching_engines.values_mut() {
886            if matching_engine
887                .instrument
888                .expiration_ns()
889                .is_some_and(|expiration_ns| ts_now >= expiration_ns)
890            {
891                matching_engine.process_instrument_expiration(ts_now);
892            }
893        }
894
895        self.drain_oto_commands();
896    }
897
898    /// Returns unprocessed instrument expirations for timer scheduling.
899    #[must_use]
900    pub fn instrument_expirations(&self) -> Vec<(InstrumentId, UnixNanos)> {
901        self.matching_engines
902            .values()
903            .filter(|matching_engine| !matching_engine.is_expiration_processed())
904            .filter_map(|matching_engine| {
905                matching_engine
906                    .instrument
907                    .expiration_ns()
908                    .filter(|expiration_ns| *expiration_ns > UnixNanos::default())
909                    .map(|expiration_ns| (matching_engine.instrument.id(), expiration_ns))
910            })
911            .collect()
912    }
913
914    /// Advances the exchange clock to the given timestamp so that any event
915    /// generators (modules, account state) see the correct time even when
916    /// no commands are pending.
917    ///
918    /// # Panics
919    ///
920    /// Panics if the clock is not a [`VirtualClock`].
921    pub fn set_clock_time(&self, ts_now: UnixNanos) {
922        let mut clock_ref = self.clock.borrow_mut();
923        let test_clock = clock_ref
924            .as_any_mut()
925            .downcast_mut::<VirtualClock>()
926            .expect("SimulatedExchange requires VirtualClock");
927        test_clock.set_time(ts_now);
928    }
929
930    /// Sends a trading command to the exchange for processing.
931    ///
932    /// Ignores commands while a callback failure is latched, until [`Self::reset`] clears it.
933    /// [`Self::process_modules`] returns the latched error.
934    pub fn send(&mut self, command: TradingCommand) {
935        if matches!(
936            &command,
937            TradingCommand::QueryOrder(_) | TradingCommand::QueryAccount(_)
938        ) {
939            log::warn!("Simulated exchange does not support queries: {command}");
940            return;
941        }
942
943        if self.callback_error.is_some() {
944            return;
945        }
946
947        if !self.use_message_queue {
948            let _guard = DeferEventsGuard::new(Rc::clone(&self.deferring_events));
949            self.process_trading_command(command);
950        } else if self.latency_model.is_none() {
951            self.inflight_orders.insert(&command);
952            self.message_queue.push_back(command);
953        } else {
954            let (timestamp, counter) = match self.generate_inflight_command(&command) {
955                Ok(arrival) => arrival,
956                Err(e) => {
957                    self.callback_error = Some(format!("Latency model failed: {e:#}"));
958                    return;
959                }
960            };
961
962            self.inflight_orders.insert(&command);
963            self.inflight_queue
964                .push(InflightCommand::new(timestamp, counter, command));
965        }
966    }
967
968    fn generate_inflight_command(
969        &mut self,
970        command: &TradingCommand,
971    ) -> anyhow::Result<(UnixNanos, u32)> {
972        if let Some(latency_model) = &self.latency_model {
973            let ts_now = self.clock.borrow().timestamp_ns();
974
975            let latency = match command {
976                TradingCommand::SubmitOrder(_) | TradingCommand::SubmitOrderList(_) => {
977                    latency_model.get_insert_latency(command, ts_now)?
978                }
979                TradingCommand::ModifyOrder(_) | TradingCommand::ModifyOrders(_) => {
980                    latency_model.get_update_latency(command, ts_now)?
981                }
982                TradingCommand::CancelOrder(_)
983                | TradingCommand::CancelOrders(_)
984                | TradingCommand::CancelAllOrders(_) => {
985                    latency_model.get_delete_latency(command, ts_now)?
986                }
987                _ => anyhow::bail!("Cannot handle command: {command:?}"),
988            };
989
990            let ts = command.ts_init().checked_add(latency).ok_or_else(|| {
991                anyhow::anyhow!("Latency arrival timestamp exceeds u64 nanoseconds")
992            })?;
993
994            let counter = self
995                .inflight_counter
996                .entry(ts)
997                .and_modify(|e| *e += 1)
998                .or_insert(1);
999
1000            Ok((ts, *counter))
1001        } else {
1002            anyhow::bail!("Latency model should be initialized");
1003        }
1004    }
1005
1006    /// Processes a single order book delta.
1007    ///
1008    /// # Errors
1009    ///
1010    /// Returns an error if module pre-processing or matching engine processing fails.
1011    pub fn process_order_book_delta(&mut self, delta: OrderBookDelta) -> anyhow::Result<()> {
1012        self.pre_process_modules(&Data::BookDelta(delta))?;
1013
1014        if !self.matching_engines.contains_key(&delta.instrument_id) {
1015            let instrument = {
1016                let cache = self.cache.as_ref().borrow();
1017                cache.instrument(&delta.instrument_id).cloned()
1018            };
1019
1020            if let Some(instrument) = instrument {
1021                self.add_instrument(instrument)?;
1022            } else {
1023                anyhow::bail!(
1024                    "No matching engine found for instrument {}",
1025                    delta.instrument_id
1026                );
1027            }
1028        }
1029
1030        if let Some(matching_engine) = self.matching_engines.get_mut(&delta.instrument_id) {
1031            matching_engine.process_order_book_delta(&delta)?;
1032        } else {
1033            anyhow::bail!("Matching engine should be initialized");
1034        }
1035
1036        self.drain_oto_commands();
1037        Ok(())
1038    }
1039
1040    /// Processes a batch of order book deltas.
1041    ///
1042    /// # Errors
1043    ///
1044    /// Returns an error if module pre-processing or matching engine processing fails.
1045    pub fn process_order_book_deltas(&mut self, deltas: &OrderBookDeltas) -> anyhow::Result<()> {
1046        self.pre_process_modules(&Data::BookDeltas(Box::new(deltas.clone())))?;
1047
1048        if !self.matching_engines.contains_key(&deltas.instrument_id) {
1049            let instrument = {
1050                let cache = self.cache.as_ref().borrow();
1051                cache.instrument(&deltas.instrument_id).cloned()
1052            };
1053
1054            if let Some(instrument) = instrument {
1055                self.add_instrument(instrument)?;
1056            } else {
1057                anyhow::bail!(
1058                    "No matching engine found for instrument {}",
1059                    deltas.instrument_id
1060                );
1061            }
1062        }
1063
1064        if let Some(matching_engine) = self.matching_engines.get_mut(&deltas.instrument_id) {
1065            matching_engine.process_order_book_deltas(deltas)?;
1066        } else {
1067            anyhow::bail!("Matching engine should be initialized");
1068        }
1069
1070        self.drain_oto_commands();
1071        Ok(())
1072    }
1073
1074    /// Processes an L2 order book depth snapshot.
1075    ///
1076    /// # Errors
1077    ///
1078    /// Returns an error if module pre-processing or matching engine processing fails.
1079    pub fn process_order_book_depth(&mut self, depth: &OrderBookDepth) -> anyhow::Result<()> {
1080        self.pre_process_modules(&Data::BookDepth(Box::new(depth.clone())))?;
1081
1082        if !self.matching_engines.contains_key(&depth.instrument_id) {
1083            let instrument = {
1084                let cache = self.cache.as_ref().borrow();
1085                cache.instrument(&depth.instrument_id).cloned()
1086            };
1087
1088            if let Some(instrument) = instrument {
1089                self.add_instrument(instrument)?;
1090            } else {
1091                anyhow::bail!(
1092                    "No matching engine found for instrument {}",
1093                    depth.instrument_id
1094                );
1095            }
1096        }
1097
1098        if let Some(matching_engine) = self.matching_engines.get_mut(&depth.instrument_id) {
1099            matching_engine.process_order_book_depth(depth)?;
1100        } else {
1101            anyhow::bail!("Matching engine should be initialized");
1102        }
1103
1104        self.drain_oto_commands();
1105        Ok(())
1106    }
1107
1108    /// Processes a mark price update and updates the matching engine.
1109    ///
1110    /// # Errors
1111    ///
1112    /// Returns an error if module pre-processing or matching engine initialization fails.
1113    pub fn process_mark_price(&mut self, mark: &MarkPriceUpdate) -> anyhow::Result<()> {
1114        self.pre_process_modules(&Data::MarkPrice(*mark))?;
1115
1116        if !self.matching_engines.contains_key(&mark.instrument_id) {
1117            let instrument = {
1118                let cache = self.cache.as_ref().borrow();
1119                cache.instrument(&mark.instrument_id).cloned()
1120            };
1121
1122            if let Some(instrument) = instrument {
1123                self.add_instrument(instrument)?;
1124            } else {
1125                anyhow::bail!(
1126                    "No matching engine found for instrument {}",
1127                    mark.instrument_id
1128                );
1129            }
1130        }
1131
1132        if let Some(matching_engine) = self.matching_engines.get_mut(&mark.instrument_id) {
1133            matching_engine.process_mark_price(mark);
1134        } else {
1135            anyhow::bail!("Matching engine should be initialized");
1136        }
1137
1138        self.drain_oto_commands();
1139        Ok(())
1140    }
1141
1142    /// Processes a quote tick and updates the matching engine.
1143    ///
1144    /// # Errors
1145    ///
1146    /// Returns an error if module pre-processing or matching engine processing fails.
1147    pub fn process_quote_tick(&mut self, quote: &QuoteTick) -> anyhow::Result<()> {
1148        self.pre_process_modules(&Data::Quote(*quote))?;
1149
1150        if !self.matching_engines.contains_key(&quote.instrument_id) {
1151            let instrument = {
1152                let cache = self.cache.as_ref().borrow();
1153                cache.instrument(&quote.instrument_id).cloned()
1154            };
1155
1156            if let Some(instrument) = instrument {
1157                self.add_instrument(instrument)?;
1158            } else {
1159                anyhow::bail!(
1160                    "No matching engine found for instrument {}",
1161                    quote.instrument_id
1162                );
1163            }
1164        }
1165
1166        if let Some(matching_engine) = self.matching_engines.get_mut(&quote.instrument_id) {
1167            matching_engine.process_quote_tick(quote);
1168        } else {
1169            anyhow::bail!("Matching engine should be initialized");
1170        }
1171
1172        self.drain_oto_commands();
1173        Ok(())
1174    }
1175
1176    /// Processes a trade tick and updates the matching engine.
1177    ///
1178    /// # Errors
1179    ///
1180    /// Returns an error if module pre-processing or matching engine processing fails.
1181    pub fn process_trade_tick(&mut self, trade: &TradeTick) -> anyhow::Result<()> {
1182        self.pre_process_modules(&Data::Trade(*trade))?;
1183
1184        if !self.matching_engines.contains_key(&trade.instrument_id) {
1185            let instrument = {
1186                let cache = self.cache.as_ref().borrow();
1187                cache.instrument(&trade.instrument_id).cloned()
1188            };
1189
1190            if let Some(instrument) = instrument {
1191                self.add_instrument(instrument)?;
1192            } else {
1193                anyhow::bail!(
1194                    "No matching engine found for instrument {}",
1195                    trade.instrument_id
1196                );
1197            }
1198        }
1199
1200        if let Some(matching_engine) = self.matching_engines.get_mut(&trade.instrument_id) {
1201            matching_engine.process_trade_tick(trade);
1202        } else {
1203            anyhow::bail!("Matching engine should be initialized");
1204        }
1205
1206        self.drain_oto_commands();
1207        Ok(())
1208    }
1209
1210    /// Processes a bar and updates the matching engine.
1211    ///
1212    /// # Errors
1213    ///
1214    /// Returns an error if L1 bar execution receives a non-time external bar other
1215    /// than a mark-price bar, or if module pre-processing or matching engine processing fails.
1216    pub fn process_bar(&mut self, bar: Bar) -> anyhow::Result<()> {
1217        if self.bar_execution
1218            && self.book_type == BookType::L1_MBP
1219            && bar.bar_type.is_externally_aggregated()
1220            && bar.bar_type.spec().price_type != PriceType::Mark
1221        {
1222            anyhow::ensure!(
1223                bar.bar_type.spec().is_time_aggregated(),
1224                "Bar execution requires time-aggregated bars, received {}",
1225                bar.bar_type,
1226            );
1227        }
1228
1229        self.pre_process_modules(&Data::Bar(bar))?;
1230
1231        if !self.matching_engines.contains_key(&bar.instrument_id()) {
1232            let instrument = {
1233                let cache = self.cache.as_ref().borrow();
1234                cache.instrument(&bar.instrument_id()).cloned()
1235            };
1236
1237            if let Some(instrument) = instrument {
1238                self.add_instrument(instrument)?;
1239            } else {
1240                anyhow::bail!(
1241                    "No matching engine found for instrument {}",
1242                    bar.instrument_id()
1243                );
1244            }
1245        }
1246
1247        if let Some(matching_engine) = self.matching_engines.get_mut(&bar.instrument_id()) {
1248            matching_engine.process_bar(&bar);
1249        } else {
1250            anyhow::bail!("Matching engine should be initialized");
1251        }
1252
1253        self.drain_oto_commands();
1254        Ok(())
1255    }
1256
1257    /// Processes an instrument status update.
1258    ///
1259    /// # Errors
1260    ///
1261    /// Returns an error if module pre-processing or matching engine processing fails.
1262    pub fn process_instrument_status(&mut self, status: InstrumentStatus) -> anyhow::Result<()> {
1263        self.pre_process_modules(&Data::InstrumentStatus(status))?;
1264
1265        if !self.matching_engines.contains_key(&status.instrument_id) {
1266            let instrument = {
1267                let cache = self.cache.as_ref().borrow();
1268                cache.instrument(&status.instrument_id).cloned()
1269            };
1270
1271            if let Some(instrument) = instrument {
1272                self.add_instrument(instrument)?;
1273            } else {
1274                anyhow::bail!(
1275                    "No matching engine found for instrument {}",
1276                    status.instrument_id
1277                );
1278            }
1279        }
1280
1281        if let Some(matching_engine) = self.matching_engines.get_mut(&status.instrument_id) {
1282            matching_engine.process_status(status.action);
1283        } else {
1284            anyhow::bail!("Matching engine should be initialized");
1285        }
1286
1287        self.drain_oto_commands();
1288        Ok(())
1289    }
1290
1291    /// Processes an instrument close event.
1292    ///
1293    /// # Errors
1294    ///
1295    /// Returns an error if module pre-processing or matching engine processing fails.
1296    pub fn process_instrument_close(&mut self, close: InstrumentClose) -> anyhow::Result<()> {
1297        self.pre_process_modules(&Data::InstrumentClose(close))?;
1298
1299        if !self.matching_engines.contains_key(&close.instrument_id) {
1300            let instrument = {
1301                let cache = self.cache.as_ref().borrow();
1302                cache.instrument(&close.instrument_id).cloned()
1303            };
1304
1305            if let Some(instrument) = instrument {
1306                self.add_instrument(instrument)?;
1307            } else {
1308                anyhow::bail!(
1309                    "No matching engine found for instrument {}",
1310                    close.instrument_id
1311                );
1312            }
1313        }
1314
1315        if let Some(matching_engine) = self.matching_engines.get_mut(&close.instrument_id) {
1316            matching_engine.process_instrument_close(close);
1317        } else {
1318            anyhow::bail!("Matching engine should be initialized");
1319        }
1320
1321        self.drain_oto_commands();
1322        Ok(())
1323    }
1324
1325    /// Processes a funding rate update.
1326    ///
1327    /// Returns the funding boundary timestamp when the engine should schedule a settlement.
1328    ///
1329    /// # Errors
1330    ///
1331    /// Returns an error if module pre-processing or funding settlement fails.
1332    pub fn process_funding_rate(
1333        &mut self,
1334        funding_rate: FundingRateUpdate,
1335    ) -> anyhow::Result<Option<UnixNanos>> {
1336        let replay_ts = self.clock.borrow().timestamp_ns();
1337        let instrument_id = funding_rate.instrument_id;
1338        let boundary = Self::funding_boundary(&funding_rate);
1339        let next_boundary = self.queue_funding_rate(funding_rate)?;
1340
1341        if let Some(boundary) = boundary
1342            && boundary <= replay_ts
1343        {
1344            self.process_funding_settlement(instrument_id, boundary)?;
1345            return Ok(None);
1346        }
1347
1348        Ok(next_boundary)
1349    }
1350
1351    pub(crate) fn process_funding_rate_deferred(
1352        &mut self,
1353        funding_rate: FundingRateUpdate,
1354        replay_ts: UnixNanos,
1355    ) -> anyhow::Result<Option<UnixNanos>> {
1356        self.queue_funding_rate(funding_rate)?;
1357        Ok(self
1358            .next_funding_boundary()
1359            .filter(|boundary| *boundary > replay_ts))
1360    }
1361
1362    fn queue_funding_rate(
1363        &mut self,
1364        funding_rate: FundingRateUpdate,
1365    ) -> anyhow::Result<Option<UnixNanos>> {
1366        self.pre_process_modules(&Data::FundingRate(funding_rate))?;
1367
1368        let Some(boundary) = Self::funding_boundary(&funding_rate) else {
1369            log::debug!(
1370                "Funding rate update for {} does not define a settlement boundary",
1371                funding_rate.instrument_id
1372            );
1373            return Ok(None);
1374        };
1375
1376        let key = (boundary, funding_rate.instrument_id);
1377        if !self.funding_settlements.contains(&key) {
1378            self.pending_funding_rates.insert(key, funding_rate);
1379        }
1380        Ok(Some(boundary))
1381    }
1382
1383    /// Processes a scheduled funding settlement for the instrument.
1384    ///
1385    /// # Errors
1386    ///
1387    /// Returns an error if a prior simulation module failure requires reset.
1388    pub fn process_funding_settlement(
1389        &mut self,
1390        instrument_id: InstrumentId,
1391        ts_event: UnixNanos,
1392    ) -> anyhow::Result<()> {
1393        self.check_callback_error()?;
1394        let key = (ts_event, instrument_id);
1395        let Some(funding_rate) = self.pending_funding_rates.remove(&key) else {
1396            return Ok(());
1397        };
1398
1399        if !self.settle_funding_rate(&funding_rate, ts_event) {
1400            self.pending_funding_rates.insert(key, funding_rate);
1401        }
1402        Ok(())
1403    }
1404
1405    #[must_use]
1406    pub(crate) fn funding_boundaries_due(
1407        &self,
1408        replay_ts: UnixNanos,
1409    ) -> Vec<(UnixNanos, InstrumentId)> {
1410        self.pending_funding_rates
1411            .keys()
1412            .copied()
1413            .take_while(|(boundary, _)| *boundary <= replay_ts)
1414            .collect()
1415    }
1416
1417    pub(crate) fn settle_funding_boundary(
1418        &mut self,
1419        boundary: UnixNanos,
1420        instrument_id: InstrumentId,
1421    ) -> bool {
1422        let key = (boundary, instrument_id);
1423        let Some(funding_rate) = self.pending_funding_rates.remove(&key) else {
1424            return true;
1425        };
1426
1427        if self.settle_funding_rate(&funding_rate, boundary) {
1428            true
1429        } else {
1430            self.pending_funding_rates.insert(key, funding_rate);
1431            false
1432        }
1433    }
1434
1435    #[must_use]
1436    pub(crate) fn next_funding_boundary(&self) -> Option<UnixNanos> {
1437        self.pending_funding_rates
1438            .first_key_value()
1439            .map(|((boundary, _), _)| *boundary)
1440    }
1441
1442    fn settle_funding_rate(
1443        &mut self,
1444        funding_rate: &FundingRateUpdate,
1445        ts_event: UnixNanos,
1446    ) -> bool {
1447        let settlement_key = (ts_event, funding_rate.instrument_id);
1448        if self.funding_settlements.contains(&settlement_key) {
1449            return true;
1450        }
1451
1452        let Some(exec_client) = &self.exec_client else {
1453            log::warn!(
1454                "Cannot settle funding for {}: execution client is not registered",
1455                funding_rate.instrument_id
1456            );
1457            return false;
1458        };
1459        let account_id = exec_client.account_id();
1460        let account_venue = exec_client.venue();
1461
1462        if !self
1463            .matching_engines
1464            .contains_key(&funding_rate.instrument_id)
1465        {
1466            let instrument = {
1467                let cache = self.cache.as_ref().borrow();
1468                cache.instrument(&funding_rate.instrument_id).cloned()
1469            };
1470
1471            if let Some(instrument) = instrument {
1472                if let Err(e) = self.add_instrument(instrument) {
1473                    log::error!(
1474                        "Cannot settle funding for {}: failed to add instrument: {e}",
1475                        funding_rate.instrument_id
1476                    );
1477                    return false;
1478                }
1479            } else {
1480                log::warn!(
1481                    "Cannot settle funding for {}: no matching engine or instrument",
1482                    funding_rate.instrument_id
1483                );
1484                return false;
1485            }
1486        }
1487
1488        // Snapshots without history: valuation reads only position state, and the snapshot is the
1489        // rollback point if settlement fails after the cached positions are adjusted in place
1490        let open_positions: Vec<Position> = {
1491            let cache = self.cache.borrow();
1492            cache
1493                .positions_open(
1494                    Some(&self.id),
1495                    Some(&funding_rate.instrument_id),
1496                    None,
1497                    Some(&account_id),
1498                    None,
1499                )
1500                .into_iter()
1501                .map(|position| position.clone_without_events())
1502                .collect()
1503        };
1504
1505        if open_positions.is_empty() {
1506            self.funding_settlements.insert(settlement_key);
1507            return true;
1508        }
1509
1510        let Some(settlement_price) = self.funding_settlement_price(funding_rate.instrument_id)
1511        else {
1512            log::warn!(
1513                "Cannot settle funding for {}: no mark price or top-of-book price",
1514                funding_rate.instrument_id
1515            );
1516            return false;
1517        };
1518
1519        let settlement_currency = open_positions[0].settlement_currency;
1520        let mut valued_positions = Vec::with_capacity(open_positions.len());
1521        let mut account_adjustments: AHashMap<Currency, Money> = AHashMap::new();
1522
1523        for position in open_positions {
1524            if position.settlement_currency != settlement_currency {
1525                log::error!(
1526                    "Cannot settle funding for {}: position settlement currencies differ",
1527                    funding_rate.instrument_id
1528                );
1529                return false;
1530            }
1531
1532            let notional = match position.try_notional_value(settlement_price) {
1533                Ok(notional) => notional,
1534                Err(e) => {
1535                    log::error!(
1536                        "Cannot settle funding for position {}: invalid notional value: {e}",
1537                        position.id
1538                    );
1539                    return false;
1540                }
1541            };
1542
1543            let side = if position.signed_qty > Decimal::ZERO {
1544                -Decimal::ONE
1545            } else {
1546                Decimal::ONE
1547            };
1548            let Some(amount) = notional
1549                .as_decimal()
1550                .checked_mul(funding_rate.rate)
1551                .and_then(|value| value.checked_mul(side))
1552            else {
1553                log::error!(
1554                    "Cannot settle funding for position {}: funding amount overflow",
1555                    position.id
1556                );
1557                return false;
1558            };
1559            let pnl_change = match Money::from_decimal(amount, notional.currency) {
1560                Ok(money) => money,
1561                Err(e) => {
1562                    log::error!(
1563                        "Cannot settle funding for position {}: invalid funding amount: {e}",
1564                        position.id
1565                    );
1566                    return false;
1567                }
1568            };
1569
1570            if pnl_change.currency != settlement_currency {
1571                log::error!(
1572                    "Cannot settle funding for position {}: settlement currency {} differs from funding currency {}",
1573                    position.id,
1574                    settlement_currency,
1575                    pnl_change.currency
1576                );
1577                return false;
1578            }
1579
1580            if let Some(realized) = position.realized_pnl {
1581                if realized.currency != pnl_change.currency {
1582                    log::error!(
1583                        "Cannot settle funding for position {}: realized PnL currency {} differs from funding currency {}",
1584                        position.id,
1585                        realized.currency,
1586                        pnl_change.currency
1587                    );
1588                    return false;
1589                }
1590
1591                if realized.checked_add(pnl_change).is_none() {
1592                    log::error!(
1593                        "Cannot settle funding for position {}: realized PnL overflow",
1594                        position.id
1595                    );
1596                    return false;
1597                }
1598            }
1599            let total_adjustment =
1600                if let Some(current) = account_adjustments.get(&pnl_change.currency).copied() {
1601                    let Some(total) = current.checked_add(pnl_change) else {
1602                        log::error!(
1603                            "Cannot settle funding for {}: aggregate account adjustment overflow",
1604                            funding_rate.instrument_id
1605                        );
1606                        return false;
1607                    };
1608                    total
1609                } else {
1610                    pnl_change
1611                };
1612            account_adjustments.insert(pnl_change.currency, total_adjustment);
1613            valued_positions.push((position, pnl_change));
1614        }
1615
1616        let mut account_adjustments = account_adjustments.into_values().collect::<Vec<_>>();
1617        account_adjustments.sort_unstable_by_key(|adjustment| adjustment.currency.code);
1618
1619        if !self.frozen_account {
1620            let cache = self.cache.borrow();
1621            let Some(account) = cache.account_for_venue(&account_venue) else {
1622                log::error!("Cannot settle funding: no account for venue {account_venue}");
1623                return false;
1624            };
1625
1626            // A single-currency account holds only its base currency, so the cash
1627            // adjustment is converted there; position PnL keeps the settlement currency
1628            if let Some(base_currency) = account.base_currency() {
1629                for adjustment in &mut account_adjustments {
1630                    if adjustment.currency == base_currency {
1631                        continue;
1632                    }
1633                    let xrate = match cache.try_get_xrate(
1634                        account_venue,
1635                        adjustment.currency,
1636                        base_currency,
1637                        PriceType::Mid,
1638                    ) {
1639                        Ok(Some(xrate)) => xrate,
1640                        Ok(None) => {
1641                            log::warn!(
1642                                "Cannot settle funding for {}: no exchange rate from {} to {base_currency}",
1643                                funding_rate.instrument_id,
1644                                adjustment.currency
1645                            );
1646                            return false;
1647                        }
1648                        Err(e) => {
1649                            log::warn!(
1650                                "Cannot settle funding for {}: exchange rate from {} to {base_currency}: {e}",
1651                                funding_rate.instrument_id,
1652                                adjustment.currency
1653                            );
1654                            return false;
1655                        }
1656                    };
1657                    let Some(amount) = adjustment.as_decimal().checked_mul(xrate) else {
1658                        log::error!(
1659                            "Cannot settle funding for {}: currency conversion overflow",
1660                            funding_rate.instrument_id
1661                        );
1662                        return false;
1663                    };
1664                    *adjustment = match Money::from_decimal(amount, base_currency) {
1665                        Ok(money) => money,
1666                        Err(e) => {
1667                            log::error!(
1668                                "Cannot settle funding for {}: invalid converted adjustment: {e}",
1669                                funding_rate.instrument_id
1670                            );
1671                            return false;
1672                        }
1673                    };
1674                }
1675            }
1676
1677            for adjustment in &account_adjustments {
1678                let Some(balance) = account.balance(Some(adjustment.currency)) else {
1679                    log::error!(
1680                        "Cannot settle funding: no account balance for currency {}",
1681                        adjustment.currency
1682                    );
1683                    return false;
1684                };
1685
1686                if balance.total.checked_add(*adjustment).is_none()
1687                    || balance.free.checked_add(*adjustment).is_none()
1688                {
1689                    log::error!(
1690                        "Cannot settle funding: {} account adjustment exceeds Money bounds",
1691                        adjustment.currency
1692                    );
1693                    return false;
1694                }
1695            }
1696        }
1697
1698        let ts_init = self.clock.borrow().timestamp_ns();
1699        let settlement = FundingSettlement::new(
1700            msgbus::get_message_bus().borrow().trader_id,
1701            funding_rate.instrument_id,
1702            account_id,
1703            funding_rate.rate,
1704            settlement_price,
1705            settlement_currency,
1706            UUID4::new(),
1707            ts_event,
1708            ts_init,
1709        );
1710        let mut adjusted_positions = Vec::with_capacity(valued_positions.len());
1711        for (original, pnl_change) in valued_positions {
1712            let adjustment = PositionAdjusted::new(
1713                settlement.trader_id,
1714                original.strategy_id,
1715                original.instrument_id,
1716                original.id,
1717                original.account_id,
1718                PositionAdjustmentType::Funding,
1719                None,
1720                Some(pnl_change),
1721                Some(Ustr::from(&format!(
1722                    "funding_settlement:{}",
1723                    settlement.event_id
1724                ))),
1725                UUID4::new(),
1726                settlement.ts_event,
1727                settlement.ts_init,
1728            );
1729            adjusted_positions.push((original, adjustment));
1730        }
1731
1732        {
1733            let mut cache = self.cache.borrow_mut();
1734
1735            for (index, (original, adjustment)) in adjusted_positions.iter().enumerate() {
1736                if let Err(e) = cache.update_position_from_adjustment(original.id, *adjustment) {
1737                    log::error!(
1738                        "Cannot update position {} after funding settlement: {e}",
1739                        original.id
1740                    );
1741
1742                    // Include the failing position in case its adjustment was applied before
1743                    // a backing integrity check rejected it.
1744                    revert_funding_adjustments(
1745                        &mut cache,
1746                        &adjusted_positions[..=index],
1747                        "funding settlement",
1748                    );
1749                    return false;
1750                }
1751            }
1752        }
1753
1754        for adjustment in &account_adjustments {
1755            if !self.adjust_account_balance(*adjustment, true) {
1756                let mut cache = self.cache.borrow_mut();
1757                revert_funding_adjustments(&mut cache, &adjusted_positions, "account adjustment");
1758                return false;
1759            }
1760        }
1761
1762        self.funding_settlements.insert(settlement_key);
1763        let settlement_topic = switchboard::get_funding_settlement_topic(settlement.instrument_id);
1764        msgbus::publish_any(settlement_topic, &settlement);
1765
1766        for (_, adjustment) in adjusted_positions {
1767            let event = PositionEvent::PositionAdjusted(adjustment);
1768            let PositionEvent::PositionAdjusted(adjustment) = &event else {
1769                continue;
1770            };
1771            let topic = switchboard::get_event_position_topic(adjustment.strategy_id);
1772            msgbus::publish_position_event(topic, &event);
1773        }
1774
1775        true
1776    }
1777
1778    fn funding_settlement_price(&self, instrument_id: InstrumentId) -> Option<Price> {
1779        if let Some(mark_price) = self.cache.borrow().mark_price(&instrument_id) {
1780            return Some(mark_price.value);
1781        }
1782
1783        let bid = self.best_bid_price(instrument_id)?;
1784        let ask = self.best_ask_price(instrument_id)?;
1785        let midpoint = (bid.as_decimal() + ask.as_decimal()) / Decimal::from(2);
1786        Price::from_decimal_dp(midpoint, bid.precision.max(ask.precision)).ok()
1787    }
1788
1789    fn is_interval_funding_boundary(funding_rate: &FundingRateUpdate) -> bool {
1790        let Some(interval_mins) = funding_rate.interval else {
1791            return false;
1792        };
1793        let Ok(interval) = DurationNanos::try_from_mins(u64::from(interval_mins)) else {
1794            return false;
1795        };
1796
1797        !interval.is_zero() && funding_rate.ts_event.floor(interval) == funding_rate.ts_event
1798    }
1799
1800    fn funding_boundary(funding_rate: &FundingRateUpdate) -> Option<UnixNanos> {
1801        funding_rate.next_funding_ns.or_else(|| {
1802            Self::is_interval_funding_boundary(funding_rate).then_some(funding_rate.ts_event)
1803        })
1804    }
1805
1806    /// Advances the exchange clock and processes all pending inflight and queued trading commands
1807    /// up to `ts_now`.
1808    ///
1809    /// Does nothing while a callback failure is latched, until [`Self::reset`] clears it.
1810    /// [`Self::process_modules`] returns the latched error.
1811    ///
1812    /// # Panics
1813    ///
1814    /// Panics if the exchange clock is not a [`VirtualClock`] or popping an inflight command fails
1815    /// during processing.
1816    pub fn process(&mut self, ts_now: UnixNanos) {
1817        self.process_commands(ts_now, SettlementScope::All);
1818    }
1819
1820    pub(crate) fn process_for_scope(&mut self, ts_now: UnixNanos, scope: SettlementScope) {
1821        self.process_commands(ts_now, scope);
1822    }
1823
1824    fn process_commands(&mut self, ts_now: UnixNanos, scope: SettlementScope) {
1825        if self.callback_error.is_some() {
1826            return;
1827        }
1828
1829        self.set_clock_time(ts_now);
1830
1831        let mut deferred = Vec::new();
1832        let mut processed_timestamps = BTreeSet::new();
1833
1834        while let Some(inflight) = self.inflight_queue.peek() {
1835            if inflight.timestamp > ts_now {
1836                break;
1837            }
1838            let inflight = self.inflight_queue.pop().unwrap();
1839
1840            if !inflight.matches_scope(ts_now, scope) {
1841                deferred.push(inflight);
1842                continue;
1843            }
1844
1845            processed_timestamps.insert(inflight.timestamp);
1846            self.message_queue.push_back(inflight.command);
1847        }
1848
1849        let deferred_timestamps: BTreeSet<_> =
1850            deferred.iter().map(|inflight| inflight.timestamp).collect();
1851        self.inflight_queue.extend(deferred);
1852
1853        for timestamp in processed_timestamps.difference(&deferred_timestamps) {
1854            self.inflight_counter.remove(timestamp);
1855        }
1856
1857        while let Some(command) = self.message_queue.pop_front() {
1858            self.process_trading_command(command);
1859        }
1860    }
1861
1862    /// Runs all simulation modules for the given timestamp.
1863    ///
1864    /// Must be called once per time step after all command queues have fully
1865    /// settled, not inside the settle loop.
1866    ///
1867    /// # Errors
1868    ///
1869    /// Returns an error if a latency model or simulation module fails.
1870    /// The exchange retains the failure and rejects further processing until reset.
1871    pub fn process_modules(&mut self, ts_now: UnixNanos) -> anyhow::Result<()> {
1872        self.check_callback_error()?;
1873
1874        if self.frozen_account || self.exec_client.is_none() {
1875            return Ok(());
1876        }
1877
1878        let results = {
1879            let cache = self.cache.borrow();
1880            let ctx = ExchangeContext {
1881                venue: self.id,
1882                base_currency: self.base_currency,
1883                instruments: &self.instruments,
1884                matching_engines: &self.matching_engines,
1885                cache: &cache,
1886            };
1887            self.modules
1888                .iter()
1889                .enumerate()
1890                .map(|(module_index, module)| {
1891                    module
1892                        .process(ts_now, &ctx)
1893                        .map(|result| (module_index, result))
1894                        .map_err(|e| (module_index, e))
1895                })
1896                .collect::<Result<Vec<_>, _>>()
1897        };
1898        let results = match results {
1899            Ok(results) => results,
1900            Err((module_index, error)) => {
1901                return Err(self.store_module_error(module_index, "process", &error));
1902            }
1903        };
1904
1905        for (module_index, result) in results {
1906            if let SimulationModuleResult::Completed(adjustments) = result {
1907                let outcomes = adjustments
1908                    .into_iter()
1909                    .map(|adjustment| match self.try_adjust_account(adjustment) {
1910                        Ok(()) => AccountAdjustmentOutcome::Applied,
1911                        Err(e) => AccountAdjustmentOutcome::Failed(e),
1912                    })
1913                    .collect::<Vec<_>>();
1914
1915                if let Err(e) = self.modules[module_index].acknowledge(&outcomes) {
1916                    return Err(self.store_module_error(module_index, "acknowledge", &e));
1917                }
1918            }
1919        }
1920        Ok(())
1921    }
1922
1923    /// Resets the exchange to its initial state.
1924    ///
1925    /// # Errors
1926    ///
1927    /// Returns an error if a simulation module cannot reset.
1928    pub fn reset(&mut self) -> anyhow::Result<()> {
1929        if !self.account_at_starting_balances() {
1930            self.generate_fresh_account_state();
1931        }
1932
1933        let mut callback_error = None;
1934
1935        for (module_index, module) in self.modules.iter().enumerate() {
1936            if let Err(e) = module.reset()
1937                && callback_error.is_none()
1938            {
1939                callback_error = Some(format!(
1940                    "Simulation module {module_index} reset failed: {e:#}"
1941                ));
1942            }
1943        }
1944
1945        for (instrument_id, matching_engine) in &mut self.matching_engines {
1946            matching_engine.reset();
1947
1948            if let Some(instrument) = self.initial_instruments.get(instrument_id) {
1949                if let Err(e) = self.cache.borrow_mut().add_instrument(instrument.clone()) {
1950                    callback_error.get_or_insert_with(|| e.to_string());
1951                    continue;
1952                }
1953
1954                matching_engine.update_instrument(instrument.clone())?;
1955                self.instruments.insert(*instrument_id, instrument.clone());
1956            }
1957        }
1958
1959        self.pending_funding_rates.clear();
1960        self.funding_settlements.clear();
1961        self.message_queue.clear();
1962        self.inflight_queue.clear();
1963        self.inflight_orders.clear();
1964        self.inflight_counter.clear();
1965
1966        log::info!("Resetting exchange state");
1967        self.callback_error = callback_error;
1968        self.check_callback_error()
1969    }
1970
1971    /// Logs diagnostic information from all simulation modules.
1972    ///
1973    /// # Errors
1974    ///
1975    /// Returns an error if a simulation module cannot produce its diagnostics.
1976    pub fn log_diagnostics(&self) -> anyhow::Result<()> {
1977        for (module_index, module) in self.modules.iter().enumerate() {
1978            module.log_diagnostics().map_err(|e| {
1979                anyhow::anyhow!("Simulation module {module_index} log_diagnostics failed: {e:#}")
1980            })?;
1981        }
1982        Ok(())
1983    }
1984
1985    /// Checks if any margin accounts have breached maintenance margin and liquidates open
1986    /// positions when the trigger threshold is met.
1987    ///
1988    /// Liquidation is scoped to the breached settlement currency: only positions whose
1989    /// instrument settles in the same currency as the breached margin account are closed.
1990    /// Positions settled in other currencies remain open, isolating the liquidation to
1991    /// the currency whose equity fell below the maintenance threshold.
1992    ///
1993    /// > **Note**: A future `cross_margin_mode` venue configuration could extend this to
1994    /// > liquidate all positions across all settlement currencies simultaneously.
1995    pub fn process_liquidations(&mut self, ts_now: UnixNanos) {
1996        if !self.liquidation_enabled {
1997            return;
1998        }
1999
2000        if self.frozen_account {
2001            return;
2002        }
2003
2004        let account = {
2005            let cache = self.cache.borrow();
2006            cache.account_for_venue_owned(&self.id)
2007        };
2008        let Some(account) = account else { return };
2009        let AccountAny::Margin(margin_account) = &account else {
2010            return;
2011        };
2012        let account_id = margin_account.id();
2013
2014        let currencies: Vec<Currency> = margin_account.currencies();
2015
2016        let open_positions: Vec<Position> = {
2017            let cache = self.cache.borrow();
2018            cache
2019                .positions_open(Some(&self.id), None, None, None, None)
2020                .into_iter()
2021                .map(|p| p.cloned())
2022                .collect()
2023        };
2024
2025        // Pre-bucket position indices by settlement currency to avoid repeated full scans.
2026        let mut positions_by_currency: AHashMap<Currency, Vec<usize>> = AHashMap::new();
2027        for (i, p) in open_positions.iter().enumerate() {
2028            positions_by_currency
2029                .entry(p.settlement_currency)
2030                .or_default()
2031                .push(i);
2032        }
2033
2034        for currency in currencies {
2035            let Some(balance) = margin_account.balance(Some(currency)) else {
2036                continue;
2037            };
2038            let balance_f64 = balance.total.as_f64();
2039
2040            let Some(indices) = positions_by_currency.get(&currency) else {
2041                continue;
2042            };
2043
2044            let (upnl_f64, all_priced) = {
2045                let cache = self.cache.borrow();
2046                let mut upnl = 0.0_f64;
2047                let mut all_priced = true;
2048                let mut bar_types = None;
2049
2050                for &i in indices {
2051                    let p = &open_positions[i];
2052                    if let Some(pnl) = liquidation_unrealized_pnl(&cache, p, &mut bar_types) {
2053                        upnl += pnl.as_f64();
2054                    } else {
2055                        all_priced = false;
2056                        break;
2057                    }
2058                }
2059                (upnl, all_priced)
2060            };
2061
2062            if !all_priced {
2063                continue; // defer until all positions are priced
2064            }
2065
2066            let equity = balance_f64 + upnl_f64;
2067            let maintenance = margin_account.total_maintenance_margin(currency).as_f64();
2068
2069            if maintenance == 0.0 {
2070                continue;
2071            }
2072
2073            let threshold = maintenance * self.liquidation_trigger_ratio;
2074
2075            if equity > threshold {
2076                continue;
2077            }
2078
2079            log::warn!(
2080                "LIQUIDATION triggered for account {} currency {}: equity={:.4} <= threshold={:.4} (maintenance={:.4} x ratio={})",
2081                account_id,
2082                currency,
2083                equity,
2084                threshold,
2085                maintenance,
2086                self.liquidation_trigger_ratio
2087            );
2088
2089            for matching_engine in self.matching_engines.values_mut() {
2090                matching_engine.liquidate_open_positions(
2091                    ts_now,
2092                    self.liquidation_cancel_open_orders,
2093                    currency,
2094                );
2095            }
2096        }
2097
2098        self.drain_oto_commands();
2099    }
2100
2101    fn process_trading_command(&mut self, command: TradingCommand) {
2102        self.inflight_orders.remove(&command);
2103        let instrument_id = command.instrument_id();
2104        assert!(
2105            self.matching_engines.contains_key(&instrument_id),
2106            "Matching engine not found for instrument {instrument_id}",
2107        );
2108
2109        let command = match command {
2110            TradingCommand::ModifyOrder(ref command)
2111                if self.process_modify_submitted_order(command) =>
2112            {
2113                return;
2114            }
2115            TradingCommand::ModifyOrders(mut command) => {
2116                command
2117                    .modifies
2118                    .retain(|modify| !self.process_modify_submitted_order(modify));
2119
2120                if command.modifies.is_empty() {
2121                    return;
2122                }
2123                TradingCommand::ModifyOrders(command)
2124            }
2125            command => command,
2126        };
2127
2128        let account_id = if let Some(exec_client) = &self.exec_client {
2129            exec_client.account_id()
2130        } else {
2131            panic!("Execution client should be initialized");
2132        };
2133
2134        if let TradingCommand::SubmitOrderList(ref command) = command {
2135            let mut orders: Vec<OrderAny> = self
2136                .cache
2137                .borrow()
2138                .orders_for_ids(&command.order_list.client_order_ids, command);
2139
2140            for order in &mut orders {
2141                let order_instrument_id = order.instrument_id();
2142                if let Some(matching_engine) = self.matching_engines.get_mut(&order_instrument_id) {
2143                    matching_engine.process_order(order, account_id);
2144                } else {
2145                    panic!("Matching engine not found for instrument {order_instrument_id}");
2146                }
2147            }
2148
2149            self.drain_oto_commands();
2150            return;
2151        }
2152
2153        if let Some(matching_engine) = self.matching_engines.get_mut(&instrument_id) {
2154            match command {
2155                TradingCommand::SubmitOrder(command) => {
2156                    let mut order = self
2157                        .cache
2158                        .borrow()
2159                        .order(&command.client_order_id)
2160                        .map(|o| o.clone())
2161                        .expect("Order must exist in cache");
2162                    matching_engine.process_order(&mut order, account_id);
2163                }
2164                TradingCommand::ModifyOrder(ref command) => {
2165                    matching_engine.process_modify(command, account_id);
2166                }
2167                TradingCommand::ModifyOrders(ref command) => {
2168                    matching_engine.process_batch_modify(command, account_id);
2169                }
2170                TradingCommand::CancelOrder(ref command) => {
2171                    matching_engine.process_cancel(command, account_id);
2172                }
2173                TradingCommand::CancelOrders(ref command) => {
2174                    matching_engine.process_batch_cancel(command, account_id);
2175                }
2176                TradingCommand::CancelAllOrders(ref command) => {
2177                    matching_engine.process_cancel_all(command, account_id);
2178                }
2179                _ => {}
2180            }
2181        } else {
2182            panic!("Matching engine not found for instrument {instrument_id}");
2183        }
2184
2185        self.drain_oto_commands();
2186    }
2187
2188    fn drain_oto_commands(&mut self) {
2189        while let Some(command) = self.matching_orders.pop_command() {
2190            let instrument_id = command.instrument_id();
2191            if let Some(engine) = self.matching_engines.get_mut(&instrument_id) {
2192                engine.process_oto_command(&command);
2193            } else {
2194                log::error!("Cannot process OTO action: no matching engine for {instrument_id}");
2195            }
2196
2197            if let OtoCommand::Release {
2198                parent_quantity: Some(quantity),
2199                parent_order_id,
2200                parent_instrument_id,
2201                ..
2202            } = command
2203                && let Some(engine) = self.matching_engines.get_mut(&parent_instrument_id)
2204            {
2205                engine.process_oto_resize(parent_order_id, quantity);
2206            }
2207        }
2208    }
2209
2210    fn process_modify_submitted_order(&self, command: &ModifyOrder) -> bool {
2211        let Some(order) = self
2212            .cache
2213            .borrow()
2214            .order(&command.client_order_id)
2215            .map(|o| o.clone())
2216        else {
2217            return false;
2218        };
2219
2220        let modifies_submitted_order = matches!(order.status(), OrderStatus::Submitted)
2221            || (matches!(order.status(), OrderStatus::PendingUpdate)
2222                && order
2223                    .previous_status()
2224                    .is_some_and(|status| matches!(status, OrderStatus::Submitted)));
2225
2226        if !modifies_submitted_order {
2227            return false;
2228        }
2229
2230        self.generate_order_updated(
2231            &order,
2232            command.quantity.unwrap_or_else(|| order.quantity()),
2233            command.price.or_else(|| order.price()),
2234            command.trigger_price.or_else(|| order.trigger_price()),
2235        );
2236        true
2237    }
2238
2239    fn generate_order_updated(
2240        &self,
2241        order: &OrderAny,
2242        quantity: Quantity,
2243        price: Option<Price>,
2244        trigger_price: Option<Price>,
2245    ) {
2246        let ts_now = self.clock.borrow().timestamp_ns();
2247        let event = OrderEventAny::Updated(OrderUpdated::new(
2248            order.trader_id(),
2249            order.strategy_id(),
2250            order.instrument_id(),
2251            order.client_order_id(),
2252            quantity,
2253            UUID4::new(),
2254            ts_now,
2255            ts_now,
2256            false,
2257            order.venue_order_id(),
2258            order.account_id(),
2259            price,
2260            trigger_price,
2261            None,
2262            order.is_quote_quantity(),
2263        ));
2264        self.dispatch_order_event(event);
2265    }
2266
2267    fn dispatch_order_event(&self, event: OrderEventAny) {
2268        if let Some(handler) = &self.event_handler {
2269            handler(event);
2270        } else {
2271            msgbus::send_order_event(MessagingSwitchboard::exec_engine_process(), event);
2272        }
2273    }
2274
2275    fn account_at_starting_balances(&self) -> bool {
2276        let Some(account) = self.get_account() else {
2277            return false;
2278        };
2279
2280        let balances = account.balances();
2281
2282        for starting in &self.starting_balances {
2283            let Some(balance) = balances.get(&starting.currency) else {
2284                return false;
2285            };
2286
2287            if balance.total != *starting || balance.free != *starting {
2288                return false;
2289            }
2290        }
2291
2292        true
2293    }
2294
2295    fn generate_fresh_account_state(&self) {
2296        let balances: Vec<AccountBalance> = self
2297            .starting_balances
2298            .iter()
2299            .map(|money| AccountBalance::new(*money, Money::zero(money.currency), *money))
2300            .collect();
2301
2302        if let Some(exec_client) = &self.exec_client {
2303            let ts_event = self.clock.borrow().timestamp_ns();
2304            exec_client
2305                .generate_account_state(balances, vec![], true, ts_event, None)
2306                .unwrap();
2307        }
2308
2309        let calculate_account_state = !self.frozen_account;
2310
2311        if let Some(mut account) = self.get_account() {
2312            account.set_calculate_account_state(calculate_account_state);
2313
2314            match &mut account {
2315                AccountAny::Margin(margin_account) => {
2316                    margin_account.set_default_leverage(self.default_leverage);
2317                    for (instrument_id, leverage) in &self.leverages {
2318                        margin_account.set_leverage(*instrument_id, *leverage);
2319                    }
2320
2321                    if let Some(model) = &self.margin_model {
2322                        margin_account.set_margin_model(model.clone());
2323                    }
2324                }
2325                AccountAny::Cash(cash_account) => {
2326                    cash_account.allow_borrowing = self.allow_cash_borrowing;
2327                }
2328                AccountAny::Betting(_) | AccountAny::Wallet(_) => {}
2329            }
2330
2331            self.cache.borrow_mut().update_account(&account).unwrap();
2332        }
2333    }
2334}
2335
2336#[derive(Clone, Copy)]
2337pub(crate) enum SettlementScope {
2338    All,
2339    Data(Option<InstrumentId>),
2340}
2341
2342/// Marks the window in which order events are routed to the deferred handler, and clears
2343/// it on drop so an unwind cannot leave the exchange deferring every later event.
2344#[derive(Debug)]
2345struct DeferEventsGuard {
2346    deferring: Rc<Cell<bool>>,
2347}
2348
2349impl DeferEventsGuard {
2350    fn new(deferring: Rc<Cell<bool>>) -> Self {
2351        deferring.set(true);
2352        Self { deferring }
2353    }
2354}
2355
2356impl Drop for DeferEventsGuard {
2357    fn drop(&mut self) {
2358        self.deferring.set(false);
2359    }
2360}
2361
2362// Reverts funding adjustments applied in place, newest first, restoring and persisting each
2363// position from the snapshot taken before settlement
2364fn revert_funding_adjustments(
2365    cache: &mut Cache,
2366    adjusted: &[(Position, PositionAdjusted)],
2367    failed_step: &str,
2368) {
2369    for (original, _) in adjusted.iter().rev() {
2370        if let Err(e) = cache.revert_position_adjustment(original) {
2371            log::error!(
2372                "Cannot roll back position {} after failed {failed_step}: {e}",
2373                original.id
2374            );
2375        }
2376    }
2377}
2378
2379// Values a position for the liquidation check with the portfolio's price fallback: mark price,
2380// then the side-appropriate quote, then the last trade, then the most recent bar close.
2381fn liquidation_unrealized_pnl(
2382    cache: &Cache,
2383    position: &Position,
2384    bar_types: &mut Option<AHashMap<InstrumentId, Vec<BarType>>>,
2385) -> Option<Money> {
2386    let instrument_id = &position.instrument_id;
2387    let price_type = match position.side {
2388        PositionSide::Long => PriceType::Bid,
2389        PositionSide::Short => PriceType::Ask,
2390        PositionSide::Flat => return Some(Money::zero(position.settlement_currency)),
2391    };
2392
2393    let allows_non_positive = || {
2394        cache
2395            .instrument(instrument_id)
2396            .is_some_and(Instrument::allows_negative_price)
2397    };
2398    let is_valid = |price: &Price| {
2399        !price.is_undefined()
2400            && !price.is_error()
2401            && (price.as_decimal() > Decimal::ZERO || allows_non_positive())
2402    };
2403    let quote_price = || {
2404        cache.quote(instrument_id).and_then(|quote| {
2405            let (price, size) = match price_type {
2406                PriceType::Bid => (quote.bid_price, quote.bid_size),
2407                _ => (quote.ask_price, quote.ask_size),
2408            };
2409            (is_valid(&price) && (price.as_decimal() > Decimal::ZERO || size.is_positive()))
2410                .then_some(price)
2411        })
2412    };
2413
2414    // Bars closing together rank in the fallback order above, then mid, then the opposite quote
2415    // side, then by bar type, so the choice never depends on cache iteration order.
2416    let bar_rank = |bar: &Bar| match bar.bar_type.spec().price_type {
2417        PriceType::Mark => 0,
2418        bar_price_type if bar_price_type == price_type => 1,
2419        PriceType::Last => 2,
2420        PriceType::Mid => 3,
2421        PriceType::Bid | PriceType::Ask => 4,
2422    };
2423
2424    // In a backtest `ts_init` is the bar close for open- and close-stamped bars alike
2425    let bar_close = || {
2426        // Index once per currency valuation, before any liquidation callbacks can change the cache
2427        let bar_types = bar_types.get_or_insert_with(|| liquidation_bar_types(cache));
2428        bar_types
2429            .get(instrument_id)
2430            .into_iter()
2431            .flatten()
2432            .filter_map(|bar_type| cache.bar(bar_type))
2433            .filter(|bar| is_valid(&bar.close))
2434            .min_by_key(|bar| (Reverse(bar.ts_init), bar_rank(bar), bar.bar_type))
2435            .map(|bar| bar.close)
2436    };
2437
2438    let Some(price) = cache
2439        .price(instrument_id, PriceType::Mark)
2440        .filter(is_valid)
2441        .or_else(quote_price)
2442        .or_else(|| cache.price(instrument_id, PriceType::Last).filter(is_valid))
2443        .or_else(bar_close)
2444    else {
2445        log::warn!(
2446            "Cannot value {} for liquidation, no mark, quote, trade or bar for {instrument_id}",
2447            position.id,
2448        );
2449        return None;
2450    };
2451
2452    position
2453        .try_unrealized_pnl(price)
2454        .inspect_err(|e| {
2455            log::error!("Cannot calculate unrealized PnL for {}: {e}", position.id);
2456        })
2457        .ok()
2458}
2459
2460fn liquidation_bar_types(cache: &Cache) -> AHashMap<InstrumentId, Vec<BarType>> {
2461    let mut by_instrument: AHashMap<InstrumentId, Vec<BarType>> = AHashMap::new();
2462
2463    for source in [AggregationSource::External, AggregationSource::Internal] {
2464        for bar_type in cache.bar_types(None, None, source) {
2465            by_instrument
2466                .entry(bar_type.instrument_id())
2467                .or_default()
2468                .push(*bar_type);
2469        }
2470    }
2471
2472    by_instrument
2473}
2474
2475// Compares two instruments' tradable definitions on their serialized form without event
2476// timestamps, so every field (including free-form `info`) takes part, and a serialization
2477// failure compares as changed so a different definition is never accepted.
2478fn instrument_definitions_match(a: &InstrumentAny, b: &InstrumentAny) -> bool {
2479    fn normalized(instrument: &InstrumentAny) -> Option<serde_json::Value> {
2480        let mut value = serde_json::to_value(instrument).ok()?;
2481
2482        if let Some(definition) = value
2483            .as_object_mut()
2484            .and_then(|obj| obj.values_mut().next())
2485            .and_then(serde_json::Value::as_object_mut)
2486        {
2487            definition.remove("ts_event");
2488            definition.remove("ts_init");
2489        }
2490
2491        Some(value)
2492    }
2493
2494    match (normalized(a), normalized(b)) {
2495        (Some(a), Some(b)) => a == b,
2496        _ => false,
2497    }
2498}
2499
2500#[cfg(test)]
2501mod tests {
2502    use nautilus_common::messages::execution::{QueryAccount, QueryOrder, SubmitOrder};
2503    use nautilus_core::DurationNanos;
2504    use nautilus_execution::models::{
2505        fee::{FeeModelAny, MakerTakerFeeModel},
2506        latency::{LatencyModelHandle, StaticLatencyModel},
2507    };
2508    use nautilus_model::{
2509        accounts::MarginAccount,
2510        data::BarSpecification,
2511        enums::{AccountType, BarAggregation, BookType, OrderSide, OrderType},
2512        events::AccountState,
2513        identifiers::{ClientOrderId, StrategyId, TradeId, TraderId},
2514        instruments::{
2515            CurrencyPair, InstrumentAny,
2516            stubs::{audusd_sim, futures_contract_es, gbpusd_sim},
2517        },
2518        orders::{OrderTestBuilder, stubs::TestOrderEventStubs},
2519        stubs::TestDefault,
2520        types::{
2521            AccountBalance,
2522            price::{PRICE_ERROR, PRICE_UNDEF},
2523        },
2524    };
2525    use rstest::rstest;
2526    use rust_decimal_macros::dec;
2527
2528    use super::*;
2529
2530    #[derive(Clone, Copy)]
2531    enum LiquidationPriceSource {
2532        Mark,
2533        Quote,
2534        Trade,
2535        Bar,
2536    }
2537
2538    #[rstest]
2539    #[case::mark(LiquidationPriceSource::Mark)]
2540    #[case::quote(LiquidationPriceSource::Quote)]
2541    #[case::trade(LiquidationPriceSource::Trade)]
2542    #[case::bar(LiquidationPriceSource::Bar)]
2543    fn test_liquidation_rejects_sentinel_prices(
2544        #[case] source: LiquidationPriceSource,
2545        #[values(
2546            InstrumentAny::CurrencyPair(audusd_sim()),
2547            InstrumentAny::FuturesContract(futures_contract_es(None, None))
2548        )]
2549        instrument: InstrumentAny,
2550        #[values(OrderSide::Buy, OrderSide::Sell)] side: OrderSide,
2551        #[values(Price::from_raw(PRICE_UNDEF, 0), Price::from_raw(PRICE_ERROR, 0))] sentinel: Price,
2552        #[values(false, true)] has_fallback: bool,
2553    ) {
2554        let mut cache = Cache::default();
2555        cache.add_instrument(instrument.clone()).unwrap();
2556        let position = liquidation_position(&instrument, side);
2557        let ts = UnixNanos::from(2);
2558        let bar_spec = BarSpecification::new(1, BarAggregation::Minute, PriceType::Last);
2559        let bar_type = BarType::new(instrument.id(), bar_spec, AggregationSource::External);
2560
2561        if has_fallback {
2562            let value = match side {
2563                OrderSide::Buy => dec!(90),
2564                OrderSide::Sell => dec!(110),
2565            };
2566
2567            let close = Price::from_decimal_dp(value, instrument.price_precision()).unwrap();
2568
2569            let bar = Bar::new(
2570                bar_type,
2571                close,
2572                close,
2573                close,
2574                close,
2575                Quantity::from("1"),
2576                ts,
2577                ts,
2578            );
2579            cache.add_bar(bar).unwrap();
2580        }
2581
2582        match source {
2583            LiquidationPriceSource::Mark => {
2584                let mark = MarkPriceUpdate::new(instrument.id(), sentinel, ts, ts);
2585                cache.add_mark_price(mark).unwrap();
2586            }
2587            LiquidationPriceSource::Quote => {
2588                let valid = Price::from("100");
2589                let (bid, ask) = match side {
2590                    OrderSide::Buy => (sentinel, valid),
2591                    OrderSide::Sell => (valid, sentinel),
2592                };
2593
2594                let quote = QuoteTick::new(
2595                    instrument.id(),
2596                    bid,
2597                    ask,
2598                    Quantity::from("1"),
2599                    Quantity::from("2"),
2600                    ts,
2601                    ts,
2602                );
2603                cache.add_quote(quote).unwrap();
2604            }
2605            LiquidationPriceSource::Trade => {
2606                let trade = TradeTick::new(
2607                    instrument.id(),
2608                    sentinel,
2609                    Quantity::from("1"),
2610                    AggressorSide::Sell,
2611                    TradeId::from("T-SENTINEL"),
2612                    ts,
2613                    ts,
2614                );
2615                cache.add_trade(trade).unwrap();
2616            }
2617            LiquidationPriceSource::Bar => {
2618                let invalid_spec =
2619                    BarSpecification::new(1, BarAggregation::Second, PriceType::Last);
2620                let invalid_type =
2621                    BarType::new(instrument.id(), invalid_spec, AggregationSource::Internal);
2622                let later = UnixNanos::from(3);
2623
2624                let bar = Bar::new(
2625                    invalid_type,
2626                    sentinel,
2627                    sentinel,
2628                    sentinel,
2629                    sentinel,
2630                    Quantity::from("1"),
2631                    later,
2632                    later,
2633                );
2634                cache.add_bar(bar).unwrap();
2635            }
2636        }
2637
2638        let mut bar_types = None;
2639        let actual = liquidation_unrealized_pnl(&cache, &position, &mut bar_types);
2640
2641        let expected = has_fallback.then(|| {
2642            let amount = dec!(-10) * instrument.multiplier().as_decimal();
2643            Money::from_decimal(amount, instrument.settlement_currency()).unwrap()
2644        });
2645
2646        assert_eq!(actual, expected);
2647    }
2648
2649    #[rstest]
2650    #[case(false)]
2651    #[case(true)]
2652    fn test_liquidation_bar_index_keeps_instruments_and_sides_separate(#[case] reverse: bool) {
2653        let audusd = InstrumentAny::CurrencyPair(audusd_sim());
2654        let gbpusd = InstrumentAny::CurrencyPair(gbpusd_sim());
2655        let mut cache = Cache::default();
2656        for instrument in [&audusd, &gbpusd] {
2657            cache.add_instrument(instrument.clone()).unwrap();
2658        }
2659
2660        let ts = UnixNanos::from(2);
2661
2662        for (instrument, price_type, value, source) in [
2663            (
2664                &audusd,
2665                PriceType::Bid,
2666                dec!(90),
2667                AggregationSource::External,
2668            ),
2669            (
2670                &audusd,
2671                PriceType::Ask,
2672                dec!(110),
2673                AggregationSource::Internal,
2674            ),
2675            (
2676                &gbpusd,
2677                PriceType::Last,
2678                dec!(100),
2679                AggregationSource::External,
2680            ),
2681        ] {
2682            let spec = BarSpecification::new(1, BarAggregation::Minute, price_type);
2683            let bar_type = BarType::new(instrument.id(), spec, source);
2684            let close = Price::from_decimal_dp(value, instrument.price_precision()).unwrap();
2685
2686            let bar = Bar::new(
2687                bar_type,
2688                close,
2689                close,
2690                close,
2691                close,
2692                Quantity::from("1"),
2693                ts,
2694                ts,
2695            );
2696            cache.add_bar(bar).unwrap();
2697        }
2698
2699        let mut positions = [
2700            (liquidation_position(&audusd, OrderSide::Buy), dec!(-10)),
2701            (liquidation_position(&audusd, OrderSide::Sell), dec!(-10)),
2702            (liquidation_position(&gbpusd, OrderSide::Buy), dec!(0)),
2703        ];
2704
2705        if reverse {
2706            positions.reverse();
2707        }
2708
2709        let mut bar_types = None;
2710        let actual: Vec<_> = positions
2711            .iter()
2712            .map(|(position, _)| liquidation_unrealized_pnl(&cache, position, &mut bar_types))
2713            .collect();
2714        let expected: Vec<_> = positions
2715            .iter()
2716            .map(|(_, amount)| Some(Money::from_decimal(*amount, Currency::USD()).unwrap()))
2717            .collect();
2718
2719        assert_eq!(actual, expected);
2720    }
2721
2722    fn liquidation_position(instrument: &InstrumentAny, side: OrderSide) -> Position {
2723        let order = OrderTestBuilder::new(OrderType::Market)
2724            .instrument_id(instrument.id())
2725            .side(side)
2726            .quantity(Quantity::from("1"))
2727            .build();
2728        let price = Price::from_decimal_dp(dec!(100), instrument.price_precision()).unwrap();
2729        let fill = TestOrderEventStubs::filled(
2730            &order,
2731            instrument,
2732            None,
2733            None,
2734            Some(price),
2735            None,
2736            None,
2737            None,
2738            None,
2739            None,
2740        );
2741        Position::new(instrument, fill.into())
2742    }
2743
2744    /// The three `send` dispatch modes a query must be intercepted ahead of.
2745    #[derive(Clone, Copy)]
2746    enum Dispatch {
2747        /// `use_message_queue = true` with a latency model: `inflight_queue`.
2748        Latency,
2749        /// `use_message_queue = true`, no latency: `message_queue`.
2750        Queued,
2751        /// `use_message_queue = false`: synchronous `process_trading_command`.
2752        Immediate,
2753    }
2754
2755    fn setup_exchange(dispatch: Dispatch) -> SimulatedExchange {
2756        let cache = Rc::new(RefCell::new(Cache::default()));
2757        let clock: Rc<RefCell<dyn Clock>> = Rc::new(RefCell::new(VirtualClock::new()));
2758        let mut config = SimulatedVenueConfig::builder()
2759            .venue(Venue::new("SIM"))
2760            .oms_type(OmsType::Netting)
2761            .account_type(AccountType::Margin)
2762            .book_type(BookType::L2_MBP)
2763            .starting_balances(vec![Money::new(1_000.0, Currency::USD())])
2764            .fee_model(FeeModelAny::MakerTaker(MakerTakerFeeModel::zero()).into())
2765            .build()
2766            .unwrap();
2767
2768        match dispatch {
2769            Dispatch::Latency => {
2770                config.latency_model = Some(LatencyModelHandle::new(StaticLatencyModel::new(
2771                    DurationNanos::default(),
2772                    DurationNanos::default(),
2773                    DurationNanos::default(),
2774                    DurationNanos::default(),
2775                )));
2776            }
2777            Dispatch::Queued => {} // Defaults: use_message_queue = true, no latency
2778            Dispatch::Immediate => config.use_message_queue = false,
2779        }
2780
2781        SimulatedExchange::new(config, cache, clock).unwrap()
2782    }
2783
2784    #[rstest]
2785    fn test_modify_order_priority_config_reaches_matching_engine(
2786        #[values(
2787            OrderPriorityResetPolicy::PriceChange,
2788            OrderPriorityResetPolicy::PriceOrQuantityIncrease,
2789            OrderPriorityResetPolicy::AnyModify
2790        )]
2791        policy: OrderPriorityResetPolicy,
2792    ) {
2793        let cache = Rc::new(RefCell::new(Cache::default()));
2794        let clock: Rc<RefCell<dyn Clock>> = Rc::new(RefCell::new(VirtualClock::new()));
2795        let config = SimulatedVenueConfig::builder()
2796            .venue(Venue::from("SIM"))
2797            .oms_type(OmsType::Netting)
2798            .account_type(AccountType::Margin)
2799            .book_type(BookType::L2_MBP)
2800            .starting_balances(vec![Money::from("1_000 USD")])
2801            .fee_model(FeeModelAny::MakerTaker(MakerTakerFeeModel::zero()).into())
2802            .order_priority_reset_policy(policy)
2803            .build()
2804            .unwrap();
2805        let mut exchange = SimulatedExchange::new(config, cache.clone(), clock).unwrap();
2806        let instrument = InstrumentAny::CurrencyPair(audusd_sim());
2807        exchange.add_instrument(instrument.clone()).unwrap();
2808        let engine = exchange.matching_engines.get_mut(&instrument.id()).unwrap();
2809        engine.set_event_handler(Rc::new(move |event| {
2810            cache.borrow_mut().update_order(&event).unwrap();
2811        }));
2812
2813        let ids = [
2814            ClientOrderId::from("MODIFY-FIRST"),
2815            ClientOrderId::from("MODIFY-SECOND"),
2816        ];
2817
2818        for id in ids {
2819            let mut order = OrderTestBuilder::new(OrderType::Limit)
2820                .instrument_id(instrument.id())
2821                .client_order_id(id)
2822                .side(OrderSide::Buy)
2823                .price(Price::from("1.00000"))
2824                .quantity(Quantity::from("5"))
2825                .submit(true)
2826                .build();
2827            exchange
2828                .cache
2829                .borrow_mut()
2830                .add_order(order.clone(), None, None, false)
2831                .unwrap();
2832            engine.process_order(&mut order, AccountId::from("SIM-001"));
2833        }
2834
2835        let order = exchange.cache.borrow().order(&ids[0]).unwrap().clone();
2836        engine.process_modify(
2837            &ModifyOrder::new(
2838                order.trader_id(),
2839                None,
2840                order.strategy_id(),
2841                order.instrument_id(),
2842                ids[0],
2843                order.venue_order_id(),
2844                Some(Quantity::from("3")),
2845                None,
2846                None,
2847                UUID4::new(),
2848                1.into(),
2849                None,
2850                None,
2851            ),
2852            AccountId::from("SIM-001"),
2853        );
2854
2855        let expected = if policy == OrderPriorityResetPolicy::AnyModify {
2856            vec![ids[1], ids[0]]
2857        } else {
2858            ids.to_vec()
2859        };
2860
2861        assert_eq!(
2862            engine
2863                .get_core()
2864                .get_orders_bid()
2865                .iter()
2866                .map(|o| o.client_order_id)
2867                .collect::<Vec<_>>(),
2868            expected
2869        );
2870        assert_eq!(
2871            exchange.cache.borrow().order(&ids[0]).unwrap().quantity(),
2872            Quantity::from("3")
2873        );
2874    }
2875
2876    #[rstest]
2877    fn test_replay_instrument_expiration_change_is_rejected() {
2878        let mut exchange = setup_exchange(Dispatch::Queued);
2879        let mut option = nautilus_model::instruments::stubs::option_contract_appl();
2880        option.id = InstrumentId::from("TEST.SIM");
2881        let original = InstrumentAny::OptionContract(option.clone());
2882        exchange.add_instrument(original.clone()).unwrap();
2883        exchange.update_instrument(&original).unwrap();
2884        option.expiration_ns = UnixNanos::from(10);
2885
2886        let error = exchange
2887            .update_instrument(&InstrumentAny::OptionContract(option))
2888            .unwrap_err();
2889
2890        assert!(error.to_string().contains("Cannot change expiration"));
2891        let cache = exchange.cache.borrow();
2892        for instrument in [
2893            &exchange.instruments[&original.id()],
2894            &exchange.matching_engines[&original.id()].instrument,
2895            cache.instrument(&original.id()).unwrap(),
2896        ] {
2897            assert_eq!(instrument.expiration_ns(), original.expiration_ns());
2898        }
2899    }
2900
2901    #[rstest]
2902    #[case(false)]
2903    #[case(true)]
2904    fn test_liquidation_enabled(#[case] expected: bool) {
2905        let cache = Rc::new(RefCell::new(Cache::default()));
2906        let clock: Rc<RefCell<dyn Clock>> = Rc::new(RefCell::new(VirtualClock::new()));
2907        let config = SimulatedVenueConfig::builder()
2908            .venue(Venue::new("SIM"))
2909            .oms_type(OmsType::Netting)
2910            .account_type(AccountType::Margin)
2911            .book_type(BookType::L1_MBP)
2912            .starting_balances(vec![Money::new(1_000.0, Currency::USD())])
2913            .liquidation_enabled(expected)
2914            .fee_model(FeeModelAny::MakerTaker(MakerTakerFeeModel::zero()).into())
2915            .build()
2916            .unwrap();
2917        let exchange = SimulatedExchange::new(config, cache, clock).unwrap();
2918
2919        assert_eq!(exchange.liquidation_enabled(), expected);
2920    }
2921
2922    #[rstest]
2923    #[case(AccountType::Margin, Decimal::from(10))]
2924    #[case(AccountType::Cash, Decimal::ONE)]
2925    fn test_default_leverage_uses_account_type(
2926        #[case] account_type: AccountType,
2927        #[case] expected: Decimal,
2928    ) {
2929        let config = SimulatedVenueConfig::builder()
2930            .venue(Venue::new("SIM"))
2931            .oms_type(OmsType::Netting)
2932            .account_type(account_type)
2933            .book_type(BookType::L1_MBP)
2934            .starting_balances(vec![Money::from("1_000 USD")])
2935            .fee_model(FeeModelAny::MakerTaker(MakerTakerFeeModel::zero()).into())
2936            .build()
2937            .unwrap();
2938        let cache = Rc::new(RefCell::new(Cache::default()));
2939        let clock: Rc<RefCell<dyn Clock>> = Rc::new(RefCell::new(VirtualClock::new()));
2940
2941        let exchange = SimulatedExchange::new(config, cache, clock).unwrap();
2942
2943        assert_eq!(exchange.default_leverage, expected);
2944    }
2945
2946    fn query_order() -> TradingCommand {
2947        TradingCommand::QueryOrder(QueryOrder::new(
2948            TraderId::test_default(),
2949            None,
2950            StrategyId::test_default(),
2951            InstrumentId::from("AUD/USD.SIM"),
2952            ClientOrderId::from("O-001"),
2953            None,
2954            UUID4::new(),
2955            UnixNanos::default(),
2956            None,
2957            None,
2958        ))
2959    }
2960
2961    fn query_account() -> TradingCommand {
2962        TradingCommand::QueryAccount(QueryAccount::new(
2963            TraderId::test_default(),
2964            None,
2965            AccountId::test_default(),
2966            UUID4::new(),
2967            UnixNanos::default(),
2968            None,
2969            None,
2970        ))
2971    }
2972
2973    #[rstest]
2974    fn test_inflight_command_matches_settlement_scope() {
2975        let inflight = InflightCommand::new(UnixNanos::from(1), 0, query_order());
2976        let instrument_id = InstrumentId::from("AUD/USD.SIM");
2977        let other_id = InstrumentId::from("GBP/USD.SIM");
2978
2979        assert!(inflight.matches_scope(UnixNanos::from(1), SettlementScope::All));
2980        assert!(inflight.matches_scope(
2981            UnixNanos::from(1),
2982            SettlementScope::Data(Some(instrument_id)),
2983        ));
2984        assert!(
2985            !inflight.matches_scope(UnixNanos::from(1), SettlementScope::Data(Some(other_id)),)
2986        );
2987        assert!(!inflight.matches_scope(UnixNanos::from(1), SettlementScope::Data(None)));
2988        assert!(inflight.matches_scope(UnixNanos::default(), SettlementScope::Data(None)));
2989    }
2990
2991    #[rstest]
2992    #[case(Dispatch::Latency)]
2993    #[case(Dispatch::Queued)]
2994    #[case(Dispatch::Immediate)]
2995    fn test_send_query_order_is_no_op(#[case] dispatch: Dispatch) {
2996        let mut exchange = setup_exchange(dispatch);
2997
2998        exchange.send(query_order());
2999
3000        assert!(!exchange.has_pending_commands(UnixNanos::from(u64::MAX)));
3001        assert_eq!(exchange.max_inflight_command_ts(), None);
3002    }
3003
3004    #[rstest]
3005    #[case(Dispatch::Latency)]
3006    #[case(Dispatch::Queued)]
3007    #[case(Dispatch::Immediate)]
3008    fn test_send_query_account_is_no_op(#[case] dispatch: Dispatch) {
3009        let mut exchange = setup_exchange(dispatch);
3010
3011        exchange.send(query_account());
3012
3013        assert!(!exchange.has_pending_commands(UnixNanos::from(u64::MAX)));
3014        assert_eq!(exchange.max_inflight_command_ts(), None);
3015    }
3016
3017    #[rstest]
3018    fn test_add_instrument_raw_id_overflow_does_not_mutate_maps(audusd_sim: CurrencyPair) {
3019        let mut exchange = setup_exchange(Dispatch::Immediate);
3020        exchange.last_raw_id = u32::MAX;
3021
3022        let result = exchange.add_instrument(InstrumentAny::CurrencyPair(audusd_sim));
3023
3024        assert!(result.is_err());
3025        assert!(exchange.instruments.is_empty());
3026        assert!(exchange.matching_engines.is_empty());
3027        assert_eq!(exchange.last_raw_id, u32::MAX);
3028    }
3029
3030    #[rstest]
3031    fn test_add_identical_instrument_is_noop(audusd_sim: CurrencyPair) {
3032        let mut exchange = setup_exchange(Dispatch::Immediate);
3033        exchange
3034            .add_instrument(InstrumentAny::CurrencyPair(audusd_sim.clone()))
3035            .unwrap();
3036
3037        let mut restamped = audusd_sim.clone();
3038        restamped.ts_event = UnixNanos::from(1);
3039        restamped.ts_init = UnixNanos::from(1);
3040        exchange
3041            .add_instrument(InstrumentAny::CurrencyPair(restamped))
3042            .unwrap();
3043
3044        assert_eq!(exchange.instruments.len(), 1);
3045        assert_eq!(exchange.matching_engines.len(), 1);
3046        assert_eq!(exchange.matching_engines[&audusd_sim.id].raw_id, 1);
3047        assert_eq!(exchange.last_raw_id, 1);
3048        assert_eq!(
3049            exchange.instruments[&audusd_sim.id].ts_init(),
3050            UnixNanos::default()
3051        );
3052    }
3053
3054    #[rstest]
3055    #[case::price_increment(|pair: &mut CurrencyPair| {
3056        pair.price_precision = 4;
3057        pair.price_increment = Price::from("0.0001");
3058    })]
3059    #[case::lot_size(|pair: &mut CurrencyPair| pair.lot_size = Some(Quantity::from(100)))]
3060    #[case::margin_init(|pair: &mut CurrencyPair| pair.margin_init = dec!(0.5))]
3061    #[case::max_quantity(|pair: &mut CurrencyPair| pair.max_quantity = Some(Quantity::from(10)))]
3062    fn test_add_changed_instrument_is_rejected_without_state_change(
3063        audusd_sim: CurrencyPair,
3064        #[case] change: fn(&mut CurrencyPair),
3065    ) {
3066        let mut exchange = setup_exchange(Dispatch::Immediate);
3067        exchange
3068            .add_instrument(InstrumentAny::CurrencyPair(audusd_sim.clone()))
3069            .unwrap();
3070        let mut changed = audusd_sim.clone();
3071        change(&mut changed);
3072
3073        let result = exchange.add_instrument(InstrumentAny::CurrencyPair(changed));
3074
3075        assert_eq!(
3076            result.unwrap_err().to_string(),
3077            "Instrument AUD/USD.SIM is already registered with a different definition"
3078        );
3079        assert_eq!(exchange.instruments.len(), 1);
3080        assert_eq!(exchange.matching_engines.len(), 1);
3081        assert_eq!(exchange.matching_engines[&audusd_sim.id].raw_id, 1);
3082        assert_eq!(exchange.last_raw_id, 1);
3083        assert_eq!(
3084            serde_json::to_value(&exchange.instruments[&audusd_sim.id]).unwrap(),
3085            serde_json::to_value(InstrumentAny::CurrencyPair(audusd_sim)).unwrap()
3086        );
3087    }
3088
3089    #[rstest]
3090    fn test_reset_clears_inflight_counter() {
3091        let mut exchange = setup_exchange(Dispatch::Latency);
3092        let account = MarginAccount::new(
3093            AccountState::new(
3094                AccountId::test_default(),
3095                AccountType::Margin,
3096                vec![AccountBalance::new(
3097                    Money::from("1000 USD"),
3098                    Money::from("0 USD"),
3099                    Money::from("1000 USD"),
3100                )],
3101                vec![],
3102                false,
3103                UUID4::default(),
3104                UnixNanos::default(),
3105                UnixNanos::default(),
3106                None,
3107            ),
3108            false,
3109        );
3110        exchange
3111            .cache
3112            .borrow_mut()
3113            .add_account(AccountAny::Margin(account))
3114            .unwrap();
3115
3116        let order = OrderTestBuilder::new(OrderType::Limit)
3117            .instrument_id(InstrumentId::from("AUD/USD.SIM"))
3118            .client_order_id(ClientOrderId::from("O-RESET"))
3119            .side(OrderSide::Buy)
3120            .quantity(Quantity::from("1"))
3121            .price(Price::from("1.00000"))
3122            .build();
3123        exchange
3124            .cache
3125            .borrow_mut()
3126            .add_order(order.clone(), None, None, false)
3127            .unwrap();
3128        exchange
3129            .cache
3130            .borrow_mut()
3131            .update_order(&TestOrderEventStubs::submitted(
3132                &order,
3133                AccountId::test_default(),
3134            ))
3135            .unwrap();
3136        exchange.send(TradingCommand::SubmitOrder(SubmitOrder::new(
3137            TraderId::test_default(),
3138            None,
3139            StrategyId::test_default(),
3140            order.instrument_id(),
3141            order.client_order_id(),
3142            order.init_event().clone(),
3143            None,
3144            None,
3145            None,
3146            UUID4::default(),
3147            UnixNanos::from(100),
3148            None,
3149        )));
3150
3151        assert_eq!(exchange.inflight_counter.len(), 1);
3152
3153        exchange.reset().unwrap();
3154
3155        assert!(exchange.inflight_counter.is_empty());
3156    }
3157
3158    #[cfg(feature = "python")]
3159    mod python_latency {
3160        use std::ffi::CString;
3161
3162        use nautilus_common::messages::execution::CancelAllOrders;
3163        use nautilus_execution::python::latency::{PyLatencyModel, pyobject_to_latency_model_any};
3164        use pyo3::{prelude::*, types::PyDict};
3165
3166        use super::*;
3167
3168        #[rstest]
3169        fn test_python_latency_schedules_once_with_clock_and_command_time() {
3170            let mut exchange = setup_exchange(Dispatch::Latency);
3171            exchange.set_clock_time(UnixNanos::new(500));
3172            let (model, obj) = recorded_latency("11");
3173            exchange.set_latency_model(model);
3174            exchange.send(cancel_command());
3175
3176            let calls = Python::attach(|py| {
3177                obj.bind(py)
3178                    .getattr("calls")
3179                    .unwrap()
3180                    .extract::<Vec<(u64, u64)>>()
3181                    .unwrap()
3182            });
3183
3184            assert_eq!(calls, vec![(100, 500)]);
3185            assert_eq!(
3186                exchange.max_inflight_command_ts(),
3187                Some(UnixNanos::new(111))
3188            );
3189            assert_eq!(exchange.inflight_queue.len(), 1);
3190            assert_eq!(
3191                exchange.inflight_counter.get(&UnixNanos::new(111)),
3192                Some(&1)
3193            );
3194            assert!(exchange.callback_error.is_none());
3195        }
3196
3197        #[rstest]
3198        #[case("-1", "Python LatencyModel.get_delete_latency failed:")]
3199        #[case("2 ** 64 - 1", "Latency arrival timestamp exceeds u64 nanoseconds")]
3200        #[case(
3201            "(_ for _ in ()).throw(ValueError('sample failed'))",
3202            "ValueError: sample failed"
3203        )]
3204        fn test_python_latency_failure_latches_without_queuing(
3205            #[case] delay: &str,
3206            #[case] message: &str,
3207        ) {
3208            let mut exchange = setup_exchange(Dispatch::Latency);
3209            let (model, obj) = recorded_latency(delay);
3210            exchange.set_latency_model(model);
3211            exchange.send(cancel_command());
3212            exchange.send(cancel_command());
3213
3214            let calls = Python::attach(|py| {
3215                obj.bind(py)
3216                    .getattr("calls")
3217                    .unwrap()
3218                    .extract::<Vec<(u64, u64)>>()
3219                    .unwrap()
3220            });
3221
3222            assert_eq!(calls, vec![(100, 0)]);
3223            assert!(
3224                exchange
3225                    .check_callback_error()
3226                    .unwrap_err()
3227                    .to_string()
3228                    .contains(message)
3229            );
3230            assert_eq!(exchange.max_inflight_command_ts(), None);
3231            assert!(exchange.inflight_queue.is_empty());
3232            assert!(exchange.message_queue.is_empty());
3233            assert!(exchange.inflight_counter.is_empty());
3234        }
3235
3236        fn cancel_command() -> TradingCommand {
3237            TradingCommand::CancelAllOrders(CancelAllOrders::new(
3238                TraderId::test_default(),
3239                None,
3240                StrategyId::test_default(),
3241                InstrumentId::from("AUD/USD.SIM"),
3242                None,
3243                UUID4::new(),
3244                UnixNanos::new(100),
3245                None,
3246                None,
3247            ))
3248        }
3249
3250        fn recorded_latency(delay: &str) -> (LatencyModelHandle, Py<PyAny>) {
3251            Python::initialize();
3252            Python::attach(|py| {
3253                let locals = PyDict::new(py);
3254                locals
3255                    .set_item("LatencyModel", py.get_type::<PyLatencyModel>())
3256                    .unwrap();
3257                let source = format!(
3258                    "type('RecordedLatency', (LatencyModel,), {{'calls': [], 'get_delete_latency': lambda self, command, ts_now: self.calls.append((command.ts_init, ts_now)) or ({delay})}})()"
3259                );
3260                let source = CString::new(source).unwrap();
3261                let obj = py.eval(&source, Some(&locals), None).unwrap();
3262                let model = pyobject_to_latency_model_any(&obj).unwrap().into();
3263                (model, obj.unbind())
3264            })
3265        }
3266    }
3267}