1use 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
44pub 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
167pub 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); 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 .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
202pub 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); 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
241pub 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); 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
282pub 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); 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
375const 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
384const OPRA_ROOTS_CASH_AMERICAN: &[&str] = &["OEX", "XAU"];
386
387fn 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
401fn 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 (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
435pub 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(); 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}