Safe Arithmetic

Token amounts, fees, and share calculations must never wrap silently. On-chain, use checked_*, saturating_*, or explicit bounds checks and map failures to ProgramError.

Recipe

let total = base
    .checked_add(fee)
    .ok_or(ProgramError::InvalidArgument)?;

When to reach for this:

• Aggregating balances, shares, or reward indexes.
• Computing fees as a percentage of lamports or token units.
• Implementing vault accounting or pro-rata distributions.

Working Example

use solana_program::program_error::ProgramError;
 
pub fn apply_fee(amount: u64, bps: u64) -> Result<u64, ProgramError> {
    if bps > 10_000 {
        return Err(ProgramError::InvalidArgument);
    }
    let fee = amount
        .checked_mul(bps)
        .and_then(|v| v.checked_div(10_000))
        .ok_or(ProgramError::InvalidArgument)?;
    amount
        .checked_sub(fee)
        .ok_or(ProgramError::InvalidArgument)
}

What this demonstrates:

• Basis points fee uses two-step checked mul/div.
• Bounds check bps before math.
• Errors surface as InvalidArgument for client decoding.

Deep Dive

API Choice

Financial Patterns

• Use u128 intermediates for mul-div when product exceeds u64.
• Document rounding (floor vs ceil) for fee splits.

Rust Notes

let wide = (a as u128).checked_mul(b as u128)?;

Gotchas

• Unchecked ops - a + b wraps in release without overflow checks in some contexts. Fix: Always checked_* for user funds.
• Saturating misuse - saturating_sub can hide insolvency. Fix: Use checked_sub when balance must not underflow.
• Division by zero - Rust panics on / 0 even on-chain. Fix: Guard divisor explicitly.
• Cast truncation - as u64 from u128 silently truncates. Fix: Check try_into bounds.
• Signed confusion - Token amounts are unsigned - avoid i64 unless required. Fix: undefined

Alternatives

FAQs

Related

• Fee & Treasury Patterns - Fee collection
• Vault & Escrow - Balance tracking
• Rust for Solana Best Practices - Security habits

Stack versions: This page was written for Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, anchor-lang 0.32.1, Rust 1.91.1, @solana/kit 7.0.0, Surfpool 0.12.0, and LiteSVM 0.6.x.