Add extra memory manipulation functions

.changeset/dull-students-eat.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`Memory`: Add library with utilities to manipulate memory

contracts/mocks/Stateless.sol

@@ -49,6 +49,7 @@ import {SignatureChecker} from "../utils/cryptography/SignatureChecker.sol";
 import {SignedMath} from "../utils/math/SignedMath.sol";
 import {StorageSlot} from "../utils/StorageSlot.sol";
 import {Strings} from "../utils/Strings.sol";
+import {Memory} from "../utils/Memory.sol";
 import {Time} from "../utils/types/Time.sol";
 
 contract Dummy1234 {}

contracts/utils/Memory.sol

@@ -0,0 +1,104 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.20;
+
+/**
+ * @dev Utilities to manipulate memory.
+ *
+ * Memory is a contiguous and dynamic byte array in which Solidity stores non-primitive types.
+ * This library provides functions to manipulate pointers to this dynamic array.
+ *
+ * WARNING: When manipulating memory, make sure to follow the Solidity documentation
+ * guidelines for https://docs.soliditylang.org/en/v0.8.20/assembly.html#memory-safety[Memory Safety].
+ */
+library Memory {
+    type Pointer is bytes32;
+
+    /// @dev Returns a `Pointer` to the current free `Pointer`.
+    function getFreeMemoryPointer() internal pure returns (Pointer ptr) {
+        assembly ("memory-safe") {
+            ptr := mload(0x40)
+        }
+    }
+
+    /// @dev Sets the free `Pointer` to a specific value.
+    ///
+    /// WARNING: Everything after the pointer may be overwritten.
+    function setFreeMemoryPointer(Pointer ptr) internal pure {
+        assembly ("memory-safe") {
+            mstore(0x40, ptr)
+        }
+    }
+
+    /// @dev Returns a `Pointer` to the content of a `bytes` buffer. Skips the length word.
+    function contentPointer(bytes memory buffer) internal pure returns (Pointer) {
+        return addOffset(asPointer(buffer), 32);
+    }
+
+    /**
+     * @dev Copies `length` bytes from `srcPtr` to `destPtr`. Equivalent to https://www.evm.codes/?fork=cancun#5e[`mcopy`].
+     *
+     * WARNING: Reading or writing beyond the allocated memory bounds of either pointer
+     * will result in undefined behavior and potential memory corruption.
+     */
+    function copy(Pointer destPtr, Pointer srcPtr, uint256 length) internal pure {
+        assembly ("memory-safe") {
+            mcopy(destPtr, srcPtr, length)
+        }
+    }
+
+    /**
+     * @dev Extracts a `bytes1` from a `Pointer`. `offset` starts from the most significant byte.
+     *
+     * NOTE: Will return `0x00` if `offset` is larger or equal to `32`.
+     */
+    function loadByte(Pointer ptr, uint256 offset) internal pure returns (bytes1 v) {
+        bytes32 word = load(ptr);
+        assembly ("memory-safe") {
+            v := byte(offset, word)
+        }
+    }
+
+    /// @dev Extracts a `bytes32` from a `Pointer`.
+    function load(Pointer ptr) internal pure returns (bytes32 v) {
+        assembly ("memory-safe") {
+            v := mload(ptr)
+        }
+    }
+
+    /// @dev Adds an offset to a `Pointer`.
+    function addOffset(Pointer ptr, uint256 offset) internal pure returns (Pointer) {
+        return asPointer(bytes32(asUint256(ptr) + offset));
+    }
+
+    /// @dev `Pointer` to `bytes32`. Expects a pointer to a properly ABI-encoded `bytes` object.
+    function asBytes32(Pointer ptr) internal pure returns (bytes32) {
+        return Pointer.unwrap(ptr);
+    }
+
+    /// @dev `Pointer` to `uint256`. Expects a pointer to a properly ABI-encoded `bytes` object.
+    function asUint256(Pointer ptr) internal pure returns (uint256) {
+        return uint256(asBytes32(ptr));
+    }
+
+    /// @dev `bytes32` to `Pointer`. Expects a pointer to a properly ABI-encoded `bytes` object.
+    function asPointer(bytes32 value) internal pure returns (Pointer) {
+        return Pointer.wrap(value);
+    }
+
+    /// @dev Returns a `Pointer` to the `value`'s header (i.e. includes the length word).
+    function asPointer(bytes memory value) internal pure returns (Pointer) {
+        bytes32 ptr;
+        assembly ("memory-safe") {
+            ptr := value
+        }
+        return asPointer(ptr);
+    }
+
+    /// @dev `Pointer` to `bytes`. Expects a pointer to a properly ABI-encoded `bytes` object.
+    function asBytes(Pointer ptr) internal pure returns (bytes memory b) {
+        assembly ("memory-safe") {
+            b := ptr
+        }
+    }
+}

contracts/utils/README.adoc

@@ -38,6 +38,7 @@ Miscellaneous contracts and libraries containing utility functions you can use t
  * {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].
  * {Comparators}: A library that contains comparator functions to use with the {Heap} library.
  * {CAIP2}, {CAIP10}: Libraries for formatting and parsing CAIP-2 and CAIP-10 identifiers.
+ * {Memory}: A utility library to manipulate memory.
  * {InteroperableAddress}: Library for formatting and parsing ERC-7930 interoperable addresses.
  * {Blockhash}: A library for accessing historical block hashes beyond the standard 256 block limit utilizing EIP-2935's historical blockhash functionality.
  * {Time}: A library that provides helpers for manipulating time-related objects, including a `Delay` type.
@@ -135,6 +136,8 @@ Ethereum contracts have no native concept of an interface, so applications must
 
 {{CAIP10}}
 
+{{Memory}}
+
 {{InteroperableAddress}}
 
 {{Blockhash}}

docs/modules/ROOT/pages/utilities.adoc

@@ -263,7 +263,7 @@ Some use cases require more powerful data structures than arrays and mappings of
 - xref:api:utils.adoc#EnumerableSet[`EnumerableSet`]: A https://en.wikipedia.org/wiki/Set_(abstract_data_type)[set] with enumeration capabilities.
 - xref:api:utils.adoc#EnumerableMap[`EnumerableMap`]: A `mapping` variant with enumeration capabilities.
 - xref:api:utils.adoc#MerkleTree[`MerkleTree`]: An on-chain https://wikipedia.org/wiki/Merkle_Tree[Merkle Tree] with helper functions.
-- xref:api:utils.adoc#Heap.sol[`Heap`]: A 
+- xref:api:utils.adoc#Heap.sol[`Heap`]: A https://en.wikipedia.org/wiki/Binary_heap[binary heap] to store elements with priority defined by a compartor function.
 
 The `Enumerable*` structures are similar to mappings in that they store and remove elements in constant time and don't allow for repeated entries, but they also support _enumeration_, which means you can easily query all stored entries both on and off-chain.
 
@@ -461,6 +461,55 @@ await instance.multicall([
 ]);
 ----
 
+=== Memory
+
+The xref:api:utils.adoc#Memory[`Memory`] library provides functions for advanced use cases that require granular memory management. A common use case is to avoid unnecessary memory expansion costs when performing repeated operations that allocate memory in a loop. Consider the following example:
+
+[source,solidity]
+----
+function processMultipleItems(uint256[] memory items) internal {
+  for (uint256 i = 0; i < items.length; i++) {
+    bytes memory tempData = abi.encode(items[i], block.timestamp);
+    // Process tempData...
+  }
+}
+----
+
+Note that each iteration allocates new memory for `tempData`, causing the memory to expand continuously. This can be optimized by resetting the memory pointer between iterations:
+
+[source,solidity]
+----
+function processMultipleItems(uint256[] memory items) internal {
+  Memory.Pointer ptr = Memory.getFreeMemoryPointer(); // Cache pointer
+  for (uint256 i = 0; i < items.length; i++) {
+    bytes memory tempData = abi.encode(items[i], block.timestamp);
+    // Process tempData...
+    Memory.setFreeMemoryPointer(ptr); // Reset pointer for reuse
+  }
+}
+----
+
+This way, memory allocated for `tempData` in each iteration is reused, significantly reducing memory expansion costs when processing many items.
+
+==== Copying memory buffers
+
+The `Memory` library provides a `copy` function that allows copying data between memory locations. This is useful when you need to extract a segment of data from a larger buffer or when you want to avoid unnecessary memory allocations. The following example demonstrates how to copy a segment of data from a source buffer:
+
+[source,solidity]
+----
+function copyDataSegment(bytes memory source, uint256 offset, uint256 length) 
+    internal pure returns (bytes memory result) {
+
+    result = new bytes(length);
+    Memory.Pointer srcPtr = Memory.addOffset(Memory.contentPointer(source), offset);
+    Memory.Pointer destPtr = Memory.contentPointer(result);
+
+    Memory.copy(destPtr, srcPtr, length);
+}
+----
+
+IMPORTANT: Manual memory management increases gas costs and prevents compiler optimizations. Only use these functions after profiling confirms they're necessary. By default, Solidity handles memory safely - using this library without understanding memory layout and safety may be dangerous. See the https://docs.soliditylang.org/en/v0.8.20/internals/layout_in_memory.html[memory layout] and https://docs.soliditylang.org/en/v0.8.20/assembly.html#memory-safety[memory safety] documentation for details.
+
 === Historical Block Hashes
 
 xref:api:utils.adoc#Blockhash[`Blockhash`] provides L2 protocol developers with extended access to historical block hashes beyond Ethereum's native 256-block limit. By leveraging https://eips.ethereum.org/EIPS/eip-2935[EIP-2935]'s history storage contract, the library enables access to block hashes up to 8,191 blocks in the past, making it invaluable for L2 fraud proofs and state verification systems.

test/utils/Memory.t.sol

@@ -0,0 +1,67 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.20;
+
+import {Test} from "forge-std/Test.sol";
+import {Memory} from "@openzeppelin/contracts/utils/Memory.sol";
+
+contract MemoryTest is Test {
+    using Memory for *;
+
+    // - first 0x80 bytes are reserved (scratch + FMP + zero)
+    uint256 constant START_PTR = 0x80;
+    // - moving the free memory pointer to far causes OOG errors
+    uint256 constant END_PTR = type(uint24).max;
+
+    function testGetsetFreeMemoryPointer(uint256 seed) public pure {
+        bytes32 ptr = bytes32(bound(seed, START_PTR, END_PTR));
+        ptr.asPointer().setFreeMemoryPointer();
+        assertEq(Memory.getFreeMemoryPointer().asBytes32(), ptr);
+    }
+
+    function testSymbolicContentPointer(uint256 seed) public pure {
+        Memory.Pointer ptr = bytes32(bound(seed, START_PTR, END_PTR)).asPointer();
+        assertEq(ptr.asBytes().contentPointer().asBytes32(), ptr.addOffset(32).asBytes32());
+    }
+
+    function testCopy(bytes memory data, uint256 destSeed) public pure {
+        uint256 minDestPtr = Memory.getFreeMemoryPointer().asUint256();
+        Memory.Pointer destPtr = bytes32(bound(destSeed, minDestPtr, minDestPtr + END_PTR)).asPointer();
+        destPtr.addOffset(data.length + 32).setFreeMemoryPointer();
+        destPtr.copy(data.asPointer(), data.length + 32);
+        bytes memory copiedData = destPtr.asBytes();
+        assertEq(data.length, copiedData.length);
+        for (uint256 i = 0; i < data.length; i++) {
+            assertEq(data[i], copiedData[i]);
+        }
+    }
+
+    function testLoadByte(uint256 seed, uint256 index, bytes32 value) public pure {
+        index = bound(index, 0, 31);
+        Memory.Pointer ptr = bytes32(bound(seed, START_PTR, END_PTR)).asPointer();
+
+        assembly ("memory-safe") {
+            mstore(ptr, value)
+        }
+
+        bytes1 expected;
+        assembly ("memory-safe") {
+            expected := byte(index, value)
+        }
+        assertEq(ptr.loadByte(index), expected);
+    }
+
+    function testLoad(uint256 seed, bytes32 value) public pure {
+        Memory.Pointer ptr = bytes32(bound(seed, START_PTR, END_PTR)).asPointer();
+        assembly ("memory-safe") {
+            mstore(ptr, value)
+        }
+        assertEq(ptr.load(), value);
+    }
+
+    function testSymbolicAddOffset(uint256 seed, uint256 offset) public pure {
+        offset = bound(offset, 0, type(uint256).max - END_PTR);
+        Memory.Pointer ptr = bytes32(bound(seed, START_PTR, END_PTR)).asPointer();
+        assertEq(ptr.addOffset(offset).asUint256(), ptr.asUint256() + offset);
+    }
+}

test/utils/Memory.test.js

@@ -0,0 +1,91 @@
+const { ethers } = require('hardhat');
+const { expect } = require('chai');
+const { loadFixture } = require('@nomicfoundation/hardhat-network-helpers');
+
+async function fixture() {
+  const mock = await ethers.deployContract('$Memory');
+
+  return { mock };
+}
+
+describe('Memory', function () {
+  beforeEach(async function () {
+    Object.assign(this, await loadFixture(fixture));
+  });
+
+  describe('free pointer', function () {
+    it('sets free memory pointer', async function () {
+      const ptr = ethers.toBeHex(0xa0, 32);
+      await expect(this.mock.$setFreeMemoryPointer(ptr)).to.not.be.reverted;
+    });
+
+    it('gets free memory pointer', async function () {
+      await expect(this.mock.$getFreeMemoryPointer()).to.eventually.equal(
+        ethers.toBeHex(0x80, 32), // Default pointer
+      );
+    });
+  });
+
+  it('load extracts a word', async function () {
+    const ptr = await this.mock.$getFreeMemoryPointer();
+    await expect(this.mock.$load(ptr)).to.eventually.equal(ethers.toBeHex(0, 32));
+  });
+
+  it('loadByte extracts a byte', async function () {
+    const ptr = await this.mock.$getFreeMemoryPointer();
+    await expect(this.mock.$loadByte(ptr, 0)).to.eventually.equal(ethers.toBeHex(0, 1));
+  });
+
+  it('contentPointer', async function () {
+    const data = ethers.toUtf8Bytes('hello world');
+    const result = await this.mock.$contentPointer(data);
+    expect(result).to.equal(ethers.toBeHex(0xa0, 32)); // 0x80 is the default free pointer (length)
+  });
+
+  describe('addOffset', function () {
+    it('addOffset', async function () {
+      const basePtr = ethers.toBeHex(0x80, 32);
+      const offset = 32;
+      const expectedPtr = ethers.toBeHex(0xa0, 32);
+
+      await expect(this.mock.$addOffset(basePtr, offset)).to.eventually.equal(expectedPtr);
+    });
+
+    it('addOffsetwraps around', async function () {
+      const basePtr = ethers.toBeHex(0x80, 32);
+      const offset = 256;
+      const expectedPtr = ethers.toBeHex(0x180, 32);
+      await expect(this.mock.$addOffset(basePtr, offset)).to.eventually.equal(expectedPtr);
+    });
+  });
+
+  describe('pointer conversions', function () {
+    it('asBytes32 / asPointer', async function () {
+      const ptr = ethers.toBeHex('0x1234', 32);
+      await expect(this.mock.$asBytes32(ptr)).to.eventually.equal(ptr);
+      await expect(this.mock.$asPointer(ethers.Typed.bytes32(ptr))).to.eventually.equal(ptr);
+    });
+
+    it('asBytes / asPointer', async function () {
+      const ptr = await this.mock.$asPointer(ethers.Typed.bytes(ethers.toUtf8Bytes('hello world')));
+      expect(ptr).to.equal(ethers.toBeHex(0x80, 32)); // Default free pointer
+      await expect(this.mock.$asBytes(ptr)).to.eventually.equal(ethers.toBeHex(0x20, 32));
+    });
+
+    it('asUint256', async function () {
+      const value = 0x1234;
+      const ptr = ethers.toBeHex(value, 32);
+      await expect(this.mock.$asUint256(ptr)).to.eventually.equal(value);
+    });
+  });
+
+  describe('memory operations', function () {
+    it('copy', async function () {
+      await expect(this.mock.$copy(ethers.toBeHex(0x80, 32), ethers.toBeHex(0xc0, 32), 32)).to.not.be.reverted;
+    });
+
+    it('copy with zero length', async function () {
+      await expect(this.mock.$copy(ethers.toBeHex(0x80, 32), ethers.toBeHex(0xc0, 32), 0)).to.not.be.reverted;
+    });
+  });
+});