You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit b2b05b9
Browse filesBrowse the repository at this point in the historyBrowse files
Running an STX-only pool under PoX-5: what changed, how rewards reach your
4
-
members, and what you can leave to them.
3
+
Running an STX-only pool under PoX-5: what the ongoing job is, how rewards
4
+
reach your members, and what you can leave to them.
5
5
---
6
6
7
7
# Operate a Pool
8
8
9
-
Under PoX-4, operating a pool meant a recurring pile of transactions: accept each delegation, commit the aggregate, re-commit when it grew, attach a fresh signer signature every cycle. **None of that exists in PoX-5.**
10
-
11
9
After you have deployed a signer-manager contract and bound your signer key to it, your ongoing job is to **run the signer**. Everything else is optional.
12
10
13
11
{% hint style="info" %}
14
-
This page covers the **STX-only pool**: any signer-manager contract that multiple STX stakers stake to. The whitelisted community-tranche sBTC bond pool is a different model — there the pool contract is itself the staker via `register-for-bond`, and it must be on a bond's capacity allowlist. That path is documented separately.
12
+
This page covers the **STX-only pool**: any signer-manager contract that multiple STX stakers stake to. The whitelisted community-tranche sBTC bond pool works differently. There the pool contract is itself the staker via `register-for-bond`, and it must be on a bond's capacity allowlist. That path is documented separately.
15
13
{% endhint %}
16
14
17
-
### What you no longer do
18
-
19
-
***No `delegate-stack-stx`.** There is no per-staker acceptance transaction. Stakers stake to your contract directly.
20
-
***No `stack-aggregation-commit`.** Your signer-manager is added to a cycle's signer set _lazily_ — the first time its aggregate stake crosses the fixed 50,000 STX `SIGNER_SET_MIN_USTX` minimum, as a side effect of some staker's own `stake` or `stake-update` call.
21
-
***No per-cycle signer signature.** The signer key is bound to your manager once, via `grant-signer-key` and `register-signer`.
22
-
***No `stack-aggregation-increase`.** A staker who wants to add STX calls `stake-update` themselves.
23
-
24
-
The practical effect: there is no longer a deadline you can miss. Nothing lapses because you forgot to submit a transaction before the prepare phase.
25
-
26
15
### What you do
27
16
28
-
1.**Set up once**— see[Deploy a Signer Manager Contract](https://docs.stacks.co/operate/deploy-a-signer-manager-contract).
29
-
2.**Run the infrastructure** — a Bitcoin node, a Stacks node, and the signer software. See [Run a Signer](https://docs.stacks.co/operate/run-a-signer).
30
-
3.**Watch your threshold**— below.
31
-
4.**Optionally, claim rewards for your members**— below. This is the one genuinely discretionary part of the job.
17
+
1.**Set up once.**See[Deploy a Signer Manager Contract](https://docs.stacks.co/operate/deploy-a-signer-manager-contract).
18
+
2.**Run the infrastructure:** a Bitcoin node, a Stacks node, and the signer software. See [Run a Signer](https://docs.stacks.co/operate/run-a-signer).
19
+
3.**Watch your threshold.**Covered below.
20
+
4.**Claim rewards for your members, if you choose to.**Covered below. This is the one discretionary part of the job.
32
21
33
22
### Stakers come to you
34
23
35
-
There is no acceptance step. A staker calls `stake` naming your signer-manager's contract principal, choosing their own amount and a lock of 1 to 96 cycles. Your contract's `validate-stake!` callback is your only gate — allowlisting, minimums or other conditions are logic you write there, not something PoX-5 provides.
24
+
There is no acceptance step. A staker calls `stake` naming your signer-manager's contract principal, choosing their own amount and a lock of 1 to 96 cycles. Your contract's `validate-stake!` callback is your only gate. Allowlisting, minimums, and any other condition are logic you write there, rather than something PoX-5 provides.
36
25
37
-
One consequence worth planning for: **you cannot enforce a minimum stake on-chain** unless you build it into `validate-stake!`, because members stake directly rather than through you. If your concern is that very small positions aren't worth the payout cost, the lever is on the claiming side — only auto-claim above an amount you choose — not on the staking side.
26
+
Because members stake directly, you cannot enforce a minimum stake on-chain unless you build it into `validate-stake!`. If your concern is that very small positions cost more to pay out than they yield, the lever sits on the claiming side: auto-claim only above an amount you choose.
38
27
39
28
#### Knowing whether you are in the signer set
40
29
41
-
Two read-only calls, no dashboard required:
30
+
Check it with read-only calls, no dashboard required:
42
31
43
-
*`fetchAmountDelegatedForSigner`— total uSTX staked to your manager for a cycle, bonds and STX-only combined. Compare against `SIGNER_SET_MIN_USTX` (50,000 STX).
44
-
*`fetchSignerSetContainsForCycle({ signer, rewardCycle, network })`— whether you are actually in the set for that cycle.
32
+
*`fetchAmountDelegatedForSigner`returns the total uSTX staked to your manager for a cycle, bonds and STX-only combined. Compare it against `SIGNER_SET_MIN_USTX` (50,000 STX).
33
+
*`fetchSignerSetContainsForCycle({ signer, rewardCycle, network })`returns whether you are in the set for that cycle.
45
34
46
35
### How rewards reach your members
47
36
48
-
The path has changed shape, and it is worth understanding before you design your payout policy:
37
+
The path from miner to member:
49
38
50
39
```
51
40
BTC (miner commitments)
@@ -54,66 +43,75 @@ BTC (miner commitments)
54
43
→ member receives BTC or sBTC (claim-staker-rewards)
55
44
```
56
45
57
-
Two claims, and **both are permissionless**:
46
+
Both claimsare permissionless:
58
47
59
48
***`claim-rewards`** moves your signer's rewards for a cycle out of pox-5 and into your signer-manager.
60
49
***`claim-staker-rewards`** distributes one member's share, after your fee.
61
50
62
-
Anyone can call either. That is the point: your members are not dependent on you, and you are not a custodian at any stage.
51
+
Anyone can call either, so your members can recover their rewards without you, and you never hold their funds.
63
52
64
53
{% hint style="info" %}
65
-
The reference contract's staker claim covers **one member per call**. There is no batch claim in the contract today.
54
+
The reference contract's staker claim covers **one member per call**. The contract has no batch claim today.
66
55
{% endhint %}
67
56
68
-
#### BTC or sBTC — the member chooses
69
-
70
-
When a member stakes, they can attach calldata containing a Bitcoin payout address and a **maximum L1 fee in sats**. What they receive on claim depends on it:
| A BTC address, and the fee fits within their maximum |**Native BTC**, autobridged sBTC to L1 |
75
-
| No BTC address |**sBTC**, to the address they staked from (the default) |
76
-
| A BTC address, but the L1 fee would exceed their maximum |**sBTC** — the withdrawal falls back rather than failing |
77
-
78
-
The L1 fee comes out of that member's own yield, before payout. Your fee is taken earlier still, at the sBTC level — so choosing native BTC does not avoid it.
57
+
#### BTC or sBTC: the member chooses
79
58
80
-
You can make the Bitcoin address mandatory in your own interface, and you can recommend it. But a member who stakes to your contract through a different interface may not have supplied one, and **your process is identical either way** — you call the same claim, and they get whichever asset their calldata implies.
59
+
When a member stakes, they can attach calldata containing a Bitcoin payout address and a **maximum L1 fee in sats**. What they receive on claim follows from it:
81
60
82
-
For small positions sBTC is usually the better outcome anyway: it is cheaper to move and it avoids creating tiny UTXOs.
| A BTC address, and the fee fits within their maximum |**Native BTC**, withdrawn from sBTC to L1 |
64
+
| No BTC address |**sBTC**, to the address they staked from (the default) |
65
+
| A BTC address, but the L1 fee would exceed their maximum |**sBTC**. The withdrawal falls back rather than failing |
83
66
84
-
#### Why the single batched Bitcoin payoutis gone
67
+
The L1 fee comes out of that member's own yield, before payout. Your fee is taken earlier, at the sBTC level, so choosing native BTC does not avoid it.
85
68
86
-
Under PoX-4 an operator could receive BTC and fan it out in one large Bitcoin transaction. That is no longer possible, for three reasons worth being straight about:
69
+
You can make the Bitcoin address mandatory in your own interface, and you can recommend it. A member who stakes to your contract through a different interface may not have supplied one, and your process is identical either way: you call the same claim, and they receive whichever asset their calldata implies.
87
70
88
-
* Miner commitments now fund a **three-tranche waterfall** — bond participants are paid a target yield first, and STX-only stakers are paid from the remainder. Rewards are no longer a simple per-cycle BTC pot to divide.
89
-
* Settling in **sBTC on Stacks is cheaper** than settling on L1, and only the members who want L1 pay for L1.
90
-
* It requires **less trust**. Rewards never pass through an operator-controlled wallet. There is no window in which you hold members' funds.
71
+
Small positions do better in sBTC, which costs less to move and avoids creating tiny UTXOs.
91
72
92
73
### Claiming for members, or leaving it to them
93
74
94
-
Both are legitimate, and the choice is genuinely yours.
75
+
Both are legitimate.
95
76
96
-
**Claim for your members.** This is what they are used to from previous PoX regimes, and it is the friendlier default. You pay the Stacks transaction fees, and you may choose to sponsor them. You can claim on any cadence — every cycle, monthly, or only once accrued rewards are worth the cost.
77
+
**Claim for your members.** This matches what they are used to from previous PoX regimes. You pay the Stacks transaction fees, and you can sponsor them. You choose the cadence: every cycle, monthly, or once accrued rewards exceed the cost of claiming.
97
78
98
-
**Let members self-claim.**Then charge a lower fee and say so. Members can let sBTC accumulate in your contract for as long as they like — months, if they want — and claim once the amount justifies the L1 fee. That flexibility did not exist under fixed payout schedules.
79
+
**Let members self-claim.**Charge a lower fee and say so. Members can leave sBTC accumulating in your contract for monthsand claim once the amount justifies the L1 fee.
99
80
100
-
What you should not do is leave it ambiguous. Members who assume you are claiming for them will otherwise see nothing arrive.
81
+
State which one you do. Members who assume you are claiming for them will otherwise see nothing arrive.
101
82
102
83
{% hint style="warning" %}
103
-
If you do claim for members, communicate the practical minimum. A member with a very small position who elected a BTC payout may find the L1 fee consumes their yield — they will receive sBTC instead, which is the correct outcome but a surprising one if unexplained.
84
+
If you claim for members, publish the practical minimum. A member with a small position who elected a BTC payout receives sBTC instead once the L1 fee exceeds their maximum. That is the correct outcome, and it surprises people who have not been told.
104
85
{% endhint %}
105
86
106
87
### Your fee, and the ceiling on it
107
88
108
-
Fees are set and collected on your signer-manager — see[Take a Signer Fee](https://docs.stacks.co/operate/take-a-signer-fee).
89
+
Fees are set and collected on your signer-manager. See[Take a Signer Fee](https://docs.stacks.co/operate/take-a-signer-fee).
109
90
110
-
One point worth understanding before you deploy. The reference contract permits any fee from 0% to 99.99%, adjustable by an admin at any time. A contract deployed with a **lower hard ceiling** is a materially stronger commitment to members, because the ceiling is immutable code while the fee itself is a variable. A manager that can never charge more than 5% is a different proposition from one that merely charges 5% today.
91
+
The reference contract permits any fee from 0% to 99.99%, adjustable by an admin at any time. Deploying with a **lower hard ceiling** is a stronger commitment to members, because the ceiling is immutable code while the fee is a variable. A manager that can never charge more than 5% is a stronger guarantee than one that charges 5% today.
111
92
112
93
{% hint style="warning" %}
113
-
Changing to a different signer-manager contract later is not a migration. Members who staked to your original contract stay there until their locks end — so running both means running two signers and two Stacks nodes side by side. Decide before you accept stake.
94
+
Changing to a different signer-manager contract later is not a migration. Members who staked to your original contract stay there until their locks end, so running both means running two signers and two Stacks nodes side by side. Decide before you accept stake.
114
95
{% endhint %}
115
96
116
97
### Tooling
117
98
118
99
*[Leather](https://app.leather.io/staking) includes a claim function members can use themselves.
119
100
*[stx.fan/signer](https://stx.fan/signer/) is an open-source set of standalone tools, including one that indexes who has staked to your manager. The [source](https://github.com/no314/stx-fan/tree/main/signer) can be repurposed for your own interface.
101
+
102
+
### What changed from PoX-4
103
+
104
+
If you operated a pool before Epoch 4.0, these recurring transactions have gone:
105
+
106
+
***`delegate-stack-stx`.** There is no per-staker acceptance transaction. Stakers stake to your contract directly.
107
+
***`stack-aggregation-commit`.** Your signer-manager joins a cycle's signer set _lazily_, the first time its aggregate stake crosses the fixed 50,000 STX `SIGNER_SET_MIN_USTX` minimum, as a side effect of some staker's own `stake` or `stake-update` call.
108
+
***Per-cycle signer signatures.** The signer key binds to your manager once, via `grant-signer-key` and `register-signer`.
109
+
***`stack-aggregation-increase`.** A staker who wants to add STX calls `stake-update` themselves.
110
+
111
+
No deadline remains that you can miss. Nothing lapses because you forgot to submit a transaction before the prepare phase.
112
+
113
+
The single batched Bitcoin payout is gone too. Under PoX-4 an operator could receive BTC and fan it out in one large Bitcoin transaction. What replaced it:
114
+
115
+
* Miner commitments now fund a **three-tranche waterfall** across bond participants, STX-only stakers, and the reserve fund. Bond participants are paid their target yield first and STX-only stakers are paid from the cycle excess, so rewards are no longer a per-cycle BTC pot to divide.
116
+
* Settling in **sBTC on Stacks costs less** than settling on L1, and only the members who want L1 pay for L1.
117
+
* Rewards never pass through an operator-controlled wallet, so no window exists in which you hold members' funds.
0 commit comments