Skip to content

Commit c61d7ee

Browse files
werner-stacksgitbook-bot
werner-stacks
authored and
gitbook-bot
committed
GITBOOK: Add PoX-5 Upgrade Guide under Run a Signer
1 parent 53f0feb commit c61d7ee

2 files changed

Lines changed: 146 additions & 0 deletions

File tree

‎docs/operate/SUMMARY.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@
1616
* [Mine Mainnet Stacks Tokens](run-a-miner/mine-mainnet-stacks-tokens.md)
1717
* [Verify Miner](run-a-miner/verify-miner.md)
1818
* [Run a Signer](run-a-signer/README.md)
19+
* [PoX-5 Upgrade Guide](run-a-signer/pox-5-upgrade-guide.md)
1920
* [Signer Quickstart](run-a-signer/signer-quickstart.md)
2021
* [How to Read Signer Logs](run-a-signer/how-to-read-signer-logs.md)
2122
* [How to Monitor Signer](run-a-signer/how-to-monitor-signer.md)

‎docs/operate/run-a-signer/pox-5-upgrade-guide.md‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
---
2+
description: >-
3+
Mainnet upgrade guide for Stacks signer operators and stacking pool operators.
4+
Required release 4.0.1, activating at Bitcoin block 960,230.
5+
---
6+
7+
# PoX-5 Upgrade Guide
8+
9+
{% hint style="warning" %}
10+
Every signer operator must upgrade to `4.0.1` before activation at Bitcoin block `960,230` — approximately **July 30, 2026 AM UTC**. Nodes still on `3.4.x` diverge after activation.
11+
{% endhint %}
12+
13+
* **Audience:** Stacks signer operators, stacking pool operators, and STX staking services
14+
* **Required release:** `4.0.1`
15+
* **Activation:** Bitcoin block `960,230` — approximately July 30, 2026 AM UTC
16+
* **Last verified:** July 21, 2026
17+
18+
Pool operators must also deploy and register a signer-manager after activation, then coordinate affected stakers' move to PoX-5.
19+
20+
This guide covers STX staking under PoX-5. Native BTC bonds and whitelisted sBTC community pools follow separate integration paths.
21+
22+
### What you need to do
23+
24+
Use the table below to find the steps that apply to you. Some organizations have more than one role.
25+
26+
| If you... | Do this |
27+
| ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
28+
| Run `stacks-signer` | Upgrade to `4.0.1`, preserve the existing signer key, and verify signing health. |
29+
| Run the Stacks node your signer uses | Upgrade the node to `4.0.1` and verify chain-tip parity. |
30+
| Provide signing for a pool | Review its signer-manager, generate the one-time signer-key grant, and verify registration. |
31+
| Operate a stacking pool | Deploy and administer the pool's PoX-5 signer-manager, complete registration, and operate rewards. |
32+
| Stack STX | After the signer-manager is active, submit a PoX-5 `stake` transaction from the wallet that owns the STX. |
33+
34+
{% hint style="info" %}
35+
**Who deploys the signer-manager?** If you deploy a PoX-5 stacking pool, you must also deploy and administer its signer-manager contract. A signer-only provider reviews the contract and provides the signer-key grant, but does not deploy or administer the manager unless explicitly agreed.
36+
{% endhint %}
37+
38+
Existing PoX-4 positions do not become PoX-5 positions automatically. Affected users or protocol-controlled accounts must submit a new PoX-5 stake transaction.
39+
40+
### 1. Prepare before activation
41+
42+
#### Upgrade the signer and node
43+
44+
1. Upgrade `stacks-signer` to `4.0.1`. If you operate its Stacks node, upgrade that node to `4.0.1` as well. Nodes on `3.4.x` diverge after activation.
45+
2. Preserve the existing signer configuration, private key, and database. Do not rotate the signer key or create a fresh database solely for this upgrade.
46+
3. Restart and confirm the running version, node connectivity, expected signer slot, clean logs, and normal proposal and response activity.
47+
4. Monitor the activation window and the first post-fork blocks.
48+
49+
Official signer image:
50+
51+
```sh
52+
docker pull ghcr.io/stacks-network/stacks-signer:4.0.1@sha256:815b5518ec0f3a9b4c30d7fdca8f048a1fe8c263790ca65c5785e119b87d8590
53+
```
54+
55+
For a new signer, generate the key offline with `stacks-cli make_keychain` or your approved key-management process. Keep the private key on the signer host; registration uses only the 33-byte compressed public key.
56+
57+
#### Prepare the signer-manager
58+
59+
Before activation:
60+
61+
* review and test the mainnet-configured signer-manager source your organization intends to deploy;
62+
* record its expected canonical hash, contract name, and intended principal;
63+
* identify the temporary software wallet used for deployment and the cold wallet that will retain admin control;
64+
* rehearse deployment, admin rotation, grant, registration, staking, and reward claims on testnet; and
65+
* assign owners for rewards, accounting, monitoring, and support.
66+
67+
The signer-manager contract connects stake to the signer, validates new stake and updates, accounts for fees and rewards, and distributes rewards. Its code is immutable after deployment. Do not deploy an unmodified `stacks-core` test fixture: the PoX-5 and sBTC principals must match mainnet.
68+
69+
The reference signer-manager uses Clarity 6 and cannot be deployed on mainnet until Epoch 4.0 activates at block `960,230`.
70+
71+
### 2. Complete the on-chain setup after activation
72+
73+
{% hint style="warning" %}
74+
Use [Signer Sidekick](https://stx.fan/signer/) **only after PoX-5 is active on mainnet.** Signer Sidekick is one tool; the links below open its individual steps. Select **Mainnet** and confirm the network indicator on every page.
75+
{% endhint %}
76+
77+
| Step | Owner and action | Signer Sidekick page / signing identity |
78+
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
79+
| 1. Preflight | Confirm the network, PoX-5 contract, balance, cycle, and signer-set minimum. | [Preflight](https://stx.fan/signer/01-connect-preflight.html); connect the admin wallet, no transaction. |
80+
| 2. Deploy | Deploy the reviewed, mainnet-configured signer-manager source for your rollout. Continue only if its canonical hash matches the expected value. | [Deploy manager](https://stx.fan/signer/03-deploy-manager.html); temporary software wallet. |
81+
| 3. Secure admin | Add the cold admin, reconnect as that admin, then remove the temporary deployer. Never remove the last working admin. | Deploy page → **Admin rotation**; temporary wallet, then cold admin. |
82+
| 4. Generate grant | On the signer host, create the one-time signer-manager grant using a fresh `auth-id`. | Signer key; off-chain command below. |
83+
| 5. Register | Submit `register-self` and verify that the manager resolves to the expected signer public key. | [Register-self](https://stx.fan/signer/04-register-self.html); manager admin. |
84+
| 6. Stake | Lock STX for 1–96 cycles. The signer needs at least 50,000 STX in aggregate for the upcoming cycle; an individual stake may be smaller. | [Stake](https://stx.fan/signer/05-stake.html); staker wallet. |
85+
| 7. Verify | Confirm registration, grant validity, assigned STX, and eligibility for the upcoming cycle. | [Rewards + status](https://stx.fan/signer/06-rewards-status.html); read-only. |
86+
87+
Generate the grant on the signer host:
88+
89+
```sh
90+
stacks-signer generate-staking-signature \
91+
--config <config> \
92+
--signer-manager <manager-principal> \
93+
--auth-id <unique-id> \
94+
--json
95+
```
96+
97+
The `auth-id` must match the value used during registration. Do not accept stake until the signer-manager is registered and its signer-key grant is active; PoX-5 checks the grant on every new `stake` and `stake-update`.
98+
99+
### 3. Operate rewards
100+
101+
Under the reference manager, rewards accrue as sBTC. If a staker supplied a `pox-addr`, claiming initiates an sBTC withdrawal to that L1 Bitcoin address instead.
102+
103+
Reward distribution has two steps:
104+
105+
1. `claim-rewards` moves the signer's cycle rewards into the signer-manager.
106+
2. `claim-staker-rewards` distributes each staker's share after fees.
107+
108+
Both calls are permissionless, but the pool operator should own automation, monitoring, reconciliation, and failed-withdrawal handling. The public Signer Sidekick web workflow does not yet include claim or distribution pages; agree on the operating procedure before accepting partner or user stake.
109+
110+
PoX-5 removes the recurring PoX-4 aggregation commitment. Participation still depends on completing registration and staking before the applicable cycle deadline.
111+
112+
### Security and known limitations
113+
114+
{% hint style="danger" %}
115+
**Signer keys:** Never paste a signer private key or seed phrase into a website, chat, or email. Generate grants on the signer host.
116+
{% endhint %}
117+
118+
* **Ledger deployment:** Ledger Stacks App versions through `0.26.17` cannot sign the Clarity 6 deployment payload. Deploy with a temporary software wallet, then rotate admin control to the Ledger or cold wallet before registration or staking.
119+
* **Ledger staking:** Staking post-conditions require Stacks App `0.26.15` or newer. Use Deny mode with the staking post-condition. Use Allow mode only after your organization has reviewed and approved the loss of that transaction-level guardrail.
120+
* **Interim tooling:** Signer Sidekick is unofficial, interim tooling. A reference hash match verifies source identity, not production approval. Confirm the network, manager principal, wallet identity, and final on-chain result at every step.
121+
* **Transaction status:** A transaction ID confirms submission, not success. Verify that every deployment and contract call succeeded on-chain.
122+
* **Troubleshooting:** Preserve signer configuration, logs, and database state when escalating an issue. Do not reset `signer.sqlite` without a diagnosed failure and an approved recovery plan.
123+
124+
### Readiness confirmation
125+
126+
You are ready when:
127+
128+
* the signer and any operator-run node are on `4.0.1` and healthy;
129+
* the signer-manager is deployed after activation, its admin is secured, and its signer-key grant is active;
130+
* at least 50,000 STX is assigned to the signer for the upcoming cycle;
131+
* affected PoX-4 users or protocol accounts can complete a new PoX-5 stake; and
132+
* named owners are operating reward claims, accounting, monitoring, and support.
133+
134+
Provide Stacks with the running versions, signer-manager principal, registration and eligibility confirmation, and an activation-window contact.
135+
136+
### References
137+
138+
* [Stacks Core `4.0.1` release](https://github.com/stacks-network/stacks-core/releases/tag/4.0.1)
139+
* [SIP-045: PoX-5 Bitcoin Staking](https://github.com/stacksgov/sips/blob/main/sips/sip-045/sip-045-pox-5-bitcoin-staking.md)
140+
* [PoX-5 signer integration guide](https://pox-5.vercel.app/docs/development/advanced/signers)
141+
* [PoX-5 STX staking guide](https://pox-5.vercel.app/docs/development/solo-stx)
142+
* [PoX-5 reference signer-manager](https://github.com/stacks-network/stacks-core/blob/4.0.1/contrib/core-contract-tests/contracts/signer-manager.clar)
143+
* [PoX-5 contract](https://github.com/stacks-network/stacks-core/blob/4.0.1/stackslib/src/chainstate/stacks/boot/pox-5.clar)
144+
145+
For native BTC bonds or whitelisted sBTC community pools, use the separate [PoX-5 pools integration guide](https://pox-5.vercel.app/docs/development/pools).

0 commit comments

Comments
 (0)