Skip to content

Commit a7177aa

Browse files
NoahMaizelsNoahMaizels
authored
Merge pull request #743 from ethersphere/stake-migration
stake migration instructions
2 parents ddcf8f2 + c78097c commit a7177aa

File tree

3 files changed

+187
-89
lines changed

3 files changed

+187
-89
lines changed

‎docs/bee/working-with-bee/cashing-out.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ The token you desire to withdraw is specified in the path directly:
2828
```bash
2929
http://localhost:1633/wallet/withdraw/{coin}
3030
```
31-
For `coin`, you can use the value `NativeToken` for xDAI or `BZZ` for xBZZ.
31+
For `coin`, you can use the value `NativeToken` for xDAI or `BZZ` for xBZZ.
3232

3333
The `amount` query parameter is used to specify how much of the token you wish to withdraw. The value should be specified in the lowest denomination for each token (wei for xDAI and PLUR for xBZZ).
3434

‎docs/bee/working-with-bee/staking.md‎

Lines changed: 183 additions & 83 deletions
Original file line numberDiff line numberDiff line change
@@ -11,36 +11,93 @@ This guide will walk you through **staking xBZZ** and participating in the **red
1111
Staking requires a fully synced full node and a minimum of 10 xBZZ. See detailed [staking requirements](/docs/bee/working-with-bee/staking#requirements) below.
1212
:::
1313

14-
### Step 1: Fund Your Node with xDAI
14+
### Prerequisites
1515

16-
Your node needs **xDAI** to pay for transaction fees on Gnosis Chain.
16+
- A small amount of xDAI to pay transaction fees - ~0.01 xDAI is enough to start
17+
- At least 10 xBZZ to deposit as non-refundable stake
18+
- A fully synced full Bee node
1719

18-
Run this command to check how much is required:
20+
:::tip
21+
If you don't already have xDAI or xBZZ, you will need to [get some](/docs/bee/installation/fund-your-node#getting-tokens).
22+
:::
23+
24+
### Step 1: Fund Your Node with xDAI and xBZZ
25+
26+
Your node needs **xDAI** to pay for transaction fees on Gnosis Chain, and also needs **xBZZ** to deposit as stake.
27+
28+
First, find your node's address using:
1929

2030
```bash
21-
curl localhost:1633/redistributionstate | jq
31+
swarm-cli addresses
2232
```
23-
Check the `"minimumGasFunds"` field in the response.
33+
34+
This will print your node's various addresses. The one you need to fund is `Ethereum`
2435

2536
:::tip
26-
**Recommended:** Deposit at least **0.5 xDAI** to cover fees for the next few weeks/months of active staking.
37+
The `Ethereum` term here refers to an Ethereum style address on Gnosis Chain. Do not send funds to the address on the Ethereum chain itself.
2738
:::
2839

29-
### Step 2: Stake 10 xBZZ (or More)
40+
```bash
41+
Node Addresses
42+
------------------------------------------------------------------------------------------------------------------
43+
Ethereum: 9a73f283cd9211b96b5ec63f7a81a0ddc847cd93
44+
...
45+
```
46+
47+
Then, use the following command to check how much is required:
48+
49+
```bash
50+
swarm-cli status
51+
```
52+
53+
At the bottom of the results printed to the terminal you will find the `Redistribution` section. From there you will see the `Minimum gas funds` item. That value is the minimum amount required to participate in a *single redistribution round*.
54+
55+
:::tip
56+
If you plan on operating your node for an extended period, you will want to deposit quite a bit more than the minimum. You can start with **0.01 xDAI** to cover fees for the next few weeks/months of active staking, and then monitor actual usage and top-up when needed.
57+
:::
58+
59+
```
60+
Redistribution
61+
Reward: 0.0000000000000000
62+
Has sufficient funds: true
63+
Fully synced: true
64+
Frozen: false
65+
Last selected round: 263526
66+
Last played round: 0
67+
Last won round: 0
68+
Minimum gas funds: 0.000000000326250000
69+
```
70+
71+
Finally, send the required xDAI and xBZZ to the address you got from `swarm-cli addresses`.
72+
73+
You will need to send at least 10 xBZZ to get started staking.
74+
75+
:::tip
76+
Send **20 xBZZ** if using the [reserve doubling](#reserve-doubling) feature.
77+
:::
78+
79+
### Step 2: Stake xBZZ
3080

3181
Once your node has xDAI, stake **at least 10 xBZZ** (this is non-refundable).
3282

83+
You can use the following `swarm-cli` command to stake 10 xBZZ:
84+
85+
:::info
86+
The deposit amount is specified in [PLUR](/docs/references/glossary/#plur)
87+
:::
88+
3389
```bash
34-
curl -X POST localhost:1633/stake/100000000000000000
90+
swarm-cli stake --deposit 100000000000000000
3591
```
3692

37-
Confirm the staking transaction was successful using `GET /stake`:
93+
After a moment, the staking transaction will complete. Then you can check that the transaction was successful:
3894

3995
```bash
40-
curl localhost:1633/stake
96+
swarm-cli stake
4197
```
98+
4299
```bash
43-
{"stakedAmount":"100000000000000000"}
100+
Staked xBZZ: 10
44101
```
45102

46103
:::tip
@@ -53,18 +110,10 @@ After staking you should [check your node's status](/docs/bee/working-with-bee/s
53110

54111
### Step 4: Monitor & Maximize Rewards
55112

56-
✅ Use a stable Gnosis Chain [RPC endpoint](/docs/bee/working-with-bee/configuration#setting-blockchain-rpc-endpoint)
57-
✅ [Check `/redistributionstate`](/docs/bee/working-with-bee/staking#check-redistribution-status) to ensure `isFullySynced` and `hasSufficientFunds` are consistently `true`, and `isFrozen` is `false`.
58-
✅ [Check `/rchash`](/docs/bee/working-with-bee/bee-api#rchash) to ensure your node's performance is sufficient
59-
60-
61-
### Next Steps
62-
63-
* **🛠 Troubleshooting?** See the [Troubleshooting Guide](#troubleshooting).
64-
65-
* **💰 Want to maximize earnings?** Read [Maximizing Rewards](#maximize-rewards).
113+
✅ Make sure you are using a stable Gnosis Chain [RPC endpoint](/docs/bee/working-with-bee/configuration#setting-blockchain-rpc-endpoint).
114+
✅ [Check your node's status](/docs/bee/working-with-bee/staking#check-redistribution-status) to ensure it's operating properly.
115+
✅ [Check `/rchash`](/docs/bee/working-with-bee/bee-api#rchash) to ensure your node's performance is sufficient.
66116

67-
* **📖 Want to learn more?** Just continue reading through the rest of this page for an in-depth exploration of staking on Swarm.
68117

69118

70119
## Staking Overview
@@ -81,66 +130,7 @@ Only stake your xBZZ if you intend to participate as a full node, as withdrawals
81130
- A [high-performance RPC endpoint](/docs/bee/working-with-bee/configuration#setting-blockchain-rpc-endpoint) connection to Gnosis Chain.
82131
- A minimum of 10 xBZZ to be used as ***non-refundable*** stake (the requirement is increased if [reserve doubling](/docs/bee/working-with-bee/staking#reserve-doubling) is used).
83132

84-
### Add xDAI
85-
86-
Before staking, a node must first be funded with a small amount of xDAI to pay for Gnosis Chain transaction fees.
87-
88-
You can check exactly how much xDAI is required to get started with staking from the `/redistributionstate` endpoint:
89-
90-
```bash
91-
root@user-bee:~# curl localhost:1633/redistributionstate | jq
92-
```
93-
94-
```bash
95-
% Total % Received % Xferd Average Speed Time Time Time Current
96-
Dload Upload Total Spent Left Speed
97-
100 304 100 304 0 0 15258 0 --:--:-- --:--:-- --:--:-- 16000
98-
{
99-
"minimumGasFunds": "3750000030000000",
100-
"hasSufficientFunds": true,
101-
"isFrozen": false,
102-
"isFullySynced": false,
103-
"phase": "reveal",
104-
"round": 253280,
105-
"lastWonRound": 0,
106-
"lastPlayedRound": 0,
107-
"lastFrozenRound": 0,
108-
"lastSelectedRound": 0,
109-
"lastSampleDurationSeconds": 0,
110-
"block": 38498620,
111-
"reward": "0",
112-
"fees": "0",
113-
"isHealthy": true
114-
}
115-
```
116-
117-
The `"3750000030000000"` value listed for `"minimumGasFunds"` is the minimum required amount of xDAI denominated in Wei ($1 \text{xDAI} = 10^{18} \text{ Wei}$) required for staking. That is equivalent to 0.00375 xDAI. However, it's recommended to add more than just the minimum amount, since it will quickly be used up by storage incentives related transaction fees. As little as 0.5 xDAI should last for weeks or even months, as the average incentive-related transaction fee can be as low as 0.001 xDAI or less.
118-
119-
### Add xBZZ
120-
121-
Your node must be funded with a minimum of 10 xBZZ before performing the staking transaction. An additional 10 xBZZ is required if the [reserve doubling](/docs/bee/working-with-bee/staking#reserve-doubling) feature is used. If you don't already have xBZZ, you will need [get some](/docs/bee/installation/fund-your-node#how-to-get-xbzz) and transfer it to your [node's wallet](/docs/bee/installation/fund-your-node#funding-your-wallet).
122-
123-
### Deposit stake
124-
125-
Once your node has xDAI to pay for transaction fees, you can use the `POST /stake` endpoint to add the initial required minimum 10 xBZZ stake. The amount is denominated in [PLUR](/docs/references/glossary#plur), the smallest denomination of xBZZ:
126-
127-
```bash
128-
curl -X POST localhost:1633/stake/100000000000000000
129-
```
130-
131-
If the command executed successfully it returns a transaction hash that you can use to verify on a block explorer such as [GnosisScan](https://gnosisscan.io).
132-
133-
It is possible to deposit more by repeatedly using the command above.
134-
135-
You can also check the amount staked with a `GET /stake` request:
136-
137-
```bash
138-
curl localhost:1633/stake
139-
```
140-
141-
```bash
142-
{"stakedAmount":"100000000000000000"}
143-
```
133+
144134

145135
### Check Status
146136

@@ -438,7 +428,117 @@ Use the binary number you just copied and set it as a string value for the `targ
438428
## bee.yaml
439429
target-neighborhood: "01100011110"
440430
```
441-
431+
432+
## Stake Migration
433+
434+
If a new Bee release includes an updated staking contract, then you will be required to migrate your node's stake in order to continue normal operation. The stake migration process consists of the following steps:
435+
436+
1. Withdraw xBZZ
437+
2. Stop node
438+
3. Update and restart
439+
4. Re-stake to the new contract
440+
441+
442+
### Step 1: Withdraw xBZZ
443+
444+
When a new version of Bee is released with an updated staking contract, the previous staking contract will be disabled, and stake withdrawals will be enabled.
445+
446+
Once the contract is disabled, stake can be withdrawn by calling the `/stake` endpoint with the `DELETE` method:
447+
448+
```bash
449+
curl -X DELETE http://localhost:1633/stake
450+
```
451+
452+
This command will withdraw all stake from the node to the node’s Gnosis Chain address.
453+
454+
Confirm that the stake was withdrawn:
455+
456+
```bash
457+
curl -s http://localhost:1633/stake | jq
458+
```
459+
The value for `stakedAmount` should now be zero:
460+
```
461+
{
462+
"stakedAmount": "0"
463+
}
464+
```
465+
### Step 2: Stop node
466+
467+
This step will vary depending on how the node was set up:
468+
469+
```bash
470+
sudo systemctl stop bee
471+
```
472+
473+
or
474+
475+
```
476+
docker compose down
477+
```
478+
479+
or
480+
481+
```
482+
docker stop <container_name_or_id>
483+
```
484+
485+
etc.
486+
487+
### Step 3: Update and restart
488+
489+
:::danger
490+
Before every Bee client upgrade, it is best practice to ALWAYS take a full [backup](/docs/bee/working-with-bee/backups) of your node.
491+
:::
492+
493+
After withdrawing stake and stopping the node, update to the newest version of Bee. After updating, restart the node.
494+
495+
You can use the `/health` endpoint to confirm your current Bee version:
496+
497+
```bash
498+
curl -s http://localhost:1633/health | jq
499+
```
500+
501+
To confirm a successful update, check that the `version` number in the results corresponds to the [latest](https://github.com/ethersphere/bee/releases/tag/v2.5.0) Bee release:
502+
503+
```bash
504+
{
505+
"status": "ok",
506+
"version": "2.5.0-5ec231ba",
507+
"apiVersion": "7.3.0"
508+
}
509+
```
510+
511+
512+
### Step 4: Re-stake xBZZ
513+
514+
515+
After upgrading to the latest version and restarting, xBZZ should be re-staked into the new staking contract so that the node can continue to participate in the redistribution game.
516+
517+
To stake the minimum required 10 xBZZ:
518+
519+
:::tip
520+
Make sure to modify to the correct staking amount in case your node is using [reserve doubling](/docs/bee/working-with-bee/staking#reserve-doubling).
521+
:::
522+
523+
```bash
524+
curl -X POST localhost:1633/stake/100000000000000000
525+
```
526+
527+
Confirm that the staking transaction was successful:
528+
529+
```bash
530+
curl -s http://localhost:1633/stake | jq
531+
```
532+
The expected output after staking the minimum of 10 xBZZ:
533+
534+
```bash
535+
{
536+
"stakedAmount": "100000000000000000"
537+
}
538+
```
539+
540+
Congratulations! You have performed a successful stake migration and your node will now continue to operate as normal.
541+
442542
## Troubleshooting
443543

444544
In this section we cover several commonly seen issues encountered for staking nodes participating in the redistribution game. If you don't see your issue covered here or require additional guidance, check out the `#node-operators` [Discord channel](https://discord.com/channels/799027393297514537/811553590170353685) where you will find support from other node operators and community members.

‎docs/bee/working-with-bee/upgrade.md‎

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,7 @@ title: Upgrading Bee
33
id: upgrading-bee
44
---
55

6-
Keep a close eye on the[#bee-node-updates](https://discord.gg/vQcngMzZ9c) channel in our [Discord Server](https://discord.gg/wdghaQsGq5) for information on the latest software updates for Bee. It's very important to keep Bee up to date to benefit from security updates and ensure you are able to properly interact with the Swarm network. The [#node-operators](https://discord.com/channels/799027393297514537/811553590170353685) channel is another excellent resource for any of your questions regarding node operation.
7-
8-
## Upgrade Procedure Warnings
6+
It's very important to keep Bee up to date to benefit from security updates and ensure you are able to properly interact with the Swarm network. The [#node-operators](https://discord.com/channels/799027393297514537/811553590170353685) channel is an excellent resource for any of your questions regarding node operation.
97

108
:::warning
119
Bee sure to [back up](/docs/bee/working-with-bee/backups) your keys and [cash out your cheques](/docs/bee/working-with-bee/cashing-out) to ensure your xBZZ is safe before applying updates.
@@ -58,11 +56,11 @@ You may now start your node again:
5856
sudo systemctl start bee
5957
```
6058

61-
#### Manual Installations
59+
### Manual Installations
6260

6361
To upgrade your manual installation, simply stop Bee, replace the Bee binary and restart.
6462

65-
#### Docker
63+
### Docker
6664

6765
To upgrade your Docker installation, simply increment the version number in your configuration and restart.
6866

0 commit comments

Comments
 (0)