Skip to main content

nautilus_execution/matching_engine/
config.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
16use serde::{Deserialize, Serialize};
17
18/// Configuration for `OrderMatchingEngine` instances.
19///
20/// With `defer_option_settlement`, automatic checks at the exact option expiry
21/// timestamp cancel orders but defer settlement to `process_instrument_expiration`.
22/// To settle at expiry, the caller schedules that call after processing the
23/// timestamp's market data. Automatic checks after expiry can also settle.
24/// Explicit contract-close events bypass this deferral.
25#[derive(Debug, Clone, Deserialize, Serialize, bon::Builder)]
26#[serde(default, deny_unknown_fields)]
27pub struct OrderMatchingEngineConfig {
28    #[builder(default = true)]
29    pub bar_execution: bool,
30    #[builder(default)]
31    pub bar_adaptive_high_low_ordering: bool,
32    #[builder(default = true)]
33    pub trade_execution: bool,
34    #[builder(default)]
35    pub liquidity_consumption: bool,
36    #[builder(default = true)]
37    pub reject_stop_orders: bool,
38    #[builder(default = true)]
39    pub support_gtd_orders: bool,
40    #[builder(default = true)]
41    pub support_contingent_orders: bool,
42    #[builder(default = true)]
43    pub use_position_ids: bool,
44    #[builder(default)]
45    pub use_random_ids: bool,
46    #[builder(default = true)]
47    pub use_reduce_only: bool,
48    #[builder(default)]
49    pub use_market_order_acks: bool,
50    #[builder(default)]
51    pub queue_position: bool,
52    #[builder(default)]
53    pub oto_full_trigger: bool,
54    #[builder(default)]
55    pub defer_option_settlement: bool,
56    pub price_protection_points: Option<u32>,
57    /// The queue-priority reset policy for successful modify commands.
58    #[builder(default)]
59    pub order_priority_reset_policy: OrderPriorityResetPolicy,
60}
61
62impl Default for OrderMatchingEngineConfig {
63    fn default() -> Self {
64        Self::builder().build()
65    }
66}
67
68/// Determines when successful modify commands reset queue position and same-price priority.
69#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
70#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
71#[cfg_attr(
72    feature = "python",
73    pyo3::pyclass(
74        frozen,
75        eq,
76        eq_int,
77        module = "nautilus_trader.execution",
78        from_py_object,
79        rename_all = "SCREAMING_SNAKE_CASE",
80    )
81)]
82#[cfg_attr(
83    feature = "python",
84    pyo3_stub_gen::derive::gen_stub_pyclass_enum(module = "nautilus_trader.execution")
85)]
86pub enum OrderPriorityResetPolicy {
87    /// Preserve quantity-only modifications and retain existing price-change handling.
88    #[default]
89    PriceChange = 0,
90    /// Reset when the limit or trigger price changes, or the total order quantity increases.
91    PriceOrQuantityIncrease = 1,
92    /// Reset after every successful modify command, including unchanged values.
93    AnyModify = 2,
94}
95
96#[cfg(feature = "python")]
97#[pyo3::pymethods]
98#[pyo3_stub_gen::derive::gen_stub_pymethods]
99impl OrderPriorityResetPolicy {
100    #[allow(
101        clippy::trivially_copy_pass_by_ref,
102        reason = "PyO3 protocol methods borrow their receivers"
103    )]
104    const fn __hash__(&self) -> isize {
105        *self as isize
106    }
107}
108
109#[cfg(test)]
110mod tests {
111    use rstest::rstest;
112
113    use super::*;
114
115    #[rstest]
116    fn test_default() {
117        let config = OrderMatchingEngineConfig::default();
118        assert!(config.bar_execution);
119        assert!(!config.bar_adaptive_high_low_ordering);
120        assert!(config.trade_execution);
121        assert!(!config.liquidity_consumption);
122        assert!(config.reject_stop_orders);
123        assert!(config.support_gtd_orders);
124        assert!(config.support_contingent_orders);
125        assert!(config.use_position_ids);
126        assert!(!config.use_random_ids);
127        assert!(config.use_reduce_only);
128        assert!(!config.use_market_order_acks);
129        assert!(!config.queue_position);
130        assert_eq!(
131            config.order_priority_reset_policy,
132            OrderPriorityResetPolicy::PriceChange
133        );
134        assert!(!config.oto_full_trigger);
135        assert!(!config.defer_option_settlement);
136        assert_eq!(config.price_protection_points, None);
137    }
138
139    #[rstest]
140    #[case(OrderPriorityResetPolicy::PriceChange, "PRICE_CHANGE")]
141    #[case(
142        OrderPriorityResetPolicy::PriceOrQuantityIncrease,
143        "PRICE_OR_QUANTITY_INCREASE"
144    )]
145    #[case(OrderPriorityResetPolicy::AnyModify, "ANY_MODIFY")]
146    fn test_order_priority_reset_policy_serde(
147        #[case] policy: OrderPriorityResetPolicy,
148        #[case] name: &str,
149    ) {
150        let value = serde_json::Value::String(name.to_owned());
151        assert_eq!(serde_json::to_value(policy).unwrap(), value);
152        assert_eq!(
153            serde_json::from_value::<OrderPriorityResetPolicy>(value).unwrap(),
154            policy
155        );
156    }
157}