Skip to content

Latest commit

 

History

History
277 lines (232 loc) · 18.1 KB

ARITHMETIC_PROFILE.md

File metadata and controls

277 lines (232 loc) · 18.1 KB

Arithmetic Profile

Verity uses wrapping modular arithmetic at 2^256 across all compilation layers, matching the EVM Yellow Paper specification.

This document is the authoritative reference for arithmetic semantics. For formal proofs, see Compiler/Proofs/ArithmeticProfile.lean.

Wrapping Semantics

All arithmetic in the compilation path (EDSL -> CompilationModel -> IR -> Yul) wraps modulo 2^256. There are no implicit overflow checks; values silently wrap.

Operation Semantics Div/Mod-by-zero
add(a, b) (a + b) % 2^256 —
sub(a, b) (2^256 + a - b) % 2^256 —
mul(a, b) (a * b) % 2^256 —
div(a, b) a / b (truncating) returns 0
mod(a, b) a % b returns 0
and(a, b) bitwise AND —
or(a, b) bitwise OR —
xor(a, b) bitwise XOR —
not(a) (2^256 - 1) - a —
shl(s, v) (v * 2^s) % 2^256 —
shr(s, v) v / 2^s —
lt(a, b) 1 if a < b, else 0 —
gt(a, b) 1 if a > b, else 0 —
eq(a, b) 1 if a = b, else 0 —
iszero(a) 1 if a = 0, else 0 —

Proof Coverage

Wrapping semantics are proven (not assumed) across all three verification layers:

Layer Proof location What is proved
Layer 1 (EDSL) Verity/Core/Uint256.lean Uint256.add, sub, mul, pow, div, mod are wrapping modular
Layer 1 (EDSL) Verity/Proofs/Stdlib/Math.lean safeAdd, safeSub, safeMul correctness
Compiler Compiler/Proofs/ArithmeticProfile.lean add_wraps, sub_wraps, mul_wraps, div_by_zero, mod_by_zero
EVMYulLean native builtins Compiler/Proofs/YulGeneration/Backends/EvmYulLeanBuiltinSemantics.lean Native builtin dispatch for EVMYulLean proofs
EVMYulLean routing facts Compiler/Proofs/YulGeneration/Backends/EvmYulLeanBridgeLemmas.lean Native routing lemmas for all bridged builtins
EVMYulLean bridge tests Compiler/Proofs/YulGeneration/Backends/EvmYulLeanBridgeTest.lean Smoke vectors for the native builtin routing surface

The EVMYulLean native builtin layer uses EVMYulLean's Fin-based UInt256 operations directly. Current coverage:

  • universal bridge lemmas for 25 pure builtins: add, sub, mul, div, mod, addmod, mulmod, exp, sdiv, smod, lt, gt, slt, sgt, eq, iszero, and, or, xor, not, shl, shr, sar, signextend, and byte
  • context-lifted native routing through evalBuiltinCallWithEvmYulLeanContext for all 36 covered builtin cases
  • concrete bridge smoke tests are no longer needed for any pure builtin

The EDSL exposes pow(a, b) and a ^ b for EVM modular exponentiation. Macro lowering emits a reserved compiler builtin that compiles directly to Yul/EVM exp(a, b).

Higher-Level Expression Operators

Beyond the 15 low-level builtins, the ExprCompileCore proven fragment includes compilation-correctness proofs for 8 higher-level expression operators:

Operator Arity Semantics
min(a, b) binary minimum of two values
max(a, b) binary maximum of two values
ceilDiv(a, b) binary ceiling division (a + b - 1) / b
ite(c, t, e) ternary conditional expression
wMulDown(a, b) binary (a * b) / WAD (WAD = 10^18)
wDivUp(a, b) binary (a * WAD + b - 1) / b
mulDivDown(a, b, c) ternary (a * b) / c
mulDivUp(a, b, c) ternary (a * b + c - 1) / c

These proofs are in Compiler/Proofs/IRGeneration/FunctionBody/Base.lean and Compiler/Proofs/IRGeneration/FunctionBody/Stmt.lean, and cover both IR compilation correctness and end-to-end evaluation semantics.

The compiled mulDivDown / mulDivUp operators still use 256-bit EVM multiplication before division. They are suitable for fixed-point code whose product is known to fit in uint256, but they are not full-precision OpenZeppelin/Solmate Math.mulDiv replacements.

Checked (Safe) Arithmetic

For contracts that require overflow protection, the EDSL provides checked operations:

Operation Type Behavior
safeAdd a b Option Uint256 none if a + b > 2^256 - 1
safeSub a b Option Uint256 none if b > a
safeMul a b Option Uint256 none if a * b > 2^256 - 1
safeDiv a b Option Uint256 none if b = 0
addPanic a b Contract Uint256 reverts with Panic(0x11) if a + b > 2^256 - 1
subPanic a b Contract Uint256 reverts with Panic(0x11) if b > a
mulPanic a b Contract Uint256 reverts with Panic(0x11) if a * b > 2^256 - 1
divPanic a b Contract Uint256 reverts with Panic(0x12) if b = 0
Int256.safeAdd a b Option Int256 none if the mathematical sum is outside [-2^255, 2^255-1]
Int256.safeSub a b Option Int256 none if the mathematical difference is out of range
Int256.safeMul a b Option Int256 none if the mathematical product is out of range
Int256.safeDiv a b Option Int256 none if b = 0 or a = minValue ∧ b = -1
Int256.safeNeg a Option Int256 none if a = minValue
Int256.safeMod a b Option Int256 none if b = 0
addPanic a b Contract Int256 reverts with Panic(0x11) on signed overflow
subPanic a b Contract Int256 reverts with Panic(0x11) on signed overflow
mulPanic a b Contract Int256 reverts with Panic(0x11) on signed overflow
divPanic a b Contract Int256 Panic(0x12) on divide-by-zero; Panic(0x11) on minValue / -1
negPanic a Contract Int256 reverts with Panic(0x11) if a = minValue
modPanic a b Contract Int256 reverts with Panic(0x12) if b = 0
mulDiv512Down? a b c Option Uint256 none if c = 0 or floor(a * b / c) > 2^256 - 1; product is unbounded
mulDiv512Up? a b c Option Uint256 none if c = 0 or ceil(a * b / c) > 2^256 - 1; product is unbounded

Checked operations are explicit EDSL-level constructs. The compiler does not insert overflow checks for bare add/sub/mul, and bare div keeps EVM division-by-zero semantics. Contracts that need checked behavior must explicitly use safeAdd/safeSub/safeMul/safeDiv and handle the Option result. In verity_contract, requireSomeUint (safeAdd ...), requireSomeUint (safeSub ...), requireSomeUint (safeMul ...), and requireSomeUint (safeDiv ...) lower to concrete require guards followed by the corresponding arithmetic result binding. requireSomeUintError (safeAdd ...) ErrorName(args) and the corresponding safeSub/safeMul/safeDiv forms lower to the same guards but emit typed custom errors through requireError. The mulDiv512...? helpers are proof/modeling helpers for full-precision Solidity Math.mulDiv semantics; compiled Yul lowering for a first-class 512-bit division primitive is still tracked by #1761.

Example checked arithmetic with a typed custom error:

errors
  error AddOverflow ()
  error MulOverflow (Uint256, Uint256)

function checked (a : Uint256, b : Uint256) : Uint256 := do
  let sum ← requireSomeUintError (safeAdd a b) AddOverflow()
  let product ← requireSomeUintError (safeMul sum b) MulOverflow(sum, b)
  return product

For Solidity-0.8-style unsigned source models, prefer the panic wrappers addPanic/subPanic/mulPanic/divPanic. For binds such as let total ← addPanic total amount, the verity_contract macro emits the operation's failure predicate in a guarded Stmt.panic, followed by the arithmetic result binding. The exact pair of adjacent statements together form the guard/panic/arithmetic sequence. Overflow and underflow use typed .arithmeticOverflow (0x11); division by zero uses typed .divisionByZero (0x12). This is intentionally different from requireSomeUint ... "Panic(...)": it produces Solidity's canonical Panic(uint256) payload rather than Error(string).

Stmt.panic PanicCode compiles directly to 36 bytes of revert data: selector 0x4e487b71 followed by one ABI word containing the typed code. The separate raw Stmt.panicCode Expr path remains for runtime codes and generated enum guards such as 0x21, and retains expression caching during lowering. When the full checked-helper set is available, CodegenCommon recognizes only the exact typed adjacent pair and replaces it with the corresponding checked helper call. Both operands must be numeric literals or variable references; calls and other compound expressions remain unchanged so the rewrite cannot remove operand effects or change their evaluation order relative to the guard. ECM output is inspected automatically under the same rules, without an opt-in. Deployment and runtime are validated independently against the actual emitted Yul: all four arithmetic helpers and both panic helpers must occur exactly once at top level with canonical signatures/bodies, and no other binding may reuse their names. ECM alone does not insert helpers. Region comments prevent matches across boundaries; malformed markers disable the pass. Reserved ECM marker text inside module output falls back to opacity. Explicit unsafe-Yul remains opaque. Usage analysis likewise requires matching operands, guard, operation, and typed panic constructor; a standalone or raw panic cannot enable the helpers. Generated-model and Yul tests cover all four operations and negative matcher cases. Compiler.Proofs.IRGeneration.PanicPayloadIR proves the abstract memory writes and revert result, which do not observe returned bytes. Compiler.Proofs.YulGeneration.PanicPayloadBytes separately proves the emitted panic AST returns the exact canonical 36-byte payload for any initial memory, using EVMYulLean's byte-addressed memory and revert operations. It includes both typed constructors and a general theorem interpreting numeric codes as EVM words.

The direct Lean definitions of the four wrappers retain their historical diagnostic strings. Those messages are executable-model compatibility behavior, not compiled revert bytes; the macro-generated path bypasses them and emits the canonical payload above.

The same addPanic/subPanic/mulPanic/divPanic bind sources accept Int256 operands. Those lower to signed overflow guards (slt same-sign / sign-change for add and sub, sdiv reconstruction plus the minValue * -1 special case for mul, sdiv with divide-by-zero and minValue / -1 for div). negPanic and modPanic are signed-only. Comparison helpers slt/sgt/sle/sge and isNeg lower to Yul slt/sgt.

Uint256.toInt256 and Int256.toUint256 are bit-reinterpretations with no range check, matching Solidity's int256(uint256(x)) / uint256(int256(x)). They are not checked casts.

Int256 storage fields compile as FieldType.int256 (one EVM word, same layout as uint256) so they round-trip through storage layout reports and #check_contract.

Correctness proofs: Verity/Proofs/Stdlib/Math.lean proves that checked operations return the correct result within bounds and none otherwise (e.g., safeAdd_some, safeAdd_none). Verity/Core/Int256.lean proves the signed *Panic success/failure boundary: success equals the mathematical Int result and failure is exactly the out-of-range condition.

Stdlib.Math also exposes fixed-point helpers mulDivDown, mulDivUp, wMulDown, and wDivUp (the w variants fix the divisor/multiplier to WAD = 10^18). All lemmas are in Verity/Proofs/Stdlib/Math.lean and are intentionally preconditioned: they assume the widened numerator stays within MAX_UINT256.

For full-precision modeling, mulDiv512Down?_some and mulDiv512Up?_some state the exact natural-number quotient returned when the divisor is nonzero and the final quotient fits; the matching _none_of_zero_divisor, _none_of_overflow, _eq_some_iff, _isSome_iff, and _isNone_iff lemmas expose the failure boundary. Successful full-precision results also have direct sandwich lemmas: mulDiv512Down?_mul_le, mulDiv512Down?_lt_succ_mul, mulDiv512Up?_mul_ge, and mulDiv512Up?_mul_le_add_pred, plus one-divisor error-bound lemmas mulDiv512Down?_mul_lt_add and mulDiv512Up?_mul_lt_add. They also mirror the existing mulDiv convenience surface with numerator commutativity, successful-result numerator monotonicity, divisor antitonicity, positivity, zero-numerator, and exact same-denominator cancellation lemmas. Compatibility bridge lemmas mulDiv512Down?_eq_mulDivDown_of_no_overflow and mulDiv512Up?_eq_mulDivUp_of_no_overflow connect the full-precision helpers to the existing 256-bit helpers under the older no-overflow preconditions. Full-precision ceil/floor exactness is covered by mulDiv512Up?_eq_down_of_dvd and mulDiv512Up?_some_succ_of_not_dvd, matching the older 256-bit mulDiv divisibility proof shape. The success/rejection bridge lemmas mulDiv512Down?_isSome_of_up_isSome and mulDiv512Up?_isNone_of_down_isNone connect the two rounding modes. Successful ceil/floor result pairs also expose the same one-step rounding boundary through mulDiv512Down?_le_up, mulDiv512Up?_le_down_add_one, and mulDiv512Up?_eq_down_or_succ.

Verity.Proofs.Stdlib.Automation mirrors the full-precision fit/rejection iff lemmas under automation-friendly names (mulDiv512Down?_some_iff, mulDiv512Down?_none_iff, mulDiv512Up?_some_iff, mulDiv512Up?_none_iff), so downstream proofs can rewrite common quotient-fit side conditions without importing the full arithmetic proof module directly.

Lemma family Generic helpers Wad-specialized helpers
Monotonicity (numerator) mulDivDown_monotone_left/right, mulDivUp_monotone_left/right wMulDown_monotone_left/right, wDivUp_monotone_left
Commutativity mulDivDown_comm, mulDivUp_comm wMulDown_comm
Positivity mulDivDown_pos, mulDivUp_pos wMulDown_pos, wDivUp_pos
Zero collapse mulDivDown_zero_left/right, mulDivUp_zero_left/right wMulDown_zero_left/right, wDivUp_zero
Cancellation / identity mulDivDown_cancel_right/left, mulDivUp_cancel_right/left wMulDown_one_left/right, wDivUp_by_wad
Antitonicity (divisor) mulDivDown_antitone_divisor, mulDivUp_antitone_divisor wDivUp_antitone_right
Rounding gap (ceil vs floor) mulDivUp_le_mulDivDown_add_one, mulDivUp_eq_mulDivDown_or_succ —
Divisibility exactness mulDivUp_eq_mulDivDown_of_dvd, mulDivUp_eq_mulDivDown_add_one_of_not_dvd —
Floor sandwich bounds mulDivDown_mul_le, mulDivDown_mul_lt_add wMulDown_mul_le, wMulDown_mul_lt_add
Ceil sandwich bounds mulDivUp_mul_ge, mulDivUp_mul_lt_add wDivUp_mul_ge, wDivUp_mul_lt_add

The sandwich bounds are especially useful for AMM reserve/share proofs. For BN254/Groth16 public-input proofs, modField_nat_eq, modField_lt, modField_zero, modField_SNARK_SCALAR_FIELD, modField_eq_zero_iff, modField_eq_of_nat_mod_eq, modField_eq_iff_nat_mod_eq, modField_eq_self_of_lt, modField_nat_mod_eq, and modField_idempotent expose the exact SNARK_SCALAR_FIELD reduction semantics used by Stdlib.Math.modField.

Example: See Contracts/SafeCounter/SafeCounter.lean and Contracts/SafeCounter/Proofs/Basic.lean for a contract using checked arithmetic with proven overflow/underflow behavior.

Backend Profiles and Arithmetic

All backend profiles (--backend-profile semantic, solidity-parity-ordering, solidity-parity) use identical wrapping arithmetic semantics. Profiles differ only in Yul output-shape normalization:

  • semantic (default): canonical output order
  • solidity-parity-ordering: dispatch case blocks sorted by selector
  • solidity-parity: selector sorting + deterministic patch pass

The arithmetic model is invariant across profiles. See docs/SOLIDITY_PARITY_PROFILE.md for profile details.

What Is NOT Proved

  • Gas semantics: proofs establish result correctness, not gas cost or bounded liveness.
  • Implicit compiler-layer overflow detection: the compiler does not insert checks for bare arithmetic. Use the EDSL's explicit safe operations or panic wrappers for checked behavior.
  • Whole-contract structured-panic preservation: the exact panic payload is proved for the local emitted AST using EVM memory operations, not full native Yul execution or solc bytecode. Typed and raw panic statements remain outside the current generic SupportedSpec effect fragment. Independently, the post-codegen rewrite from the exact adjacent typed pair (together forming the guard/panic/arithmetic sequence) to a checked helper call is protected by structural matching and regression tests, not an end-to-end preservation theorem.
  • Cryptographic primitives: keccak256 is axiomatized (see AXIOMS.md).
  • Universal bridge equivalence: 25/25 pure EVMYulLean-backed builtins have universal bridge lemmas. All 25 also have context-lifted native bridge theorems. All 8 higher-level expression operators also have proven compilation correctness.

Auditor Checklist

  1. Confirm that the contract's arithmetic assumptions match wrapping semantics.
  2. If overflow or division-by-zero protection is required, verify the contract uses safeAdd/safeSub/safeMul/safeDiv or the corresponding addPanic/subPanic/mulPanic/divPanic wrapper.
  3. Check that safe operations are consumed through requireSomeUint or requireSomeUintError; for Solidity-parity panic behavior, check that the explicit panic wrappers are used instead of a Panic-looking string message.
  4. Review Compiler/Proofs/ArithmeticProfile.lean for the formal wrapping proofs.
  5. Confirm the backend profile does not affect arithmetic behavior (it doesn't).

Related Documents