nautilus_model/defi/types/
quantity.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//! DeFi-specific extensions for the [`Quantity`] type.
17
18use alloy_primitives::U256;
19
20use crate::types::quantity::Quantity;
21
22impl Quantity {
23    /// Constructs a [`Quantity`] from a raw amount expressed in wei (18-decimal fixed-point).
24    ///
25    /// The resulting [`Quantity`] will always have `precision` equal to `18`.
26    ///
27    /// # Panics
28    ///
29    /// Panics if the supplied `raw_wei` cannot fit into an **unsigned** 128-bit integer (this
30    /// would exceed the numeric range of the internal `QuantityRaw` representation).
31    #[must_use]
32    pub fn from_wei<U>(raw_wei: U) -> Self
33    where
34        U: Into<U256>,
35    {
36        let raw_u256: U256 = raw_wei.into();
37        let raw_u128: u128 = raw_u256
38            .try_into()
39            .expect("raw wei value exceeds unsigned 128-bit range");
40
41        Self::from_raw(raw_u128, 18)
42    }
43
44    /// Converts this [`Quantity`] to a wei amount (U256).
45    ///
46    /// Only valid for prices with precision 18. For other precisions convert to precision 18 first.
47    ///
48    /// # Panics
49    ///
50    /// Panics if the quantity has precision other than 18.
51    #[must_use]
52    pub fn as_wei(&self) -> U256 {
53        assert!(
54            self.precision == 18,
55            "Failed to convert quantity with precision {} to wei (requires precision 18)",
56            self.precision
57        );
58
59        U256::from(self.raw)
60    }
61}
62
63#[cfg(test)]
64mod tests {
65    use rstest::rstest;
66    use rust_decimal_macros::dec;
67
68    use super::*;
69
70    #[rstest]
71    fn test_from_wei_basic() {
72        let quantity = Quantity::from_wei(U256::from(1_000_000_000_000_000_000_u128)); // 1 token in wei
73        assert_eq!(quantity.precision, 18);
74        assert_eq!(quantity.as_decimal(), dec!(1.0));
75    }
76
77    #[rstest]
78    fn test_as_wei_basic() {
79        let quantity = Quantity::from_raw(1_000_000_000_000_000_000_u128, 18);
80        let wei = quantity.as_wei();
81        assert_eq!(wei, U256::from(1_000_000_000_000_000_000_u128));
82    }
83
84    #[rstest]
85    #[should_panic(
86        expected = "Failed to convert quantity with precision 2 to wei (requires precision 18)"
87    )]
88    fn test_as_wei_wrong_precision() {
89        let quantity = Quantity::new(1.23, 2);
90        let _ = quantity.as_wei();
91    }
92
93    #[rstest]
94    fn test_wei_round_trip() {
95        let original_wei = U256::from(1_500_000_000_000_000_000_u128); // 1.5 tokens
96        let quantity = Quantity::from_wei(original_wei);
97        let converted_wei = quantity.as_wei();
98        assert_eq!(original_wei, converted_wei);
99        assert_eq!(quantity.as_decimal(), dec!(1.5));
100    }
101
102    #[rstest]
103    fn test_from_wei_large_value() {
104        // Test with a large but valid wei amount
105        let large_wei = U256::from(1_000_000_000_000_000_000_000_u128); // 1000 tokens
106        let quantity = Quantity::from_wei(large_wei);
107        assert_eq!(quantity.precision, 18);
108        assert_eq!(quantity.as_decimal(), dec!(1000.0));
109    }
110
111    #[rstest]
112    fn test_from_wei_small_value() {
113        // Test with a small but representable wei amount (1 million wei = 1e-12)
114        // Very small values like 1 wei (1e-18) are at the edge of f64 precision
115        let small_wei = U256::from(1_000_000_u128);
116        let quantity = Quantity::from_wei(small_wei);
117        assert_eq!(quantity.precision, 18);
118        assert_eq!(quantity.as_decimal(), dec!(0.000000000001));
119    }
120
121    #[rstest]
122    fn test_from_wei_zero() {
123        let quantity = Quantity::from_wei(U256::ZERO);
124        assert_eq!(quantity.precision, 18);
125        assert_eq!(quantity.as_decimal(), dec!(0));
126        assert_eq!(quantity.as_wei(), U256::ZERO);
127    }
128
129    #[rstest]
130    fn test_from_wei_very_large_value() {
131        // Test with a very large but valid wei amount (1 billion tokens)
132        let large_wei = U256::from(1_000_000_000_000_000_000_000_000_000_u128);
133        let quantity = Quantity::from_wei(large_wei);
134        assert_eq!(quantity.precision, 18);
135        assert_eq!(quantity.as_wei(), large_wei);
136        assert_eq!(quantity.as_decimal(), dec!(1000000000));
137    }
138
139    #[rstest]
140    #[should_panic(expected = "raw wei value exceeds unsigned 128-bit range")]
141    fn test_from_wei_overflow() {
142        let overflow_wei = U256::from(u128::MAX) + U256::from(1_u64);
143        let _ = Quantity::from_wei(overflow_wei);
144    }
145
146    #[rstest]
147    fn test_from_wei_various_amounts() {
148        // Test various wei amounts and their decimal equivalents
149        let test_cases = vec![
150            (1_u128, dec!(0.000000000000000001)),        // 1 wei
151            (1000_u128, dec!(0.000000000000001)),        // 1 thousand wei
152            (1_000_000_u128, dec!(0.000000000001)),      // 1 million wei
153            (1_000_000_000_u128, dec!(0.000000001)),     // 1 gwei
154            (1_000_000_000_000_u128, dec!(0.000001)),    // 1 microtoken
155            (1_000_000_000_000_000_u128, dec!(0.001)),   // 1 millitoken
156            (1_000_000_000_000_000_000_u128, dec!(1)),   // 1 token
157            (10_000_000_000_000_000_000_u128, dec!(10)), // 10 tokens
158        ];
159
160        for (wei_amount, expected_decimal) in test_cases {
161            let quantity = Quantity::from_wei(U256::from(wei_amount));
162            assert_eq!(quantity.precision, 18);
163            assert_eq!(quantity.as_decimal(), expected_decimal);
164            assert_eq!(quantity.as_wei(), U256::from(wei_amount));
165        }
166    }
167
168    #[rstest]
169    fn test_as_wei_precision_validation() {
170        // Test that as_wei() requires exactly precision 18
171        for precision in [2, 6, 8, 16] {
172            let quantity = Quantity::new(123.45, precision);
173            let result = std::panic::catch_unwind(|| quantity.as_wei());
174            assert!(
175                result.is_err(),
176                "as_wei() should panic for precision {precision}"
177            );
178        }
179    }
180
181    #[rstest]
182    fn test_arithmetic_operations_with_wei() {
183        let quantity1 = Quantity::from_wei(U256::from(1_000_000_000_000_000_000_u128)); // 1.0
184        let quantity2 = Quantity::from_wei(U256::from(500_000_000_000_000_000_u128)); // 0.5
185
186        // Test addition
187        let sum = quantity1 + quantity2;
188        assert_eq!(sum.precision, 18);
189        assert_eq!(sum.as_decimal(), dec!(1.5));
190        assert_eq!(sum.as_wei(), U256::from(1_500_000_000_000_000_000_u128));
191
192        // Test subtraction
193        let diff = quantity1 - quantity2;
194        assert_eq!(diff.precision, 18);
195        assert_eq!(diff.as_decimal(), dec!(0.5));
196        assert_eq!(diff.as_wei(), U256::from(500_000_000_000_000_000_u128));
197    }
198
199    #[rstest]
200    fn test_comparison_operations_with_wei() {
201        let quantity1 = Quantity::from_wei(U256::from(1_000_000_000_000_000_000_u128)); // 1.0
202        let quantity2 = Quantity::from_wei(U256::from(2_000_000_000_000_000_000_u128)); // 2.0
203        let quantity3 = Quantity::from_wei(U256::from(1_000_000_000_000_000_000_u128)); // 1.0
204
205        assert!(quantity1 < quantity2);
206        assert!(quantity2 > quantity1);
207        assert_eq!(quantity1, quantity3);
208        assert!(quantity1 <= quantity3);
209        assert!(quantity1 >= quantity3);
210    }
211}
nautilus_model/defi/types/quantity.rs

nautilus_model/defi/types/
quantity.rs
