From 3b635ddd55c227e0875c895d97f734d102ad2266 Mon Sep 17 00:00:00 2001
From: Simone Orsi <241460653+simone-stacks@users.noreply.github.com>
Date: Tue, 19 May 2026 10:25:11 +0000
Subject: [PATCH 1/4] docs: drop stale Err(NotInPreparePhase) claim in
 get_nakamoto_reward_cycle_info

---
 stackslib/src/chainstate/nakamoto/coordinator/mod.rs | 1 -
 1 file changed, 1 deletion(-)

diff --git a/stackslib/src/chainstate/nakamoto/coordinator/mod.rs b/stackslib/src/chainstate/nakamoto/coordinator/mod.rs
index 0e17267361f..d2e9e175c86 100644
--- a/stackslib/src/chainstate/nakamoto/coordinator/mod.rs
+++ b/stackslib/src/chainstate/nakamoto/coordinator/mod.rs
@@ -293,7 +293,6 @@ fn find_prepare_phase_sortitions(
 ///
 /// Returns Ok(Some(reward-cycle-info)) if we found the first sortition in the prepare phase.
 /// Returns Ok(None) if we're still waiting for the PoX anchor block sortition
-/// Returns Err(Error::NotInPreparePhase) if `burn_height` is not in the prepare phase
 pub fn get_nakamoto_reward_cycle_info<U: RewardSetProvider>(
     sortition_tip: &SortitionId,
     reward_cycle: u64,

From a1b38188afd4780fe6a594b5f5beb288dbf26db3 Mon Sep 17 00:00:00 2001
From: Simone Orsi <241460653+simone-stacks@users.noreply.github.com>
Date: Tue, 19 May 2026 10:25:23 +0000
Subject: [PATCH 2/4] docs: replace 'Panics if' with 'Returns Err if' in
 increase_lock_v2/v3

---
 clarity/src/vm/database/structures.rs | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/clarity/src/vm/database/structures.rs b/clarity/src/vm/database/structures.rs
index 9741f3fb4ff..efcee4cffa5 100644
--- a/clarity/src/vm/database/structures.rs
+++ b/clarity/src/vm/database/structures.rs
@@ -544,7 +544,7 @@ impl<'db, 'conn> STXBalanceSnapshot<'db, 'conn> {
     }
 
     /// Increase the account's current lock to `new_total_locked`.
-    /// Panics if `self` was not locked by V2 PoX.
+    /// Returns `Err` if `self` was not locked by V2 PoX.
     pub fn increase_lock_v2(&mut self, new_total_locked: u128) -> Result<(), VmExecutionError> {
         let unlocked = self.unlock_available_tokens_if_any()?;
         if unlocked > 0 {
@@ -763,7 +763,7 @@ impl<'db, 'conn> STXBalanceSnapshot<'db, 'conn> {
     }
 
     /// Increase the account's current lock to `new_total_locked`.
-    /// Panics if `self` was not locked by V3 PoX.
+    /// Returns `Err` if `self` was not locked by V3 PoX.
     pub fn increase_lock_v3(&mut self, new_total_locked: u128) -> Result<(), VmExecutionError> {
         let unlocked = self.unlock_available_tokens_if_any()?;
         if unlocked > 0 {

From 9212c78f1c6e7ea732fe90ba632ecbfcc3af31d5 Mon Sep 17 00:00:00 2001
From: Simone Orsi <241460653+simone-stacks@users.noreply.github.com>
Date: Tue, 19 May 2026 10:25:28 +0000
Subject: [PATCH 3/4] docs: fix increase_lock_v4 panic doc to cite V4 PoX (was
 V3)

---
 clarity/src/vm/database/structures.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/clarity/src/vm/database/structures.rs b/clarity/src/vm/database/structures.rs
index efcee4cffa5..c7c1e26d636 100644
--- a/clarity/src/vm/database/structures.rs
+++ b/clarity/src/vm/database/structures.rs
@@ -889,7 +889,7 @@ impl<'db, 'conn> STXBalanceSnapshot<'db, 'conn> {
     }
 
     /// Increase the account's current lock to `new_total_locked`.
-    /// Panics if `self` was not locked by V3 PoX.
+    /// Panics if `self` was not locked by V4 PoX.
     pub fn increase_lock_v4(&mut self, new_total_locked: u128) -> Result<(), VmExecutionError> {
         let unlocked = self.unlock_available_tokens_if_any()?;
         if unlocked > 0 {

From 2b68b2b14f05fdaf3dddc027ddc8d381ab675a04 Mon Sep 17 00:00:00 2001
From: Simone Orsi <241460653+simone-stacks@users.noreply.github.com>
Date: Tue, 19 May 2026 10:25:33 +0000
Subject: [PATCH 4/4] docs: add SAFETY annotations to DoubleSha256
 into_le/into_be transmute blocks

---
 stacks-common/src/util/hash.rs | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/stacks-common/src/util/hash.rs b/stacks-common/src/util/hash.rs
index e33483d18ca..3bacd9e7e63 100644
--- a/stacks-common/src/util/hash.rs
+++ b/stacks-common/src/util/hash.rs
@@ -312,6 +312,11 @@ impl DoubleSha256 {
     #[inline]
     pub fn into_le(self) -> Uint256 {
         let DoubleSha256(data) = self;
+        // SAFETY: source `[u8; 32]` and target `[u64; 4]` have the same size
+        // (32 bytes) and both are POD with no invalid bit patterns. The
+        // transmute reinterprets the bytes as four u64 limbs in the host's
+        // native byte order; the subsequent `to_le()` loop normalizes each
+        // limb to little-endian so the result is host-independent.
         let mut ret: [u64; 4] = unsafe { mem::transmute(data) };
         for x in ret.iter_mut() {
             *x = x.to_le();
@@ -324,6 +329,11 @@ impl DoubleSha256 {
     pub fn into_be(self) -> Uint256 {
         let DoubleSha256(mut data) = self;
         data.reverse();
+        // SAFETY: source `[u8; 32]` and target `[u64; 4]` have the same size
+        // (32 bytes) and both are POD with no invalid bit patterns. The
+        // transmute reinterprets the (reversed) bytes as four u64 limbs in
+        // the host's native byte order; the subsequent `to_be()` loop
+        // normalizes each limb to big-endian so the result is host-independent.
         let mut ret: [u64; 4] = unsafe { mem::transmute(data) };
         for x in ret.iter_mut() {
             *x = x.to_be();