From df646acf253a2bd2bddbfb928b622698c98201d7 Mon Sep 17 00:00:00 2001 From: friedger Date: Tue, 1 Apr 2025 10:41:39 +0200 Subject: [PATCH 01/22] feat: add sip to remove cool down cycle --- sips/sip-x/sip-x-remove-cooldown-cycle.md | 100 ++++++++++++++++++++++ 1 file changed, 100 insertions(+) create mode 100644 sips/sip-x/sip-x-remove-cooldown-cycle.md diff --git a/sips/sip-x/sip-x-remove-cooldown-cycle.md b/sips/sip-x/sip-x-remove-cooldown-cycle.md new file mode 100644 index 000000000..678367ada --- /dev/null +++ b/sips/sip-x/sip-x-remove-cooldown-cycle.md @@ -0,0 +1,100 @@ +# Preamble + +**SIP Number:** XXX + +**Title:** Remove Cooldown Cycle for Stackers + +**Authors:** + +- Friedger Müffke ([friedger@ryder.id](mailto:friedger@ryder.id)) + +**Consideration:** Technical + +**Type:** Consensus + +**Status:** Draft + +**Created:** 2025-04-01 + +**License:** BSD 2-Clause + +**Sign-off:** + +**Discussions-To:** + +- [Stacks Forum Discussions](https://forum.stacks.org/t/remove-cool-down-cycle-in-stacking/17899) + +# Abstract + +This SIP proposes a change to the different phases of the stacking process so that stackers can change their stacking settings without the so-called cooldown cycle. + +The specification defines that + +- the beginning of the prepare phase is moved by 90 blocks towards the end of hte cycle +- the length of the prepare phase is reduced to 10 blocks and +- that locked Stacks token ready for unlocking are unlocked at 90 blocks before the beginning of the prepare phase. + +# Introduction + +## Glossary + +| Term | Definition | +| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Cooldown Cycle** | The period of 1 stacking cycle where stackers cannot stack their STX tokens because their tokens are unlocked only at the beginning of a stacking cycle. | + +## Problem Statement + +The current stacking process is defined by a prepare phase of 100 bitcoin blocks that is used to find an anchor block for the next stacking cycle. Stackers must lock their Stacks tokens before the preapre phase, i.e. before the 2000th blocks of the current stacking cycle. Furthermore, Stacks tokens are locked for a locking period that always end at the beginning of a cycle, i.e. after the prepare phase. Therefore, the current implementation of Stacking includes a period where Stacks tokens are unlocked and cannot earn stacking rewards (Cooldown Cycle). + +The cooldown cycle for unstacking from a pool presents a problem for network decentralization. As a stacker, when I delegate to a signer and that signer does not perform and gets low yield, I get penalized for switching. In today's model with cooldown cycles, users get double penalized if a validator does not perform. Even if there are penalties for signers not performing / being down, the switching costs are too high for users to switch (2 weeks worth of yield is a lot). + +## Proposed Solution + +The proposed solution defines the end of the locking period to be before the start of the stacking cycle. + +# Specification + +Applying these upgrades to the Stacks blockchain requires a consensus-breaking network upgrade, in this case, a hard fork. Like other such changes, this will require a new Stacks epoch. In this SIP, we will refer to this new epoch as Stacks 3.2. + +## Locking period + +Stacking transactions shall result in locking periods that end 100 blocks before the beginning of a stacking period. This includes + +- stack-stx +- stack-extend +- delegate-stack-stx +- delegate-stack-extend + +The PoX contract has to be changed and return the unlock height as previous unlock height minus 100 blocks for mainnet. E.g. + +``` +(new-unlock-ht (- (reward-cycle-to-burn-height (+ u1 last-extend-cycle)) u100)) +``` + +The unlocking process of the stacks node needs to be adapted accordingly. + +## Prepare phase + +The prepare phase shall start 10 blocks before the beginning of the stacking cycle and last for 10 blocks. + +The prepare cycle length defined in PoX contract has be changed to + +``` +(define-constant PREPARE_CYCLE_LENGTH (if is-in-mainnet u10 u5)) +``` + +## Transition to PoX-5 + +A new PoX contract requires that all stacked Stacks tokens are unlocked and Stackers need to lock their Stacks token again using the new PoX-5 contract. The process shall be similar to the previous upgrades of the PoX contract. PoX-4 contract shall be deactivated and PoX-5 contract shall be activated at the beginning of epoch 3.2 All locked Stacks tokens shall be unlocked automatically 1 block after the beginning of epoch 3.2. + +# Related Work + +The previous PoX process is described in SIP 007 + +# Activation + +This SIP requires are hard for and shall be activated on Stacks 3.2 as defined by the SIP for epoch 3.2. + +## Appendix + +[1] https://github.com/stacks-network/stacks-core/issues/4912 From 7015353a204030b530716fa83555dde68367724a Mon Sep 17 00:00:00 2001 From: friedger Date: Fri, 4 Apr 2025 10:53:21 +0200 Subject: [PATCH 02/22] chore: remove solo stacking --- sips/sip-x/sip-x-improved-stacking.md | 148 ++++++++++++++++++++++ sips/sip-x/sip-x-remove-cooldown-cycle.md | 100 --------------- 2 files changed, 148 insertions(+), 100 deletions(-) create mode 100644 sips/sip-x/sip-x-improved-stacking.md delete mode 100644 sips/sip-x/sip-x-remove-cooldown-cycle.md diff --git a/sips/sip-x/sip-x-improved-stacking.md b/sips/sip-x/sip-x-improved-stacking.md new file mode 100644 index 000000000..9fb1ad4c5 --- /dev/null +++ b/sips/sip-x/sip-x-improved-stacking.md @@ -0,0 +1,148 @@ +# Preamble + +**SIP Number:** XXX + +**Title:** Improved Stacking Protocol + +**Authors:** + +- Friedger Müffke ([friedger@ryder.id](mailto:friedger@ryder.id)) + +**Consideration:** Technical + +**Type:** Consensus + +**Status:** Draft + +**Created:** 2025-04-01 + +**License:** BSD 2-Clause + +**Sign-off:** + +**Discussions-To:** + +- [Stacks Forum Discussions](https://forum.stacks.org/t/remove-cool-down-cycle-in-stacking/17899) + +# Abstract + +This SIP proposes a change to the different phases of the stacking process so that stackers can change +their stacking settings without the so-called cooldown cycle. Furthermore, the relationship between stackers +and signers is strengthened and stacking overall is simplified. + +The specification defines that + +- the beginning of the prepare phase is moved by 90 blocks towards the end of hte cycle. +- the length of the prepare phase is reduced to 10 blocks. +- that locked Stacks token ready for unlocking are unlocked at 90 blocks before the beginning of the prepare phase. +- that delegated stacking tokens are locked immediately. +- that stacking rewards are received by the Bitcoin address specified by the signer. +- that solo stackers and delegating stackers have to follow the same flow. + +# Introduction + +## Glossary + +| Term | Definition | +| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Cooldown Cycle** | The period of 1 stacking cycle where stackers cannot stack their STX tokens because their tokens are unlocked only at the beginning of a stacking cycle. | +| **Signer** | | +| **Delegation** | | +| **PoX Contract** | | + +## Problem Statement + +The current stacking process is has two different paths, one for solo stackers, one for delegated stackers, +resulting in a more complex users experience and complex code. Furthermore, users cannot change their +stacking settings (decrease amount, change PoX address, etc.) without an unlocked cycle where users cannot earn +stacking rewards. + +The process is defined by a prepare phase of 100 bitcoin blocks that is used to find an anchor block +for the next stacking cycle. Stackers must lock +their Stacks tokens before the +preapre phase, i.e. before the 2000th blocks of the current stacking cycle. Furthermore, Stacks +tokens are locked for a locking period that always end at the beginning of a cycle, i.e. after the +prepare phase. Therefore, the current implementation of Stacking includes a period where Stacks +tokens are unlocked and cannot earn stacking rewards (Cooldown Cycle). + +The current PoX contract allows users to lock Stacks tokens during the prepare phase. This is too late for the next cycle +and the tokens are locked without earning stacking rewards for one cycle. + +The cooldown cycle for unstacking from a pool presents a problem for network decentralization. +As a stacker, when I delegate to a signer and that signer does not perform and gets low yield, +I get penalized for switching. In today's model with cooldown cycles, users get double penalized +if a validator does not perform. Even if there are penalties for signers not performing / being down, +the switching costs are too high for users to switch (2 weeks worth of yield is a lot). + +## Proposed Solution + +A new PoX contract is proposed without +the flow for solo stacking and moves responsibilities from pool operators to signers. It also +defines the end of the locking period to be before the start of the stacking cycle. + +The user will be able to switch from one signer to another with a single contract call and without a cool down period. + +# Specification + +Applying these upgrades to the Stacks blockchain requires a consensus-breaking network upgrade, +in this case, a hard fork. Like other such changes, this will require a new Stacks epoch. +In this SIP, we will refer to this new epoch as Stacks 3.2. + +## Delegated Stacking only + +The following PoX contract functions shall be removed + +- stack-stx +- stack-increase +- stack-extend + +## Locking period + +Stacking transactions shall result in locking periods that end 100 blocks before the beginning of a stacking period. This includes + +- delegate-stack-stx +- delegate-stack-extend + +The PoX contract has to be changed and return the unlock height as previous unlock height minus 100 blocks for mainnet. E.g. + +``` +(new-unlock-ht (- (reward-cycle-to-burn-height (+ u1 last-extend-cycle)) u100)) +``` + +The unlocking process of the stacks node needs to be adapted accordingly. + +## Prepare phase + +The prepare phase shall start 10 blocks before the beginning of the stacking cycle and last for 10 blocks. + +The prepare cycle length defined in PoX contract has be changed to + +``` +(define-constant PREPARE_CYCLE_LENGTH (if is-in-mainnet u10 u5)) +``` + +## Relationship Between Stackers and Signers + +The signature provided by a signers to a stackers shall use one of the following topics + +- delegate +- delegate-increase +- delegate-extend +- agg-commit +- agg-increase + +## Transition to PoX-5 + +A new PoX contract requires that all stacked Stacks tokens are unlocked and Stackers need to lock their Stacks token again using the new PoX-5 contract. The process shall be similar to the previous upgrades of the PoX contract. PoX-4 contract shall be deactivated and PoX-5 contract shall be activated at the beginning of epoch 3.2 All locked Stacks tokens shall be unlocked automatically 1 block after the beginning of epoch 3.2. + +# Related Work + +The previous PoX process is described in [SIP 007](https://github.com/stacksgov/sips/blob/main/sips/sip-007/sip-007-stacking-consensus.md). + +# Activation + +This SIP requires are hard fork and shall be activated on Stacks 3.2 as defined by the SIP for epoch 3.2. + +## Appendix + +[1] https://github.com/stacks-network/stacks-core/issues/4912 diff --git a/sips/sip-x/sip-x-remove-cooldown-cycle.md b/sips/sip-x/sip-x-remove-cooldown-cycle.md deleted file mode 100644 index 678367ada..000000000 --- a/sips/sip-x/sip-x-remove-cooldown-cycle.md +++ /dev/null @@ -1,100 +0,0 @@ -# Preamble - -**SIP Number:** XXX - -**Title:** Remove Cooldown Cycle for Stackers - -**Authors:** - -- Friedger Müffke ([friedger@ryder.id](mailto:friedger@ryder.id)) - -**Consideration:** Technical - -**Type:** Consensus - -**Status:** Draft - -**Created:** 2025-04-01 - -**License:** BSD 2-Clause - -**Sign-off:** - -**Discussions-To:** - -- [Stacks Forum Discussions](https://forum.stacks.org/t/remove-cool-down-cycle-in-stacking/17899) - -# Abstract - -This SIP proposes a change to the different phases of the stacking process so that stackers can change their stacking settings without the so-called cooldown cycle. - -The specification defines that - -- the beginning of the prepare phase is moved by 90 blocks towards the end of hte cycle -- the length of the prepare phase is reduced to 10 blocks and -- that locked Stacks token ready for unlocking are unlocked at 90 blocks before the beginning of the prepare phase. - -# Introduction - -## Glossary - -| Term | Definition | -| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Cooldown Cycle** | The period of 1 stacking cycle where stackers cannot stack their STX tokens because their tokens are unlocked only at the beginning of a stacking cycle. | - -## Problem Statement - -The current stacking process is defined by a prepare phase of 100 bitcoin blocks that is used to find an anchor block for the next stacking cycle. Stackers must lock their Stacks tokens before the preapre phase, i.e. before the 2000th blocks of the current stacking cycle. Furthermore, Stacks tokens are locked for a locking period that always end at the beginning of a cycle, i.e. after the prepare phase. Therefore, the current implementation of Stacking includes a period where Stacks tokens are unlocked and cannot earn stacking rewards (Cooldown Cycle). - -The cooldown cycle for unstacking from a pool presents a problem for network decentralization. As a stacker, when I delegate to a signer and that signer does not perform and gets low yield, I get penalized for switching. In today's model with cooldown cycles, users get double penalized if a validator does not perform. Even if there are penalties for signers not performing / being down, the switching costs are too high for users to switch (2 weeks worth of yield is a lot). - -## Proposed Solution - -The proposed solution defines the end of the locking period to be before the start of the stacking cycle. - -# Specification - -Applying these upgrades to the Stacks blockchain requires a consensus-breaking network upgrade, in this case, a hard fork. Like other such changes, this will require a new Stacks epoch. In this SIP, we will refer to this new epoch as Stacks 3.2. - -## Locking period - -Stacking transactions shall result in locking periods that end 100 blocks before the beginning of a stacking period. This includes - -- stack-stx -- stack-extend -- delegate-stack-stx -- delegate-stack-extend - -The PoX contract has to be changed and return the unlock height as previous unlock height minus 100 blocks for mainnet. E.g. - -``` -(new-unlock-ht (- (reward-cycle-to-burn-height (+ u1 last-extend-cycle)) u100)) -``` - -The unlocking process of the stacks node needs to be adapted accordingly. - -## Prepare phase - -The prepare phase shall start 10 blocks before the beginning of the stacking cycle and last for 10 blocks. - -The prepare cycle length defined in PoX contract has be changed to - -``` -(define-constant PREPARE_CYCLE_LENGTH (if is-in-mainnet u10 u5)) -``` - -## Transition to PoX-5 - -A new PoX contract requires that all stacked Stacks tokens are unlocked and Stackers need to lock their Stacks token again using the new PoX-5 contract. The process shall be similar to the previous upgrades of the PoX contract. PoX-4 contract shall be deactivated and PoX-5 contract shall be activated at the beginning of epoch 3.2 All locked Stacks tokens shall be unlocked automatically 1 block after the beginning of epoch 3.2. - -# Related Work - -The previous PoX process is described in SIP 007 - -# Activation - -This SIP requires are hard for and shall be activated on Stacks 3.2 as defined by the SIP for epoch 3.2. - -## Appendix - -[1] https://github.com/stacks-network/stacks-core/issues/4912 From 7546e846c936c66bc5cf980f32c0281778a40a87 Mon Sep 17 00:00:00 2001 From: friedger Date: Tue, 8 Apr 2025 21:44:19 +0200 Subject: [PATCH 03/22] fix: tpyes, corrections --- sips/sip-x/sip-x-improved-stacking.md | 28 +++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/sips/sip-x/sip-x-improved-stacking.md b/sips/sip-x/sip-x-improved-stacking.md index 9fb1ad4c5..9f926dd64 100644 --- a/sips/sip-x/sip-x-improved-stacking.md +++ b/sips/sip-x/sip-x-improved-stacking.md @@ -32,12 +32,12 @@ and signers is strengthened and stacking overall is simplified. The specification defines that -- the beginning of the prepare phase is moved by 90 blocks towards the end of hte cycle. -- the length of the prepare phase is reduced to 10 blocks. -- that locked Stacks token ready for unlocking are unlocked at 90 blocks before the beginning of the prepare phase. -- that delegated stacking tokens are locked immediately. -- that stacking rewards are received by the Bitcoin address specified by the signer. -- that solo stackers and delegating stackers have to follow the same flow. +- the beginning of the prepare phase is moved by 90 Bitcoin blocks towards the end of the cycle. +- the length of the prepare phase is reduced to 10 Bitcoin blocks. +- locked Stacks token ready for unlocking are unlocked at 90 blocks before the beginning of the prepare phase. +- delegated stacking tokens are locked immediately. +- stacking rewards are received by the Bitcoin address specified by the signer. +- solo stackers and delegating stackers have to follow the same flow. # Introduction @@ -52,15 +52,15 @@ The specification defines that ## Problem Statement -The current stacking process is has two different paths, one for solo stackers, one for delegated stackers, -resulting in a more complex users experience and complex code. Furthermore, users cannot change their -stacking settings (decrease amount, change PoX address, etc.) without an unlocked cycle where users cannot earn +The current stacking process has two different paths, one for solo stackers, one for delegated stackers, +resulting in a more complex user experience and more complex code. Furthermore, users cannot change their +stacking settings (decrease amount, change PoX reward address, etc.) without an unlocked cycle where users cannot earn stacking rewards. The process is defined by a prepare phase of 100 bitcoin blocks that is used to find an anchor block for the next stacking cycle. Stackers must lock their Stacks tokens before the -preapre phase, i.e. before the 2000th blocks of the current stacking cycle. Furthermore, Stacks +preapre phase, i.e. before the 2000th block of the current stacking cycle. Furthermore, Stacks tokens are locked for a locking period that always end at the beginning of a cycle, i.e. after the prepare phase. Therefore, the current implementation of Stacking includes a period where Stacks tokens are unlocked and cannot earn stacking rewards (Cooldown Cycle). @@ -72,11 +72,11 @@ The cooldown cycle for unstacking from a pool presents a problem for network dec As a stacker, when I delegate to a signer and that signer does not perform and gets low yield, I get penalized for switching. In today's model with cooldown cycles, users get double penalized if a validator does not perform. Even if there are penalties for signers not performing / being down, -the switching costs are too high for users to switch (2 weeks worth of yield is a lot). +the switching costs are too high for users to switch (2 weeks worth of yield). ## Proposed Solution -A new PoX contract is proposed without +This SIP proposes a new Proof of Transfer (PoX) contract without the flow for solo stacking and moves responsibilities from pool operators to signers. It also defines the end of the locking period to be before the start of the stacking cycle. @@ -123,7 +123,7 @@ The prepare cycle length defined in PoX contract has be changed to ## Relationship Between Stackers and Signers -The signature provided by a signers to a stackers shall use one of the following topics +The signature provided by signers to stackers shall use one of the following topics - delegate - delegate-increase @@ -141,7 +141,7 @@ The previous PoX process is described in [SIP 007](https://github.com/stacksgov/ # Activation -This SIP requires are hard fork and shall be activated on Stacks 3.2 as defined by the SIP for epoch 3.2. +This SIP requires a hard fork and shall be activated on Stacks 3.2 as defined by the SIP for epoch 3.2. ## Appendix From 440532491fcc4cdb092276a2c190327229f90d36 Mon Sep 17 00:00:00 2001 From: friedger Date: Sun, 15 Jun 2025 00:30:11 +0200 Subject: [PATCH 04/22] feat: update sip to auto extend --- sips/sip-x/sip-x-improved-stacking.md | 110 ++++++++++++++++++-------- 1 file changed, 76 insertions(+), 34 deletions(-) diff --git a/sips/sip-x/sip-x-improved-stacking.md b/sips/sip-x/sip-x-improved-stacking.md index 9f926dd64..d43a3cc63 100644 --- a/sips/sip-x/sip-x-improved-stacking.md +++ b/sips/sip-x/sip-x-improved-stacking.md @@ -26,36 +26,45 @@ # Abstract -This SIP proposes a change to the different phases of the stacking process so that stackers can change -their stacking settings without the so-called cooldown cycle. Furthermore, the relationship between stackers +This SIP proposes a change to stacking process so that stackers can change their stacking settings without the so-called cooldown cycle. Furthermore, the relationship between stackers and signers is strengthened and stacking overall is simplified. The specification defines that -- the beginning of the prepare phase is moved by 90 Bitcoin blocks towards the end of the cycle. -- the length of the prepare phase is reduced to 10 Bitcoin blocks. -- locked Stacks token ready for unlocking are unlocked at 90 blocks before the beginning of the prepare phase. +- solo stackers and delegating stackers have to follow the same flow and use the same contract functions: All delegate block voting power to signers. +- stackers can change their stacking settings for the next cycle before the prepare phase, including the chosen signer (switch pools). +- locked Stacks token are locked for 1 cycle at the time and that the locking period is extended by another cycle if the user does not request to unlock token. - delegated stacking tokens are locked immediately. - stacking rewards are received by the Bitcoin address specified by the signer. -- solo stackers and delegating stackers have to follow the same flow. +- locking Stacks tokens is protected by a new type of post conditions, enabling stacking through a contract in a single transactions. # Introduction +## Current Situation + +Currently, the stacking protocol has a few aspects that makes using and integration stacking harder than it could be: + +- There are two groups of stackers: solo stackers and delegated stackers. They use different sets of PoX contract functions + +- When using a contract for stacking, the contract needs to added as an allowed pox contract. This requires a separate transaction. + +- Solo stackers do all transactions with their cold wallet holding the whole stx balance. They need to make a transaction at least once every 12 cycles (6 months). In contrast, delegated stackers need to do only a single transaction with their wallet for the entire stacking. + +- Signers make off-chain agreements with pool operators about revenue sharing. + ## Glossary | Term | Definition | | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Cooldown Cycle** | The period of 1 stacking cycle where stackers cannot stack their STX tokens because their tokens are unlocked only at the beginning of a stacking cycle. | -| **Signer** | | -| **Delegation** | | -| **PoX Contract** | | +| **Signer** | The node operators that verify and confirm proposed blocks by miners. | +| **Delegation** | Current meaning: delegating the management of stacking. New meaning: delegating the voting power for proposed blocks. | +| **PoX Contract** | The smart contract that users interact with to lock their tokens. | ## Problem Statement The current stacking process has two different paths, one for solo stackers, one for delegated stackers, -resulting in a more complex user experience and more complex code. Furthermore, users cannot change their -stacking settings (decrease amount, change PoX reward address, etc.) without an unlocked cycle where users cannot earn -stacking rewards. +resulting in a more complex user experience and more complex code. The process is defined by a prepare phase of 100 bitcoin blocks that is used to find an anchor block for the next stacking cycle. Stackers must lock @@ -74,13 +83,15 @@ I get penalized for switching. In today's model with cooldown cycles, users get if a validator does not perform. Even if there are penalties for signers not performing / being down, the switching costs are too high for users to switch (2 weeks worth of yield). +Furthermore, users cannot change their +stacking settings (decrease amount, change PoX reward address, etc.) without an unlocked cycle where users cannot earn +stacking rewards. + ## Proposed Solution This SIP proposes a new Proof of Transfer (PoX) contract without the flow for solo stacking and moves responsibilities from pool operators to signers. It also -defines the end of the locking period to be before the start of the stacking cycle. - -The user will be able to switch from one signer to another with a single contract call and without a cool down period. +defines a new locking mechanism that allows users to switch from one signer to another with a single contract call and without a cool down period. # Specification @@ -96,45 +107,76 @@ The following PoX contract functions shall be removed - stack-increase - stack-extend -## Locking period +## Locking Post Conditions + +The following type of post conditions are added to the current definition in SIP-005 (`TransactionPostCondition`) + +- `LockingLimnit(PostConditionPrincipal, FungibleConditionCode, u64)` + +A transaction (using Deny mode) with this post condition will abort if the locked Stacks tokens of the principal does not satisfy the provided conditions. The logic follows the conditions of STX transfer. -Stacking transactions shall result in locking periods that end 100 blocks before the beginning of a stacking period. This includes +## Automatic Extend and Locking period -- delegate-stack-stx -- delegate-stack-extend +The following function shall be removed -The PoX contract has to be changed and return the unlock height as previous unlock height minus 100 blocks for mainnet. E.g. +- `delegate-stack-extend` -``` -(new-unlock-ht (- (reward-cycle-to-burn-height (+ u1 last-extend-cycle)) u100)) -``` +In addition, the stacking settings for each stacker (user with delegation) shall be applied for the next stacking cycle if the user did not signal end of stacking by calling `revoke-delegate-stx` 200 blocks before the start of the next cycle. -The unlocking process of the stacks node needs to be adapted accordingly. +This results in the following structure of the stacking cycle: -## Prepare phase +- bitcoin block 1-1900: stacking as usual, user can signal change of stacking settings. +- bitcoin block 1901-2000: stacking as usual, signers can still aggregate stacking changes. +- bitcoin block 2001-2100 (prepare phase): no rewards for stackers, changes to stacking are applied to the cycle after next. -The prepare phase shall start 10 blocks before the beginning of the stacking cycle and last for 10 blocks. +That means the locking period is 1 cycle with automatic extend for another cycle until the user decided to end stacking. -The prepare cycle length defined in PoX contract has be changed to +## Semantic Change of Delegation -``` -(define-constant PREPARE_CYCLE_LENGTH (if is-in-mainnet u10 u5)) -``` +When signers verify and accept proposed blocks by miners, their voting power corresponds to the amount of stacked Stacks tokens (see SIP-021). The new stacking process shall change the delegation flow as follows: -## Relationship Between Stackers and Signers +- `delegate-stx` shall be renamed to `delegate`. The function takes the arguments: amount, delegate-to, signature, optional bitcoin block height defining the end of stacking and auto extending, optional max-amount. The amount defines how many Stacks tokens are locked immediately. The max-amount the maximum of Stacks tokens that can be locked in the future. delegate-to describes the signer. Signature is a signature of the signer indicating that the signer accepted to delegation of voting power. -The signature provided by signers to stackers shall use one of the following topics +- `revoke-delegate-stx` shall be renamed to `revoke-delegate`. After calling this functions auto extend is stopped and Stacks tokens are unlocked for the user at the end of the current cycle. + +- `delegate-increase` is replaced by `delegate`. Users can just call delegate with a higher amount. + +- `delegate-extend` is removed because the locking period is extended automatically each cycle. + +## Aggregation Commit and PoX Reward Address + +Signers provide a PoX reward address during the aggregation commit call. This bitcoin address shall be used to receive stacking rewards. + +There is no chance in the registration of PoX reward addresses. In particular, there can be more than one PoX reward address per signer and Stacks tokens part of a PoX reward address that aggregated less than the minimum required for at least 1 reward slot are NOT unlocked. + +## Relation between Stackers and Signers + +The signatures provided by signers to stackers shall use one of the following topics - delegate -- delegate-increase -- delegate-extend - agg-commit - agg-increase +The other topics are not used anymore. + ## Transition to PoX-5 A new PoX contract requires that all stacked Stacks tokens are unlocked and Stackers need to lock their Stacks token again using the new PoX-5 contract. The process shall be similar to the previous upgrades of the PoX contract. PoX-4 contract shall be deactivated and PoX-5 contract shall be activated at the beginning of epoch 3.2 All locked Stacks tokens shall be unlocked automatically 1 block after the beginning of epoch 3.2. +## Registration of Signers + +Signers handle three private keys: + +1. one for signing blocks and delegation approval; +2. one for PoX reward address and reward distribution; +3. one for aggregation on the Stacks blockchain. + +The Stacks address of the first key is used by Stacks holders during delegation for `delegate-to`. + +The encoded bitcoin address of the second key and the Stacks address of the third key are announced in a registration contract call. The new function of the PoX contract is named `signer-register` and just takes the encoded bitcoin address, and the stacks address as parameters. + +Note, for solo stackers these three keys can be just a single key. For more complex setup, the keys can be handles by different independant entities. Also, the PoX reward address can be a deposit address for sBTC. + # Related Work The previous PoX process is described in [SIP 007](https://github.com/stacksgov/sips/blob/main/sips/sip-007/sip-007-stacking-consensus.md). From cbca81fbb2e1edceb11476b4ce4b57099c96d052 Mon Sep 17 00:00:00 2001 From: friedger Date: Sun, 15 Jun 2025 10:10:35 +0200 Subject: [PATCH 05/22] fix typos and grammar --- sips/sip-x/sip-x-improved-stacking.md | 96 +++++++++++++++------------ 1 file changed, 55 insertions(+), 41 deletions(-) diff --git a/sips/sip-x/sip-x-improved-stacking.md b/sips/sip-x/sip-x-improved-stacking.md index d43a3cc63..8359e163e 100644 --- a/sips/sip-x/sip-x-improved-stacking.md +++ b/sips/sip-x/sip-x-improved-stacking.md @@ -26,40 +26,41 @@ # Abstract -This SIP proposes a change to stacking process so that stackers can change their stacking settings without the so-called cooldown cycle. Furthermore, the relationship between stackers +This SIP proposes a change to the stacking process so that stackers can change their stacking settings without the so-called cooldown cycle. Furthermore, the relationship between stackers and signers is strengthened and stacking overall is simplified. The specification defines that -- solo stackers and delegating stackers have to follow the same flow and use the same contract functions: All delegate block voting power to signers. +- solo stackers and delegating stackers have to follow the same flow and use the same contract functions: All users delegate block voting power to signers. - stackers can change their stacking settings for the next cycle before the prepare phase, including the chosen signer (switch pools). -- locked Stacks token are locked for 1 cycle at the time and that the locking period is extended by another cycle if the user does not request to unlock token. +- locked Stacks token are locked for 1 cycle at a time and that the locking period is extended by another cycle if the user does not request to unlock tokens. - delegated stacking tokens are locked immediately. - stacking rewards are received by the Bitcoin address specified by the signer. -- locking Stacks tokens is protected by a new type of post conditions, enabling stacking through a contract in a single transactions. +- locking Stacks tokens is protected by a new type of post conditions, enabling stacking through a contract in a single transaction. # Introduction ## Current Situation -Currently, the stacking protocol has a few aspects that makes using and integration stacking harder than it could be: +Currently, the stacking protocol has a few aspects that make using and integration stacking harder than it could be: -- There are two groups of stackers: solo stackers and delegated stackers. They use different sets of PoX contract functions +- There are two groups of stackers: solo stackers and delegated stackers. They use different sets of PoX contract functions. -- When using a contract for stacking, the contract needs to added as an allowed pox contract. This requires a separate transaction. +- When using a contract for stacking, the contract needs to be added as an allowed pox contract. This requires a separate transaction. -- Solo stackers do all transactions with their cold wallet holding the whole stx balance. They need to make a transaction at least once every 12 cycles (6 months). In contrast, delegated stackers need to do only a single transaction with their wallet for the entire stacking. +- Solo stackers do all transactions with their cold wallet holding the whole STX balance. They need to make a transaction at least once every 12 cycles (6 months). In contrast, delegated stackers need to do only a single transaction with their wallet for the entire stacking. -- Signers make off-chain agreements with pool operators about revenue sharing. +- Signers make off-chain agreements with pool operators regarding revenue sharing. ## Glossary -| Term | Definition | -| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Cooldown Cycle** | The period of 1 stacking cycle where stackers cannot stack their STX tokens because their tokens are unlocked only at the beginning of a stacking cycle. | -| **Signer** | The node operators that verify and confirm proposed blocks by miners. | -| **Delegation** | Current meaning: delegating the management of stacking. New meaning: delegating the voting power for proposed blocks. | -| **PoX Contract** | The smart contract that users interact with to lock their tokens. | +| Term | Definition | +| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Cooldown Cycle** | The period of 1 stacking cycle where stackers cannot stack their STX tokens because their tokens are unlocked only at the beginning of a stacking cycle. | +| **Signer** | The node operators that verify and confirm proposed blocks by miners. | +| **Delegation (old)** | delegating the management of stacking. | +| **Delegation (new)** | delegating the voting power for proposed blocks. | +| **PoX Contract** | The smart contract that users interact with to lock their tokens. | ## Problem Statement @@ -69,8 +70,8 @@ resulting in a more complex user experience and more complex code. The process is defined by a prepare phase of 100 bitcoin blocks that is used to find an anchor block for the next stacking cycle. Stackers must lock their Stacks tokens before the -preapre phase, i.e. before the 2000th block of the current stacking cycle. Furthermore, Stacks -tokens are locked for a locking period that always end at the beginning of a cycle, i.e. after the +prepare phase, i.e. before the 2000th block of the current stacking cycle. Furthermore, Stacks +tokens are locked for a locking period that always ends at the beginning of a cycle, i.e. after the prepare phase. Therefore, the current implementation of Stacking includes a period where Stacks tokens are unlocked and cannot earn stacking rewards (Cooldown Cycle). @@ -80,17 +81,17 @@ and the tokens are locked without earning stacking rewards for one cycle. The cooldown cycle for unstacking from a pool presents a problem for network decentralization. As a stacker, when I delegate to a signer and that signer does not perform and gets low yield, I get penalized for switching. In today's model with cooldown cycles, users get double penalized -if a validator does not perform. Even if there are penalties for signers not performing / being down, -the switching costs are too high for users to switch (2 weeks worth of yield). +if a signer does not perform. Even if there are penalties for signers not performing / being down, +the switching costs are too high for users to switch (two weeks' worth of yield). Furthermore, users cannot change their -stacking settings (decrease amount, change PoX reward address, etc.) without an unlocked cycle where users cannot earn +stacking settings (decrease amount, change PoX reward address, etc.) without an unlocked cycle during which users cannot earn stacking rewards. ## Proposed Solution This SIP proposes a new Proof of Transfer (PoX) contract without -the flow for solo stacking and moves responsibilities from pool operators to signers. It also +the flow for solo stacking and moves responsibilities from pool operators to signers who were introduced in the Nakamot upgrade. It also defines a new locking mechanism that allows users to switch from one signer to another with a single contract call and without a cool down period. # Specification @@ -101,7 +102,7 @@ In this SIP, we will refer to this new epoch as Stacks 3.2. ## Delegated Stacking only -The following PoX contract functions shall be removed +The following PoX contract functions shall be removed: - stack-stx - stack-increase @@ -109,19 +110,19 @@ The following PoX contract functions shall be removed ## Locking Post Conditions -The following type of post conditions are added to the current definition in SIP-005 (`TransactionPostCondition`) +The following type of post conditions shall be added to the current definition in SIP-005 (`TransactionPostCondition`) -- `LockingLimnit(PostConditionPrincipal, FungibleConditionCode, u64)` +- `LockingLimit(PostConditionPrincipal, FungibleConditionCode, u64)` -A transaction (using Deny mode) with this post condition will abort if the locked Stacks tokens of the principal does not satisfy the provided conditions. The logic follows the conditions of STX transfer. +A transaction (using Deny mode) with this post condition will abort if the locked Stacks tokens of the principal does not satisfy the provided conditions. The logic for the conditions follows that of STX transfer. ## Automatic Extend and Locking period -The following function shall be removed +The following function shall be removed: - `delegate-stack-extend` -In addition, the stacking settings for each stacker (user with delegation) shall be applied for the next stacking cycle if the user did not signal end of stacking by calling `revoke-delegate-stx` 200 blocks before the start of the next cycle. +In addition, the stacking settings for each stacker (user with delegation) shall be applied for the next stacking cycle if the user did not signal the end of stacking by calling `revoke-delegate-stx` 200 blocks before the start of the next cycle. This results in the following structure of the stacking cycle: @@ -129,25 +130,38 @@ This results in the following structure of the stacking cycle: - bitcoin block 1901-2000: stacking as usual, signers can still aggregate stacking changes. - bitcoin block 2001-2100 (prepare phase): no rewards for stackers, changes to stacking are applied to the cycle after next. -That means the locking period is 1 cycle with automatic extend for another cycle until the user decided to end stacking. +```mermaid +gantt + title Stacking Cycle Structure + dateFormat x + axisFormat %s + section Stacking Cycle + Stacking as usual, user can signal change of stacking settings :active, a1, 1, 1900 + Stacking as usual, signers can still aggregate stacking changes :a2, 1901, 100 + Prepare phase, no rewards, changes applied to cycle after next :a3, 2001, 100 +``` + +That means the locking period is 1 cycle, with automatic extension for another cycle until the user decides to end stacking. ## Semantic Change of Delegation -When signers verify and accept proposed blocks by miners, their voting power corresponds to the amount of stacked Stacks tokens (see SIP-021). The new stacking process shall change the delegation flow as follows: +When signers verify and accept proposed blocks by miners, their voting power corresponds to the amount of stacked Stacks tokens (see SIP-021). The new stacking process changes the delegation flow as follows: -- `delegate-stx` shall be renamed to `delegate`. The function takes the arguments: amount, delegate-to, signature, optional bitcoin block height defining the end of stacking and auto extending, optional max-amount. The amount defines how many Stacks tokens are locked immediately. The max-amount the maximum of Stacks tokens that can be locked in the future. delegate-to describes the signer. Signature is a signature of the signer indicating that the signer accepted to delegation of voting power. +- `delegate-stx` shall be renamed to `delegate`. The function takes the arguments: `amount`, `delegate-to`, `signature`, optional bitcoin `block-height` defining the end of stacking and auto extending, optional `max-amount`. The `amount` defines how many Stacks tokens are locked immediately. The `max-amount` the maximum of Stacks tokens that can be locked in the future through auto extending. If omitted the whole balance is locked. The argument `delegate-to` describes the signer. The argument `signature` is a signature of the signer indicating that the signer accepted the delegation of voting power. -- `revoke-delegate-stx` shall be renamed to `revoke-delegate`. After calling this functions auto extend is stopped and Stacks tokens are unlocked for the user at the end of the current cycle. +- `revoke-delegate-stx` shall be renamed to `revoke-delegate`. After calling this functions, auto extension is stopped and Stacks tokens are unlocked for the user at the end of the current cycle. -- `delegate-increase` is replaced by `delegate`. Users can just call delegate with a higher amount. +- `delegate-increase` is replaced by `delegate`. Users can simply call delegate with a higher amount. -- `delegate-extend` is removed because the locking period is extended automatically each cycle. +- `delegate-extend` is removed because the locking period is automatically extended each cycle. ## Aggregation Commit and PoX Reward Address Signers provide a PoX reward address during the aggregation commit call. This bitcoin address shall be used to receive stacking rewards. -There is no chance in the registration of PoX reward addresses. In particular, there can be more than one PoX reward address per signer and Stacks tokens part of a PoX reward address that aggregated less than the minimum required for at least 1 reward slot are NOT unlocked. +There is no change in the registration of PoX reward addresses. In particular, there can be more than one PoX reward address per signer. + +Stacks tokens that are part of a PoX reward address that aggregated less than the minimum required for at least one reward slot shall be unlocked at the beginning of the cycle. ## Relation between Stackers and Signers @@ -157,11 +171,7 @@ The signatures provided by signers to stackers shall use one of the following to - agg-commit - agg-increase -The other topics are not used anymore. - -## Transition to PoX-5 - -A new PoX contract requires that all stacked Stacks tokens are unlocked and Stackers need to lock their Stacks token again using the new PoX-5 contract. The process shall be similar to the previous upgrades of the PoX contract. PoX-4 contract shall be deactivated and PoX-5 contract shall be activated at the beginning of epoch 3.2 All locked Stacks tokens shall be unlocked automatically 1 block after the beginning of epoch 3.2. +The other topics are no longer used. ## Registration of Signers @@ -175,7 +185,11 @@ The Stacks address of the first key is used by Stacks holders during delegation The encoded bitcoin address of the second key and the Stacks address of the third key are announced in a registration contract call. The new function of the PoX contract is named `signer-register` and just takes the encoded bitcoin address, and the stacks address as parameters. -Note, for solo stackers these three keys can be just a single key. For more complex setup, the keys can be handles by different independant entities. Also, the PoX reward address can be a deposit address for sBTC. +Note, for solo stackers these three keys can be just a single key. For more complex setup, the keys can be handled by different independant entities. Also, the PoX reward address can be a deposit address for sBTC. + +## Transition to PoX-5 + +A new PoX contract requires that all stacked Stacks tokens are unlocked and Stackers need to lock their Stacks token again using the new PoX-5 contract. The process shall be similar to the previous upgrades of the PoX contract. The PoX-4 contract shall be deactivated and the PoX-5 contract shall be activated at the beginning of epoch 3.2. All locked Stacks tokens shall be unlocked automatically one block after the beginning of epoch 3.2. # Related Work @@ -183,7 +197,7 @@ The previous PoX process is described in [SIP 007](https://github.com/stacksgov/ # Activation -This SIP requires a hard fork and shall be activated on Stacks 3.2 as defined by the SIP for epoch 3.2. +This SIP requires a hard fork and shall be activated on Stacks 3.2, as defined by the SIP for epoch 3.2. ## Appendix From 3bbf4424df05545de96ad8a7a40785a3753f7c67 Mon Sep 17 00:00:00 2001 From: friedger Date: Sun, 15 Jun 2025 13:52:14 +0200 Subject: [PATCH 06/22] improve mermaid graph --- sips/sip-x/sip-x-improved-stacking.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/sips/sip-x/sip-x-improved-stacking.md b/sips/sip-x/sip-x-improved-stacking.md index 8359e163e..76ccb5e40 100644 --- a/sips/sip-x/sip-x-improved-stacking.md +++ b/sips/sip-x/sip-x-improved-stacking.md @@ -131,14 +131,15 @@ This results in the following structure of the stacking cycle: - bitcoin block 2001-2100 (prepare phase): no rewards for stackers, changes to stacking are applied to the cycle after next. ```mermaid -gantt +timeline title Stacking Cycle Structure - dateFormat x - axisFormat %s - section Stacking Cycle - Stacking as usual, user can signal change of stacking settings :active, a1, 1, 1900 - Stacking as usual, signers can still aggregate stacking changes :a2, 1901, 100 - Prepare phase, no rewards, changes applied to cycle after next :a3, 2001, 100 + section Earning + 1 : Stacking as usual : User can signal change of stacking settings + ... : Usual reward distribution + 1901 : Stacking as usual : Auto extension : Signers can still aggregate stacking changes + section No earning + 2001 : Prepare phase, no rewards: delegate txs applied only to cycle after next + 2100 : End of cycle ``` That means the locking period is 1 cycle, with automatic extension for another cycle until the user decides to end stacking. From 31e8c92bacae1af125e11ddc3b4691e27f2e82ff Mon Sep 17 00:00:00 2001 From: friedger Date: Tue, 17 Jun 2025 10:01:27 +0200 Subject: [PATCH 07/22] prevent DDoS attack through small stacking amounts --- sips/sip-x/sip-x-improved-stacking.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sips/sip-x/sip-x-improved-stacking.md b/sips/sip-x/sip-x-improved-stacking.md index 76ccb5e40..44f01b8e4 100644 --- a/sips/sip-x/sip-x-improved-stacking.md +++ b/sips/sip-x/sip-x-improved-stacking.md @@ -150,7 +150,7 @@ When signers verify and accept proposed blocks by miners, their voting power cor - `delegate-stx` shall be renamed to `delegate`. The function takes the arguments: `amount`, `delegate-to`, `signature`, optional bitcoin `block-height` defining the end of stacking and auto extending, optional `max-amount`. The `amount` defines how many Stacks tokens are locked immediately. The `max-amount` the maximum of Stacks tokens that can be locked in the future through auto extending. If omitted the whole balance is locked. The argument `delegate-to` describes the signer. The argument `signature` is a signature of the signer indicating that the signer accepted the delegation of voting power. -- `revoke-delegate-stx` shall be renamed to `revoke-delegate`. After calling this functions, auto extension is stopped and Stacks tokens are unlocked for the user at the end of the current cycle. +- `revoke-delegate-stx` shall be renamed to `revoke-delegate`. After calling this functions, auto extension is stopped and Stacks tokens are unlocked for the user at the end of the current cycle. If the signer the user delegated to did not aggregated enough Stacks tokens to receive at least one reward slot then the user's Stacks token are unlocked immediately through this call. - `delegate-increase` is replaced by `delegate`. Users can simply call delegate with a higher amount. @@ -162,7 +162,7 @@ Signers provide a PoX reward address during the aggregation commit call. This bi There is no change in the registration of PoX reward addresses. In particular, there can be more than one PoX reward address per signer. -Stacks tokens that are part of a PoX reward address that aggregated less than the minimum required for at least one reward slot shall be unlocked at the beginning of the cycle. +Stacks tokens that are part of a PoX reward address that aggregated less than the minimum required for at least one reward slot can be unlocked through `revoke-delegate`. ## Relation between Stackers and Signers From 3ce2e0e7dbd4ff72a3e7a273361682435dcf98b1 Mon Sep 17 00:00:00 2001 From: friedger Date: Tue, 17 Jun 2025 14:38:59 +0200 Subject: [PATCH 08/22] fix: typos, clarity --- sips/sip-x/sip-x-improved-stacking.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/sips/sip-x/sip-x-improved-stacking.md b/sips/sip-x/sip-x-improved-stacking.md index 44f01b8e4..902e1df89 100644 --- a/sips/sip-x/sip-x-improved-stacking.md +++ b/sips/sip-x/sip-x-improved-stacking.md @@ -33,7 +33,7 @@ The specification defines that - solo stackers and delegating stackers have to follow the same flow and use the same contract functions: All users delegate block voting power to signers. - stackers can change their stacking settings for the next cycle before the prepare phase, including the chosen signer (switch pools). -- locked Stacks token are locked for 1 cycle at a time and that the locking period is extended by another cycle if the user does not request to unlock tokens. +- locked Stacks tokens are locked for 1 cycle at a time and that the locking period is extended by another cycle if the user does not request to unlock tokens. - delegated stacking tokens are locked immediately. - stacking rewards are received by the Bitcoin address specified by the signer. - locking Stacks tokens is protected by a new type of post conditions, enabling stacking through a contract in a single transaction. @@ -42,7 +42,7 @@ The specification defines that ## Current Situation -Currently, the stacking protocol has a few aspects that make using and integration stacking harder than it could be: +Currently, the stacking protocol has a few aspects that make using and integrating stacking harder than it could be: - There are two groups of stackers: solo stackers and delegated stackers. They use different sets of PoX contract functions. @@ -73,7 +73,7 @@ their Stacks tokens before the prepare phase, i.e. before the 2000th block of the current stacking cycle. Furthermore, Stacks tokens are locked for a locking period that always ends at the beginning of a cycle, i.e. after the prepare phase. Therefore, the current implementation of Stacking includes a period where Stacks -tokens are unlocked and cannot earn stacking rewards (Cooldown Cycle). +tokens are unlocked and ineligible for stacking rewards (Cooldown Cycle). The current PoX contract allows users to lock Stacks tokens during the prepare phase. This is too late for the next cycle and the tokens are locked without earning stacking rewards for one cycle. @@ -92,7 +92,7 @@ stacking rewards. This SIP proposes a new Proof of Transfer (PoX) contract without the flow for solo stacking and moves responsibilities from pool operators to signers who were introduced in the Nakamot upgrade. It also -defines a new locking mechanism that allows users to switch from one signer to another with a single contract call and without a cool down period. +defines a new locking mechanism that allows users to switch from one signer to another with a single contract call and without a cooldown period. # Specification @@ -150,7 +150,7 @@ When signers verify and accept proposed blocks by miners, their voting power cor - `delegate-stx` shall be renamed to `delegate`. The function takes the arguments: `amount`, `delegate-to`, `signature`, optional bitcoin `block-height` defining the end of stacking and auto extending, optional `max-amount`. The `amount` defines how many Stacks tokens are locked immediately. The `max-amount` the maximum of Stacks tokens that can be locked in the future through auto extending. If omitted the whole balance is locked. The argument `delegate-to` describes the signer. The argument `signature` is a signature of the signer indicating that the signer accepted the delegation of voting power. -- `revoke-delegate-stx` shall be renamed to `revoke-delegate`. After calling this functions, auto extension is stopped and Stacks tokens are unlocked for the user at the end of the current cycle. If the signer the user delegated to did not aggregated enough Stacks tokens to receive at least one reward slot then the user's Stacks token are unlocked immediately through this call. +- `revoke-delegate-stx` shall be renamed to `revoke-delegate`. After calling this functions, auto extension is stopped and Stacks tokens are unlocked for the user at the end of the current cycle. If the signer the user delegated to did not aggregate enough Stacks tokens to receive at least one reward slot then the user's Stacks token are unlocked immediately through this call. - `delegate-increase` is replaced by `delegate`. Users can simply call delegate with a higher amount. @@ -186,7 +186,7 @@ The Stacks address of the first key is used by Stacks holders during delegation The encoded bitcoin address of the second key and the Stacks address of the third key are announced in a registration contract call. The new function of the PoX contract is named `signer-register` and just takes the encoded bitcoin address, and the stacks address as parameters. -Note, for solo stackers these three keys can be just a single key. For more complex setup, the keys can be handled by different independant entities. Also, the PoX reward address can be a deposit address for sBTC. +Note, for solo stackers these three keys can be just a single key. For more complex setup, the keys can be handled by different independent entities. Also, the PoX reward address can be a deposit address for sBTC. ## Transition to PoX-5 From 0891e53a96fa594f42c7ae7462df4968ef51d62f Mon Sep 17 00:00:00 2001 From: Friedger Date: Mon, 30 Jun 2025 19:39:26 +0200 Subject: [PATCH 09/22] Update sips/sip-x/sip-x-improved-stacking.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Rafael Cárdenas --- sips/sip-x/sip-x-improved-stacking.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sips/sip-x/sip-x-improved-stacking.md b/sips/sip-x/sip-x-improved-stacking.md index 902e1df89..0417439e1 100644 --- a/sips/sip-x/sip-x-improved-stacking.md +++ b/sips/sip-x/sip-x-improved-stacking.md @@ -91,7 +91,7 @@ stacking rewards. ## Proposed Solution This SIP proposes a new Proof of Transfer (PoX) contract without -the flow for solo stacking and moves responsibilities from pool operators to signers who were introduced in the Nakamot upgrade. It also +the flow for solo stacking and moves responsibilities from pool operators to signers who were introduced in the Nakamoto upgrade. It also defines a new locking mechanism that allows users to switch from one signer to another with a single contract call and without a cooldown period. # Specification From 895f3b7160c7d6541a9f6c3c3ca78e8942fd4957 Mon Sep 17 00:00:00 2001 From: friedger Date: Tue, 1 Jul 2025 23:16:51 +0200 Subject: [PATCH 10/22] chore: clarify the flow --- sips/sip-x/sip-x-improved-stacking.md | 75 ++++++++++++++------------- 1 file changed, 38 insertions(+), 37 deletions(-) diff --git a/sips/sip-x/sip-x-improved-stacking.md b/sips/sip-x/sip-x-improved-stacking.md index 0417439e1..b80de0360 100644 --- a/sips/sip-x/sip-x-improved-stacking.md +++ b/sips/sip-x/sip-x-improved-stacking.md @@ -26,13 +26,13 @@ # Abstract -This SIP proposes a change to the stacking process so that stackers can change their stacking settings without the so-called cooldown cycle. Furthermore, the relationship between stackers +This SIP proposes a change to the stacking process so that Stackers can change their stacking settings without the so-called cooldown cycle. Furthermore, the relationship between Stackers and signers is strengthened and stacking overall is simplified. The specification defines that -- solo stackers and delegating stackers have to follow the same flow and use the same contract functions: All users delegate block voting power to signers. -- stackers can change their stacking settings for the next cycle before the prepare phase, including the chosen signer (switch pools). +- solo Stackers and delegating Stackers have to follow the same flow and use the same contract functions: All users delegate block voting power to signers. +- Stackers can change their stacking settings for the next cycle before the prepare phase, including the chosen signer (switch pools). - locked Stacks tokens are locked for 1 cycle at a time and that the locking period is extended by another cycle if the user does not request to unlock tokens. - delegated stacking tokens are locked immediately. - stacking rewards are received by the Bitcoin address specified by the signer. @@ -44,11 +44,11 @@ The specification defines that Currently, the stacking protocol has a few aspects that make using and integrating stacking harder than it could be: -- There are two groups of stackers: solo stackers and delegated stackers. They use different sets of PoX contract functions. +- There are two groups of Stackers: solo Stackers and delegated Stackers. They use different sets of PoX contract functions. -- When using a contract for stacking, the contract needs to be added as an allowed pox contract. This requires a separate transaction. +- When using a contract for stacking, the contract needs to be added as an allowed PoX contract. This requires a separate transaction. -- Solo stackers do all transactions with their cold wallet holding the whole STX balance. They need to make a transaction at least once every 12 cycles (6 months). In contrast, delegated stackers need to do only a single transaction with their wallet for the entire stacking. +- Solo Stackers do all transactions with their cold wallet holding the whole STX balance. They need to make a transaction at least once every 12 cycles (6 months). In contrast, delegated Stackers need to do only a single transaction with their wallet for the entire stacking. - Signers make off-chain agreements with pool operators regarding revenue sharing. @@ -56,15 +56,15 @@ Currently, the stacking protocol has a few aspects that make using and integrati | Term | Definition | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Cooldown Cycle** | The period of 1 stacking cycle where stackers cannot stack their STX tokens because their tokens are unlocked only at the beginning of a stacking cycle. | +| **Cooldown Cycle** | The period of 1 stacking cycle where Stackers cannot stack their STX tokens because their tokens are unlocked only at the beginning of a stacking cycle. | | **Signer** | The node operators that verify and confirm proposed blocks by miners. | -| **Delegation (old)** | delegating the management of stacking. | -| **Delegation (new)** | delegating the voting power for proposed blocks. | +| **Delegation (old)** | Delegating the management of stacking. | +| **Delegation (new)** | Delegating the voting power for proposed blocks. | | **PoX Contract** | The smart contract that users interact with to lock their tokens. | ## Problem Statement -The current stacking process has two different paths, one for solo stackers, one for delegated stackers, +The current stacking process has two different paths, one for solo Stackers, one for delegated Stackers, resulting in a more complex user experience and more complex code. The process is defined by a prepare phase of 100 bitcoin blocks that is used to find an anchor block @@ -79,7 +79,7 @@ The current PoX contract allows users to lock Stacks tokens during the prepare p and the tokens are locked without earning stacking rewards for one cycle. The cooldown cycle for unstacking from a pool presents a problem for network decentralization. -As a stacker, when I delegate to a signer and that signer does not perform and gets low yield, +As a Stacker, when I delegate to a signer and that signer does not perform and gets low yield, I get penalized for switching. In today's model with cooldown cycles, users get double penalized if a signer does not perform. Even if there are penalties for signers not performing / being down, the switching costs are too high for users to switch (two weeks' worth of yield). @@ -114,21 +114,21 @@ The following type of post conditions shall be added to the current definition i - `LockingLimit(PostConditionPrincipal, FungibleConditionCode, u64)` -A transaction (using Deny mode) with this post condition will abort if the locked Stacks tokens of the principal does not satisfy the provided conditions. The logic for the conditions follows that of STX transfer. +A transaction (using Deny mode) with this post condition will abort if the locked Stacks tokens of the principal do not satisfy the provided conditions. The logic for the conditions follows that of STX transfer. -## Automatic Extend and Locking period +## Automatic Extend and Locking Period The following function shall be removed: - `delegate-stack-extend` -In addition, the stacking settings for each stacker (user with delegation) shall be applied for the next stacking cycle if the user did not signal the end of stacking by calling `revoke-delegate-stx` 200 blocks before the start of the next cycle. +In addition, the stacking settings for each Stacker (user with delegation) shall be applied for the next stacking cycle if the user did not signal the end of stacking by calling `revoke-delegate-stx` 200 blocks before the start of the next cycle. This results in the following structure of the stacking cycle: - bitcoin block 1-1900: stacking as usual, user can signal change of stacking settings. - bitcoin block 1901-2000: stacking as usual, signers can still aggregate stacking changes. -- bitcoin block 2001-2100 (prepare phase): no rewards for stackers, changes to stacking are applied to the cycle after next. +- bitcoin block 2001-2100 (prepare phase): no rewards for Stackers, changes to stacking are applied to the cycle after next. ```mermaid timeline @@ -148,49 +148,50 @@ That means the locking period is 1 cycle, with automatic extension for another c When signers verify and accept proposed blocks by miners, their voting power corresponds to the amount of stacked Stacks tokens (see SIP-021). The new stacking process changes the delegation flow as follows: -- `delegate-stx` shall be renamed to `delegate`. The function takes the arguments: `amount`, `delegate-to`, `signature`, optional bitcoin `block-height` defining the end of stacking and auto extending, optional `max-amount`. The `amount` defines how many Stacks tokens are locked immediately. The `max-amount` the maximum of Stacks tokens that can be locked in the future through auto extending. If omitted the whole balance is locked. The argument `delegate-to` describes the signer. The argument `signature` is a signature of the signer indicating that the signer accepted the delegation of voting power. +- `delegate-stx` shall be renamed to `delegate`/`designate`. The function takes the arguments: `amount`, `signature`, optional bitcoin `block-height` defining the end of stacking and auto extending, optional `pox-addr` defining that pox-address that the signer must use, optional `max-amount`. The `amount` defines how many Stacks tokens are locked immediately. The `max-amount` defines the maximum of Stacks tokens that can be locked in the future through auto extending. If provided the minimum of the user's stx balance and `max-amount` is locked. If omitted, the whole user's balance is locked. Users can use sponsored transactions to call revoke-delegate-stx in case there is no unlocked stx in the account. The argument `signature` is a signature of the signer indicating that the signer accepted the delegation of voting power. The signing follows the structured message signing with the parameters and topic `designate` as message. The public key of the signature can be used to identify the signer similar to the Stacks address of the pool operator in the previous PoX design. -- `revoke-delegate-stx` shall be renamed to `revoke-delegate`. After calling this functions, auto extension is stopped and Stacks tokens are unlocked for the user at the end of the current cycle. If the signer the user delegated to did not aggregate enough Stacks tokens to receive at least one reward slot then the user's Stacks token are unlocked immediately through this call. +- `revoke-delegate-stx` shall be renamed to `revoke-delegate`/`revoke-designate`. After calling this function, auto extension is stopped and Stacks tokens are unlocked for the user at the end of the current cycle. If a signer does not aggregate enough Stacks tokens to receive at least one reward slot (or does not commit at all) then the user's Stacks token are unlocked immediately through this call. -- `delegate-increase` is replaced by `delegate`. Users can simply call delegate with a higher amount. +- `delegate-increase` is replaced by `delegate-update-amount`/`designate-update-amount`. It sets max-amount to the new value. The amount can be smaller than the currently locked amount. As tokens are only locked for 1 cycle at a time, handling decreasing is now easy enough in comparison to the previous system with locking periods of up to 12 cycles. - `delegate-extend` is removed because the locking period is automatically extended each cycle. -## Aggregation Commit and PoX Reward Address +## Role of Signers -Signers provide a PoX reward address during the aggregation commit call. This bitcoin address shall be used to receive stacking rewards. +### PoX Reward Addresses -There is no change in the registration of PoX reward addresses. In particular, there can be more than one PoX reward address per signer. +`Stacks-aggregation-commit` is replaced by `register-signer`. Signers indicate their liveness and provide a PoX reward address and a Stacks address with this call. The bitcoin address shall be used to receive stacking rewards. It can be used by Stackers as `pox-addr` parameter during `delegate`/`designate` call. + +The `register-signer` call can only be called between 1901st and 2000th block of a stacking cycle. During this period, Stackers can't change their stacking settings, therefore, no aggregate is required. -Stacks tokens that are part of a PoX reward address that aggregated less than the minimum required for at least one reward slot can be unlocked through `revoke-delegate`. +There is no change in the registration of PoX reward addresses. In particular, there can be more than one PoX reward address per signer. -## Relation between Stackers and Signers +### Signatures -The signatures provided by signers to stackers shall use one of the following topics +The signatures provided by signers to Stackers or the network shall use one of the following topics -- delegate -- agg-commit -- agg-increase +- delegate/designate +- agg-commit/alive The other topics are no longer used. -## Registration of Signers +Signers handle two or three private keys: -Signers handle three private keys: +1. one for signing blocks, +2. one for delegation approval and register transactions on the Stacks blockchain; +3. optionally, one for PoX reward address and reward distribution. -1. one for signing blocks and delegation approval; -2. one for PoX reward address and reward distribution; -3. one for aggregation on the Stacks blockchain. +Note, for solo Stackers these keys can be just a single key. For more complex setup, the keys can be handled by different independent entities. Also, the PoX reward address can be a deposit address for sBTC of a Stacks smart contract. In this case, the signer does not hold a private key for the PoX reward address. -The Stacks address of the first key is used by Stacks holders during delegation for `delegate-to`. +## Transition to PoX-5 -The encoded bitcoin address of the second key and the Stacks address of the third key are announced in a registration contract call. The new function of the PoX contract is named `signer-register` and just takes the encoded bitcoin address, and the stacks address as parameters. +A new PoX contract requires that all stacked Stacks tokens are unlocked and Stackers need to lock their Stacks token again using the new PoX-5 contract. The process shall be similar to the previous upgrades of the PoX contract. The PoX-4 contract shall be deactivated and the PoX-5 contract shall be activated at the beginning of epoch 3.2. All locked Stacks tokens shall be unlocked automatically one block after the beginning of epoch 3.2. Nevertheless, these tokens will earn rewards until the end of the cycle. -Note, for solo stackers these three keys can be just a single key. For more complex setup, the keys can be handled by different independent entities. Also, the PoX reward address can be a deposit address for sBTC. +## Reference implementation -## Transition to PoX-5 +A reference implementation for creating signatures is available at ... (TODO). Note, that signers (or previously pool operators) no longer extend the locking period for each Stacker on-chain, instead signers provide a signature for each Stacker off-chain. -A new PoX contract requires that all stacked Stacks tokens are unlocked and Stackers need to lock their Stacks token again using the new PoX-5 contract. The process shall be similar to the previous upgrades of the PoX contract. The PoX-4 contract shall be deactivated and the PoX-5 contract shall be activated at the beginning of epoch 3.2. All locked Stacks tokens shall be unlocked automatically one block after the beginning of epoch 3.2. +A reference implementation for a sidecar for signer node is available at ... (TODO). # Related Work From 8e15dc7d815f207aaec9abc88c61479faaeeb990 Mon Sep 17 00:00:00 2001 From: Friedger Date: Thu, 31 Jul 2025 09:37:05 +0200 Subject: [PATCH 11/22] Update sips/sip-x/sip-x-improved-stacking.md --- sips/sip-x/sip-x-improved-stacking.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sips/sip-x/sip-x-improved-stacking.md b/sips/sip-x/sip-x-improved-stacking.md index b80de0360..c2582dd83 100644 --- a/sips/sip-x/sip-x-improved-stacking.md +++ b/sips/sip-x/sip-x-improved-stacking.md @@ -127,7 +127,7 @@ In addition, the stacking settings for each Stacker (user with delegation) shall This results in the following structure of the stacking cycle: - bitcoin block 1-1900: stacking as usual, user can signal change of stacking settings. -- bitcoin block 1901-2000: stacking as usual, signers can still aggregate stacking changes. +- bitcoin block 1901-2000: stacking as usual, signers can still aggregate stacking changes, signalled changes by users will be applied only for the next cycle. - bitcoin block 2001-2100 (prepare phase): no rewards for Stackers, changes to stacking are applied to the cycle after next. ```mermaid From 8a10e82e26f2d9aa01559da8cd5aac8aac5c5570 Mon Sep 17 00:00:00 2001 From: friedger Date: Thu, 31 Jul 2025 18:53:08 +0200 Subject: [PATCH 12/22] add section about locked amount and events --- sips/sip-x/sip-x-improved-stacking.md | 33 ++++++++++++++++++++------- 1 file changed, 25 insertions(+), 8 deletions(-) diff --git a/sips/sip-x/sip-x-improved-stacking.md b/sips/sip-x/sip-x-improved-stacking.md index c2582dd83..0ff8ceb03 100644 --- a/sips/sip-x/sip-x-improved-stacking.md +++ b/sips/sip-x/sip-x-improved-stacking.md @@ -127,7 +127,7 @@ In addition, the stacking settings for each Stacker (user with delegation) shall This results in the following structure of the stacking cycle: - bitcoin block 1-1900: stacking as usual, user can signal change of stacking settings. -- bitcoin block 1901-2000: stacking as usual, signers can still aggregate stacking changes, signalled changes by users will be applied only for the next cycle. +- bitcoin block 1901-2000: stacking as usual, signers can still aggregate stacking changes, changes to stacking are applied to the cycle after next. - bitcoin block 2001-2100 (prepare phase): no rewards for Stackers, changes to stacking are applied to the cycle after next. ```mermaid @@ -148,21 +148,38 @@ That means the locking period is 1 cycle, with automatic extension for another c When signers verify and accept proposed blocks by miners, their voting power corresponds to the amount of stacked Stacks tokens (see SIP-021). The new stacking process changes the delegation flow as follows: -- `delegate-stx` shall be renamed to `delegate`/`designate`. The function takes the arguments: `amount`, `signature`, optional bitcoin `block-height` defining the end of stacking and auto extending, optional `pox-addr` defining that pox-address that the signer must use, optional `max-amount`. The `amount` defines how many Stacks tokens are locked immediately. The `max-amount` defines the maximum of Stacks tokens that can be locked in the future through auto extending. If provided the minimum of the user's stx balance and `max-amount` is locked. If omitted, the whole user's balance is locked. Users can use sponsored transactions to call revoke-delegate-stx in case there is no unlocked stx in the account. The argument `signature` is a signature of the signer indicating that the signer accepted the delegation of voting power. The signing follows the structured message signing with the parameters and topic `designate` as message. The public key of the signature can be used to identify the signer similar to the Stacks address of the pool operator in the previous PoX design. +- `delegate-stx` shall be renamed to `designate`. The function takes the arguments: `amount`, `signature`, optional bitcoin `block-height` defining the end of stacking and auto extending, optional `pox-addr` defining that pox-address that the signer must use, optional `max-amount`. The `amount` defines how many Stacks tokens are locked immediately. The `max-amount` defines the maximum of Stacks tokens that can be locked in the future through auto extending. If provided the minimum of the user's stx balance and `max-amount` is locked. If omitted, the whole user's balance is locked. Users can use sponsored transactions to call revoke-delegate-stx in case there is no unlocked stx in the account. The argument `signature` is a signature of the signer indicating that the signer accepted the delegation of voting power. The signing follows the structured message signing with the parameters and topic `designate` as message. The public key of the signature can be used to identify the signer similar to the Stacks address of the pool operator in the previous PoX design. -- `revoke-delegate-stx` shall be renamed to `revoke-delegate`/`revoke-designate`. After calling this function, auto extension is stopped and Stacks tokens are unlocked for the user at the end of the current cycle. If a signer does not aggregate enough Stacks tokens to receive at least one reward slot (or does not commit at all) then the user's Stacks token are unlocked immediately through this call. +- `revoke-delegate-stx` shall be renamed to `revoke-designate`. After calling this function, auto extension is stopped and Stacks tokens are unlocked for the user at the end of the current cycle. If a signer does not aggregate enough Stacks tokens to receive at least one reward slot (or does not commit at all) then the user's Stacks token are unlocked immediately through this call. -- `delegate-increase` is replaced by `delegate-update-amount`/`designate-update-amount`. It sets max-amount to the new value. The amount can be smaller than the currently locked amount. As tokens are only locked for 1 cycle at a time, handling decreasing is now easy enough in comparison to the previous system with locking periods of up to 12 cycles. +- `delegate-increase` is replaced by `designate-update-amount`. It sets max-amount to the new value. The amount can be smaller than the currently locked amount. As tokens are only locked for 1 cycle at a time, handling decreasing is now easy enough in comparison to the previous system with locking periods of up to 12 cycles. - `delegate-extend` is removed because the locking period is automatically extended each cycle. +## Amount of Stacked STX + +When a transaction locks or unlocks STX for the user a corresponding event shall be emitted. The following events used in PoX 4 are used: + +- `stack-stx` (rename to `designate`) +- `stack-increase` (renamed to `designate-increase`) +- `stack-decrease` (renamed to `designate-decrease`) +- `stack-extend` (rename to `designate-extend`) +- `stack-aggregation-commit` (renamed to `signer-accept`) + +Furthermore, a function `get-stacker-info` shall return for the given principal + +- the accepted stacked amount by the signer and the cycle of acceptance `(optional {amount: uint), cycle: uint})` +- the current stacked amount `uint` + +When stackers designate the first time, the function `get-stacker-info` returns only the current stacked amount until it was accepted by the signer. + ## Role of Signers ### PoX Reward Addresses -`Stacks-aggregation-commit` is replaced by `register-signer`. Signers indicate their liveness and provide a PoX reward address and a Stacks address with this call. The bitcoin address shall be used to receive stacking rewards. It can be used by Stackers as `pox-addr` parameter during `delegate`/`designate` call. +`Stacks-aggregation-commit` is replaced by `signer-register`. Signers indicate their liveness and provide a PoX reward address and a Stacks address with this call. The bitcoin address shall be used to receive stacking rewards. It can be used by Stackers as `pox-addr` parameter during `delegate`/`designate` call. -The `register-signer` call can only be called between 1901st and 2000th block of a stacking cycle. During this period, Stackers can't change their stacking settings, therefore, no aggregate is required. +The `signer-register` call can only be called between 1901st and 2000th block of a stacking cycle. During this period, Stackers can't change their stacking settings, therefore, no aggregate is required. There is no change in the registration of PoX reward addresses. In particular, there can be more than one PoX reward address per signer. @@ -170,8 +187,8 @@ There is no change in the registration of PoX reward addresses. In particular, t The signatures provided by signers to Stackers or the network shall use one of the following topics -- delegate/designate -- agg-commit/alive +- designate +- register The other topics are no longer used. From a2e7bae3ce73d3ac7b6b0b2a4e9956a6481569c9 Mon Sep 17 00:00:00 2001 From: friedger Date: Thu, 31 Jul 2025 19:18:56 +0200 Subject: [PATCH 13/22] clarify voting power and decreased stacked stx amount --- sips/sip-x/sip-x-improved-stacking.md | 27 ++++++++++++++++++--------- 1 file changed, 18 insertions(+), 9 deletions(-) diff --git a/sips/sip-x/sip-x-improved-stacking.md b/sips/sip-x/sip-x-improved-stacking.md index 0ff8ceb03..521c7932d 100644 --- a/sips/sip-x/sip-x-improved-stacking.md +++ b/sips/sip-x/sip-x-improved-stacking.md @@ -122,7 +122,7 @@ The following function shall be removed: - `delegate-stack-extend` -In addition, the stacking settings for each Stacker (user with delegation) shall be applied for the next stacking cycle if the user did not signal the end of stacking by calling `revoke-delegate-stx` 200 blocks before the start of the next cycle. +In addition, the stacking settings for each Stacker (user with delegation) shall be applied for the next stacking cycle if the user did not signal the end of stacking by calling `revoke-designation` 200 blocks before the start of the next cycle. This results in the following structure of the stacking cycle: @@ -144,15 +144,19 @@ timeline That means the locking period is 1 cycle, with automatic extension for another cycle until the user decides to end stacking. +The amount of stacking STX can increase during the automatic extension up to the minimum of the balance and a user specified maximum amount. + +The amount of stacked STX does not decrease during the automatic extension. If the user requested a decrease of the stacked amount, this difference is unlocked at the end of the stacking period. + ## Semantic Change of Delegation When signers verify and accept proposed blocks by miners, their voting power corresponds to the amount of stacked Stacks tokens (see SIP-021). The new stacking process changes the delegation flow as follows: - `delegate-stx` shall be renamed to `designate`. The function takes the arguments: `amount`, `signature`, optional bitcoin `block-height` defining the end of stacking and auto extending, optional `pox-addr` defining that pox-address that the signer must use, optional `max-amount`. The `amount` defines how many Stacks tokens are locked immediately. The `max-amount` defines the maximum of Stacks tokens that can be locked in the future through auto extending. If provided the minimum of the user's stx balance and `max-amount` is locked. If omitted, the whole user's balance is locked. Users can use sponsored transactions to call revoke-delegate-stx in case there is no unlocked stx in the account. The argument `signature` is a signature of the signer indicating that the signer accepted the delegation of voting power. The signing follows the structured message signing with the parameters and topic `designate` as message. The public key of the signature can be used to identify the signer similar to the Stacks address of the pool operator in the previous PoX design. -- `revoke-delegate-stx` shall be renamed to `revoke-designate`. After calling this function, auto extension is stopped and Stacks tokens are unlocked for the user at the end of the current cycle. If a signer does not aggregate enough Stacks tokens to receive at least one reward slot (or does not commit at all) then the user's Stacks token are unlocked immediately through this call. +- `revoke-delegate-stx` shall be renamed to `revoke-designation`. After calling this function, auto extension is stopped and Stacks tokens are unlocked for the user at the end of the current cycle. If a signer does not aggregate enough Stacks tokens to receive at least one reward slot (or does not commit at all) then the user's Stacks token are unlocked immediately through this call. -- `delegate-increase` is replaced by `designate-update-amount`. It sets max-amount to the new value. The amount can be smaller than the currently locked amount. As tokens are only locked for 1 cycle at a time, handling decreasing is now easy enough in comparison to the previous system with locking periods of up to 12 cycles. +- `delegate-increase` is replaced by `update-max-amount`. It sets max-amount to the new value. This value is applied when the user's designation is extended for the next cycle. The amount can be smaller than the currently locked amount. As tokens are only locked for 1 cycle at a time, handling decreasing is now easy enough in comparison to the previous system with locking periods of up to 12 cycles. - `delegate-extend` is removed because the locking period is automatically extended each cycle. @@ -160,18 +164,19 @@ When signers verify and accept proposed blocks by miners, their voting power cor When a transaction locks or unlocks STX for the user a corresponding event shall be emitted. The following events used in PoX 4 are used: -- `stack-stx` (rename to `designate`) -- `stack-increase` (renamed to `designate-increase`) -- `stack-decrease` (renamed to `designate-decrease`) -- `stack-extend` (rename to `designate-extend`) -- `stack-aggregation-commit` (renamed to `signer-accept`) +- `designate` when the user designates a signer +- `designate-increase` when the amount of voting power is increased by a user +- `designate-decrease` when the amount of voting power is decreased by a user. +- `designate-extend` when the designation is extended by 1 cycle for a user. +- `signer-accept` when the signer accepts the designation from all users. Furthermore, a function `get-stacker-info` shall return for the given principal - the accepted stacked amount by the signer and the cycle of acceptance `(optional {amount: uint), cycle: uint})` - the current stacked amount `uint` +- the current max-amount `(optional uint)` -When stackers designate the first time, the function `get-stacker-info` returns only the current stacked amount until it was accepted by the signer. +When stackers designate the first time, the function `get-stacker-info` the accepted stacked amount is `none`. ## Role of Signers @@ -200,6 +205,10 @@ Signers handle two or three private keys: Note, for solo Stackers these keys can be just a single key. For more complex setup, the keys can be handled by different independent entities. Also, the PoX reward address can be a deposit address for sBTC of a Stacks smart contract. In this case, the signer does not hold a private key for the PoX reward address. +### Voting Power + +The voting power for a signer is the sum of the accepted stacked STX, not the sum of the currently stacked STX because users can have descreased the stacking amount. + ## Transition to PoX-5 A new PoX contract requires that all stacked Stacks tokens are unlocked and Stackers need to lock their Stacks token again using the new PoX-5 contract. The process shall be similar to the previous upgrades of the PoX contract. The PoX-4 contract shall be deactivated and the PoX-5 contract shall be activated at the beginning of epoch 3.2. All locked Stacks tokens shall be unlocked automatically one block after the beginning of epoch 3.2. Nevertheless, these tokens will earn rewards until the end of the cycle. From 0ef1069cd7609378eb79efd419c83937133700fe Mon Sep 17 00:00:00 2001 From: Friedger Date: Thu, 14 Aug 2025 16:54:07 +0200 Subject: [PATCH 14/22] rename to sip 032 --- ...{sip-x-improved-stacking.md => sip-032-improved-stacking.md} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename sips/sip-x/{sip-x-improved-stacking.md => sip-032-improved-stacking.md} (99%) diff --git a/sips/sip-x/sip-x-improved-stacking.md b/sips/sip-x/sip-032-improved-stacking.md similarity index 99% rename from sips/sip-x/sip-x-improved-stacking.md rename to sips/sip-x/sip-032-improved-stacking.md index 521c7932d..d3ffff4b2 100644 --- a/sips/sip-x/sip-x-improved-stacking.md +++ b/sips/sip-x/sip-032-improved-stacking.md @@ -1,6 +1,6 @@ # Preamble -**SIP Number:** XXX +**SIP Number:** 032 **Title:** Improved Stacking Protocol From d1a016dd8477540c4cddaa1e24b81ebaa99d76b4 Mon Sep 17 00:00:00 2001 From: Friedger Date: Thu, 14 Aug 2025 17:29:33 +0200 Subject: [PATCH 15/22] rename folder --- sips/{sip-x => sip-032}/sip-032-improved-stacking.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename sips/{sip-x => sip-032}/sip-032-improved-stacking.md (100%) diff --git a/sips/sip-x/sip-032-improved-stacking.md b/sips/sip-032/sip-032-improved-stacking.md similarity index 100% rename from sips/sip-x/sip-032-improved-stacking.md rename to sips/sip-032/sip-032-improved-stacking.md From 5c1159dcc62ddbd43401fbe548e949e2a388b1cb Mon Sep 17 00:00:00 2001 From: friedger Date: Sat, 23 Aug 2025 19:55:28 +0200 Subject: [PATCH 16/22] fix: address comments, update to 3.3 --- sips/sip-032/sip-032-improved-stacking.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/sips/sip-032/sip-032-improved-stacking.md b/sips/sip-032/sip-032-improved-stacking.md index d3ffff4b2..eba9af9f8 100644 --- a/sips/sip-032/sip-032-improved-stacking.md +++ b/sips/sip-032/sip-032-improved-stacking.md @@ -79,8 +79,8 @@ The current PoX contract allows users to lock Stacks tokens during the prepare p and the tokens are locked without earning stacking rewards for one cycle. The cooldown cycle for unstacking from a pool presents a problem for network decentralization. -As a Stacker, when I delegate to a signer and that signer does not perform and gets low yield, -I get penalized for switching. In today's model with cooldown cycles, users get double penalized +When a stacker delegates to a signer and that signer does not perform and gets low yield, +the stacker gets penalized for switching. In today's model with cooldown cycles, users get double penalized if a signer does not perform. Even if there are penalties for signers not performing / being down, the switching costs are too high for users to switch (two weeks' worth of yield). @@ -98,7 +98,7 @@ defines a new locking mechanism that allows users to switch from one signer to a Applying these upgrades to the Stacks blockchain requires a consensus-breaking network upgrade, in this case, a hard fork. Like other such changes, this will require a new Stacks epoch. -In this SIP, we will refer to this new epoch as Stacks 3.2. +In this SIP, we will refer to this new epoch as Stacks 3.3. ## Delegated Stacking only @@ -203,7 +203,7 @@ Signers handle two or three private keys: 2. one for delegation approval and register transactions on the Stacks blockchain; 3. optionally, one for PoX reward address and reward distribution. -Note, for solo Stackers these keys can be just a single key. For more complex setup, the keys can be handled by different independent entities. Also, the PoX reward address can be a deposit address for sBTC of a Stacks smart contract. In this case, the signer does not hold a private key for the PoX reward address. +Note, for solo Stackers these keys could be theoretically just a single key. For more complex setups, the keys can be handled by different independent entities. Also, the PoX reward address can be a deposit address for sBTC of a Stacks smart contract. In this case, the signer does not hold a private key for the PoX reward address. ### Voting Power @@ -211,7 +211,7 @@ The voting power for a signer is the sum of the accepted stacked STX, not the su ## Transition to PoX-5 -A new PoX contract requires that all stacked Stacks tokens are unlocked and Stackers need to lock their Stacks token again using the new PoX-5 contract. The process shall be similar to the previous upgrades of the PoX contract. The PoX-4 contract shall be deactivated and the PoX-5 contract shall be activated at the beginning of epoch 3.2. All locked Stacks tokens shall be unlocked automatically one block after the beginning of epoch 3.2. Nevertheless, these tokens will earn rewards until the end of the cycle. +A new PoX contract requires that all stacked Stacks tokens are unlocked and Stackers need to lock their Stacks token again using the new PoX-5 contract. The process shall be similar to the previous upgrades of the PoX contract. The PoX-4 contract shall be deactivated and the PoX-5 contract shall be activated at the beginning of epoch 3.3. All locked Stacks tokens shall be unlocked automatically one block after the beginning of epoch 3.3. Nevertheless, these tokens will earn rewards until the end of the cycle. ## Reference implementation @@ -225,7 +225,7 @@ The previous PoX process is described in [SIP 007](https://github.com/stacksgov/ # Activation -This SIP requires a hard fork and shall be activated on Stacks 3.2, as defined by the SIP for epoch 3.2. +This SIP requires a hard fork and shall be activated on Stacks 3.3, as defined by the SIP for epoch 3.3. ## Appendix From 1cb837b85460adb8902c8745d68c4c73b003b5f2 Mon Sep 17 00:00:00 2001 From: friedger Date: Sat, 23 Aug 2025 21:30:36 +0200 Subject: [PATCH 17/22] fix: clarify the events --- sips/sip-032/sip-032-improved-stacking.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/sips/sip-032/sip-032-improved-stacking.md b/sips/sip-032/sip-032-improved-stacking.md index eba9af9f8..ff78d042b 100644 --- a/sips/sip-032/sip-032-improved-stacking.md +++ b/sips/sip-032/sip-032-improved-stacking.md @@ -168,6 +168,9 @@ When a transaction locks or unlocks STX for the user a corresponding event shall - `designate-increase` when the amount of voting power is increased by a user - `designate-decrease` when the amount of voting power is decreased by a user. - `designate-extend` when the designation is extended by 1 cycle for a user. + +The new event is added: + - `signer-accept` when the signer accepts the designation from all users. Furthermore, a function `get-stacker-info` shall return for the given principal From 02d5c73a9465ae9ac974be0df8cff739c01dc655 Mon Sep 17 00:00:00 2001 From: friedger Date: Sat, 23 Aug 2025 22:11:07 +0200 Subject: [PATCH 18/22] fix: use signer-accept also as event name --- sips/sip-032/sip-032-improved-stacking.md | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/sips/sip-032/sip-032-improved-stacking.md b/sips/sip-032/sip-032-improved-stacking.md index ff78d042b..399254086 100644 --- a/sips/sip-032/sip-032-improved-stacking.md +++ b/sips/sip-032/sip-032-improved-stacking.md @@ -162,15 +162,12 @@ When signers verify and accept proposed blocks by miners, their voting power cor ## Amount of Stacked STX -When a transaction locks or unlocks STX for the user a corresponding event shall be emitted. The following events used in PoX 4 are used: +When a transaction locks or unlocks STX for the user a corresponding event shall be emitted. The following events are used: - `designate` when the user designates a signer - `designate-increase` when the amount of voting power is increased by a user - `designate-decrease` when the amount of voting power is decreased by a user. - `designate-extend` when the designation is extended by 1 cycle for a user. - -The new event is added: - - `signer-accept` when the signer accepts the designation from all users. Furthermore, a function `get-stacker-info` shall return for the given principal @@ -185,11 +182,11 @@ When stackers designate the first time, the function `get-stacker-info` the acce ### PoX Reward Addresses -`Stacks-aggregation-commit` is replaced by `signer-register`. Signers indicate their liveness and provide a PoX reward address and a Stacks address with this call. The bitcoin address shall be used to receive stacking rewards. It can be used by Stackers as `pox-addr` parameter during `delegate`/`designate` call. +`Stacks-aggregation-commit` is replaced by `signer-accept`. Signers indicate their liveness and provide a PoX reward address and a Stacks address with this call. The bitcoin address shall be used to receive stacking rewards. It can be used by Stackers as `pox-addr` parameter during `delegate`/`designate` call. -The `signer-register` call can only be called between 1901st and 2000th block of a stacking cycle. During this period, Stackers can't change their stacking settings, therefore, no aggregate is required. +Furthermore, the `signer-accept` call indicates the acceptance of the designation of all users before the call. The very first call to `signer-accept` by a signer can already accept designations if the signer's details have been communicated off-chain before. -There is no change in the registration of PoX reward addresses. In particular, there can be more than one PoX reward address per signer. +The `signer-accept` call can only be called between 1901st and 2000th block of a stacking cycle. During this period, Stackers can't change their stacking settings, therefore, no aggregate is required. ### Signatures From 876eaac25ecc9474accd8419f9804d49b3dbdc4a Mon Sep 17 00:00:00 2001 From: Friedger Date: Mon, 15 Sep 2025 23:16:06 +0200 Subject: [PATCH 19/22] Update sips/sip-032/sip-032-improved-stacking.md Co-authored-by: wileyj <2847772+wileyj@users.noreply.github.com> --- sips/sip-032/sip-032-improved-stacking.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sips/sip-032/sip-032-improved-stacking.md b/sips/sip-032/sip-032-improved-stacking.md index 399254086..c7bb2aed8 100644 --- a/sips/sip-032/sip-032-improved-stacking.md +++ b/sips/sip-032/sip-032-improved-stacking.md @@ -10,7 +10,7 @@ **Consideration:** Technical -**Type:** Consensus +**Type:** Consensus (hard fork) **Status:** Draft From aa838212cacff15fb2f00ef2235685a336adf850 Mon Sep 17 00:00:00 2001 From: Friedger Date: Mon, 15 Sep 2025 23:16:26 +0200 Subject: [PATCH 20/22] Update sips/sip-032/sip-032-improved-stacking.md Co-authored-by: wileyj <2847772+wileyj@users.noreply.github.com> --- sips/sip-032/sip-032-improved-stacking.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sips/sip-032/sip-032-improved-stacking.md b/sips/sip-032/sip-032-improved-stacking.md index c7bb2aed8..d1c04c340 100644 --- a/sips/sip-032/sip-032-improved-stacking.md +++ b/sips/sip-032/sip-032-improved-stacking.md @@ -22,7 +22,7 @@ **Discussions-To:** -- [Stacks Forum Discussions](https://forum.stacks.org/t/remove-cool-down-cycle-in-stacking/17899) +- https://forum.stacks.org/t/remove-cool-down-cycle-in-stacking/17899 # Abstract From 02a49101f808ac01579e9ee69efef0d56dfbf451 Mon Sep 17 00:00:00 2001 From: friedger Date: Thu, 25 Sep 2025 10:03:04 +0200 Subject: [PATCH 21/22] fix: clarify use of maximum allowed amount to stack --- sips/sip-032/sip-032-improved-stacking.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/sips/sip-032/sip-032-improved-stacking.md b/sips/sip-032/sip-032-improved-stacking.md index 399254086..6f0297c35 100644 --- a/sips/sip-032/sip-032-improved-stacking.md +++ b/sips/sip-032/sip-032-improved-stacking.md @@ -152,11 +152,11 @@ The amount of stacked STX does not decrease during the automatic extension. If t When signers verify and accept proposed blocks by miners, their voting power corresponds to the amount of stacked Stacks tokens (see SIP-021). The new stacking process changes the delegation flow as follows: -- `delegate-stx` shall be renamed to `designate`. The function takes the arguments: `amount`, `signature`, optional bitcoin `block-height` defining the end of stacking and auto extending, optional `pox-addr` defining that pox-address that the signer must use, optional `max-amount`. The `amount` defines how many Stacks tokens are locked immediately. The `max-amount` defines the maximum of Stacks tokens that can be locked in the future through auto extending. If provided the minimum of the user's stx balance and `max-amount` is locked. If omitted, the whole user's balance is locked. Users can use sponsored transactions to call revoke-delegate-stx in case there is no unlocked stx in the account. The argument `signature` is a signature of the signer indicating that the signer accepted the delegation of voting power. The signing follows the structured message signing with the parameters and topic `designate` as message. The public key of the signature can be used to identify the signer similar to the Stacks address of the pool operator in the previous PoX design. +- `delegate-stx` shall be renamed to `designate`. The function takes the arguments: `amount`, `signature`, optional bitcoin `block-height` defining the end of stacking and auto extending, optional `pox-addr` defining that pox-address that the signer must use, optional `amount-allowance`. The `amount` defines how many Stacks tokens are locked immediately. The `amount-allowance` defines the maximum of Stacks tokens that can be locked in the future through auto extending. If provided, the minimum of the user's stx balance and `amount-allowance` is locked. If omitted, the `amount` is used as `amount-allowance`. Users can use sponsored transactions to call revoke-delegate-stx in case there is no unlocked stx in the account. The argument `signature` is a signature of the signer indicating that the signer accepted the delegation of voting power. The signing follows the structured message signing with the parameters and topic `designate` as message. The public key of the signature can be used to identify the signer similar to the Stacks address of the pool operator in the previous PoX design. - `revoke-delegate-stx` shall be renamed to `revoke-designation`. After calling this function, auto extension is stopped and Stacks tokens are unlocked for the user at the end of the current cycle. If a signer does not aggregate enough Stacks tokens to receive at least one reward slot (or does not commit at all) then the user's Stacks token are unlocked immediately through this call. -- `delegate-increase` is replaced by `update-max-amount`. It sets max-amount to the new value. This value is applied when the user's designation is extended for the next cycle. The amount can be smaller than the currently locked amount. As tokens are only locked for 1 cycle at a time, handling decreasing is now easy enough in comparison to the previous system with locking periods of up to 12 cycles. +- `delegate-increase` is replaced by `update-amount-allowance`. It sets `amount-allowance` to the new value. This value is applied when the user's designation is extended for the next cycle. The amount can be smaller than the currently locked amount. As tokens are only locked for 1 cycle at a time, handling decreasing is now easy enough in comparison to the previous system with locking periods of up to 12 cycles. - `delegate-extend` is removed because the locking period is automatically extended each cycle. @@ -174,7 +174,7 @@ Furthermore, a function `get-stacker-info` shall return for the given principal - the accepted stacked amount by the signer and the cycle of acceptance `(optional {amount: uint), cycle: uint})` - the current stacked amount `uint` -- the current max-amount `(optional uint)` +- the current amount-allowance `(optional uint)` When stackers designate the first time, the function `get-stacker-info` the accepted stacked amount is `none`. From b22221e938de1945817c95d5db1de69484f84977 Mon Sep 17 00:00:00 2001 From: friedger Date: Tue, 14 Apr 2026 08:59:40 +0200 Subject: [PATCH 22/22] feat: add method signatures --- sips/sip-032/sip-032-improved-stacking.md | 82 ++++++++++++++++++++++- 1 file changed, 81 insertions(+), 1 deletion(-) diff --git a/sips/sip-032/sip-032-improved-stacking.md b/sips/sip-032/sip-032-improved-stacking.md index 24409c689..8ae421d13 100644 --- a/sips/sip-032/sip-032-improved-stacking.md +++ b/sips/sip-032/sip-032-improved-stacking.md @@ -152,7 +152,7 @@ The amount of stacked STX does not decrease during the automatic extension. If t When signers verify and accept proposed blocks by miners, their voting power corresponds to the amount of stacked Stacks tokens (see SIP-021). The new stacking process changes the delegation flow as follows: -- `delegate-stx` shall be renamed to `designate`. The function takes the arguments: `amount`, `signature`, optional bitcoin `block-height` defining the end of stacking and auto extending, optional `pox-addr` defining that pox-address that the signer must use, optional `amount-allowance`. The `amount` defines how many Stacks tokens are locked immediately. The `amount-allowance` defines the maximum of Stacks tokens that can be locked in the future through auto extending. If provided, the minimum of the user's stx balance and `amount-allowance` is locked. If omitted, the `amount` is used as `amount-allowance`. Users can use sponsored transactions to call revoke-delegate-stx in case there is no unlocked stx in the account. The argument `signature` is a signature of the signer indicating that the signer accepted the delegation of voting power. The signing follows the structured message signing with the parameters and topic `designate` as message. The public key of the signature can be used to identify the signer similar to the Stacks address of the pool operator in the previous PoX design. +- `delegate-stx` shall be renamed to `designate`. The function takes the arguments: `amount`, `signature`, optional bitcoin `end-burn-block-height` defining the end of stacking and auto extending, optional `pox-addr` defining that pox-address that the signer must use, optional `amount-allowance`. The `amount` defines how many Stacks tokens are locked immediately. The `amount-allowance` defines the maximum of Stacks tokens that can be locked in the future through auto extending. If provided, the minimum of the user's stx balance and `amount-allowance` is locked. If omitted, the `amount` is used as `amount-allowance`. Users can use sponsored transactions to call revoke-delegate-stx in case there is no unlocked stx in the account. The argument `signature` is a signature of the signer indicating that the signer accepted the delegation of voting power. The signing follows the structured message signing with the parameters and topic `designate` as message. The public key of the signature can be used to identify the signer similar to the Stacks address of the pool operator in the previous PoX design. - `revoke-delegate-stx` shall be renamed to `revoke-designation`. After calling this function, auto extension is stopped and Stacks tokens are unlocked for the user at the end of the current cycle. If a signer does not aggregate enough Stacks tokens to receive at least one reward slot (or does not commit at all) then the user's Stacks token are unlocked immediately through this call. @@ -209,10 +209,90 @@ Note, for solo Stackers these keys could be theoretically just a single key. For The voting power for a signer is the sum of the accepted stacked STX, not the sum of the currently stacked STX because users can have descreased the stacking amount. +## Stacking flow + +### Typical stacking flow +1. Signer published PoX address to use for the next cycles (until changed). +2. Stacker requests signature from Signer A. +3. Stacker stacks STX with that signature. +4. Auto-extend is performed by nodes. + +### Change of Signer +Stacker wants to change the Signer B, after the typical stacking flow. + +5. Stacker requests signature from Signer B. +6. Stacker stacks STX with the new signature, STX are locked +7. Auto-extend changes the voting power of Stacker from Signer A to signer B. + +### Change of PoX address +Signer wants to change the PoX address. + +5. Signer A publishes new PoX address to use for the next cycles (until changed). +6. Stackers who requested a specific PoX address to be used, need to re-stack. +7. Auto-extend uses the new PoX address for all stackers who did not provide a PoX address during stacking or did not re-stack with the new PoX address. + +### Increase of Stacking Amount +Stacker wants to increase the stacking amount. + +5. Stacker requests signature from Signer A +6. Stacker increases the STX stacked, higher amount is locked. +7. Auto-extend uses the new amount for Signer A + +### Decrease of Stacking Amount +Stacker wants to decrease stacking amount. + +5. Stacker indicates reduction of STX stacked. +6. Auto-extend uses the new lower amount, unlocks the difference to the previous amount. + +### Revoke Stacking +5. Stacker revokes stacking +6. Auto-extend excludes Stacker for next cycle and unlocks Stacker's STX + +### Exclude Stacker +Signer wants to exclude a stacker + +5. Signer A revokes for Stacker +6. Auto-exend excluses Stacker for next cycle and unlocks Stacker's STX + +### Split Rewards to Different PoX Addresses +Signer wants to receive parts of the rewards at PoX address A and parts at PoX address B. + +1. Signer A publishes a list PoX addresses. +2. Stacker chooses on PoX address, requests a signature from Ssigner A. +3. Stacker stacks STX. +4. Auto-extend uses the corresponding amounts per PoX address, if the sum is above the amount required for 1 reward slot. + ## Transition to PoX-5 A new PoX contract requires that all stacked Stacks tokens are unlocked and Stackers need to lock their Stacks token again using the new PoX-5 contract. The process shall be similar to the previous upgrades of the PoX contract. The PoX-4 contract shall be deactivated and the PoX-5 contract shall be activated at the beginning of epoch 3.3. All locked Stacks tokens shall be unlocked automatically one block after the beginning of epoch 3.3. Nevertheless, these tokens will earn rewards until the end of the cycle. +## Method Signatures PoX-5 + +``` +(define-public + (designate + ;; The amount of uSTX to be locked immediately + (amount uint) + ;; Reward cycle + (reward-cycle uint) + ;; Signature of the signer indicating that the signer accepted the delegation of voting power + (signer-sig (buff 65)) + ;; + (signer-key (buff 33)) + ;; + (max-amount uint) + ;; + (auth-id uint) + ;; The Bitcoin block height at which this designation ends, if any. + (end-burn-block-height (optional uint)) + ;; PoX address that the signer must use, to which PoX yield accrues + (pox-addr (optional { version: (buff 1), hashbytes: (buff 32) })) + ;; Maximum amount of uSTX that can be locked through future auto-extending + (max-amount (optional uint)) + ) +) +``` + ## Reference implementation A reference implementation for creating signatures is available at ... (TODO). Note, that signers (or previously pool operators) no longer extend the locking period for each Stacker on-chain, instead signers provide a signature for each Stacker off-chain.