nautilus_model/instruments/
crypto_option_spread.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 std::hash::{Hash, Hasher};
17
18use nautilus_core::{
19    Params, UnixNanos,
20    correctness::{CorrectnessResult, check_equal_u8, check_valid_string_ascii},
21};
22use rust_decimal::Decimal;
23use serde::{Deserialize, Serialize};
24use ustr::Ustr;
25
26use super::{Instrument, any::InstrumentAny, tick_scheme::check_tick_scheme};
27use crate::{
28    enums::{AssetClass, InstrumentClass, OptionKind},
29    identifiers::{InstrumentId, Symbol},
30    types::{
31        currency::Currency,
32        money::Money,
33        price::{Price, check_positive_price},
34        quantity::{Quantity, check_positive_quantity},
35    },
36};
37
38/// Represents a crypto option spread instrument, with crypto assets as underlying and for
39/// settlement.
40#[repr(C)]
41#[derive(Clone, Debug, Serialize, Deserialize)]
42#[cfg_attr(
43    feature = "python",
44    pyo3::pyclass(module = "nautilus_trader.model", from_py_object)
45)]
46#[cfg_attr(
47    feature = "python",
48    pyo3_stub_gen::derive::gen_stub_pyclass(module = "nautilus_trader.model")
49)]
50pub struct CryptoOptionSpread {
51    /// The instrument ID.
52    pub id: InstrumentId,
53    /// The raw/local/native symbol for the instrument, assigned by the venue.
54    pub raw_symbol: Symbol,
55    /// The underlying asset.
56    pub underlying: Currency,
57    /// The contract quote currency.
58    pub quote_currency: Currency,
59    /// The settlement currency.
60    pub settlement_currency: Currency,
61    /// If the instrument costing is inverse (quantity expressed in quote currency units).
62    pub is_inverse: bool,
63    /// The strategy type for the spread.
64    pub strategy_type: Ustr,
65    /// UNIX timestamp (nanoseconds) for contract activation.
66    pub activation_ns: UnixNanos,
67    /// UNIX timestamp (nanoseconds) for contract expiration.
68    pub expiration_ns: UnixNanos,
69    /// The price decimal precision.
70    pub price_precision: u8,
71    /// The trading size decimal precision.
72    pub size_precision: u8,
73    /// The minimum price increment (tick size).
74    pub price_increment: Price,
75    /// The minimum size increment.
76    pub size_increment: Quantity,
77    /// The option multiplier.
78    pub multiplier: Quantity,
79    /// The rounded lot unit size (standard/board).
80    pub lot_size: Quantity,
81    /// The initial (order) margin requirement in percentage of order value.
82    pub margin_init: Decimal,
83    /// The maintenance (position) margin in percentage of position value.
84    pub margin_maint: Decimal,
85    /// The fee rate for liquidity makers as a percentage of order value.
86    pub maker_fee: Decimal,
87    /// The fee rate for liquidity takers as a percentage of order value.
88    pub taker_fee: Decimal,
89    /// The maximum allowable order quantity.
90    pub max_quantity: Option<Quantity>,
91    /// The minimum allowable order quantity.
92    pub min_quantity: Option<Quantity>,
93    /// The maximum allowable order notional value.
94    pub max_notional: Option<Money>,
95    /// The minimum allowable order notional value.
96    pub min_notional: Option<Money>,
97    /// The maximum allowable quoted price.
98    pub max_price: Option<Price>,
99    /// The minimum allowable quoted price.
100    pub min_price: Option<Price>,
101    /// The registered variable tick scheme name.
102    pub tick_scheme: Option<Ustr>,
103    /// Additional instrument metadata as a JSON-serializable dictionary.
104    pub info: Option<Params>,
105    /// UNIX timestamp (nanoseconds) when the data event occurred.
106    pub ts_event: UnixNanos,
107    /// UNIX timestamp (nanoseconds) when the data object was initialized.
108    pub ts_init: UnixNanos,
109}
110
111#[bon::bon]
112impl CryptoOptionSpread {
113    #[expect(clippy::too_many_arguments)]
114    fn new_checked(
115        instrument_id: InstrumentId,
116        raw_symbol: Symbol,
117        underlying: Currency,
118        quote_currency: Currency,
119        settlement_currency: Currency,
120        is_inverse: bool,
121        strategy_type: Ustr,
122        activation_ns: UnixNanos,
123        expiration_ns: UnixNanos,
124        price_precision: u8,
125        size_precision: u8,
126        price_increment: Price,
127        size_increment: Quantity,
128        multiplier: Option<Quantity>,
129        lot_size: Option<Quantity>,
130        max_quantity: Option<Quantity>,
131        min_quantity: Option<Quantity>,
132        max_notional: Option<Money>,
133        min_notional: Option<Money>,
134        max_price: Option<Price>,
135        min_price: Option<Price>,
136        margin_init: Option<Decimal>,
137        margin_maint: Option<Decimal>,
138        maker_fee: Option<Decimal>,
139        taker_fee: Option<Decimal>,
140        tick_scheme: Option<Ustr>,
141        info: Option<Params>,
142        ts_event: UnixNanos,
143        ts_init: UnixNanos,
144    ) -> CorrectnessResult<Self> {
145        check_valid_string_ascii(strategy_type, stringify!(strategy_type))?;
146        check_equal_u8(
147            price_precision,
148            price_increment.precision,
149            stringify!(price_precision),
150            stringify!(price_increment.precision),
151        )?;
152        check_equal_u8(
153            size_precision,
154            size_increment.precision,
155            stringify!(size_precision),
156            stringify!(size_increment.precision),
157        )?;
158        check_positive_price(price_increment, stringify!(price_increment))?;
159        check_positive_quantity(size_increment, stringify!(size_increment))?;
160        check_tick_scheme(tick_scheme)?;
161
162        if let Some(multiplier) = multiplier {
163            check_positive_quantity(multiplier, stringify!(multiplier))?;
164        }
165
166        if let Some(lot_size) = lot_size {
167            check_positive_quantity(lot_size, stringify!(lot_size))?;
168        }
169
170        Ok(Self {
171            id: instrument_id,
172            raw_symbol,
173            underlying,
174            quote_currency,
175            settlement_currency,
176            is_inverse,
177            strategy_type,
178            activation_ns,
179            expiration_ns,
180            price_precision,
181            size_precision,
182            price_increment,
183            size_increment,
184            multiplier: multiplier.unwrap_or(Quantity::from(1)),
185            lot_size: lot_size.unwrap_or(Quantity::from(1)),
186            margin_init: margin_init.unwrap_or_default(),
187            margin_maint: margin_maint.unwrap_or_default(),
188            maker_fee: maker_fee.unwrap_or_default(),
189            taker_fee: taker_fee.unwrap_or_default(),
190            max_notional,
191            min_notional,
192            max_quantity,
193            min_quantity,
194            max_price,
195            min_price,
196            tick_scheme,
197            info,
198            ts_event,
199            ts_init,
200        })
201    }
202
203    /// Returns a fluent builder for a [`CryptoOptionSpread`] instance.
204    ///
205    /// Required fields are enforced at compile time; optional fields can be omitted and use the
206    /// same defaults as checked construction. The same correctness checks run on `build`.
207    ///
208    /// # Errors
209    ///
210    /// Returns an error if any input validation fails.
211    #[builder(start_fn = builder, finish_fn = build)]
212    pub fn build_checked(
213        instrument_id: InstrumentId,
214        raw_symbol: Symbol,
215        underlying: Currency,
216        quote_currency: Currency,
217        settlement_currency: Currency,
218        is_inverse: bool,
219        strategy_type: Ustr,
220        activation_ns: UnixNanos,
221        expiration_ns: UnixNanos,
222        price_precision: u8,
223        size_precision: u8,
224        price_increment: Price,
225        size_increment: Quantity,
226        multiplier: Option<Quantity>,
227        lot_size: Option<Quantity>,
228        max_quantity: Option<Quantity>,
229        min_quantity: Option<Quantity>,
230        max_notional: Option<Money>,
231        min_notional: Option<Money>,
232        max_price: Option<Price>,
233        min_price: Option<Price>,
234        margin_init: Option<Decimal>,
235        margin_maint: Option<Decimal>,
236        maker_fee: Option<Decimal>,
237        taker_fee: Option<Decimal>,
238        tick_scheme: Option<Ustr>,
239        info: Option<Params>,
240        ts_event: UnixNanos,
241        ts_init: UnixNanos,
242    ) -> CorrectnessResult<Self> {
243        Self::new_checked(
244            instrument_id,
245            raw_symbol,
246            underlying,
247            quote_currency,
248            settlement_currency,
249            is_inverse,
250            strategy_type,
251            activation_ns,
252            expiration_ns,
253            price_precision,
254            size_precision,
255            price_increment,
256            size_increment,
257            multiplier,
258            lot_size,
259            max_quantity,
260            min_quantity,
261            max_notional,
262            min_notional,
263            max_price,
264            min_price,
265            margin_init,
266            margin_maint,
267            maker_fee,
268            taker_fee,
269            tick_scheme,
270            info,
271            ts_event,
272            ts_init,
273        )
274    }
275}
276
277impl PartialEq<Self> for CryptoOptionSpread {
278    fn eq(&self, other: &Self) -> bool {
279        self.id == other.id
280    }
281}
282
283impl Eq for CryptoOptionSpread {}
284
285impl Hash for CryptoOptionSpread {
286    fn hash<H: Hasher>(&self, state: &mut H) {
287        self.id.hash(state);
288    }
289}
290
291impl Instrument for CryptoOptionSpread {
292    fn into_any(self) -> InstrumentAny {
293        InstrumentAny::CryptoOptionSpread(self)
294    }
295
296    fn id(&self) -> InstrumentId {
297        self.id
298    }
299
300    fn raw_symbol(&self) -> Symbol {
301        self.raw_symbol
302    }
303
304    fn asset_class(&self) -> AssetClass {
305        AssetClass::Cryptocurrency
306    }
307
308    fn instrument_class(&self) -> InstrumentClass {
309        InstrumentClass::OptionSpread
310    }
311
312    fn underlying(&self) -> Option<Ustr> {
313        Some(self.underlying.code)
314    }
315
316    fn base_currency(&self) -> Option<Currency> {
317        Some(self.underlying)
318    }
319
320    fn quote_currency(&self) -> Currency {
321        self.quote_currency
322    }
323
324    fn settlement_currency(&self) -> Currency {
325        self.settlement_currency
326    }
327
328    fn is_inverse(&self) -> bool {
329        self.is_inverse
330    }
331
332    fn isin(&self) -> Option<Ustr> {
333        None
334    }
335
336    fn option_kind(&self) -> Option<OptionKind> {
337        None
338    }
339
340    fn strike_price(&self) -> Option<Price> {
341        None
342    }
343
344    fn strategy_type(&self) -> Option<Ustr> {
345        Some(self.strategy_type)
346    }
347
348    fn activation_ns(&self) -> Option<UnixNanos> {
349        Some(self.activation_ns)
350    }
351
352    fn expiration_ns(&self) -> Option<UnixNanos> {
353        Some(self.expiration_ns)
354    }
355
356    fn exchange(&self) -> Option<Ustr> {
357        None
358    }
359
360    fn price_precision(&self) -> u8 {
361        self.price_precision
362    }
363
364    fn size_precision(&self) -> u8 {
365        self.size_precision
366    }
367
368    fn price_increment(&self) -> Price {
369        self.price_increment
370    }
371
372    fn size_increment(&self) -> Quantity {
373        self.size_increment
374    }
375
376    fn multiplier(&self) -> Quantity {
377        self.multiplier
378    }
379
380    fn lot_size(&self) -> Option<Quantity> {
381        Some(self.lot_size)
382    }
383
384    fn max_quantity(&self) -> Option<Quantity> {
385        self.max_quantity
386    }
387
388    fn min_quantity(&self) -> Option<Quantity> {
389        self.min_quantity
390    }
391
392    fn max_notional(&self) -> Option<Money> {
393        self.max_notional
394    }
395
396    fn min_notional(&self) -> Option<Money> {
397        self.min_notional
398    }
399
400    fn max_price(&self) -> Option<Price> {
401        self.max_price
402    }
403
404    fn min_price(&self) -> Option<Price> {
405        self.min_price
406    }
407
408    fn tick_scheme(&self) -> Option<Ustr> {
409        self.tick_scheme
410    }
411
412    fn info(&self) -> Option<&Params> {
413        self.info.as_ref()
414    }
415
416    fn ts_event(&self) -> UnixNanos {
417        self.ts_event
418    }
419
420    fn ts_init(&self) -> UnixNanos {
421        self.ts_init
422    }
423
424    fn margin_init(&self) -> Decimal {
425        self.margin_init
426    }
427
428    fn margin_maint(&self) -> Decimal {
429        self.margin_maint
430    }
431
432    fn maker_fee(&self) -> Decimal {
433        self.maker_fee
434    }
435
436    fn taker_fee(&self) -> Decimal {
437        self.taker_fee
438    }
439}
440
441#[cfg(test)]
442mod tests {
443    use nautilus_core::correctness::CorrectnessResult;
444    use rstest::rstest;
445    use rust_decimal_macros::dec;
446
447    use crate::{
448        enums::{AssetClass, InstrumentClass},
449        identifiers::{InstrumentId, Symbol},
450        instruments::{CryptoOptionSpread, Instrument, stubs::*},
451        types::{Currency, Money, Price, Quantity},
452    };
453
454    #[rstest]
455    fn test_trait_accessors(crypto_option_spread_btc_deribit: CryptoOptionSpread) {
456        assert_eq!(
457            crypto_option_spread_btc_deribit.id(),
458            InstrumentId::from("BTC-CS-19MAY26-70000_75000.DERIBIT")
459        );
460        assert_eq!(
461            crypto_option_spread_btc_deribit.asset_class(),
462            AssetClass::Cryptocurrency
463        );
464        assert_eq!(
465            crypto_option_spread_btc_deribit.instrument_class(),
466            InstrumentClass::OptionSpread
467        );
468        assert_eq!(
469            crypto_option_spread_btc_deribit.quote_currency(),
470            Currency::USD()
471        );
472        assert_eq!(
473            crypto_option_spread_btc_deribit.settlement_currency(),
474            Currency::BTC()
475        );
476        assert!(!crypto_option_spread_btc_deribit.is_inverse());
477        assert_eq!(crypto_option_spread_btc_deribit.price_precision(), 4);
478        assert_eq!(crypto_option_spread_btc_deribit.size_precision(), 1);
479        assert_eq!(
480            crypto_option_spread_btc_deribit.size_increment(),
481            Quantity::from("0.1")
482        );
483        assert!(crypto_option_spread_btc_deribit.activation_ns().is_some());
484        assert!(crypto_option_spread_btc_deribit.expiration_ns().is_some());
485    }
486
487    #[rstest]
488    fn test_new_checked_price_precision_mismatch() {
489        let result = CryptoOptionSpread::new_checked(
490            InstrumentId::from("BTC-CS-TEST.DERIBIT"),
491            Symbol::from("BTC-CS-TEST"),
492            Currency::BTC(),
493            Currency::USD(),
494            Currency::BTC(),
495            false,
496            ustr::Ustr::from("CS"),
497            0.into(),
498            0.into(),
499            4, // mismatch
500            1,
501            Price::from("0.001"),
502            Quantity::from("0.1"),
503            None,
504            None,
505            None,
506            None,
507            None,
508            None,
509            None,
510            None,
511            None,
512            None,
513            None,
514            None,
515            None,
516            None,
517            0.into(),
518            0.into(),
519        );
520        assert!(result.is_err());
521    }
522
523    #[rstest]
524    #[case::zero_multiplier(Some(Quantity::from("0")), None)]
525    #[case::zero_lot_size(None, Some(Quantity::from("0")))]
526    fn test_new_checked_rejects_non_positive_sizing(
527        #[case] multiplier: Option<Quantity>,
528        #[case] lot_size: Option<Quantity>,
529    ) {
530        let result = crypto_option_spread_result(multiplier, lot_size);
531        assert!(result.is_err());
532    }
533
534    #[rstest]
535    fn test_serialization_roundtrip(crypto_option_spread_btc_deribit: CryptoOptionSpread) {
536        let json = serde_json::to_string(&crypto_option_spread_btc_deribit).unwrap();
537        let deserialized: CryptoOptionSpread = serde_json::from_str(&json).unwrap();
538        assert_eq!(json, serde_json::to_string(&deserialized).unwrap());
539    }
540
541    #[rstest]
542    fn test_builder_matches_new_checked() {
543        let positional = CryptoOptionSpread::new_checked(
544            InstrumentId::from("BTC-CS-19MAY26-70000_75000.DERIBIT"),
545            Symbol::from("BTC-CS-19MAY26-70000_75000"),
546            Currency::BTC(),
547            Currency::USDC(),
548            Currency::USDT(),
549            false,
550            ustr::Ustr::from("CS"),
551            1.into(),
552            2.into(),
553            4,
554            1,
555            Price::from("0.0001"),
556            Quantity::from("0.1"),
557            Some(Quantity::from("10")),
558            Some(Quantity::from("5")),
559            Some(Quantity::from("1000.0")),
560            Some(Quantity::from("0.1")),
561            Some(Money::new(1_000_000.0, Currency::USDC())),
562            Some(Money::new(10.0, Currency::USDC())),
563            Some(Price::from("9.9999")),
564            Some(Price::from("0.0001")),
565            Some(dec!(0.01)),
566            Some(dec!(0.02)),
567            Some(dec!(0.0002)),
568            Some(dec!(0.0004)),
569            None,
570            None,
571            1.into(),
572            2.into(),
573        )
574        .unwrap();
575
576        let built = CryptoOptionSpread::builder()
577            .instrument_id(InstrumentId::from("BTC-CS-19MAY26-70000_75000.DERIBIT"))
578            .raw_symbol(Symbol::from("BTC-CS-19MAY26-70000_75000"))
579            .underlying(Currency::BTC())
580            .quote_currency(Currency::USDC())
581            .settlement_currency(Currency::USDT())
582            .is_inverse(false)
583            .strategy_type(ustr::Ustr::from("CS"))
584            .activation_ns(1.into())
585            .expiration_ns(2.into())
586            .price_precision(4)
587            .size_precision(1)
588            .price_increment(Price::from("0.0001"))
589            .size_increment(Quantity::from("0.1"))
590            .multiplier(Quantity::from("10"))
591            .lot_size(Quantity::from("5"))
592            .max_quantity(Quantity::from("1000.0"))
593            .min_quantity(Quantity::from("0.1"))
594            .max_notional(Money::new(1_000_000.0, Currency::USDC()))
595            .min_notional(Money::new(10.0, Currency::USDC()))
596            .max_price(Price::from("9.9999"))
597            .min_price(Price::from("0.0001"))
598            .margin_init(dec!(0.01))
599            .margin_maint(dec!(0.02))
600            .maker_fee(dec!(0.0002))
601            .taker_fee(dec!(0.0004))
602            .ts_event(1.into())
603            .ts_init(2.into())
604            .build()
605            .unwrap();
606
607        assert_eq!(
608            serde_json::to_value(&positional).unwrap(),
609            serde_json::to_value(&built).unwrap(),
610        );
611    }
612
613    fn crypto_option_spread_result(
614        multiplier: Option<Quantity>,
615        lot_size: Option<Quantity>,
616    ) -> CorrectnessResult<CryptoOptionSpread> {
617        CryptoOptionSpread::new_checked(
618            InstrumentId::from("BTC-CS-TEST.DERIBIT"),
619            Symbol::from("BTC-CS-TEST"),
620            Currency::BTC(),
621            Currency::USD(),
622            Currency::BTC(),
623            false,
624            ustr::Ustr::from("CS"),
625            0.into(),
626            0.into(),
627            4,
628            1,
629            Price::from("0.0001"),
630            Quantity::from("0.1"),
631            multiplier,
632            lot_size,
633            None,
634            None,
635            None,
636            None,
637            None,
638            None,
639            None,
640            None,
641            None,
642            None,
643            None,
644            None,
645            0.into(),
646            0.into(),
647        )
648    }
649}
nautilus_model/instruments/crypto_option_spread.rs

nautilus_model/instruments/
crypto_option_spread.rs
