Arithmetic & Overflow

On-chain programs use fixed-size integers with wrapping arithmetic in unchecked ops. Overflow and rounding bugs drain vaults, mint unbacked shares, or brick accounts permanently.

Recipe

Quick-reference recipe card - copy-paste ready.

let shares = deposit_amount
    .checked_mul(total_shares)
    .and_then(|v| v.checked_div(total_assets))
    .ok_or(ErrorCode::MathOverflow)?;
 
// Prefer u128 intermediates for token math
let out = (amount_in as u128)
    .checked_mul(reserve_out as u128)
    .and_then(|n| n.checked_div((reserve_in as u128) + (amount_in as u128)))
    .ok_or(ErrorCode::MathOverflow)? as u64;

When to reach for this:

• Share minting/burning in vaults.
• AMM swap calculations inside programs.
• Interest index accrual in lending.
• Any +, -, *, / on token amounts.

Working Example

use anchor_lang::prelude::*;
 
#[account]
pub struct Pool {
    pub total_assets: u64,
    pub total_shares: u64,
}
 
pub fn deposit(pool: &mut Pool, amount: u64) -> Result<u64> {
    let shares = if pool.total_shares == 0 {
        amount
    } else {
        (amount as u128)
            .checked_mul(pool.total_shares as u128)
            .and_then(|n| n.checked_div(pool.total_assets as u128))
            .ok_or(ErrorCode::MathOverflow)? as u64
    };
 
    pool.total_assets = pool
        .total_assets
        .checked_add(amount)
        .ok_or(ErrorCode::MathOverflow)?;
    pool.total_shares = pool
        .total_shares
        .checked_add(shares)
        .ok_or(ErrorCode::MathOverflow)?;
 
    Ok(shares)
}
 
#[error_code]
pub enum ErrorCode {
    MathOverflow,
}

What this demonstrates:

• Division after multiplication uses u128 headroom.
• First depositor 1:1 mint avoids divide-by-zero.
• State updates use checked_add to catch overflow.

Deep Dive

How It Works

• BPF builds may not trap on overflow for plain operators in release mode.
• checked_* returns None on overflow - map to program error.
• Division truncates toward zero - favors protocol on rounding policy.
• Fee calculations should use basis points: amount * bps / 10_000.

Rounding Policy

Rust Notes

use anchor_lang::solana_program::native_token::LAMPORTS_PER_SOL;
 
const BPS: u128 = 10_000;
let fee = (amount as u128)
    .checked_mul(fee_bps as u128)
    .and_then(|v| v.checked_add(BPS - 1)) // ceil div trick
    .and_then(|v| v.checked_div(BPS))
    .ok_or(ErrorCode::MathOverflow)? as u64;

Gotchas

• Plain + on balances - Silent wrap near u64::MAX. Fix: checked_add everywhere on user balances.
• Divide before multiply - Loses precision and enables dust attacks. Fix: Multiply first in wider type.
• Zero total shares - Divide by zero or inflation attack on first deposit. Fix: Minimum liquidity lock or virtual offset.
• Cast truncates - u128 as u64 silently truncates. Fix: u64::try_from with range check.
• Signed confusion - Using i64 prices without bounds. Fix: Document ranges; use checked_* on signed too.
• Different token decimals - Mixing 6 and 9 decimal mints. Fix: Normalize to common precision before math.

Alternatives

FAQs

Related

• Safe Arithmetic - Rust patterns
• Account Validation Attacks - economic exploits
• Sealevel Attacks Catalog - inflation attacks
• Fuzzing Programs - edge case discovery

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.