Struct Wad 

pub struct Wad(/* private fields */);

Fixed-point decimal number with 18 decimal places of precision.

Wad represents decimal numbers using a fixed-point representation where 1.0 is stored as 1_000_000_000_000_000_000 (10^18). This provides precise decimal arithmetic suitable for financial calculations in smart contracts.

Truncation

All arithmetic operations truncate toward zero rather than rounding:

• 5 / 2 = 2 (not 2.5 or 3)
• -5 / 2 = -2 (not -2.5 or -3)

Precision

Due to truncation on each multiplication/division, the order of operations can affect results:

let a = Wad::from_integer(&e, 1000);
let b = Wad::from_raw(55_000_000_000_000_000);  // 0.055
let c = Wad::from_raw(8_333_333_333_333_333);   // ~0.00833

let result1 = a * b * c;      // Truncates after first multiplication
let result2 = a * (b * c);    // Truncates after inner multiplication
// result1 and result2 may differ by ~10^-16 due to different truncation points

Typical precision loss: ~10^-15 to 10^-16 in relative terms, which is negligible when converting to typical token precision (6-8 decimals).

Examples

use soroban_sdk::Env;
use contract_utils::math::wad::Wad;

let e = Env::default();

// Creating Wad values
let five = Wad::from_integer(&e, 5);           // 5.0
let half = Wad::from_ratio(&e, 1, 2);          // 0.5
let price = Wad::from_token_amount(&e, 1_500_000, 6); // 1.5 (from USDC)

// Arithmetic
let sum = five + half;                          // 5.5
let product = five * half;                      // 2.5
let quotient = five / half;                     // 10.0

// Converting back to token amounts
let usdc_amount = product.to_token_amount(&e, 6); // 2_500_000 (2.5 USDC)

Implementations

impl Wad

pub fn from_integer(e: &Env, n: i128) -> Self

Creates a Wad from an integer by applying WAD scaling.

Treats the input as a whole number and scales it to WAD precision (18 decimals).

Arguments

• e - Access to the Soroban environment.
• n - The integer value to convert to WAD representation.

Errors

• SorobanFixedPointError::Overflow - When the multiplication overflows i128.

Examples

let wad = Wad::from_integer(&e, 5);
assert_eq!(wad.raw(), 5_000_000_000_000_000_000);

Notes

Compare with Wad::from_raw which does NOT apply WAD scaling.

pub fn to_integer(self) -> i128

Converts Wad back to an integer by removing WAD scaling.

Truncates toward zero, discarding any fractional part.

Examples

let wad = Wad::from_raw(5_000_000_000_000_000_000);
assert_eq!(wad.to_integer(), 5);

pub fn from_ratio(e: &Env, num: i128, den: i128) -> Self

Creates a Wad from a ratio (num / den).

Arguments

• e - Access to the Soroban environment.
• num - The numerator of the ratio.
• den - The denominator of the ratio.

Errors

• SorobanFixedPointError::DivisionByZero - When den is zero.
• SorobanFixedPointError::Overflow - When the multiplication overflows i128.

Examples

let wad = Wad::from_ratio(&e, 5, 10);
assert_eq!(wad.raw(), 500_000_000_000_000_000); // 0.5 in WAD

pub fn from_token_amount(e: &Env, amount: i128, token_decimals: u8) -> Self

Creates a Wad from a token amount with specified decimals.

Converts a token’s native representation to WAD (18 decimals). Truncates toward zero when scaling down (token_decimals > 18).

Arguments

• e - Access to the Soroban environment.
• amount - The token amount in its smallest unit.
• token_decimals - The number of decimals the token uses.

Errors

• SorobanFixedPointError::Overflow - When the scaling multiplication overflows i128.

Examples

// USDC has 2 decimals, so 1 USDC = 100 units
let wad = Wad::from_token_amount(&e, 100, 2);
assert_eq!(wad.raw(), 1_000_000_000_000_000_000); // 1.0 in WAD

Notes

amount must be in the token’s smallest unit. For example, to represent 1 USDC (2 decimals), pass 100, not 1.

pub fn to_token_amount(self, e: &Env, token_decimals: u8) -> i128

Converts Wad to a token amount with specified decimals.

Converts from WAD (18 decimals) back to a token’s native representation. Truncates toward zero when scaling down (token_decimals < 18).

Arguments

• e - Access to the Soroban environment.
• token_decimals - The number of decimals the target token uses.

Errors

• SorobanFixedPointError::Overflow - When the scaling multiplication overflows i128 (occurs when token_decimals > 18).

Examples

let wad = Wad::from_raw(1_000_000_000_000_000_000); // 1.0 in WAD
let usdc_amount = wad.to_token_amount(&e, 2);
assert_eq!(usdc_amount, 100); // 1 USDC = 100 units

pub fn from_price(e: &Env, price_integer: i128, price_decimals: u8) -> Self

Creates a Wad from a price with specified decimals.

This is an alias for Wad::from_token_amount.

Arguments

• e - Access to the Soroban environment.
• price_integer - The price in its smallest unit.
• price_decimals - The number of decimals the price uses.

Errors

refer to Wad::from_token_amount errors.

pub fn raw(self) -> i128

Returns the raw i128 value without applying WAD scaling.

Returns the internal representation directly.

Examples

let wad = Wad::from_integer(5);
assert_eq!(wad.raw(), 5_000_000_000_000_000_000);

pub fn from_raw(raw: i128) -> Self

Creates a Wad from a raw i128 value without applying WAD scaling.

Interprets the input as the internal representation directly.

Arguments

• raw - The raw internal value.

Examples

let wad = Wad::from_raw(5);
// Represents 0.000000000000000005 in decimal
assert_eq!(wad.raw(), 5);

Notes

Compare with Wad::from_integer which applies WAD scaling.

pub fn min(self, other: Self) -> Self

Returns the minimum of two Wad values.

Arguments

• other - The other Wad value to compare.

pub fn max(self, other: Self) -> Self

Returns the maximum of two Wad values.

Arguments

• other - The other Wad value to compare.

pub fn checked_add(self, rhs: Wad) -> Option<Wad>

Checked addition. Returns None on overflow.

pub fn checked_sub(self, rhs: Wad) -> Option<Wad>

Checked subtraction. Returns None on overflow.

pub fn checked_mul(self, e: &Env, rhs: Wad) -> Option<Wad>

Checked multiplication (Wad * Wad).

Returns None on overflow. Handles phantom overflow by scaling to I256 when intermediate multiplication overflows i128 but the final result fits. Result is truncated toward zero after division by WAD_SCALE.

pub fn checked_div(self, e: &Env, rhs: Wad) -> Option<Wad>

Checked division (Wad / Wad). Returns None on overflow or division by zero.

Result is truncated toward zero.

pub fn checked_mul_int(self, n: i128) -> Option<Wad>

Checked multiplication by integer. Returns None on overflow.

pub fn checked_div_int(self, n: i128) -> Option<Wad>

Checked division by integer. Returns None on division by zero.

pub fn abs(self) -> Self

Returns the absolute value of the Wad.

Examples

let e = Env::default();
let negative = Wad::from_integer(&e, -5);
assert_eq!(negative.abs(), Wad::from_integer(&e, 5));

pub fn pow(self, e: &Env, exponent: u32) -> Self

Raises Wad to an unsigned integer power using exponentiation by squaring.

This method is optimized for efficiency, computing the result in O(log n) multiplications where n is the exponent. Each multiplication maintains fixed-point precision by dividing by WAD_SCALE, with truncation toward zero.

Arguments

• e - Access to the Soroban environment for error handling.
• exponent - The unsigned integer exponent (0 to 2^32-1).

Errors

• SorobanFixedPointError::Overflow - When intermediate or final result exceeds i128 bounds.

Examples

// Compound interest: (1.05)^10
let rate = Wad::from_ratio(&e, 105, 100);  // 1.05
let final_multiplier = rate.pow(&e, 10);
let final_amount = principal * final_multiplier;

// Quadratic bonding curve: price = supply^2
let supply = Wad::from_integer(&e, 1000);
let price = supply.pow(&e, 2);

pub fn checked_pow(self, e: &Env, exponent: u32) -> Option<Self>

Checked version of Wad::pow.

Returns None instead of panicking on overflow. Handles phantom overflow transparently by scaling to I256 when intermediate multiplications overflow i128 but the final result fits.

Arguments

• e - Access to the Soroban environment for i256 operations.
• exponent - The unsigned integer exponent.

Examples

let e = Env::default();
let small = Wad::from_integer(&e, 2);
assert_eq!(small.checked_pow(&e, 10), Some(Wad::from_integer(&e, 1024)));

let large = Wad::from_integer(&e, i128::MAX / WAD_SCALE);
assert_eq!(large.checked_pow(&e, 2), None); // Overflows

Notes

Phantom overflow is handled internally.

Trait Implementations

impl Add for Wad

type Output = Wad

The resulting type after applying the + operator.

fn add(self, rhs: Wad) -> Wad

Performs the + operation.

impl Clone for Wad

fn clone(&self) -> Wad

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Wad

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Div<i128> for Wad

type Output = Wad

The resulting type after applying the / operator.

fn div(self, rhs: i128) -> Wad

Performs the / operation.

impl Div for Wad

type Output = Wad

The resulting type after applying the / operator.

fn div(self, rhs: Wad) -> Wad

Performs the / operation.

impl Mul<Wad> for i128

type Output = Wad

The resulting type after applying the * operator.

fn mul(self, rhs: Wad) -> Wad

Performs the * operation.

impl Mul<i128> for Wad

type Output = Wad

The resulting type after applying the * operator.

fn mul(self, rhs: i128) -> Wad

Performs the * operation.

impl Mul for Wad

type Output = Wad

The resulting type after applying the * operator.

fn mul(self, rhs: Wad) -> Wad

Performs the * operation.

impl Neg for Wad

type Output = Wad

The resulting type after applying the - operator.

fn neg(self) -> Wad

Performs the unary - operation.

impl Ord for Wad

fn cmp(&self, other: &Wad) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for Wad

fn eq(&self, other: &Wad) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for Wad

fn partial_cmp(&self, other: &Wad) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Sub for Wad

type Output = Wad

The resulting type after applying the - operator.

fn sub(self, rhs: Wad) -> Wad

Performs the - operation.

impl Copy for Wad

impl Eq for Wad

impl StructuralPartialEq for Wad