Skip to main content

nautilus_databento/decode/
instruments.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 ahash::AHashMap;
17use databento::dbn;
18use nautilus_core::UnixNanos;
19use nautilus_model::{
20    enums::{AssetClass, ExerciseStyle, SettlementType},
21    identifiers::{
22        InstrumentId, Symbol,
23        futures::{FuturesYearDigits, parse_futures_symbol},
24    },
25    instruments::{
26        CurrencyPair, Equity, FuturesContract, FuturesSpread, InstrumentAny, OptionContract,
27        OptionSpread,
28    },
29    types::{Currency, Quantity},
30};
31use ustr::Ustr;
32
33use super::{
34    expiration::{DatabentoDecodeConfig, corrected_option_expiration},
35    primitives::{
36        decode_lot_size, decode_multiplier, decode_optional_timestamp, decode_price,
37        decode_price_increment, decode_timestamp, decode_underlying, parse_cfi_iso10926,
38        parse_cfi_option_terms, parse_currency_or_usd_default, parse_option_kind,
39        precision_from_raw,
40    },
41};
42use crate::symbology::resolve_futures_instrument_id;
43
44/// # Errors
45///
46/// Returns an error if decoding the `InstrumentDefMsg` fails.
47///
48/// Returns `Ok(None)` for instrument classes with no Nautilus equivalent (`'I'` Index,
49/// `'B'` Bond, or any future class) and FX spots that cannot be mapped to known currencies.
50pub fn decode_instrument_def_msg(
51    msg: &dbn::InstrumentDefMsg,
52    instrument_id: InstrumentId,
53    ts_init: Option<UnixNanos>,
54    decode_config: Option<&DatabentoDecodeConfig>,
55) -> anyhow::Result<Option<InstrumentAny>> {
56    match msg.instrument_class as u8 as char {
57        'K' => Ok(Some(InstrumentAny::Equity(decode_equity(
58            msg,
59            instrument_id,
60            ts_init,
61        )?))),
62        'X' => {
63            Ok(decode_currency_pair(msg, instrument_id, ts_init)?.map(InstrumentAny::CurrencyPair))
64        }
65        'F' => Ok(Some(InstrumentAny::FuturesContract(
66            decode_futures_contract(msg, instrument_id, ts_init)?,
67        ))),
68        'S' => Ok(Some(InstrumentAny::FuturesSpread(decode_futures_spread(
69            msg,
70            instrument_id,
71            ts_init,
72        )?))),
73        'C' | 'P' => Ok(Some(InstrumentAny::OptionContract(decode_option_contract(
74            msg,
75            instrument_id,
76            ts_init,
77            decode_config,
78        )?))),
79        'T' | 'M' => Ok(Some(InstrumentAny::OptionSpread(decode_option_spread(
80            msg,
81            instrument_id,
82            ts_init,
83            decode_config,
84        )?))),
85        other => {
86            let label = match other {
87                'I' => "'I' (Index)".to_string(),
88                'B' => "'B' (Bond)".to_string(),
89                _ => format!("'{other}'"),
90            };
91            log::warn!("Skipping unsupported `instrument_class` {label} for {instrument_id}",);
92            Ok(None)
93        }
94    }
95}
96
97fn decode_currency_pair(
98    msg: &dbn::InstrumentDefMsg,
99    instrument_id: InstrumentId,
100    ts_init: Option<UnixNanos>,
101) -> anyhow::Result<Option<CurrencyPair>> {
102    let raw_symbol_str = msg.raw_symbol()?;
103    let raw_symbol = Symbol::from(raw_symbol_str);
104    let Some((base_currency, quote_currency)) = parse_fx_pair(
105        raw_symbol_str,
106        msg.asset().unwrap_or_default(),
107        msg.currency().unwrap_or_default(),
108    ) else {
109        log::warn!(
110            "Skipping FX spot {instrument_id}: could not parse currencies from raw_symbol='{raw_symbol_str}'"
111        );
112        return Ok(None);
113    };
114    let price_increment = decode_price_increment(msg.min_price_increment, quote_currency.precision);
115    let size_increment = decode_lot_size(msg.min_lot_size_round_lot);
116    let multiplier = decode_multiplier(msg.unit_of_measure_qty)?;
117    let lot_size = decode_lot_size(msg.min_lot_size_round_lot);
118    let ts_event = UnixNanos::from(msg.ts_recv);
119    let ts_init = ts_init.unwrap_or(ts_event);
120
121    Ok(Some(
122        CurrencyPair::builder()
123            .instrument_id(instrument_id)
124            .raw_symbol(raw_symbol)
125            .base_currency(base_currency)
126            .quote_currency(quote_currency)
127            .price_precision(price_increment.precision)
128            .size_precision(size_increment.precision)
129            .price_increment(price_increment)
130            .size_increment(size_increment)
131            .multiplier(multiplier)
132            .lot_size(lot_size)
133            .ts_event(ts_event)
134            .ts_init(ts_init)
135            .build()?,
136    ))
137}
138
139fn parse_fx_pair(raw_symbol: &str, asset: &str, currency: &str) -> Option<(Currency, Currency)> {
140    parse_fx_pair_from_symbol(raw_symbol)
141        .or_else(|| parse_fx_pair_from_symbol(asset))
142        .or_else(|| parse_fx_pair_from_asset_currency(asset, currency))
143}
144
145fn parse_fx_pair_from_symbol(value: &str) -> Option<(Currency, Currency)> {
146    let normalized = value
147        .chars()
148        .filter(|ch| ch.is_ascii_alphabetic())
149        .collect::<String>()
150        .to_ascii_uppercase();
151
152    if normalized.len() != 6 {
153        return None;
154    }
155
156    let base = Currency::try_from_str(&normalized[..3])?;
157    let quote = Currency::try_from_str(&normalized[3..])?;
158    Some((base, quote))
159}
160
161fn parse_fx_pair_from_asset_currency(asset: &str, currency: &str) -> Option<(Currency, Currency)> {
162    let base = Currency::try_from_str(asset.trim().to_ascii_uppercase().as_str())?;
163    let quote = Currency::try_from_str(currency.trim().to_ascii_uppercase().as_str())?;
164    Some((base, quote))
165}
166
167/// Decodes a Databento instrument definition message into an `Equity` instrument.
168///
169/// # Errors
170///
171/// Returns an error if parsing or constructing `Equity` fails.
172///
173/// # Panics
174///
175/// Panics if the constructed instrument fails validation.
176pub fn decode_equity(
177    msg: &dbn::InstrumentDefMsg,
178    instrument_id: InstrumentId,
179    ts_init: Option<UnixNanos>,
180) -> anyhow::Result<Equity> {
181    let raw_symbol = Symbol::new_checked(msg.raw_symbol()?)?;
182    let currency = parse_currency_or_usd_default(msg.currency());
183    let price_increment = decode_price_increment(msg.min_price_increment, currency.precision);
184    let lot_size = decode_lot_size(msg.min_lot_size_round_lot);
185    let ts_event = UnixNanos::from(msg.ts_recv); // More accurate and reliable timestamp
186    let ts_init = ts_init.unwrap_or(ts_event);
187
188    Ok(Equity::builder()
189        .instrument_id(instrument_id)
190        .raw_symbol(raw_symbol)
191        // No ISIN available yet
192        .currency(currency)
193        .price_precision(price_increment.precision)
194        .price_increment(price_increment)
195        .lot_size(lot_size)
196        .ts_event(ts_event)
197        .ts_init(ts_init)
198        .build()
199        .unwrap())
200}
201
202/// Decodes a Databento instrument definition message into a `FuturesContract` instrument.
203///
204/// # Errors
205///
206/// Returns an error if parsing or constructing `FuturesContract` fails.
207pub fn decode_futures_contract(
208    msg: &dbn::InstrumentDefMsg,
209    instrument_id: InstrumentId,
210    ts_init: Option<UnixNanos>,
211) -> anyhow::Result<FuturesContract> {
212    let raw_symbol = Symbol::new_checked(msg.raw_symbol()?)?;
213    let currency = parse_currency_or_usd_default(msg.currency());
214    let exchange = Ustr::from(msg.exchange()?);
215    let underlying = decode_underlying(msg.asset()?, &instrument_id.symbol);
216    let (asset_class, _) = parse_cfi_iso10926(msg.cfi()?);
217    let price_increment = decode_price_increment(msg.min_price_increment, currency.precision);
218    let multiplier = decode_multiplier(msg.unit_of_measure_qty)?;
219    let lot_size = decode_lot_size(msg.min_lot_size_round_lot);
220    let ts_event = UnixNanos::from(msg.ts_recv); // More accurate and reliable timestamp
221    let ts_init = ts_init.unwrap_or(ts_event);
222
223    Ok(FuturesContract::builder()
224        .instrument_id(instrument_id)
225        .raw_symbol(raw_symbol)
226        .asset_class(asset_class.unwrap_or(AssetClass::Commodity))
227        .exchange(exchange)
228        .underlying(underlying)
229        .activation_ns(decode_optional_timestamp(msg.activation).unwrap_or_default())
230        .expiration_ns(decode_timestamp(msg.expiration, "expiration")?)
231        .currency(currency)
232        .price_precision(price_increment.precision)
233        .price_increment(price_increment)
234        .multiplier(multiplier)
235        .lot_size(lot_size)
236        .ts_event(ts_event)
237        .ts_init(ts_init)
238        .build()?)
239}
240
241/// Decodes a Databento instrument definition message into a `FuturesSpread` instrument.
242///
243/// # Errors
244///
245/// Returns an error if parsing or constructing `FuturesSpread` fails.
246pub fn decode_futures_spread(
247    msg: &dbn::InstrumentDefMsg,
248    instrument_id: InstrumentId,
249    ts_init: Option<UnixNanos>,
250) -> anyhow::Result<FuturesSpread> {
251    let raw_symbol = Symbol::new_checked(msg.raw_symbol()?)?;
252    let exchange = Ustr::from(msg.exchange()?);
253    let underlying = decode_underlying(msg.asset()?, &instrument_id.symbol);
254    let (asset_class, _) = parse_cfi_iso10926(msg.cfi()?);
255    let strategy_type = Ustr::from(msg.secsubtype()?);
256    let currency = parse_currency_or_usd_default(msg.currency());
257    let price_increment = decode_price_increment(msg.min_price_increment, currency.precision);
258    let multiplier = decode_multiplier(msg.unit_of_measure_qty)?;
259    let lot_size = decode_lot_size(msg.min_lot_size_round_lot);
260    let ts_event = UnixNanos::from(msg.ts_recv); // More accurate and reliable timestamp
261    let ts_init = ts_init.unwrap_or(ts_event);
262
263    Ok(FuturesSpread::builder()
264        .instrument_id(instrument_id)
265        .raw_symbol(raw_symbol)
266        .asset_class(asset_class.unwrap_or(AssetClass::Commodity))
267        .exchange(exchange)
268        .underlying(underlying)
269        .strategy_type(strategy_type)
270        .activation_ns(decode_optional_timestamp(msg.activation).unwrap_or_default())
271        .expiration_ns(decode_timestamp(msg.expiration, "expiration")?)
272        .currency(currency)
273        .price_precision(price_increment.precision)
274        .price_increment(price_increment)
275        .multiplier(multiplier)
276        .lot_size(lot_size)
277        .ts_event(ts_event)
278        .ts_init(ts_init)
279        .build()?)
280}
281
282/// Decodes a Databento instrument definition message into an `OptionContract` instrument.
283///
284/// Strike precision preserves every wire digit, with a floor at the strike currency's precision.
285/// Exercise style and settlement type come from the CFI code. OPRA definitions carry no CFI code,
286/// so they use fixed rules by option root.
287///
288/// # Errors
289///
290/// Returns an error if parsing or constructing `OptionContract` fails.
291pub fn decode_option_contract(
292    msg: &dbn::InstrumentDefMsg,
293    instrument_id: InstrumentId,
294    ts_init: Option<UnixNanos>,
295    decode_config: Option<&DatabentoDecodeConfig>,
296) -> anyhow::Result<OptionContract> {
297    let raw_symbol = Symbol::new_checked(msg.raw_symbol()?)?;
298    let currency = parse_currency_or_usd_default(msg.currency());
299    let strike_price_currency = parse_currency_or_usd_default(msg.strike_price_currency());
300    let exchange = Ustr::from(msg.exchange()?);
301    let mut underlying = decode_underlying(msg.underlying()?, &instrument_id.symbol);
302    if instrument_id
303        .symbol
304        .as_str()
305        .split_once(' ')
306        .and_then(|(code, _)| parse_futures_symbol(code))
307        .is_some_and(|parsed| parsed.year_digits.len() == 2)
308    {
309        let underlying_id =
310            InstrumentId::new(Symbol::from(underlying.as_str()), instrument_id.venue);
311        let underlying_id = resolve_futures_instrument_id(
312            &dbn::RecordRef::from(msg),
313            underlying_id,
314            FuturesYearDigits::Two,
315            &AHashMap::new(),
316            None,
317        )?;
318        underlying = Ustr::from(underlying_id.symbol.as_str());
319    }
320
321    let asset_class_opt = if instrument_id.venue.as_str() == "OPRA" {
322        Some(AssetClass::Equity)
323    } else {
324        let (asset_class, _) = parse_cfi_iso10926(msg.cfi()?);
325        asset_class
326    };
327    let option_kind = parse_option_kind(msg.instrument_class)?;
328    let strike_precision =
329        precision_from_raw(msg.strike_price).max(strike_price_currency.precision);
330    let strike_price = decode_price(msg.strike_price, strike_precision, "strike_price")
331        .map_err(|e| anyhow::anyhow!("{instrument_id}: {e}"))?;
332    let dataset = msg.hd.publisher().ok().map(|p| p.dataset());
333    let (exercise_style, settlement_type) = match parse_cfi_option_terms(msg.cfi()?) {
334        (None, None) if dataset == Some(dbn::Dataset::OpraPillar) => {
335            opra_option_terms(underlying.as_str()).unzip()
336        }
337        terms => terms,
338    };
339
340    let price_increment = decode_price_increment(msg.min_price_increment, currency.precision);
341    let multiplier =
342        decode_option_multiplier(dataset, msg.contract_multiplier, msg.unit_of_measure_qty)?;
343    let lot_size = decode_lot_size(msg.min_lot_size_round_lot);
344    let expiration = corrected_option_expiration(
345        decode_timestamp(msg.expiration, "expiration")?,
346        underlying,
347        dataset,
348        decode_config,
349    );
350    let ts_event = UnixNanos::from(msg.ts_recv); // More accurate and reliable timestamp
351    let ts_init = ts_init.unwrap_or(ts_event);
352
353    Ok(OptionContract::builder()
354        .instrument_id(instrument_id)
355        .raw_symbol(raw_symbol)
356        .asset_class(asset_class_opt.unwrap_or(AssetClass::Commodity))
357        .exchange(exchange)
358        .underlying(underlying)
359        .option_kind(option_kind)
360        .strike_price(strike_price)
361        .currency(currency)
362        .activation_ns(decode_optional_timestamp(msg.activation).unwrap_or_default())
363        .expiration_ns(expiration)
364        .price_precision(price_increment.precision)
365        .price_increment(price_increment)
366        .multiplier(multiplier)
367        .lot_size(lot_size)
368        .maybe_exercise_style(exercise_style)
369        .maybe_settlement_type(settlement_type)
370        .ts_event(ts_event)
371        .ts_init(ts_init)
372        .build()?)
373}
374
375// OPRA cash-settled option roots (index, currency, and index binary options), European-style
376const OPRA_ROOTS_CASH_EUROPEAN: &[&str] = &[
377    "BKX", "BKXPM", "CBTX", "CBTXW", "DJX", "DJXW", "HGX", "MBTX", "MBTXW", "MGTN", "MGTNW",
378    "MRTBW", "MRUT", "MXACW", "MXEA", "MXEF", "MXUSA", "MXWLD", "NANOS", "NDX", "NDXB", "NDXP",
379    "OSX", "OSXPM", "RLV", "RUI", "RUT", "RUTW", "SIXB", "SIXI", "SIXM", "SIXRE", "SIXU", "SIXV",
380    "SPEQW", "SPEQX", "SPESG", "SPX", "SPXO", "SPXW", "UTY", "VIX", "VIXW", "XDA", "XDB", "XDC",
381    "XDE", "XDN", "XDS", "XDZ", "XEO", "XND", "XSP", "XSPBW",
382];
383
384// OPRA cash-settled index option roots, American-style
385const OPRA_ROOTS_CASH_AMERICAN: &[&str] = &["OEX", "XAU"];
386
387// OPRA definitions carry no CFI code: roots outside the cash-settled lists take the US equity and
388// ETF option convention, except root shapes that the record cannot tell apart from other products
389fn opra_option_terms(root: &str) -> Option<(ExerciseStyle, SettlementType)> {
390    if OPRA_ROOTS_CASH_EUROPEAN.contains(&root) {
391        Some((ExerciseStyle::European, SettlementType::Cash))
392    } else if OPRA_ROOTS_CASH_AMERICAN.contains(&root) {
393        Some((ExerciseStyle::American, SettlementType::Cash))
394    } else if is_opra_root_ambiguous(root) {
395        None
396    } else {
397        Some((ExerciseStyle::American, SettlementType::Physical))
398    }
399}
400
401// Cboe metric binaries use five-letter `K` roots (`KAAPL`), a shape some equities share, and
402// roots with a digit before a letter (`B1SPY`) belong to no identified product
403fn is_opra_root_ambiguous(root: &str) -> bool {
404    let root = root.as_bytes();
405    let has_metric_binary_shape =
406        root.len() == 5 && root[0] == b'K' && root.iter().all(u8::is_ascii_uppercase);
407    let has_digit_before_letter = root
408        .windows(2)
409        .any(|pair| pair[0].is_ascii_digit() && pair[1].is_ascii_alphabetic());
410
411    has_metric_binary_shape || has_digit_before_letter
412}
413
414fn decode_option_multiplier(
415    dataset: Option<dbn::Dataset>,
416    contract_multiplier: i32,
417    unit_of_measure_qty: i64,
418) -> anyhow::Result<Quantity> {
419    match (dataset, contract_multiplier, unit_of_measure_qty) {
420        // OPRA definitions can leave both fields unset: use the standard OCC contract size
421        (Some(dbn::Dataset::OpraPillar), 0 | i32::MAX, 0 | i64::MAX) => {
422            Ok(Quantity::from_mantissa_exponent(100, 0, 0))
423        }
424        (Some(dbn::Dataset::OpraPillar), 0 | i32::MAX, _) => decode_multiplier(unit_of_measure_qty),
425        (Some(dbn::Dataset::OpraPillar), value, _) if value < 0 => {
426            anyhow::bail!("Invalid negative `contract_multiplier`: {value}")
427        }
428        (Some(dbn::Dataset::OpraPillar), value, _) => {
429            Ok(Quantity::from_mantissa_exponent(value as u64, 0, 0))
430        }
431        _ => decode_multiplier(unit_of_measure_qty),
432    }
433}
434
435/// Decodes a Databento instrument definition message into an `OptionSpread` instrument.
436///
437/// # Errors
438///
439/// Returns an error if parsing or constructing `OptionSpread` fails.
440pub fn decode_option_spread(
441    msg: &dbn::InstrumentDefMsg,
442    instrument_id: InstrumentId,
443    ts_init: Option<UnixNanos>,
444    decode_config: Option<&DatabentoDecodeConfig>,
445) -> anyhow::Result<OptionSpread> {
446    let exchange = Ustr::from(msg.exchange()?);
447    let underlying = decode_underlying(msg.underlying()?, &instrument_id.symbol);
448    let asset_class_opt = if instrument_id.venue.as_str() == "OPRA" {
449        Some(AssetClass::Equity)
450    } else {
451        let (asset_class, _) = parse_cfi_iso10926(msg.cfi()?);
452        asset_class
453    };
454    let strategy_type = Ustr::from(msg.secsubtype()?);
455    let currency = parse_currency_or_usd_default(msg.currency());
456    let price_increment = decode_price_increment(msg.min_price_increment, currency.precision);
457    let multiplier = decode_multiplier(msg.unit_of_measure_qty)?;
458    let lot_size = decode_lot_size(msg.min_lot_size_round_lot);
459    let expiration = corrected_option_expiration(
460        decode_timestamp(msg.expiration, "expiration")?,
461        underlying,
462        msg.hd.publisher().ok().map(|p| p.dataset()),
463        decode_config,
464    );
465    let ts_event = msg.ts_recv.into(); // More accurate and reliable timestamp
466    let ts_init = ts_init.unwrap_or(ts_event);
467
468    Ok(OptionSpread::builder()
469        .instrument_id(instrument_id)
470        .raw_symbol(instrument_id.symbol)
471        .asset_class(asset_class_opt.unwrap_or(AssetClass::Commodity))
472        .exchange(exchange)
473        .underlying(underlying)
474        .strategy_type(strategy_type)
475        .activation_ns(decode_optional_timestamp(msg.activation).unwrap_or_default())
476        .expiration_ns(expiration)
477        .currency(currency)
478        .price_precision(price_increment.precision)
479        .price_increment(price_increment)
480        .multiplier(multiplier)
481        .lot_size(lot_size)
482        .ts_event(ts_event)
483        .ts_init(ts_init)
484        .build()?)
485}