From 0090897e344815a3d2c2fed4134fdff321e04d66 Mon Sep 17 00:00:00 2001
From: Vectorized <webby1111@hotmail.com>
Date: Fri, 6 Jun 2025 10:40:50 +0000
Subject: [PATCH] T

---
 docs/utils/libtransient.md   | 5 +++--
 src/utils/LibTransient.sol   | 5 +++--
 src/utils/g/LibTransient.sol | 5 +++--
 test/LibTransient.t.sol      | 4 +++-
 4 files changed, 12 insertions(+), 7 deletions(-)

diff --git a/docs/utils/libtransient.md b/docs/utils/libtransient.md
index 79dd418716..d9dd976cb8 100644
--- a/docs/utils/libtransient.md
+++ b/docs/utils/libtransient.md
@@ -832,8 +832,9 @@ Note: The value pointed to might not be cleared from previous usage.
 function peek(TStack storage ptr) internal view returns (bytes32 topPtr)
 ```
 
-Returns a pointer to the top element. Returns zero if the stack is empty.   
-This method can help avoid an additional `TLOAD`.
+Returns a pointer to the top element. Returns the zero pointer if the stack is empty.   
+This method can help avoid an additional `TLOAD`, but you MUST check if the   
+returned pointer is zero. And if it is, please DO NOT read / write to it.
 
 ### top(TStack)
 
diff --git a/src/utils/LibTransient.sol b/src/utils/LibTransient.sol
index bf1e40ee7f..b7151a4198 100644
--- a/src/utils/LibTransient.sol
+++ b/src/utils/LibTransient.sol
@@ -762,8 +762,9 @@ library LibTransient {
         }
     }
 
-    /// @dev Returns a pointer to the top element. Returns zero if the stack is empty.
-    /// This method can help avoid an additional `TLOAD`.
+    /// @dev Returns a pointer to the top element. Returns the zero pointer if the stack is empty.
+    /// This method can help avoid an additional `TLOAD`, but you MUST check if the
+    /// returned pointer is zero. And if it is, please DO NOT read / write to it.
     function peek(TStack storage ptr) internal view returns (bytes32 topPtr) {
         /// @solidity memory-safe-assembly
         assembly {
diff --git a/src/utils/g/LibTransient.sol b/src/utils/g/LibTransient.sol
index 268324900f..23b53a9696 100644
--- a/src/utils/g/LibTransient.sol
+++ b/src/utils/g/LibTransient.sol
@@ -772,8 +772,9 @@ library LibTransient {
         }
     }
 
-    /// @dev Returns a pointer to the top element. Returns zero if the stack is empty.
-    /// This method can help avoid an additional `TLOAD`.
+    /// @dev Returns a pointer to the top element. Returns the zero pointer if the stack is empty.
+    /// This method can help avoid an additional `TLOAD`, but you MUST check if the
+    /// returned pointer is zero. And if it is, please DO NOT read / write to it.
     function peek(TStack storage ptr) internal view returns (bytes32 topPtr) {
         /// @solidity memory-safe-assembly
         assembly {
diff --git a/test/LibTransient.t.sol b/test/LibTransient.t.sol
index 8a921ac4d7..1a279d2e65 100644
--- a/test/LibTransient.t.sol
+++ b/test/LibTransient.t.sol
@@ -325,7 +325,9 @@ contract LibTransientTest is SoladyTest {
 
         LibTransient.tStack(stackSlot).clear();
         assertEq(LibTransient.tStack(stackSlot).peek(), 0);
-        assertEq(LibTransient.tStack(stackSlot).peek().tBytes32().get(), 0);
+        if (stackSlot != 0) {
+            assertEq(LibTransient.tStack(stackSlot).peek().tBytes32().get(), 0);
+        }
 
         assertEq(LibTransient.tStack(stackSlot).length(), 0);
         for (uint256 i; i < n; ++i) {