Extend Checkpoints with new sizes and lookup mechanisms

CHANGELOG.md

@@ -13,6 +13,9 @@
  * `SafeCast`: optimize downcasting of signed integers. ([#3565](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3565))
  * `ERC20FlashMint`: add an internal `_flashFee` function for overriding. ([#3551](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3551))
  * `VestingWallet`: remove unused library `Math.sol`. ([#3605](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3605))
+ * `Checkpoints`: Use provedural generation to support multiple key/value lengths. ([#3589](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3589))
+ * `Checkpoints`: Add new lookup mechanisms. ([#3589](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3589))
+ * `Array`: Add `unsafeAccess` functions that allow reading and writting to a element in a storage array while bypassing solidity's "out-of-array" check. ([#3589](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3589))
 
 ### Compatibility Note
 

contracts/governance/extensions/GovernorVotesQuorumFraction.sol

@@ -50,8 +50,8 @@ abstract contract GovernorVotesQuorumFraction is GovernorVotes {
         }
 
         // Optimistic search, check the latest checkpoint
-        Checkpoints.Checkpoint memory latest = _quorumNumeratorHistory._checkpoints[length - 1];
-        if (latest._blockNumber <= blockNumber) {
+        Checkpoints.Checkpoint224 memory latest = _quorumNumeratorHistory._checkpoints[length - 1];
+        if (latest._key <= blockNumber) {
             return latest._value;
         }
 
@@ -107,7 +107,7 @@ abstract contract GovernorVotesQuorumFraction is GovernorVotes {
         // Make sure we keep track of the original numerator in contracts upgraded from a version without checkpoints.
         if (oldQuorumNumerator != 0 && _quorumNumeratorHistory._checkpoints.length == 0) {
             _quorumNumeratorHistory._checkpoints.push(
-                Checkpoints.Checkpoint({_blockNumber: 0, _value: SafeCast.toUint224(oldQuorumNumerator)})
+                Checkpoints.Checkpoint224({_key: 0, _value: SafeCast.toUint224(oldQuorumNumerator)})
             );
         }
 

contracts/mocks/ArraysMock.sol

@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.0;
+
+import "../utils/Arrays.sol";
+
+contract Uint256ArraysMock {
+    using Arrays for uint256[];
+
+    uint256[] private _array;
+
+    constructor(uint256[] memory array) {
+        _array = array;
+    }
+
+    function findUpperBound(uint256 element) external view returns (uint256) {
+        return _array.findUpperBound(element);
+    }
+
+    function unsafeAccess(uint256 pos) external view returns (uint256) {
+        return _array.unsafeAccess(pos).value;
+    }
+}
+
+contract AddressArraysMock {
+    using Arrays for address[];
+
+    address[] private _array;
+
+    constructor(address[] memory array) {
+        _array = array;
+    }
+
+    function unsafeAccess(uint256 pos) external view returns (address) {
+        return _array.unsafeAccess(pos).value;
+    }
+}
+
+contract Bytes32ArraysMock {
+    using Arrays for bytes32[];
+
+    bytes32[] private _array;
+
+    constructor(bytes32[] memory array) {
+        _array = array;
+    }
+
+    function unsafeAccess(uint256 pos) external view returns (bytes32) {
+        return _array.unsafeAccess(pos).value;
+    }
+}

contracts/mocks/CheckpointsMock.sol

@@ -0,0 +1,87 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.0;
+
+import "../utils/Checkpoints.sol";
+
+contract CheckpointsMock {
+    using Checkpoints for Checkpoints.History;
+
+    Checkpoints.History private _totalCheckpoints;
+
+    function latest() public view returns (uint256) {
+        return _totalCheckpoints.latest();
+    }
+
+    function push(uint256 value) public returns (uint256, uint256) {
+        return _totalCheckpoints.push(value);
+    }
+
+    function getAtBlock(uint256 blockNumber) public view returns (uint256) {
+        return _totalCheckpoints.getAtBlock(blockNumber);
+    }
+
+    function length() public view returns (uint256) {
+        return _totalCheckpoints._checkpoints.length;
+    }
+}
+
+contract Checkpoints224Mock {
+    using Checkpoints for Checkpoints.Checkpoint224[];
+
+    Checkpoints.Checkpoint224[] private _totalCheckpoints;
+
+    function latest() public view returns (uint224) {
+        return _totalCheckpoints.latest();
+    }
+
+    function push(uint32 key, uint224 value) public returns (uint224, uint224) {
+        return _totalCheckpoints.push(key, value);
+    }
+
+    function lowerLookup(uint32 key) public view returns (uint224) {
+        return _totalCheckpoints.lowerLookup(key);
+    }
+
+    function upperLookup(uint32 key) public view returns (uint224) {
+        return _totalCheckpoints.upperLookup(key);
+    }
+
+    function upperLookupRecent(uint32 key) public view returns (uint224) {
+        return _totalCheckpoints.upperLookupRecent(key);
+    }
+
+    function length() public view returns (uint256) {
+        return _totalCheckpoints.length;
+    }
+}
+
+contract Checkpoints160Mock {
+    using Checkpoints for Checkpoints.Checkpoint160[];
+
+    Checkpoints.Checkpoint160[] private _totalCheckpoints;
+
+    function latest() public view returns (uint160) {
+        return _totalCheckpoints.latest();
+    }
+
+    function push(uint96 key, uint160 value) public returns (uint160, uint160) {
+        return _totalCheckpoints.push(key, value);
+    }
+
+    function lowerLookup(uint96 key) public view returns (uint160) {
+        return _totalCheckpoints.lowerLookup(key);
+    }
+
+    function upperLookup(uint96 key) public view returns (uint160) {
+        return _totalCheckpoints.upperLookup(key);
+    }
+
+    function upperLookupRecent(uint96 key) public view returns (uint224) {
+        return _totalCheckpoints.upperLookupRecent(key);
+    }
+
+    function length() public view returns (uint256) {
+        return _totalCheckpoints.length;
+    }
+}

contracts/utils/Arrays.sol

@@ -3,12 +3,15 @@
 
 pragma solidity ^0.8.0;
 
+import "./StorageSlot.sol";
 import "./math/Math.sol";
 
 /**
  * @dev Collection of functions related to array types.
  */
 library Arrays {
+    using StorageSlot for bytes32;
+
     /**
      * @dev Searches a sorted `array` and returns the first index that contains
      * a value greater or equal to `element`. If no such index exists (i.e. all
@@ -31,18 +34,60 @@ library Arrays {
 
             // Note that mid will always be strictly less than high (i.e. it will be a valid array index)
             // because Math.average rounds down (it does integer division with truncation).
-            if (array[mid] > element) {
+            if (unsafeAccess(array, mid).value > element) {
                 high = mid;
             } else {
                 low = mid + 1;
             }
         }
 
         // At this point `low` is the exclusive upper bound. We will return the inclusive upper bound.
-        if (low > 0 && array[low - 1] == element) {
+        if (low > 0 && unsafeAccess(array, low - 1).value == element) {
             return low - 1;
         } else {
             return low;
         }
     }
+
+    /**
+     * @dev Access an array in an "unsafe" way. Skips solidity "index-out-of-range" check.
+     * @notice WARNING: only use if you are certain pos is lower than the array length.
+     */
+    function unsafeAccess(address[] storage arr, uint256 pos) internal pure returns (StorageSlot.AddressSlot storage) {
+        bytes32 slot;
+        /// @solidity memory-safe-assembly
+        assembly {
+            mstore(0, arr.slot)
+            slot := add(keccak256(0, 0x20), pos)
+        }
+        return slot.getAddressSlot();
+    }
+
+    /**
+     * @dev Access an array in an "unsafe" way. Skips solidity "index-out-of-range" check.
+     * @notice WARNING: only use if you are certain pos is lower than the array length.
+     */
+    function unsafeAccess(bytes32[] storage arr, uint256 pos) internal pure returns (StorageSlot.Bytes32Slot storage) {
+        bytes32 slot;
+        /// @solidity memory-safe-assembly
+        assembly {
+            mstore(0, arr.slot)
+            slot := add(keccak256(0, 0x20), pos)
+        }
+        return slot.getBytes32Slot();
+    }
+
+    /**
+     * @dev Access an array in an "unsafe" way. Skips solidity "index-out-of-range" check.
+     * @notice WARNING: only use if you are certain pos is lower than the array length.
+     */
+    function unsafeAccess(uint256[] storage arr, uint256 pos) internal pure returns (StorageSlot.Uint256Slot storage) {
+        bytes32 slot;
+        /// @solidity memory-safe-assembly
+        assembly {
+            mstore(0, arr.slot)
+            slot := add(keccak256(0, 0x20), pos)
+        }
+        return slot.getUint256Slot();
+    }
 }