Skip to main content

nautilus_serialization/arrow/instrument/
mod.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
16//! Arrow serialization for instruments.
17//!
18//! `InstrumentAny` acts as a dispatcher that routes to the appropriate concrete instrument type's
19//! Arrow serialization implementation. Each concrete instrument type implements its own schema
20//! with all fields as columns (wide schema approach), matching the Python implementation.
21
22use std::{any::type_name, borrow::Borrow, collections::HashMap, fmt, str::FromStr};
23
24use arrow::{
25    array::{Array, StringArray},
26    datatypes::Schema,
27    error::ArrowError,
28    record_batch::RecordBatch,
29};
30use nautilus_model::{
31    instruments::{
32        Instrument, InstrumentAny, betting::BettingInstrument, binary_option::BinaryOption,
33        cfd::Cfd, commodity::Commodity, crypto_future::CryptoFuture,
34        crypto_futures_spread::CryptoFuturesSpread, crypto_option::CryptoOption,
35        crypto_option_spread::CryptoOptionSpread, crypto_perpetual::CryptoPerpetual,
36        currency_pair::CurrencyPair, equity::Equity, futures_contract::FuturesContract,
37        futures_spread::FuturesSpread, index_instrument::IndexInstrument,
38        option_contract::OptionContract, option_spread::OptionSpread,
39        perpetual_contract::PerpetualContract, tokenized_asset::TokenizedAsset,
40    },
41    types::{Currency, Price, Quantity},
42};
43
44#[allow(unused)]
45use crate::arrow::{
46    ArrowSchemaProvider, Data, DecodeDataFromRecordBatch, DecodeFromRecordBatch,
47    EncodeToRecordBatch, EncodingError, KEY_INSTRUMENT_ID, KEY_TYPE_NAME, first_logical_null,
48};
49
50pub mod betting;
51pub mod binary_option;
52pub mod cfd;
53pub mod commodity;
54pub mod crypto_future;
55pub mod crypto_futures_spread;
56pub mod crypto_option;
57pub mod crypto_option_spread;
58pub mod crypto_perpetual;
59pub mod currency_pair;
60pub mod equity;
61pub mod futures_contract;
62pub mod futures_spread;
63pub mod index_instrument;
64pub mod option_contract;
65pub mod option_spread;
66pub mod perpetual_contract;
67pub mod tokenized_asset;
68
69// Columns added after the original schemas are read by name and yield `None` when absent,
70// so fragments written before the column existed decode exactly as they did previously.
71pub(crate) fn optional_quantity_value(
72    values: Option<&StringArray>,
73    field: &'static str,
74    row: usize,
75) -> Result<Option<Quantity>, EncodingError> {
76    let Some(column) = values else {
77        return Ok(None);
78    };
79
80    if column.is_null(row) {
81        return Ok(None);
82    }
83
84    Quantity::from_str(column.value(row))
85        .map(Some)
86        .map_err(|e| EncodingError::ParseError(field, format!("row {row}: {e}")))
87}
88
89pub(crate) fn optional_price_value(
90    values: Option<&StringArray>,
91    field: &'static str,
92    row: usize,
93) -> Result<Option<Price>, EncodingError> {
94    let Some(column) = values else {
95        return Ok(None);
96    };
97
98    if column.is_null(row) {
99        return Ok(None);
100    }
101
102    Price::from_str(column.value(row))
103        .map(Some)
104        .map_err(|e| EncodingError::ParseError(field, format!("row {row}: {e}")))
105}
106
107pub(crate) fn optional_parsed_value<T>(
108    values: Option<&StringArray>,
109    field: &'static str,
110    row: usize,
111) -> Result<Option<T>, EncodingError>
112where
113    T: FromStr,
114    T::Err: fmt::Display,
115{
116    let Some(column) = values else {
117        return Ok(None);
118    };
119
120    if column.is_null(row) {
121        return Ok(None);
122    }
123
124    T::from_str(column.value(row))
125        .map(Some)
126        .map_err(|e| EncodingError::ParseError(field, format!("row {row}: {e}")))
127}
128
129// Errors on empty/whitespace codes so corrupted rows surface as ParseError,
130// instead of silently registering as a fallback currency. Known codes resolve
131// from CURRENCY_MAP with original metadata; unknown non-empty codes fall back
132// to a new crypto currency to support newly listed exchange assets.
133pub(crate) fn decode_currency(
134    value: &str,
135    field: &'static str,
136    context: &'static str,
137    row: usize,
138) -> Result<Currency, EncodingError> {
139    let trimmed = value.trim();
140    if trimmed.is_empty() {
141        return Err(EncodingError::ParseError(
142            field,
143            format!("row {row}: empty currency code"),
144        ));
145    }
146
147    Ok(Currency::get_or_create_crypto_with_context(
148        trimmed,
149        Some(context),
150    ))
151}
152
153const INSTRUMENT_VALIDATION_FIELD: &str = "instrument";
154
155pub(crate) fn instrument_validation_error<T>(
156    row: usize,
157    error: impl fmt::Display,
158) -> EncodingError {
159    let type_name = type_name::<T>();
160    let instrument_type = type_name.rsplit("::").next().unwrap_or(type_name);
161
162    EncodingError::ParseError(
163        INSTRUMENT_VALIDATION_FIELD,
164        format!("row {row}: invalid {instrument_type}: {error}"),
165    )
166}
167
168pub(crate) fn validate_required_instrument_columns<T: ArrowSchemaProvider>(
169    metadata: &HashMap<String, String>,
170    record_batch: &RecordBatch,
171) -> Result<(), EncodingError> {
172    let expected = T::get_schema(Some(metadata.clone()));
173    let actual = record_batch.schema();
174    for field in expected
175        .fields()
176        .iter()
177        .filter(|field| !field.is_nullable())
178    {
179        let Ok(index) = actual.index_of(field.name()) else {
180            continue;
181        };
182
183        if let Some(row) = first_logical_null(record_batch.column(index).as_ref()) {
184            return Err(EncodingError::ParseError(
185                INSTRUMENT_VALIDATION_FIELD,
186                format!("required field '{}' is null at row {row}", field.name()),
187            ));
188        }
189    }
190
191    Ok(())
192}
193
194impl ArrowSchemaProvider for InstrumentAny {
195    fn get_schema(metadata: Option<HashMap<String, String>>) -> Schema {
196        let instrument_type = metadata
197            .as_ref()
198            .and_then(|m| m.get(KEY_TYPE_NAME))
199            .map_or("CurrencyPair", |s| s.as_str());
200
201        match instrument_type {
202            "BettingInstrument" => BettingInstrument::get_schema(metadata),
203            "BinaryOption" => BinaryOption::get_schema(metadata),
204            "Cfd" => Cfd::get_schema(metadata),
205            "Commodity" => Commodity::get_schema(metadata),
206            "CryptoFuture" => CryptoFuture::get_schema(metadata),
207            "CryptoFuturesSpread" => CryptoFuturesSpread::get_schema(metadata),
208            "CryptoOption" => CryptoOption::get_schema(metadata),
209            "CryptoOptionSpread" => CryptoOptionSpread::get_schema(metadata),
210            "CryptoPerpetual" => CryptoPerpetual::get_schema(metadata),
211            "CurrencyPair" => CurrencyPair::get_schema(metadata),
212            "Equity" => Equity::get_schema(metadata),
213            "FuturesContract" => FuturesContract::get_schema(metadata),
214            "FuturesSpread" => FuturesSpread::get_schema(metadata),
215            "IndexInstrument" => IndexInstrument::get_schema(metadata),
216            "OptionContract" => OptionContract::get_schema(metadata),
217            "OptionSpread" => OptionSpread::get_schema(metadata),
218            "PerpetualContract" => PerpetualContract::get_schema(metadata),
219            "TokenizedAsset" => TokenizedAsset::get_schema(metadata),
220            _ => {
221                // Fallback to CurrencyPair schema if type is unknown
222                CurrencyPair::get_schema(metadata)
223            }
224        }
225    }
226}
227
228impl EncodeToRecordBatch for InstrumentAny {
229    fn encode_batch<T>(
230        #[allow(unused)] metadata: &HashMap<String, String>,
231        data: &[T],
232    ) -> Result<RecordBatch, ArrowError>
233    where
234        T: std::borrow::Borrow<Self>,
235    {
236        if data.is_empty() {
237            return Err(ArrowError::InvalidArgumentError(
238                "Cannot encode empty instrument batch".to_string(),
239            ));
240        }
241
242        let mut by_type: HashMap<String, Vec<&Self>> = HashMap::new();
243
244        for instrument in data.iter().map(Borrow::borrow) {
245            let type_name = match instrument {
246                Self::Cfd(_) => "Cfd",
247                Self::Commodity(_) => "Commodity",
248                Self::CurrencyPair(_) => "CurrencyPair",
249                Self::Equity(_) => "Equity",
250                Self::CryptoFuture(_) => "CryptoFuture",
251                Self::CryptoFuturesSpread(_) => "CryptoFuturesSpread",
252                Self::CryptoPerpetual(_) => "CryptoPerpetual",
253                Self::CryptoOption(_) => "CryptoOption",
254                Self::CryptoOptionSpread(_) => "CryptoOptionSpread",
255                Self::FuturesContract(_) => "FuturesContract",
256                Self::FuturesSpread(_) => "FuturesSpread",
257                Self::IndexInstrument(_) => "IndexInstrument",
258                Self::OptionContract(_) => "OptionContract",
259                Self::OptionSpread(_) => "OptionSpread",
260                Self::BinaryOption(_) => "BinaryOption",
261                Self::Betting(_) => "BettingInstrument",
262                Self::PerpetualContract(_) => "PerpetualContract",
263                Self::TokenizedAsset(_) => "TokenizedAsset",
264            };
265            by_type
266                .entry(type_name.to_string())
267                .or_default()
268                .push(instrument);
269        }
270
271        if by_type.len() > 1 {
272            return Err(ArrowError::InvalidArgumentError(
273                "Cannot encode mixed instrument types in a single batch. Use separate batches for each type.".to_string(),
274            ));
275        }
276
277        let (type_name, instruments) = by_type.iter().next().unwrap();
278        match type_name.as_str() {
279            "Cfd" => {
280                let cfds: Vec<_> = instruments
281                    .iter()
282                    .map(|i| {
283                        if let Self::Cfd(c) = i {
284                            c
285                        } else {
286                            unreachable!()
287                        }
288                    })
289                    .cloned()
290                    .collect();
291                Cfd::encode_batch(metadata, &cfds)
292            }
293            "Commodity" => {
294                let commodities: Vec<_> = instruments
295                    .iter()
296                    .map(|i| {
297                        if let Self::Commodity(c) = i {
298                            c
299                        } else {
300                            unreachable!()
301                        }
302                    })
303                    .cloned()
304                    .collect();
305                Commodity::encode_batch(metadata, &commodities)
306            }
307            "BettingInstrument" => {
308                let betting: Vec<_> = instruments
309                    .iter()
310                    .map(|i| {
311                        if let Self::Betting(b) = i {
312                            b
313                        } else {
314                            unreachable!()
315                        }
316                    })
317                    .cloned()
318                    .collect();
319                BettingInstrument::encode_batch(metadata, &betting)
320            }
321            "BinaryOption" => {
322                let binary_options: Vec<_> = instruments
323                    .iter()
324                    .map(|i| {
325                        if let Self::BinaryOption(bo) = i {
326                            bo
327                        } else {
328                            unreachable!()
329                        }
330                    })
331                    .cloned()
332                    .collect();
333                BinaryOption::encode_batch(metadata, &binary_options)
334            }
335            "CryptoFuture" => {
336                let crypto_futures: Vec<_> = instruments
337                    .iter()
338                    .map(|i| {
339                        if let Self::CryptoFuture(cf) = i {
340                            cf
341                        } else {
342                            unreachable!()
343                        }
344                    })
345                    .cloned()
346                    .collect();
347                CryptoFuture::encode_batch(metadata, &crypto_futures)
348            }
349            "CryptoFuturesSpread" => {
350                let spreads: Vec<_> = instruments
351                    .iter()
352                    .map(|i| {
353                        if let Self::CryptoFuturesSpread(cfs) = i {
354                            cfs
355                        } else {
356                            unreachable!()
357                        }
358                    })
359                    .cloned()
360                    .collect();
361                CryptoFuturesSpread::encode_batch(metadata, &spreads)
362            }
363            "CryptoOption" => {
364                let crypto_options: Vec<_> = instruments
365                    .iter()
366                    .map(|i| {
367                        if let Self::CryptoOption(co) = i {
368                            co
369                        } else {
370                            unreachable!()
371                        }
372                    })
373                    .cloned()
374                    .collect();
375                CryptoOption::encode_batch(metadata, &crypto_options)
376            }
377            "CryptoOptionSpread" => {
378                let spreads: Vec<_> = instruments
379                    .iter()
380                    .map(|i| {
381                        if let Self::CryptoOptionSpread(cos) = i {
382                            cos
383                        } else {
384                            unreachable!()
385                        }
386                    })
387                    .cloned()
388                    .collect();
389                CryptoOptionSpread::encode_batch(metadata, &spreads)
390            }
391            "CryptoPerpetual" => {
392                let crypto_perps: Vec<_> = instruments
393                    .iter()
394                    .map(|i| {
395                        if let Self::CryptoPerpetual(cp) = i {
396                            cp
397                        } else {
398                            unreachable!()
399                        }
400                    })
401                    .cloned()
402                    .collect();
403                CryptoPerpetual::encode_batch(metadata, &crypto_perps)
404            }
405            "CurrencyPair" => {
406                let currency_pairs: Vec<_> = instruments
407                    .iter()
408                    .map(|i| {
409                        if let Self::CurrencyPair(cp) = i {
410                            cp
411                        } else {
412                            unreachable!()
413                        }
414                    })
415                    .cloned()
416                    .collect();
417                CurrencyPair::encode_batch(metadata, &currency_pairs)
418            }
419            "Equity" => {
420                let equities: Vec<_> = instruments
421                    .iter()
422                    .map(|i| {
423                        if let Self::Equity(e) = i {
424                            e
425                        } else {
426                            unreachable!()
427                        }
428                    })
429                    .cloned()
430                    .collect();
431                Equity::encode_batch(metadata, &equities)
432            }
433            "FuturesContract" => {
434                let futures_contracts: Vec<_> = instruments
435                    .iter()
436                    .map(|i| {
437                        if let Self::FuturesContract(fc) = i {
438                            fc
439                        } else {
440                            unreachable!()
441                        }
442                    })
443                    .cloned()
444                    .collect();
445                FuturesContract::encode_batch(metadata, &futures_contracts)
446            }
447            "FuturesSpread" => {
448                let futures_spreads: Vec<_> = instruments
449                    .iter()
450                    .map(|i| {
451                        if let Self::FuturesSpread(fs) = i {
452                            fs
453                        } else {
454                            unreachable!()
455                        }
456                    })
457                    .cloned()
458                    .collect();
459                FuturesSpread::encode_batch(metadata, &futures_spreads)
460            }
461            "IndexInstrument" => {
462                let index_instruments: Vec<_> = instruments
463                    .iter()
464                    .map(|i| {
465                        if let Self::IndexInstrument(ii) = i {
466                            ii
467                        } else {
468                            unreachable!()
469                        }
470                    })
471                    .cloned()
472                    .collect();
473                IndexInstrument::encode_batch(metadata, &index_instruments)
474            }
475            "OptionContract" => {
476                let option_contracts: Vec<_> = instruments
477                    .iter()
478                    .map(|i| {
479                        if let Self::OptionContract(oc) = i {
480                            oc
481                        } else {
482                            unreachable!()
483                        }
484                    })
485                    .cloned()
486                    .collect();
487                OptionContract::encode_batch(metadata, &option_contracts)
488            }
489            "OptionSpread" => {
490                let option_spreads: Vec<_> = instruments
491                    .iter()
492                    .map(|i| {
493                        if let Self::OptionSpread(os) = i {
494                            os
495                        } else {
496                            unreachable!()
497                        }
498                    })
499                    .cloned()
500                    .collect();
501                OptionSpread::encode_batch(metadata, &option_spreads)
502            }
503            "PerpetualContract" => {
504                let perpetual_contracts: Vec<_> = instruments
505                    .iter()
506                    .map(|i| {
507                        if let Self::PerpetualContract(pc) = i {
508                            pc
509                        } else {
510                            unreachable!()
511                        }
512                    })
513                    .cloned()
514                    .collect();
515                PerpetualContract::encode_batch(metadata, &perpetual_contracts)
516            }
517            "TokenizedAsset" => {
518                let tokenized_assets: Vec<_> = instruments
519                    .iter()
520                    .map(|i| {
521                        if let Self::TokenizedAsset(ta) = i {
522                            ta
523                        } else {
524                            unreachable!()
525                        }
526                    })
527                    .cloned()
528                    .collect();
529                TokenizedAsset::encode_batch(metadata, &tokenized_assets)
530            }
531            _ => Err(ArrowError::InvalidArgumentError(format!(
532                "Instrument type {type_name} serialization not yet implemented"
533            ))),
534        }
535    }
536
537    fn metadata(&self) -> HashMap<String, String> {
538        let mut metadata = HashMap::new();
539        metadata.insert(
540            KEY_INSTRUMENT_ID.to_string(),
541            Instrument::id(self).to_string(),
542        );
543
544        let type_name = match self {
545            Self::Cfd(_) => "Cfd",
546            Self::Commodity(_) => "Commodity",
547            Self::CurrencyPair(_) => "CurrencyPair",
548            Self::Equity(_) => "Equity",
549            Self::CryptoFuture(_) => "CryptoFuture",
550            Self::CryptoFuturesSpread(_) => "CryptoFuturesSpread",
551            Self::CryptoPerpetual(_) => "CryptoPerpetual",
552            Self::CryptoOption(_) => "CryptoOption",
553            Self::CryptoOptionSpread(_) => "CryptoOptionSpread",
554            Self::FuturesContract(_) => "FuturesContract",
555            Self::FuturesSpread(_) => "FuturesSpread",
556            Self::IndexInstrument(_) => "IndexInstrument",
557            Self::OptionContract(_) => "OptionContract",
558            Self::OptionSpread(_) => "OptionSpread",
559            Self::BinaryOption(_) => "BinaryOption",
560            Self::Betting(_) => "BettingInstrument",
561            Self::PerpetualContract(_) => "PerpetualContract",
562            Self::TokenizedAsset(_) => "TokenizedAsset",
563        };
564
565        metadata.insert(KEY_TYPE_NAME.to_string(), type_name.to_string());
566        metadata
567    }
568}
569
570/// Decode InstrumentAny from RecordBatch
571/// (Cannot implement DecodeFromRecordBatch trait due to `Into<Data>` bound)
572///
573/// # Errors
574///
575/// Returns an error if the RecordBatch cannot be decoded.
576pub fn decode_instrument_any_batch(
577    #[allow(unused)] metadata: &HashMap<String, String>,
578    record_batch: &RecordBatch,
579) -> Result<Vec<InstrumentAny>, EncodingError> {
580    let type_name = metadata
581        .get(KEY_TYPE_NAME)
582        .map(String::as_str)
583        .ok_or_else(|| EncodingError::MissingMetadata(KEY_TYPE_NAME))?;
584
585    match type_name {
586        "Cfd" => {
587            let cfds = cfd::decode_cfd_batch(metadata, record_batch)?;
588            Ok(cfds.into_iter().map(InstrumentAny::Cfd).collect())
589        }
590        "Commodity" => {
591            let commodities = commodity::decode_commodity_batch(metadata, record_batch)?;
592            Ok(commodities
593                .into_iter()
594                .map(InstrumentAny::Commodity)
595                .collect())
596        }
597        "BettingInstrument" => {
598            let betting = betting::decode_betting_instrument_batch(metadata, record_batch)?;
599            Ok(betting.into_iter().map(InstrumentAny::Betting).collect())
600        }
601        "BinaryOption" => {
602            let binary_options = binary_option::decode_binary_option_batch(metadata, record_batch)?;
603            Ok(binary_options
604                .into_iter()
605                .map(InstrumentAny::BinaryOption)
606                .collect())
607        }
608        "CryptoFuture" => {
609            let crypto_futures = crypto_future::decode_crypto_future_batch(metadata, record_batch)?;
610            Ok(crypto_futures
611                .into_iter()
612                .map(InstrumentAny::CryptoFuture)
613                .collect())
614        }
615        "CryptoFuturesSpread" => {
616            let spreads =
617                crypto_futures_spread::decode_crypto_futures_spread_batch(metadata, record_batch)?;
618            Ok(spreads
619                .into_iter()
620                .map(InstrumentAny::CryptoFuturesSpread)
621                .collect())
622        }
623        "CryptoOption" => {
624            let crypto_options = crypto_option::decode_crypto_option_batch(metadata, record_batch)?;
625            Ok(crypto_options
626                .into_iter()
627                .map(InstrumentAny::CryptoOption)
628                .collect())
629        }
630        "CryptoOptionSpread" => {
631            let spreads =
632                crypto_option_spread::decode_crypto_option_spread_batch(metadata, record_batch)?;
633            Ok(spreads
634                .into_iter()
635                .map(InstrumentAny::CryptoOptionSpread)
636                .collect())
637        }
638        "CryptoPerpetual" => {
639            let crypto_perps =
640                crypto_perpetual::decode_crypto_perpetual_batch(metadata, record_batch)?;
641            Ok(crypto_perps
642                .into_iter()
643                .map(InstrumentAny::CryptoPerpetual)
644                .collect())
645        }
646        "CurrencyPair" => {
647            let currency_pairs = currency_pair::decode_currency_pair_batch(metadata, record_batch)?;
648            Ok(currency_pairs
649                .into_iter()
650                .map(InstrumentAny::CurrencyPair)
651                .collect())
652        }
653        "Equity" => {
654            let equities = equity::decode_equity_batch(metadata, record_batch)?;
655            Ok(equities.into_iter().map(InstrumentAny::Equity).collect())
656        }
657        "FuturesContract" => {
658            let futures_contracts =
659                futures_contract::decode_futures_contract_batch(metadata, record_batch)?;
660            Ok(futures_contracts
661                .into_iter()
662                .map(InstrumentAny::FuturesContract)
663                .collect())
664        }
665        "FuturesSpread" => {
666            let futures_spreads =
667                futures_spread::decode_futures_spread_batch(metadata, record_batch)?;
668            Ok(futures_spreads
669                .into_iter()
670                .map(InstrumentAny::FuturesSpread)
671                .collect())
672        }
673        "IndexInstrument" => {
674            let index_instruments =
675                index_instrument::decode_index_instrument_batch(metadata, record_batch)?;
676            Ok(index_instruments
677                .into_iter()
678                .map(InstrumentAny::IndexInstrument)
679                .collect())
680        }
681        "OptionContract" => {
682            let option_contracts =
683                option_contract::decode_option_contract_batch(metadata, record_batch)?;
684            Ok(option_contracts
685                .into_iter()
686                .map(InstrumentAny::OptionContract)
687                .collect())
688        }
689        "OptionSpread" => {
690            let option_spreads = option_spread::decode_option_spread_batch(metadata, record_batch)?;
691            Ok(option_spreads
692                .into_iter()
693                .map(InstrumentAny::OptionSpread)
694                .collect())
695        }
696        "PerpetualContract" => {
697            let perpetual_contracts =
698                perpetual_contract::decode_perpetual_contract_batch(metadata, record_batch)?;
699            Ok(perpetual_contracts
700                .into_iter()
701                .map(InstrumentAny::PerpetualContract)
702                .collect())
703        }
704        "TokenizedAsset" => {
705            let tokenized_assets =
706                tokenized_asset::decode_tokenized_asset_batch(metadata, record_batch)?;
707            Ok(tokenized_assets
708                .into_iter()
709                .map(InstrumentAny::TokenizedAsset)
710                .collect())
711        }
712        _ => Err(EncodingError::ParseError(
713            KEY_TYPE_NAME,
714            format!("Unknown instrument type: {type_name}"),
715        )),
716    }
717}
718
719#[cfg(test)]
720mod tests {
721    use std::sync::Arc;
722
723    use arrow::{
724        array::{Array, ArrayRef, StringArray, UInt8Array},
725        datatypes::DataType,
726    };
727    use nautilus_core::{Params, UnixNanos};
728    use nautilus_model::{
729        enums::{AssetClass, CurrencyType, OptionKind},
730        identifiers::{InstrumentId, Symbol},
731        instruments::{
732            Instrument, InstrumentAny,
733            currency_pair::CurrencyPair,
734            stubs::{
735                betting, cfd_gold, commodity_gold, crypto_future_btcusdt,
736                crypto_futures_spread_btc_deribit, crypto_option_btc_deribit,
737                crypto_option_spread_btc_deribit, crypto_perpetual_ethusdt, currency_pair_ethusdt,
738                equity_aapl, perpetual_contract_eurusd, tokenized_asset_aaplx,
739            },
740            tick_scheme::{
741                FixedTickScheme, TickScheme, TieredTickScheme, get_tick_scheme,
742                register_tick_scheme,
743            },
744        },
745        types::{Currency, Money, Price, Quantity},
746    };
747    use rstest::rstest;
748    use rust_decimal_macros::dec;
749    use ustr::Ustr;
750
751    use super::*;
752
753    #[rstest]
754    fn test_get_schema() {
755        let mut metadata = HashMap::new();
756        metadata.insert(KEY_TYPE_NAME.to_string(), "CurrencyPair".to_string());
757        let schema = InstrumentAny::get_schema(Some(metadata));
758        assert!(schema.fields().len() >= 20);
759        assert_eq!(schema.field(0).name(), "id");
760    }
761
762    #[rstest]
763    #[case("")]
764    #[case("   ")]
765    #[case("\t\n")]
766    fn test_decode_currency_empty_or_whitespace_errors(#[case] value: &str) {
767        let result = decode_currency(value, "currency", "test.currency", 7);
768        let err = result.expect_err("empty code must surface EncodingError");
769        match err {
770            EncodingError::ParseError(field, msg) => {
771                assert_eq!(field, "currency");
772                assert!(
773                    msg.contains("row 7"),
774                    "message should include row index, found: {msg}",
775                );
776                assert!(
777                    msg.contains("empty currency code"),
778                    "message should describe empty code, found: {msg}",
779                );
780            }
781            other => panic!("unexpected error variant: {other:?}"),
782        }
783        // Ensure the fallback did not register a phantom currency under the empty key.
784        assert!(Currency::try_from_str(value.trim()).is_none());
785    }
786
787    #[rstest]
788    #[case("USD", CurrencyType::Fiat, 2)]
789    #[case("BTC", CurrencyType::Crypto, 8)]
790    #[case("XAU", CurrencyType::CommodityBacked, 2)]
791    fn test_decode_currency_known_code_preserves_metadata(
792        #[case] code: &str,
793        #[case] expected_type: CurrencyType,
794        #[case] expected_precision: u8,
795    ) {
796        let currency = decode_currency(code, "currency", "test.currency", 0).unwrap();
797        assert_eq!(currency.code.as_str(), code);
798        assert_eq!(currency.currency_type, expected_type);
799        assert_eq!(currency.precision, expected_precision);
800    }
801
802    #[rstest]
803    fn test_decode_currency_unknown_code_registers_as_crypto() {
804        let code = "XDECTEST";
805        assert!(
806            Currency::try_from_str(code).is_none(),
807            "test precondition: '{code}' must not be pre-registered",
808        );
809
810        let currency = decode_currency(code, "base_currency", "test.base_currency", 0).unwrap();
811        assert_eq!(currency.code.as_str(), code);
812        assert_eq!(currency.currency_type, CurrencyType::Crypto);
813        assert_eq!(currency.precision, 8);
814        assert_eq!(currency.iso4217, 0);
815
816        let registered = Currency::try_from_str(code).expect("unknown code must be registered");
817        assert_eq!(registered, currency);
818    }
819
820    #[rstest]
821    fn test_encode_decode_round_trip() {
822        let instrument_id = InstrumentId::from("EUR/USD.SIM");
823        let currency_pair = CurrencyPair::builder()
824            .instrument_id(instrument_id)
825            .raw_symbol(Symbol::from("EUR/USD"))
826            .base_currency(Currency::from("EUR"))
827            .quote_currency(Currency::from("USD"))
828            .price_precision(5)
829            // size_precision must match size_increment precision (0)
830            .size_precision(0)
831            .price_increment(Price::new(0.00001, 5))
832            // precision 0
833            .size_increment(Quantity::new(1.0, 0))
834            .tick_scheme(Ustr::from("FOREX_5DECIMAL"))
835            .ts_event(UnixNanos::default())
836            .ts_init(UnixNanos::default())
837            .build()
838            .unwrap();
839        let instrument = InstrumentAny::CurrencyPair(currency_pair);
840
841        let metadata = instrument.metadata();
842        let record_batch =
843            InstrumentAny::encode_batch(&metadata, std::slice::from_ref(&instrument)).unwrap();
844        let decoded = decode_instrument_any_batch(&metadata, &record_batch).unwrap();
845
846        assert_eq!(decoded.len(), 1);
847        assert_eq!(Instrument::id(&decoded[0]), Instrument::id(&instrument));
848        assert_eq!(
849            Instrument::raw_symbol(&decoded[0]),
850            Instrument::raw_symbol(&instrument)
851        );
852        assert_eq!(
853            Instrument::asset_class(&decoded[0]),
854            Instrument::asset_class(&instrument)
855        );
856
857        match (&decoded[0], &instrument) {
858            (InstrumentAny::CurrencyPair(decoded_cp), InstrumentAny::CurrencyPair(original_cp)) => {
859                assert_eq!(decoded_cp.id, original_cp.id);
860                assert_eq!(decoded_cp.base_currency, original_cp.base_currency);
861                assert_eq!(decoded_cp.quote_currency, original_cp.quote_currency);
862                assert_eq!(decoded_cp.price_precision, original_cp.price_precision);
863                assert_eq!(decoded_cp.size_precision, original_cp.size_precision);
864                assert_eq!(decoded_cp.tick_scheme, original_cp.tick_scheme);
865            }
866            _ => panic!("Decoded instrument type mismatch"),
867        }
868    }
869
870    #[rstest]
871    #[case::binary_option(nautilus_model::instruments::stubs::binary_option().into_any())]
872    #[case::betting(betting().into_any())]
873    #[case::cfd(cfd_gold().into_any())]
874    #[case::commodity(commodity_gold().into_any())]
875    #[case::crypto_future(crypto_future_btcusdt(2, 6, Price::from("0.01"), Quantity::from("0.000001")).into_any())]
876    #[case::crypto_futures_spread(crypto_futures_spread_btc_deribit().into_any())]
877    #[case::crypto_option(crypto_option_btc_deribit(3, 1, Price::from("0.001"), Quantity::from("0.1")).into_any())]
878    #[case::crypto_option_spread(crypto_option_spread_btc_deribit().into_any())]
879    #[case::crypto_perpetual(crypto_perpetual_ethusdt().into_any())]
880    #[case::currency_pair(currency_pair_ethusdt().into_any())]
881    #[case::perpetual_contract(perpetual_contract_eurusd().into_any())]
882    #[case::tokenized_asset(tokenized_asset_aaplx().into_any())]
883    fn test_instrument_exact_money_notional_round_trip(#[case] instrument: InstrumentAny) {
884        let currency = instrument.quote_currency();
885        let maximum = Money::from_decimal_exact(dec!(1.000000001), currency).unwrap();
886        let minimum = Money::from_decimal_exact(dec!(0.000000003), currency).unwrap();
887        let mut encoded = serde_json::to_value(instrument).unwrap();
888        let fields = encoded
889            .as_object_mut()
890            .unwrap()
891            .values_mut()
892            .next()
893            .unwrap();
894        fields["max_notional"] = serde_json::to_value(maximum).unwrap();
895        fields["min_notional"] = serde_json::to_value(minimum).unwrap();
896        let instrument: InstrumentAny = serde_json::from_value(encoded).unwrap();
897        let metadata = instrument.metadata();
898        let batch =
899            InstrumentAny::encode_batch(&metadata, std::slice::from_ref(&instrument)).unwrap();
900        let decoded = decode_instrument_any_batch(&metadata, &batch).unwrap();
901
902        assert_eq!(decoded.len(), 1);
903        assert_eq!(decoded[0].id(), instrument.id());
904        assert_eq!(decoded[0].max_notional(), Some(maximum));
905        assert_eq!(decoded[0].min_notional(), Some(minimum));
906    }
907
908    #[rstest]
909    fn test_decode_currency_pair_without_tick_scheme_column_defaults_none() {
910        let instrument_id = InstrumentId::from("EUR/USD.SIM");
911        let currency_pair = CurrencyPair::builder()
912            .instrument_id(instrument_id)
913            .raw_symbol(Symbol::from("EUR/USD"))
914            .base_currency(Currency::from("EUR"))
915            .quote_currency(Currency::from("USD"))
916            .price_precision(5)
917            .size_precision(0)
918            .price_increment(Price::new(0.00001, 5))
919            .size_increment(Quantity::new(1.0, 0))
920            .tick_scheme(Ustr::from("FOREX_5DECIMAL"))
921            .ts_event(UnixNanos::default())
922            .ts_init(UnixNanos::default())
923            .build()
924            .unwrap();
925        let instrument = InstrumentAny::CurrencyPair(currency_pair);
926
927        let metadata = instrument.metadata();
928        let record_batch =
929            InstrumentAny::encode_batch(&metadata, std::slice::from_ref(&instrument)).unwrap();
930        let record_batch = batch_without_column(&record_batch, "tick_scheme");
931        let decoded = decode_instrument_any_batch(&metadata, &record_batch).unwrap();
932
933        assert_eq!(decoded.len(), 1);
934        match &decoded[0] {
935            InstrumentAny::CurrencyPair(decoded_cp) => {
936                assert_eq!(decoded_cp.id, instrument.id());
937                assert_eq!(decoded_cp.tick_scheme, None);
938            }
939            _ => panic!("Decoded instrument type mismatch"),
940        }
941    }
942
943    #[rstest]
944    fn test_encode_decode_round_trip_equity() {
945        use nautilus_model::instruments::{Instrument, equity::Equity};
946
947        let instrument_id = InstrumentId::from("AAPL.NASDAQ");
948        let equity = Equity::builder()
949            .instrument_id(instrument_id)
950            .raw_symbol(Symbol::from("AAPL"))
951            .currency(Currency::from("USD"))
952            .price_precision(2)
953            .price_increment(Price::new(0.01, 2))
954            .ts_event(UnixNanos::default())
955            .ts_init(UnixNanos::default())
956            .build()
957            .unwrap();
958        let instrument = InstrumentAny::Equity(equity);
959
960        let metadata = instrument.metadata();
961        let record_batch =
962            InstrumentAny::encode_batch(&metadata, std::slice::from_ref(&instrument)).unwrap();
963        let decoded = decode_instrument_any_batch(&metadata, &record_batch).unwrap();
964        assert_eq!(decoded.len(), 1);
965        assert_eq!(Instrument::id(&decoded[0]), Instrument::id(&instrument));
966        assert_eq!(
967            Instrument::raw_symbol(&decoded[0]),
968            Instrument::raw_symbol(&instrument)
969        );
970        assert_eq!(
971            Instrument::asset_class(&decoded[0]),
972            Instrument::asset_class(&instrument)
973        );
974
975        match (&decoded[0], &instrument) {
976            (InstrumentAny::Equity(decoded_eq), InstrumentAny::Equity(original_eq)) => {
977                assert_eq!(decoded_eq.id, original_eq.id);
978                assert_eq!(decoded_eq.currency, original_eq.currency);
979                assert_eq!(decoded_eq.price_precision, original_eq.price_precision);
980            }
981            _ => panic!("Decoded instrument type mismatch"),
982        }
983    }
984
985    #[rstest]
986    fn test_encode_decode_round_trip_equity_all_fields() {
987        use nautilus_core::Params;
988
989        let info = Params::new([("sector".to_string(), serde_json::json!("technology"))].into());
990
991        let equity = Equity::builder()
992            .instrument_id(InstrumentId::from("AAPL.NASDAQ"))
993            .raw_symbol(Symbol::from("AAPL"))
994            .isin(Ustr::from("US0378331005"))
995            .currency(Currency::from("USD"))
996            .price_precision(2)
997            .price_increment(Price::from("0.01"))
998            .lot_size(Quantity::from("100"))
999            .max_quantity(Quantity::from("10000"))
1000            .min_quantity(Quantity::from("1"))
1001            .max_price(Price::from("9999.99"))
1002            .min_price(Price::from("0.01"))
1003            .margin_init(dec!(0.01))
1004            .margin_maint(dec!(0.02))
1005            .tick_scheme(Ustr::from("TOPIX100"))
1006            .info(info)
1007            .ts_event(1.into())
1008            .ts_init(2.into())
1009            .build()
1010            .unwrap();
1011        let instrument = InstrumentAny::Equity(equity.clone());
1012
1013        let metadata = instrument.metadata();
1014        let record_batch =
1015            InstrumentAny::encode_batch(&metadata, std::slice::from_ref(&instrument)).unwrap();
1016        let decoded = decode_instrument_any_batch(&metadata, &record_batch).unwrap();
1017
1018        assert_eq!(decoded.len(), 1);
1019        let InstrumentAny::Equity(decoded_equity) = &decoded[0] else {
1020            panic!("Decoded instrument type mismatch");
1021        };
1022
1023        // The v1 `from_dict` dropped these quantity constraints (#4461), so check them here
1024        assert_eq!(decoded_equity.max_quantity, equity.max_quantity);
1025        assert_eq!(decoded_equity.min_quantity, equity.min_quantity);
1026
1027        // `PartialEq` compares only `id`, so compare every field via its serialized form
1028        assert_eq!(
1029            serde_json::to_value(decoded_equity).unwrap(),
1030            serde_json::to_value(&equity).unwrap(),
1031        );
1032    }
1033
1034    #[rstest]
1035    fn test_instrument_info_uses_nullable_utf8_json() {
1036        let absent = equity_aapl();
1037        let mut populated = absent.clone();
1038
1039        let info = nautilus_core::Params::new(
1040            [
1041                ("enabled".to_string(), serde_json::json!(true)),
1042                ("source".to_string(), serde_json::json!("unit-test")),
1043            ]
1044            .into(),
1045        );
1046        populated.info = Some(info);
1047        let instruments = [
1048            InstrumentAny::Equity(populated.clone()),
1049            InstrumentAny::Equity(absent.clone()),
1050        ];
1051        let metadata = instruments[0].metadata();
1052
1053        let batch = InstrumentAny::encode_batch(&metadata, &instruments).unwrap();
1054        let schema = batch.schema();
1055        let field = schema.field_with_name("info").unwrap();
1056        let info = batch
1057            .column_by_name("info")
1058            .unwrap()
1059            .as_any()
1060            .downcast_ref::<StringArray>()
1061            .unwrap();
1062        let decoded = decode_instrument_any_batch(&metadata, &batch).unwrap();
1063
1064        assert_eq!(field.data_type(), &DataType::Utf8);
1065        assert!(field.is_nullable());
1066        assert_eq!(field.extension_type_name(), Some("arrow.json"));
1067        assert_eq!(
1068            serde_json::from_str::<nautilus_core::Params>(info.value(0)).unwrap(),
1069            populated.info.clone().unwrap(),
1070        );
1071        assert!(info.is_null(1));
1072        let InstrumentAny::Equity(decoded_populated) = &decoded[0] else {
1073            panic!("Decoded instrument type mismatch");
1074        };
1075        let InstrumentAny::Equity(decoded_absent) = &decoded[1] else {
1076            panic!("Decoded instrument type mismatch");
1077        };
1078        assert_eq!(decoded_populated.info, populated.info);
1079        assert_eq!(decoded_absent.info, absent.info);
1080    }
1081
1082    #[rstest]
1083    fn test_encode_decode_round_trip_futures_contract_all_fields() {
1084        let contract = FuturesContract::builder()
1085            .instrument_id(InstrumentId::from("ESZ4.XCME"))
1086            .raw_symbol(Symbol::from("ESZ4"))
1087            .asset_class(AssetClass::Index)
1088            .exchange(Ustr::from("XCME"))
1089            .underlying(Ustr::from("ES"))
1090            .activation_ns(1.into())
1091            .expiration_ns(2.into())
1092            .currency(Currency::from("USD"))
1093            .price_precision(2)
1094            .price_increment(Price::from("0.01"))
1095            .multiplier(Quantity::from("1"))
1096            .lot_size(Quantity::from("1"))
1097            .max_quantity(Quantity::from("10000"))
1098            .min_quantity(Quantity::from("5"))
1099            .max_price(Price::from("9999.99"))
1100            .min_price(Price::from("0.01"))
1101            .margin_init(dec!(0.01))
1102            .margin_maint(dec!(0.02))
1103            .ts_event(1.into())
1104            .ts_init(2.into())
1105            .build()
1106            .unwrap();
1107
1108        let decoded = encode_decode_instrument(&InstrumentAny::FuturesContract(contract.clone()));
1109        let InstrumentAny::FuturesContract(decoded) = decoded else {
1110            panic!("Decoded instrument type mismatch");
1111        };
1112
1113        assert_eq!(
1114            serde_json::to_value(&decoded).unwrap(),
1115            serde_json::to_value(&contract).unwrap(),
1116        );
1117    }
1118
1119    #[rstest]
1120    fn test_encode_decode_round_trip_option_contract_all_fields() {
1121        let contract = OptionContract::builder()
1122            .instrument_id(InstrumentId::from("AAPL_C100.OPRA"))
1123            .raw_symbol(Symbol::from("AAPL_C100"))
1124            .asset_class(AssetClass::Equity)
1125            .exchange(Ustr::from("OPRA"))
1126            .underlying(Ustr::from("AAPL"))
1127            .option_kind(OptionKind::Call)
1128            .strike_price(Price::from("100.00"))
1129            .currency(Currency::from("USD"))
1130            .activation_ns(1.into())
1131            .expiration_ns(2.into())
1132            .price_precision(2)
1133            .price_increment(Price::from("0.01"))
1134            .multiplier(Quantity::from("100"))
1135            .lot_size(Quantity::from("1"))
1136            .max_quantity(Quantity::from("10000"))
1137            .min_quantity(Quantity::from("5"))
1138            .max_price(Price::from("9999.99"))
1139            .min_price(Price::from("0.01"))
1140            .margin_init(dec!(0.01))
1141            .margin_maint(dec!(0.02))
1142            .ts_event(1.into())
1143            .ts_init(2.into())
1144            .build()
1145            .unwrap();
1146
1147        let decoded = encode_decode_instrument(&InstrumentAny::OptionContract(contract.clone()));
1148        let InstrumentAny::OptionContract(decoded) = decoded else {
1149            panic!("Decoded instrument type mismatch");
1150        };
1151
1152        assert_eq!(
1153            serde_json::to_value(&decoded).unwrap(),
1154            serde_json::to_value(&contract).unwrap(),
1155        );
1156    }
1157
1158    #[rstest]
1159    fn test_encode_decode_round_trip_binary_option_all_fields() {
1160        let raw = "0.1234567890123456789012345678";
1161        let info = Params::new([("gamma_market".to_string(), serde_json::json!(raw))].into());
1162        let option = BinaryOption::builder()
1163            .instrument_id(InstrumentId::from("ELECTION.POLYMARKET"))
1164            .raw_symbol(Symbol::from("ELECTION"))
1165            .asset_class(AssetClass::Alternative)
1166            .currency(Currency::from("USDC"))
1167            .activation_ns(1.into())
1168            .expiration_ns(2.into())
1169            .price_precision(2)
1170            .size_precision(0)
1171            .price_increment(Price::from("0.01"))
1172            .size_increment(Quantity::from("1"))
1173            .event_id(Ustr::from("event-123"))
1174            .info(info)
1175            .outcome(Ustr::from("YES"))
1176            .description(Ustr::from("Election outcome"))
1177            .max_quantity(Quantity::from("10000"))
1178            .min_quantity(Quantity::from("5"))
1179            .max_notional(Money::from("50000 USDC"))
1180            .min_notional(Money::from("5 USDC"))
1181            .max_price(Price::from("0.99"))
1182            .min_price(Price::from("0.01"))
1183            .margin_init(dec!(0.01))
1184            .margin_maint(dec!(0.02))
1185            .ts_event(1.into())
1186            .ts_init(2.into())
1187            .build()
1188            .unwrap();
1189
1190        let decoded = encode_decode_instrument(&InstrumentAny::BinaryOption(option.clone()));
1191        let InstrumentAny::BinaryOption(decoded) = decoded else {
1192            panic!("Decoded instrument type mismatch");
1193        };
1194
1195        assert_eq!(
1196            serde_json::to_value(&decoded).unwrap(),
1197            serde_json::to_value(&option).unwrap(),
1198        );
1199    }
1200
1201    #[rstest]
1202    #[case::missing(false)]
1203    #[case::null(true)]
1204    fn test_binary_option_event_id_legacy_default(#[case] null: bool) {
1205        let mut option = nautilus_model::instruments::stubs::binary_option();
1206        option.event_id = Some(Ustr::from("event-123"));
1207        let metadata = option.metadata();
1208        let batch = BinaryOption::encode_batch(&metadata, &[option]).unwrap();
1209
1210        let batch = if null {
1211            batch_with_null_string_column(&batch, "event_id")
1212        } else {
1213            batch_without_column(&batch, "event_id")
1214        };
1215
1216        let decoded = binary_option::decode_binary_option_batch(&metadata, &batch).unwrap();
1217        assert_eq!(decoded.len(), 1);
1218        assert_eq!(decoded[0].event_id, None);
1219    }
1220
1221    #[rstest]
1222    #[case::fixed("BINARY_CODEC_FIXED", TickScheme::Fixed(FixedTickScheme::new(Price::from("0.0020")).unwrap()))]
1223    #[case::tiered("BINARY_CODEC_TIERED", TickScheme::Tiered(TieredTickScheme::from_ticks(vec![Price::from("0.000000001"), Price::from("0.123456789"), Price::from("0.999999999")], 9).unwrap()))]
1224    #[case::betfair("BETFAIR", TickScheme::Betfair)]
1225    #[case::crypto("CRYPTO_0_01", TickScheme::Crypto)]
1226    fn test_binary_option_tick_scheme_definition_restores_missing_scheme(
1227        #[case] name: &str,
1228        #[case] scheme: TickScheme,
1229    ) {
1230        if get_tick_scheme(name).is_none() {
1231            register_tick_scheme(name, scheme.clone()).unwrap();
1232        }
1233
1234        let mut option = nautilus_model::instruments::stubs::binary_option();
1235        option.tick_scheme = Some(Ustr::from(name));
1236        let metadata = option.metadata();
1237        let batch = BinaryOption::encode_batch(&metadata, &[option.clone()]).unwrap();
1238        let restored_name = format!("{name}_RESTORED");
1239        let mut columns = batch.columns().to_vec();
1240        columns[batch.schema().index_of("tick_scheme").unwrap()] =
1241            Arc::new(StringArray::from(vec![restored_name.as_str()]));
1242        let batch = RecordBatch::try_new(batch.schema(), columns).unwrap();
1243        assert_eq!(get_tick_scheme(&restored_name), None);
1244
1245        let decoded = binary_option::decode_binary_option_batch(&metadata, &batch).unwrap();
1246        let repeated = binary_option::decode_binary_option_batch(&metadata, &batch).unwrap();
1247        option.tick_scheme = Some(Ustr::from(restored_name.as_str()));
1248
1249        assert_eq!(
1250            serde_json::to_value(&decoded).unwrap(),
1251            serde_json::to_value([&option]).unwrap()
1252        );
1253        assert_eq!(
1254            serde_json::to_value(&repeated).unwrap(),
1255            serde_json::to_value([&option]).unwrap()
1256        );
1257        assert_eq!(get_tick_scheme(&restored_name), Some(scheme));
1258    }
1259
1260    #[rstest]
1261    #[case::missing_builtin(false, "BETFAIR")]
1262    #[case::null_builtin(true, "BETFAIR")]
1263    #[case::missing_custom(false, "BINARY_CODEC_LEGACY_REGISTERED_MISSING")]
1264    #[case::null_custom(true, "BINARY_CODEC_LEGACY_REGISTERED_NULL")]
1265    fn test_binary_option_tick_scheme_definition_legacy_default(
1266        #[case] null: bool,
1267        #[case] name: &str,
1268    ) {
1269        if get_tick_scheme(name).is_none() {
1270            let scheme = FixedTickScheme::new(Price::from("0.0020")).unwrap();
1271            register_tick_scheme(name, TickScheme::Fixed(scheme)).unwrap();
1272        }
1273
1274        let mut option = nautilus_model::instruments::stubs::binary_option();
1275        option.tick_scheme = Some(Ustr::from(name));
1276        let metadata = option.metadata();
1277        let batch = BinaryOption::encode_batch(&metadata, &[option.clone()]).unwrap();
1278        let batch = if null {
1279            batch_with_null_string_column(&batch, "tick_scheme_definition")
1280        } else {
1281            batch_without_column(&batch, "tick_scheme_definition")
1282        };
1283
1284        let decoded = binary_option::decode_binary_option_batch(&metadata, &batch).unwrap();
1285
1286        assert_eq!(
1287            serde_json::to_value(decoded).unwrap(),
1288            serde_json::to_value([option]).unwrap()
1289        );
1290    }
1291
1292    #[rstest]
1293    #[case::missing(false)]
1294    #[case::null(true)]
1295    fn test_binary_option_legacy_unregistered_tick_scheme_rejected(#[case] null: bool) {
1296        let option = nautilus_model::instruments::stubs::binary_option();
1297        let metadata = option.metadata();
1298        let batch = BinaryOption::encode_batch(&metadata, &[option]).unwrap();
1299        let batch = if null {
1300            batch_with_null_string_column(&batch, "tick_scheme_definition")
1301        } else {
1302            batch_without_column(&batch, "tick_scheme_definition")
1303        };
1304
1305        let name = "BINARY_CODEC_LEGACY_UNREGISTERED";
1306        let mut columns = batch.columns().to_vec();
1307        columns[batch.schema().index_of("tick_scheme").unwrap()] =
1308            Arc::new(StringArray::from(vec![name]));
1309        let batch = RecordBatch::try_new(batch.schema(), columns).unwrap();
1310        assert_eq!(get_tick_scheme(name), None);
1311
1312        let error = binary_option::decode_binary_option_batch(&metadata, &batch).unwrap_err();
1313
1314        assert!(
1315            matches!(&error, EncodingError::ParseError("instrument", detail) if detail == "row 0: invalid BinaryOption: tick_scheme not found in tick schemes"),
1316            "{error}"
1317        );
1318    }
1319
1320    #[rstest]
1321    fn test_binary_option_encoding_unregistered_tick_scheme_rejected() {
1322        let name = "BINARY_CODEC_ENCODING_UNREGISTERED";
1323        let mut option = nautilus_model::instruments::stubs::binary_option();
1324        option.tick_scheme = Some(Ustr::from(name));
1325        let metadata = option.metadata();
1326        assert_eq!(get_tick_scheme(name), None);
1327
1328        let error = BinaryOption::encode_batch(&metadata, &[option]).unwrap_err();
1329
1330        assert!(
1331            matches!(&error, ArrowError::InvalidArgumentError(detail) if detail == "Unknown tick scheme BINARY_CODEC_ENCODING_UNREGISTERED"),
1332            "{error}"
1333        );
1334    }
1335
1336    #[rstest]
1337    #[case::malformed(Some("BINARY_CODEC_BAD_JSON"), "{", "EOF while parsing")]
1338    #[case::no_name(None, r#"{"type":"crypto"}"#, "no tick scheme name")]
1339    #[case::conflict(Some("BETFAIR"), r#"{"type":"crypto"}"#, "conflicting definition")]
1340    #[case::invalid_ticks(
1341        Some("BINARY_CODEC_BAD_TICKS"),
1342        r#"{"type":"tiered","ticks":["0.02","0.01"],"precision":2}"#,
1343        "not greater"
1344    )]
1345    #[case::inexact(
1346        Some("BINARY_CODEC_INEXACT"),
1347        r#"{"type":"tiered","ticks":["0.001"],"precision":2}"#,
1348        "cannot be represented"
1349    )]
1350    fn test_binary_option_tick_scheme_definition_rejects_invalid_data(
1351        #[case] name: Option<&str>,
1352        #[case] json: &str,
1353        #[case] message: &str,
1354    ) {
1355        let option = nautilus_model::instruments::stubs::binary_option();
1356        let metadata = option.metadata();
1357        let batch = BinaryOption::encode_batch(&metadata, &[option]).unwrap();
1358        let mut columns = batch.columns().to_vec();
1359        columns[batch.schema().index_of("tick_scheme").unwrap()] =
1360            Arc::new(StringArray::from(vec![name]));
1361        columns[batch.schema().index_of("tick_scheme_definition").unwrap()] =
1362            Arc::new(StringArray::from(vec![json]));
1363        let batch = RecordBatch::try_new(batch.schema(), columns).unwrap();
1364
1365        let error = binary_option::decode_binary_option_batch(&metadata, &batch).unwrap_err();
1366
1367        assert!(
1368            matches!(&error, EncodingError::ParseError("tick_scheme_definition", detail) if detail.starts_with("row 0:") && detail.contains(message)),
1369            "{error}"
1370        );
1371    }
1372
1373    // The `betting` stub populates every bound, margin, and fee, so this covers the whole struct
1374    #[rstest]
1375    fn test_encode_decode_round_trip_betting_all_fields() {
1376        let instrument = betting();
1377
1378        let decoded = encode_decode_instrument(&InstrumentAny::Betting(instrument.clone()));
1379        let InstrumentAny::Betting(decoded) = decoded else {
1380            panic!("Decoded instrument type mismatch");
1381        };
1382
1383        assert_eq!(
1384            serde_json::to_value(&decoded).unwrap(),
1385            serde_json::to_value(&instrument).unwrap(),
1386        );
1387    }
1388
1389    fn encode_decode_instrument(instrument: &InstrumentAny) -> InstrumentAny {
1390        let metadata = instrument.metadata();
1391        let record_batch =
1392            InstrumentAny::encode_batch(&metadata, std::slice::from_ref(instrument)).unwrap();
1393        let mut decoded = decode_instrument_any_batch(&metadata, &record_batch).unwrap();
1394
1395        assert_eq!(decoded.len(), 1);
1396        decoded.remove(0)
1397    }
1398
1399    fn roundtrip_case(instrument: &InstrumentAny) {
1400        let metadata = instrument.metadata();
1401        let record_batch =
1402            InstrumentAny::encode_batch(&metadata, std::slice::from_ref(instrument)).unwrap();
1403        let decoded = decode_instrument_any_batch(&metadata, &record_batch).unwrap();
1404
1405        assert_eq!(decoded.len(), 1);
1406        assert_eq!(Instrument::id(&decoded[0]), Instrument::id(instrument));
1407        assert_eq!(
1408            Instrument::raw_symbol(&decoded[0]),
1409            Instrument::raw_symbol(instrument)
1410        );
1411        assert_eq!(
1412            Instrument::asset_class(&decoded[0]),
1413            Instrument::asset_class(instrument)
1414        );
1415        assert_eq!(
1416            Instrument::instrument_class(&decoded[0]),
1417            Instrument::instrument_class(instrument)
1418        );
1419        assert_eq!(
1420            Instrument::price_precision(&decoded[0]),
1421            Instrument::price_precision(instrument)
1422        );
1423        assert_eq!(
1424            Instrument::size_precision(&decoded[0]),
1425            Instrument::size_precision(instrument)
1426        );
1427        assert_eq!(
1428            Instrument::quote_currency(&decoded[0]),
1429            Instrument::quote_currency(instrument)
1430        );
1431        assert_eq!(
1432            std::mem::discriminant(&decoded[0]),
1433            std::mem::discriminant(instrument),
1434            "decoded variant must match encoded variant"
1435        );
1436    }
1437
1438    fn batch_without_column(record_batch: &RecordBatch, column_name: &str) -> RecordBatch {
1439        let schema = record_batch.schema();
1440        let column_index = schema.index_of(column_name).unwrap();
1441        let fields: Vec<_> = schema
1442            .fields()
1443            .iter()
1444            .enumerate()
1445            .filter(|(index, _)| *index != column_index)
1446            .map(|(_, field)| field.as_ref().clone())
1447            .collect();
1448        let columns = record_batch
1449            .columns()
1450            .iter()
1451            .enumerate()
1452            .filter(|(index, _)| *index != column_index)
1453            .map(|(_, column)| Arc::clone(column))
1454            .collect();
1455        let new_schema = Schema::new_with_metadata(fields, schema.metadata().clone());
1456
1457        RecordBatch::try_new(Arc::new(new_schema), columns).unwrap()
1458    }
1459
1460    fn string_column_value<'a>(
1461        record_batch: &'a RecordBatch,
1462        column_name: &str,
1463    ) -> Option<&'a str> {
1464        let values = record_batch
1465            .column_by_name(column_name)
1466            .unwrap()
1467            .as_any()
1468            .downcast_ref::<StringArray>()
1469            .unwrap();
1470
1471        (!values.is_null(0)).then(|| values.value(0))
1472    }
1473
1474    fn batch_with_null_string_column(record_batch: &RecordBatch, column_name: &str) -> RecordBatch {
1475        let schema = record_batch.schema();
1476        let column_index = schema.index_of(column_name).unwrap();
1477        let mut columns = record_batch.columns().to_vec();
1478        let null_column: ArrayRef = Arc::new(StringArray::from(vec![None::<&str>]));
1479        columns[column_index] = null_column;
1480
1481        RecordBatch::try_new(schema, columns).unwrap()
1482    }
1483
1484    fn batch_with_uint8_column(
1485        record_batch: &RecordBatch,
1486        column_name: &str,
1487        values: Vec<u8>,
1488    ) -> RecordBatch {
1489        let schema = record_batch.schema();
1490        let column_index = schema.index_of(column_name).unwrap();
1491        let mut columns = record_batch.columns().to_vec();
1492        columns[column_index] = Arc::new(UInt8Array::from(values));
1493
1494        RecordBatch::try_new(schema, columns).unwrap()
1495    }
1496
1497    fn batch_with_null_uint8_column(record_batch: &RecordBatch, column_name: &str) -> RecordBatch {
1498        let schema = record_batch.schema();
1499        let column_index = schema.index_of(column_name).unwrap();
1500        let fields = schema
1501            .fields()
1502            .iter()
1503            .enumerate()
1504            .map(|(index, field)| {
1505                if index == column_index {
1506                    field.as_ref().clone().with_nullable(true)
1507                } else {
1508                    field.as_ref().clone()
1509                }
1510            })
1511            .collect::<Vec<_>>();
1512
1513        let mut columns = record_batch.columns().to_vec();
1514        columns[column_index] = Arc::new(UInt8Array::from(vec![None]));
1515        let schema = Schema::new_with_metadata(fields, schema.metadata().clone());
1516
1517        RecordBatch::try_new(Arc::new(schema), columns).unwrap()
1518    }
1519
1520    #[rstest]
1521    fn test_public_instrument_decoders_reject_null_required_columns() {
1522        let instruments = vec![
1523            InstrumentAny::Betting(nautilus_model::instruments::stubs::betting()),
1524            InstrumentAny::BinaryOption(nautilus_model::instruments::stubs::binary_option()),
1525            InstrumentAny::Cfd(nautilus_model::instruments::stubs::cfd_gold()),
1526            InstrumentAny::Commodity(nautilus_model::instruments::stubs::commodity_gold()),
1527            InstrumentAny::CryptoFuture(nautilus_model::instruments::stubs::crypto_future_btcusdt(
1528                2,
1529                6,
1530                Price::from("0.01"),
1531                Quantity::from("0.000001"),
1532            )),
1533            InstrumentAny::CryptoFuturesSpread(
1534                nautilus_model::instruments::stubs::crypto_futures_spread_btc_deribit(),
1535            ),
1536            InstrumentAny::CryptoOption(
1537                nautilus_model::instruments::stubs::crypto_option_btc_deribit(
1538                    3,
1539                    1,
1540                    Price::from("0.001"),
1541                    Quantity::from("0.1"),
1542                ),
1543            ),
1544            InstrumentAny::CryptoOptionSpread(
1545                nautilus_model::instruments::stubs::crypto_option_spread_btc_deribit(),
1546            ),
1547            InstrumentAny::CryptoPerpetual(
1548                nautilus_model::instruments::stubs::crypto_perpetual_ethusdt(),
1549            ),
1550            InstrumentAny::CurrencyPair(nautilus_model::instruments::stubs::currency_pair_btcusdt()),
1551            InstrumentAny::Equity(nautilus_model::instruments::stubs::equity_aapl()),
1552            InstrumentAny::FuturesContract(
1553                nautilus_model::instruments::stubs::futures_contract_es(None, None),
1554            ),
1555            InstrumentAny::FuturesSpread(nautilus_model::instruments::stubs::futures_spread_es()),
1556            InstrumentAny::IndexInstrument(
1557                nautilus_model::instruments::stubs::index_instrument_spx(),
1558            ),
1559            InstrumentAny::OptionContract(
1560                nautilus_model::instruments::stubs::option_contract_appl(),
1561            ),
1562            InstrumentAny::OptionSpread(nautilus_model::instruments::stubs::option_spread()),
1563            InstrumentAny::PerpetualContract(
1564                nautilus_model::instruments::stubs::perpetual_contract_eurusd(),
1565            ),
1566            InstrumentAny::TokenizedAsset(
1567                nautilus_model::instruments::stubs::tokenized_asset_aaplx(),
1568            ),
1569        ];
1570
1571        for instrument in instruments {
1572            let metadata = instrument.metadata();
1573            let record_batch =
1574                InstrumentAny::encode_batch(&metadata, std::slice::from_ref(&instrument)).unwrap();
1575            let record_batch = batch_with_null_uint8_column(&record_batch, "price_precision");
1576
1577            let result = decode_instrument_any_batch(&metadata, &record_batch);
1578
1579            assert!(matches!(
1580                result,
1581                Err(EncodingError::ParseError(INSTRUMENT_VALIDATION_FIELD, ref message))
1582                    if message == "required field 'price_precision' is null at row 0"
1583            ));
1584        }
1585    }
1586
1587    #[rstest]
1588    #[case::binary_option(InstrumentAny::BinaryOption(
1589        nautilus_model::instruments::stubs::binary_option()
1590    ))]
1591    #[case::cfd(InstrumentAny::Cfd(nautilus_model::instruments::stubs::cfd_gold()))]
1592    #[case::commodity(InstrumentAny::Commodity(
1593        nautilus_model::instruments::stubs::commodity_gold()
1594    ))]
1595    #[case::crypto_future(InstrumentAny::CryptoFuture(
1596        nautilus_model::instruments::stubs::crypto_future_btcusdt(
1597            2,
1598            6,
1599            Price::from("0.01"),
1600            Quantity::from("0.000001"),
1601        )
1602    ))]
1603    #[case::crypto_futures_spread(InstrumentAny::CryptoFuturesSpread(
1604        nautilus_model::instruments::stubs::crypto_futures_spread_btc_deribit()
1605    ))]
1606    #[case::crypto_option(InstrumentAny::CryptoOption(
1607        nautilus_model::instruments::stubs::crypto_option_btc_deribit(
1608            3,
1609            1,
1610            Price::from("0.001"),
1611            Quantity::from("0.1"),
1612        )
1613    ))]
1614    #[case::crypto_option_spread(InstrumentAny::CryptoOptionSpread(
1615        nautilus_model::instruments::stubs::crypto_option_spread_btc_deribit()
1616    ))]
1617    #[case::crypto_perpetual(InstrumentAny::CryptoPerpetual(
1618        nautilus_model::instruments::stubs::crypto_perpetual_ethusdt()
1619    ))]
1620    #[case::currency_pair(InstrumentAny::CurrencyPair(
1621        nautilus_model::instruments::stubs::currency_pair_btcusdt()
1622    ))]
1623    #[case::equity(InstrumentAny::Equity(nautilus_model::instruments::stubs::equity_aapl()))]
1624    #[case::futures_contract(InstrumentAny::FuturesContract(
1625        nautilus_model::instruments::stubs::futures_contract_es(None, None,)
1626    ))]
1627    #[case::futures_spread(InstrumentAny::FuturesSpread(
1628        nautilus_model::instruments::stubs::futures_spread_es()
1629    ))]
1630    #[case::index_instrument(InstrumentAny::IndexInstrument(
1631        nautilus_model::instruments::stubs::index_instrument_spx()
1632    ))]
1633    #[case::option_contract(InstrumentAny::OptionContract(
1634        nautilus_model::instruments::stubs::option_contract_appl()
1635    ))]
1636    #[case::option_spread(InstrumentAny::OptionSpread(
1637        nautilus_model::instruments::stubs::option_spread()
1638    ))]
1639    #[case::perpetual_contract(InstrumentAny::PerpetualContract(
1640        nautilus_model::instruments::stubs::perpetual_contract_eurusd()
1641    ))]
1642    #[case::tokenized_asset(InstrumentAny::TokenizedAsset(
1643        nautilus_model::instruments::stubs::tokenized_asset_aaplx()
1644    ))]
1645    fn test_decode_instrument_checked_constructor_error(#[case] instrument: InstrumentAny) {
1646        let metadata = instrument.metadata();
1647        let class = metadata.get(KEY_TYPE_NAME).unwrap();
1648        let first_row_price_precision = Instrument::price_precision(&instrument);
1649        let instruments = vec![instrument.clone(), instrument];
1650        let record_batch = InstrumentAny::encode_batch(&metadata, &instruments).unwrap();
1651        let record_batch = batch_with_uint8_column(
1652            &record_batch,
1653            "price_precision",
1654            vec![first_row_price_precision, u8::MAX],
1655        );
1656
1657        let error = decode_instrument_any_batch(&metadata, &record_batch)
1658            .expect_err("invalid precision must return EncodingError");
1659
1660        match error {
1661            EncodingError::ParseError(field, message) => {
1662                assert_eq!(field, INSTRUMENT_VALIDATION_FIELD);
1663                assert!(
1664                    message.contains(class),
1665                    "message should include instrument class, found: {message}",
1666                );
1667                assert!(
1668                    message.starts_with("row 1:"),
1669                    "message should include row index, found: {message}",
1670                );
1671                assert!(
1672                    message.contains("price_precision"),
1673                    "message should include failed precision, found: {message}",
1674                );
1675            }
1676            other => panic!("unexpected error variant: {other:?}"),
1677        }
1678    }
1679
1680    #[rstest]
1681    fn test_roundtrip_betting() {
1682        use nautilus_model::instruments::stubs::betting;
1683        roundtrip_case(&InstrumentAny::Betting(betting()));
1684    }
1685
1686    #[rstest]
1687    fn test_roundtrip_binary_option() {
1688        use nautilus_model::instruments::stubs::binary_option;
1689        roundtrip_case(&InstrumentAny::BinaryOption(binary_option()));
1690    }
1691
1692    #[rstest]
1693    fn test_roundtrip_cfd() {
1694        use nautilus_model::instruments::stubs::cfd_gold;
1695        roundtrip_case(&InstrumentAny::Cfd(cfd_gold()));
1696    }
1697
1698    #[rstest]
1699    fn test_roundtrip_commodity() {
1700        use nautilus_model::instruments::stubs::commodity_gold;
1701        roundtrip_case(&InstrumentAny::Commodity(commodity_gold()));
1702    }
1703
1704    #[rstest]
1705    fn test_roundtrip_crypto_future() {
1706        use nautilus_model::instruments::stubs::crypto_future_btcusdt;
1707
1708        let mut inst = crypto_future_btcusdt(2, 6, Price::from("0.01"), Quantity::from("0.000001"));
1709        inst.lot_size = Quantity::from("0.25");
1710        let any = InstrumentAny::CryptoFuture(inst.clone());
1711        roundtrip_case(&any);
1712        let metadata = any.metadata();
1713        let batch = InstrumentAny::encode_batch(&metadata, std::slice::from_ref(&any)).unwrap();
1714        let decoded = decode_instrument_any_batch(&metadata, &batch).unwrap();
1715        let InstrumentAny::CryptoFuture(decoded_inst) = &decoded[0] else {
1716            panic!("decoded variant is not CryptoFuture");
1717        };
1718        assert_eq!(decoded_inst.lot_size, inst.lot_size);
1719    }
1720
1721    #[rstest]
1722    fn test_decode_crypto_future_without_lot_size_column_defaults_to_one() {
1723        use nautilus_model::instruments::stubs::crypto_future_btcusdt;
1724
1725        let inst = crypto_future_btcusdt(2, 6, Price::from("0.01"), Quantity::from("0.000001"));
1726        let any = InstrumentAny::CryptoFuture(inst);
1727        let metadata = any.metadata();
1728        let batch = InstrumentAny::encode_batch(&metadata, std::slice::from_ref(&any)).unwrap();
1729        let batch = batch_without_column(&batch, "lot_size");
1730
1731        let decoded = decode_instrument_any_batch(&metadata, &batch).unwrap();
1732
1733        let InstrumentAny::CryptoFuture(decoded_inst) = &decoded[0] else {
1734            panic!("decoded variant is not CryptoFuture");
1735        };
1736        assert_eq!(decoded_inst.lot_size, Quantity::from(1));
1737    }
1738
1739    #[rstest]
1740    fn test_decode_crypto_future_null_lot_size_defaults_to_one() {
1741        use nautilus_model::instruments::stubs::crypto_future_btcusdt;
1742
1743        let inst = crypto_future_btcusdt(2, 6, Price::from("0.01"), Quantity::from("0.000001"));
1744        let any = InstrumentAny::CryptoFuture(inst);
1745        let metadata = any.metadata();
1746        let batch = InstrumentAny::encode_batch(&metadata, std::slice::from_ref(&any)).unwrap();
1747        let batch = batch_with_null_string_column(&batch, "lot_size");
1748
1749        let decoded = decode_instrument_any_batch(&metadata, &batch).unwrap();
1750
1751        let InstrumentAny::CryptoFuture(decoded_inst) = &decoded[0] else {
1752            panic!("decoded variant is not CryptoFuture");
1753        };
1754        assert_eq!(decoded_inst.lot_size, Quantity::from(1));
1755    }
1756
1757    #[rstest]
1758    fn test_roundtrip_crypto_option() {
1759        use nautilus_model::instruments::stubs::crypto_option_btc_deribit;
1760
1761        let mut inst = crypto_option_btc_deribit(3, 1, Price::from("0.001"), Quantity::from("0.1"));
1762        inst.lot_size = Quantity::from("0.5");
1763        let any = InstrumentAny::CryptoOption(inst.clone());
1764        roundtrip_case(&any);
1765        let metadata = any.metadata();
1766        let batch = InstrumentAny::encode_batch(&metadata, std::slice::from_ref(&any)).unwrap();
1767        let decoded = decode_instrument_any_batch(&metadata, &batch).unwrap();
1768        let InstrumentAny::CryptoOption(decoded_inst) = &decoded[0] else {
1769            panic!("decoded variant is not CryptoOption");
1770        };
1771        assert_eq!(decoded_inst.lot_size, inst.lot_size);
1772    }
1773
1774    #[rstest]
1775    fn test_decode_crypto_option_without_lot_size_column_defaults_to_one() {
1776        use nautilus_model::instruments::stubs::crypto_option_btc_deribit;
1777
1778        let inst = crypto_option_btc_deribit(3, 1, Price::from("0.001"), Quantity::from("0.1"));
1779        let any = InstrumentAny::CryptoOption(inst);
1780        let metadata = any.metadata();
1781        let batch = InstrumentAny::encode_batch(&metadata, std::slice::from_ref(&any)).unwrap();
1782        let batch = batch_without_column(&batch, "lot_size");
1783
1784        let decoded = decode_instrument_any_batch(&metadata, &batch).unwrap();
1785
1786        let InstrumentAny::CryptoOption(decoded_inst) = &decoded[0] else {
1787            panic!("decoded variant is not CryptoOption");
1788        };
1789        assert_eq!(decoded_inst.lot_size, Quantity::from(1));
1790    }
1791
1792    #[rstest]
1793    fn test_decode_crypto_option_null_lot_size_defaults_to_one() {
1794        use nautilus_model::instruments::stubs::crypto_option_btc_deribit;
1795
1796        let inst = crypto_option_btc_deribit(3, 1, Price::from("0.001"), Quantity::from("0.1"));
1797        let any = InstrumentAny::CryptoOption(inst);
1798        let metadata = any.metadata();
1799        let batch = InstrumentAny::encode_batch(&metadata, std::slice::from_ref(&any)).unwrap();
1800        let batch = batch_with_null_string_column(&batch, "lot_size");
1801
1802        let decoded = decode_instrument_any_batch(&metadata, &batch).unwrap();
1803
1804        let InstrumentAny::CryptoOption(decoded_inst) = &decoded[0] else {
1805            panic!("decoded variant is not CryptoOption");
1806        };
1807        assert_eq!(decoded_inst.lot_size, Quantity::from(1));
1808    }
1809
1810    #[rstest]
1811    fn test_roundtrip_crypto_futures_spread() {
1812        use nautilus_model::instruments::{Instrument, stubs::crypto_futures_spread_btc_deribit};
1813        let inst = crypto_futures_spread_btc_deribit();
1814        let any = InstrumentAny::CryptoFuturesSpread(inst.clone());
1815        roundtrip_case(&any);
1816        let metadata = any.metadata();
1817        let batch = InstrumentAny::encode_batch(&metadata, std::slice::from_ref(&any)).unwrap();
1818        let decoded = decode_instrument_any_batch(&metadata, &batch).unwrap();
1819        let InstrumentAny::CryptoFuturesSpread(decoded_inst) = &decoded[0] else {
1820            panic!("decoded variant is not CryptoFuturesSpread");
1821        };
1822        assert_eq!(decoded_inst.lot_size, inst.lot_size);
1823        assert_eq!(decoded_inst.is_inverse, inst.is_inverse);
1824        assert_eq!(decoded_inst.strategy_type, inst.strategy_type);
1825        assert_eq!(decoded_inst.settlement_currency, inst.settlement_currency);
1826        assert_eq!(Instrument::id(decoded_inst), Instrument::id(&inst));
1827    }
1828
1829    #[rstest]
1830    fn test_roundtrip_crypto_option_spread() {
1831        use nautilus_model::instruments::{Instrument, stubs::crypto_option_spread_btc_deribit};
1832        let inst = crypto_option_spread_btc_deribit();
1833        let any = InstrumentAny::CryptoOptionSpread(inst.clone());
1834        roundtrip_case(&any);
1835        let metadata = any.metadata();
1836        let batch = InstrumentAny::encode_batch(&metadata, std::slice::from_ref(&any)).unwrap();
1837        let decoded = decode_instrument_any_batch(&metadata, &batch).unwrap();
1838        let InstrumentAny::CryptoOptionSpread(decoded_inst) = &decoded[0] else {
1839            panic!("decoded variant is not CryptoOptionSpread");
1840        };
1841        // Deribit BTC option combos carry min_trade_amount=0.1, which sets
1842        // lot_size=0.1; dropping the lot_size Arrow column would silently
1843        // default it back to 1
1844        assert_eq!(decoded_inst.lot_size, inst.lot_size);
1845        assert_eq!(decoded_inst.size_precision, inst.size_precision);
1846        assert_eq!(decoded_inst.size_increment, inst.size_increment);
1847        assert_eq!(decoded_inst.is_inverse, inst.is_inverse);
1848        assert_eq!(decoded_inst.strategy_type, inst.strategy_type);
1849        assert_eq!(decoded_inst.settlement_currency, inst.settlement_currency);
1850        assert_eq!(Instrument::id(decoded_inst), Instrument::id(&inst));
1851    }
1852
1853    #[rstest]
1854    fn test_roundtrip_crypto_perpetual_inverse() {
1855        use nautilus_model::instruments::stubs::btcusd_bybit;
1856        roundtrip_case(&InstrumentAny::CryptoPerpetual(btcusd_bybit()));
1857    }
1858
1859    #[rstest]
1860    fn test_roundtrip_crypto_perpetual_linear() {
1861        use nautilus_model::instruments::stubs::crypto_perpetual_ethusdt;
1862
1863        let mut inst = crypto_perpetual_ethusdt();
1864        inst.lot_size = Quantity::from("0.005");
1865        let any = InstrumentAny::CryptoPerpetual(inst.clone());
1866        roundtrip_case(&any);
1867        let metadata = any.metadata();
1868        let batch = InstrumentAny::encode_batch(&metadata, std::slice::from_ref(&any)).unwrap();
1869        let decoded = decode_instrument_any_batch(&metadata, &batch).unwrap();
1870        let InstrumentAny::CryptoPerpetual(decoded_inst) = &decoded[0] else {
1871            panic!("decoded variant is not CryptoPerpetual");
1872        };
1873        assert_eq!(decoded_inst.lot_size, inst.lot_size);
1874    }
1875
1876    #[rstest]
1877    fn test_decode_crypto_perpetual_without_lot_size_column_defaults_to_one() {
1878        use nautilus_model::instruments::stubs::crypto_perpetual_ethusdt;
1879
1880        let inst = crypto_perpetual_ethusdt();
1881        let any = InstrumentAny::CryptoPerpetual(inst);
1882        let metadata = any.metadata();
1883        let batch = InstrumentAny::encode_batch(&metadata, std::slice::from_ref(&any)).unwrap();
1884        let batch = batch_without_column(&batch, "lot_size");
1885
1886        let decoded = decode_instrument_any_batch(&metadata, &batch).unwrap();
1887
1888        let InstrumentAny::CryptoPerpetual(decoded_inst) = &decoded[0] else {
1889            panic!("decoded variant is not CryptoPerpetual");
1890        };
1891        assert_eq!(decoded_inst.lot_size, Quantity::from(1));
1892    }
1893
1894    #[rstest]
1895    fn test_decode_crypto_perpetual_null_lot_size_defaults_to_one() {
1896        use nautilus_model::instruments::stubs::crypto_perpetual_ethusdt;
1897
1898        let inst = crypto_perpetual_ethusdt();
1899        let any = InstrumentAny::CryptoPerpetual(inst);
1900        let metadata = any.metadata();
1901        let batch = InstrumentAny::encode_batch(&metadata, std::slice::from_ref(&any)).unwrap();
1902        let batch = batch_with_null_string_column(&batch, "lot_size");
1903
1904        let decoded = decode_instrument_any_batch(&metadata, &batch).unwrap();
1905
1906        let InstrumentAny::CryptoPerpetual(decoded_inst) = &decoded[0] else {
1907            panic!("decoded variant is not CryptoPerpetual");
1908        };
1909        assert_eq!(decoded_inst.lot_size, Quantity::from(1));
1910    }
1911
1912    #[rstest]
1913    fn test_roundtrip_futures_contract() {
1914        use nautilus_model::instruments::stubs::futures_contract_es;
1915        roundtrip_case(&InstrumentAny::FuturesContract(futures_contract_es(
1916            None, None,
1917        )));
1918    }
1919
1920    #[rstest]
1921    fn test_roundtrip_futures_spread() {
1922        use nautilus_model::instruments::stubs::futures_spread_es;
1923        roundtrip_case(&InstrumentAny::FuturesSpread(futures_spread_es()));
1924    }
1925
1926    #[rstest]
1927    fn test_roundtrip_index_instrument() {
1928        use nautilus_model::instruments::stubs::index_instrument_spx;
1929        roundtrip_case(&InstrumentAny::IndexInstrument(index_instrument_spx()));
1930    }
1931
1932    #[rstest]
1933    #[case::option_contract(InstrumentAny::OptionContract(
1934        nautilus_model::instruments::stubs::option_contract_appl()
1935    ))]
1936    #[case::crypto_option(InstrumentAny::CryptoOption(crypto_option_btc_deribit(
1937        3,
1938        1,
1939        Price::from("0.001"),
1940        Quantity::from("0.1")
1941    )))]
1942    fn test_option_terms_round_trip(#[case] instrument: InstrumentAny) {
1943        let (underlying_id, kind) = match &instrument {
1944            InstrumentAny::OptionContract(_) => ("AAPL.NASDAQ", "CALL"),
1945            InstrumentAny::CryptoOption(_) => ("BTCUSDT.BINANCE", "PUT"),
1946            _ => unreachable!("option fixtures only"),
1947        };
1948
1949        for (known, style, settlement) in [
1950            (true, Some("AMERICAN"), Some("CASH")),
1951            (true, Some("EUROPEAN"), Some("PHYSICAL")),
1952            (false, Some("BERMUDAN"), Some("CASH")),
1953            (true, Some("EUROPEAN"), None),
1954            (true, None, Some("PHYSICAL")),
1955            (false, None, None),
1956        ] {
1957            let mut encoded = serde_json::to_value(&instrument).unwrap();
1958            let fields = encoded
1959                .as_object_mut()
1960                .unwrap()
1961                .values_mut()
1962                .next()
1963                .unwrap();
1964            fields["underlying_instrument_id"] =
1965                serde_json::to_value(known.then_some(underlying_id)).unwrap();
1966            fields["exercise_style"] = serde_json::to_value(style).unwrap();
1967            fields["settlement_type"] = serde_json::to_value(settlement).unwrap();
1968            let instrument: InstrumentAny = serde_json::from_value(encoded.clone()).unwrap();
1969            let metadata = instrument.metadata();
1970            let batch =
1971                InstrumentAny::encode_batch(&metadata, std::slice::from_ref(&instrument)).unwrap();
1972            let restored = decode_instrument_any_batch(&metadata, &batch).unwrap();
1973            assert_eq!(serde_json::to_value(&restored[0]).unwrap(), encoded);
1974            assert_eq!(string_column_value(&batch, "option_kind"), Some(kind));
1975            assert_eq!(string_column_value(&batch, "exercise_style"), style);
1976
1977            let legacy = batch_without_column(&batch, "underlying_instrument_id");
1978            let legacy = batch_without_column(&legacy, "exercise_style");
1979            let legacy = batch_without_column(&legacy, "settlement_type");
1980            let decoded = decode_instrument_any_batch(&metadata, &legacy).unwrap();
1981            let restored = serde_json::to_value(&decoded[0]).unwrap();
1982            let fields = restored.as_object().unwrap().values().next().unwrap();
1983            assert_eq!(fields["underlying_instrument_id"], serde_json::Value::Null);
1984            assert_eq!(fields["exercise_style"], serde_json::Value::Null);
1985            assert_eq!(fields["settlement_type"], serde_json::Value::Null);
1986        }
1987    }
1988
1989    #[rstest]
1990    #[case::option_contract(InstrumentAny::OptionContract(
1991        nautilus_model::instruments::stubs::option_contract_appl()
1992    ))]
1993    #[case::crypto_option(InstrumentAny::CryptoOption(crypto_option_btc_deribit(
1994        3,
1995        1,
1996        Price::from("0.001"),
1997        Quantity::from("0.1")
1998    )))]
1999    fn test_invalid_option_terms_return_field_error(
2000        #[case] instrument: InstrumentAny,
2001        #[values("underlying_instrument_id", "exercise_style", "settlement_type")]
2002        field: &'static str,
2003    ) {
2004        let metadata = instrument.metadata();
2005        let batch = InstrumentAny::encode_batch(&metadata, &[instrument]).unwrap();
2006        let schema = batch.schema();
2007        let index = schema.index_of(field).unwrap();
2008        let mut columns = batch.columns().to_vec();
2009        columns[index] = Arc::new(StringArray::from(vec!["INVALID"]));
2010        let invalid = RecordBatch::try_new(schema, columns).unwrap();
2011        let error = decode_instrument_any_batch(&metadata, &invalid).unwrap_err();
2012
2013        let EncodingError::ParseError(actual_field, detail) = error else {
2014            panic!("expected field parse error, was {error:?}");
2015        };
2016
2017        assert_eq!(actual_field, field);
2018        assert!(detail.starts_with("row 0: "));
2019    }
2020
2021    #[rstest]
2022    fn test_roundtrip_option_contract() {
2023        use nautilus_model::instruments::stubs::option_contract_appl;
2024        roundtrip_case(&InstrumentAny::OptionContract(option_contract_appl()));
2025    }
2026
2027    #[rstest]
2028    fn test_roundtrip_option_spread() {
2029        use nautilus_model::instruments::stubs::option_spread;
2030        roundtrip_case(&InstrumentAny::OptionSpread(option_spread()));
2031    }
2032
2033    #[rstest]
2034    fn test_roundtrip_perpetual_contract() {
2035        use nautilus_model::instruments::stubs::perpetual_contract_eurusd;
2036        roundtrip_case(&InstrumentAny::PerpetualContract(
2037            perpetual_contract_eurusd(),
2038        ));
2039    }
2040
2041    #[rstest]
2042    fn test_roundtrip_tokenized_asset() {
2043        use nautilus_model::instruments::stubs::tokenized_asset_aaplx;
2044        roundtrip_case(&InstrumentAny::TokenizedAsset(tokenized_asset_aaplx()));
2045    }
2046}