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,
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_currency_or_usd_default, parse_option_kind, precision_from_raw,
39    },
40};
41use crate::symbology::resolve_futures_instrument_id;
42
43/// # Errors
44///
45/// Returns an error if decoding the `InstrumentDefMsg` fails.
46///
47/// Returns `Ok(None)` for instrument classes with no Nautilus equivalent (`'I'` Index,
48/// `'B'` Bond, or any future class) and FX spots that cannot be mapped to known currencies.
49pub fn decode_instrument_def_msg(
50    msg: &dbn::InstrumentDefMsg,
51    instrument_id: InstrumentId,
52    ts_init: Option<UnixNanos>,
53    decode_config: Option<&DatabentoDecodeConfig>,
54) -> anyhow::Result<Option<InstrumentAny>> {
55    match msg.instrument_class as u8 as char {
56        'K' => Ok(Some(InstrumentAny::Equity(decode_equity(
57            msg,
58            instrument_id,
59            ts_init,
60        )?))),
61        'X' => {
62            Ok(decode_currency_pair(msg, instrument_id, ts_init)?.map(InstrumentAny::CurrencyPair))
63        }
64        'F' => Ok(Some(InstrumentAny::FuturesContract(
65            decode_futures_contract(msg, instrument_id, ts_init)?,
66        ))),
67        'S' => Ok(Some(InstrumentAny::FuturesSpread(decode_futures_spread(
68            msg,
69            instrument_id,
70            ts_init,
71        )?))),
72        'C' | 'P' => Ok(Some(InstrumentAny::OptionContract(decode_option_contract(
73            msg,
74            instrument_id,
75            ts_init,
76            decode_config,
77        )?))),
78        'T' | 'M' => Ok(Some(InstrumentAny::OptionSpread(decode_option_spread(
79            msg,
80            instrument_id,
81            ts_init,
82            decode_config,
83        )?))),
84        other => {
85            let label = match other {
86                'I' => "'I' (Index)".to_string(),
87                'B' => "'B' (Bond)".to_string(),
88                _ => format!("'{other}'"),
89            };
90            log::warn!("Skipping unsupported `instrument_class` {label} for {instrument_id}",);
91            Ok(None)
92        }
93    }
94}
95
96fn decode_currency_pair(
97    msg: &dbn::InstrumentDefMsg,
98    instrument_id: InstrumentId,
99    ts_init: Option<UnixNanos>,
100) -> anyhow::Result<Option<CurrencyPair>> {
101    let raw_symbol_str = msg.raw_symbol()?;
102    let raw_symbol = Symbol::from(raw_symbol_str);
103    let Some((base_currency, quote_currency)) = parse_fx_pair(
104        raw_symbol_str,
105        msg.asset().unwrap_or_default(),
106        msg.currency().unwrap_or_default(),
107    ) else {
108        log::warn!(
109            "Skipping FX spot {instrument_id}: could not parse currencies from raw_symbol='{raw_symbol_str}'"
110        );
111        return Ok(None);
112    };
113    let price_increment = decode_price_increment(msg.min_price_increment, quote_currency.precision);
114    let size_increment = decode_lot_size(msg.min_lot_size_round_lot);
115    let multiplier = decode_multiplier(msg.unit_of_measure_qty)?;
116    let lot_size = decode_lot_size(msg.min_lot_size_round_lot);
117    let ts_event = UnixNanos::from(msg.ts_recv);
118    let ts_init = ts_init.unwrap_or(ts_event);
119
120    Ok(Some(
121        CurrencyPair::builder()
122            .instrument_id(instrument_id)
123            .raw_symbol(raw_symbol)
124            .base_currency(base_currency)
125            .quote_currency(quote_currency)
126            .price_precision(price_increment.precision)
127            .size_precision(size_increment.precision)
128            .price_increment(price_increment)
129            .size_increment(size_increment)
130            .multiplier(multiplier)
131            .lot_size(lot_size)
132            .ts_event(ts_event)
133            .ts_init(ts_init)
134            .build()?,
135    ))
136}
137
138fn parse_fx_pair(raw_symbol: &str, asset: &str, currency: &str) -> Option<(Currency, Currency)> {
139    parse_fx_pair_from_symbol(raw_symbol)
140        .or_else(|| parse_fx_pair_from_symbol(asset))
141        .or_else(|| parse_fx_pair_from_asset_currency(asset, currency))
142}
143
144fn parse_fx_pair_from_symbol(value: &str) -> Option<(Currency, Currency)> {
145    let normalized = value
146        .chars()
147        .filter(|ch| ch.is_ascii_alphabetic())
148        .collect::<String>()
149        .to_ascii_uppercase();
150
151    if normalized.len() != 6 {
152        return None;
153    }
154
155    let base = Currency::try_from_str(&normalized[..3])?;
156    let quote = Currency::try_from_str(&normalized[3..])?;
157    Some((base, quote))
158}
159
160fn parse_fx_pair_from_asset_currency(asset: &str, currency: &str) -> Option<(Currency, Currency)> {
161    let base = Currency::try_from_str(asset.trim().to_ascii_uppercase().as_str())?;
162    let quote = Currency::try_from_str(currency.trim().to_ascii_uppercase().as_str())?;
163    Some((base, quote))
164}
165
166/// Decodes a Databento instrument definition message into an `Equity` instrument.
167///
168/// # Errors
169///
170/// Returns an error if parsing or constructing `Equity` fails.
171///
172/// # Panics
173///
174/// Panics if the constructed instrument fails validation.
175pub fn decode_equity(
176    msg: &dbn::InstrumentDefMsg,
177    instrument_id: InstrumentId,
178    ts_init: Option<UnixNanos>,
179) -> anyhow::Result<Equity> {
180    let currency = parse_currency_or_usd_default(msg.currency());
181    let price_increment = decode_price_increment(msg.min_price_increment, currency.precision);
182    let lot_size = decode_lot_size(msg.min_lot_size_round_lot);
183    let ts_event = UnixNanos::from(msg.ts_recv); // More accurate and reliable timestamp
184    let ts_init = ts_init.unwrap_or(ts_event);
185
186    Ok(Equity::builder()
187        .instrument_id(instrument_id)
188        .raw_symbol(instrument_id.symbol)
189        // No ISIN available yet
190        .currency(currency)
191        .price_precision(price_increment.precision)
192        .price_increment(price_increment)
193        .lot_size(lot_size)
194        .ts_event(ts_event)
195        .ts_init(ts_init)
196        .build()
197        .unwrap())
198}
199
200/// Decodes a Databento instrument definition message into a `FuturesContract` instrument.
201///
202/// # Errors
203///
204/// Returns an error if parsing or constructing `FuturesContract` fails.
205pub fn decode_futures_contract(
206    msg: &dbn::InstrumentDefMsg,
207    instrument_id: InstrumentId,
208    ts_init: Option<UnixNanos>,
209) -> anyhow::Result<FuturesContract> {
210    let raw_symbol = Symbol::new_checked(msg.raw_symbol()?)?;
211    let currency = parse_currency_or_usd_default(msg.currency());
212    let exchange = Ustr::from(msg.exchange()?);
213    let underlying = decode_underlying(msg.asset()?, &instrument_id.symbol);
214    let (asset_class, _) = parse_cfi_iso10926(msg.cfi()?);
215    let price_increment = decode_price_increment(msg.min_price_increment, currency.precision);
216    let multiplier = decode_multiplier(msg.unit_of_measure_qty)?;
217    let lot_size = decode_lot_size(msg.min_lot_size_round_lot);
218    let ts_event = UnixNanos::from(msg.ts_recv); // More accurate and reliable timestamp
219    let ts_init = ts_init.unwrap_or(ts_event);
220
221    Ok(FuturesContract::builder()
222        .instrument_id(instrument_id)
223        .raw_symbol(raw_symbol)
224        .asset_class(asset_class.unwrap_or(AssetClass::Commodity))
225        .exchange(exchange)
226        .underlying(underlying)
227        .activation_ns(decode_optional_timestamp(msg.activation).unwrap_or_default())
228        .expiration_ns(decode_timestamp(msg.expiration, "expiration")?)
229        .currency(currency)
230        .price_precision(price_increment.precision)
231        .price_increment(price_increment)
232        .multiplier(multiplier)
233        .lot_size(lot_size)
234        .ts_event(ts_event)
235        .ts_init(ts_init)
236        .build()?)
237}
238
239/// Decodes a Databento instrument definition message into a `FuturesSpread` instrument.
240///
241/// # Errors
242///
243/// Returns an error if parsing or constructing `FuturesSpread` fails.
244pub fn decode_futures_spread(
245    msg: &dbn::InstrumentDefMsg,
246    instrument_id: InstrumentId,
247    ts_init: Option<UnixNanos>,
248) -> anyhow::Result<FuturesSpread> {
249    let raw_symbol = Symbol::new_checked(msg.raw_symbol()?)?;
250    let exchange = Ustr::from(msg.exchange()?);
251    let underlying = decode_underlying(msg.asset()?, &instrument_id.symbol);
252    let (asset_class, _) = parse_cfi_iso10926(msg.cfi()?);
253    let strategy_type = Ustr::from(msg.secsubtype()?);
254    let currency = parse_currency_or_usd_default(msg.currency());
255    let price_increment = decode_price_increment(msg.min_price_increment, currency.precision);
256    let multiplier = decode_multiplier(msg.unit_of_measure_qty)?;
257    let lot_size = decode_lot_size(msg.min_lot_size_round_lot);
258    let ts_event = UnixNanos::from(msg.ts_recv); // More accurate and reliable timestamp
259    let ts_init = ts_init.unwrap_or(ts_event);
260
261    Ok(FuturesSpread::builder()
262        .instrument_id(instrument_id)
263        .raw_symbol(raw_symbol)
264        .asset_class(asset_class.unwrap_or(AssetClass::Commodity))
265        .exchange(exchange)
266        .underlying(underlying)
267        .strategy_type(strategy_type)
268        .activation_ns(decode_optional_timestamp(msg.activation).unwrap_or_default())
269        .expiration_ns(decode_timestamp(msg.expiration, "expiration")?)
270        .currency(currency)
271        .price_precision(price_increment.precision)
272        .price_increment(price_increment)
273        .multiplier(multiplier)
274        .lot_size(lot_size)
275        .ts_event(ts_event)
276        .ts_init(ts_init)
277        .build()?)
278}
279
280/// Decodes a Databento instrument definition message into an `OptionContract` instrument.
281///
282/// Strike precision preserves every wire digit, with a floor at the strike currency's precision.
283///
284/// # Errors
285///
286/// Returns an error if parsing or constructing `OptionContract` fails.
287pub fn decode_option_contract(
288    msg: &dbn::InstrumentDefMsg,
289    instrument_id: InstrumentId,
290    ts_init: Option<UnixNanos>,
291    decode_config: Option<&DatabentoDecodeConfig>,
292) -> anyhow::Result<OptionContract> {
293    let raw_symbol = Symbol::new_checked(msg.raw_symbol()?)?;
294    let currency = parse_currency_or_usd_default(msg.currency());
295    let strike_price_currency = parse_currency_or_usd_default(msg.strike_price_currency());
296    let exchange = Ustr::from(msg.exchange()?);
297    let mut underlying = decode_underlying(msg.underlying()?, &instrument_id.symbol);
298    if instrument_id
299        .symbol
300        .as_str()
301        .split_once(' ')
302        .and_then(|(code, _)| parse_futures_symbol(code))
303        .is_some_and(|parsed| parsed.year_digits.len() == 2)
304    {
305        let underlying_id =
306            InstrumentId::new(Symbol::from(underlying.as_str()), instrument_id.venue);
307        let underlying_id = resolve_futures_instrument_id(
308            &dbn::RecordRef::from(msg),
309            underlying_id,
310            FuturesYearDigits::Two,
311            &AHashMap::new(),
312            None,
313        )?;
314        underlying = Ustr::from(underlying_id.symbol.as_str());
315    }
316
317    let asset_class_opt = if instrument_id.venue.as_str() == "OPRA" {
318        Some(AssetClass::Equity)
319    } else {
320        let (asset_class, _) = parse_cfi_iso10926(msg.cfi()?);
321        asset_class
322    };
323    let option_kind = parse_option_kind(msg.instrument_class)?;
324    let strike_precision =
325        precision_from_raw(msg.strike_price).max(strike_price_currency.precision);
326    let strike_price = decode_price(msg.strike_price, strike_precision, "strike_price")
327        .map_err(|e| anyhow::anyhow!("{instrument_id}: {e}"))?;
328    let dataset = msg.hd.publisher().ok().map(|p| p.dataset());
329    let price_increment = decode_price_increment(msg.min_price_increment, currency.precision);
330    let multiplier =
331        decode_option_multiplier(dataset, msg.contract_multiplier, msg.unit_of_measure_qty)?;
332    let lot_size = decode_lot_size(msg.min_lot_size_round_lot);
333    let expiration = corrected_option_expiration(
334        decode_timestamp(msg.expiration, "expiration")?,
335        underlying,
336        dataset,
337        decode_config,
338    );
339    let ts_event = UnixNanos::from(msg.ts_recv); // More accurate and reliable timestamp
340    let ts_init = ts_init.unwrap_or(ts_event);
341
342    Ok(OptionContract::builder()
343        .instrument_id(instrument_id)
344        .raw_symbol(raw_symbol)
345        .asset_class(asset_class_opt.unwrap_or(AssetClass::Commodity))
346        .exchange(exchange)
347        .underlying(underlying)
348        .option_kind(option_kind)
349        .strike_price(strike_price)
350        .currency(currency)
351        .activation_ns(decode_optional_timestamp(msg.activation).unwrap_or_default())
352        .expiration_ns(expiration)
353        .price_precision(price_increment.precision)
354        .price_increment(price_increment)
355        .multiplier(multiplier)
356        .lot_size(lot_size)
357        .ts_event(ts_event)
358        .ts_init(ts_init)
359        .build()?)
360}
361
362fn decode_option_multiplier(
363    dataset: Option<dbn::Dataset>,
364    contract_multiplier: i32,
365    unit_of_measure_qty: i64,
366) -> anyhow::Result<Quantity> {
367    match (dataset, contract_multiplier) {
368        (Some(dbn::Dataset::OpraPillar), 0 | i32::MAX) => decode_multiplier(unit_of_measure_qty),
369        (Some(dbn::Dataset::OpraPillar), value) if value < 0 => {
370            anyhow::bail!("Invalid negative `contract_multiplier`: {value}")
371        }
372        (Some(dbn::Dataset::OpraPillar), value) => {
373            Ok(Quantity::from_mantissa_exponent(value as u64, 0, 0))
374        }
375        _ => decode_multiplier(unit_of_measure_qty),
376    }
377}
378
379/// Decodes a Databento instrument definition message into an `OptionSpread` instrument.
380///
381/// # Errors
382///
383/// Returns an error if parsing or constructing `OptionSpread` fails.
384pub fn decode_option_spread(
385    msg: &dbn::InstrumentDefMsg,
386    instrument_id: InstrumentId,
387    ts_init: Option<UnixNanos>,
388    decode_config: Option<&DatabentoDecodeConfig>,
389) -> anyhow::Result<OptionSpread> {
390    let exchange = Ustr::from(msg.exchange()?);
391    let underlying = decode_underlying(msg.underlying()?, &instrument_id.symbol);
392    let asset_class_opt = if instrument_id.venue.as_str() == "OPRA" {
393        Some(AssetClass::Equity)
394    } else {
395        let (asset_class, _) = parse_cfi_iso10926(msg.cfi()?);
396        asset_class
397    };
398    let strategy_type = Ustr::from(msg.secsubtype()?);
399    let currency = parse_currency_or_usd_default(msg.currency());
400    let price_increment = decode_price_increment(msg.min_price_increment, currency.precision);
401    let multiplier = decode_multiplier(msg.unit_of_measure_qty)?;
402    let lot_size = decode_lot_size(msg.min_lot_size_round_lot);
403    let expiration = corrected_option_expiration(
404        decode_timestamp(msg.expiration, "expiration")?,
405        underlying,
406        msg.hd.publisher().ok().map(|p| p.dataset()),
407        decode_config,
408    );
409    let ts_event = msg.ts_recv.into(); // More accurate and reliable timestamp
410    let ts_init = ts_init.unwrap_or(ts_event);
411
412    Ok(OptionSpread::builder()
413        .instrument_id(instrument_id)
414        .raw_symbol(instrument_id.symbol)
415        .asset_class(asset_class_opt.unwrap_or(AssetClass::Commodity))
416        .exchange(exchange)
417        .underlying(underlying)
418        .strategy_type(strategy_type)
419        .activation_ns(decode_optional_timestamp(msg.activation).unwrap_or_default())
420        .expiration_ns(expiration)
421        .currency(currency)
422        .price_precision(price_increment.precision)
423        .price_increment(price_increment)
424        .multiplier(multiplier)
425        .lot_size(lot_size)
426        .ts_event(ts_event)
427        .ts_init(ts_init)
428        .build()?)
429}