web3gbit-cli 1.0.0

package/lib/openzeppelin-contracts/scripts/generate/templates/Checkpoints.js

@@ -0,0 +1,242 @@
+const format = require('../format-lines');
+const { OPTS } = require('./Checkpoints.opts');
+
+// TEMPLATE
+const header = `\
+pragma solidity ^0.8.20;
+
+import {Math} from "../math/Math.sol";
+
+/**
+ * @dev This library defines the \`Trace*\` struct, for checkpointing values as they change at different points in
+ * time, and later looking up past values by block number. See {Votes} as an example.
+ *
+ * To create a history of checkpoints define a variable type \`Checkpoints.Trace*\` in your contract, and store a new
+ * checkpoint for the current transaction block using the {push} function.
+ */
+`;
+
+const errors = `\
+/**
+ * @dev A value was attempted to be inserted on a past checkpoint.
+ */
+error CheckpointUnorderedInsertion();
+`;
+
+const template = opts => `\
+struct ${opts.historyTypeName} {
+    ${opts.checkpointTypeName}[] ${opts.checkpointFieldName};
+}
+
+struct ${opts.checkpointTypeName} {
+    ${opts.keyTypeName} ${opts.keyFieldName};
+    ${opts.valueTypeName} ${opts.valueFieldName};
+}
+
+/**
+ * @dev Pushes a (\`key\`, \`value\`) pair into a ${opts.historyTypeName} so that it is stored as the checkpoint.
+ *
+ * Returns previous value and new value.
+ *
+ * IMPORTANT: Never accept \`key\` as a user input, since an arbitrary \`type(${opts.keyTypeName}).max\` key set will disable the
+ * library.
+ */
+function push(
+    ${opts.historyTypeName} storage self,
+    ${opts.keyTypeName} key,
+    ${opts.valueTypeName} value
+) internal returns (${opts.valueTypeName} oldValue, ${opts.valueTypeName} newValue) {
+    return _insert(self.${opts.checkpointFieldName}, key, value);
+}
+
+/**
+ * @dev Returns the value in the first (oldest) checkpoint with key greater or equal than the search key, or zero if
+ * there is none.
+ */
+function lowerLookup(${opts.historyTypeName} storage self, ${opts.keyTypeName} key) internal view returns (${opts.valueTypeName}) {
+    uint256 len = self.${opts.checkpointFieldName}.length;
+    uint256 pos = _lowerBinaryLookup(self.${opts.checkpointFieldName}, key, 0, len);
+    return pos == len ? 0 : _unsafeAccess(self.${opts.checkpointFieldName}, pos).${opts.valueFieldName};
+}
+
+/**
+ * @dev Returns the value in the last (most recent) checkpoint with key lower or equal than the search key, or zero
+ * if there is none.
+ */
+function upperLookup(${opts.historyTypeName} storage self, ${opts.keyTypeName} key) internal view returns (${opts.valueTypeName}) {
+    uint256 len = self.${opts.checkpointFieldName}.length;
+    uint256 pos = _upperBinaryLookup(self.${opts.checkpointFieldName}, key, 0, len);
+    return pos == 0 ? 0 : _unsafeAccess(self.${opts.checkpointFieldName}, pos - 1).${opts.valueFieldName};
+}
+
+/**
+ * @dev Returns the value in the last (most recent) checkpoint with key lower or equal than the search key, or zero
+ * if there is none.
+ *
+ * NOTE: This is a variant of {upperLookup} that is optimized to find "recent" checkpoint (checkpoints with high
+ * keys).
+ */
+function upperLookupRecent(${opts.historyTypeName} storage self, ${opts.keyTypeName} key) internal view returns (${opts.valueTypeName}) {
+    uint256 len = self.${opts.checkpointFieldName}.length;
+
+    uint256 low = 0;
+    uint256 high = len;
+
+    if (len > 5) {
+        uint256 mid = len - Math.sqrt(len);
+        if (key < _unsafeAccess(self.${opts.checkpointFieldName}, mid)._key) {
+            high = mid;
+        } else {
+            low = mid + 1;
+        }
+    }
+
+    uint256 pos = _upperBinaryLookup(self.${opts.checkpointFieldName}, key, low, high);
+
+    return pos == 0 ? 0 : _unsafeAccess(self.${opts.checkpointFieldName}, pos - 1).${opts.valueFieldName};
+}
+
+/**
+ * @dev Returns the value in the most recent checkpoint, or zero if there are no checkpoints.
+ */
+function latest(${opts.historyTypeName} storage self) internal view returns (${opts.valueTypeName}) {
+    uint256 pos = self.${opts.checkpointFieldName}.length;
+    return pos == 0 ? 0 : _unsafeAccess(self.${opts.checkpointFieldName}, pos - 1).${opts.valueFieldName};
+}
+
+/**
+ * @dev Returns whether there is a checkpoint in the structure (i.e. it is not empty), and if so the key and value
+ * in the most recent checkpoint.
+ */
+function latestCheckpoint(${opts.historyTypeName} storage self) internal view returns (bool exists, ${opts.keyTypeName} ${opts.keyFieldName}, ${opts.valueTypeName} ${opts.valueFieldName}) {
+    uint256 pos = self.${opts.checkpointFieldName}.length;
+    if (pos == 0) {
+        return (false, 0, 0);
+    } else {
+        ${opts.checkpointTypeName} storage ckpt = _unsafeAccess(self.${opts.checkpointFieldName}, pos - 1);
+        return (true, ckpt.${opts.keyFieldName}, ckpt.${opts.valueFieldName});
+    }
+}
+
+/**
+ * @dev Returns the number of checkpoints.
+ */
+function length(${opts.historyTypeName} storage self) internal view returns (uint256) {
+    return self.${opts.checkpointFieldName}.length;
+}
+
+/**
+ * @dev Returns checkpoint at given position.
+ */
+function at(${opts.historyTypeName} storage self, uint32 pos) internal view returns (${opts.checkpointTypeName} memory) {
+    return self.${opts.checkpointFieldName}[pos];
+}
+
+/**
+ * @dev Pushes a (\`key\`, \`value\`) pair into an ordered list of checkpoints, either by inserting a new checkpoint,
+ * or by updating the last one.
+ */
+function _insert(
+    ${opts.checkpointTypeName}[] storage self,
+    ${opts.keyTypeName} key,
+    ${opts.valueTypeName} value
+) private returns (${opts.valueTypeName} oldValue, ${opts.valueTypeName} newValue) {
+    uint256 pos = self.length;
+
+    if (pos > 0) {
+        ${opts.checkpointTypeName} storage last = _unsafeAccess(self, pos - 1);
+        ${opts.keyTypeName} lastKey = last.${opts.keyFieldName};
+        ${opts.valueTypeName} lastValue = last.${opts.valueFieldName};
+
+        // Checkpoint keys must be non-decreasing.
+        if (lastKey > key) {
+            revert CheckpointUnorderedInsertion();
+        }
+
+        // Update or push new checkpoint
+        if (lastKey == key) {
+            last.${opts.valueFieldName} = value;
+        } else {
+            self.push(${opts.checkpointTypeName}({${opts.keyFieldName}: key, ${opts.valueFieldName}: value}));
+        }
+        return (lastValue, value);
+    } else {
+        self.push(${opts.checkpointTypeName}({${opts.keyFieldName}: key, ${opts.valueFieldName}: value}));
+        return (0, value);
+    }
+}
+
+/**
+ * @dev Return the index of the first (oldest) checkpoint with key strictly bigger than the search key, or \`high\`
+ * if there is none. \`low\` and \`high\` define a section where to do the search, with inclusive \`low\` and exclusive
+ * \`high\`.
+ *
+ * WARNING: \`high\` should not be greater than the array's length.
+ */
+function _upperBinaryLookup(
+    ${opts.checkpointTypeName}[] storage self,
+    ${opts.keyTypeName} key,
+    uint256 low,
+    uint256 high
+) private view returns (uint256) {
+    while (low < high) {
+        uint256 mid = Math.average(low, high);
+        if (_unsafeAccess(self, mid).${opts.keyFieldName} > key) {
+            high = mid;
+        } else {
+            low = mid + 1;
+        }
+    }
+    return high;
+}
+
+/**
+ * @dev Return the index of the first (oldest) checkpoint with key greater or equal than the search key, or \`high\`
+ * if there is none. \`low\` and \`high\` define a section where to do the search, with inclusive \`low\` and exclusive
+ * \`high\`.
+ *
+ * WARNING: \`high\` should not be greater than the array's length.
+ */
+function _lowerBinaryLookup(
+    ${opts.checkpointTypeName}[] storage self,
+    ${opts.keyTypeName} key,
+    uint256 low,
+    uint256 high
+) private view returns (uint256) {
+    while (low < high) {
+        uint256 mid = Math.average(low, high);
+        if (_unsafeAccess(self, mid).${opts.keyFieldName} < key) {
+            low = mid + 1;
+        } else {
+            high = mid;
+        }
+    }
+    return high;
+}
+
+/**
+ * @dev Access an element of the array without performing bounds check. The position is assumed to be within bounds.
+ */
+function _unsafeAccess(
+    ${opts.checkpointTypeName}[] storage self,
+    uint256 pos
+) private pure returns (${opts.checkpointTypeName} storage result) {
+    assembly {
+        mstore(0x00, self.slot)
+        result.slot := add(keccak256(0x00, 0x20), ${opts.checkpointSize === 1 ? 'pos' : `mul(pos, ${opts.checkpointSize})`})
+    }
+}
+`;
+
+// GENERATE
+module.exports = format(
+  header.trimEnd(),
+  'library Checkpoints {',
+  format(
+    [].concat(
+      errors,
+      OPTS.map(opts => template(opts)),
+    ),
+  ).trimEnd(),
+  '}',
+);

package/lib/openzeppelin-contracts/scripts/generate/templates/Checkpoints.opts.js

@@ -0,0 +1,18 @@
+// OPTIONS
+const VALUE_SIZES = [256, 224, 208, 160];
+
+const defaultOpts = size => ({
+  historyTypeName: `Trace${size}`,
+  checkpointTypeName: `Checkpoint${size}`,
+  checkpointFieldName: '_checkpoints',
+  checkpointSize: size < 256 ? 1 : 2,
+  keyTypeName: size < 256 ? `uint${256 - size}` : 'uint256',
+  keyFieldName: '_key',
+  valueTypeName: `uint${size}`,
+  valueFieldName: '_value',
+});
+
+module.exports = {
+  VALUE_SIZES,
+  OPTS: VALUE_SIZES.map(size => defaultOpts(size)),
+};

package/lib/openzeppelin-contracts/scripts/generate/templates/Checkpoints.t.js

@@ -0,0 +1,141 @@
+const format = require('../format-lines');
+const { capitalize } = require('../../helpers');
+const { OPTS } = require('./Checkpoints.opts.js');
+
+// TEMPLATE
+const header = `\
+pragma solidity ^0.8.20;
+
+import {Test} from "forge-std/Test.sol";
+import {SafeCast} from "@openzeppelin/contracts/utils/math/SafeCast.sol";
+import {Checkpoints} from "@openzeppelin/contracts/utils/structs/Checkpoints.sol";
+`;
+
+const template = opts => `\
+using Checkpoints for Checkpoints.${opts.historyTypeName};
+
+// Maximum gap between keys used during the fuzzing tests: the \`_prepareKeys\` function will make sure that
+// key#n+1 is in the [key#n, key#n + _KEY_MAX_GAP] range.
+uint8 internal constant _KEY_MAX_GAP = 64;
+
+Checkpoints.${opts.historyTypeName} internal _ckpts;
+
+// helpers
+function _bound${capitalize(opts.keyTypeName)}(${opts.keyTypeName} x, ${opts.keyTypeName} min, ${
+  opts.keyTypeName
+} max) internal pure returns (${opts.keyTypeName}) {
+    return ${
+      opts.keyTypeName === 'uint256'
+        ? 'bound(x, min, max)'
+        : `SafeCast.to${capitalize(opts.keyTypeName)}(bound(uint256(x), uint256(min), uint256(max)))`
+    };
+}
+
+function _prepareKeys(${opts.keyTypeName}[] memory keys, ${opts.keyTypeName} maxSpread) internal pure {
+    ${opts.keyTypeName} lastKey = 0;
+    for (uint256 i = 0; i < keys.length; ++i) {
+        ${opts.keyTypeName} key = _bound${capitalize(opts.keyTypeName)}(keys[i], lastKey, lastKey + maxSpread);
+        keys[i] = key;
+        lastKey = key;
+    }
+}
+
+function _assertLatestCheckpoint(bool exist, ${opts.keyTypeName} key, ${opts.valueTypeName} value) internal view {
+    (bool _exist, ${opts.keyTypeName} _key, ${opts.valueTypeName} _value) = _ckpts.latestCheckpoint();
+    assertEq(_exist, exist);
+    assertEq(_key, key);
+    assertEq(_value, value);
+}
+
+// tests
+function testPush(${opts.keyTypeName}[] memory keys, ${opts.valueTypeName}[] memory values, ${
+  opts.keyTypeName
+} pastKey) public {
+    vm.assume(values.length > 0 && values.length <= keys.length);
+    _prepareKeys(keys, _KEY_MAX_GAP);
+
+    // initial state
+    assertEq(_ckpts.length(), 0);
+    assertEq(_ckpts.latest(), 0);
+    _assertLatestCheckpoint(false, 0, 0);
+
+    uint256 duplicates = 0;
+    for (uint256 i = 0; i < keys.length; ++i) {
+        ${opts.keyTypeName} key = keys[i];
+        ${opts.valueTypeName} value = values[i % values.length];
+        if (i > 0 && key == keys[i - 1]) ++duplicates;
+
+        // push
+        _ckpts.push(key, value);
+
+        // check length & latest
+        assertEq(_ckpts.length(), i + 1 - duplicates);
+        assertEq(_ckpts.latest(), value);
+        _assertLatestCheckpoint(true, key, value);
+    }
+
+    if (keys.length > 0) {
+        ${opts.keyTypeName} lastKey = keys[keys.length - 1];
+        if (lastKey > 0) {
+            pastKey = _bound${capitalize(opts.keyTypeName)}(pastKey, 0, lastKey - 1);
+
+            vm.expectRevert();
+            this.push(pastKey, values[keys.length % values.length]);
+        }
+    }
+}
+
+// used to test reverts
+function push(${opts.keyTypeName} key, ${opts.valueTypeName} value) external {
+    _ckpts.push(key, value);
+}
+
+function testLookup(${opts.keyTypeName}[] memory keys, ${opts.valueTypeName}[] memory values, ${
+  opts.keyTypeName
+} lookup) public {
+    vm.assume(values.length > 0 && values.length <= keys.length);
+    _prepareKeys(keys, _KEY_MAX_GAP);
+
+    ${opts.keyTypeName} lastKey = keys.length == 0 ? 0 : keys[keys.length - 1];
+    lookup = _bound${capitalize(opts.keyTypeName)}(lookup, 0, lastKey + _KEY_MAX_GAP);
+
+    ${opts.valueTypeName} upper = 0;
+    ${opts.valueTypeName} lower = 0;
+    ${opts.keyTypeName} lowerKey = type(${opts.keyTypeName}).max;
+    for (uint256 i = 0; i < keys.length; ++i) {
+        ${opts.keyTypeName} key = keys[i];
+        ${opts.valueTypeName} value = values[i % values.length];
+
+        // push
+        _ckpts.push(key, value);
+
+        // track expected result of lookups
+        if (key <= lookup) {
+            upper = value;
+        }
+        // find the first key that is not smaller than the lookup key
+        if (key >= lookup && (i == 0 || keys[i - 1] < lookup)) {
+            lowerKey = key;
+        }
+        if (key == lowerKey) {
+            lower = value;
+        }
+    }
+
+    // check lookup
+    assertEq(_ckpts.lowerLookup(lookup), lower);
+    assertEq(_ckpts.upperLookup(lookup), upper);
+    assertEq(_ckpts.upperLookupRecent(lookup), upper);
+}
+`;
+
+// GENERATE
+module.exports = format(
+  header,
+  ...OPTS.flatMap(opts => [
+    `contract Checkpoints${opts.historyTypeName}Test is Test {`,
+    [template(opts).trimEnd()],
+    '}',
+    '',
+  ]),
+);

package/lib/openzeppelin-contracts/scripts/generate/templates/Enumerable.opts.js

@@ -0,0 +1,56 @@
+const { capitalize, mapValues } = require('../../helpers');
+
+const typeDescr = ({ type, size = 0, memory = false }) => {
+  memory |= size > 0;
+
+  const name = [type == 'uint256' ? 'Uint' : capitalize(type), size].filter(Boolean).join('x');
+  const base = size ? type : undefined;
+  const typeFull = size ? `${type}[${size}]` : type;
+  const typeLoc = memory ? `${typeFull} memory` : typeFull;
+  return { name, type: typeFull, typeLoc, base, size, memory };
+};
+
+const toSetTypeDescr = value => ({
+  name: value.name + 'Set',
+  value,
+});
+
+const toMapTypeDescr = ({ key, value }) => ({
+  name: `${key.name}To${value.name}Map`,
+  keySet: toSetTypeDescr(key),
+  key,
+  value,
+});
+
+const SET_TYPES = [
+  { type: 'bytes32' },
+  { type: 'bytes4' },
+  { type: 'address' },
+  { type: 'uint256' },
+  { type: 'string', memory: true },
+  { type: 'bytes', memory: true },
+]
+  .map(typeDescr)
+  .map(toSetTypeDescr);
+
+const MAP_TYPES = []
+  .concat(
+    // value type maps
+    ['uint256', 'address', 'bytes32']
+      .flatMap((keyType, _, array) => array.map(valueType => ({ key: { type: keyType }, value: { type: valueType } })))
+      .slice(0, -1), // remove bytes32 → bytes32 (last one) that is already defined
+    // other value type maps
+    { key: { type: 'bytes4' }, value: { type: 'address' } },
+    // non-value type maps
+    { key: { type: 'bytes', memory: true }, value: { type: 'bytes', memory: true } },
+  )
+  .map(entry => mapValues(entry, typeDescr))
+  .map(toMapTypeDescr);
+
+module.exports = {
+  SET_TYPES,
+  MAP_TYPES,
+  typeDescr,
+  toSetTypeDescr,
+  toMapTypeDescr,
+};