Integer Math API Reference
This page documents the public API of openzeppelin_math for OpenZeppelin Contracts for Sui v1.x.
use openzeppelin_math::rounding;Rounding strategy helpers shared by arithmetic operations across width-specific modules.
Types
Functions
Types
enum RoundingMode { Down, Up, Nearest }
enum
#Down always rounds toward zero, Up rounds toward ceiling, and Nearest rounds to the closest integer with ties rounded up.
Functions
down() -> RoundingMode
public
#Returns RoundingMode::Down.
up() -> RoundingMode
public
#Returns RoundingMode::Up.
nearest() -> RoundingMode
public
#Returns RoundingMode::Nearest (round-half-up behavior).
use openzeppelin_math::decimal_scaling;Helpers for converting balances between decimal precisions while enforcing safe casts and explicit truncation semantics.
Functions
safe_downcast_balance(raw_amount, source_decimals, target_decimals)safe_upcast_balance(amount, source_decimals, target_decimals)
Errors
Functions
safe_downcast_balance(raw_amount: u256, source_decimals: u8, target_decimals: u8) -> u64
public
#Converts a u256 amount to u64 across decimal domains. When scaling down (source_decimals > target_decimals), fractional residue is truncated, not rounded.
Aborts when decimals exceed 24 or when the scaled value cannot fit in u64.
safe_upcast_balance(amount: u64, source_decimals: u8, target_decimals: u8) -> u256
public
#Converts a u64 amount to u256 across decimal domains.
Scaling up preserves precision. Scaling down truncates fractional residue (no rounding). Aborts when decimal values exceed the supported range.
Errors
ESafeDowncastOverflowedInt
error
#Raised when a downcast path would require representing a value larger than u64::MAX.
EInvalidDecimals
error
#Raised when either decimal argument is greater than the package limit (24).
These modules expose a consistent API surface across unsigned widths.
Each module wraps shared arithmetic helpers with width-specific bit limits and representability checks.
Source modules:
Functions
average(a, b, rounding_mode)checked_shl(value, shift)checked_shr(value, shift)mul_div(a, b, denominator, rounding_mode)mul_shr(a, b, shift, rounding_mode)clz(value)msb(value)log2(value, rounding_mode)log256(value, rounding_mode)log10(value, rounding_mode)sqrt(value, rounding_mode)inv_mod(value, modulus)mul_mod(a, b, modulus)
Functions
average(a: Int, b: Int, rounding_mode: RoundingMode) -> Int
public
#Returns the arithmetic mean of a and b for Int in {u8, u16, u32, u64, u128, u256}, rounded according to rounding_mode.
checked_shl(value: Int, shift: u8) -> Option<Int>
public
#Performs a lossless left shift. Returns none() when shifting would consume non-zero bits.
checked_shr(value: Int, shift: u8) -> Option<Int>
public
#Performs a lossless right shift. Returns none() when shifting would consume non-zero bits.
mul_div(a: Int, b: Int, denominator: Int, rounding_mode: RoundingMode) -> Option<Int>
public
#Computes (a * b) / denominator with configured rounding. Returns none() when the rounded value is not representable in the target width.
Aborts when denominator is zero.
mul_shr(a: Int, b: Int, shift: u8, rounding_mode: RoundingMode) -> Option<Int>
public
#Computes (a * b) >> shift with configured rounding and returns none() when the rounded result overflows the target width.
clz(value: Int) -> u8 | u16
public
#Counts leading zero bits. For u256, the return type is u16; for other widths it is u8.
msb(value: Int) -> u8
public
#Returns the zero-based index of the most significant set bit. By convention returns 0 for value = 0.
log2(value: Int, rounding_mode: RoundingMode) -> u8 | u16
public
#Computes base-2 logarithm with configured rounding. For u256, the return type is u16; for other widths it is u8.
log256(value: Int, rounding_mode: RoundingMode) -> u8
public
#Computes base-256 logarithm with configured rounding.
log10(value: Int, rounding_mode: RoundingMode) -> u8
public
#Computes base-10 logarithm with configured rounding.
sqrt(value: Int, rounding_mode: RoundingMode) -> Int
public
#Computes square root with configured rounding.
inv_mod(value: Int, modulus: Int) -> Option<Int>
public
#Computes modular multiplicative inverse.
Returns none() when inverse does not exist (including modulus = 1).
Aborts when modulus is zero.
mul_mod(a: Int, b: Int, modulus: Int) -> Int
public
#Computes (a * b) mod modulus.
Aborts when modulus is zero.
use openzeppelin_math::u512;Wide-integer helper module used by high-precision arithmetic paths where u256 intermediates may overflow.
Types
Functions
new(hi, lo)zero()from_u256(value)hi(value)lo(value)ge(value, other)mul_u256(a, b)div_rem_u256(numerator, divisor)
Errors
Types
struct U512 { hi: u256, lo: u256 }
struct
#Represents a 512-bit unsigned integer as two u256 limbs.
Functions
new(hi: u256, lo: u256) -> U512
public
#Builds a U512 value from explicit high and low limbs.
zero() -> U512
public
#Returns the all-zero U512 value.
from_u256(value: u256) -> U512
public
#Embeds a u256 value as U512 { hi: 0, lo: value }.
hi(value: &U512) -> u256
public
#Returns the upper 256-bit limb.
lo(value: &U512) -> u256
public
#Returns the lower 256-bit limb.
ge(value: &U512, other: &U512) -> bool
public
#Lexicographic greater-or-equal comparison between two wide integers.
mul_u256(a: u256, b: u256) -> U512
public
#Computes full-width product a * b as a 512-bit result.
Aborts with ECarryOverflow if an internal carry invariant is violated.
div_rem_u256(numerator: U512, divisor: u256) -> (bool, u256, u256)
public
#Divides a 512-bit numerator by a non-zero u256 divisor.
Returns (overflow, quotient, remainder), where overflow = true indicates the exact quotient does not fit in u256.
In overflow cases, quotient is returned as 0 while remainder remains correct.
Errors
ECarryOverflow
error
#Raised when cross-limb accumulation produces an out-of-range final carry.
EUnderflow
error
#Raised when an internal borrow operation would underflow the high limb.
EDivideByZero
error
#Raised when div_rem_u256 is called with divisor = 0.
EInvalidRemainder
error
#Raised when internal division remainder invariants are violated.