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, SubmitOrderList, 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        let Some(exec_client) = &self.exec_client else {
770            return Ok(());
771        };
772
773        let venue = exec_client.venue();
774
775        let (balances, margins, ts_event) = {
776            let cache = self.cache.borrow();
777            let account = cache
778                .account_for_venue(&venue)
779                .ok_or(AccountAdjustmentError::MissingAccount(venue))?;
780            let balance = account
781                .balance(Some(adjustment.currency))
782                .ok_or(AccountAdjustmentError::MissingBalance(adjustment.currency))?;
783            let total = balance
784                .total
785                .checked_add(adjustment)
786                .ok_or(AccountAdjustmentError::TotalOverflow(adjustment.currency))?;
787
788            let current_balance = match &*account {
789                AccountAny::Margin(margin_account)
790                    if lock_margins && margin_account.calculate_account_state =>
791                {
792                    margin_account.balance_locking_margins(total)
793                }
794                _ => {
795                    let free = balance.free.checked_add(adjustment).ok_or(
796                        AccountAdjustmentError::FreeBalanceOverflow(adjustment.currency),
797                    )?;
798                    let mut current_balance = *balance;
799                    current_balance.total = total;
800                    current_balance.free = free;
801                    current_balance
802                }
803            };
804
805            // Carry account-wide margins too, applying the state replaces both sets
806            let margins = match &*account {
807                AccountAny::Margin(margin_account) => margin_account
808                    .margins
809                    .values()
810                    .chain(margin_account.account_margins.values())
811                    .copied()
812                    .collect(),
813                _ => Vec::new(),
814            };
815
816            (
817                vec![current_balance],
818                margins,
819                self.clock.borrow().timestamp_ns(),
820            )
821        };
822
823        exec_client
824            .generate_account_state(balances, margins, true, ts_event, None)
825            .map_err(|e| AccountAdjustmentError::AccountStateGeneration(e.to_string()))?;
826        Ok(())
827    }
828
829    /// Returns whether there are pending commands at or before `ts_now`.
830    #[must_use]
831    pub fn has_pending_commands(&self, ts_now: UnixNanos) -> bool {
832        if !self.message_queue.is_empty() {
833            return true;
834        }
835        self.inflight_queue
836            .peek()
837            .is_some_and(|inflight| inflight.timestamp <= ts_now)
838    }
839
840    pub(crate) fn has_pending_commands_for_scope(
841        &self,
842        ts_now: UnixNanos,
843        scope: SettlementScope,
844    ) -> bool {
845        if matches!(scope, SettlementScope::All) {
846            return self.has_pending_commands(ts_now);
847        }
848
849        if !self.message_queue.is_empty() {
850            return true;
851        }
852
853        self.inflight_queue
854            .iter()
855            .any(|inflight| inflight.timestamp <= ts_now && inflight.matches_scope(ts_now, scope))
856    }
857
858    /// Returns the latest arrival timestamp across all latency-deferred
859    /// inflight commands, or `None` when the inflight queue is empty.
860    ///
861    /// Used at shutdown to advance the clock past the configured `LatencyModel`
862    /// delay so trailing commands (those emitted on the final data tick or
863    /// in `on_stop`) settle before the engines stop.
864    #[must_use]
865    pub fn max_inflight_command_ts(&self) -> Option<UnixNanos> {
866        self.inflight_queue.iter().map(|c| c.timestamp).max()
867    }
868
869    /// Iterates all matching engines so newly submitted orders can match
870    /// against the current market state.
871    pub fn iterate_matching_engines(&mut self, ts_now: UnixNanos) {
872        for index in 0..self.matching_engines.len() {
873            if let Some((_, engine)) = self.matching_engines.get_index_mut(index) {
874                engine.iterate(ts_now, AggressorSide::NoAggressor);
875            }
876
877            self.drain_oto_commands();
878        }
879    }
880
881    /// Processes instrument expirations due at the given timestamp.
882    pub fn process_instrument_expirations(&mut self, ts_now: UnixNanos) {
883        for matching_engine in self.matching_engines.values_mut() {
884            if matching_engine
885                .instrument
886                .expiration_ns()
887                .is_some_and(|expiration_ns| ts_now >= expiration_ns)
888            {
889                matching_engine.process_instrument_expiration(ts_now);
890            }
891        }
892
893        self.drain_oto_commands();
894    }
895
896    /// Returns unprocessed instrument expirations for timer scheduling.
897    #[must_use]
898    pub fn instrument_expirations(&self) -> Vec<(InstrumentId, UnixNanos)> {
899        self.matching_engines
900            .values()
901            .filter(|matching_engine| !matching_engine.is_expiration_processed())
902            .filter_map(|matching_engine| {
903                matching_engine
904                    .instrument
905                    .expiration_ns()
906                    .filter(|expiration_ns| *expiration_ns > UnixNanos::default())
907                    .map(|expiration_ns| (matching_engine.instrument.id(), expiration_ns))
908            })
909            .collect()
910    }
911
912    /// Advances the exchange clock to the given timestamp so that any event
913    /// generators (modules, account state) see the correct time even when
914    /// no commands are pending.
915    ///
916    /// # Panics
917    ///
918    /// Panics if the clock is not a [`VirtualClock`].
919    pub fn set_clock_time(&self, ts_now: UnixNanos) {
920        let mut clock_ref = self.clock.borrow_mut();
921        let test_clock = clock_ref
922            .as_any_mut()
923            .downcast_mut::<VirtualClock>()
924            .expect("SimulatedExchange requires VirtualClock");
925        test_clock.set_time(ts_now);
926    }
927
928    /// Sends a trading command to the exchange for processing.
929    ///
930    /// Ignores commands while a callback failure is latched, until [`Self::reset`] clears it.
931    /// [`Self::process_modules`] returns the latched error.
932    pub fn send(&mut self, command: TradingCommand) {
933        if matches!(
934            &command,
935            TradingCommand::QueryOrder(_) | TradingCommand::QueryAccount(_)
936        ) {
937            log::warn!("Simulated exchange does not support queries: {command}");
938            return;
939        }
940
941        if self.callback_error.is_some() {
942            return;
943        }
944
945        if !self.use_message_queue {
946            let _guard = DeferEventsGuard::new(Rc::clone(&self.deferring_events));
947            self.process_trading_command(command);
948        } else if self.latency_model.is_none() {
949            self.inflight_orders.insert(&command);
950            self.message_queue.push_back(command);
951        } else {
952            let (timestamp, counter) = match self.generate_inflight_command(&command) {
953                Ok(arrival) => arrival,
954                Err(e) => {
955                    self.callback_error = Some(format!("Latency model failed: {e:#}"));
956                    return;
957                }
958            };
959
960            self.inflight_orders.insert(&command);
961            self.inflight_queue
962                .push(InflightCommand::new(timestamp, counter, command));
963        }
964    }
965
966    fn generate_inflight_command(
967        &mut self,
968        command: &TradingCommand,
969    ) -> anyhow::Result<(UnixNanos, u32)> {
970        if let Some(latency_model) = &self.latency_model {
971            let ts_now = self.clock.borrow().timestamp_ns();
972
973            let latency = match command {
974                TradingCommand::SubmitOrder(_) | TradingCommand::SubmitOrderList(_) => {
975                    latency_model.get_insert_latency(command, ts_now)?
976                }
977                TradingCommand::ModifyOrder(_) | TradingCommand::ModifyOrders(_) => {
978                    latency_model.get_update_latency(command, ts_now)?
979                }
980                TradingCommand::CancelOrder(_)
981                | TradingCommand::CancelOrders(_)
982                | TradingCommand::CancelAllOrders(_) => {
983                    latency_model.get_delete_latency(command, ts_now)?
984                }
985                _ => anyhow::bail!("Cannot handle command: {command:?}"),
986            };
987
988            let ts = command.ts_init().checked_add(latency).ok_or_else(|| {
989                anyhow::anyhow!("Latency arrival timestamp exceeds u64 nanoseconds")
990            })?;
991
992            let counter = self
993                .inflight_counter
994                .entry(ts)
995                .and_modify(|e| *e += 1)
996                .or_insert(1);
997
998            Ok((ts, *counter))
999        } else {
1000            anyhow::bail!("Latency model should be initialized");
1001        }
1002    }
1003
1004    /// Processes a single order book delta.
1005    ///
1006    /// # Errors
1007    ///
1008    /// Returns an error if module pre-processing or matching engine processing fails.
1009    pub fn process_order_book_delta(&mut self, delta: OrderBookDelta) -> anyhow::Result<()> {
1010        self.pre_process_modules(&Data::BookDelta(delta))?;
1011        self.dispatch_market_data(delta.instrument_id, |matching_engine| {
1012            matching_engine.process_order_book_delta(&delta)?;
1013            Ok(())
1014        })
1015    }
1016
1017    /// Processes a batch of order book deltas.
1018    ///
1019    /// # Errors
1020    ///
1021    /// Returns an error if module pre-processing or matching engine processing fails.
1022    pub fn process_order_book_deltas(&mut self, deltas: &OrderBookDeltas) -> anyhow::Result<()> {
1023        self.pre_process_modules(&Data::BookDeltas(Box::new(deltas.clone())))?;
1024        self.dispatch_market_data(deltas.instrument_id, |matching_engine| {
1025            matching_engine.process_order_book_deltas(deltas)?;
1026            Ok(())
1027        })
1028    }
1029
1030    /// Processes an L2 order book depth snapshot.
1031    ///
1032    /// # Errors
1033    ///
1034    /// Returns an error if module pre-processing or matching engine processing fails.
1035    pub fn process_order_book_depth(&mut self, depth: &OrderBookDepth) -> anyhow::Result<()> {
1036        self.pre_process_modules(&Data::BookDepth(Box::new(depth.clone())))?;
1037        self.dispatch_market_data(depth.instrument_id, |matching_engine| {
1038            matching_engine.process_order_book_depth(depth)?;
1039            Ok(())
1040        })
1041    }
1042
1043    /// Processes a mark price update and updates the matching engine.
1044    ///
1045    /// # Errors
1046    ///
1047    /// Returns an error if module pre-processing or matching engine initialization fails.
1048    pub fn process_mark_price(&mut self, mark: &MarkPriceUpdate) -> anyhow::Result<()> {
1049        self.pre_process_modules(&Data::MarkPrice(*mark))?;
1050        self.dispatch_market_data(mark.instrument_id, |matching_engine| {
1051            matching_engine.process_mark_price(mark);
1052            Ok(())
1053        })
1054    }
1055
1056    /// Processes a quote tick and updates the matching engine.
1057    ///
1058    /// # Errors
1059    ///
1060    /// Returns an error if module pre-processing or matching engine processing fails.
1061    pub fn process_quote_tick(&mut self, quote: &QuoteTick) -> anyhow::Result<()> {
1062        self.pre_process_modules(&Data::Quote(*quote))?;
1063        self.dispatch_market_data(quote.instrument_id, |matching_engine| {
1064            matching_engine.process_quote_tick(quote);
1065            Ok(())
1066        })
1067    }
1068
1069    /// Processes a trade tick and updates the matching engine.
1070    ///
1071    /// # Errors
1072    ///
1073    /// Returns an error if module pre-processing or matching engine processing fails.
1074    pub fn process_trade_tick(&mut self, trade: &TradeTick) -> anyhow::Result<()> {
1075        self.pre_process_modules(&Data::Trade(*trade))?;
1076        self.dispatch_market_data(trade.instrument_id, |matching_engine| {
1077            matching_engine.process_trade_tick(trade);
1078            Ok(())
1079        })
1080    }
1081
1082    /// Processes a bar and updates the matching engine.
1083    ///
1084    /// # Errors
1085    ///
1086    /// Returns an error if L1 bar execution receives a non-time external bar other
1087    /// than a mark-price bar, or if module pre-processing or matching engine processing fails.
1088    pub fn process_bar(&mut self, bar: Bar) -> anyhow::Result<()> {
1089        if self.bar_execution
1090            && self.book_type == BookType::L1_MBP
1091            && bar.bar_type.is_externally_aggregated()
1092            && bar.bar_type.spec().price_type != PriceType::Mark
1093        {
1094            anyhow::ensure!(
1095                bar.bar_type.spec().is_time_aggregated(),
1096                "Bar execution requires time-aggregated bars, received {}",
1097                bar.bar_type,
1098            );
1099        }
1100
1101        self.pre_process_modules(&Data::Bar(bar))?;
1102        self.dispatch_market_data(bar.instrument_id(), |matching_engine| {
1103            matching_engine.process_bar(&bar);
1104            Ok(())
1105        })
1106    }
1107
1108    /// Processes an instrument status update.
1109    ///
1110    /// # Errors
1111    ///
1112    /// Returns an error if module pre-processing or matching engine processing fails.
1113    pub fn process_instrument_status(&mut self, status: InstrumentStatus) -> anyhow::Result<()> {
1114        self.pre_process_modules(&Data::InstrumentStatus(status))?;
1115        self.dispatch_market_data(status.instrument_id, |matching_engine| {
1116            matching_engine.process_status(status.action);
1117            Ok(())
1118        })
1119    }
1120
1121    /// Processes an instrument close event.
1122    ///
1123    /// # Errors
1124    ///
1125    /// Returns an error if module pre-processing or matching engine processing fails.
1126    pub fn process_instrument_close(&mut self, close: InstrumentClose) -> anyhow::Result<()> {
1127        self.pre_process_modules(&Data::InstrumentClose(close))?;
1128        self.dispatch_market_data(close.instrument_id, |matching_engine| {
1129            matching_engine.process_instrument_close(close);
1130            Ok(())
1131        })
1132    }
1133
1134    fn dispatch_market_data(
1135        &mut self,
1136        instrument_id: InstrumentId,
1137        process: impl FnOnce(&mut OrderMatchingEngine) -> anyhow::Result<()>,
1138    ) -> anyhow::Result<()> {
1139        if !self.matching_engines.contains_key(&instrument_id) {
1140            let instrument = {
1141                let cache = self.cache.as_ref().borrow();
1142                cache.instrument(&instrument_id).cloned()
1143            };
1144
1145            if let Some(instrument) = instrument {
1146                self.add_instrument(instrument)?;
1147            } else {
1148                anyhow::bail!("No matching engine found for instrument {instrument_id}");
1149            }
1150        }
1151
1152        if let Some(matching_engine) = self.matching_engines.get_mut(&instrument_id) {
1153            process(matching_engine)?;
1154        } else {
1155            anyhow::bail!("Matching engine should be initialized");
1156        }
1157
1158        self.drain_oto_commands();
1159        Ok(())
1160    }
1161
1162    /// Processes a funding rate update.
1163    ///
1164    /// Returns the funding boundary timestamp when the engine should schedule a settlement.
1165    ///
1166    /// # Errors
1167    ///
1168    /// Returns an error if module pre-processing or funding settlement fails.
1169    pub fn process_funding_rate(
1170        &mut self,
1171        funding_rate: FundingRateUpdate,
1172    ) -> anyhow::Result<Option<UnixNanos>> {
1173        let replay_ts = self.clock.borrow().timestamp_ns();
1174        let instrument_id = funding_rate.instrument_id;
1175        let boundary = Self::funding_boundary(&funding_rate);
1176        let next_boundary = self.queue_funding_rate(funding_rate)?;
1177
1178        if let Some(boundary) = boundary
1179            && boundary <= replay_ts
1180        {
1181            self.process_funding_settlement(instrument_id, boundary)?;
1182            return Ok(None);
1183        }
1184
1185        Ok(next_boundary)
1186    }
1187
1188    pub(crate) fn process_funding_rate_deferred(
1189        &mut self,
1190        funding_rate: FundingRateUpdate,
1191        replay_ts: UnixNanos,
1192    ) -> anyhow::Result<Option<UnixNanos>> {
1193        self.queue_funding_rate(funding_rate)?;
1194        Ok(self
1195            .next_funding_boundary()
1196            .filter(|boundary| *boundary > replay_ts))
1197    }
1198
1199    fn queue_funding_rate(
1200        &mut self,
1201        funding_rate: FundingRateUpdate,
1202    ) -> anyhow::Result<Option<UnixNanos>> {
1203        self.pre_process_modules(&Data::FundingRate(funding_rate))?;
1204
1205        let Some(boundary) = Self::funding_boundary(&funding_rate) else {
1206            log::debug!(
1207                "Funding rate update for {} does not define a settlement boundary",
1208                funding_rate.instrument_id
1209            );
1210            return Ok(None);
1211        };
1212
1213        let key = (boundary, funding_rate.instrument_id);
1214        if !self.funding_settlements.contains(&key) {
1215            self.pending_funding_rates.insert(key, funding_rate);
1216        }
1217        Ok(Some(boundary))
1218    }
1219
1220    /// Processes a scheduled funding settlement for the instrument.
1221    ///
1222    /// # Errors
1223    ///
1224    /// Returns an error if a prior simulation module failure requires reset.
1225    pub fn process_funding_settlement(
1226        &mut self,
1227        instrument_id: InstrumentId,
1228        ts_event: UnixNanos,
1229    ) -> anyhow::Result<()> {
1230        self.check_callback_error()?;
1231        let key = (ts_event, instrument_id);
1232        let Some(funding_rate) = self.pending_funding_rates.remove(&key) else {
1233            return Ok(());
1234        };
1235
1236        if !self.settle_funding_rate(&funding_rate, ts_event) {
1237            self.pending_funding_rates.insert(key, funding_rate);
1238        }
1239        Ok(())
1240    }
1241
1242    #[must_use]
1243    pub(crate) fn funding_boundaries_due(
1244        &self,
1245        replay_ts: UnixNanos,
1246    ) -> Vec<(UnixNanos, InstrumentId)> {
1247        self.pending_funding_rates
1248            .keys()
1249            .copied()
1250            .take_while(|(boundary, _)| *boundary <= replay_ts)
1251            .collect()
1252    }
1253
1254    pub(crate) fn settle_funding_boundary(
1255        &mut self,
1256        boundary: UnixNanos,
1257        instrument_id: InstrumentId,
1258    ) -> bool {
1259        let key = (boundary, instrument_id);
1260        let Some(funding_rate) = self.pending_funding_rates.remove(&key) else {
1261            return true;
1262        };
1263
1264        if self.settle_funding_rate(&funding_rate, boundary) {
1265            true
1266        } else {
1267            self.pending_funding_rates.insert(key, funding_rate);
1268            false
1269        }
1270    }
1271
1272    #[must_use]
1273    pub(crate) fn next_funding_boundary(&self) -> Option<UnixNanos> {
1274        self.pending_funding_rates
1275            .first_key_value()
1276            .map(|((boundary, _), _)| *boundary)
1277    }
1278
1279    fn settle_funding_rate(
1280        &mut self,
1281        funding_rate: &FundingRateUpdate,
1282        ts_event: UnixNanos,
1283    ) -> bool {
1284        let settlement_key = (ts_event, funding_rate.instrument_id);
1285        if self.funding_settlements.contains(&settlement_key) {
1286            return true;
1287        }
1288
1289        let Some(exec_client) = &self.exec_client else {
1290            log::warn!(
1291                "Cannot settle funding for {}: execution client is not registered",
1292                funding_rate.instrument_id
1293            );
1294            return false;
1295        };
1296        let account_id = exec_client.account_id();
1297        let account_venue = exec_client.venue();
1298
1299        if !self.prepare_funding_instrument(funding_rate.instrument_id) {
1300            return false;
1301        }
1302
1303        // Snapshots without history: valuation reads only position state, and the snapshot is the
1304        // rollback point if settlement fails after the cached positions are adjusted in place
1305        let open_positions: Vec<Position> = {
1306            let cache = self.cache.borrow();
1307            cache
1308                .positions_open(
1309                    Some(&self.id),
1310                    Some(&funding_rate.instrument_id),
1311                    None,
1312                    Some(&account_id),
1313                    None,
1314                )
1315                .into_iter()
1316                .map(|position| position.clone_without_events())
1317                .collect()
1318        };
1319
1320        if open_positions.is_empty() {
1321            self.funding_settlements.insert(settlement_key);
1322            return true;
1323        }
1324
1325        let Some(settlement_price) = self.funding_settlement_price(funding_rate.instrument_id)
1326        else {
1327            log::warn!(
1328                "Cannot settle funding for {}: no mark price or top-of-book price",
1329                funding_rate.instrument_id
1330            );
1331            return false;
1332        };
1333
1334        let settlement_currency = open_positions[0].settlement_currency;
1335
1336        let Some(FundingValuation {
1337            positions: valued_positions,
1338            mut account_adjustments,
1339        }) = value_funding_positions(
1340            funding_rate,
1341            settlement_price,
1342            open_positions,
1343            settlement_currency,
1344        )
1345        else {
1346            return false;
1347        };
1348
1349        if !self.validate_funding_account_adjustments(
1350            funding_rate.instrument_id,
1351            account_venue,
1352            &mut account_adjustments,
1353        ) {
1354            return false;
1355        }
1356
1357        let ts_init = self.clock.borrow().timestamp_ns();
1358        let settlement = FundingSettlement::new(
1359            msgbus::get_message_bus().borrow().trader_id,
1360            funding_rate.instrument_id,
1361            account_id,
1362            funding_rate.rate,
1363            settlement_price,
1364            settlement_currency,
1365            UUID4::new(),
1366            ts_event,
1367            ts_init,
1368        );
1369        let mut adjusted_positions = Vec::with_capacity(valued_positions.len());
1370        for (original, pnl_change) in valued_positions {
1371            let adjustment = PositionAdjusted::new(
1372                settlement.trader_id,
1373                original.strategy_id,
1374                original.instrument_id,
1375                original.id,
1376                original.account_id,
1377                PositionAdjustmentType::Funding,
1378                None,
1379                Some(pnl_change),
1380                Some(Ustr::from(&format!(
1381                    "funding_settlement:{}",
1382                    settlement.event_id
1383                ))),
1384                UUID4::new(),
1385                settlement.ts_event,
1386                settlement.ts_init,
1387            );
1388            adjusted_positions.push((original, adjustment));
1389        }
1390
1391        if !self.apply_funding_adjustments(&adjusted_positions, &account_adjustments) {
1392            return false;
1393        }
1394
1395        self.funding_settlements.insert(settlement_key);
1396        let settlement_topic = switchboard::get_funding_settlement_topic(settlement.instrument_id);
1397        msgbus::publish_any(settlement_topic, &settlement);
1398
1399        for (_, adjustment) in adjusted_positions {
1400            let strategy_id = adjustment.strategy_id;
1401            let event = PositionEvent::PositionAdjusted(adjustment);
1402            let topic = switchboard::get_event_position_topic(strategy_id);
1403            msgbus::publish_position_event(topic, &event);
1404        }
1405
1406        true
1407    }
1408
1409    fn prepare_funding_instrument(&mut self, instrument_id: InstrumentId) -> bool {
1410        if self.matching_engines.contains_key(&instrument_id) {
1411            return true;
1412        }
1413
1414        let instrument = {
1415            let cache = self.cache.as_ref().borrow();
1416            cache.instrument(&instrument_id).cloned()
1417        };
1418
1419        let Some(instrument) = instrument else {
1420            log::warn!(
1421                "Cannot settle funding for {instrument_id}: no matching engine or instrument"
1422            );
1423            return false;
1424        };
1425
1426        if let Err(e) = self.add_instrument(instrument) {
1427            log::error!("Cannot settle funding for {instrument_id}: failed to add instrument: {e}");
1428            return false;
1429        }
1430
1431        true
1432    }
1433
1434    fn validate_funding_account_adjustments(
1435        &self,
1436        instrument_id: InstrumentId,
1437        account_venue: Venue,
1438        account_adjustments: &mut [Money],
1439    ) -> bool {
1440        if self.frozen_account {
1441            return true;
1442        }
1443
1444        let cache = self.cache.borrow();
1445
1446        let Some(account) = cache.account_for_venue(&account_venue) else {
1447            log::error!("Cannot settle funding: no account for venue {account_venue}");
1448            return false;
1449        };
1450
1451        // A single-currency account holds only its base currency, so the cash
1452        // adjustment is converted there; position PnL keeps the settlement currency
1453        if let Some(base_currency) = account.base_currency() {
1454            for adjustment in account_adjustments.iter_mut() {
1455                if adjustment.currency == base_currency {
1456                    continue;
1457                }
1458
1459                let Some(converted) = convert_funding_adjustment(
1460                    &cache,
1461                    instrument_id,
1462                    account_venue,
1463                    base_currency,
1464                    *adjustment,
1465                ) else {
1466                    return false;
1467                };
1468
1469                *adjustment = converted;
1470            }
1471        }
1472
1473        for adjustment in account_adjustments.iter() {
1474            let Some(balance) = account.balance(Some(adjustment.currency)) else {
1475                log::error!(
1476                    "Cannot settle funding: no account balance for currency {}",
1477                    adjustment.currency
1478                );
1479                return false;
1480            };
1481
1482            if balance.total.checked_add(*adjustment).is_none()
1483                || balance.free.checked_add(*adjustment).is_none()
1484            {
1485                log::error!(
1486                    "Cannot settle funding: {} account adjustment exceeds Money bounds",
1487                    adjustment.currency
1488                );
1489                return false;
1490            }
1491        }
1492
1493        true
1494    }
1495
1496    fn apply_funding_adjustments(
1497        &self,
1498        adjusted_positions: &[(Position, PositionAdjusted)],
1499        account_adjustments: &[Money],
1500    ) -> bool {
1501        {
1502            let mut cache = self.cache.borrow_mut();
1503
1504            for (index, (original, adjustment)) in adjusted_positions.iter().enumerate() {
1505                if let Err(e) = cache.update_position_from_adjustment(original.id, *adjustment) {
1506                    log::error!(
1507                        "Cannot update position {} after funding settlement: {e}",
1508                        original.id
1509                    );
1510
1511                    // Include the failing position in case its adjustment was applied before
1512                    // a backing integrity check rejected it.
1513                    revert_funding_adjustments(
1514                        &mut cache,
1515                        &adjusted_positions[..=index],
1516                        "funding settlement",
1517                    );
1518                    return false;
1519                }
1520            }
1521        }
1522
1523        for adjustment in account_adjustments {
1524            if !self.adjust_account_balance(*adjustment, true) {
1525                let mut cache = self.cache.borrow_mut();
1526                revert_funding_adjustments(&mut cache, adjusted_positions, "account adjustment");
1527                return false;
1528            }
1529        }
1530
1531        true
1532    }
1533
1534    fn funding_settlement_price(&self, instrument_id: InstrumentId) -> Option<Price> {
1535        if let Some(mark_price) = self.cache.borrow().mark_price(&instrument_id) {
1536            return Some(mark_price.value);
1537        }
1538
1539        let bid = self.best_bid_price(instrument_id)?;
1540        let ask = self.best_ask_price(instrument_id)?;
1541        let midpoint = (bid.as_decimal() + ask.as_decimal()) / Decimal::from(2);
1542        Price::from_decimal_dp(midpoint, bid.precision.max(ask.precision)).ok()
1543    }
1544
1545    fn is_interval_funding_boundary(funding_rate: &FundingRateUpdate) -> bool {
1546        let Some(interval_mins) = funding_rate.interval else {
1547            return false;
1548        };
1549        let Ok(interval) = DurationNanos::try_from_mins(u64::from(interval_mins)) else {
1550            return false;
1551        };
1552
1553        !interval.is_zero() && funding_rate.ts_event.floor(interval) == funding_rate.ts_event
1554    }
1555
1556    fn funding_boundary(funding_rate: &FundingRateUpdate) -> Option<UnixNanos> {
1557        funding_rate.next_funding_ns.or_else(|| {
1558            Self::is_interval_funding_boundary(funding_rate).then_some(funding_rate.ts_event)
1559        })
1560    }
1561
1562    /// Advances the exchange clock and processes all pending inflight and queued trading commands
1563    /// up to `ts_now`.
1564    ///
1565    /// Does nothing while a callback failure is latched, until [`Self::reset`] clears it.
1566    /// [`Self::process_modules`] returns the latched error.
1567    ///
1568    /// # Panics
1569    ///
1570    /// Panics if the exchange clock is not a [`VirtualClock`] or popping an inflight command fails
1571    /// during processing.
1572    pub fn process(&mut self, ts_now: UnixNanos) {
1573        self.process_commands(ts_now, SettlementScope::All);
1574    }
1575
1576    pub(crate) fn process_for_scope(&mut self, ts_now: UnixNanos, scope: SettlementScope) {
1577        self.process_commands(ts_now, scope);
1578    }
1579
1580    fn process_commands(&mut self, ts_now: UnixNanos, scope: SettlementScope) {
1581        if self.callback_error.is_some() {
1582            return;
1583        }
1584
1585        self.set_clock_time(ts_now);
1586
1587        let mut deferred = Vec::new();
1588        let mut processed_timestamps = BTreeSet::new();
1589
1590        while let Some(inflight) = self.inflight_queue.peek() {
1591            if inflight.timestamp > ts_now {
1592                break;
1593            }
1594            let inflight = self.inflight_queue.pop().unwrap();
1595
1596            if !inflight.matches_scope(ts_now, scope) {
1597                deferred.push(inflight);
1598                continue;
1599            }
1600
1601            processed_timestamps.insert(inflight.timestamp);
1602            self.message_queue.push_back(inflight.command);
1603        }
1604
1605        let deferred_timestamps: BTreeSet<_> =
1606            deferred.iter().map(|inflight| inflight.timestamp).collect();
1607        self.inflight_queue.extend(deferred);
1608
1609        for timestamp in processed_timestamps.difference(&deferred_timestamps) {
1610            self.inflight_counter.remove(timestamp);
1611        }
1612
1613        while let Some(command) = self.message_queue.pop_front() {
1614            self.process_trading_command(command);
1615        }
1616    }
1617
1618    /// Runs all simulation modules for the given timestamp.
1619    ///
1620    /// Must be called once per time step after all command queues have fully
1621    /// settled, not inside the settle loop.
1622    ///
1623    /// # Errors
1624    ///
1625    /// Returns an error if a latency model or simulation module fails.
1626    /// The exchange retains the failure and rejects further processing until reset.
1627    pub fn process_modules(&mut self, ts_now: UnixNanos) -> anyhow::Result<()> {
1628        self.check_callback_error()?;
1629
1630        if self.frozen_account || self.exec_client.is_none() {
1631            return Ok(());
1632        }
1633
1634        let results = {
1635            let cache = self.cache.borrow();
1636            let ctx = ExchangeContext {
1637                venue: self.id,
1638                base_currency: self.base_currency,
1639                instruments: &self.instruments,
1640                matching_engines: &self.matching_engines,
1641                cache: &cache,
1642            };
1643            self.modules
1644                .iter()
1645                .enumerate()
1646                .map(|(module_index, module)| {
1647                    module
1648                        .process(ts_now, &ctx)
1649                        .map(|result| (module_index, result))
1650                        .map_err(|e| (module_index, e))
1651                })
1652                .collect::<Result<Vec<_>, _>>()
1653        };
1654        let results = match results {
1655            Ok(results) => results,
1656            Err((module_index, error)) => {
1657                return Err(self.store_module_error(module_index, "process", &error));
1658            }
1659        };
1660
1661        for (module_index, result) in results {
1662            if let SimulationModuleResult::Completed(adjustments) = result {
1663                let outcomes = adjustments
1664                    .into_iter()
1665                    .map(|adjustment| match self.try_adjust_account(adjustment) {
1666                        Ok(()) => AccountAdjustmentOutcome::Applied,
1667                        Err(e) => AccountAdjustmentOutcome::Failed(e),
1668                    })
1669                    .collect::<Vec<_>>();
1670
1671                if let Err(e) = self.modules[module_index].acknowledge(&outcomes) {
1672                    return Err(self.store_module_error(module_index, "acknowledge", &e));
1673                }
1674            }
1675        }
1676        Ok(())
1677    }
1678
1679    /// Resets the exchange to its initial state.
1680    ///
1681    /// # Errors
1682    ///
1683    /// Returns an error if a simulation module cannot reset.
1684    pub fn reset(&mut self) -> anyhow::Result<()> {
1685        if !self.account_at_starting_balances() {
1686            self.generate_fresh_account_state();
1687        }
1688
1689        let mut callback_error = None;
1690
1691        for (module_index, module) in self.modules.iter().enumerate() {
1692            if let Err(e) = module.reset()
1693                && callback_error.is_none()
1694            {
1695                callback_error = Some(format!(
1696                    "Simulation module {module_index} reset failed: {e:#}"
1697                ));
1698            }
1699        }
1700
1701        for (instrument_id, matching_engine) in &mut self.matching_engines {
1702            matching_engine.reset();
1703
1704            if let Some(instrument) = self.initial_instruments.get(instrument_id) {
1705                if let Err(e) = self.cache.borrow_mut().add_instrument(instrument.clone()) {
1706                    callback_error.get_or_insert_with(|| e.to_string());
1707                    continue;
1708                }
1709
1710                matching_engine.update_instrument(instrument.clone())?;
1711                self.instruments.insert(*instrument_id, instrument.clone());
1712            }
1713        }
1714
1715        self.pending_funding_rates.clear();
1716        self.funding_settlements.clear();
1717        self.message_queue.clear();
1718        self.inflight_queue.clear();
1719        self.inflight_orders.clear();
1720        self.inflight_counter.clear();
1721
1722        log::info!("Resetting exchange state");
1723        self.callback_error = callback_error;
1724        self.check_callback_error()
1725    }
1726
1727    /// Logs diagnostic information from all simulation modules.
1728    ///
1729    /// # Errors
1730    ///
1731    /// Returns an error if a simulation module cannot produce its diagnostics.
1732    pub fn log_diagnostics(&self) -> anyhow::Result<()> {
1733        for (module_index, module) in self.modules.iter().enumerate() {
1734            module.log_diagnostics().map_err(|e| {
1735                anyhow::anyhow!("Simulation module {module_index} log_diagnostics failed: {e:#}")
1736            })?;
1737        }
1738        Ok(())
1739    }
1740
1741    /// Checks if any margin accounts have breached maintenance margin and liquidates open
1742    /// positions when the trigger threshold is met.
1743    ///
1744    /// Liquidation is scoped to the breached settlement currency: only positions whose
1745    /// instrument settles in the same currency as the breached margin account are closed.
1746    /// Positions settled in other currencies remain open, isolating the liquidation to
1747    /// the currency whose equity fell below the maintenance threshold.
1748    ///
1749    /// > **Note**: A future `cross_margin_mode` venue configuration could extend this to
1750    /// > liquidate all positions across all settlement currencies simultaneously.
1751    pub fn process_liquidations(&mut self, ts_now: UnixNanos) {
1752        if !self.liquidation_enabled {
1753            return;
1754        }
1755
1756        if self.frozen_account {
1757            return;
1758        }
1759
1760        let account = {
1761            let cache = self.cache.borrow();
1762            cache.account_for_venue_owned(&self.id)
1763        };
1764        let Some(account) = account else { return };
1765        let AccountAny::Margin(margin_account) = &account else {
1766            return;
1767        };
1768        let account_id = margin_account.id();
1769
1770        let currencies: Vec<Currency> = margin_account.currencies();
1771
1772        let open_positions: Vec<Position> = {
1773            let cache = self.cache.borrow();
1774            cache
1775                .positions_open(Some(&self.id), None, None, None, None)
1776                .into_iter()
1777                .map(|p| p.cloned())
1778                .collect()
1779        };
1780
1781        // Pre-bucket position indices by settlement currency to avoid repeated full scans.
1782        let mut positions_by_currency: AHashMap<Currency, Vec<usize>> = AHashMap::new();
1783        for (i, p) in open_positions.iter().enumerate() {
1784            positions_by_currency
1785                .entry(p.settlement_currency)
1786                .or_default()
1787                .push(i);
1788        }
1789
1790        for currency in currencies {
1791            let Some(balance) = margin_account.balance(Some(currency)) else {
1792                continue;
1793            };
1794            let balance_f64 = balance.total.as_f64();
1795
1796            let Some(indices) = positions_by_currency.get(&currency) else {
1797                continue;
1798            };
1799
1800            let upnl_f64 = {
1801                let cache = self.cache.borrow();
1802                liquidation_unrealized_total(&cache, &open_positions, indices)
1803            };
1804
1805            let Some(upnl_f64) = upnl_f64 else {
1806                continue; // defer until all positions are priced
1807            };
1808
1809            let equity = balance_f64 + upnl_f64;
1810            let maintenance = margin_account.total_maintenance_margin(currency).as_f64();
1811
1812            if maintenance == 0.0 {
1813                continue;
1814            }
1815
1816            let threshold = maintenance * self.liquidation_trigger_ratio;
1817
1818            if equity > threshold {
1819                continue;
1820            }
1821
1822            log::warn!(
1823                "LIQUIDATION triggered for account {} currency {}: equity={:.4} <= threshold={:.4} (maintenance={:.4} x ratio={})",
1824                account_id,
1825                currency,
1826                equity,
1827                threshold,
1828                maintenance,
1829                self.liquidation_trigger_ratio
1830            );
1831
1832            for matching_engine in self.matching_engines.values_mut() {
1833                matching_engine.liquidate_open_positions(
1834                    ts_now,
1835                    self.liquidation_cancel_open_orders,
1836                    currency,
1837                );
1838            }
1839        }
1840
1841        self.drain_oto_commands();
1842    }
1843
1844    fn process_trading_command(&mut self, command: TradingCommand) {
1845        self.inflight_orders.remove(&command);
1846        let instrument_id = command.instrument_id();
1847        assert!(
1848            self.matching_engines.contains_key(&instrument_id),
1849            "Matching engine not found for instrument {instrument_id}",
1850        );
1851
1852        let Some(command) = self.normalize_trading_command(command) else {
1853            return;
1854        };
1855
1856        let account_id = if let Some(exec_client) = &self.exec_client {
1857            exec_client.account_id()
1858        } else {
1859            panic!("Execution client should be initialized");
1860        };
1861
1862        if let TradingCommand::SubmitOrderList(ref command) = command {
1863            self.process_order_list(command, account_id);
1864
1865            self.drain_oto_commands();
1866            return;
1867        }
1868
1869        if let Some(matching_engine) = self.matching_engines.get_mut(&instrument_id) {
1870            match command {
1871                TradingCommand::SubmitOrder(command) => {
1872                    let mut order = self
1873                        .cache
1874                        .borrow()
1875                        .order(&command.client_order_id)
1876                        .map(|o| o.clone())
1877                        .expect("Order must exist in cache");
1878                    matching_engine.process_order(&mut order, account_id);
1879                }
1880                TradingCommand::ModifyOrder(ref command) => {
1881                    matching_engine.process_modify(command, account_id);
1882                }
1883                TradingCommand::ModifyOrders(ref command) => {
1884                    matching_engine.process_batch_modify(command, account_id);
1885                }
1886                TradingCommand::CancelOrder(ref command) => {
1887                    matching_engine.process_cancel(command, account_id);
1888                }
1889                TradingCommand::CancelOrders(ref command) => {
1890                    matching_engine.process_batch_cancel(command, account_id);
1891                }
1892                TradingCommand::CancelAllOrders(ref command) => {
1893                    matching_engine.process_cancel_all(command, account_id);
1894                }
1895                _ => {}
1896            }
1897        } else {
1898            panic!("Matching engine not found for instrument {instrument_id}");
1899        }
1900
1901        self.drain_oto_commands();
1902    }
1903
1904    fn normalize_trading_command(&self, command: TradingCommand) -> Option<TradingCommand> {
1905        match command {
1906            TradingCommand::ModifyOrder(ref command)
1907                if self.process_modify_submitted_order(command) =>
1908            {
1909                None
1910            }
1911            TradingCommand::ModifyOrders(mut command) => {
1912                command
1913                    .modifies
1914                    .retain(|modify| !self.process_modify_submitted_order(modify));
1915
1916                if command.modifies.is_empty() {
1917                    return None;
1918                }
1919
1920                Some(TradingCommand::ModifyOrders(command))
1921            }
1922            command => Some(command),
1923        }
1924    }
1925
1926    fn process_order_list(&mut self, command: &SubmitOrderList, account_id: AccountId) {
1927        let mut orders: Vec<OrderAny> = self
1928            .cache
1929            .borrow()
1930            .orders_for_ids(&command.order_list.client_order_ids, command);
1931
1932        for order in &mut orders {
1933            let order_instrument_id = order.instrument_id();
1934            if let Some(matching_engine) = self.matching_engines.get_mut(&order_instrument_id) {
1935                matching_engine.process_order(order, account_id);
1936            } else {
1937                panic!("Matching engine not found for instrument {order_instrument_id}");
1938            }
1939        }
1940    }
1941
1942    fn drain_oto_commands(&mut self) {
1943        while let Some(command) = self.matching_orders.pop_command() {
1944            let instrument_id = command.instrument_id();
1945            if let Some(engine) = self.matching_engines.get_mut(&instrument_id) {
1946                engine.process_oto_command(&command);
1947            } else {
1948                log::error!("Cannot process OTO action: no matching engine for {instrument_id}");
1949            }
1950
1951            if let OtoCommand::Release {
1952                parent_quantity: Some(quantity),
1953                parent_order_id,
1954                parent_instrument_id,
1955                ..
1956            } = command
1957                && let Some(engine) = self.matching_engines.get_mut(&parent_instrument_id)
1958            {
1959                engine.process_oto_resize(parent_order_id, quantity);
1960            }
1961        }
1962    }
1963
1964    fn process_modify_submitted_order(&self, command: &ModifyOrder) -> bool {
1965        let Some(order) = self
1966            .cache
1967            .borrow()
1968            .order(&command.client_order_id)
1969            .map(|o| o.clone())
1970        else {
1971            return false;
1972        };
1973
1974        let modifies_submitted_order = matches!(order.status(), OrderStatus::Submitted)
1975            || (matches!(order.status(), OrderStatus::PendingUpdate)
1976                && order
1977                    .previous_status()
1978                    .is_some_and(|status| matches!(status, OrderStatus::Submitted)));
1979
1980        if !modifies_submitted_order {
1981            return false;
1982        }
1983
1984        self.generate_order_updated(
1985            &order,
1986            command.quantity.unwrap_or_else(|| order.quantity()),
1987            command.price.or_else(|| order.price()),
1988            command.trigger_price.or_else(|| order.trigger_price()),
1989        );
1990        true
1991    }
1992
1993    fn generate_order_updated(
1994        &self,
1995        order: &OrderAny,
1996        quantity: Quantity,
1997        price: Option<Price>,
1998        trigger_price: Option<Price>,
1999    ) {
2000        let ts_now = self.clock.borrow().timestamp_ns();
2001        let event = OrderEventAny::Updated(OrderUpdated::new(
2002            order.trader_id(),
2003            order.strategy_id(),
2004            order.instrument_id(),
2005            order.client_order_id(),
2006            quantity,
2007            UUID4::new(),
2008            ts_now,
2009            ts_now,
2010            false,
2011            order.venue_order_id(),
2012            order.account_id(),
2013            price,
2014            trigger_price,
2015            None,
2016            order.is_quote_quantity(),
2017        ));
2018        self.dispatch_order_event(event);
2019    }
2020
2021    fn dispatch_order_event(&self, event: OrderEventAny) {
2022        if let Some(handler) = &self.event_handler {
2023            handler(event);
2024        } else {
2025            msgbus::send_order_event(MessagingSwitchboard::exec_engine_process(), event);
2026        }
2027    }
2028
2029    fn account_at_starting_balances(&self) -> bool {
2030        let Some(account) = self.get_account() else {
2031            return false;
2032        };
2033
2034        let balances = account.balances();
2035
2036        for starting in &self.starting_balances {
2037            let Some(balance) = balances.get(&starting.currency) else {
2038                return false;
2039            };
2040
2041            if balance.total != *starting || balance.free != *starting {
2042                return false;
2043            }
2044        }
2045
2046        true
2047    }
2048
2049    fn generate_fresh_account_state(&self) {
2050        let balances: Vec<AccountBalance> = self
2051            .starting_balances
2052            .iter()
2053            .map(|money| AccountBalance::new(*money, Money::zero(money.currency), *money))
2054            .collect();
2055
2056        if let Some(exec_client) = &self.exec_client {
2057            let ts_event = self.clock.borrow().timestamp_ns();
2058            exec_client
2059                .generate_account_state(balances, vec![], true, ts_event, None)
2060                .unwrap();
2061        }
2062
2063        let calculate_account_state = !self.frozen_account;
2064
2065        if let Some(mut account) = self.get_account() {
2066            account.set_calculate_account_state(calculate_account_state);
2067
2068            match &mut account {
2069                AccountAny::Margin(margin_account) => {
2070                    margin_account.set_default_leverage(self.default_leverage);
2071                    for (instrument_id, leverage) in &self.leverages {
2072                        margin_account.set_leverage(*instrument_id, *leverage);
2073                    }
2074
2075                    if let Some(model) = &self.margin_model {
2076                        margin_account.set_margin_model(model.clone());
2077                    }
2078                }
2079                AccountAny::Cash(cash_account) => {
2080                    cash_account.allow_borrowing = self.allow_cash_borrowing;
2081                }
2082                AccountAny::Betting(_) | AccountAny::Wallet(_) => {}
2083            }
2084
2085            self.cache.borrow_mut().update_account(&account).unwrap();
2086        }
2087    }
2088}
2089
2090#[derive(Clone, Copy)]
2091pub(crate) enum SettlementScope {
2092    All,
2093    Data(Option<InstrumentId>),
2094}
2095
2096/// Marks the window in which order events are routed to the deferred handler, and clears
2097/// it on drop so an unwind cannot leave the exchange deferring every later event.
2098#[derive(Debug)]
2099struct DeferEventsGuard {
2100    deferring: Rc<Cell<bool>>,
2101}
2102
2103impl DeferEventsGuard {
2104    fn new(deferring: Rc<Cell<bool>>) -> Self {
2105        deferring.set(true);
2106        Self { deferring }
2107    }
2108}
2109
2110impl Drop for DeferEventsGuard {
2111    fn drop(&mut self) {
2112        self.deferring.set(false);
2113    }
2114}
2115
2116struct FundingValuation {
2117    positions: Vec<(Position, Money)>,
2118    account_adjustments: Vec<Money>,
2119}
2120
2121fn value_funding_positions(
2122    funding_rate: &FundingRateUpdate,
2123    settlement_price: Price,
2124    open_positions: Vec<Position>,
2125    settlement_currency: Currency,
2126) -> Option<FundingValuation> {
2127    let mut valued_positions = Vec::with_capacity(open_positions.len());
2128    let mut account_adjustments: AHashMap<Currency, Money> = AHashMap::new();
2129
2130    for position in open_positions {
2131        let pnl_change = value_funding_position(
2132            funding_rate,
2133            settlement_price,
2134            &position,
2135            settlement_currency,
2136        )?;
2137
2138        let total_adjustment =
2139            if let Some(current) = account_adjustments.get(&pnl_change.currency).copied() {
2140                let Some(total) = current.checked_add(pnl_change) else {
2141                    log::error!(
2142                        "Cannot settle funding for {}: aggregate account adjustment overflow",
2143                        funding_rate.instrument_id
2144                    );
2145                    return None;
2146                };
2147
2148                total
2149            } else {
2150                pnl_change
2151            };
2152
2153        account_adjustments.insert(pnl_change.currency, total_adjustment);
2154        valued_positions.push((position, pnl_change));
2155    }
2156
2157    let mut account_adjustments = account_adjustments.into_values().collect::<Vec<_>>();
2158    account_adjustments.sort_unstable_by_key(|adjustment| adjustment.currency.code);
2159
2160    Some(FundingValuation {
2161        positions: valued_positions,
2162        account_adjustments,
2163    })
2164}
2165
2166fn value_funding_position(
2167    funding_rate: &FundingRateUpdate,
2168    settlement_price: Price,
2169    position: &Position,
2170    settlement_currency: Currency,
2171) -> Option<Money> {
2172    if position.settlement_currency != settlement_currency {
2173        log::error!(
2174            "Cannot settle funding for {}: position settlement currencies differ",
2175            funding_rate.instrument_id
2176        );
2177        return None;
2178    }
2179
2180    let notional = match position.try_notional_value(settlement_price) {
2181        Ok(notional) => notional,
2182        Err(e) => {
2183            log::error!(
2184                "Cannot settle funding for position {}: invalid notional value: {e}",
2185                position.id
2186            );
2187            return None;
2188        }
2189    };
2190
2191    let side = if position.signed_qty > Decimal::ZERO {
2192        -Decimal::ONE
2193    } else {
2194        Decimal::ONE
2195    };
2196
2197    let Some(amount) = notional
2198        .as_decimal()
2199        .checked_mul(funding_rate.rate)
2200        .and_then(|value| value.checked_mul(side))
2201    else {
2202        log::error!(
2203            "Cannot settle funding for position {}: funding amount overflow",
2204            position.id
2205        );
2206        return None;
2207    };
2208
2209    let pnl_change = match Money::from_decimal(amount, notional.currency) {
2210        Ok(money) => money,
2211        Err(e) => {
2212            log::error!(
2213                "Cannot settle funding for position {}: invalid funding amount: {e}",
2214                position.id
2215            );
2216            return None;
2217        }
2218    };
2219
2220    if pnl_change.currency != settlement_currency {
2221        log::error!(
2222            "Cannot settle funding for position {}: settlement currency {} differs from funding currency {}",
2223            position.id,
2224            settlement_currency,
2225            pnl_change.currency
2226        );
2227        return None;
2228    }
2229
2230    if let Some(realized) = position.realized_pnl {
2231        if realized.currency != pnl_change.currency {
2232            log::error!(
2233                "Cannot settle funding for position {}: realized PnL currency {} differs from funding currency {}",
2234                position.id,
2235                realized.currency,
2236                pnl_change.currency
2237            );
2238            return None;
2239        }
2240
2241        if realized.checked_add(pnl_change).is_none() {
2242            log::error!(
2243                "Cannot settle funding for position {}: realized PnL overflow",
2244                position.id
2245            );
2246            return None;
2247        }
2248    }
2249
2250    Some(pnl_change)
2251}
2252
2253fn convert_funding_adjustment(
2254    cache: &Cache,
2255    instrument_id: InstrumentId,
2256    account_venue: Venue,
2257    base_currency: Currency,
2258    adjustment: Money,
2259) -> Option<Money> {
2260    let xrate = match cache.try_get_xrate(
2261        account_venue,
2262        adjustment.currency,
2263        base_currency,
2264        PriceType::Mid,
2265    ) {
2266        Ok(Some(xrate)) => xrate,
2267        Ok(None) => {
2268            log::warn!(
2269                "Cannot settle funding for {}: no exchange rate from {} to {base_currency}",
2270                instrument_id,
2271                adjustment.currency
2272            );
2273            return None;
2274        }
2275        Err(e) => {
2276            log::warn!(
2277                "Cannot settle funding for {}: exchange rate from {} to {base_currency}: {e}",
2278                instrument_id,
2279                adjustment.currency
2280            );
2281            return None;
2282        }
2283    };
2284
2285    let Some(amount) = adjustment.as_decimal().checked_mul(xrate) else {
2286        log::error!("Cannot settle funding for {instrument_id}: currency conversion overflow");
2287        return None;
2288    };
2289
2290    let converted = match Money::from_decimal(amount, base_currency) {
2291        Ok(money) => money,
2292        Err(e) => {
2293            log::error!(
2294                "Cannot settle funding for {instrument_id}: invalid converted adjustment: {e}"
2295            );
2296            return None;
2297        }
2298    };
2299
2300    Some(converted)
2301}
2302
2303fn liquidation_unrealized_total(
2304    cache: &Cache,
2305    positions: &[Position],
2306    indices: &[usize],
2307) -> Option<f64> {
2308    let mut upnl = 0.0_f64;
2309    let mut bar_types = None;
2310    for &i in indices {
2311        let pnl = liquidation_unrealized_pnl(cache, &positions[i], &mut bar_types)?;
2312        upnl += pnl.as_f64();
2313    }
2314
2315    Some(upnl)
2316}
2317
2318// Reverts funding adjustments applied in place, newest first, restoring and persisting each
2319// position from the snapshot taken before settlement
2320fn revert_funding_adjustments(
2321    cache: &mut Cache,
2322    adjusted: &[(Position, PositionAdjusted)],
2323    failed_step: &str,
2324) {
2325    for (original, _) in adjusted.iter().rev() {
2326        if let Err(e) = cache.revert_position_adjustment(original) {
2327            log::error!(
2328                "Cannot roll back position {} after failed {failed_step}: {e}",
2329                original.id
2330            );
2331        }
2332    }
2333}
2334
2335// Values a position for the liquidation check with the portfolio's price fallback: mark price,
2336// then the side-appropriate quote, then the last trade, then the most recent bar close.
2337fn liquidation_unrealized_pnl(
2338    cache: &Cache,
2339    position: &Position,
2340    bar_types: &mut Option<AHashMap<InstrumentId, Vec<BarType>>>,
2341) -> Option<Money> {
2342    let instrument_id = &position.instrument_id;
2343    let price_type = match position.side {
2344        PositionSide::Long => PriceType::Bid,
2345        PositionSide::Short => PriceType::Ask,
2346        PositionSide::Flat => return Some(Money::zero(position.settlement_currency)),
2347    };
2348
2349    let allows_non_positive = || {
2350        cache
2351            .instrument(instrument_id)
2352            .is_some_and(Instrument::allows_negative_price)
2353    };
2354    let is_valid = |price: &Price| {
2355        !price.is_undefined()
2356            && !price.is_error()
2357            && (price.as_decimal() > Decimal::ZERO || allows_non_positive())
2358    };
2359    let quote_price = || {
2360        cache.quote(instrument_id).and_then(|quote| {
2361            let (price, size) = match price_type {
2362                PriceType::Bid => (quote.bid_price, quote.bid_size),
2363                _ => (quote.ask_price, quote.ask_size),
2364            };
2365            (is_valid(&price) && (price.as_decimal() > Decimal::ZERO || size.is_positive()))
2366                .then_some(price)
2367        })
2368    };
2369
2370    // Bars closing together rank in the fallback order above, then mid, then the opposite quote
2371    // side, then by bar type, so the choice never depends on cache iteration order.
2372    let bar_rank = |bar: &Bar| match bar.bar_type.spec().price_type {
2373        PriceType::Mark => 0,
2374        bar_price_type if bar_price_type == price_type => 1,
2375        PriceType::Last => 2,
2376        PriceType::Mid => 3,
2377        PriceType::Bid | PriceType::Ask => 4,
2378    };
2379
2380    // In a backtest `ts_init` is the bar close for open- and close-stamped bars alike
2381    let bar_close = || {
2382        // Index once per currency valuation, before any liquidation callbacks can change the cache
2383        let bar_types = bar_types.get_or_insert_with(|| liquidation_bar_types(cache));
2384        bar_types
2385            .get(instrument_id)
2386            .into_iter()
2387            .flatten()
2388            .filter_map(|bar_type| cache.bar(bar_type))
2389            .filter(|bar| is_valid(&bar.close))
2390            .min_by_key(|bar| (Reverse(bar.ts_init), bar_rank(bar), bar.bar_type))
2391            .map(|bar| bar.close)
2392    };
2393
2394    let Some(price) = cache
2395        .price(instrument_id, PriceType::Mark)
2396        .filter(is_valid)
2397        .or_else(quote_price)
2398        .or_else(|| cache.price(instrument_id, PriceType::Last).filter(is_valid))
2399        .or_else(bar_close)
2400    else {
2401        log::warn!(
2402            "Cannot value {} for liquidation, no mark, quote, trade or bar for {instrument_id}",
2403            position.id,
2404        );
2405        return None;
2406    };
2407
2408    position
2409        .try_unrealized_pnl(price)
2410        .inspect_err(|e| {
2411            log::error!("Cannot calculate unrealized PnL for {}: {e}", position.id);
2412        })
2413        .ok()
2414}
2415
2416fn liquidation_bar_types(cache: &Cache) -> AHashMap<InstrumentId, Vec<BarType>> {
2417    let mut by_instrument: AHashMap<InstrumentId, Vec<BarType>> = AHashMap::new();
2418
2419    for source in [AggregationSource::External, AggregationSource::Internal] {
2420        for bar_type in cache.bar_types(None, None, source) {
2421            by_instrument
2422                .entry(bar_type.instrument_id())
2423                .or_default()
2424                .push(*bar_type);
2425        }
2426    }
2427
2428    by_instrument
2429}
2430
2431// Compares two instruments' tradable definitions on their serialized form without event
2432// timestamps, so every field (including free-form `info`) takes part, and a serialization
2433// failure compares as changed so a different definition is never accepted.
2434fn instrument_definitions_match(a: &InstrumentAny, b: &InstrumentAny) -> bool {
2435    fn normalized(instrument: &InstrumentAny) -> Option<serde_json::Value> {
2436        let mut value = serde_json::to_value(instrument).ok()?;
2437
2438        if let Some(definition) = value
2439            .as_object_mut()
2440            .and_then(|obj| obj.values_mut().next())
2441            .and_then(serde_json::Value::as_object_mut)
2442        {
2443            definition.remove("ts_event");
2444            definition.remove("ts_init");
2445        }
2446
2447        Some(value)
2448    }
2449
2450    match (normalized(a), normalized(b)) {
2451        (Some(a), Some(b)) => a == b,
2452        _ => false,
2453    }
2454}
2455
2456#[cfg(test)]
2457mod tests {
2458    use nautilus_common::messages::execution::{QueryAccount, QueryOrder, SubmitOrder};
2459    use nautilus_core::DurationNanos;
2460    use nautilus_execution::models::{
2461        fee::{FeeModelAny, MakerTakerFeeModel},
2462        latency::{LatencyModelHandle, StaticLatencyModel},
2463    };
2464    use nautilus_model::{
2465        accounts::MarginAccount,
2466        data::BarSpecification,
2467        enums::{AccountType, BarAggregation, BookType, OrderSide, OrderType},
2468        events::AccountState,
2469        identifiers::{ClientOrderId, StrategyId, TradeId, TraderId},
2470        instruments::{
2471            CurrencyPair, InstrumentAny,
2472            stubs::{audusd_sim, futures_contract_es, gbpusd_sim},
2473        },
2474        orders::{OrderTestBuilder, stubs::TestOrderEventStubs},
2475        stubs::TestDefault,
2476        types::{
2477            AccountBalance,
2478            money::MONEY_RAW_MAX,
2479            price::{PRICE_ERROR, PRICE_UNDEF},
2480        },
2481    };
2482    use rstest::rstest;
2483    use rust_decimal_macros::dec;
2484
2485    use super::*;
2486    use crate::execution_client::BacktestExecutionClient;
2487
2488    #[derive(Clone, Copy)]
2489    enum LiquidationPriceSource {
2490        Mark,
2491        Quote,
2492        Trade,
2493        Bar,
2494    }
2495
2496    #[rstest]
2497    #[case::mark(LiquidationPriceSource::Mark)]
2498    #[case::quote(LiquidationPriceSource::Quote)]
2499    #[case::trade(LiquidationPriceSource::Trade)]
2500    #[case::bar(LiquidationPriceSource::Bar)]
2501    fn test_liquidation_rejects_sentinel_prices(
2502        #[case] source: LiquidationPriceSource,
2503        #[values(
2504            InstrumentAny::CurrencyPair(audusd_sim()),
2505            InstrumentAny::FuturesContract(futures_contract_es(None, None))
2506        )]
2507        instrument: InstrumentAny,
2508        #[values(OrderSide::Buy, OrderSide::Sell)] side: OrderSide,
2509        #[values(Price::from_raw(PRICE_UNDEF, 0), Price::from_raw(PRICE_ERROR, 0))] sentinel: Price,
2510        #[values(false, true)] has_fallback: bool,
2511    ) {
2512        let mut cache = Cache::default();
2513        cache.add_instrument(instrument.clone()).unwrap();
2514        let position = liquidation_position(&instrument, side);
2515        let ts = UnixNanos::from(2);
2516        let bar_spec = BarSpecification::new(1, BarAggregation::Minute, PriceType::Last);
2517        let bar_type = BarType::new(instrument.id(), bar_spec, AggregationSource::External);
2518
2519        if has_fallback {
2520            let value = match side {
2521                OrderSide::Buy => dec!(90),
2522                OrderSide::Sell => dec!(110),
2523            };
2524
2525            let close = Price::from_decimal_dp(value, instrument.price_precision()).unwrap();
2526
2527            let bar = Bar::new(
2528                bar_type,
2529                close,
2530                close,
2531                close,
2532                close,
2533                Quantity::from("1"),
2534                ts,
2535                ts,
2536            );
2537            cache.add_bar(bar).unwrap();
2538        }
2539
2540        match source {
2541            LiquidationPriceSource::Mark => {
2542                let mark = MarkPriceUpdate::new(instrument.id(), sentinel, ts, ts);
2543                cache.add_mark_price(mark).unwrap();
2544            }
2545            LiquidationPriceSource::Quote => {
2546                let valid = Price::from("100");
2547                let (bid, ask) = match side {
2548                    OrderSide::Buy => (sentinel, valid),
2549                    OrderSide::Sell => (valid, sentinel),
2550                };
2551
2552                let quote = QuoteTick::new(
2553                    instrument.id(),
2554                    bid,
2555                    ask,
2556                    Quantity::from("1"),
2557                    Quantity::from("2"),
2558                    ts,
2559                    ts,
2560                );
2561                cache.add_quote(quote).unwrap();
2562            }
2563            LiquidationPriceSource::Trade => {
2564                let trade = TradeTick::new(
2565                    instrument.id(),
2566                    sentinel,
2567                    Quantity::from("1"),
2568                    AggressorSide::Sell,
2569                    TradeId::from("T-SENTINEL"),
2570                    ts,
2571                    ts,
2572                );
2573                cache.add_trade(trade).unwrap();
2574            }
2575            LiquidationPriceSource::Bar => {
2576                let invalid_spec =
2577                    BarSpecification::new(1, BarAggregation::Second, PriceType::Last);
2578                let invalid_type =
2579                    BarType::new(instrument.id(), invalid_spec, AggregationSource::Internal);
2580                let later = UnixNanos::from(3);
2581
2582                let bar = Bar::new(
2583                    invalid_type,
2584                    sentinel,
2585                    sentinel,
2586                    sentinel,
2587                    sentinel,
2588                    Quantity::from("1"),
2589                    later,
2590                    later,
2591                );
2592                cache.add_bar(bar).unwrap();
2593            }
2594        }
2595
2596        let mut bar_types = None;
2597        let actual = liquidation_unrealized_pnl(&cache, &position, &mut bar_types);
2598
2599        let expected = has_fallback.then(|| {
2600            let amount = dec!(-10) * instrument.multiplier().as_decimal();
2601            Money::from_decimal(amount, instrument.settlement_currency()).unwrap()
2602        });
2603
2604        assert_eq!(actual, expected);
2605    }
2606
2607    #[rstest]
2608    #[case(false)]
2609    #[case(true)]
2610    fn test_liquidation_bar_index_keeps_instruments_and_sides_separate(#[case] reverse: bool) {
2611        let audusd = InstrumentAny::CurrencyPair(audusd_sim());
2612        let gbpusd = InstrumentAny::CurrencyPair(gbpusd_sim());
2613        let mut cache = Cache::default();
2614        for instrument in [&audusd, &gbpusd] {
2615            cache.add_instrument(instrument.clone()).unwrap();
2616        }
2617
2618        let ts = UnixNanos::from(2);
2619
2620        for (instrument, price_type, value, source) in [
2621            (
2622                &audusd,
2623                PriceType::Bid,
2624                dec!(90),
2625                AggregationSource::External,
2626            ),
2627            (
2628                &audusd,
2629                PriceType::Ask,
2630                dec!(110),
2631                AggregationSource::Internal,
2632            ),
2633            (
2634                &gbpusd,
2635                PriceType::Last,
2636                dec!(100),
2637                AggregationSource::External,
2638            ),
2639        ] {
2640            let spec = BarSpecification::new(1, BarAggregation::Minute, price_type);
2641            let bar_type = BarType::new(instrument.id(), spec, source);
2642            let close = Price::from_decimal_dp(value, instrument.price_precision()).unwrap();
2643
2644            let bar = Bar::new(
2645                bar_type,
2646                close,
2647                close,
2648                close,
2649                close,
2650                Quantity::from("1"),
2651                ts,
2652                ts,
2653            );
2654            cache.add_bar(bar).unwrap();
2655        }
2656
2657        let mut positions = [
2658            (liquidation_position(&audusd, OrderSide::Buy), dec!(-10)),
2659            (liquidation_position(&audusd, OrderSide::Sell), dec!(-10)),
2660            (liquidation_position(&gbpusd, OrderSide::Buy), dec!(0)),
2661        ];
2662
2663        if reverse {
2664            positions.reverse();
2665        }
2666
2667        let mut bar_types = None;
2668        let actual: Vec<_> = positions
2669            .iter()
2670            .map(|(position, _)| liquidation_unrealized_pnl(&cache, position, &mut bar_types))
2671            .collect();
2672        let expected: Vec<_> = positions
2673            .iter()
2674            .map(|(_, amount)| Some(Money::from_decimal(*amount, Currency::USD()).unwrap()))
2675            .collect();
2676
2677        assert_eq!(actual, expected);
2678    }
2679
2680    fn liquidation_position(instrument: &InstrumentAny, side: OrderSide) -> Position {
2681        let order = OrderTestBuilder::new(OrderType::Market)
2682            .instrument_id(instrument.id())
2683            .side(side)
2684            .quantity(Quantity::from("1"))
2685            .build();
2686        let price = Price::from_decimal_dp(dec!(100), instrument.price_precision()).unwrap();
2687        let fill = TestOrderEventStubs::filled(
2688            &order,
2689            instrument,
2690            None,
2691            None,
2692            Some(price),
2693            None,
2694            None,
2695            None,
2696            None,
2697            None,
2698        );
2699        Position::new(instrument, fill.into())
2700    }
2701
2702    #[rstest]
2703    #[case::position_failure(false)]
2704    #[case::account_failure(true)]
2705    fn test_funding_application_rolls_back_positions(#[case] account_failure: bool) {
2706        let instrument = InstrumentAny::CurrencyPair(audusd_sim());
2707        let exchange = Rc::new(RefCell::new(setup_exchange(Dispatch::Queued)));
2708        let cache = exchange.borrow().cache.clone();
2709        let clock = exchange.borrow().clock.clone();
2710
2711        let client = BacktestExecutionClient::new(
2712            TraderId::test_default(),
2713            AccountId::test_default(),
2714            &exchange,
2715            cache.clone(),
2716            clock,
2717            None,
2718            None,
2719        );
2720
2721        exchange.borrow_mut().register_client(Rc::new(client));
2722        let mut adjusted_positions = Vec::new();
2723
2724        for (index, id) in ["P-FUND-A", "P-FUND-B"].into_iter().enumerate() {
2725            let mut original = liquidation_position(&instrument, OrderSide::Buy);
2726            original.id = id.into();
2727            cache
2728                .borrow_mut()
2729                .add_position(&original, OmsType::Hedging)
2730                .unwrap();
2731
2732            let currency = if index == 1 && !account_failure {
2733                Currency::AUD()
2734            } else {
2735                Currency::USD()
2736            };
2737
2738            let pnl_change = Money::from_decimal(dec!(-3.25), currency).unwrap();
2739
2740            let adjustment = PositionAdjusted::new(
2741                original.trader_id,
2742                original.strategy_id,
2743                original.instrument_id,
2744                original.id,
2745                original.account_id,
2746                PositionAdjustmentType::Funding,
2747                None,
2748                Some(pnl_change),
2749                None,
2750                UUID4::new(),
2751                UnixNanos::from(2),
2752                UnixNanos::from(3),
2753            );
2754
2755            adjusted_positions.push((original, adjustment));
2756        }
2757
2758        let applied = exchange
2759            .borrow()
2760            .apply_funding_adjustments(&adjusted_positions, &[Money::from("-6.50 USD")]);
2761
2762        assert!(!applied);
2763
2764        for (original, _) in adjusted_positions {
2765            let actual = cache.borrow().position_owned(&original.id).unwrap();
2766            assert_eq!(
2767                serde_json::to_value(&actual).unwrap(),
2768                serde_json::to_value(&original).unwrap()
2769            );
2770        }
2771    }
2772
2773    #[rstest]
2774    #[case::decimal_overflow(Decimal::MAX)]
2775    #[case::money_bounds(Money::from_raw(MONEY_RAW_MAX, Currency::USD()).as_decimal())]
2776    fn test_funding_valuation_rejects_overflow(#[case] rate: Decimal) {
2777        let instrument = InstrumentAny::CurrencyPair(audusd_sim());
2778        let position = liquidation_position(&instrument, OrderSide::Buy);
2779
2780        let funding_rate = FundingRateUpdate::new(
2781            instrument.id(),
2782            rate,
2783            Some(480),
2784            None,
2785            UnixNanos::from(2),
2786            UnixNanos::from(3),
2787        );
2788
2789        let valued = value_funding_position(
2790            &funding_rate,
2791            Price::from("100.00000"),
2792            &position,
2793            Currency::USD(),
2794        );
2795        assert_eq!(valued, None);
2796    }
2797
2798    /// The three `send` dispatch modes a query must be intercepted ahead of.
2799    #[derive(Clone, Copy)]
2800    enum Dispatch {
2801        /// `use_message_queue = true` with a latency model: `inflight_queue`.
2802        Latency,
2803        /// `use_message_queue = true`, no latency: `message_queue`.
2804        Queued,
2805        /// `use_message_queue = false`: synchronous `process_trading_command`.
2806        Immediate,
2807    }
2808
2809    fn setup_exchange(dispatch: Dispatch) -> SimulatedExchange {
2810        let cache = Rc::new(RefCell::new(Cache::default()));
2811        let clock: Rc<RefCell<dyn Clock>> = Rc::new(RefCell::new(VirtualClock::new()));
2812        let mut config = SimulatedVenueConfig::builder()
2813            .venue(Venue::new("SIM"))
2814            .oms_type(OmsType::Netting)
2815            .account_type(AccountType::Margin)
2816            .book_type(BookType::L2_MBP)
2817            .starting_balances(vec![Money::new(1_000.0, Currency::USD())])
2818            .fee_model(FeeModelAny::MakerTaker(MakerTakerFeeModel::zero()).into())
2819            .build()
2820            .unwrap();
2821
2822        match dispatch {
2823            Dispatch::Latency => {
2824                config.latency_model = Some(LatencyModelHandle::new(StaticLatencyModel::new(
2825                    DurationNanos::default(),
2826                    DurationNanos::default(),
2827                    DurationNanos::default(),
2828                    DurationNanos::default(),
2829                )));
2830            }
2831            Dispatch::Queued => {} // Defaults: use_message_queue = true, no latency
2832            Dispatch::Immediate => config.use_message_queue = false,
2833        }
2834
2835        SimulatedExchange::new(config, cache, clock).unwrap()
2836    }
2837
2838    #[rstest]
2839    fn test_modify_order_priority_config_reaches_matching_engine(
2840        #[values(
2841            OrderPriorityResetPolicy::PriceChange,
2842            OrderPriorityResetPolicy::PriceOrQuantityIncrease,
2843            OrderPriorityResetPolicy::AnyModify
2844        )]
2845        policy: OrderPriorityResetPolicy,
2846    ) {
2847        let cache = Rc::new(RefCell::new(Cache::default()));
2848        let clock: Rc<RefCell<dyn Clock>> = Rc::new(RefCell::new(VirtualClock::new()));
2849        let config = SimulatedVenueConfig::builder()
2850            .venue(Venue::from("SIM"))
2851            .oms_type(OmsType::Netting)
2852            .account_type(AccountType::Margin)
2853            .book_type(BookType::L2_MBP)
2854            .starting_balances(vec![Money::from("1_000 USD")])
2855            .fee_model(FeeModelAny::MakerTaker(MakerTakerFeeModel::zero()).into())
2856            .order_priority_reset_policy(policy)
2857            .build()
2858            .unwrap();
2859        let mut exchange = SimulatedExchange::new(config, cache.clone(), clock).unwrap();
2860        let instrument = InstrumentAny::CurrencyPair(audusd_sim());
2861        exchange.add_instrument(instrument.clone()).unwrap();
2862        let engine = exchange.matching_engines.get_mut(&instrument.id()).unwrap();
2863        engine.set_event_handler(Rc::new(move |event| {
2864            cache.borrow_mut().update_order(&event).unwrap();
2865        }));
2866
2867        let ids = [
2868            ClientOrderId::from("MODIFY-FIRST"),
2869            ClientOrderId::from("MODIFY-SECOND"),
2870        ];
2871
2872        for id in ids {
2873            let mut order = OrderTestBuilder::new(OrderType::Limit)
2874                .instrument_id(instrument.id())
2875                .client_order_id(id)
2876                .side(OrderSide::Buy)
2877                .price(Price::from("1.00000"))
2878                .quantity(Quantity::from("5"))
2879                .submit(true)
2880                .build();
2881            exchange
2882                .cache
2883                .borrow_mut()
2884                .add_order(order.clone(), None, None, false)
2885                .unwrap();
2886            engine.process_order(&mut order, AccountId::from("SIM-001"));
2887        }
2888
2889        let order = exchange.cache.borrow().order(&ids[0]).unwrap().clone();
2890        engine.process_modify(
2891            &ModifyOrder::new(
2892                order.trader_id(),
2893                None,
2894                order.strategy_id(),
2895                order.instrument_id(),
2896                ids[0],
2897                order.venue_order_id(),
2898                Some(Quantity::from("3")),
2899                None,
2900                None,
2901                UUID4::new(),
2902                1.into(),
2903                None,
2904                None,
2905            ),
2906            AccountId::from("SIM-001"),
2907        );
2908
2909        let expected = if policy == OrderPriorityResetPolicy::AnyModify {
2910            vec![ids[1], ids[0]]
2911        } else {
2912            ids.to_vec()
2913        };
2914
2915        assert_eq!(
2916            engine
2917                .get_core()
2918                .get_orders_bid()
2919                .iter()
2920                .map(|o| o.client_order_id)
2921                .collect::<Vec<_>>(),
2922            expected
2923        );
2924        assert_eq!(
2925            exchange.cache.borrow().order(&ids[0]).unwrap().quantity(),
2926            Quantity::from("3")
2927        );
2928    }
2929
2930    #[rstest]
2931    fn test_replay_instrument_expiration_change_is_rejected() {
2932        let mut exchange = setup_exchange(Dispatch::Queued);
2933        let mut option = nautilus_model::instruments::stubs::option_contract_appl();
2934        option.id = InstrumentId::from("TEST.SIM");
2935        let original = InstrumentAny::OptionContract(option.clone());
2936        exchange.add_instrument(original.clone()).unwrap();
2937        exchange.update_instrument(&original).unwrap();
2938        option.expiration_ns = UnixNanos::from(10);
2939
2940        let error = exchange
2941            .update_instrument(&InstrumentAny::OptionContract(option))
2942            .unwrap_err();
2943
2944        assert!(error.to_string().contains("Cannot change expiration"));
2945        let cache = exchange.cache.borrow();
2946        for instrument in [
2947            &exchange.instruments[&original.id()],
2948            &exchange.matching_engines[&original.id()].instrument,
2949            cache.instrument(&original.id()).unwrap(),
2950        ] {
2951            assert_eq!(instrument.expiration_ns(), original.expiration_ns());
2952        }
2953    }
2954
2955    #[rstest]
2956    #[case(false)]
2957    #[case(true)]
2958    fn test_liquidation_enabled(#[case] expected: bool) {
2959        let cache = Rc::new(RefCell::new(Cache::default()));
2960        let clock: Rc<RefCell<dyn Clock>> = Rc::new(RefCell::new(VirtualClock::new()));
2961        let config = SimulatedVenueConfig::builder()
2962            .venue(Venue::new("SIM"))
2963            .oms_type(OmsType::Netting)
2964            .account_type(AccountType::Margin)
2965            .book_type(BookType::L1_MBP)
2966            .starting_balances(vec![Money::new(1_000.0, Currency::USD())])
2967            .liquidation_enabled(expected)
2968            .fee_model(FeeModelAny::MakerTaker(MakerTakerFeeModel::zero()).into())
2969            .build()
2970            .unwrap();
2971        let exchange = SimulatedExchange::new(config, cache, clock).unwrap();
2972
2973        assert_eq!(exchange.liquidation_enabled(), expected);
2974    }
2975
2976    #[rstest]
2977    #[case(AccountType::Margin, Decimal::from(10))]
2978    #[case(AccountType::Cash, Decimal::ONE)]
2979    fn test_default_leverage_uses_account_type(
2980        #[case] account_type: AccountType,
2981        #[case] expected: Decimal,
2982    ) {
2983        let config = SimulatedVenueConfig::builder()
2984            .venue(Venue::new("SIM"))
2985            .oms_type(OmsType::Netting)
2986            .account_type(account_type)
2987            .book_type(BookType::L1_MBP)
2988            .starting_balances(vec![Money::from("1_000 USD")])
2989            .fee_model(FeeModelAny::MakerTaker(MakerTakerFeeModel::zero()).into())
2990            .build()
2991            .unwrap();
2992        let cache = Rc::new(RefCell::new(Cache::default()));
2993        let clock: Rc<RefCell<dyn Clock>> = Rc::new(RefCell::new(VirtualClock::new()));
2994
2995        let exchange = SimulatedExchange::new(config, cache, clock).unwrap();
2996
2997        assert_eq!(exchange.default_leverage, expected);
2998    }
2999
3000    fn query_order() -> TradingCommand {
3001        TradingCommand::QueryOrder(QueryOrder::new(
3002            TraderId::test_default(),
3003            None,
3004            StrategyId::test_default(),
3005            InstrumentId::from("AUD/USD.SIM"),
3006            ClientOrderId::from("O-001"),
3007            None,
3008            UUID4::new(),
3009            UnixNanos::default(),
3010            None,
3011            None,
3012        ))
3013    }
3014
3015    fn query_account() -> TradingCommand {
3016        TradingCommand::QueryAccount(QueryAccount::new(
3017            TraderId::test_default(),
3018            None,
3019            AccountId::test_default(),
3020            UUID4::new(),
3021            UnixNanos::default(),
3022            None,
3023            None,
3024        ))
3025    }
3026
3027    #[rstest]
3028    fn test_inflight_command_matches_settlement_scope() {
3029        let inflight = InflightCommand::new(UnixNanos::from(1), 0, query_order());
3030        let instrument_id = InstrumentId::from("AUD/USD.SIM");
3031        let other_id = InstrumentId::from("GBP/USD.SIM");
3032
3033        assert!(inflight.matches_scope(UnixNanos::from(1), SettlementScope::All));
3034        assert!(inflight.matches_scope(
3035            UnixNanos::from(1),
3036            SettlementScope::Data(Some(instrument_id)),
3037        ));
3038        assert!(
3039            !inflight.matches_scope(UnixNanos::from(1), SettlementScope::Data(Some(other_id)),)
3040        );
3041        assert!(!inflight.matches_scope(UnixNanos::from(1), SettlementScope::Data(None)));
3042        assert!(inflight.matches_scope(UnixNanos::default(), SettlementScope::Data(None)));
3043    }
3044
3045    #[rstest]
3046    #[case(Dispatch::Latency)]
3047    #[case(Dispatch::Queued)]
3048    #[case(Dispatch::Immediate)]
3049    fn test_send_query_order_is_no_op(#[case] dispatch: Dispatch) {
3050        let mut exchange = setup_exchange(dispatch);
3051
3052        exchange.send(query_order());
3053
3054        assert!(!exchange.has_pending_commands(UnixNanos::from(u64::MAX)));
3055        assert_eq!(exchange.max_inflight_command_ts(), None);
3056    }
3057
3058    #[rstest]
3059    #[case(Dispatch::Latency)]
3060    #[case(Dispatch::Queued)]
3061    #[case(Dispatch::Immediate)]
3062    fn test_send_query_account_is_no_op(#[case] dispatch: Dispatch) {
3063        let mut exchange = setup_exchange(dispatch);
3064
3065        exchange.send(query_account());
3066
3067        assert!(!exchange.has_pending_commands(UnixNanos::from(u64::MAX)));
3068        assert_eq!(exchange.max_inflight_command_ts(), None);
3069    }
3070
3071    #[rstest]
3072    fn test_add_instrument_raw_id_overflow_does_not_mutate_maps(audusd_sim: CurrencyPair) {
3073        let mut exchange = setup_exchange(Dispatch::Immediate);
3074        exchange.last_raw_id = u32::MAX;
3075
3076        let result = exchange.add_instrument(InstrumentAny::CurrencyPair(audusd_sim));
3077
3078        assert!(result.is_err());
3079        assert!(exchange.instruments.is_empty());
3080        assert!(exchange.matching_engines.is_empty());
3081        assert_eq!(exchange.last_raw_id, u32::MAX);
3082    }
3083
3084    #[rstest]
3085    fn test_add_identical_instrument_is_noop(audusd_sim: CurrencyPair) {
3086        let mut exchange = setup_exchange(Dispatch::Immediate);
3087        exchange
3088            .add_instrument(InstrumentAny::CurrencyPair(audusd_sim.clone()))
3089            .unwrap();
3090
3091        let mut restamped = audusd_sim.clone();
3092        restamped.ts_event = UnixNanos::from(1);
3093        restamped.ts_init = UnixNanos::from(1);
3094        exchange
3095            .add_instrument(InstrumentAny::CurrencyPair(restamped))
3096            .unwrap();
3097
3098        assert_eq!(exchange.instruments.len(), 1);
3099        assert_eq!(exchange.matching_engines.len(), 1);
3100        assert_eq!(exchange.matching_engines[&audusd_sim.id].raw_id, 1);
3101        assert_eq!(exchange.last_raw_id, 1);
3102        assert_eq!(
3103            exchange.instruments[&audusd_sim.id].ts_init(),
3104            UnixNanos::default()
3105        );
3106    }
3107
3108    #[rstest]
3109    #[case::price_increment(|pair: &mut CurrencyPair| {
3110        pair.price_precision = 4;
3111        pair.price_increment = Price::from("0.0001");
3112    })]
3113    #[case::lot_size(|pair: &mut CurrencyPair| pair.lot_size = Some(Quantity::from(100)))]
3114    #[case::margin_init(|pair: &mut CurrencyPair| pair.margin_init = dec!(0.5))]
3115    #[case::max_quantity(|pair: &mut CurrencyPair| pair.max_quantity = Some(Quantity::from(10)))]
3116    fn test_add_changed_instrument_is_rejected_without_state_change(
3117        audusd_sim: CurrencyPair,
3118        #[case] change: fn(&mut CurrencyPair),
3119    ) {
3120        let mut exchange = setup_exchange(Dispatch::Immediate);
3121        exchange
3122            .add_instrument(InstrumentAny::CurrencyPair(audusd_sim.clone()))
3123            .unwrap();
3124        let mut changed = audusd_sim.clone();
3125        change(&mut changed);
3126
3127        let result = exchange.add_instrument(InstrumentAny::CurrencyPair(changed));
3128
3129        assert_eq!(
3130            result.unwrap_err().to_string(),
3131            "Instrument AUD/USD.SIM is already registered with a different definition"
3132        );
3133        assert_eq!(exchange.instruments.len(), 1);
3134        assert_eq!(exchange.matching_engines.len(), 1);
3135        assert_eq!(exchange.matching_engines[&audusd_sim.id].raw_id, 1);
3136        assert_eq!(exchange.last_raw_id, 1);
3137        assert_eq!(
3138            serde_json::to_value(&exchange.instruments[&audusd_sim.id]).unwrap(),
3139            serde_json::to_value(InstrumentAny::CurrencyPair(audusd_sim)).unwrap()
3140        );
3141    }
3142
3143    #[rstest]
3144    fn test_reset_clears_inflight_counter() {
3145        let mut exchange = setup_exchange(Dispatch::Latency);
3146        let account = MarginAccount::new(
3147            AccountState::new(
3148                AccountId::test_default(),
3149                AccountType::Margin,
3150                vec![AccountBalance::new(
3151                    Money::from("1000 USD"),
3152                    Money::from("0 USD"),
3153                    Money::from("1000 USD"),
3154                )],
3155                vec![],
3156                false,
3157                UUID4::default(),
3158                UnixNanos::default(),
3159                UnixNanos::default(),
3160                None,
3161            ),
3162            false,
3163        );
3164        exchange
3165            .cache
3166            .borrow_mut()
3167            .add_account(AccountAny::Margin(account))
3168            .unwrap();
3169
3170        let order = OrderTestBuilder::new(OrderType::Limit)
3171            .instrument_id(InstrumentId::from("AUD/USD.SIM"))
3172            .client_order_id(ClientOrderId::from("O-RESET"))
3173            .side(OrderSide::Buy)
3174            .quantity(Quantity::from("1"))
3175            .price(Price::from("1.00000"))
3176            .build();
3177        exchange
3178            .cache
3179            .borrow_mut()
3180            .add_order(order.clone(), None, None, false)
3181            .unwrap();
3182        exchange
3183            .cache
3184            .borrow_mut()
3185            .update_order(&TestOrderEventStubs::submitted(
3186                &order,
3187                AccountId::test_default(),
3188            ))
3189            .unwrap();
3190        exchange.send(TradingCommand::SubmitOrder(SubmitOrder::new(
3191            TraderId::test_default(),
3192            None,
3193            StrategyId::test_default(),
3194            order.instrument_id(),
3195            order.client_order_id(),
3196            order.init_event().clone(),
3197            None,
3198            None,
3199            None,
3200            UUID4::default(),
3201            UnixNanos::from(100),
3202            None,
3203        )));
3204
3205        assert_eq!(exchange.inflight_counter.len(), 1);
3206
3207        exchange.reset().unwrap();
3208
3209        assert!(exchange.inflight_counter.is_empty());
3210    }
3211
3212    #[cfg(feature = "python")]
3213    mod python_latency {
3214        use std::ffi::CString;
3215
3216        use nautilus_common::messages::execution::CancelAllOrders;
3217        use nautilus_execution::python::latency::{PyLatencyModel, pyobject_to_latency_model_any};
3218        use pyo3::{prelude::*, types::PyDict};
3219
3220        use super::*;
3221
3222        #[rstest]
3223        fn test_python_latency_schedules_once_with_clock_and_command_time() {
3224            let mut exchange = setup_exchange(Dispatch::Latency);
3225            exchange.set_clock_time(UnixNanos::new(500));
3226            let (model, obj) = recorded_latency("11");
3227            exchange.set_latency_model(model);
3228            exchange.send(cancel_command());
3229
3230            let calls = Python::attach(|py| {
3231                obj.bind(py)
3232                    .getattr("calls")
3233                    .unwrap()
3234                    .extract::<Vec<(u64, u64)>>()
3235                    .unwrap()
3236            });
3237
3238            assert_eq!(calls, vec![(100, 500)]);
3239            assert_eq!(
3240                exchange.max_inflight_command_ts(),
3241                Some(UnixNanos::new(111))
3242            );
3243            assert_eq!(exchange.inflight_queue.len(), 1);
3244            assert_eq!(
3245                exchange.inflight_counter.get(&UnixNanos::new(111)),
3246                Some(&1)
3247            );
3248            assert!(exchange.callback_error.is_none());
3249        }
3250
3251        #[rstest]
3252        #[case("-1", "Python LatencyModel.get_delete_latency failed:")]
3253        #[case("2 ** 64 - 1", "Latency arrival timestamp exceeds u64 nanoseconds")]
3254        #[case(
3255            "(_ for _ in ()).throw(ValueError('sample failed'))",
3256            "ValueError: sample failed"
3257        )]
3258        fn test_python_latency_failure_latches_without_queuing(
3259            #[case] delay: &str,
3260            #[case] message: &str,
3261        ) {
3262            let mut exchange = setup_exchange(Dispatch::Latency);
3263            let (model, obj) = recorded_latency(delay);
3264            exchange.set_latency_model(model);
3265            exchange.send(cancel_command());
3266            exchange.send(cancel_command());
3267
3268            let calls = Python::attach(|py| {
3269                obj.bind(py)
3270                    .getattr("calls")
3271                    .unwrap()
3272                    .extract::<Vec<(u64, u64)>>()
3273                    .unwrap()
3274            });
3275
3276            assert_eq!(calls, vec![(100, 0)]);
3277            assert!(
3278                exchange
3279                    .check_callback_error()
3280                    .unwrap_err()
3281                    .to_string()
3282                    .contains(message)
3283            );
3284            assert_eq!(exchange.max_inflight_command_ts(), None);
3285            assert!(exchange.inflight_queue.is_empty());
3286            assert!(exchange.message_queue.is_empty());
3287            assert!(exchange.inflight_counter.is_empty());
3288        }
3289
3290        fn cancel_command() -> TradingCommand {
3291            TradingCommand::CancelAllOrders(CancelAllOrders::new(
3292                TraderId::test_default(),
3293                None,
3294                StrategyId::test_default(),
3295                InstrumentId::from("AUD/USD.SIM"),
3296                None,
3297                UUID4::new(),
3298                UnixNanos::new(100),
3299                None,
3300                None,
3301            ))
3302        }
3303
3304        fn recorded_latency(delay: &str) -> (LatencyModelHandle, Py<PyAny>) {
3305            Python::initialize();
3306            Python::attach(|py| {
3307                let locals = PyDict::new(py);
3308                locals
3309                    .set_item("LatencyModel", py.get_type::<PyLatencyModel>())
3310                    .unwrap();
3311                let source = format!(
3312                    "type('RecordedLatency', (LatencyModel,), {{'calls': [], 'get_delete_latency': lambda self, command, ts_now: self.calls.append((command.ts_init, ts_now)) or ({delay})}})()"
3313                );
3314                let source = CString::new(source).unwrap();
3315                let obj = py.eval(&source, Some(&locals), None).unwrap();
3316                let model = pyobject_to_latency_model_any(&obj).unwrap().into();
3317                (model, obj.unbind())
3318            })
3319        }
3320    }
3321}