Overview

The WAD library provides fixed-point decimal arithmetic for Soroban smart contracts with 18 decimal places of precision. It's designed specifically for DeFi applications where precise decimal calculations are critical, such as interest rates, exchange rates, and token pricing.

It is a fixed-point representation where:

• 1.0 is represented as 1_000_000_000_000_000_000 (10^18)
• 0.5 is represented as 500_000_000_000_000_000
• 123.456 is represented as 123_456_000_000_000_000_000

This allows precise decimal arithmetic using only integer operations, avoiding the pitfalls of floating-point arithmetic in smart contracts.

Why WAD?

Shortcomings of Integers and Float Numbers

Native Integers (i128, u64):

• No decimal support - 1/2 = 0 instead of 0.5
• Loss of precision in financial calculations
• Requires manual scaling for each operation

Floating-Point (f64, f32):

• Non-deterministic behavior across platforms
• Rounding errors that compound in financial calculations
• Security vulnerabilities from precision loss

Why WAD is Better

• High Precision: 18 decimals is more than sufficient for financial calculations
• Deterministic: Same inputs always produce same outputs
• Efficient: Uses native i128 arithmetic under the hood
• Battle-Tested: Used in production by MakerDAO, Uniswap, Aave, and others
• Ergonomic: Operator overloading makes code readable: a + b * c
• Type Safe: NewType pattern prevents mixing scaled and unscaled values

Design Decisions

1. NewType Pattern

We use a NewType struct Wad(i128) instead of a type alias:

// Type alias
type Wad = i128;

// NewType
pub struct Wad(i128);

Benefits:

• Type Safety: Cannot accidentally mix scaled and unscaled values
• Operator Overloading: Can implement +, -, *, / with correct semantics
• Semantic Clarity: Makes intent explicit in function signatures

2. No From/Into Traits

We deliberately DID NOT implement From<i128> or Into<i128> because it's ambiguous:

// What should this mean?
let wad = Wad::from(5);
// Is it 5.0 (scaled to 5 * 10^18)?
// Or 0.000000000000000005 (raw value 5)?

Instead, we provide explicit constructors:

• Wad::from_integer(e, 5) - Creates 5.0 (scaled)
• Wad::from_raw(5) - Creates raw value 5 (0.000000000000000005)

3. Truncation vs Rounding

All operations truncate toward zero rather than rounding:

Why truncation?

• Predictable: Same behavior as integer division
• Conservative: In financial calculations, truncation is often safer (e.g., don't over-calculate interest)
• Fast: No additional logic needed

4. Operator Overloading

We provide operator overloading (+, -, *, /, -) for convenience:

// Readable arithmetic
let total = price + fee;
let cost = quantity * price;
let ratio = numerator / denominator;

Operator overloading is supported across WAD and native i128 types where unambiguous: WAD * i128, i128 * WAD, WAD / i128.

Explicit methods are available for safety:

• checked_add(), checked_sub(), etc. return Option<Wad> for overflow handling

How It Works

Internal Representation

pub struct Wad(i128); // Internal representation
pub const WAD_SCALE: i128 = 1_000_000_000_000_000_000; // 10^18

A Wad is simply a wrapper around i128 that interprets the value as having 18 decimal places.

Arithmetic Operations

Addition/Subtraction: Direct on internal values

impl Add for Wad {
    fn add(self, rhs: Wad) -> Wad {
        Wad(self.0 + rhs.0)
    }
}

Multiplication: Scale down by WAD_SCALE

impl Mul for Wad {
    fn mul(self, rhs: Wad) -> Wad {
        // (a * b) / 10^18
        Wad((self.0 * rhs.0) / WAD_SCALE)
    }
}

Division: Scale up by WAD_SCALE

impl Div for Wad {
    fn div(self, rhs: Wad) -> Wad {
        // (a * 10^18) / b
        Wad((self.0 * WAD_SCALE) / rhs.0)
    }
}

Exponentiation

WAD supports raising a value to an unsigned integer exponent via pow.

• pow(&e, exponent) is optimized using exponentiation by squaring (O(log n) multiplications).
• Each multiplication keeps WAD semantics (fixed-point multiplication and truncation toward zero).
• Overflow is reported via Soroban errors.

In addition to pow, WAD also provides checked_pow, which returns None on overflow.

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

Notes on pow and Phantom Overflow

pow / checked_pow are implemented using exponentiation by squaring and rely on Soroban fixed-point helpers that can automatically scale intermediate products to I256 when needed.

This avoids phantom overflow cases where an intermediate multiplication would overflow i128, but the final scaled result would still fit in i128.

Token Conversions

Different tokens have different decimal places (USDC: 6, XLM: 7, ETH: 18, BTC: 8). WAD handles these conversions:

// Convert from USDC (6 decimals) to WAD
let usdc_amount: i128 = 1_500_000; // 1.5 USDC
let wad = Wad::from_token_amount(&e, usdc_amount, 6);
// wad.raw() = 1_500_000_000_000_000_000 (1.5 in WAD)

// Convert back to USDC
let usdc_back: i128 = wad.to_token_amount(&e, 6);
// usdc_back = 1_500_000

Precision Characteristics

Understanding Fixed-Point Precision

WAD is a fixed-point math library. Like all fixed-point arithmetic systems, precision loss is inherent and unavoidable. The goal is not to eliminate precision errors —that's impossible— but to reduce them to a degree so minimal that they become irrelevant in practical applications.

WAD achieves this goal exceptionally well. With precision loss in the range of 10^-16, the errors are so microscopically small that they have zero practical impact on financial calculations. To put this in perspective: if you're calculating with millions of dollars, the error would be measured in quadrillionths of a cent.

How Precision Loss Manifests

Due to truncation in each operation, operation order can produce slightly different 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 ~315 WAD units
// That's 0.000000000000000315 or (3.15 × 10^-16)

Why This Doesn't Matter:

• Errors are in the 10^-15 to 10^-18 range, far beyond practical significance
• Token precision (6-8 decimals) completely absorbs these errors when converting back
• Real-world financial systems round to 2-8 decimal places; WAD's 18 decimals provide a massive safety margin
• This is orders of magnitude more precise than needed for DeFi applications

Usage Examples

Basic Arithmetic

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

fn calculate_interest(e: &Env, principal: i128, rate_bps: u32) -> i128 {
    // Convert principal (assume 6 decimals like USDC)
    let principal_wad = Wad::from_token_amount(e, principal, 6);

    // Rate in basis points (e.g., 550 = 5.5%)
    let rate_wad = Wad::from_ratio(e, rate_bps as i128, 10_000);

    // Calculate interest
    let interest_wad = principal_wad * rate_wad;

    // Convert back to token amount
    interest_wad.to_token_amount(e, 6)
}

Price Calculations

fn calculate_swap_output(
    e: &Env,
    amount_in: i128,
    reserve_in: i128,
    reserve_out: i128,
) -> i128 {
    // Convert to WAD
    let amount_in_wad = Wad::from_token_amount(e, amount_in, 6);
    let reserve_in_wad = Wad::from_token_amount(e, reserve_in, 6);
    let reserve_out_wad = Wad::from_token_amount(e, reserve_out, 6);

    // Constant product formula: amount_out = (amount_in * reserve_out) / (reserve_in + amount_in)
    let numerator = amount_in_wad * reserve_out_wad;
    let denominator = reserve_in_wad + amount_in_wad;
    let amount_out_wad = numerator / denominator;

    // Convert back
    amount_out_wad.to_token_amount(e, 6)
}

Compound Interest

fn calculate_compound_interest(
    e: &Env,
    principal: i128,
    annual_rate_bps: u32,
    days: u32,
) -> i128 {
    let principal_wad = Wad::from_token_amount(e, principal, 6);
    let rate = Wad::from_ratio(e, annual_rate_bps as i128, 10_000);
    let time_fraction = Wad::from_ratio(e, days as i128, 365);

    // Simple interest: principal * rate * time
    let interest = principal_wad * rate * time_fraction;

    interest.to_token_amount(e, 6)
}

Safe Arithmetic with Overflow Checks

fn safe_multiply(e: &Env, a: i128, b: i128) -> Result<i128, Error> {
    let a_wad = Wad::from_token_amount(e, a, 6);
    let b_wad = Wad::from_token_amount(e, b, 6);

    // Use checked variant
    let result_wad = a_wad
        .checked_mul(e, b_wad)
        .ok_or(Error::Overflow)?;

    Ok(result_wad.to_token_amount(e, 6))
}

API Reference

Constructors

Converters

Arithmetic Operators

Checked Arithmetic

Utility Methods

Error Handling

WAD uses Soroban's contract error system via SorobanFixedPointError:

pub enum SorobanFixedPointError {
    Overflow = 1500,
    DivisionByZero = 1501,
}