immutable-constants

# Immutable & Constant Variables ## When to Use Each | Type | Set At | Stored In | SLOAD Cost | Use Case | |------|--------|-----------|------------|----------| | `constant` | Compile time | Bytecode (inlined) | 0 gas | Known at write time: math constants, hashes, selectors | | `immutable` | Deploy time (constructor) | Bytecode (appended) | 0 gas | Known at deploy: addresses, chain IDs, config | | Storage | Runtime | Storage slot | 2,100 cold / 100 warm | Must change after deployment | ## Constant Variables Must be known at compile time. Value is inlined everywhere it's used. ```solidity contract Constants { // Numeric constants uint256 public constant MAX_BPS = 10_000; uint256 public constant WAD = 1e18; uint256 public constant RAY = 1e27; uint256 public constant PRECISION = 1e18; // Hash constants — computed at compile time bytes32 public constant ADMIN_ROLE = keccak256("ADMIN_ROLE"); bytes32 public constant MINTER_ROLE = keccak256("MINTER_ROLE"); // EIP-712 type hashes bytes32 public constant PERMIT_TYPEHASH = keccak256( "Permit(address owner,address spender,uint256 value,uint256 nonce,uint256 deadline)" ); // EIP-1967 slots bytes32 internal constant _IMPLEMENTATION_SLOT = bytes32(uint256(keccak256("eip1967.proxy.implementation")) - 1); // Selector constants bytes4 public constant TRANSFER_SELECTOR = IERC20.transfer.selector; } ``` ### What Can Be Constant - Literal values (`uint256`, `int256`, `bool`, `address`, `bytes1`-`bytes32`) - `keccak256()` of literal values - Expressions evaluated at compile time - **Cannot** be `constant`: values depending on runtime state, `block.timestamp`, `msg.sender` ## Immutable Variables Set once in the constructor, stored in bytecode. Cannot be changed after deployment. ```solidity contract ImmutableConfig { address public immutable WETH; address public immutable FACTORY; address public immutable ORACLE; uint256 public immutable DEPLOYMENT_CHAIN_ID; uint256 public immutable CREATED_AT; uint8 public immutable UNDERLYING_DECIMALS; constructor( address weth, address factory, address oracle, address underlying ) { if (weth == address(0)) revert ZeroAddress(); if (factory == address(0)) revert ZeroAddress(); if (oracle == address(0)) revert ZeroAddress(); WETH = weth; FACTORY = factory; ORACLE = oracle; DEPLOYMENT_CHAIN_ID = block.chainid; CREATED_AT = block.timestamp; UNDERLYING_DECIMALS = IERC20Metadata(underlying).decimals(); } } ``` ### Immutable Rules - Must be assigned in the constructor (or inline for simple expressions) - Cannot be assigned in any other function - Cannot be used in upgradeable contracts with initializers (no constructor runs) - Value types only: `address`, `uint*`, `int*`, `bool`, `bytes1`-`bytes32` - **Cannot** be `immutable`: `string`, `bytes`, arrays, structs, mappings ## Gas Comparison ```solidity contract GasComparison { // Storage: 2,100 gas cold SLOAD, 100 gas warm SLOAD address public storageVar; // Immutable: 0 gas — loaded from bytecode via PUSH32 address public immutable immutableVar; // Constant: 0 gas — inlined at every usage site uint256 public constant CONSTANT_VAR = 42; constructor(address _addr) { storageVar = _addr; immutableVar = _addr; } // Reading storageVar: ~2,100 gas (cold) or ~100 gas (warm) // Reading immutableVar: ~3 gas (PUSH32) // Reading CONSTANT_VAR: ~3 gas (PUSH32, inlined) } ``` ### Real-World Savings For a function that reads an address 3 times: - Storage: 2,100 + 100 + 100 = **2,300 gas** - Immutable: 3 + 3 + 3 = **9 gas** (savings: 2,291 gas) ## Bytes32 vs String for Constants ```solidity // BAD: string constant — still uses dynamic encoding string public constant NAME = "MyProtocol"; // GOOD: bytes32 constant — fixed size, cheaper to read and compare bytes32 public constant NAME = "MyProtocol"; // Converting bytes32 to string (offchain or in rare onchain cases) function nameAsString() external pure returns (string memory) { return string(abi.encodePacked(NAME)); } ``` ## Naming Conventions ```solidity // Constants: UPPER_SNAKE_CASE uint256 public constant MAX_SUPPLY = 1_000_000e18; // Immutables: UPPER_SNAKE_CASE (they're functionally constant post-deploy) address public immutable TREASURY; // Storage variables: camelCase uint256 public totalDeposited; ``` ## Immutables in Upgradeable Contracts Immutables are stored in bytecode, not storage. In upgradeable proxies, the proxy reads the **implementation's** bytecode. This means immutables can be used in implementations — they're set in the implementation's constructor (which runs at deployment, not through the proxy). ```solidity contract VaultImplementation is Initializable { // These are set when the implementation contract is deployed address public immutable WETH; address public immutable FACTORY; constructor(address weth, address factory) { WETH = weth; FACTORY = factory; _disableInitializers(); } function initialize(address admin) external initializer { // Storage variables set here (via proxy's storage) __Ownable_init(admin); } } ``` ## Checklist - [ ] All values known at compile time are `constant` - [ ] All values known at deploy time (but not compile time) are `immutable` - [ ] Only values that change post-deployment use storage - [ ] Constructor validates all immutable values (zero-address checks) - [ ] UPPER_SNAKE_CASE naming for both `constant` and `immutable` - [ ] `bytes32` preferred over `string` for short constant strings - [ ] Immutables in upgradeable contracts are in the implementation constructor