YUL and Byte Manipulation: Going Low-Level in Solidity

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

contract FunctionalAssemblyExample {
    function addUsingFunctionalAssembly(uint x, uint y) public pure returns (uint) {
        uint result;
        
        assembly {
            // Create local variables within the assembly block
            let xVal := x      // Copy the value of x to the assembly variable xVal
            let yVal := y      // Copy the value of y to the assembly variable yVal
            
            // Perform addition using the EVM's 'add' operation
            result := add(xVal, yVal)
        }
        
        return result;  // Return the value computed in assembly
    }
}

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

contract InstructionalAssemblyExample {
    function addUsingInstructionalAssembly(uint x, uint y) public pure returns (uint) {
        uint result;
        
        assembly {
            // Push the value of x onto the stack
            // When a variable name appears alone, its value is pushed onto the stack
            x  // This pushes the value of x onto the stack
            
            // Push the value of y onto the stack
            // The stack now contains [y, x] (with y at the top)
            y  // This pushes the value of y onto the stack
            
            // Execute the 'add' opcode
            // This pops the top two values from the stack (y and x),
            // adds them together, and pushes the result back onto the stack
            add  // Stack now contains [x+y]
            
            // Store the value at the top of the stack into 'result'
            // The =: operator assigns the top of the stack to the variable on the right
            =: result  // Pop the value from the stack and assign to result
            
            // At this point, the stack is empty again
        }
        
        return result;
    }
}

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

contract YulExample {
    // Function that multiplies two numbers and implements conditional logic
    function multiply(uint256 a, uint256 b) public pure returns (uint256 result) {
        assembly {
            // Simple Yul multiplication using the mul opcode
            // In Yul, operations look like function calls
            result := mul(a, b)  // Multiply a and b, store in result
            
            // If-statement in Yul - checks if result < 10
            if lt(result, 10) {
                // If the result is less than 10, set it to 0
                result := 0
            }
        }
    }
    
    // Function demonstrating more complex Yul features
    function complexYul(uint256 input) public pure returns (uint256 output) {
        assembly {
            // Variable declaration with 'let' keyword
            let doubledInput := mul(input, 2)  // input * 2
            
            // Switch statement example
            switch doubledInput
            case 0 { 
                output := 0  // If doubledInput = 0, set output to 0
            }
            case 1 { 
                output := 10  // If doubledInput = 1, set output to 10
            }
            case 2 { 
                output := 20  // If doubledInput = 2, set output to 20
            }
            default { 
                output := doubledInput  // Otherwise, use doubledInput as-is
            }
            
            // For loop example in Yul
            for { let i := 0 } lt(i, 5) { i := add(i, 1) } {
                // Add the loop counter to output in each iteration
                output := add(output, i)  // output += i
            }
        }
    }
}

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

// Import OpenZeppelin's proxy contracts
import "@openzeppelin/contracts/proxy/ERC1967/ERC1967Proxy.sol";
import "@openzeppelin/contracts/proxy/beacon/UpgradeableBeacon.sol";
import "@openzeppelin/contracts/proxy/transparent/TransparentUpgradeableProxy.sol";

/**
 * @title MyContract
 * @dev Initial implementation contract with basic functionality
 * 
 * This contract represents the first version of our logic. It has minimal
 * functionality - just storing and retrieving a value.
 */
contract MyContract {
    // State variable that will be stored in the proxy's storage
    uint256 public value;
    
    /**
     * @notice Set the contract's value
     * @param _value The new value to store
     */
    function setValue(uint256 _value) external {
        value = _value;
    }
}

/**
 * @title UpgradedContract
 * @dev Enhanced implementation with additional functionality
 * 
 * This contract represents the second version of our logic with new features.
 * It maintains compatibility with the original storage layout to avoid corrupting data.
 */
contract UpgradedContract {
    // IMPORTANT: Storage layout must be compatible with MyContract
    // This variable must remain in the same slot as in the original contract
    uint256 public value;
    
    // New state variable added in the upgrade
    string public name;
    
    /**
     * @notice Set the contract's value (same as in original contract)
     * @param _value The new value to store
     */
    function setValue(uint256 _value) external {
        value = _value;
    }
    
    /**
     * @notice Set the contract's name (new function added in the upgrade)
     * @param _name The new name to store
     */
    function setName(string calldata _name) external {
        name = _name;
    }
}

/**
 * @title ProxyExample
 * @dev Demonstrates deploying and upgrading proxy contracts
 * 
 * This contract shows the complete lifecycle of an upgradeable contract system:
 * 1. Deploy initial implementation
 * 2. Deploy proxy pointing to implementation
 * 3. Deploy new implementation
 * 4. Upgrade proxy to new implementation
 */
contract ProxyExample {
    // Storage for the implementation contract address
    address public implementation;
    
    // Storage for the proxy contract address
    address public proxy;
    
    /**
     * @notice Deploy the initial implementation and proxy
     * @dev Sets up the initial proxy system with MyContract as the implementation
     * 
     * How proxy contracts work:
     * - The proxy holds the state (storage)
     * - The implementation holds the logic (code)
     * - When you call the proxy, it uses delegatecall to execute the implementation's code with the proxy's storage
     */
    function deployProxy() external {
        // Deploy the implementation contract (the logic)
        implementation = address(new MyContract());
        
        // Deploy the proxy pointing to our implementation
        // The TransparentUpgradeableProxy will delegatecall into the implementation for all function calls
        proxy = address(new TransparentUpgradeableProxy(
            implementation,      // The implementation address (logic contract)
            msg.sender,          // Admin account - has permission to upgrade the proxy
            ""                   // No initialization data for this example
        ));
        
        // Now users can interact with the proxy address as if it were a MyContract instance
        // while the actual logic is executed from the implementation address
    }
    
    /**
     * @notice Upgrade the proxy to a new implementation
     * @dev Deploys a new implementation and updates the proxy to point to it
     * 
     * The key to upgrades:
     * - The proxy's storage remains unchanged
     * - Only the target of delegatecall (the implementation address) is updated
     * - This way, all state is preserved while the logic can be replaced
     */
    function upgradeProxy() external {
        // Deploy the new implementation (with enhanced functionality)
        address newImplementation = address(new UpgradedContract());
        
        // Upgrade the proxy to point to the new implementation
        // This changes where delegatecall goes, but preserves all storage
        TransparentUpgradeableProxy(payable(proxy)).upgradeTo(newImplementation);
        
        // Now users can still interact with the same proxy address
        // but they'll have access to the new functions in UpgradedContract
        // and all the previous state data is preserved
    }
}

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

// Import OpenZeppelin's cryptography utilities for signature recovery
import "@openzeppelin/contracts/utils/cryptography/ECDSA.sol";

/**
 * @title SignatureVerification
 * @dev Demonstrates verifying digital signatures created off-chain
 * 
 * This contract shows how to implement off-chain signing and on-chain verification
 * using OpenZeppelin's ECDSA library, which is a common pattern for:
 * - Meta-transactions (gasless transactions)
 * - Off-chain authorizations
 * - Verifying data originated from a specific user
 */
contract SignatureVerification {
    // Apply the ECDSA library to bytes32 type
    using ECDSA for bytes32;
    
    // Map each address to its current nonce (for replay protection)
    mapping(address => uint256) public nonces;
    
    /**
     * @notice Verify that a signature was created by a specific address
     * @dev Reconstructs the original message and recovers the signer
     * @param signer The address that supposedly signed the message
     * @param amount The amount included in the signed message
     * @param nonce Unique number to prevent replay attacks
     * @param signature The signature bytes (r, s, v components combined)
     * @return True if the signature is valid, false otherwise
     * 
     * Signature verification process:
     * 1. Recreate the exact message hash that was signed
     * 2. Convert it to an Ethereum signed message hash format
     * 3. Recover the signer address from the signature
     * 4. Check if the recovered address matches the expected signer
     */
    function verifySignature(
        address signer,
        uint256 amount,
        uint256 nonce,
        bytes calldata signature
    ) public view returns (bool) {
        // Step 1: Recreate the message hash that was signed off-chain
        // The parameters must be packed in the exact same order as when the signature was created
        bytes32 messageHash = keccak256(abi.encodePacked(
            signer,         // Who is signing
            amount,         // What amount they're authorizing
            nonce,          // Unique nonce to prevent replays
            address(this)   // Contract address for security (prevents cross-contract replay)
        ));
        
        // Step 2: Convert to an Ethereum signed message hash
        // This adds the "Ethereum Signed Message:
32" prefix to comply with EIP-191
        // This prefix is automatically added by wallet software when a user signs a message
        bytes32 ethSignedMessageHash = messageHash.toEthSignedMessageHash();
        
        // Step 3: Recover the signer's address from the signature
        // The ECDSA recovery algorithm uses the signature to derive the public key that created it
        address recoveredSigner = ethSignedMessageHash.recover(signature);
        
        // Step 4: Check if the recovered address matches the expected signer
        return recoveredSigner == signer;
    }
    
    /**
     * @notice Process a transaction that was authorized by an off-chain signature
     * @dev Verifies the signature and executes the intended operation
     * @param amount The amount from the signed message
     * @param nonce The nonce from the signed message (must match the current nonce)
     * @param signature The cryptographic signature authorizing the action
     * 
     * Common use cases:
     * - Gasless transactions where a relayer pays gas but user authorizes action
     * - Batching multiple operations into a single transaction
     * - Permission delegation without giving full contract access
     */
    function processSignedTransaction(
        uint256 amount,
        uint256 nonce,
        bytes calldata signature
    ) external {
        // Check that the nonce matches the expected next nonce for the sender
        // This prevents replay attacks where the same signature is used multiple times
        require(nonce == nonces[msg.sender], "Invalid nonce");
        
        // Verify that the signature is valid and created by the sender
        require(
            verifySignature(msg.sender, amount, nonce, signature),
            "Invalid signature"
        );
        
        // If we get here, the signature is valid and the nonce is correct
        
        // Execute the intended operation
        // ... implementation details ...
        
        // Increment the nonce to prevent the signature from being used again
        nonces[msg.sender]++;
    }
}

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

// Import OpenZeppelin's BitMaps library for efficient boolean storage
import "@openzeppelin/contracts/utils/structs/BitMaps.sol";

/**
 * @title WhitelistWithBitMap
 * @dev Demonstrates using bitmaps for gas-efficient boolean storage
 * 
 * This contract shows how to use OpenZeppelin's BitMaps library to
 * optimize storage costs when dealing with large numbers of boolean flags.
 */
contract WhitelistWithBitMap {
    // Use the BitMaps library with the BitMap struct
    using BitMaps for BitMaps.BitMap;
    
    // Declare a bitmap storage structure
    // Behind the scenes, this is a mapping(uint256 => uint256) where:
    // - The outer key is the "index" (which 256-bit chunk)
    // - The inner value is a 256-bit word where each bit represents a boolean
    BitMaps.BitMap private userMembership;
    
    /**
     * @notice Add a user to the whitelist
     * @dev Sets the bit at position userId to 1 (true)
     * @param userId The ID of the user to add
     * 
     * How it works internally:
     * 1. Calculate which storage slot (index) contains this bit: userId / 256
     * 2. Calculate which bit position within that slot: userId % 256
     * 3. Use a bitmask operation to set just that bit to 1
     */
    function addToWhitelist(uint256 userId) external {
        userMembership.set(userId);
    }
    
    /**
     * @notice Remove a user from the whitelist
     * @dev Sets the bit at position userId to 0 (false)
     * @param userId The ID of the user to remove
     * 
     * Similar to set(), but uses a different bitmask to clear the bit:
     * map[index] &= ~(1 << (userId % 256))
     */
    function removeFromWhitelist(uint256 userId) external {
        userMembership.unset(userId);
    }
    
    /**
     * @notice Check if a user is in the whitelist
     * @dev Reads the bit at position userId
     * @param userId The ID of the user to check
     * @return True if the user is whitelisted, false otherwise
     * 
     * Gets the value by checking if the specific bit is set:
     * return (map[index] & (1 << (userId % 256))) != 0
     */
    function isWhitelisted(uint256 userId) external view returns (bool) {
        return userMembership.get(userId);
    }
    
    // ---- Comparison with Traditional Approach ----
    
    // Traditional way: one storage slot per boolean (very inefficient)
    mapping(uint256 => bool) private traditionalWhitelist;
    
    /**
     * @notice Add a user using the traditional approach
     * @dev Stores a complete bool value - uses an entire storage slot per user
     * @param userId The ID of the user to add
     */
    function addTraditional(uint256 userId) external {
        traditionalWhitelist[userId] = true;
    }
    
    // Storage Efficiency Comparison:
    // - Traditional: 1 user = 1 storage slot = 20,000 gas for first write
    // - BitMap: 256 users = 1 storage slot = ~20,000 gas for first write of the slot
    //
    // This means BitMap is up to 256x more storage-efficient for large numbers of boolean values!
}

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

/**
 * @title ByteBasics
 * @dev Demonstrates fundamental operations with byte arrays in Solidity
 * 
 * This contract shows basic byte array manipulation techniques using
 * native Solidity operations without any external libraries.
 */
contract ByteBasics {
    /**
     * @notice Concatenate two byte arrays into a single array
     * @dev Uses abi.encodePacked which is the most gas-efficient way to combine byte arrays
     * @param a First byte array
     * @param b Second byte array
     * @return A new byte array containing a followed by b
     * 
     * abi.encodePacked is a low-level function that tightly packs the arguments
     * without padding, making it ideal for byte array concatenation.
     */
    function concatenate(bytes memory a, bytes memory b) public pure returns (bytes memory) {
        // abi.encodePacked will tightly pack the arguments without any padding
        // This is the most efficient way to concatenate byte arrays in Solidity
        return abi.encodePacked(a, b);
        
        // Note: An alternative approach would be to create a new array of the 
        // appropriate size and copy bytes manually, but that would be less efficient
    }
    
    /**
     * @notice Extract a section from a byte array
     * @dev Manually copies bytes from the source array to a newly allocated array
     * @param data Source byte array
     * @param start Starting index (0-based)
     * @param length Number of bytes to extract
     * @return A new byte array containing the specified substring
     * 
     * Solidity doesn't have built-in substring functions for bytes, so we
     * need to implement this manually by:
     * 1. Creating a new bytes array of the desired length
     * 2. Copying bytes one by one from the source to the new array
     */
    function substring(bytes memory data, uint256 start, uint256 length) public pure returns (bytes memory) {
        // Check bounds to prevent accessing memory outside the array
        require(start + length <= data.length, "Out of bounds");
        
        // Allocate a new byte array of the specified length
        bytes memory result = new bytes(length);
        
        // Manual byte-by-byte copy from data to result
        for (uint256 i = 0; i < length; i++) {
            // In Solidity, bytes arrays can be indexed like normal arrays
            // This copies one byte at a time from source to destination
            result[i] = data[start + i];
        }
        
        return result;
    }
    
    /**
     * @notice Compare two byte arrays for equality
     * @dev Uses keccak256 hash comparison for gas efficiency
     * @param a First byte array
     * @param b Second byte array
     * @return True if the arrays contain identical bytes, false otherwise
     * 
     * Direct comparison of dynamic arrays is not possible in Solidity.
     * The most efficient approach is to hash both arrays and compare the hashes.
     */
    function equal(bytes memory a, bytes memory b) public pure returns (bool) {
        // Calculate keccak256 hash of each byte array
        // If the arrays are identical, their hashes will be identical
        return keccak256(a) == keccak256(b);
        
        // Note: This is much more gas efficient than comparing byte-by-byte,
        // especially for large arrays, but it does have a small cost for the hash calculation
    }
}

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

// Import the BytesLib library for advanced byte manipulation
import "solidity-bytes-utils/contracts/BytesLib.sol";

/**
 * @title AdvancedByteOperations
 * @dev Demonstrates using the solidity-bytes-utils library for advanced byte manipulations
 * 
 * This contract shows how to use the BytesLib library for operations that would
 * be complex or gas-inefficient to implement manually.
 */
contract AdvancedByteOperations {
    // Apply the BytesLib library to the bytes type
    // This allows us to call library functions as if they were methods on bytes arrays
    using BytesLib for bytes;
    
    /**
     * @notice Demonstrate various advanced byte operations
     * @dev Shows several BytesLib functions: concat, slice, and type conversions
     * @return A tuple containing the results of various operations:
     *         - concat: The result of concatenating two byte arrays
     *         - slice: A section extracted from the concatenated array
     *         - toUint8: The first byte converted to a uint8
     *         - toBytes32: The first 32 bytes converted to bytes32
     *         - toAddress: The first 20 bytes converted to an address
     * 
     * BytesLib provides optimized implementations of these operations using
     * assembly for better gas efficiency.
     */
    function demonstrateByteUtils() public pure returns (
        bytes memory concat,
        bytes memory slice,
        uint8 toUint8,
        bytes32 toBytes32,
        address toAddress
    ) {
        // Define two byte arrays using hex literals
        // hex"..." is a convenient way to define byte arrays with exact values
        bytes memory a = hex"deadbeef";                  // 4 bytes: [0xde, 0xad, 0xbe, 0xef]
        bytes memory b = hex"0123456789abcdef";          // 8 bytes: [0x01, 0x23, 0x45, ...]
        
        // Concatenate bytes using the library's concat function
        // This returns a new byte array containing a followed by b
        concat = a.concat(b);
        // concat now contains: [0xde, 0xad, 0xbe, 0xef, 0x01, 0x23, 0x45, ...]
        
        // Slice a section from the concatenated bytes
        // Parameters: (startIndex, length)
        // This extracts 8 bytes starting from index 4
        slice = concat.slice(4, 8);
        // slice contains b's bytes: [0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef]
        
        // Convert bytes to different data types
        
        // Convert the first byte to a uint8 (8-bit unsigned integer)
        // Parameter: starting position in the array
        toUint8 = b.toUint8(0);  // 0x01 = 1 in decimal
        
        // Convert the first 32 bytes to a bytes32 value (or fewer if array is smaller)
        // Parameter: starting position in the array
        toBytes32 = b.toBytes32(0);  // 0x0123456789abcdef000...000 (padded with zeros)
        
        // Convert the first 20 bytes to an address (or fewer if array is smaller)
        // Parameter: starting position in the array
        toAddress = b.toAddress(0);  // 0x0123456789abcdefXXXXXX (where X is zero padding)
    }
    
    /**
     * @notice Find the position of a pattern within a byte array
     * @dev Uses BytesLib's indexOf function to locate a subsequence
     * @param data The byte array to search in
     * @param pattern The byte pattern to search for
     * @return The position of the pattern, or -1 if not found
     * 
     * This is similar to string search functions in other languages,
     * but optimized for byte arrays in Solidity.
     */
    function findPattern(bytes memory data, bytes memory pattern) public pure returns (int) {
        // Search for pattern starting from index 0
        // Returns -1 if pattern is not found
        return data.indexOf(pattern, 0);
    }
}

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

/**
 * @title YulMemoryManagement
 * @dev Demonstrates low-level memory manipulation using Yul
 * 
 * This contract shows how to efficiently copy byte arrays in memory using
 * Yul assembly, which can be more gas-efficient than Solidity's built-in operations.
 */
contract YulMemoryManagement {
    /**
     * @notice Create an efficient copy of a byte array
     * @dev Uses Yul assembly to copy 32 bytes at a time for efficiency
     * @param source The source byte array to copy
     * @return A new byte array with the same contents as source
     * 
     * Solidity's memory model:
     * - Dynamic arrays in memory are stored as: [length][data]
     * - The first 32 bytes (a word) store the length of the array
     * - The data follows immediately after the length
     */
    function efficientCopy(bytes memory source) public pure returns (bytes memory) {
        // Allocate a new bytes array of the same length as source
        bytes memory result = new bytes(source.length);
        
        // Use assembly for more efficient memory operations
        assembly {
            // Get the memory pointers to the data portions of the arrays
            // add(x, 0x20) skips the 32-byte length field at the start of the array
            let sourcePtr := add(source, 0x20)  // Pointer to start of source data
            let resultPtr := add(result, 0x20)  // Pointer to start of result data
            
            // Load the length of the source array from its first 32 bytes
            let length := mload(source)
            
            // Copy the data in 32-byte chunks using a for loop
            // This is much more efficient than copying byte by byte
            for { let i := 0 } lt(i, length) { i := add(i, 0x20) } {
                // Check if we have at least 32 bytes left to copy
                // If we don't, the last iteration will handle the remainder
                if lt(sub(length, i), 0x20) {
                    // We've reached the point where there's less than 32 bytes left
                    // Break the loop and handle the remainder separately
                    break
                }
                
                // Copy 32 bytes from source to result
                // mload loads 32 bytes from memory starting at the given address
                // mstore stores 32 bytes to memory at the given address
                mstore(
                    add(resultPtr, i),        // Destination address
                    mload(add(sourcePtr, i))  // Source data (32 bytes)
                )
            }
            
            // Handle any remaining bytes (if length is not a multiple of 32)
            let remainder := mod(length, 0x20)
            if gt(remainder, 0) {
                // Calculate position of the last chunk
                let position := sub(length, remainder)
                
                // Create a mask for the remaining bytes
                // This ensures we only copy the bytes we need and don't
                // overwrite memory beyond our array
                
                // First, create a mask of all 1s
                let mask := 0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
                
                // Then shift it to match the number of bits we need
                // This creates a mask with 1s in the bit positions we want to keep
                mask := shl(mul(8, sub(0x20, remainder)), mask)
                
                // Load 32 bytes from the source position
                let value := mload(add(sourcePtr, position))
                
                // Apply the mask to keep only the bytes we need
                value := and(value, mask)
                
                // Store the masked value in the result
                mstore(add(resultPtr, position), value)
            }
        }
        
        return result;
    }
}

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

/**
 * @title YulCustomHash
 * @dev Demonstrates implementing a custom hash function using Yul
 * 
 * This contract shows how to implement a custom hash function using Yul assembly
 * for cryptographic purposes.
 */
contract YulCustomHash {
    /**
     * @notice Hash a message using Yul assembly
     * @dev Uses Yul assembly to implement a custom hash function
     * @param message The message to hash
     * @return The hash of the message
     * 
     * This is a simple example of a custom hash function implementation.
     * In a real-world scenario, you would use a more robust hashing algorithm.
     */
    function hash(string memory message) public pure returns (bytes32) {
        bytes memory messageBytes = bytes(message);
        bytes32 hash;
        
        assembly {
            let i := 0
            let length := mload(messageBytes)
            
            for { } lt(i, length) { i := add(i, 1) } {
                hash := keccak256(add(messageBytes, 0x20), length)
            }
        }
        
        return hash;
    }
}