Remove Memory.asPointer and Memory.asBytes32 + add warning about setting the FMP to a low value

.changeset/tangy-jokes-begin.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`Memory`: Remove the `asBytes32` and `asPointer` function to reduce the risk of mistakes when manipulating memory pointers.

CHANGELOG.md

@@ -8,6 +8,7 @@
 - `RLP`: The `encode(bytes32)` function now encodes `bytes32` as a fixed size item and not as a scalar in `encode(uint256)`. Users must replace calls to `encode(bytes32)` with `encode(uint256(bytes32))` to preserve the same behavior. ([#6167](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/6167))
 - `ERC4337Utils`: The `parseValidationData` now returns a `ValidationRange` as the last return tuple value indicating whether the `validationData` is compared against a timestamp or block number. Developers must update their code to handle this new return value (e.g. `(aggregator, validAfter, validUntil) -> (aggregator, validAfter, validUntil, range)`).
 - `SignerWebAuthn`: The `_rawSignatureValidation` function now returns `false` when the signature is not a valid WebAuthn authentication assertion. P256 fallback is removed. Developers can add it back by overriding the function.
+- `Memory`: The `setFreeMemoryPointer` function is renamed to `unsafeSetFreeMemoryPointer`. Developers should use `unsafeSetFreeMemoryPointer` instead of `setFreeMemoryPointer` after v5.6.0.
 
 ## 5.5.0 (2025-10-31)
 

contracts/token/ERC20/extensions/ERC4626.sol

@@ -111,7 +111,7 @@ abstract contract ERC4626 is ERC20, IERC4626 {
             address(asset_),
             abi.encodeCall(IERC20Metadata.decimals, ())
         );
-        Memory.setFreeMemoryPointer(ptr);
+        Memory.unsafeSetFreeMemoryPointer(ptr);
 
         return
             (success && LowLevelCall.returnDataSize() >= 32 && uint256(returnedDecimals) <= type(uint8).max)

contracts/utils/Memory.sol

@@ -30,24 +30,18 @@ library Memory {
     /**
      * @dev Sets the free `Pointer` to a specific value.
      *
+     * The solidity memory layout requires that the FMP is never set to a value lower than 0x80. Setting the
+     * FMP to a value lower than 0x80 may cause unexpected behavior. Deallocating all memory can be achieved by
+     * setting the FMP to 0x80.
+     *
      * WARNING: Everything after the pointer may be overwritten.
      **/
-    function setFreeMemoryPointer(Pointer ptr) internal pure {
+    function unsafeSetFreeMemoryPointer(Pointer ptr) internal pure {
         assembly ("memory-safe") {
             mstore(0x40, ptr)
         }
     }
 
-    /// @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 `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 Move a pointer forward by a given offset.
     function forward(Pointer ptr, uint256 offset) internal pure returns (Pointer) {
         return Pointer.wrap(bytes32(uint256(Pointer.unwrap(ptr)) + offset));

contracts/utils/cryptography/TrieProof.sol

@@ -183,7 +183,7 @@ library TrieProof {
             }
 
             // Reset memory before next iteration. Deallocates `decoded` and `path`.
-            Memory.setFreeMemoryPointer(fmp);
+            Memory.unsafeSetFreeMemoryPointer(fmp);
         }
 
         // If we've gone through all proof elements without finding a value, the proof is invalid

contracts/utils/structs/Accumulators.sol

@@ -125,6 +125,6 @@ library Accumulators {
     }
 
     function _nullPtr() private pure returns (Memory.Pointer) {
-        return Memory.asPointer(0x00);
+        return Memory.Pointer.wrap(0);
     }
 }

docs/modules/ROOT/pages/utilities.adoc

@@ -527,7 +527,7 @@ 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...
-    Memory.setFreeMemoryPointer(ptr); // Reset pointer for reuse
+    Memory.unsafeSetFreeMemoryPointer(ptr); // Reset pointer for reuse
   }
 }
 ----

test/utils/Memory.t.sol

@@ -15,10 +15,10 @@ contract MemoryTest is Test {
     // - moving the free memory pointer to far causes OOG errors
     uint256 constant END_PTR = type(uint24).max;
 
-    function testGetsetFreeMemoryPointer(uint256 seed) public pure {
+    function testGetSetFreeMemoryPointer(uint256 seed) public pure {
         bytes32 ptr = bytes32(bound(seed, START_PTR, END_PTR));
-        ptr.asPointer().setFreeMemoryPointer();
-        assertEq(Memory.getFreeMemoryPointer().asBytes32(), ptr);
+        Memory.Pointer.wrap(ptr).unsafeSetFreeMemoryPointer();
+        assertEq(Memory.Pointer.unwrap(Memory.getFreeMemoryPointer()), ptr);
     }
 
     function testAsSliceToBytes(bytes memory input) public pure {

test/utils/Memory.test.js

@@ -22,7 +22,7 @@ describe('Memory', function () {
     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;
+        await expect(this.mock.$unsafeSetFreeMemoryPointer(ptr)).to.not.be.reverted;
       });
 
       it('gets free memory pointer', async function () {
@@ -31,18 +31,6 @@ describe('Memory', function () {
         );
       });
     });
-
-    describe('pointer conversions', function () {
-      it('asBytes32', async function () {
-        const ptr = ethers.toBeHex('0x1234', 32);
-        await expect(this.mock.$asBytes32(ptr)).to.eventually.equal(ptr);
-      });
-
-      it('asPointer', async function () {
-        const ptr = ethers.toBeHex('0x1234', 32);
-        await expect(this.mock.$asPointer(ptr)).to.eventually.equal(ptr);
-      });
-    });
   });
 
   describe('Slices', function () {