# nvana_fixed
A high-precision fixed-point arithmetic library for Rust, designed for financial and DeFi calculations where precision is critical.
## Features
- **High Precision**: 18 decimal places of precision (WAD format)
- **Large Range**: Uses U256 internally, supporting values much larger than u128
- **Safe Arithmetic**: All operations are checked and return `Option` on overflow/underflow
- **DeFi Ready**: Built-in support for basis points and micro basis points
- **Comparison Traits**: Full support for equality and ordering operations
## Installation
Add this to your `Cargo.toml`:
```toml
[dependencies]
nvana_fixed = "0.1.0"
```
## Quick Start
```rust
use nvana_fixed::PreciseNumber;
// Basic arithmetic
let a = PreciseNumber::new(10).unwrap();
let b = PreciseNumber::new(3).unwrap();
let sum = a.checked_add(&b).unwrap();
let product = a.checked_mul(&b).unwrap();
let quotient = a.checked_div(&b).unwrap();
assert_eq!(sum.to_imprecise().unwrap(), 13);
assert_eq!(product.to_imprecise().unwrap(), 30);
assert_eq!(quotient.to_imprecise().unwrap(), 3); // Rounded
// Working with percentages
let rate = PreciseNumber::from_basis_points(500).unwrap(); // 5%
let principal = PreciseNumber::new(1000).unwrap();
let interest = principal.checked_mul(&rate).unwrap();
assert_eq!(interest.to_imprecise().unwrap(), 50);
// Comparisons
assert!(a < b.checked_mul(&PreciseNumber::new(2).unwrap()).unwrap());
```
## How It Works
`PreciseNumber` uses a fixed-point representation with 18 decimal places. Internally, values are stored as `value * 10^18` in a 256-bit integer:
- `1.0` is stored as `1_000_000_000_000_000_000`
- `0.5` is stored as `500_000_000_000_000_000`
- `42.123` is stored as `42_123_000_000_000_000_000`
All arithmetic operations include automatic rounding correction to minimize truncation errors.
## Safety
All arithmetic operations return `Option<PreciseNumber>` and will return `None` on:
- Overflow
- Underflow
- Division by zero
This ensures your code can handle edge cases gracefully.
## License
Licensed under MIT.