nautilus_model/defi/
token.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
16use std::{
17    fmt::{Display, Formatter},
18    sync::Arc,
19};
20
21use alloy_primitives::Address;
22use serde::{Deserialize, Serialize};
23
24use crate::defi::chain::SharedChain;
25
26/// Represents a cryptocurrency token on a blockchain network.
27#[cfg_attr(
28    feature = "python",
29    pyo3::pyclass(module = "nautilus_trader.core.nautilus_pyo3.model")
30)]
31#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
32pub struct Token {
33    /// The blockchain network where this token exists.
34    pub chain: SharedChain,
35    /// The blockchain address of the token contract.
36    pub address: Address,
37    /// The full name of the token.
38    pub name: String,
39    /// The token's ticker symbol.
40    pub symbol: String,
41    /// The number of decimal places used to represent fractional token amounts.
42    pub decimals: u8,
43}
44
45/// A thread-safe shared pointer to a `Token`, enabling efficient reuse across multiple components.
46pub type SharedToken = Arc<Token>;
47
48impl Token {
49    /// Creates a new [`Token`] instance with the specified properties.
50    #[must_use]
51    pub fn new(
52        chain: SharedChain,
53        address: Address,
54        name: String,
55        symbol: String,
56        decimals: u8,
57    ) -> Self {
58        Self {
59            chain,
60            address,
61            name,
62            symbol,
63            decimals,
64        }
65    }
66}
67
68impl Display for Token {
69    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
70        write!(f, "Token(symbol={}, name={})", self.symbol, self.name)
71    }
72}
73
74#[cfg(test)]
75mod tests {
76    use std::sync::Arc;
77
78    use rstest::rstest;
79
80    use super::*;
81    use crate::defi::chain::chains;
82
83    #[rstest]
84    fn test_token_constructor() {
85        let chain = Arc::new(chains::ETHEREUM.clone());
86        let address = "0xA0b86a33E6441b936662bb6B5d1F8Fb0E2b57A5D"
87            .parse()
88            .unwrap();
89
90        let token = Token::new(
91            chain.clone(),
92            address,
93            "Wrapped Ether".to_string(),
94            "WETH".to_string(),
95            18,
96        );
97
98        assert_eq!(token.chain.chain_id, chain.chain_id);
99        assert_eq!(token.address, address);
100        assert_eq!(token.name, "Wrapped Ether");
101        assert_eq!(token.symbol, "WETH");
102        assert_eq!(token.decimals, 18);
103    }
104
105    #[rstest]
106    fn test_token_display_with_special_characters() {
107        // Test edge case where token names/symbols contain formatting characters
108        let chain = Arc::new(chains::ETHEREUM.clone());
109        let token = Token::new(
110            chain,
111            "0xA0b86a33E6441b936662bb6B5d1F8Fb0E2b57A5D"
112                .parse()
113                .unwrap(),
114            "Test Token (with parentheses)".to_string(),
115            "TEST-1".to_string(),
116            18,
117        );
118
119        let display = token.to_string();
120        assert_eq!(
121            display,
122            "Token(symbol=TEST-1, name=Test Token (with parentheses))"
123        );
124    }
125}
nautilus_model/defi/token.rs

nautilus_model/defi/
token.rs
