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,133 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.24;
+
+import {SafeCast} from "./math/SafeCast.sol";
+import {Bytes} from "./Bytes.sol";
+
+/**
+ * @dev Provides a set of functions to operate with Base58 strings.
+ *
+ * Based on the original https://github.com/storyicon/base58-solidity/commit/807428e5174e61867e4c606bdb26cba58a8c5cb1[implementation of storyicon] (MIT).
+ */
+library Base58 {
+    using SafeCast for bool;
+    using Bytes for bytes;
+
+    error InvalidBase56Digit(uint8);
+
+    bytes internal constant _TABLE = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+    bytes internal constant _LOOKUP_TABLE =
+        hex"000102030405060708ffffffffffffff090a0b0c0d0e0f10ff1112131415ff161718191a1b1c1d1e1f20ffffffffffff2122232425262728292a2bff2c2d2e2f30313233343536373839";
+
+    function encode(bytes memory data) internal pure returns (string memory) {
+        return string(_encode(data));
+    }
+
+    function decode(string memory data) internal pure returns (bytes memory) {
+        return _decode(bytes(data));
+    }
+
+    function _encode(bytes memory data) private pure returns (bytes memory) {
+        unchecked {
+            uint256 dataCLZ = data.countLeading(0x00);
+            uint256 length = dataCLZ + ((data.length - dataCLZ) * 8351) / 6115 + 1;
+            bytes memory slot = new bytes(length);
+
+            uint256 end = length;
+            for (uint256 i = 0; i < data.length; i++) {
+                uint256 ptr = length;
+                for (uint256 carry = _mload8i(data, i); ptr > end || carry != 0; --ptr) {
+                    carry += 256 * _mload8i(slot, ptr - 1);
+                    _mstore8i(slot, ptr - 1, uint8(carry % 58));
+                    carry /= 58;
+                }
+                end = ptr;
+            }
+
+            uint256 slotCLZ = slot.countLeading(0x00);
+            length -= slotCLZ - dataCLZ;
+            slot.splice(slotCLZ - dataCLZ);
+
+            bytes memory cache = _TABLE;
+            for (uint256 i = 0; i < length; ++i) {
+                // equivalent to `slot[i] = TABLE[slot[i]];`
+                _mstore8(slot, i, _mload8(cache, _mload8i(slot, i)));
+            }
+
+            return slot;
+        }
+    }
+
+    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 = _mload8i(data, i);
+                require(chr > 48 && chr < 123, InvalidBase56Digit(chr));
+
+                // decode b58 char
+                uint256 carry = _mload8i(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;
+                    _mstore8(binu, ptr, bytes1(uint8(outi[j] >> (8 * mask))));
+                    ptr++;
+                }
+                mask = 4;
+            }
+
+            uint256 dataCLZ = data.countLeading(0x31);
+            uint256 msb = binu.countConsecutive(dataCLZ, 0x00);
+            return binu.splice(msb * (dataCLZ + msb < binu.length).toUint(), ptr);
+        }
+    }
+
+    function _mload8(bytes memory buffer, uint256 offset) private pure returns (bytes1 value) {
+        // This is not memory safe in the general case, but all calls to this private function are within bounds.
+        assembly ("memory-safe") {
+            value := mload(add(add(buffer, 0x20), offset))
+        }
+    }
+
+    function _mload8i(bytes memory buffer, uint256 offset) private pure returns (uint8 value) {
+        // This is not memory safe in the general case, but all calls to this private function are within bounds.
+        assembly ("memory-safe") {
+            value := shr(248, mload(add(add(buffer, 0x20), offset)))
+        }
+    }
+
+    function _mstore8(bytes memory buffer, uint256 offset, bytes1 value) private pure {
+        // This is not memory safe in the general case, but all calls to this private function are within bounds.
+        assembly ("memory-safe") {
+            mstore8(add(add(buffer, 0x20), offset), shr(248, value))
+        }
+    }
+
+    function _mstore8i(bytes memory buffer, uint256 offset, uint8 value) private pure {
+        // This is not memory safe in the general case, but all calls to this private function are within bounds.
+        assembly ("memory-safe") {
+            mstore8(add(add(buffer, 0x20), offset), value)
+        }
+    }
+}

contracts/utils/Bytes.sol

@@ -68,6 +68,42 @@ 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 = buffer.length;
+        if (offset > length) return 0;
+
+        assembly ("memory-safe") {
+            let chunk
+            let end := sub(length, offset)
+            for {
+                i := 0
+            } lt(i, end) {
+                i := add(i, 1)
+            } {
+                // every 32 bytes, load a new chunk
+                if iszero(mod(i, 0x20)) {
+                    chunk := mload(add(buffer, add(0x20, add(offset, i))))
+                }
+                // if the first byte of the chunk does not match the search element, exit
+                if shr(248, xor(chunk, search)) {
+                    break
+                }
+                // shift chunk
+                chunk := shl(8, chunk)
+            }
+        }
+    }
+
     /**
      * @dev Copies the content of `buffer`, from `start` (included) to the end of `buffer` into a new bytes object in
      * memory.
@@ -99,6 +135,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.20;
+
+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);
+    }
+}

test/utils/Base58.test.js

@@ -0,0 +1,37 @@
+const { ethers } = require('hardhat');
+const { expect } = require('chai');
+const { loadFixture } = require('@nomicfoundation/hardhat-network-helpers');
+
+async function fixture() {
+  const mock = await ethers.deployContract('$Base58');
+  return { mock };
+}
+
+describe('Base58', function () {
+  beforeEach(async function () {
+    Object.assign(this, await loadFixture(fixture));
+  });
+
+  describe('base58', function () {
+    describe('encode/decode', function () {
+      for (const length of [0, 1, 2, 3, 4, 32, 42, 128, 384]) // 512 runs out of gas
+        it(`buffer of length ${length}`, async function () {
+          const buffer = ethers.randomBytes(length);
+          const hex = ethers.hexlify(buffer);
+          const b58 = ethers.encodeBase58(buffer);
+
+          await expect(this.mock.$encode(hex)).to.eventually.equal(b58);
+          await expect(this.mock.$decode(b58)).to.eventually.equal(hex);
+        });
+    });
+
+    describe('decode invalid format', function () {
+      for (const chr of ['I', '-', '~'])
+        it(`Invalid base58 char ${chr}`, async function () {
+          await expect(this.mock.$decode(`VYRWKp${chr}pnN7`))
+            .to.be.revertedWithCustomError(this.mock, 'InvalidBase56Digit')
+            .withArgs(chr.codePointAt(0));
+        });
+    });
+  });
+});

test/utils/Base64.test.js

@@ -11,7 +11,7 @@ async function fixture() {
   return { mock };
 }
 
-describe('Strings', function () {
+describe('Base64', function () {
   beforeEach(async function () {
     Object.assign(this, await loadFixture(fixture));
   });
@@ -27,8 +27,8 @@ describe('Strings', function () {
     ])
       it(title, async function () {
         const buffer = Buffer.from(input, 'ascii');
-        expect(await this.mock.$encode(buffer)).to.equal(ethers.encodeBase64(buffer));
-        expect(await this.mock.$encode(buffer)).to.equal(expected);
+        await expect(this.mock.$encode(buffer)).to.eventually.equal(ethers.encodeBase64(buffer));
+        await expect(this.mock.$encode(buffer)).to.eventually.equal(expected);
       });
   });
 
@@ -43,8 +43,8 @@ describe('Strings', function () {
     ])
       it(title, async function () {
         const buffer = Buffer.from(input, 'ascii');
-        expect(await this.mock.$encodeURL(buffer)).to.equal(base64toBase64Url(ethers.encodeBase64(buffer)));
-        expect(await this.mock.$encodeURL(buffer)).to.equal(expected);
+        await expect(this.mock.$encodeURL(buffer)).to.eventually.equal(base64toBase64Url(ethers.encodeBase64(buffer)));
+        await expect(this.mock.$encodeURL(buffer)).to.eventually.equal(expected);
       });
   });
 
@@ -53,7 +53,7 @@ describe('Strings', function () {
     const buffer32 = ethers.id('example');
     const buffer31 = buffer32.slice(0, -2);
 
-    expect(await mock.encode(buffer31)).to.equal(ethers.encodeBase64(buffer31));
-    expect(await mock.encode(buffer32)).to.equal(ethers.encodeBase64(buffer32));
+    await expect(mock.encode(buffer31)).to.eventually.equal(ethers.encodeBase64(buffer31));
+    await expect(mock.encode(buffer32)).to.eventually.equal(ethers.encodeBase64(buffer32));
   });
 });