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

/// @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.

/// @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.

/// @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)
    }
}