Bee v2.3.0 Guide
The Bee v2.3.0 guide is divided into two sections. Section 1 contains a detailed guide for upgrading from Bee v2.2.0 to v2.3.0. Section 2 contains instructions for enabling the new reserve doubling feature.
Section 1: Updating to 2.3.0
Since the v2.3.0 update includes a new staking contract, node operators must manually withdraw and re-stake their xBZZ before updating their nodes, as they did for the v2.2.0 update.
Info
Stake should be withdrawn before updating to 2.3.0.
Step 1.1: Withdraw xBZZ
When Bee v2.3.0 is released, the previous staking contract will be disabled, and stake withdrawals will be enabled.
Once the contract is disabled, stake can be withdrawn by calling the /stake endpoint with the DELETE method:
curl -X DELETE http://localhost:1633/stake
This command will withdraw all stake from the node to the node’s Gnosis Chain address.
Confirm that the stake was withdrawn:
curl -s http://localhost:1633/stake | jq
The value for stakedAmount should now be zero:
{
"stakedAmount": "0"
}
Step 1.2: Stop node
This step will vary depending on how the node was set up:
sudo systemctl stop bee
or
docker compose down
or
docker stop <container_name_or_id>
Step 1.3: Update to 2.3.0 & Restart
After withdrawing stake and stopping the node, update the node to v2.3.0. The installation method will vary depending on the node setup. After updating, restart the node.
The specific restart command will depend on your installation method (Docker, install script, package installer, etc.)
Danger
Before every Bee client upgrade, it is best practice to ALWAYS take a full backup of your node.
Step 1.4: Re-stake xBZZ
After upgrading to v2.3.0 and restarting, xBZZ should be restaked into the new staking contract so that the node can continue to participate in the redistribution game.
To stake the minimum required 10 xBZZ:
curl -X POST localhost:1633/stake/100000000000000000
Info
If using the reserve doubling feature, this is the point in the update process where additional stake can be added to meet the increased minimum stake requirement of 20 xBZZ. See next section for details.
Confirm that the staking transaction was successful:
curl -s http://localhost:1633/stake | jq
The expected output after staking the minimum of 10 xBZZ:
{
"stakedAmount": "100000000000000000"
}
The expected output after staking the increased minimum of 20 xBZZ required for the reserve doubling feature:
{
"stakedAmount": "200000000000000000"
}
The upgrade to 2.3.0 is now complete. From here on, the node will continue to participate in the redistribution game as normal.
Section 2: Reserve Doubling Guide
After updating your node to v2.3.0 and manually migrating your stake, you can enable the reserve doubling feature by following the steps below:
Step 2.1: Stake at least 20 xBZZ
Info
This step can also be done while manually restaking during step 1.4 of the v2.3.0 update process. See section above for details.
The reserve doubling feature comes with an increase in the required minimum xBZZ stake from 10 xBZZ to 20 xBZZ.
For doubling the reserve of a node which already has 10 xBZZ staked, simply stake an additional 10 xBZZ for a total of 20 xBZZ stake:
Info
As always, make sure that to properly convert the stake parameter to PLUR where 1 PLUR is equal to 1e-16 xBZZ. As in our example below, we have converted from 10 xBZZ to 100000000000000000 PLUR.
curl -X POST localhost:1633/stake/100000000000000000
Or for a node with zero staked xBZZ, the entire 20 xBZZ can be staked at once:
curl -X POST localhost:1633/stake/200000000000000000
We can use the GET /stake endpoint to confirm the total stake for our node:
curl -s http://localhost:1633/stake | jq
{
"stakedAmount": "200000000000000000"
}
Step 2.2: Set reserve-capacity-doubling to 1.
The reserve doubling feature can be enabled by setting the new reserve-capacity-doubling config option to 1 using the configuration method of your choice.
Step 2.3: Restart node
After ensuring the node has at least 20 xBZZ staked and the reserve-capacity-doubling option has been set to 1, restart the node.
After restarting your node, it should then begin syncing chunks from its sister neighborhood.
The /status/neighborhoods endpoint can be used to confirm that the node has doubled its reserve and is now syncing with its sister neighborhood:
{
"neighborhoods": [
{
"neighborhood": "01111101011",
"reserveSizeWithinRadius": 1148351,
"proximity": 10
},
{
"neighborhood": "01111101010",
"reserveSizeWithinRadius": 1147423,
"proximity": 11
}
]
}
The expected output should contain two neighborhoods, the node's original neighborhood along with its sister neighborhood.
We can also check the /status endpoint to confirm our node is syncing new chunks:
curl -s http://localhost:1633/status | jq
{
"overlay": "be177e61b13b1caa20690311a909bd674a3c1ef5f00d60414f261856a8ad5c30",
"proximity": 256,
"beeMode": "full",
"reserveSize": 4192792,
"reserveSizeWithinRadius": 2295023,
"pullsyncRate": 1.3033333333333332,
"storageRadius": 10,
"connectedPeers": 18,
"neighborhoodSize": 1,
"batchCommitment": 388104192,
"isReachable": true,
"lastSyncedBlock": 6982430
}
We can see that the pullsyncRate value is above zero, meaning that our node is currently syncing chunks, as expected.
Summary of Important Details
- The new
reserve-capacity-doubling Bee configuration option is used to double a node's reserve. The only valid values are 0 and 1.
- In order for a node to be able to participate in the redistribution game for both its own and its sister neighborhood, it must have a total of 20 xBZZ staked (10 xBZZ for each neighborhood).
- A doubling can be reversed by changing
reserve-capacity-doubling back to 0 and restarting the node. There is then a two round delay, after which the additional xBZZ over the minimum 10 xBZZ can then be withdrawn.
- After doubling, there will be a delay of two rounds of the redistribution game until the node is able to participate in the game.
Section 2A: Reserve Doubling Reversing & Withdrawable Stake
Due to certain implementation details, the order in which a node's reserve is doubled and then reversed can have an impact on the amount of withdrawable stake.
When doubling a node's reserve, stake should be added AFTER
setting reserve-capacity-doubling to 1. If instead, xBZZ is first staked with reserve-capacity-doubling set to 0, and the reserve is then doubled by increasing from 0 to 1 without the addition of more stake, this will prevent stake from being withdrawable when the doubling is reversed.
In order to maximize the amount of withdrawable stake after reversing a reserve doubling, make sure to follow the steps as described in the previous section in the same order as described.
How to free up withdrawable stake from a node with >= 20 xBZZ stake that currently has zero withdrawable stake
In the case that a node with 20 xBZZ stake was doubled directly by increasing reserve-capacity-doubling from 0 to 1, the surplus xBZZ over the minimum required 10 xBZZ cannot be made withdrawable by simply reversing the reserve-capacity-doubling from 1 back to 0.
In this case, you will need to first send a very small staking transaction of a single PLUR while reserve-capacity-doubling is set to 1, and after that, change reserve-capacity-doubling from 1 to 0. This works because every time any amount of stake is added, it forces to staking contract to redo its calculations.
The detailed steps are:
- Issue a staking transaction for 1 PLUR while
reserve-capacity-doubling is set to 1.curl -X POST localhost:1633/stake/1
- Stop node and set
reserve-capacity-doubling to 0.
- Restart node. The 10 xBZZ should now be withdrawable.
Section 3: Modification to /rchash endpoint
The /rchash endpoint can be used to generate a sample reserve hash and can be used for benchmarking a full node's processor speed. Previously, the endpoint would allow for random anchor parameters. In Bee v2.3.0, this has been modified to require that the anchor parameters match the prefix bits of the node up to the node's current storage depth.
In total, the /rchash endpoint has 3 parameters: storage depth, anchor_01, and anchor_02:
/rchash/{depth}/{anchor_01}/{anchor_02}
The current depth of a node can be found from the /reservestate endpoint:
curl -sX GET http://localhost:1633/reservestate | jq
{
"radius": 15,
"storageRadius": 11,
"commitment": 128332464128
}
The value for storageRadius is your node's storage depth. Use this value as the depth parameter for /rchash.
For the two anchor values of anchor_01 and anchor_02, they must contain a prefix hex string that matches your own node's bits up to the current storage depth. So for the current depth of 11, and with 4 bits represented by each hex digit, 3 hex digits is sufficient. We will use 4 just to make sure we are covered in the case of future depth increases. For a node with overlay address e59aa85b5899cd62d54bcd9bf511824883512f7151df196820c0e6d1a02d964b, we will use the first 4 hex digits of e59a:
curl -sX GET http://localhost:1633/rchash/11/e59a/e59a| jq
Conclusion
The reserve doubling feature introduced in the 2.3.0 update offers node operators tools for increasing the efficiency of their setup with minimal increase in overhead, improving the economic viability of running nodes. Node operators will have a new tool to optimize their nodes for both scalability and profitability. For more support and to stay up to date with all the latest Swarm news for node operators, make sure you're in the node operator Discord channel and follow us on Twitter.