WIP: PoX-5 and Epoch 4 by hstove-stacks · Pull Request #7197 · stacks-network/stacks-core

hstove-stacks · 2026-05-11T14:42:32Z

This is an in-progress PR for iterative development of pox-5 work

…e modules

* pipe through the outputs from burndb to sortdb * add validation routine for the L1 locking scripts * add validation for the PoX reward set, checking scripts for matching outputs

Also includes the linked list and other state for per-cycle signer set state.

Also moved the computation logic to a separate helper function, to help with unit testing.

The expected p2wsh script will instead now be computed in Clarity and then the new function to be added will verify that the output exists.

Also simplifies many matches to reduce the number of places that need to be touched each time an epoch or clarity version is added.

Merge feat/p2wsh validation

brice-stacks · 2026-05-13T17:16:34Z

+        ;; this is a list of outputs corresponding to their timelocks.
+        ;; If the response is `err`, this is the amount of sBTC (in sats)
+        ;; that they want to lock.
+        (btc-lockup (response {


I think this being a response is bad for UX. I'd rather see two optionals, btc-lockup and sbtc-lockup, with a check to ensure they are not both set.

brice-stacks · 2026-05-13T17:18:33Z

+        is-bond: bool,
+        index: uint,


It would be nice if the ordering of these keys is consistent across all of these maps, I think is-bond is first, then index is second makes the most sense.

brice-stacks · 2026-05-13T17:23:57Z

+        (ok {
+            unlock-burn-height: (reward-cycle-to-unlock-height unlock-cycle),
+            staker: tx-sender,
+            signer: signer,
+            prev-unlock-height: prev-unlock-cycle,
+            unlock-cycle: unlock-cycle,
+            num-cycles: num-cycles,
+            amount-ustx: new-lock-amount,
+        })


Again, field ordering in tuples is nice to be consistent when possible.

(ok { - unlock-burn-height: (reward-cycle-to-unlock-height unlock-cycle), - staker: tx-sender, signer: signer, + staker: tx-sender, + amount-ustx: new-lock-amount, + num-cycles: num-cycles, prev-unlock-height: prev-unlock-cycle, + unlock-burn-height: (reward-cycle-to-unlock-height unlock-cycle), unlock-cycle: unlock-cycle, - num-cycles: num-cycles, - amount-ustx: new-lock-amount, }) ) )

brice-stacks · 2026-05-13T17:39:33Z

+    )
+)
+
+(define-public (calculate-rewards (bond-periods (list 6 uint)))


It might be nice to have a read-only version of this that could be called any time to estimate rewards, and then call that from the actual one that checks the proper height and sets the persistent storage.

…ation

* Push PoX-5 activation far ahead in the snap/consensus tests: those are not ready for PoX-5 activation, and will require integration once signer-set calculation is in place. This is the bulk of the changeset (all the snap files are touched because this impacts the pox-4 auto-unlock heights) * Remove the force-activate test instruction for PoX-5 calculation * Compute the first-waterfall reward set with `PoxConstants` PoX-5 activation rather than Epoch-4.0 height * Fix the signer set fetch API so that it will return a pox-5 signer set

brice-stacks · 2026-05-14T17:56:39Z

+;; Keep these constants in lock-step with the address version buffs above
+;; Maximum value of an address version as a uint
+(define-constant MAX_ADDRESS_VERSION u6)
+;; Maximum value of an address version that has a 20-byte hashbytes
+;; (0x00, 0x01, 0x02, 0x03, and 0x04 have 20-byte hashbytes)
+(define-constant MAX_ADDRESS_VERSION_BUFF_20 u4)
+;; Maximum value of an address version that has a 32-byte hashbytes
+;; (0x05 and 0x06 have 32-byte hashbytes)
+(define-constant MAX_ADDRESS_VERSION_BUFF_32 u6)


These are unused and can be deleted.

brice-stacks · 2026-05-14T17:58:36Z

+
+;; Used to prevent fractional multiplication errors
+;; during reward calculations
+(define-constant PRECISION u1000000000000000000) ;; 1e18


It will be better performance for this to be a power of 2 (multiplies and divides become shifts).

brice-stacks · 2026-05-14T19:04:27Z

+        ;; The signer must have been registered already
+        (asserts! (is-some (get-signer-info signer)) ERR_SIGNER_NOT_FOUND)
+
+        ;; the start-burn-ht must result in the next reward cycle, do not allow stackers


Suggested change

;; the start-burn-ht must result in the next reward cycle, do not allow stackers

;; the start-burn-ht must result in the next reward cycle, do not allow stakers

brice-stacks · 2026-05-14T19:05:08Z

+        ;;;;  tx-sender principal must not be in a bond membership
+        (asserts! (is-none (get-bond-membership tx-sender)) ERR_ALREADY_STAKED)
+
+        ;;;;  the Stacker must have sufficient unlocked funds


Suggested change

;;;; the Stacker must have sufficient unlocked funds

;;;; the staker must have sufficient unlocked funds

Also, what's with the ;;;; for some comments?

brice-stacks · 2026-05-14T19:05:46Z

+    ))
+)
+
+;; Revoke contract-caller authorization to call stacking methods


Suggested change

;; Revoke contract-caller authorization to call stacking methods

;; Revoke contract-caller authorization to call staking methods

PoX-5: Integrate sbtc address calculation

brice-stacks · 2026-05-14T19:08:41Z

+;;  normally, stacking methods may only be invoked by _direct_ transactions
+;;   (i.e., the tx-sender issues a direct contract-call to the stacking methods)
+;;  by issuing an allowance, the tx-sender may call through the allowed contract
+(define-public (allow-contract-caller


Are we still going to consider the post-condition replacement for this? I think it would be nice. See discussion.

brice-stacks · 2026-05-14T19:19:05Z

+;; Give a contract-caller authorization to call stacking methods
+;;  normally, stacking methods may only be invoked by _direct_ transactions
+;;   (i.e., the tx-sender issues a direct contract-call to the stacking methods)


"stacking" -> "staking" x 3

brice-stacks · 2026-05-14T19:19:37Z

+        )
+
+        (match last-item
+            last-stacker (let ((last-node (unwrap-panic (map-get? staker-set-ll-for-cycle {


"last-staker"

brice-stacks · 2026-05-14T19:20:30Z

+)
+
+(define-private (remove-staker-from-set-for-cycle
+        (stacker principal)


brice-stacks · 2026-05-14T19:20:45Z

+            (next-item (get next node))
+        )
+        (match prev-item
+            prev-stacker


prev-staker

brice-stacks · 2026-05-14T19:27:24Z

+;; State for tracking used signer key authorizations. This prevents re-use
+;; of the same signature or pre-set authorization for multiple transactions.
+;; Refer to the `signer-key-authorizations` map for the documentation on these fields
+(define-map used-signer-key-authorizations
+    {
+        signer-key: (buff 33),
+        reward-cycle: uint,
+        period: uint,
+        topic: (string-ascii 14),
+        pox-addr: (optional {
+            version: (buff 1),
+            hashbytes: (buff 32),
+        }),
+        auth-id: uint,
+        max-amount: uint,
+    }
+    bool ;; Whether the field has been used or not
+)


We don't need this any more.

brice-stacks · 2026-05-14T19:54:04Z

+        index: uint,
+        is-bond: bool,
+        staker: principal,
+        signer: principal,


Is it necessary to include the signer in the key here? I think we're already guaranteed to only have one entry per index/is-bond/staker, and adding the signer is just complicating it.

brice-stacks · 2026-05-14T20:07:23Z

+                        index: cycle,
+                        signer: signer,
+                        is-bond: false,


Let's keep the ordering consistent.

brice-stacks · 2026-05-14T20:10:22Z

+;; This is strictly for reward calculations - ie the STX
+;; from Bitcoin staking are not accounted for here.


This comment could be more clear. Maybe something like:

This is strictly for reward calculations - i.e. when is-bond is false, only the STX from STX-only staking is accounted for here, not the STX from bonds.

brice-stacks · 2026-05-15T17:11:32Z

+;;;;  The last accounted balance (of sBTC held by this contract)
+;;;;  at a time of reward computation.
+;;;;  N.B. it is critical that this value is set to the contract's
+;;;;  sBTC balance after any transfer of sBTC out of this contract.
+;; (define-data-var last-accounted-balance uint u0)


I think this is just going to be another place for an error to crop up. Let's not track this, and just use sBTC's functions to figure out how much the contract holds.

brice-stacks · 2026-05-15T18:09:05Z

+            (available-rewards (get available-rewards accumulator))
+            ;; How much sBTC the bond is supposed to earn per calculation,
+            ;; which is (totalSats * apy) / 48
+            (target-yield (/ (/ (* total-sats (get target-rate bond)) u10000) u48))


If the target rate is an APY, and we are calculating the target yield for 1 pay cycle, I think we should be dividing by 50, not 48.

X = year / pay cycles 1 pay cycle = 1050 blocks 1 year = 365.25 days * 24 hours/day * 60 min/day = 525,960 min 1 block = 10 min 1 year = 52,596 blocks X = 52,596 blocks / 1050 blocks ~= 50

Or are we just assuming that two consecutive bonds is approximately 1 year, so there are ~48 pay periods in one year.

brice-stacks · 2026-05-15T19:07:11Z

+(define-constant ERR_CANNOT_SETUP_BOND_TOO_LATE (err u3))
+(define-constant ERR_BOND_ALREADY_SETUP (err u4))
+(define-constant ERR_STAKER_ALREADY_ADDED (err u5))
+(define-constant ERR_L1_LOCKUP_NOT_FOUND (err u6))


Several of these constants are never used.

hstove-stacks and others added 30 commits April 22, 2026 21:10

feat: update dependencies in core-contract-tests

3496f41

fix: compute heights correctly in name register tests

f4708b0

chore: update core-contract-tests deps

0b2f674

fix: support response types as args to functions

02f260e

feat: initial pox-waterfall-0 implementation

e56fc52

feat: initial work for tracking p2wsh outputs

1f9c918

chore: cargo fmt and clippy

7af39f1

test: add unit coverage for serializer

10c0ad2

rename watched_outputs to watched_p2wsh_outputs, consolidate hex serd…

ac3e521

…e modules

feat: validation of p2wsh outputs

5fb42ba

* pipe through the outputs from burndb to sortdb * add validation routine for the L1 locking scripts * add validation for the PoX reward set, checking scripts for matching outputs

fix: bug in prune_watched_outputs

7739d50

chore: minor improvements from review comments

9b97b6c

fix: merge conflict

10c7bee

feat: add bond members to reward cycles

75d0145

Also includes the linked list and other state for per-cycle signer set state.

feat: add staking-state, more validation to bond registration

280742f

feat: change stx-value-ratio to "ustx per 100 sats"

29d525f

Also moved the computation logic to a separate helper function, to help with unit testing.

fix: update sbtc addrs in clarigen-types.ts

be677e9

chore: delete all code for validating the lockups

74d7244

The expected p2wsh script will instead now be computed in Clarity and then the new function to be added will verify that the output exists.

feat: add pruning of sortdb watched outputs

83c419f

chore: cleanup more unused code and fix some nits

b0f7393

test: fix missing import

e781053

feat: setup epoch 3.5, which deploys pox-5, and Clarity 6

1722bd3

Also simplifies many matches to reduce the number of places that need to be touched each time an epoch or clarity version is added.

test: update cargo insta snapshots

11554f8

test: update large_contract to handle epoch 3.5

7417feb

refactor: convert another match

b164f29

refactor: remove exhaustive epoch match in supports_epoch

c74d74f

refactor: remove hard-coded epoch in test

505732d

Merge pull request #7168 from brice-stacks/merge-feat/p2wsh-validation

4a4841c

Merge feat/p2wsh validation

Merge branch 'pox-wf-integration' into feat/epoch-35-clarity-6

355529c

fix: rename contract to pox-5 from pox-wf

55dba45

aaronb-stacks added 2 commits May 13, 2026 10:20

chore: fix a comment

f249d21

reject block commits in unexpected scenario, clean-up if/else

f8694be

brice-stacks reviewed May 13, 2026

View reviewed changes

aaronb-stacks added 4 commits May 13, 2026 13:58

expand end-to-end sbtc testing stub, fix reward-cycle boundary calcul…

758c194

…ation

test: use common sbtc stub generation for nakamoto_integrations

849d2c5

support snapshots in epoch_4_0 tests, return 50K STX for ustx threshold

757722f

brice-stacks reviewed May 14, 2026

View reviewed changes

chore: update comment

c21cf70

brice-stacks reviewed May 14, 2026

View reviewed changes

Merge pull request #7192 from aaronb-stacks/feat/pox-wf-commits

1c7b8e6

PoX-5: Integrate sbtc address calculation

brice-stacks reviewed May 14, 2026

View reviewed changes

hstove-stacks mentioned this pull request May 15, 2026

[wip] epoch 4 release branch #7210

Open

brice-stacks reviewed May 15, 2026

View reviewed changes

	;; the start-burn-ht must result in the next reward cycle, do not allow stackers
	;; the start-burn-ht must result in the next reward cycle, do not allow stakers

	;;;; the Stacker must have sufficient unlocked funds
	;;;; the staker must have sufficient unlocked funds

	;; Revoke contract-caller authorization to call stacking methods
	;; Revoke contract-caller authorization to call staking methods

		;; This is strictly for reward calculations - ie the STX
		;; from Bitcoin staking are not accounted for here.

Conversation

hstove-stacks commented May 11, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

brice-stacks May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

brice-stacks May 14, 2026 •

edited

Loading