U256 Math Library

🧐 Motivation
We need a complete, safe, and reusable math library for U256 to support arithmetic, division, square root, and utility operations.

📝 Details
Implement the following operations for a U256 math library:

Arithmetic

• add() – add two 256-bit values with overflow checks
• sub() – subtract two 256-bit values with underflow checks
• mul() – multiply two 256-bit values with overflow checks

Division

• div() – compute quotient
• rem() – compute remainder
• divRem() – compute quotient and remainder together

Square Root

• sqrt() – compute ⌊√x⌋, with optimized handling for small or limb-aligned values

Utility

• MODULUS() – return high-limb modulus (2^128)

• MODULUS_U256() – return U256(2^128)

• ZERO_U256() – return zero

• min(), max()

• isMultiple()

• isZero()

• Limb-specific checks:

  • isLowestLimbOnly()
  • isSecondLowestLimbOnly()
  • isThirdLowestLimbOnly()
  • isHighestLimbOnly()

• isExceedingFieldSize() – checks > 2^254 − 1

Future Work

• pow()
• powU256()

Notes

• All operations should be overflow-safe and explicit about error cases