Extended packing and extracting library for value types (#5056)

Co-authored-by: ernestognw <ernestognw@gmail.com>

scripts/generate/run.js

@@ -39,6 +39,7 @@ for (const [file, template] of Object.entries({
   'utils/SlotDerivation.sol': './templates/SlotDerivation.js',
   'utils/StorageSlot.sol': './templates/StorageSlot.js',
   'utils/Arrays.sol': './templates/Arrays.js',
+  'utils/Packing.sol': './templates/Packing.js',
   'mocks/StorageSlotMock.sol': './templates/StorageSlotMock.js',
 })) {
   generateFromTemplate(file, template, './contracts/');
@@ -47,6 +48,7 @@ for (const [file, template] of Object.entries({
 // Tests
 for (const [file, template] of Object.entries({
   'utils/structs/Checkpoints.t.sol': './templates/Checkpoints.t.js',
+  'utils/Packing.t.sol': './templates/Packing.t.js',
   'utils/SlotDerivation.t.sol': './templates/SlotDerivation.t.js',
 })) {
   generateFromTemplate(file, template, './test/');

scripts/generate/templates/Packing.js

@@ -0,0 +1,78 @@
+const format = require('../format-lines');
+const { product } = require('../../helpers');
+const { SIZES } = require('./Packing.opts');
+
+// TEMPLATE
+const header = `\
+pragma solidity ^0.8.20;
+
+/**
+ * @dev Helper library packing and unpacking multiple values into bytesXX.
+ *
+ * Example usage:
+ *
+ * \`\`\`solidity
+ * library MyPacker {
+ *     type MyType is bytes32;
+ *
+ *     function _pack(address account, bytes4 selector, uint64 period) external pure returns (MyType) {
+ *         bytes12 subpack = Packing.pack_4_8(selector, bytes8(period));
+ *         bytes32 pack = Packing.pack_20_12(bytes20(account), subpack);
+ *         return MyType.wrap(pack);
+ *     }
+ *
+ *     function _unpack(MyType self) external pure returns (address, bytes4, uint64) {
+ *         bytes32 pack = MyType.unwrap(self);
+ *         return (
+ *             address(Packing.extract_32_20(pack, 0)),
+ *             Packing.extract_32_4(pack, 20),
+ *             uint64(Packing.extract_32_8(pack, 24))
+ *         );
+ *     }
+ * }
+ * \`\`\`
+ */
+// solhint-disable func-name-mixedcase
+`;
+
+const errors = `\
+    error OutOfRangeAccess();`;
+
+const pack = (left, right) => `
+function pack_${left}_${right}(bytes${left} left, bytes${right} right) internal pure returns (bytes${
+  left + right
+} result) {
+    assembly ("memory-safe") {
+        result := or(left, shr(${8 * left}, right))
+    }
+}`;
+
+const extract = (outer, inner) => `
+function extract_${outer}_${inner}(bytes${outer} self, uint8 offset) internal pure returns (bytes${inner} result) {
+    if (offset > ${outer - inner}) revert OutOfRangeAccess();
+    assembly ("memory-safe") {
+        result := and(shl(mul(8, offset), self), shl(${256 - 8 * inner}, not(0)))
+    }
+}`;
+
+const replace = (outer, inner) => `
+function replace_${outer}_${inner}(bytes${outer} self, bytes${inner} value, uint8 offset) internal pure returns (bytes${outer} result) {
+    bytes${inner} oldValue = extract_${outer}_${inner}(self, offset);
+    assembly ("memory-safe") {
+        result := xor(self, shr(mul(8, offset), xor(oldValue, value)))
+    }
+}`;
+
+// GENERATE
+module.exports = format(
+  header.trimEnd(),
+  'library Packing {',
+  errors,
+  product(SIZES, SIZES)
+    .filter(([left, right]) => SIZES.includes(left + right))
+    .map(([left, right]) => pack(left, right)),
+  product(SIZES, SIZES)
+    .filter(([outer, inner]) => outer > inner)
+    .flatMap(([outer, inner]) => [extract(outer, inner), replace(outer, inner)]),
+  '}',
+);

scripts/generate/templates/Packing.opts.js

@@ -0,0 +1,5 @@
+const { range } = require('../../helpers');
+
+const SIZES = range(1, 33).filter(size => size == 1 || size == 2 || size % 4 == 0);
+
+module.exports = { SIZES };

scripts/generate/templates/Packing.t.js

@@ -0,0 +1,42 @@
+const format = require('../format-lines');
+const { product } = require('../../helpers');
+const { SIZES } = require('./Packing.opts');
+
+// TEMPLATE
+const header = `\
+pragma solidity ^0.8.20;
+
+import {Test} from "forge-std/Test.sol";
+import {Packing} from "@openzeppelin/contracts/utils/Packing.sol";
+`;
+
+const testPack = (left, right) => `
+function testPack(bytes${left} left, bytes${right} right) external {
+    assertEq(left, Packing.pack_${left}_${right}(left, right).extract_${left + right}_${left}(0));
+    assertEq(right, Packing.pack_${left}_${right}(left, right).extract_${left + right}_${right}(${left}));
+}`;
+
+const testReplace = (outer, inner) => `
+function testReplace(bytes${outer} container, bytes${inner} newValue, uint8 offset) external {
+    offset = uint8(bound(offset, 0, ${outer - inner}));
+
+    bytes${inner} oldValue = container.extract_${outer}_${inner}(offset);
+
+    assertEq(newValue, container.replace_${outer}_${inner}(newValue, offset).extract_${outer}_${inner}(offset));
+    assertEq(container, container.replace_${outer}_${inner}(newValue, offset).replace_${outer}_${inner}(oldValue, offset));
+}`;
+
+// GENERATE
+module.exports = format(
+  header.trimEnd(),
+  '',
+  'contract PackingTest is Test {',
+  '    using Packing for *;',
+  product(SIZES, SIZES)
+    .filter(([left, right]) => SIZES.includes(left + right))
+    .map(([left, right]) => testPack(left, right)),
+  product(SIZES, SIZES)
+    .filter(([outer, inner]) => outer > inner)
+    .map(([outer, inner]) => testReplace(outer, inner)),
+  '}',
+);