arr00-testing-oz-contracts 0.0.0 → 5.8.0

package/utils/Base58.sol

@@ -0,0 +1,240 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Contracts (last updated v5.5.0) (utils/Base58.sol)
+
+pragma solidity ^0.8.20;
+
+/**
+ * @dev Provides a set of functions to operate with Base58 strings.
+ *
+ * Base58 is an encoding scheme that converts binary data into a human-readable text format.
+ * Similar to {Base64} but specifically designed for better human usability.
+ *
+ * 1. Human-friendly alphabet: Excludes visually similar characters to reduce human error:
+ *    * No 0 (zero) vs O (capital o) confusion
+ *    * No I (capital i) vs l (lowercase L) confusion
+ *    * No non-alphanumeric characters like + or =
+ * 2. URL-safe: Contains only alphanumeric characters, making it safe for URLs without encoding.
+ *
+ * Initially based on https://github.com/storyicon/base58-solidity/commit/807428e5174e61867e4c606bdb26cba58a8c5cb1[storyicon's implementation] (MIT).
+ * Based on the updated and improved https://github.com/Vectorized/solady/blob/208e4f31cfae26e4983eb95c3488a14fdc497ad7/src/utils/Base58.sol[Vectorized version] (MIT).
+ */
+library Base58 {
+    /// @dev Unrecognized Base58 character on decoding.
+    error InvalidBase58Char(bytes1);
+
+    /**
+     * @dev Encode a `bytes` buffer as a Base58 `string`.
+     */
+    function encode(bytes memory input) internal pure returns (string memory) {
+        return string(_encode(input));
+    }
+
+    /**
+     * @dev Decode a Base58 `string` into a `bytes` buffer.
+     */
+    function decode(string memory input) internal pure returns (bytes memory) {
+        return _decode(bytes(input));
+    }
+
+    function _encode(bytes memory input) private pure returns (bytes memory output) {
+        uint256 inputLength = input.length;
+        if (inputLength == 0) return "";
+
+        assembly ("memory-safe") {
+            // Count number of zero bytes at the beginning of `input`. These are encoded using the same number of '1's
+            // at the beginning of the encoded string.
+            let inputLeadingZeros := 0
+            for {} lt(byte(0, mload(add(add(input, 0x20), inputLeadingZeros))), lt(inputLeadingZeros, inputLength)) {} {
+                inputLeadingZeros := add(inputLeadingZeros, 1)
+            }
+
+            // Start the output offset by an over-estimate of the length.
+            // When converting from base-256 (bytes) to base-58, the theoretical length ratio is log(256)/log(58).
+            // We use 9886/7239 ≈ 1.3657 as a rational approximation that slightly over-estimates to ensure
+            // sufficient memory allocation.
+            let outputLengthEstim := add(inputLeadingZeros, div(mul(sub(inputLength, inputLeadingZeros), 9886), 7239))
+
+            // This is going to be our "scratch" workspace. We leave enough room so that we can store length + encoded output at the FMP location.
+            // 0x21 = 0x20 (32 bytes for result length prefix) + 0x1 (safety buffer for division truncation)
+            let scratch := add(mload(0x40), add(outputLengthEstim, 0x21))
+
+            // Chunk input into 31-byte limbs (248 bits) for efficient batch processing.
+            // Each limb fits safely in a 256-bit word with 8-bit overflow protection.
+            // Memory layout: [output chars] [limb₁(248 bits)][limb₂(248 bits)][limb₃(248 bits)]...
+            //                               ↑ scratch
+            //                               ↑ ptr (moves right)
+            let ptr := scratch
+            for {
+                // Handle partial first limb if input length isn't divisible by 31
+                let i := mod(inputLength, 31)
+                if i {
+                    // Right-shift to align partial limb in high bits of 256-bit word
+                    mstore(ptr, shr(mul(sub(32, i), 8), mload(add(input, 0x20))))
+                    ptr := add(ptr, 0x20) // next limb
+                }
+            } lt(i, inputLength) {
+                ptr := add(ptr, 0x20) // next limb
+                i := add(i, 31) // move in buffer
+            } {
+                // Load 31 bytes from input, right-shift by 8 bits to leave 1 zero byte on the left.
+                mstore(ptr, shr(8, mload(add(add(input, 0x20), i))))
+            }
+
+            // Store the encoding table. This overlaps with the FMP that we are going to reset later anyway.
+            // See https://datatracker.ietf.org/doc/html/draft-msporny-base58-03#section-2
+            mstore(0x1f, "123456789ABCDEFGHJKLMNPQRSTUVWXY")
+            mstore(0x3f, "Zabcdefghijkmnopqrstuvwxyz")
+
+            // Core Base58 encoding: repeated division by 58 on input limbs
+            // Memory layout: [output chars] [limb₁(248 bits)][limb₂(248 bits)][limb₃(248 bits)]...
+            //                               ↑ scratch                          ↑ ptr
+            //                               ↑ output (moves left)
+            //                               ↑ data (moves right)
+            for {
+                let data := scratch // Points to first non-zero limb
+                output := scratch // Builds result right-to-left from scratch
+            } 1 {} {
+                // Skip zero limbs at the beginning (limbs become 0 after repeated divisions)
+                for {} and(iszero(mload(data)), lt(data, ptr)) {
+                    data := add(data, 0x20)
+                } {}
+                // Exit when all limbs are zero (conversion complete)
+                if eq(data, ptr) {
+                    break
+                }
+
+                // Division by 58 across all remaining limbs
+                let carry := 0
+                for {
+                    let i := data
+                } lt(i, ptr) {
+                    i := add(i, 0x20)
+                } {
+                    let acc := add(shl(248, carry), mload(i)) // Combine carry from previous limb with current limb
+                    mstore(i, div(acc, 58)) // Store quotient back in limb
+                    carry := mod(acc, 58) // Remainder becomes next carry
+                }
+
+                // Convert remainder (0-57) to Base58 character and store right-to-left in the output space
+                output := sub(output, 1)
+                mstore8(output, mload(carry))
+            }
+
+            // Write the input leading zeros at the left of the encoded.
+            // This may spill to the left into the "length" of the buffer.
+            for {
+                let i := 0
+            } lt(i, inputLeadingZeros) {} {
+                i := add(i, 0x20)
+                mstore(sub(output, i), "11111111111111111111111111111111")
+            }
+
+            // Move output pointer to account for inputLeadingZeros
+            output := sub(output, add(inputLeadingZeros, 0x20))
+
+            // Store length and allocate (reserve) memory up to scratch.
+            mstore(output, sub(scratch, add(output, 0x20))) // Overwrite spilled bytes
+            mstore(0x40, scratch)
+        }
+    }
+
+    function _decode(bytes memory input) private pure returns (bytes memory output) {
+        bytes4 errorSelector = InvalidBase58Char.selector;
+
+        uint256 inputLength = input.length;
+        if (inputLength == 0) return "";
+
+        assembly ("memory-safe") {
+            let inputLeadingZeros := 0 // Number of leading '1' in `input`.
+            // Count leading zeros. In base58, zeros are represented using '1' (chr(49)).
+            for {} and(
+                eq(byte(0, mload(add(add(input, 0x20), inputLeadingZeros))), 49),
+                lt(inputLeadingZeros, inputLength)
+            ) {} {
+                inputLeadingZeros := add(inputLeadingZeros, 1)
+            }
+
+            // Estimate the output length using the base conversion ratio.
+            // When converting from base-58 to base-256 (bytes), the theoretical length ratio is log(58)/log(256).
+            // We use 6115/8351 ≈ 0.7322 as a rational approximation that slightly over-estimates to ensure
+            // sufficient memory allocation.
+            let outputLengthEstim := add(inputLeadingZeros, div(mul(sub(inputLength, inputLeadingZeros), 6115), 8351))
+
+            // This is going to be our "scratch" workspace. We leave enough room so that we can store length + decoded output at the FMP location.
+            // 0x21 = 0x20 (32 bytes for result length prefix) + 0x1 (safety buffer for division truncation)
+            let scratch := add(mload(0x40), add(outputLengthEstim, 0x21))
+
+            // Store the decoding table for character-to-value lookup. This overlaps with the FMP that we are going to reset later anyway.
+            // Maps ASCII characters (minus 49) to their Base58 numeric values (0-57), with 0xff for invalid characters
+            mstore(0x2a, 0x30313233343536373839)
+            mstore(0x20, 0x1718191a1b1c1d1e1f20ffffffffffff2122232425262728292a2bff2c2d2e2f)
+            mstore(0x00, 0x000102030405060708ffffffffffffff090a0b0c0d0e0f10ff1112131415ff16)
+
+            // Core Base58 decoding: process each character and accumulate into 31-byte limbs
+            // Memory layout: [output bytes] [limb₁(248 bits)][limb₂(248 bits)][limb₃(248 bits)]...
+            //                               ↑ scratch
+            //                               ↑ ptr (moves right as limbs are added)
+            let ptr := scratch
+            let mask := shr(8, not(0))
+            for {
+                let j := 0
+            } lt(j, inputLength) {
+                j := add(j, 1)
+            } {
+                // Decode each character: convert from ASCII to Base58 numeric value (0-57)
+                let c := sub(byte(0, mload(add(add(input, 0x20), j))), 49) // Offset from '1' (ASCII 49)
+
+                // Validate character using bit manipulation: each bit in the bitmask represents a valid character offset
+                // 0x3fff7ff03ffbeff01ff has bits set for all valid Base58 characters (excludes 0, O, I, l)
+                // shl(c, 1) creates a single bit at position c, AND with bitmask checks if character is valid
+                // slither-disable-next-line incorrect-shift
+                if iszero(and(shl(c, 1), 0x3fff7ff03ffbeff01ff)) {
+                    mstore(0, errorSelector)
+                    mstore(4, shl(248, add(c, 49)))
+                    revert(0, 0x24)
+                }
+                let carry := byte(0, mload(c)) // Look up Base58 numeric value from decoding table
+
+                // Multiplication by 58 and addition across all existing limbs
+                for {
+                    let i := scratch
+                } lt(i, ptr) {
+                    i := add(i, 0x20)
+                } {
+                    let acc := add(carry, mul(58, mload(i))) // Multiply limb by 58 and add carry
+                    mstore(i, and(mask, acc)) // Store lower 248 bits back in limb
+                    carry := shr(248, acc) // Upper bits become carry for next limb
+                }
+                // If carry remains, we need a new limb to store the overflow
+                if carry {
+                    mstore(ptr, carry)
+                    ptr := add(ptr, 0x20) // Extend limbs array
+                }
+            }
+
+            // Copy and compact the uint248 limbs + remove any zeros at the beginning.
+            output := scratch
+            for {
+                let i := scratch
+            } lt(i, ptr) {
+                i := add(i, 0x20)
+            } {
+                output := sub(output, 31)
+                mstore(sub(output, 1), mload(i))
+            }
+            for {} lt(byte(0, mload(output)), lt(output, scratch)) {} {
+                output := add(output, 1)
+            }
+
+            // Add the zeros that were encoded in the input (prefix '1's)
+            calldatacopy(sub(output, inputLeadingZeros), calldatasize(), inputLeadingZeros)
+
+            // Move output pointer to account for inputLeadingZeros
+            output := sub(output, add(inputLeadingZeros, 0x20))
+
+            // Store length and allocate (reserve) memory up to scratch.
+            mstore(output, sub(scratch, add(output, 0x20)))
+            mstore(0x40, scratch)
+        }
+    }
+}

package/utils/Base64.sol

@@ -0,0 +1,234 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Contracts (last updated v5.6.0) (utils/Base64.sol)
+
+pragma solidity ^0.8.20;
+
+import {SafeCast} from "./math/SafeCast.sol";
+
+/**
+ * @dev Provides a set of functions to operate with Base64 strings.
+ */
+library Base64 {
+    using SafeCast for bool;
+
+    error InvalidBase64Char(bytes1);
+
+    /**
+     * @dev Converts a `bytes` to its Base64 `string` representation.
+     */
+    function encode(bytes memory data) internal pure returns (string memory) {
+        return string(_encode(data, false));
+    }
+
+    /**
+     * @dev Converts a `bytes` to its Base64Url `string` representation.
+     * Output is not padded with `=` as specified in https://www.rfc-editor.org/rfc/rfc4648[rfc4648].
+     */
+    function encodeURL(bytes memory data) internal pure returns (string memory) {
+        return string(_encode(data, true));
+    }
+
+    /**
+     * @dev Converts a Base64 `string` to the `bytes` it represents.
+     *
+     * * Supports padded and unpadded inputs.
+     * * Supports both encoding ({encode} and {encodeURL}) seamlessly.
+     * * Reverts with {InvalidBase64Char} if the input contains an invalid character.
+     */
+    function decode(string memory data) internal pure returns (bytes memory) {
+        return _decode(bytes(data));
+    }
+
+    /**
+     * @dev Internal table-agnostic encoding
+     *
+     * Padding is enabled when using the Base64 table, and disabled when using the Base64Url table.
+     * See sections 4 and 5 of https://datatracker.ietf.org/doc/html/rfc4648
+     */
+    function _encode(bytes memory data, bool urlAndFilenameSafe) private pure returns (bytes memory result) {
+        /**
+         * Inspired by Brecht Devos (Brechtpd) implementation - MIT license
+         * https://github.com/Brechtpd/base64/blob/e78d9fd951e7b0977ddca77d92dc85183770daf4/base64.sol
+         */
+        if (data.length == 0) return "";
+
+        // Padding is enabled by default, but disabled when the "urlAndFilenameSafe" alphabet is used
+        //
+        // If padding is enabled, the final length should be `bytes` data length divided by 3 rounded up and then
+        // multiplied by 4 so that it leaves room for padding the last chunk
+        // - `data.length + 2`  -> Prepare for division rounding up
+        // - `/ 3`              -> Number of 3-bytes chunks (rounded up)
+        // - `4 *`              -> 4 characters for each chunk
+        // This is equivalent to: 4 * Math.ceil(data.length / 3)
+        //
+        // If padding is disabled, the final length should be `bytes` data length multiplied by 4/3 rounded up as
+        // opposed to when padding is required to fill the last chunk.
+        // - `4 * data.length`  -> 4 characters for each chunk
+        // - ` + 2`             -> Prepare for division rounding up
+        // - `/ 3`              -> Number of 3-bytes chunks (rounded up)
+        // This is equivalent to: Math.ceil((4 * data.length) / 3)
+        uint256 resultLength = urlAndFilenameSafe ? (4 * data.length + 2) / 3 : 4 * ((data.length + 2) / 3);
+
+        assembly ("memory-safe") {
+            result := mload(0x40)
+
+            // Store the encoding table in the scratch space (and fmp ptr) to avoid memory allocation
+            //
+            // Base64    (ascii)  A B C D E F G H I J K L M N O P Q R S T U V W X Y Z a b c d e f g h i j k l m n o p q r s t u v w x y z 0 1 2 3 4 5 6 7 8 9 + /
+            // Base64    (hex)   4142434445464748494a4b4c4d4e4f505152535455565758595a6162636465666768696a6b6c6d6e6f707172737475767778797a303132333435363738392b2f
+            // Base64Url (ascii)  A B C D E F G H I J K L M N O P Q R S T U V W X Y Z a b c d e f g h i j k l m n o p q r s t u v w x y z 0 1 2 3 4 5 6 7 8 9 - _
+            // Base64Url (hex)   4142434445464748494a4b4c4d4e4f505152535455565758595a6162636465666768696a6b6c6d6e6f707172737475767778797a303132333435363738392d5f
+            // xor       (hex)   00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000670
+            mstore(0x1f, "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdef")
+            mstore(0x3f, xor("ghijklmnopqrstuvwxyz0123456789+/", mul(urlAndFilenameSafe, 0x670)))
+
+            // Prepare result pointer, jump over length
+            let resultPtr := add(result, 0x20)
+            let resultEnd := add(resultPtr, resultLength)
+            let dataPtr := data
+            let endPtr := add(data, mload(data))
+
+            // In some cases, the last iteration will read bytes after the end of the data. We cache the value, and
+            // set it to zero to make sure no dirty bytes are read in that section.
+            let afterPtr := add(endPtr, 0x20)
+            let afterCache := mload(afterPtr)
+            mstore(afterPtr, 0x00)
+
+            // Run over the input, 3 bytes at a time
+            for {} lt(dataPtr, endPtr) {} {
+                // Advance 3 bytes
+                dataPtr := add(dataPtr, 3)
+                let input := mload(dataPtr)
+
+                // To write each character, shift the 3 byte (24 bits) chunk
+                // 4 times in blocks of 6 bits for each character (18, 12, 6, 0)
+                // and apply logical AND with 0x3F to bitmask the least significant 6 bits.
+                // Use this as an index into the lookup table, mload an entire word
+                // so the desired character is in the least significant byte, and
+                // mstore8 this least significant byte into the result and continue.
+                mstore8(resultPtr, mload(and(shr(18, input), 0x3F)))
+                resultPtr := add(resultPtr, 1) // Advance
+                mstore8(resultPtr, mload(and(shr(12, input), 0x3F)))
+                resultPtr := add(resultPtr, 1) // Advance
+                mstore8(resultPtr, mload(and(shr(6, input), 0x3F)))
+                resultPtr := add(resultPtr, 1) // Advance
+                mstore8(resultPtr, mload(and(input, 0x3F)))
+                resultPtr := add(resultPtr, 1) // Advance
+            }
+
+            // Reset the value that was cached
+            mstore(afterPtr, afterCache)
+
+            if iszero(urlAndFilenameSafe) {
+                // When data `bytes` is not exactly 3 bytes long
+                // it is padded with `=` characters at the end
+                switch mod(mload(data), 3)
+                case 1 {
+                    mstore8(sub(resultPtr, 1), 0x3d)
+                    mstore8(sub(resultPtr, 2), 0x3d)
+                }
+                case 2 {
+                    mstore8(sub(resultPtr, 1), 0x3d)
+                }
+            }
+
+            // Store result length and update FMP to reserve allocated space
+            mstore(result, resultLength)
+            mstore(0x40, resultEnd)
+        }
+    }
+
+    /**
+     * @dev Internal decoding
+     */
+    function _decode(bytes memory data) private pure returns (bytes memory result) {
+        bytes4 errorSelector = InvalidBase64Char.selector;
+
+        uint256 dataLength = data.length;
+        if (dataLength == 0) return "";
+
+        uint256 resultLength = (dataLength / 4) * 3;
+        if (dataLength % 4 == 0) {
+            resultLength -= (data[dataLength - 1] == "=").toUint() + (data[dataLength - 2] == "=").toUint();
+        } else {
+            resultLength += (dataLength % 4) - 1;
+        }
+
+        assembly ("memory-safe") {
+            result := mload(0x40)
+
+            // Temporarily store the reverse lookup table between in memory. This spans from 0x00 to 0x50, Using:
+            // - all 64bytes of scratch space
+            // - part of the FMP (at location 0x40)
+            mstore(0x30, 0x2425262728292a2b2c2d2e2f30313233)
+            mstore(0x20, 0x0a0b0c0d0e0f10111213141516171819ffffffff3fff1a1b1c1d1e1f20212223)
+            mstore(0x00, 0x3eff3eff3f3435363738393a3b3c3dffffff00ffffff00010203040506070809)
+
+            // Prepare result pointer, jump over length
+            let dataPtr := data
+            let resultPtr := add(result, 0x20)
+            let endPtr := add(resultPtr, resultLength)
+
+            // In some cases, the last iteration will read bytes after the end of the data. We cache the value, and
+            // set it to "==" (fake padding) to make sure no dirty bytes are read in that section.
+            let afterPtr := add(add(data, 0x20), dataLength)
+            let afterCache := mload(afterPtr)
+            mstore(afterPtr, shl(240, 0x3d3d))
+
+            // loop while not everything is decoded
+            for {} lt(resultPtr, endPtr) {} {
+                dataPtr := add(dataPtr, 4)
+
+                // Read a 4 bytes chunk of data
+                let input := mload(dataPtr)
+
+                // Decode each byte in the chunk as a 6 bit block, and align them to form a block of 3 bytes
+                let a := sub(byte(28, input), 43)
+                // slither-disable-next-line incorrect-shift
+                if iszero(and(shl(a, 1), 0xffffffd0ffffffc47ff5)) {
+                    mstore(0, errorSelector)
+                    mstore(4, shl(248, add(a, 43)))
+                    revert(0, 0x24)
+                }
+                let b := sub(byte(29, input), 43)
+                // slither-disable-next-line incorrect-shift
+                if iszero(and(shl(b, 1), 0xffffffd0ffffffc47ff5)) {
+                    mstore(0, errorSelector)
+                    mstore(4, shl(248, add(b, 43)))
+                    revert(0, 0x24)
+                }
+                let c := sub(byte(30, input), 43)
+                // slither-disable-next-line incorrect-shift
+                if iszero(and(shl(c, 1), 0xffffffd0ffffffc47ff5)) {
+                    mstore(0, errorSelector)
+                    mstore(4, shl(248, add(c, 43)))
+                    revert(0, 0x24)
+                }
+                let d := sub(byte(31, input), 43)
+                // slither-disable-next-line incorrect-shift
+                if iszero(and(shl(d, 1), 0xffffffd0ffffffc47ff5)) {
+                    mstore(0, errorSelector)
+                    mstore(4, shl(248, add(d, 43)))
+                    revert(0, 0x24)
+                }
+
+                mstore(
+                    resultPtr,
+                    or(
+                        or(shl(250, byte(0, mload(a))), shl(244, byte(0, mload(b)))),
+                        or(shl(238, byte(0, mload(c))), shl(232, byte(0, mload(d))))
+                    )
+                )
+
+                resultPtr := add(resultPtr, 3)
+            }
+
+            // Reset the value that was cached
+            mstore(afterPtr, afterCache)
+
+            // Store result length and update FMP to reserve allocated space
+            mstore(result, resultLength)
+            mstore(0x40, endPtr)
+        }
+    }
+}