integer-overflow

# Integer Safety ## Solidity 0.8+ Automatic Checks Since Solidity 0.8, arithmetic operations revert on overflow/underflow by default. This eliminates the need for SafeMath but introduces new considerations. ```solidity // These all revert automatically on overflow (Solidity 0.8+) uint256 a = type(uint256).max; uint256 b = a + 1; // reverts: arithmetic overflow uint256 c = 0; uint256 d = c - 1; // reverts: arithmetic underflow uint8 e = 255; uint8 f = e + 1; // reverts: arithmetic overflow ``` ## Unchecked Blocks Use `unchecked` when overflow is **mathematically impossible** and gas savings matter. ```solidity // SAFE: loop counter cannot overflow (bounded by array length) for (uint256 i; i < arr.length;) { processItem(arr[i]); unchecked { ++i; } } // SAFE: subtraction will not underflow (checked by prior condition) function withdraw(uint256 amount) external { uint256 balance = balances[msg.sender]; if (balance < amount) revert InsufficientBalance(); unchecked { balances[msg.sender] = balance - amount; // balance >= amount guaranteed } } // SAFE: hash computation (intentional wrapping) unchecked { uint256 hash = uint256(keccak256(abi.encodePacked(a))) + nonce; } ``` ### When Unchecked Is Dangerous ```solidity // DANGEROUS: user-controlled values in unchecked unchecked { uint256 result = userInput1 + userInput2; // could overflow silently } // DANGEROUS: complex arithmetic with multiple operations unchecked { uint256 result = (a * b + c) / d; // any step could overflow } ``` ## Phantom Overflow Intermediate calculations can overflow even when the final result fits. ```solidity // VULNERABLE: a * b can overflow even if (a * b) / c fits in uint256 function mulDiv(uint256 a, uint256 b, uint256 c) internal pure returns (uint256) { return a * b / c; // reverts if a * b > type(uint256).max } // Example: mulDiv(2e18, 3e18, 1e18) should return 6e18 // But 2e18 * 3e18 = 6e36, which overflows uint256? No, 6e36 < 2^256 // But mulDiv(type(uint128).max, type(uint128).max, 1) WILL overflow // FIXED: use Solmate's FixedPointMathLib which handles phantom overflow import {FixedPointMathLib} from "solmate/utils/FixedPointMathLib.sol"; function mulDiv(uint256 a, uint256 b, uint256 c) internal pure returns (uint256) { return FixedPointMathLib.mulDiv(a, b, c); // assembly-based, no phantom overflow } ``` ### mulDiv Implementation Concept ```solidity // FixedPointMathLib.mulDiv uses 512-bit intermediate math in assembly: // 1. Compute full 512-bit product of a * b // 2. Divide the 512-bit result by c // 3. Return the 256-bit quotient (reverts if it doesn't fit) ``` ## Safe Casting Narrowing casts can silently truncate in Solidity. Always use explicit safe casting. ```solidity // VULNERABLE: silent truncation uint256 bigNumber = 300; uint8 small = uint8(bigNumber); // small = 44 (300 % 256), NO revert! // SAFE: explicit overflow check import {SafeCast} from "@openzeppelin/contracts/utils/math/SafeCast.sol"; using SafeCast for uint256; uint256 bigNumber = 300; uint8 small = bigNumber.toUint8(); // reverts: SafeCast: value doesn't fit in 8 bits ``` ### Common Safe Cast Operations ```solidity using SafeCast for uint256; using SafeCast for int256; uint256 value = 1000; uint128 a = value.toUint128(); // reverts if > type(uint128).max uint96 b = value.toUint96(); // reverts if > type(uint96).max uint64 c = value.toUint64(); // reverts if > type(uint64).max uint48 d = value.toUint48(); // reverts if > type(uint48).max uint32 e = value.toUint32(); // reverts if > type(uint32).max int256 signed = int256(value); // reverts if > type(int256).max ``` ## Type Boundaries ```solidity // Know your type limits type(uint8).max == 255 type(uint16).max == 65_535 type(uint32).max == 4_294_967_295 type(uint48).max == 281_474_976_710_655 type(uint64).max == 18_446_744_073_709_551_615 type(uint96).max == 79_228_162_514_264_337_593_543_950_335 type(uint128).max == 340_282_366_920_938_463_463_374_607_431_768_211_455 type(uint256).max == 2^256 - 1 type(int256).min == -(2^255) type(int256).max == 2^255 - 1 ``` ## Signed Integer Gotchas ```solidity // Negation overflow: -type(int256).min overflows int256 minValue = type(int256).min; int256 negated = -minValue; // REVERTS: overflow (no positive equivalent) // Division edge case int256 result = type(int256).min / (-1); // REVERTS: same as negation overflow // Abs function must handle min value function abs(int256 x) internal pure returns (uint256) { if (x == type(int256).min) revert AbsOverflow(); return uint256(x >= 0 ? x : -x); } ``` ## Accumulator Overflow For accounting that accumulates over time, consider if the accumulator can overflow. ```solidity // Reward accumulator pattern // rewardPerTokenStored grows continuously — can it overflow uint256? // With 1e18 precision and 1e18 rewards/sec for 100 years: // 1e18 * 1e18 * 100 * 365 * 86400 ≈ 3.15e33, well under 2^256 ≈ 1.15e77 // Safe for practical purposes, but document the assumption uint256 public rewardPerTokenStored; function rewardPerToken() public view returns (uint256) { if (totalSupply == 0) return rewardPerTokenStored; return rewardPerTokenStored + ( (lastRewardTime() - lastUpdateTime) * rewardRate * PRECISION / totalSupply ); } ``` ## Integer Safety Checklist - [ ] `unchecked` only used where overflow is mathematically impossible - [ ] Comment explaining why overflow is impossible for each `unchecked` block - [ ] No silent narrowing casts — use SafeCast - [ ] mulDiv from Solmate for multiplication followed by division - [ ] Accumulator overflow analyzed for worst-case scenarios - [ ] Signed integer edge cases handled (`type(int256).min`) - [ ] Type boundaries documented for packed struct fields