Add Base58 library

.changeset/afraid-chicken-attack.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`Bytes`: Add `splice(bytes,uint256)` and `splice(bytes,uint256,uint256)`, two "in place" variants of the existing slice functions

.changeset/loose-lamps-bake.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`Base58`: Add a library for encoding and decoding bytes buffers into base58 strings.

.changeset/thirty-pugs-pick.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`Bytes`: Add `countLeading` and `countConsecutive`

contracts/mocks/Stateless.sol

@@ -7,6 +7,7 @@ pragma solidity ^0.8.26;
 import {Address} from "../utils/Address.sol";
 import {Arrays} from "../utils/Arrays.sol";
 import {AuthorityUtils} from "../access/manager/AuthorityUtils.sol";
+import {Base58} from "../utils/Base58.sol";
 import {Base64} from "../utils/Base64.sol";
 import {BitMaps} from "../utils/structs/BitMaps.sol";
 import {Blockhash} from "../utils/Blockhash.sol";

contracts/utils/Base58.sol

@@ -0,0 +1,184 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.26;
+
+import {SafeCast} from "./math/SafeCast.sol";
+import {Bytes} from "./Bytes.sol";
+
+/**
+ * @dev Provides a set of functions to operate with Base58 strings.
+ *
+ * Based on https://github.com/storyicon/base58-solidity/commit/807428e5174e61867e4c606bdb26cba58a8c5cb1[storyicon's implementation] (MIT).
+ */
+library Base58 {
+    using SafeCast for bool;
+    using Bytes for bytes;
+
+    error InvalidBase56Digit(uint8);
+
+    /**
+     * @dev Base58 encoding & decoding tables
+     * See sections 2 of https://datatracker.ietf.org/doc/html/draft-msporny-base58-03
+     */
+    bytes internal constant _TABLE = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+    bytes internal constant _LOOKUP_TABLE =
+        hex"000102030405060708ffffffffffffff090a0b0c0d0e0f10ff1112131415ff161718191a1b1c1d1e1f20ffffffffffff2122232425262728292a2bff2c2d2e2f30313233343536373839";
+
+    /**
+     * @dev Encode a `bytes` buffer as a Base58 `string`.
+     */
+    function encode(bytes memory data) internal pure returns (string memory) {
+        return string(_encode(data));
+    }
+
+    /**
+     * @dev Decode a Base58 `string` into a `bytes` buffer.
+     */
+    function decode(string memory data) internal pure returns (bytes memory) {
+        return _decode(bytes(data));
+    }
+
+    function _encode(bytes memory data) private pure returns (bytes memory encoded) {
+        // For reference, solidity implementation
+        // unchecked {
+        //     uint256 dataLeadingZeros = data.countLeading(0x00);
+        //     uint256 length = dataLeadingZeros + ((data.length - dataLeadingZeros) * 8351) / 6115 + 1;
+        //     encoded = new bytes(length);
+        //     uint256 end = length;
+        //     for (uint256 i = 0; i < data.length; ++i) {
+        //         uint256 ptr = length;
+        //         for (uint256 carry = uint8(data[i]); ptr > end || carry != 0; --ptr) {
+        //             carry += 256 * uint8(encoded[ptr - 1]);
+        //             encoded[ptr - 1] = bytes1(uint8(carry % 58));
+        //             carry /= 58;
+        //         }
+        //         end = ptr;
+        //     }
+        //     uint256 encodedCLZ = encoded.countLeading(0x00);
+        //     length -= encodedCLZ - dataLeadingZeros;
+        //     encoded.splice(encodedCLZ - dataLeadingZeros);
+        //     for (uint256 i = 0; i < length; ++i) {
+        //         encoded[i] = _TABLE[uint8(encoded[i])];
+        //     }
+        // }
+
+        // Assembly is ~50% cheaper for buffers of size 32.
+        assembly ("memory-safe") {
+            function clzBytes(ptr, length) -> i {
+                for {
+                    i := 0
+                } and(iszero(byte(0, mload(add(ptr, i)))), lt(i, length)) {
+                    i := add(i, 1)
+                } {}
+            }
+
+            encoded := mload(0x40)
+            let dataLength := mload(data)
+
+            // Count number of zero bytes at the beginning of `data`. These are encoded using the same number of '1's
+            // at then beginning of the encoded string.
+            let dataLeadingZeros := clzBytes(add(data, 0x20), dataLength)
+
+            // Initial encoding length: 100% of zero bytes (zero prefix) + 138% of non zero bytes + 1
+            let slotLength := add(add(div(mul(sub(dataLength, dataLeadingZeros), 138), 100), dataLeadingZeros), 1)
+
+            // Zero the encoded buffer
+            for {
+                let i := 0
+            } lt(i, slotLength) {
+                i := add(i, 0x20)
+            } {
+                mstore(add(add(encoded, 0x20), i), 0)
+            }
+
+            // Build the "slots"
+            for {
+                let i := 0
+                let end := slotLength
+            } lt(i, dataLength) {
+                i := add(i, 1)
+            } {
+                let ptr := slotLength
+                for {
+                    let carry := byte(0, mload(add(add(data, 0x20), i)))
+                } or(carry, lt(end, ptr)) {
+                    ptr := sub(ptr, 1)
+                    carry := div(carry, 58)
+                } {
+                    carry := add(carry, mul(256, byte(0, mload(add(add(encoded, 0x1f), ptr)))))
+                    mstore8(add(add(encoded, 0x1f), ptr), mod(carry, 58))
+                }
+                end := ptr
+            }
+
+            // Count number of zero bytes at the beginning of slots. This is a pointer to the first non zero slot that
+            // contains the base58 data. This base58 data span over `slotLength-slotLeadingZeros` bytes.
+            let slotLeadingZeros := clzBytes(add(encoded, 0x20), slotLength)
+
+            // Update length: `slotLength-slotLeadingZeros` of non-zero data plus `dataLeadingZeros` of zero prefix.
+            let offset := sub(slotLeadingZeros, dataLeadingZeros)
+            let encodedLength := sub(slotLength, offset)
+
+            // Store the encoding table. This overlaps with the FMP that we are going to reset later anyway.
+            mstore(0x1f, "123456789ABCDEFGHJKLMNPQRSTUVWXY")
+            mstore(0x3f, "Zabcdefghijkmnopqrstuvwxyz")
+
+            // For each slot, use the table to obtain the corresponding base58 "digit".
+            for {
+                let i := 0
+            } lt(i, encodedLength) {
+                i := add(i, 1)
+            } {
+                mstore8(add(add(encoded, 0x20), i), mload(byte(0, mload(add(add(encoded, 0x20), add(offset, i))))))
+            }
+
+            // Store length and allocate (reserve) memory
+            mstore(encoded, encodedLength)
+            mstore(0x40, add(add(encoded, 0x20), encodedLength))
+        }
+    }
+
+    function _decode(bytes memory data) private pure returns (bytes memory) {
+        unchecked {
+            uint256 b58Length = data.length;
+
+            uint256 size = 2 * ((b58Length * 8351) / 6115 + 1);
+            bytes memory binu = new bytes(size);
+
+            bytes memory cache = _LOOKUP_TABLE;
+            uint256 outiLength = (b58Length + 3) / 4;
+            // Note: allocating uint32[] would be enough, but solidity doesn't pack memory.
+            uint256[] memory outi = new uint256[](outiLength);
+            for (uint256 i = 0; i < data.length; ++i) {
+                // get b58 char
+                uint8 chr = uint8(data[i]);
+                require(chr > 48 && chr < 123, InvalidBase56Digit(chr));
+
+                // decode b58 char
+                uint256 carry = uint8(cache[chr - 49]);
+                require(carry < 58, InvalidBase56Digit(chr));
+
+                for (uint256 j = outiLength; j > 0; --j) {
+                    uint256 value = carry + 58 * outi[j - 1];
+                    carry = value >> 32;
+                    outi[j - 1] = value & 0xffffffff;
+                }
+            }
+
+            uint256 ptr = 0;
+            uint256 mask = ((b58Length - 1) % 4) + 1;
+            for (uint256 j = 0; j < outiLength; ++j) {
+                while (mask > 0) {
+                    --mask;
+                    binu[ptr] = bytes1(uint8(outi[j] >> (8 * mask)));
+                    ++ptr;
+                }
+                mask = 4;
+            }
+
+            uint256 dataLeadingZeros = data.countLeading(0x31);
+            uint256 msb = binu.countConsecutive(dataLeadingZeros, 0x00);
+            return binu.splice(msb * (dataLeadingZeros + msb < binu.length).toUint(), ptr);
+        }
+    }
+}

contracts/utils/Base64.sol

@@ -8,21 +8,21 @@ pragma solidity ^0.8.20;
  */
 library Base64 {
     /**
-     * @dev Base64 Encoding/Decoding Table
+     * @dev Base64 encoding table
      * See sections 4 and 5 of https://datatracker.ietf.org/doc/html/rfc4648
      */
     string internal constant _TABLE = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
     string internal constant _TABLE_URL = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
 
     /**
-     * @dev Converts a `bytes` to its Bytes64 `string` representation.
+     * @dev Converts a `bytes` to its Base64 `string` representation.
      */
     function encode(bytes memory data) internal pure returns (string memory) {
         return _encode(data, _TABLE, true);
     }
 
     /**
-     * @dev Converts a `bytes` to its Bytes64Url `string` representation.
+     * @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) {

contracts/utils/Bytes.sol

@@ -68,6 +68,28 @@ library Bytes {
         }
     }
 
+    /**
+     * @dev Count number of occurrences of `search` at the beginning of `buffer`.
+     */
+    function countLeading(bytes memory buffer, bytes1 search) internal pure returns (uint256) {
+        return countConsecutive(buffer, 0, search);
+    }
+
+    /**
+     * @dev Count number of occurrences of `search` in `buffer`, starting from position `offset`.
+     */
+    function countConsecutive(bytes memory buffer, uint256 offset, bytes1 search) internal pure returns (uint256 i) {
+        uint256 length = Math.saturatingSub(buffer.length, offset);
+        assembly ("memory-safe") {
+            for {
+                let ptr := add(add(buffer, 0x20), offset)
+                i := 0
+            } and(iszero(shr(248, xor(mload(add(ptr, i)), search))), lt(i, length)) {
+                i := add(i, 1)
+            } {}
+        }
+    }
+
     /**
      * @dev Copies the content of `buffer`, from `start` (included) to the end of `buffer` into a new bytes object in
      * memory.
@@ -99,6 +121,35 @@ library Bytes {
         return result;
     }
 
+    /**
+     * @dev In place slice: moves the content of `buffer`, from `start` (included) to the end of `buffer` to the start of that buffer.
+     *
+     * NOTE: This function modifies the provided buffer in place. If you need to preserve the original buffer, use {slice} instead
+     */
+    function splice(bytes memory buffer, uint256 start) internal pure returns (bytes memory) {
+        return splice(buffer, start, buffer.length);
+    }
+
+    /**
+     * @dev In place slice: moves the content of `buffer`, from `start` (included) to end (excluded) to the start of that buffer.
+     *
+     * NOTE: This function modifies the provided buffer in place. If you need to preserve the original buffer, use {slice} instead
+     */
+    function splice(bytes memory buffer, uint256 start, uint256 end) internal pure returns (bytes memory) {
+        // sanitize
+        uint256 length = buffer.length;
+        end = Math.min(end, length);
+        start = Math.min(start, end);
+
+        // allocate and copy
+        assembly ("memory-safe") {
+            mcopy(add(buffer, 0x20), add(add(buffer, 0x20), start), sub(end, start))
+            mstore(buffer, sub(end, start))
+        }
+
+        return buffer;
+    }
+
     /**
      * @dev Reads a bytes32 from a bytes array without bounds checking.
      *

contracts/utils/README.adoc

@@ -24,6 +24,7 @@ Miscellaneous contracts and libraries containing utility functions you can use t
  * {Create2}: Wrapper around the https://blog.openzeppelin.com/getting-the-most-out-of-create2/[`CREATE2` EVM opcode] for safe use without having to deal with low-level assembly.
  * {Address}: Collection of functions for overloading Solidity's https://docs.soliditylang.org/en/latest/types.html#address[`address`] type.
  * {Arrays}: Collection of functions that operate on https://docs.soliditylang.org/en/latest/types.html#arrays[`arrays`].
+ * {Base58}: On-chain base58 encoding and decoding.
  * {Base64}: On-chain base64 and base64URL encoding according to https://datatracker.ietf.org/doc/html/rfc4648[RFC-4648].
  * {Bytes}: Common operations on bytes objects.
  * {Calldata}: Helpers for manipulating calldata.
@@ -105,6 +106,8 @@ Ethereum contracts have no native concept of an interface, so applications must
 
 {{Arrays}}
 
+{{Base58}}
+
 {{Base64}}
 
 {{Bytes}}

test/utils/Base58.t.sol

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.26;
+
+import {Test} from "forge-std/Test.sol";
+import {Base58} from "@openzeppelin/contracts/utils/Base58.sol";
+
+contract Base58Test is Test {
+    function testEncodeDecodeEmpty() external pure {
+        assertEq(Base58.decode(Base58.encode("")), "");
+    }
+
+    function testEncodeDecodeZeros() external pure {
+        bytes memory zeros = hex"0000000000000000";
+        assertEq(Base58.decode(Base58.encode(zeros)), zeros);
+
+        bytes memory almostZeros = hex"00000000a400000000";
+        assertEq(Base58.decode(Base58.encode(almostZeros)), almostZeros);
+    }
+
+    function testEncodeDecode(bytes memory input) external pure {
+        assertEq(Base58.decode(Base58.encode(input)), input);
+    }
+}