checked-arithmetic

name	checked-arithmetic
description	Use when writing Rust arithmetic on amounts or other quantities derived from external/user input — guard against silent overflow.
metadata	{"author":"0xMiden"}

Checked Arithmetic on User-Supplied Values

Rule

Any arithmetic where one or more operands originates from external input (transaction body, advice provider, user RPC, deserialized payload) must use checked or overflowing arithmetic and surface the overflow:

• Prefer checked_add / checked_sub / checked_mul and return an error on None.
• Use overflowing_add / widening_mul when you need the wrapping value and the overflow flag; then assert!(!overflow) (or branch) before using the result.
• Do not use the default +, -, * operators on untrusted values in release builds — debug-only overflow checks are not enough.

Why

The default +, -, * operators wrap silently in release builds, so an overflow on a balance or amount yields a wrong value with no error. Checked and overflowing operations surface the overflow so it can be rejected.

Examples

// Good: checked
let total = balance.checked_add(amount).ok_or(Error::Overflow)?;

// Good: overflowing with explicit flag check
let (product, overflow) = a.widening_mul(b);
if overflow { return Err(Error::Overflow); }

// Bad: wraps on overflow in release
let total = balance + amount;

---

Source: 0xMiden/protocol — distributed by TomeVault.