nautilus_databento/decode/
instruments.rs1use 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
43pub 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
166pub 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); 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 .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
200pub 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); 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
239pub 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); 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
280pub 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); 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
379pub 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(); 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}