nautilus_model/identifiers/
instrument_id.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2025 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//! Represents a valid instrument ID.
17
18use std::{
19    fmt::{Debug, Display, Formatter},
20    hash::Hash,
21    str::FromStr,
22};
23
24use nautilus_core::correctness::check_valid_string;
25use serde::{Deserialize, Deserializer, Serialize};
26
27#[cfg(feature = "defi")]
28use crate::defi::{Blockchain, validation::validate_address};
29use crate::identifiers::{Symbol, Venue};
30
31/// Represents a valid instrument ID.
32///
33/// The symbol and venue combination should uniquely identify the instrument.
34#[repr(C)]
35#[derive(Clone, Copy, Hash, PartialEq, Eq, PartialOrd, Ord, Default)]
36#[cfg_attr(
37    feature = "python",
38    pyo3::pyclass(module = "nautilus_trader.core.nautilus_pyo3.model")
39)]
40pub struct InstrumentId {
41    /// The instruments ticker symbol.
42    pub symbol: Symbol,
43    /// The instruments trading venue.
44    pub venue: Venue,
45}
46
47impl InstrumentId {
48    /// Creates a new [`InstrumentId`] instance.
49    #[must_use]
50    pub fn new(symbol: Symbol, venue: Venue) -> Self {
51        Self { symbol, venue }
52    }
53
54    #[must_use]
55    pub fn is_synthetic(&self) -> bool {
56        self.venue.is_synthetic()
57    }
58}
59
60impl InstrumentId {
61    /// # Errors
62    ///
63    /// Returns an error if parsing the string fails or string is invalid.
64    pub fn from_as_ref<T: AsRef<str>>(value: T) -> anyhow::Result<Self> {
65        Self::from_str(value.as_ref())
66    }
67
68    /// Extracts the blockchain from the venue if it's a DEX venue.
69    #[cfg(feature = "defi")]
70    #[must_use]
71    pub fn blockchain(&self) -> Option<Blockchain> {
72        self.venue
73            .parse_dex()
74            .map(|(blockchain, _)| blockchain)
75            .ok()
76    }
77}
78
79impl FromStr for InstrumentId {
80    type Err = anyhow::Error;
81
82    fn from_str(s: &str) -> anyhow::Result<Self> {
83        match s.rsplit_once('.') {
84            Some((symbol_part, venue_part)) => {
85                check_valid_string(symbol_part, stringify!(value))?;
86                check_valid_string(venue_part, stringify!(value))?;
87
88                let venue = Venue::new_checked(venue_part)?;
89
90                let symbol = {
91                    #[cfg(feature = "defi")]
92                    if venue.is_dex() {
93                        let validated_address = validate_address(symbol_part)
94                            .map_err(|e| anyhow::anyhow!(err_message(s, e.to_string())))?;
95                        Symbol::new(validated_address.to_string())
96                    } else {
97                        Symbol::new(symbol_part)
98                    }
99
100                    #[cfg(not(feature = "defi"))]
101                    Symbol::new(symbol_part)
102                };
103
104                Ok(Self { symbol, venue })
105            }
106            None => {
107                anyhow::bail!(err_message(
108                    s,
109                    "missing '.' separator between symbol and venue components".to_string()
110                ))
111            }
112        }
113    }
114}
115
116impl From<&str> for InstrumentId {
117    /// Creates a [`InstrumentId`] from a string slice.
118    ///
119    /// # Panics
120    ///
121    /// Panics if the `value` string is not valid.
122    fn from(value: &str) -> Self {
123        Self::from_str(value).unwrap()
124    }
125}
126
127impl From<String> for InstrumentId {
128    /// Creates a [`InstrumentId`] from a string.
129    ///
130    /// # Panics
131    ///
132    /// Panics if the `value` string is not valid.
133    fn from(value: String) -> Self {
134        Self::from(value.as_str())
135    }
136}
137
138impl Debug for InstrumentId {
139    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
140        write!(f, "\"{}.{}\"", self.symbol, self.venue)
141    }
142}
143
144impl Display for InstrumentId {
145    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
146        write!(f, "{}.{}", self.symbol, self.venue)
147    }
148}
149
150impl Serialize for InstrumentId {
151    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
152    where
153        S: serde::Serializer,
154    {
155        serializer.serialize_str(&self.to_string())
156    }
157}
158
159impl<'de> Deserialize<'de> for InstrumentId {
160    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
161    where
162        D: Deserializer<'de>,
163    {
164        let instrument_id_str = String::deserialize(deserializer)?;
165        Ok(Self::from(instrument_id_str.as_str()))
166    }
167}
168
169fn err_message(s: &str, e: String) -> String {
170    format!("Error parsing `InstrumentId` from '{s}': {e}")
171}
172
173////////////////////////////////////////////////////////////////////////////////
174// Tests
175////////////////////////////////////////////////////////////////////////////////
176#[cfg(test)]
177mod tests {
178
179    use rstest::rstest;
180
181    use super::InstrumentId;
182    use crate::identifiers::stubs::*;
183
184    #[rstest]
185    fn test_instrument_id_parse_success(instrument_id_eth_usdt_binance: InstrumentId) {
186        assert_eq!(instrument_id_eth_usdt_binance.symbol.to_string(), "ETHUSDT");
187        assert_eq!(instrument_id_eth_usdt_binance.venue.to_string(), "BINANCE");
188    }
189
190    #[rstest]
191    #[should_panic(
192        expected = "Error parsing `InstrumentId` from 'ETHUSDT-BINANCE': missing '.' separator between symbol and venue components"
193    )]
194    fn test_instrument_id_parse_failure_no_dot() {
195        let _ = InstrumentId::from("ETHUSDT-BINANCE");
196    }
197
198    #[rstest]
199    fn test_string_reprs() {
200        let id = InstrumentId::from("ETH/USDT.BINANCE");
201        assert_eq!(id.to_string(), "ETH/USDT.BINANCE");
202        assert_eq!(format!("{id}"), "ETH/USDT.BINANCE");
203    }
204
205    #[cfg(feature = "defi")]
206    #[rstest]
207    fn test_blockchain_instrument_id_valid() {
208        let id =
209            InstrumentId::from("0xC31E54c7a869B9FcBEcc14363CF510d1c41fa443.Arbitrum:UniswapV3");
210        assert_eq!(
211            id.symbol.to_string(),
212            "0xC31E54c7a869B9FcBEcc14363CF510d1c41fa443"
213        );
214        assert_eq!(id.venue.to_string(), "Arbitrum:UniswapV3");
215    }
216
217    #[cfg(feature = "defi")]
218    #[rstest]
219    #[should_panic(
220        expected = "Error creating `Venue` from 'InvalidChain:UniswapV3': invalid blockchain venue 'InvalidChain:UniswapV3': chain 'InvalidChain' not recognized"
221    )]
222    fn test_blockchain_instrument_id_invalid_chain() {
223        let _ =
224            InstrumentId::from("0xC31E54c7a869B9FcBEcc14363CF510d1c41fa443.InvalidChain:UniswapV3");
225    }
226
227    #[cfg(feature = "defi")]
228    #[rstest]
229    #[should_panic(
230        expected = "Error creating `Venue` from 'Arbitrum:': invalid blockchain venue 'Arbitrum:': expected format 'Chain:DexId'"
231    )]
232    fn test_blockchain_instrument_id_empty_dex() {
233        let _ = InstrumentId::from("0xC31E54c7a869B9FcBEcc14363CF510d1c41fa443.Arbitrum:");
234    }
235
236    #[cfg(feature = "defi")]
237    #[rstest]
238    fn test_regular_venue_with_blockchain_like_name_but_without_dex() {
239        // Should work fine since it doesn't contain ':' (not a DEX venue)
240        let id = InstrumentId::from("0xC31E54c7a869B9FcBEcc14363CF510d1c41fa443.Ethereum");
241        assert_eq!(
242            id.symbol.to_string(),
243            "0xC31E54c7a869B9FcBEcc14363CF510d1c41fa443"
244        );
245        assert_eq!(id.venue.to_string(), "Ethereum");
246    }
247
248    #[cfg(feature = "defi")]
249    #[rstest]
250    #[should_panic(
251        expected = "Error parsing `InstrumentId` from 'invalidaddress.Ethereum:UniswapV3': Ethereum address must start with '0x': invalidaddress"
252    )]
253    fn test_blockchain_instrument_id_invalid_address_no_prefix() {
254        let _ = InstrumentId::from("invalidaddress.Ethereum:UniswapV3");
255    }
256
257    #[cfg(feature = "defi")]
258    #[rstest]
259    #[should_panic(
260        expected = "Error parsing `InstrumentId` from '0x123.Ethereum:UniswapV3': Blockchain address '0x123' is incorrect: odd number of digits"
261    )]
262    fn test_blockchain_instrument_id_invalid_address_short() {
263        let _ = InstrumentId::from("0x123.Ethereum:UniswapV3");
264    }
265
266    #[cfg(feature = "defi")]
267    #[rstest]
268    #[should_panic(
269        expected = "Error parsing `InstrumentId` from '0xC31E54c7a869B9FcBEcc14363CF510d1c41fa44G.Ethereum:UniswapV3': Blockchain address '0xC31E54c7a869B9FcBEcc14363CF510d1c41fa44G' is incorrect: invalid character 'G' at position 39"
270    )]
271    fn test_blockchain_instrument_id_invalid_address_non_hex() {
272        let _ = InstrumentId::from("0xC31E54c7a869B9FcBEcc14363CF510d1c41fa44G.Ethereum:UniswapV3");
273    }
274
275    #[cfg(feature = "defi")]
276    #[rstest]
277    #[should_panic(
278        expected = "Error parsing `InstrumentId` from '0xc31e54c7a869b9fcbecc14363cf510d1c41fa443.Ethereum:UniswapV3': Blockchain address '0xc31e54c7a869b9fcbecc14363cf510d1c41fa443' has incorrect checksum"
279    )]
280    fn test_blockchain_instrument_id_invalid_address_checksum() {
281        let _ = InstrumentId::from("0xc31e54c7a869b9fcbecc14363cf510d1c41fa443.Ethereum:UniswapV3");
282    }
283
284    #[cfg(feature = "defi")]
285    #[rstest]
286    fn test_blockchain_extraction_valid_dex() {
287        let id =
288            InstrumentId::from("0xC31E54c7a869B9FcBEcc14363CF510d1c41fa443.Arbitrum:UniswapV3");
289        let blockchain = id.blockchain();
290        assert!(blockchain.is_some());
291        assert_eq!(blockchain.unwrap(), crate::defi::Blockchain::Arbitrum);
292    }
293
294    #[cfg(feature = "defi")]
295    #[rstest]
296    fn test_blockchain_extraction_tradifi_venue() {
297        let id = InstrumentId::from("ETH/USDT.BINANCE");
298        let blockchain = id.blockchain();
299        assert!(blockchain.is_none());
300    }
301}
nautilus_model/identifiers/instrument_id.rs

nautilus_model/identifiers/
instrument_id.rs
