Add Base58 library

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

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,214 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.20;
+
+/**
+ * @dev Provides a set of functions to operate with Base58 strings.
+ *
+ * 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/main/src/utils/Base58.sol[Vectorized version] (MIT).
+ */
+library Base58 {
+    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.
+            // This is an estimation of the length ratio between bytes (base 256) and base58
+            // 9886 / 7239 = 1.36565824008841 > 1.365658237309761 = Math.log(256) / Math.log(58)
+            let outputLengthEstim := add(inputLeadingZeros, div(mul(sub(inputLength, inputLeadingZeros), 9886), 7239))
+
+            // This is going to be our "scratch" workspace. We leave enough room after FMP to later store length + encoded output.
+            let scratch := add(mload(0x40), add(outputLengthEstim, 0x21))
+
+            // Cut the input buffer in section (limbs) of 31 bytes (248 bits). Store in scratch.
+            let ptr := scratch
+            for {
+                // first section is possibly smaller than 31 bytes
+                let i := mod(inputLength, 31)
+                // unfold first loop, with a different shift.
+                if i {
+                    mstore(ptr, shr(mul(sub(32, i), 8), mload(add(input, 0x20))))
+                    ptr := add(ptr, 0x20)
+                }
+            } lt(i, inputLength) {
+                ptr := add(ptr, 0x20) // next limb
+                i := add(i, 31) // move in buffer
+            } {
+                // Load 31 bytes from the input buffer and store then in scratch (at ptr) in a dedicated 32 bytes space.
+                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 sections 2 of https://inputtracker.ietf.org/doc/html/draft-msporny-base58-03
+            mstore(0x1f, "123456789ABCDEFGHJKLMNPQRSTUVWXY")
+            mstore(0x3f, "Zabcdefghijkmnopqrstuvwxyz")
+
+            // Encoding the "input" part of the result.
+            // - `data` points to the first (highest) non-empty limb. As limb get nullified by the successive
+            //   divisions by 58, we don't need to reprocess the highest ones. Algorithm ends when all limbs are zeroed
+            //   i.e. when the `data` pointer reaches the `ptr` pointer that correspond to the last limb.
+            // - `output` point the the left part of the encoded string. We start from scratch, which means we have
+            //   outputLengthEstim bytes to work with before hitting the FMP
+            for {
+                let data := scratch
+                output := scratch
+            } 1 {} {
+                // move past the first (highest) zero limbs.
+                for {} and(iszero(mload(data)), lt(data, ptr)) {
+                    data := add(data, 0x20)
+                } {}
+                // if all limbs are zeroed, we are done with this part of encoding
+                if eq(data, ptr) {
+                    break
+                }
+
+                // base 58 arithmetic on the 248bits limbs
+                let carry := 0
+                for {
+                    let i := data
+                } lt(i, ptr) {
+                    i := add(i, 0x20)
+                } {
+                    let acc := add(shl(248, carry), mload(i))
+                    mstore(i, div(acc, 58))
+                    carry := mod(acc, 58)
+                }
+
+                // encode carry using base58 table, and add it to the output
+                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)))
+            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)
+            }
+
+            // Start the output offset by an over-estimate of the length.
+            // This is an estimation of the length ratio between base58 and bytes (base 256)
+            // 6115 / 8351 = 0.7322476350137708 > 0.7322476243909465 = Math.log(58) / Math.log(256)
+            let outputLengthEstim := add(inputLeadingZeros, div(mul(sub(inputLength, inputLeadingZeros), 6115), 8351))
+
+            // This is going to be our "scratch" workspace. Be leave enough room on the left to store length + encoded input.
+            let scratch := add(mload(0x40), add(outputLengthEstim, 0x21))
+
+            // Store the decoding table. This overlaps with the FMP that we are going to reset later anyway.
+            mstore(0x2a, 0x30313233343536373839)
+            mstore(0x20, 0x1718191a1b1c1d1e1f20ffffffffffff2122232425262728292a2bff2c2d2e2f)
+            mstore(0x00, 0x000102030405060708ffffffffffffff090a0b0c0d0e0f10ff1112131415ff16)
+
+            // Decode each char of the input string, and store it in sections (limbs) of 31 bytes. Store in scratch.
+            let ptr := scratch
+            let mask := shr(8, not(0))
+            for {
+                let j := 0
+            } lt(j, inputLength) {
+                j := add(j, 1)
+            } {
+                // for each char, decode it ...
+                let c := sub(byte(0, mload(add(add(input, 0x20), j))), 49)
+                // 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))
+
+                // ... and add it to the limbs starting a `scratch`
+                for {
+                    let i := scratch
+                } lt(i, ptr) {
+                    i := add(i, 0x20)
+                } {
+                    let acc := add(carry, mul(58, mload(i)))
+                    mstore(i, and(mask, acc))
+                    carry := shr(248, acc)
+                }
+                // If the char just read result in a leftover carry, extend the limbs with the new value
+                if carry {
+                    mstore(ptr, carry)
+                    ptr := add(ptr, 0x20)
+                }
+            }
+
+            // 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)
+        }
+    }
+}

contracts/utils/Base64.sol

@@ -11,17 +11,17 @@ import {SafeCast} from "./math/SafeCast.sol";
 library Base64 {
     using SafeCast for bool;
 
-    error InvalidBase64Digit(bytes1);
+    error InvalidBase64Char(bytes1);
 
     /**
-     * @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 string(_encode(data, false));
     }
 
     /**
-     * @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) {
@@ -142,7 +142,7 @@ library Base64 {
      * @dev Internal decoding
      */
     function _decode(bytes memory data) private pure returns (bytes memory result) {
-        bytes4 errorSelector = InvalidBase64Digit.selector;
+        bytes4 errorSelector = InvalidBase64Char.selector;
 
         uint256 dataLength = data.length;
         if (dataLength == 0) return "";

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.
@@ -106,6 +107,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(hex"")), hex"");
+    }
+
+    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,65 @@
+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 random buffers', function () {
+      // length 512 runs out of gas.
+      // this checks are very slow when running coverage, causing CI to timeout.
+      for (const length of [0, 1, 2, 3, 4, 32, 42, 128, 384])
+        it(
+          [length > 32 && '[skip-on-coverage]', `buffer of length ${length}`].filter(Boolean).join(' '),
+          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);
+          },
+        );
+    });
+
+    // Tests case from section 5 of the (no longer active) Base58 Encoding Scheme RFC
+    // https://datatracker.ietf.org/doc/html/draft-msporny-base58-03
+    describe('test vectors', function () {
+      for (const { raw, b58 } of [
+        { raw: 'Hello World!', b58: '2NEpo7TZRRrLZSi2U' },
+        {
+          raw: 'The quick brown fox jumps over the lazy dog.',
+          b58: 'USm3fpXnKG5EUBx2ndxBDMPVciP5hGey2Jh4NDv6gmeo1LkMeiKrLJUUBk6Z',
+        },
+        { raw: '0x0000287fb4cd', b58: '11233QC4' },
+      ])
+        it(raw, async function () {
+          const buffer = (ethers.isHexString(raw) ? ethers.getBytes : ethers.toUtf8Bytes)(raw);
+          const hex = ethers.hexlify(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 () {
+          const getHexCode = str => ethers.hexlify(ethers.toUtf8Bytes(str));
+          const helper = { interface: ethers.Interface.from(['error InvalidBase58Char(bytes1)']) };
+
+          await expect(this.mock.$decode(`VYRWKp${chr}pnN7`))
+            .to.be.revertedWithCustomError(helper, 'InvalidBase58Char')
+            .withArgs(getHexCode(chr));
+        });
+    });
+  });
+});