Add Packing library

.changeset/heavy-baboons-give.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`Packing`: Added a new utility for packing and unpacking multiple values into a single bytes32.

contracts/utils/Packing.sol

@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.20;
+
+/**
+ * @dev Helper library packing and unpacking multiple values into bytes32
+ */
+library Packing {
+    type Uint128x2 is bytes32;
+
+    /// @dev Cast a bytes32 into a Uint128x2
+    function asUint128x2(bytes32 self) internal pure returns (Uint128x2) {
+        return Uint128x2.wrap(self);
+    }
+
+    /// @dev Cast a Uint128x2 into a bytes32
+    function asBytes32(Uint128x2 self) internal pure returns (bytes32) {
+        return Uint128x2.unwrap(self);
+    }
+
+    /// @dev Pack two uint128 into a Uint128x2
+    function pack(uint128 high128, uint128 low128) internal pure returns (Uint128x2) {
+        return Uint128x2.wrap(bytes32(bytes16(high128)) | bytes32(uint256(low128)));
+    }
+
+    /// @dev Split a Uint128x2 into two uint128
+    function split(Uint128x2 self) internal pure returns (uint128, uint128) {
+        return (high(self), low(self));
+    }
+
+    /// @dev Get the first element of a Uint128x2 (high part)
+    function high(Uint128x2 self) internal pure returns (uint128) {
+        return uint128(bytes16(Uint128x2.unwrap(self)));
+    }
+
+    /// @dev Get the second element of a Uint128x2 (low part)
+    function low(Uint128x2 self) internal pure returns (uint128) {
+        return uint128(uint256(Uint128x2.unwrap(self)));
+    }
+}

contracts/utils/README.adoc

@@ -32,6 +32,7 @@ Miscellaneous contracts and libraries containing utility functions you can use t
  * {StorageSlot}: Methods for accessing specific storage slots formatted as common primitive types. Also include primitives for reading from and writing to transient storage (only value types are currently supported).
  * {Multicall}: Abstract contract with an utility to allow batching together multiple calls in a single transaction. Useful for allowing EOAs to perform multiple operations at once.
  * {Context}: An utility for abstracting the sender and calldata in the current execution context.
+ * {Packing}: A library for packing and unpacking multiple values into bytes32
  * {Panic}: A library to revert with https://docs.soliditylang.org/en/v0.8.20/control-structures.html#panic-via-assert-and-error-via-require[Solidity panic codes].
 
 [NOTE]
@@ -117,4 +118,6 @@ Ethereum contracts have no native concept of an interface, so applications must
 
 {{Context}}
 
+{{Packing}}
+
 {{Panic}}

test/utils/Packing.t.sol

@@ -0,0 +1,27 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.20;
+
+import {Test} from "forge-std/Test.sol";
+import {Packing} from "@openzeppelin/contracts/utils/Packing.sol";
+
+contract Base64Test is Test {
+    using Packing for *;
+
+    // Pack a pair of arbitrary uint128, and check that split recovers the correct values
+    function testUint128x2(uint128 high, uint128 low) external {
+        Packing.Uint128x2 packed = Packing.pack(high, low);
+        assertEq(packed.high(), high);
+        assertEq(packed.low(), low);
+
+        (uint128 recoveredHigh, uint128 recoveredLow) = packed.split();
+        assertEq(recoveredHigh, high);
+        assertEq(recoveredLow, low);
+    }
+
+    // split an arbitrary bytes32 into a pair of uint128, and check that repack matches the input
+    function testUint128x2(bytes32 input) external {
+        (uint128 high, uint128 low) = input.asUint128x2().split();
+        assertEq(Packing.pack(high, low).asBytes32(), input);
+    }
+}

test/utils/Packing.test.js

@@ -0,0 +1,27 @@
+const { ethers } = require('hardhat');
+const { expect } = require('chai');
+const { loadFixture } = require('@nomicfoundation/hardhat-network-helpers');
+const { generators } = require('../helpers/random');
+
+async function fixture() {
+  return { mock: await ethers.deployContract('$Packing') };
+}
+
+describe('Packing', function () {
+  beforeEach(async function () {
+    Object.assign(this, await loadFixture(fixture));
+  });
+
+  it('Uint128x2', async function () {
+    const high = generators.uint256() % 2n ** 128n;
+    const low = generators.uint256() % 2n ** 128n;
+    const packed = ethers.hexlify(ethers.toBeArray((high << 128n) | low));
+
+    expect(await this.mock.$asUint128x2(packed)).to.equal(packed);
+    expect(await this.mock.$asBytes32(packed)).to.equal(packed);
+    expect(await this.mock.$pack(high, low)).to.equal(packed);
+    expect(await this.mock.$split(packed)).to.deep.equal([high, low]);
+    expect(await this.mock.$high(packed)).to.equal(high);
+    expect(await this.mock.$low(packed)).to.equal(low);
+  });
+});