fix: comments, var-name in pox-5

Author: hstove-stacks

changelog.d/pox-5-comments.fixed

@@ -0,0 +1 @@
+Clarify PoX-5 naming and comments: add `BOND_LENGTH_PERIODS`, rename `stake-update`'s `prev-unlock-height` response field to `prev-unlock-cycle`, and fix outdated comments around signer grants, prepare-phase callers, and `stake-update` lock handling

contrib/core-contract-tests/tests/clarigen-types.ts

@@ -5708,7 +5708,7 @@ export const contracts = {
                   { name: 'cycles-to-extend', type: 'uint128' },
                   { name: 'num-cycles', type: 'uint128' },
                   { name: 'old-signer', type: 'principal' },
-                  { name: 'prev-unlock-height', type: 'uint128' },
+                  { name: 'prev-unlock-cycle', type: 'uint128' },
                   { name: 'signer', type: 'principal' },
                   { name: 'staker', type: 'principal' },
                   { name: 'unlock-burn-height', type: 'uint128' },
@@ -5734,7 +5734,7 @@ export const contracts = {
             cyclesToExtend: bigint;
             numCycles: bigint;
             oldSigner: string;
-            prevUnlockHeight: bigint;
+            prevUnlockCycle: bigint;
             signer: string;
             staker: string;
             unlockBurnHeight: bigint;
@@ -7380,6 +7380,11 @@ export const contracts = {
         type: 'uint128',
         access: 'constant',
       } as TypedAbiVariable<bigint>,
+      BOND_LENGTH_PERIODS: {
+        name: 'BOND_LENGTH_PERIODS',
+        type: 'uint128',
+        access: 'constant',
+      } as TypedAbiVariable<bigint>,
       ERR_ACTIVE_BOND_NOT_INCLUDED: {
         name: 'ERR_ACTIVE_BOND_NOT_INCLUDED',
         type: {
@@ -7994,6 +7999,7 @@ export const contracts = {
       BITCOIN_LOCKTIME_THRESHOLD: 500_000_000n,
       BOND_GAP_CYCLES: 2n,
       BOND_LENGTH_CYCLES: 12n,
+      BOND_LENGTH_PERIODS: 6n,
       ERR_ACTIVE_BOND_NOT_INCLUDED: {
         isOk: false,
         value: 33n,
@@ -8452,7 +8458,7 @@ export const contracts = {
                   { name: 'cycles-to-extend', type: 'uint128' },
                   { name: 'num-cycles', type: 'uint128' },
                   { name: 'old-signer', type: 'principal' },
-                  { name: 'prev-unlock-height', type: 'uint128' },
+                  { name: 'prev-unlock-cycle', type: 'uint128' },
                   { name: 'signer', type: 'principal' },
                   { name: 'staker', type: 'principal' },
                   { name: 'unlock-burn-height', type: 'uint128' },
@@ -8478,7 +8484,7 @@ export const contracts = {
             cyclesToExtend: bigint;
             numCycles: bigint;
             oldSigner: string;
-            prevUnlockHeight: bigint;
+            prevUnlockCycle: bigint;
             signer: string;
             staker: string;
             unlockBurnHeight: bigint;

contrib/core-contract-tests/tests/pox-5/commands/StakeExtend.ts

@@ -136,7 +136,7 @@ export const StakeExtend = (accounts: Real['accounts']) =>
           // Receipt reflects the new unlock cycle; amount and signer unchanged.
           expect(receipt.value.unlockCycle).toBe(expectedUnlockCycle);
           expect(receipt.value.unlockBurnHeight).toBe(expectedUnlockBurnHeight);
-          expect(receipt.value.prevUnlockHeight).toBe(prevUnlockCycle);
+          expect(receipt.value.prevUnlockCycle).toBe(prevUnlockCycle);
           expect(receipt.value.amountUstx).toBe(expectedAmountUstx);
           expect(receipt.value.signer).toBe(signer);
           expect(receipt.value.staker).toBe(r.sender);

contrib/core-contract-tests/tests/pox-5/commands/StakeUpdate.ts

@@ -132,7 +132,7 @@ export const StakeUpdate = (accounts: Real['accounts']) =>
           // Receipt reflects the recomputed unlock cycle and new amount/signer.
           expect(receipt.value.unlockCycle).toBe(expectedUnlockCycle);
           expect(receipt.value.unlockBurnHeight).toBe(expectedUnlockBurnHeight);
-          expect(receipt.value.prevUnlockHeight).toBe(prevUnlockCycle);
+          expect(receipt.value.prevUnlockCycle).toBe(prevUnlockCycle);
           expect(receipt.value.amountUstx).toBe(expectedAmountUstx);
           expect(receipt.value.signer).toBe(newSigner);
           expect(receipt.value.staker).toBe(r.sender);

pox-locking/src/pox_5.rs

@@ -440,8 +440,8 @@ fn handle_lockup_pox_v5(
     }
 }
 
-/// Handle responses from stake-extend and stake-extend-pooled in pox-5 -- functions that
-/// *extend already-locked* STX.
+/// Handle responses from `stake-update` in pox-5 -- the function that
+/// *extends or increases already-locked* STX.
 fn handle_stake_lockup_update_pox_v5(
     global_context: &mut GlobalContext,
     function_name: &str,
@@ -677,7 +677,7 @@ mod tests {
                 ),
                 (ClarityName::from_literal("num-cycle"), Value::UInt(1)),
                 (
-                    ClarityName::from_literal("prev-unlock-height"),
+                    ClarityName::from_literal("prev-unlock-cycle"),
                     Value::UInt(2),
                 ),
                 (

stackslib/src/chainstate/stacks/boot/pox-5.clar

@@ -74,6 +74,11 @@
 (define-constant BOND_LENGTH_CYCLES u12)
 ;; The gap between the start of different bond periods
 (define-constant BOND_GAP_CYCLES u2)
+;; Bond length measured in bond-period indices
+;; (`BOND_LENGTH_CYCLES / BOND_GAP_CYCLES`). Also the maximum number of
+;; concurrently active bond periods (and the `(list 6 ...)` bound used for
+;; bond-period arguments).
+(define-constant BOND_LENGTH_PERIODS u6)
 ;; The maximum amount of time that a user can stake for
 (define-constant MAX_NUM_CYCLES u96)
 
@@ -860,7 +865,7 @@
             (bond-index (get bond-index current-membership))
             (current-cycle (current-pox-reward-cycle))
             (bond-start-cycle (bond-period-to-reward-cycle bond-index))
-            (bond-end-cycle (bond-period-to-reward-cycle (+ bond-index u6)))
+            (bond-end-cycle (bond-period-to-reward-cycle (+ bond-index BOND_LENGTH_PERIODS)))
             (next-cycle (+ current-cycle u1))
             ;; If the bond hasn't started yet, then the first cycle where
             ;; this new signer is active is the start cycle. Otherwise, it's the next reward
@@ -1159,7 +1164,7 @@
                 staker: tx-sender,
                 signer: signer,
                 old-signer: old-signer,
-                prev-unlock-height: prev-unlock-cycle,
+                prev-unlock-cycle: prev-unlock-cycle,
                 unlock-cycle: unlock-cycle,
                 num-cycles: num-cycles,
                 amount-ustx: new-lock-amount,
@@ -1204,7 +1209,7 @@
             (signer (get signer membership))
             (current-cycle (current-pox-reward-cycle))
             (bond-start-cycle (bond-period-to-reward-cycle bond-index))
-            (bond-end-cycle (bond-period-to-reward-cycle (+ bond-index u6)))
+            (bond-end-cycle (bond-period-to-reward-cycle (+ bond-index BOND_LENGTH_PERIODS)))
             (current-total-staked (get-total-sbtc-staked-for-bond bond-index))
             (first-changed-reward-cycle (clamp current-cycle bond-start-cycle bond-end-cycle))
             (amount-sats (get amount-sats membership))
@@ -1271,7 +1276,7 @@
             (signer (get signer membership))
             (current-cycle (current-pox-reward-cycle))
             (bond-start-cycle (bond-period-to-reward-cycle bond-index))
-            (bond-end-cycle (bond-period-to-reward-cycle (+ bond-index u6)))
+            (bond-end-cycle (bond-period-to-reward-cycle (+ bond-index BOND_LENGTH_PERIODS)))
             (first-changed-reward-cycle (clamp current-cycle bond-start-cycle bond-end-cycle))
             (num-cycles (- bond-end-cycle first-changed-reward-cycle))
             (current-amount-sats (get amount-sats membership))
@@ -2279,7 +2284,7 @@
             ))
             (calculation-height (get calculation-height accumulator))
             (bond-start-height (bond-period-to-burn-height bond-index))
-            (bond-end-height (bond-period-to-burn-height (+ bond-index u6)))
+            (bond-end-height (bond-period-to-burn-height (+ bond-index BOND_LENGTH_PERIODS)))
         )
         ;; Verify that we're paying out bonds in the right order
         (match (get last-bond-stx-value-ratio accumulator)
@@ -2859,9 +2864,9 @@
     )
 )
 
-;; Construct the message hash for validating a signer key grant. Unlike [get-signer-key-message-hash],
-;; this message hash does not include `max-amount`, `period`, or `reward-cycle`. The topic is always `"grant-authorization"`.
-;; The `pox-addr` field is optional. When `none`, it means the signer key can be used for any PoX address.
+;; Construct the message hash for validating a signer key grant.
+;; Unlike [get-signer-key-message-hash], this hash covers only
+;; `signer-manager` and `auth-id`. The topic is always `"grant-authorization"`.
 (define-read-only (get-signer-grant-message-hash
         (signer-manager principal)
         (auth-id uint)
@@ -2951,8 +2956,9 @@
 
 ;; Reject calls that would modify the next reward cycle's signer / staker
 ;; set during the current cycle's prepare phase, when that set is frozen.
-;; Used by `stake`, `stake-update`, `register-for-bond`, and
-;; `update-bond-registration` as `(try! (verify-not-prepare-phase))`.
+;; Used by `stake`, `stake-update`, `register-for-bond`,
+;; `update-bond-registration`, `announce-l1-early-exit`, and `unstake-sbtc`
+;; as `(try! (verify-not-prepare-phase))`.
 (define-private (verify-not-prepare-phase)
     (ok (asserts! (not (is-in-prepare-phase (current-pox-reward-cycle)))
         ERR_STAKE_IN_PREPARE_PHASE
@@ -3030,7 +3036,7 @@
     )
     (let (
             (bond-start-height (bond-period-to-burn-height bond-index))
-            (bond-end-height (bond-period-to-burn-height (+ bond-index u6)))
+            (bond-end-height (bond-period-to-burn-height (+ bond-index BOND_LENGTH_PERIODS)))
         )
         (and
             (is-some (map-get? protocol-bonds bond-index))
@@ -3340,7 +3346,7 @@
 ;; Returns the expected L1 unlock height for a given bond index.
 ;; This is equal to 1/2 of a reward cycle before the end of the bond period.
 (define-read-only (get-bond-l1-unlock-height (bond-index uint))
-    (- (bond-period-to-burn-height (+ bond-index u6))
+    (- (bond-period-to-burn-height (+ bond-index BOND_LENGTH_PERIODS))
         (/ (var-get pox-reward-cycle-length) u2)
     )
 )

stackslib/src/chainstate/tests/snapshots/blockstack_lib__chainstate__tests__static_analysis_tests__tuple_merge_exceeds_max_value_size_cdeploy.snap

@@ -1,8 +1,6 @@
 ---
 source: stackslib/src/chainstate/tests/static_analysis_tests.rs
-assertion_line: 1453
 expression: result.get_expected_results()
-snapshot_kind: text
 ---
 [
   Failure(ExpectedFailureOutput(
@@ -26,7 +24,7 @@ snapshot_kind: text
     error: "Invalid Stacks block 3ccc7959909eb66e4071780c595ac12e8236872140cd9898fd3b3ddf4ddd118e: ClarityError(StaticCheck(StaticCheckError { err: Unreachable(\"Unexpected error type during static analysis: InvariantViolation(\\\"FAIL: .size() overflowed on too large of a type. Construction should have failed!\\\")\"), expressions: Some([SymbolicExpression { expr: List([SymbolicExpression { expr: Atom(ClarityName(\"ok\")), id: 172 }, SymbolicExpression { expr: List([SymbolicExpression { expr: Atom(ClarityName(\"merge\")), id: 174 }, SymbolicExpression { expr: Atom(ClarityName(\"ta\")), id: 175 }, SymbolicExpression { expr: Atom(ClarityName(\"tb\")), id: 176 }]), id: 173 }]), id: 171 }]), diagnostic: Diagnostic { level: Error, message: \"unexpected and unacceptable interpreter behavior: Unexpected error type during static analysis: InvariantViolation(\\\"FAIL: .size() overflowed on too large of a type. Construction should have failed!\\\")\", spans: [Span { start_line: 0, start_column: 0, end_line: 0, end_column: 0 }], suggestion: None } }))",
   )),
   Success(ExpectedBlockOutput(
-    marf_hash: "4307de3ba401cf8b0b249c3c14145052e474e176e0a4b17ccebdb16006d3f884",
+    marf_hash: "c3cb6ffa4b392cac63da6cf938ca01098875febd46b39efc067810280c080aae",
     evaluated_epoch: Epoch40,
     transactions: [
       ExpectedTransactionOutput(
@@ -56,7 +54,7 @@ snapshot_kind: text
     ),
   )),
   Success(ExpectedBlockOutput(
-    marf_hash: "96f223ffc56a0c83b9fce945840bda9861f0d7335e3b108fa0f1cc0cdbb032d2",
+    marf_hash: "411bce021acf12a5dcd67d012a1545c96676910b327c3c3dae1f9e1cb1869a50",
     evaluated_epoch: Epoch40,
     transactions: [
       ExpectedTransactionOutput(
@@ -86,7 +84,7 @@ snapshot_kind: text
     ),
   )),
   Success(ExpectedBlockOutput(
-    marf_hash: "0c0565210c0967c5b58775318b5f942c1e916b5ea814645ffc29b6ea01fcef47",
+    marf_hash: "db7415eaa975289668950b202d9a6160f8e6f94077aba49b2c5cb0c12508f851",
     evaluated_epoch: Epoch40,
     transactions: [
       ExpectedTransactionOutput(
@@ -116,7 +114,7 @@ snapshot_kind: text
     ),
   )),
   Success(ExpectedBlockOutput(
-    marf_hash: "fc6b30082e15893859ac7d27713c9da144c9021c7ef5019f5685c2849513b97b",
+    marf_hash: "ac9b94d79f0ed7a4806dc47191d9adeef9ca27b2df277e4381d17151c5dc3b16",
     evaluated_epoch: Epoch40,
     transactions: [
       ExpectedTransactionOutput(
@@ -146,7 +144,7 @@ snapshot_kind: text
     ),
   )),
   Success(ExpectedBlockOutput(
-    marf_hash: "4930824fd0b20fd53fe6459416c4b50a8431f0034c5e7e91cb907a29ceed52a2",
+    marf_hash: "dafd367ffe49a2fff9ff44943379581af0ab0f9100699af4154077eb209fab30",
     evaluated_epoch: Epoch40,
     transactions: [
       ExpectedTransactionOutput(
@@ -176,7 +174,7 @@ snapshot_kind: text
     ),
   )),
   Success(ExpectedBlockOutput(
-    marf_hash: "3298dfbaaa0e99f41329fe74ed732d87cc19a92110803e63c8998a1ac6ddbf16",
+    marf_hash: "004bedff0046a7d214bde0afe817287397de87ee37205378ea5c0f785e0446f2",
     evaluated_epoch: Epoch40,
     transactions: [
       ExpectedTransactionOutput(