assembly-patterns

# Assembly Patterns ## When to Use Assembly Only use assembly when: 1. Gas savings are **measured** (not assumed) via `forge test --gas-report` 2. The optimization is in a **hot path** (called frequently) 3. Solidity cannot express the operation (e.g., specific memory layout) 4. Savings exceed 500 gas per call for the added complexity Always add `@dev` NatSpec explaining why assembly is used and what it does. ## Memory Management EVM memory layout: - `0x00-0x3f` (64 bytes): Scratch space for hashing - `0x40-0x5f` (32 bytes): Free memory pointer - `0x60-0x7f` (32 bytes): Zero slot ```solidity /// @dev Efficiently computes keccak256(abi.encodePacked(a, b)) using scratch space. function efficientHash(bytes32 a, bytes32 b) internal pure returns (bytes32 result) { assembly { mstore(0x00, a) mstore(0x20, b) result := keccak256(0x00, 0x40) } } ``` ## Efficient Hashing Hashing pairs for Merkle trees — avoids memory allocation overhead. ```solidity /// @dev Hashes a leaf pair for Merkle tree construction. Sorts to ensure /// consistent ordering regardless of input order. function hashPair(bytes32 a, bytes32 b) internal pure returns (bytes32 result) { assembly { // Sort to produce canonical ordering switch lt(a, b) case 1 { mstore(0x00, a) mstore(0x20, b) } default { mstore(0x00, b) mstore(0x20, a) } result := keccak256(0x00, 0x40) } } ``` ## Bitwise Packing and Unpacking Pack multiple values into a single uint256 for storage efficiency. ```solidity /// @dev Packs owner (160 bits), amount (80 bits), timestamp (16 bits) into uint256. function pack(address owner, uint80 amount, uint16 ts) internal pure returns (uint256 packed) { assembly { packed := or(or(shl(96, owner), shl(16, amount)), ts) } } function unpackOwner(uint256 packed) internal pure returns (address owner) { assembly { owner := shr(96, packed) } } function unpackAmount(uint256 packed) internal pure returns (uint80 amount) { assembly { amount := and(shr(16, packed), 0xffffffffffffffffffff) // 80-bit mask } } function unpackTimestamp(uint256 packed) internal pure returns (uint16 ts) { assembly { ts := and(packed, 0xffff) } } ``` ## Custom Errors in Assembly Revert with custom error selectors without Solidity overhead. ```solidity error Unauthorized(); // selector: 0x82b42900 error InsufficientBalance(uint256 available, uint256 required); /// @dev Reverts with Unauthorized() using minimal gas. function _revertUnauthorized() internal pure { assembly { mstore(0x00, 0x82b42900) // Unauthorized() selector revert(0x1c, 0x04) // offset to align 4-byte selector } } /// @dev Reverts with InsufficientBalance(available, required). function _revertInsufficientBalance(uint256 available, uint256 required) internal pure { assembly { let ptr := mload(0x40) mstore(ptr, 0xf4d678b8) // InsufficientBalance selector mstore(add(ptr, 0x04), available) mstore(add(ptr, 0x24), required) revert(add(ptr, 0x1c), 0x44) // 4 + 32 + 32 = 68 bytes } } ``` ## Low-Level Calls ```solidity /// @dev Performs a low-level call and bubbles up revert data on failure. function _call(address target, bytes memory data) internal returns (bytes memory) { (bool success, bytes memory returndata) = target.call(data); if (!success) { assembly { // Bubble up the revert reason revert(add(returndata, 0x20), mload(returndata)) } } return returndata; } ``` ## Return Data Handling ```solidity /// @dev Checks if a call returned true (for ERC-20 compatibility). /// Handles tokens that return nothing (USDT), false, or true. function _callOptionalReturn(address token, bytes memory data) internal { (bool success, bytes memory returndata) = token.call(data); if (!success) { assembly { revert(add(returndata, 0x20), mload(returndata)) } } // If returndata is present, it must decode to true if (returndata.length > 0) { if (abi.decode(returndata, (bool)) == false) { revert TokenCallFailed(); } } } ``` ## Efficient Address Checks ```solidity /// @dev Checks if an address is a contract (has code). Uses extcodesize. function isContract(address account) internal view returns (bool result) { assembly { result := gt(extcodesize(account), 0) } } /// @dev Reverts if addr is the zero address. function _requireNonZero(address addr) internal pure { assembly { if iszero(addr) { mstore(0x00, 0xd92e233d) // ZeroAddress() selector revert(0x1c, 0x04) } } } ``` ## Efficient Event Emission ```solidity /// @dev Emits Transfer(from, to, amount) without Solidity ABI encoding overhead. function _emitTransfer(address from, address to, uint256 amount) internal { assembly { // Transfer(address,address,uint256) topic let sig := 0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef mstore(0x00, amount) log3(0x00, 0x20, sig, from, to) } } ``` ## Safety Rules 1. **Never use assembly for simple operations** that Solidity handles well 2. **Always validate inputs** before assembly blocks — assembly skips Solidity's type safety 3. **Document every assembly block** with NatSpec explaining the operation 4. **Test extensively** — assembly bugs are silent and devastating 5. **Use `returndatasize()` instead of hardcoded sizes** when reading return data 6. **Avoid `mstore` past the free memory pointer** without updating it 7. **Never use `selfdestruct`** in assembly (deprecated, behavior changes post-Dencun) ## Assembly Checklist - [ ] Gas savings measured with `forge test --gas-report` (before/after) - [ ] Savings exceed 500 gas in a hot path - [ ] NatSpec `@dev` comment explains why assembly is used - [ ] All memory operations respect the free memory pointer - [ ] No writes to reserved memory areas (0x00-0x3f) that persist beyond scratch use - [ ] Return data handling uses `returndatasize()` not hardcoded lengths - [ ] Edge cases tested: zero values, max values, empty calldata