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////////////////////////////////////////////////////////////////////////////////
75// Tests
76////////////////////////////////////////////////////////////////////////////////
77
78#[cfg(test)]
79mod tests {
80    use std::sync::Arc;
81
82    use rstest::rstest;
83
84    use super::*;
85    use crate::defi::chain::chains;
86
87    #[rstest]
88    fn test_token_constructor() {
89        let chain = Arc::new(chains::ETHEREUM.clone());
90        let address = "0xA0b86a33E6441b936662bb6B5d1F8Fb0E2b57A5D"
91            .parse()
92            .unwrap();
93
94        let token = Token::new(
95            chain.clone(),
96            address,
97            "Wrapped Ether".to_string(),
98            "WETH".to_string(),
99            18,
100        );
101
102        assert_eq!(token.chain.chain_id, chain.chain_id);
103        assert_eq!(token.address, address);
104        assert_eq!(token.name, "Wrapped Ether");
105        assert_eq!(token.symbol, "WETH");
106        assert_eq!(token.decimals, 18);
107    }
108
109    #[rstest]
110    fn test_token_display_with_special_characters() {
111        // Test edge case where token names/symbols contain formatting characters
112        let chain = Arc::new(chains::ETHEREUM.clone());
113        let token = Token::new(
114            chain,
115            "0xA0b86a33E6441b936662bb6B5d1F8Fb0E2b57A5D"
116                .parse()
117                .unwrap(),
118            "Test Token (with parentheses)".to_string(),
119            "TEST-1".to_string(),
120            18,
121        );
122
123        let display = token.to_string();
124        assert_eq!(
125            display,
126            "Token(symbol=TEST-1, name=Test Token (with parentheses))"
127        );
128    }
129}
nautilus_model/defi/token.rs

nautilus_model/defi/
token.rs
