From 9ce4bb0b16fa1e2f37d2d3e749fcbfcbf7ea4c84 Mon Sep 17 00:00:00 2001 From: yjkellyjoo <34478004+yjkellyjoo@users.noreply.github.com> Date: Fri, 16 Oct 2026 06:13:13 +0000 Subject: [PATCH 1/8] chore: update OpenAPI specs and version refs to Bee v2.8.3 --- docs/bee/installation/build-from-source.md | 4 +- docs/bee/installation/docker.md | 14 ++-- docs/bee/installation/quick-start.md | 12 +-- docs/bee/installation/shell-script.md | 6 +- docs/bee/working-with-bee/bee-api.md | 2 +- docs/bee/working-with-bee/staking.md | 4 +- openapi/Swarm.yaml | 68 +++++++++++++---- openapi/SwarmCommon.yaml | 87 ++++++++++++++++++++++ 8 files changed, 162 insertions(+), 35 deletions(-) diff --git a/docs/bee/installation/build-from-source.md b/docs/bee/installation/build-from-source.md index 509ead9ba..2bf286369 100644 --- a/docs/bee/installation/build-from-source.md +++ b/docs/bee/installation/build-from-source.md @@ -32,7 +32,7 @@ Prerequisites for installing directly from source are: 3. Checkout the required version: ```bash - git checkout v2.8.2 + git checkout v2.8.3 ``` 4. Build the binary: @@ -48,7 +48,7 @@ Prerequisites for installing directly from source are: ``` ``` - 2.8.2 + 2.8.3 ``` 6. (optional) Additionally, you may also like to move the Bee binary to somewhere in your `$PATH` diff --git a/docs/bee/installation/docker.md b/docs/bee/installation/docker.md index 5b9f12384..efcfc742d 100644 --- a/docs/bee/installation/docker.md +++ b/docs/bee/installation/docker.md @@ -7,9 +7,9 @@ description: Provides comprehensive steps for deploying Bee nodes using Docker c The following is a guide for installing a Bee node using Docker. Docker images for Bee are hosted at [Docker Hub](https://hub.docker.com/r/ethersphere/bee). Using Docker to operate your Bee node offers many benefits, such as ease of deployment and consistency across environments. :::caution -In the examples below we specify the exact image version as 2.8.2. +In the examples below we specify the exact image version as 2.8.3. It's recommended to only use the exact version number tags. -Make sure to check that you're on the latest version of Bee by reviewing the tags for Bee on [Docker Hub](https://hub.docker.com/r/ethersphere/bee/tags), and replace 2.8.2 in the commands below if there is a newer full release. +Make sure to check that you're on the latest version of Bee by reviewing the tags for Bee on [Docker Hub](https://hub.docker.com/r/ethersphere/bee/tags), and replace 2.8.3 in the commands below if there is a newer full release. ::: :::warning @@ -39,13 +39,13 @@ docker run -d --name bee-1 \ -e BEE_PASSWORD="flummoxedgranitecarrot" \ -e BEE_BLOCKCHAIN_RPC_ENDPOINT="https://xdai.fairdatasociety.org" \ -v bee-1:/home/bee/.bee \ - ethersphere/bee:2.8.2 start + ethersphere/bee:2.8.3 start ``` Here is the same command in a single line in case you run into issues with the line breaks in the command above: ```bash -docker run -d --name bee-1 --restart always -p 127.0.0.1:1633:1633 -p 1634:1634 -e BEE_API_ADDR=":1633" -e BEE_FULL_NODE="true" -e BEE_SWAP_ENABLE="true" -e BEE_PASSWORD="flummoxedgranitecarrot" -e BEE_BLOCKCHAIN_RPC_ENDPOINT="https://xdai.fairdatasociety.org" -v bee-1:/home/bee/.bee ethersphere/bee:2.8.2 start +docker run -d --name bee-1 --restart always -p 127.0.0.1:1633:1633 -p 1634:1634 -e BEE_API_ADDR=":1633" -e BEE_FULL_NODE="true" -e BEE_SWAP_ENABLE="true" -e BEE_PASSWORD="flummoxedgranitecarrot" -e BEE_BLOCKCHAIN_RPC_ENDPOINT="https://xdai.fairdatasociety.org" -v bee-1:/home/bee/.bee ethersphere/bee:2.8.3 start ``` #### Command explained: @@ -61,7 +61,7 @@ docker run -d --name bee-1 --restart always -p 127.0.0.1:1633:1633 -p 1634:1634 - **`-e BEE_PASSWORD="flummoxedgranitecarrot"`**: Sets the keystore password, make sure to replace with your own. - **`-e BEE_BLOCKCHAIN_RPC_ENDPOINT="https://xdai.fairdatasociety.org"`**: Connects to the Gnosis Chain. - **`-v bee-1:/home/bee/.bee`**: Persists node data in the `bee-1` volume. -- **`ethersphere/bee:2.8.2 start`**: Runs Bee version 2.8.2 and starts the node. +- **`ethersphere/bee:2.8.3 start`**: Runs Bee version 2.8.3 and starts the node. This setup runs the Bee node in a container, with full node functionality, SWAP enabled, and connections to the Gnosis blockchain for chequebook and postage stamp management, while persisting its data using a volume. @@ -77,7 +77,7 @@ If everything is set up correctly, you should see your Bee node listed: ```bash CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -37f4ad8b4060 ethersphere/bee:2.8.2 "bee start" 6 seconds ago Up 5 seconds 127.0.0.1:1633->1633/tcp, 0.0.0.0:1634->1634/tcp, :::1634->1634/tcp bee-1 +37f4ad8b4060 ethersphere/bee:2.8.3 "bee start" 6 seconds ago Up 5 seconds 127.0.0.1:1633->1633/tcp, 0.0.0.0:1634->1634/tcp, :::1634->1634/tcp bee-1 ``` And check the logs: @@ -170,7 +170,7 @@ damage to hardware or loss of funds associated with the Ethereum account connect No developers or entity involved will be liable for any claims and damages associated with your use, inability to use, or your interaction with other nodes or the software. -"time"="2026-07-07 16:52:59.641444" "level"="info" "logger"="node" "msg"="bee version" "version"="2.8.2-7e703f49" +"time"="2026-07-07 16:52:59.641444" "level"="info" "logger"="node" "msg"="bee version" "version"="2.8.3-7e703f49" "time"="2026-07-07 16:52:59.793257" "level"="info" "logger"="node" "msg"="swarm public key" "public_key"="02d8d7e1ca6b3b43653ae27e35a375dd74e3ce2f40587fd264bc7268ed918650ab" "time"="2026-07-07 16:53:00.087534" "level"="info" "logger"="node" "msg"="pss public key" "public_key"="02aaae4ede42f47f48aa5182df4b94039ca71254f44ebc5383d5a67f71fe7e6156" diff --git a/docs/bee/installation/quick-start.md b/docs/bee/installation/quick-start.md index 2db5b7cf5..fa7168898 100644 --- a/docs/bee/installation/quick-start.md +++ b/docs/bee/installation/quick-start.md @@ -30,17 +30,17 @@ Run the shell script using `curl` or `wget`: :::tip -We specify `TAG=v2.8.2` to indicate which Bee version to install. You can find available versions in the ["releases" section](https://github.com/ethersphere/bee/releases) of the Bee GitHub repo. +We specify `TAG=v2.8.3` to indicate which Bee version to install. You can find available versions in the ["releases" section](https://github.com/ethersphere/bee/releases) of the Bee GitHub repo. ::: ```bash -curl -s https://raw.githubusercontent.com/ethersphere/bee/master/install.sh | TAG=v2.8.2 bash +curl -s https://raw.githubusercontent.com/ethersphere/bee/master/install.sh | TAG=v2.8.3 bash ``` OR ```bash -wget -q -O - https://raw.githubusercontent.com/ethersphere/bee/master/install.sh | TAG=v2.8.2 bash +wget -q -O - https://raw.githubusercontent.com/ethersphere/bee/master/install.sh | TAG=v2.8.3 bash ``` Verify installation: @@ -109,7 +109,7 @@ damage to hardware or loss of funds associated with the Ethereum account connect No developers or entity involved will be liable for any claims and damages associated with your use, inability to use, or your interaction with other nodes or the software. -"time"="2026-07-07 16:52:59.641444" "level"="info" "logger"="node" "msg"="bee version" "version"="2.8.2-7e703f49" +"time"="2026-07-07 16:52:59.641444" "level"="info" "logger"="node" "msg"="bee version" "version"="2.8.3-7e703f49" "time"="2026-07-07 16:52:59.793257" "level"="info" "logger"="node" "msg"="swarm public key" "public_key"="02d8d7e1ca6b3b43653ae27e35a375dd74e3ce2f40587fd264bc7268ed918650ab" "time"="2026-07-07 16:53:00.087534" "level"="info" "logger"="node" "msg"="pss public key" "public_key"="02aaae4ede42f47f48aa5182df4b94039ca71254f44ebc5383d5a67f71fe7e6156" @@ -181,7 +181,7 @@ swarm-cli status ```bash Bee API: http://localhost:1633 [OK] -Version: 2.8.2-7e703f49 +Version: 2.8.3-7e703f49 Mode: light Chainsync @@ -211,7 +211,7 @@ swarm-cli status ```bash Bee API: http://localhost:1633 [OK] -Version: 2.8.2-7e703f49 +Version: 2.8.3-7e703f49 Mode: light Chainsync diff --git a/docs/bee/installation/shell-script.md b/docs/bee/installation/shell-script.md index c582c4485..a7d5c49b7 100644 --- a/docs/bee/installation/shell-script.md +++ b/docs/bee/installation/shell-script.md @@ -26,7 +26,7 @@ Below is a step-by-step guide for installing and setting up your Bee node using Run the install shell script using either `curl` or `wget`: :::caution -In the example below, the version is specified using `TAG=v2.8.2`. Check the [latest Bee releases](https://github.com/ethersphere/bee/tags) and if needed, update the command to install the most recent version (note that in tags containing "rc," the abbreviation stands for "release candidate", and these versions should be used for testing purposes only). +In the example below, the version is specified using `TAG=v2.8.3`. Check the [latest Bee releases](https://github.com/ethersphere/bee/tags) and if needed, update the command to install the most recent version (note that in tags containing "rc," the abbreviation stands for "release candidate", and these versions should be used for testing purposes only). ::: :::info @@ -59,7 +59,7 @@ values={[ ```bash -curl -s https://raw.githubusercontent.com/ethersphere/bee/master/install.sh | TAG=v2.8.2 bash +curl -s https://raw.githubusercontent.com/ethersphere/bee/master/install.sh | TAG=v2.8.3 bash ``` @@ -67,7 +67,7 @@ curl -s https://raw.githubusercontent.com/ethersphere/bee/master/install.sh | TA **wget** ```bash -wget -q -O - https://raw.githubusercontent.com/ethersphere/bee/master/install.sh | TAG=v2.8.2 bash +wget -q -O - https://raw.githubusercontent.com/ethersphere/bee/master/install.sh | TAG=v2.8.3 bash ``` diff --git a/docs/bee/working-with-bee/bee-api.md b/docs/bee/working-with-bee/bee-api.md index 487e26225..5deae1172 100644 --- a/docs/bee/working-with-bee/bee-api.md +++ b/docs/bee/working-with-bee/bee-api.md @@ -584,7 +584,7 @@ curl -s http://localhost:1633/health | jq ```json { "status": "ok", - "version": "2.8.2-7e703f49", + "version": "2.8.3-7e703f49", "apiVersion": "8.1.1" } ``` diff --git a/docs/bee/working-with-bee/staking.md b/docs/bee/working-with-bee/staking.md index ada58d3e9..5ae270814 100644 --- a/docs/bee/working-with-bee/staking.md +++ b/docs/bee/working-with-bee/staking.md @@ -481,12 +481,12 @@ curl -s http://localhost:1633/health | jq To confirm a successful update, check that the value for the `"version"` field in the results corresponds to the version number of the [latest](https://github.com/ethersphere/bee/releases/latest) Bee release. -For example, if the latest version was 2.8.2, it would look like this: +For example, if the latest version was 2.8.3, it would look like this: ```json { "status": "ok", - "version": "2.8.2-7e703f49", + "version": "2.8.3-7e703f49", "apiVersion": "8.1.1" } ``` diff --git a/openapi/Swarm.yaml b/openapi/Swarm.yaml index c320410b4..d10c998ec 100644 --- a/openapi/Swarm.yaml +++ b/openapi/Swarm.yaml @@ -1,7 +1,7 @@ openapi: 3.0.3 info: - version: 8.1.1 + version: 8.2.1 title: Bee API description: "API endpoints for interacting with the Swarm network, supporting file operations, messaging, and node management" @@ -345,8 +345,6 @@ paths: $ref: "SwarmCommon.yaml#/components/parameters/SwarmPostageBatchId" required: false - $ref: "SwarmCommon.yaml#/components/parameters/SwarmPostageStamp" - - $ref: "SwarmCommon.yaml#/components/parameters/SwarmAct" - - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActHistoryAddress" requestBody: description: Chunk binary data containing at least 8 bytes. content: @@ -362,8 +360,6 @@ paths: description: Tag UID from the request `swarm-tag` header if provided. schema: $ref: "SwarmCommon.yaml#/components/schemas/Uid" - "swarm-act-history-address": - $ref: "SwarmCommon.yaml#/components/headers/SwarmActHistoryAddress" content: application/json: schema: @@ -971,9 +967,23 @@ paths: $ref: "SwarmCommon.yaml#/components/schemas/SwarmAddress" required: true description: "Single Owner Chunk address (which may have multiple payloads)" - responses: - "200": - description: Establishes a WebSocket subscription for incoming messages on the Single Owner Chunk address + - $ref: "SwarmCommon.yaml#/components/parameters/SwarmSocFieldsParameter" + - $ref: "SwarmCommon.yaml#/components/parameters/SwarmCacheWrappedChunkParameter" + - $ref: "SwarmCommon.yaml#/components/parameters/SwarmSocFieldsQueryParameter" + - $ref: "SwarmCommon.yaml#/components/parameters/SwarmCacheWrappedChunkQueryParameter" + responses: + "200": + description: > + Establishes a WebSocket subscription for incoming messages on the + Single Owner Chunk address. Each message is the binary serialization + of the Single Owner Chunk fields requested through the + swarm-soc-fields header or query parameter (defaults to the wrapped + chunk payload). + Pending messages are buffered per subscription up to a fixed limit; + a client that does not keep up with the incoming rate misses the + oldest of them, as they are discarded in favor of the newest ones. + "400": + $ref: "SwarmCommon.yaml#/components/responses/400" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: @@ -1013,8 +1023,6 @@ paths: - $ref: "SwarmCommon.yaml#/components/parameters/SwarmTagParameter" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmPinParameter" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmDeferredUpload" - - $ref: "SwarmCommon.yaml#/components/parameters/SwarmAct" - - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActHistoryAddress" requestBody: required: true description: The SOC binary data, composed of the span (8 bytes) and up to 4KB of payload. @@ -1035,8 +1043,6 @@ paths: description: Tag UID, returned when an upload session is in use (either because `swarm-tag` was supplied, `swarm-deferred-upload` requested deferred mode, or `swarm-pin` was set). schema: $ref: "SwarmCommon.yaml#/components/schemas/Uid" - "swarm-act-history-address": - $ref: "SwarmCommon.yaml#/components/headers/SwarmActHistoryAddress" "400": $ref: "SwarmCommon.yaml#/components/responses/400" "401": @@ -2444,6 +2450,36 @@ paths: $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response + patch: + summary: Enable or disable participation in new redistribution rounds + description: > + Controls whether the node will commit in a new redistribution round. + Sampling still runs while disabled so that a later re-enable can commit + in the following commit phase. Disabling does not abort an in-flight + commit and does not skip reveal or claim for a round that already committed. + Re-enabling during a commit phase that was already skipped does not retry + that round. After a node restart participation is enabled again. + tags: + - RedistributionState + requestBody: + required: true + content: + application/json: + schema: + $ref: "SwarmCommon.yaml#/components/schemas/RedistributionEnableRequest" + responses: + "200": + description: Participation flag updated + content: + application/json: + schema: + $ref: "SwarmCommon.yaml#/components/schemas/RedistributionEnableResponse" + "400": + $ref: "SwarmCommon.yaml#/components/responses/400" + "500": + $ref: "SwarmCommon.yaml#/components/responses/500" + default: + description: Default response "/wallet": get: summary: Get wallet balance for BZZ and xDAI @@ -2558,7 +2594,11 @@ paths: schema: $ref: "SwarmCommon.yaml#/components/schemas/StakeTransactionResponse" "400": - $ref: "SwarmCommon.yaml#/components/responses/400" + description: Deposit amount is below the required minimum. + content: + application/json: + schema: + $ref: "SwarmCommon.yaml#/components/schemas/StakeDepositErrorResponse" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: @@ -2567,7 +2607,7 @@ paths: "/stake": get: summary: Get the staked amount. - description: This endpoint fetches the total staked amount from the blockchain. + description: This endpoint fetches the total staked amount and the minimum additional deposit from the blockchain. The first deposit is at least 10 BZZ times 2^height. Subsequent deposits are at least 1 PLUR, or more if the price oracle has increased since the last deposit. tags: - Staking responses: diff --git a/openapi/SwarmCommon.yaml b/openapi/SwarmCommon.yaml index ffcbbac3b..8b4c15c63 100644 --- a/openapi/SwarmCommon.yaml +++ b/openapi/SwarmCommon.yaml @@ -681,6 +681,21 @@ components: properties: stakedAmount: $ref: "#/components/schemas/BigInt" + minimumDeposit: + description: Absent (null) when the stake is known but the price oracle cannot be read, so the commitment gap is unknown. + nullable: true + allOf: + - $ref: "#/components/schemas/BigInt" + + StakeDepositErrorResponse: + type: object + properties: + code: + type: integer + message: + type: string + minimumDeposit: + $ref: "#/components/schemas/BigInt" GetWithdrawableResponse: type: object @@ -825,6 +840,15 @@ components: type: boolean isHealthy: type: boolean + enabled: + type: boolean + description: Whether the node will commit in new redistribution rounds. Sampling still runs while disabled. A disabled node still finishes a round that already has an on-chain commit. Re-enabling during a commit phase that was already skipped does not retry that round. + hasCommittedThisRound: + type: boolean + description: Whether the node has already committed in the current round. Operators can shut down without freeze risk when this is false. + hasRevealedThisRound: + type: boolean + description: Whether the node has revealed in the current round. After a commit, the node must reveal before it is safe to shut down. phase: type: string round: @@ -846,6 +870,21 @@ components: fees: $ref: "#/components/schemas/BigInt" + RedistributionEnableRequest: + type: object + required: + - enabled + properties: + enabled: + type: boolean + description: Whether the node should commit in new redistribution rounds. Sampling still runs while disabled. + + RedistributionEnableResponse: + type: object + properties: + enabled: + type: boolean + PendingTransactionsResponse: type: object properties: @@ -1144,6 +1183,54 @@ components: required: false description: Associate upload with an existing Tag UID + SwarmSocFieldsParameter: + in: header + name: swarm-soc-fields + schema: + type: string + default: "payload" + required: false + description: > + Comma separated list of Single Owner Chunk fields to be serialized and + channeled on every incoming GSOC message, in the given order. Allowed + values are: address, recoveredPubKey, identifier, signature, + wrappedAddress, span, payload. When omitted it defaults to "payload". + In order to have random access on the response bytes define payload + as the last field in the list since it has variable length. + + SwarmCacheWrappedChunkParameter: + in: header + name: swarm-cache-wrapped-chunk + schema: + type: boolean + required: false + description: > + Indicates whether the wrapped chunk of every incoming GSOC message should + be cached locally so that it can be resolved through the bytes endpoint + (useful when the single owner chunk wraps a root chunk larger than 4KB). + + SwarmSocFieldsQueryParameter: + in: query + name: swarm-soc-fields + schema: + type: string + required: false + description: > + Same as the swarm-soc-fields header, for clients that cannot set request + headers (e.g. browser WebSocket). Takes precedence over the header when + both are given. + + SwarmCacheWrappedChunkQueryParameter: + in: query + name: swarm-cache-wrapped-chunk + schema: + type: boolean + required: false + description: > + Same as the swarm-cache-wrapped-chunk header, for clients that cannot set + request headers (e.g. browser WebSocket). Takes precedence over the header + when both are given. + SwarmPinParameter: in: header name: swarm-pin From 9370c9f44b6f1ec26a327dbba9e36a9a4d0b270d Mon Sep 17 00:00:00 2001 From: Yejin Kelly Joo Date: Tue, 20 Oct 2026 21:06:14 +0900 Subject: [PATCH 2/8] docs(staking): document Bee v2.8.3 staking and redistribution changes - add minimumDeposit to the /stake docs and the insufficient stake error - add enabled, hasCommittedThisRound and hasRevealedThisRound to /redistributionstate - add Pause Redistribution Participation section Co-Authored-By: Claude Sonnet 5.5 Signed-off-by: Yejin Kelly Joo --- docs/bee/working-with-bee/bee-api.md | 8 ++- docs/bee/working-with-bee/staking.md | 81 ++++++++++++++++++++++++++-- 2 files changed, 85 insertions(+), 4 deletions(-) diff --git a/docs/bee/working-with-bee/bee-api.md b/docs/bee/working-with-bee/bee-api.md index 5deae1172..19319cd3a 100644 --- a/docs/bee/working-with-bee/bee-api.md +++ b/docs/bee/working-with-bee/bee-api.md @@ -305,7 +305,10 @@ curl -s http://localhost:1633/redistributionstate | jq "block": 32354719, "reward": "1804537795127017472", "fees": "592679945236926714", - "isHealthy": true + "isHealthy": true, + "enabled": true, + "hasCommittedThisRound": false, + "hasRevealedThisRound": false } ``` @@ -324,6 +327,9 @@ curl -s http://localhost:1633/redistributionstate | jq * `"reward"` - The total all-time reward in PLUR earned by your node. * `"fees"` - The total amount in fees paid by your node denominated in xDAI wei. * `"isHealthy"` - a check of whether your node’s storage radius is the same as the most common radius from among its peer nodes +* `"enabled"` - Whether your node will commit in new rounds of the redistribution game. From Bee v2.8.3, you can pause and resume participation with a `PATCH` request to this endpoint (see [Pause Redistribution Participation](./staking.md#pause-redistribution-participation)). +* `"hasCommittedThisRound"` - Whether your node has committed in the current round. If this is `false`, you can shut down your node without the risk of being frozen. +* `"hasRevealedThisRound"` - Whether your node has revealed in the current round. After your node commits, it must reveal before it's safe to shut down. ### _/reservestate_ diff --git a/docs/bee/working-with-bee/staking.md b/docs/bee/working-with-bee/staking.md index 5ae270814..5b200dfe4 100644 --- a/docs/bee/working-with-bee/staking.md +++ b/docs/bee/working-with-bee/staking.md @@ -129,6 +129,35 @@ Only stake your xBZZ if you intend to participate as a full node, as withdrawals - A [high-performance RPC endpoint](./configuration.md#setting-blockchain-rpc-endpoint) connection to Gnosis Chain. - A minimum of 10 xBZZ to be used as ***non-refundable*** stake (the requirement is increased if [reserve doubling](./staking.md#reserve-doubling) is used). +### Minimum Deposit + +Starting with Bee v2.8.3, the [`GET /stake`](/api/#tag/Staking/paths/~1stake/get) endpoint also returns `minimumDeposit`, the smallest amount in [PLUR](./../../references/glossary.md#plur) that your node can deposit as its next stake: + +```bash +curl -s http://localhost:1633/stake | jq +``` + +```json +{ + "stakedAmount": "100000000000000000", + "minimumDeposit": "1" +} +``` + +- For a node's first deposit, the minimum is 10 xBZZ, or 20 xBZZ with [reserve doubling](#reserve-doubling). +- For later deposits, the minimum is 1 PLUR, unless your node needs more to keep its committed stake from decreasing after the storage price has increased, or to meet the 20 xBZZ total with reserve doubling. +- `minimumDeposit` is `null` when Bee can't read the current storage price from the price oracle. + +If you try to stake less than the minimum, `POST /stake/{amount}` returns HTTP 400 with the required amount: + +```json +{ + "code": 400, + "message": "insufficient stake amount", + "minimumDeposit": "100000000000000000" +} +``` + ### Check Status @@ -152,7 +181,10 @@ curl -X GET http://localhost:1633/redistributionstate | jq "lastFrozenRound": 0, "block": 26800488, "reward": "10479124611072000", - "fees": "30166618102500000" + "fees": "30166618102500000", + "enabled": true, + "hasCommittedThisRound": false, + "hasRevealedThisRound": false } ``` * `"minimumFunds": ` - The minimum xDAI needed to play a single round of the redistribution game (the unit is 1e-18 xDAI). @@ -167,10 +199,14 @@ curl -X GET http://localhost:1633/redistributionstate | jq * `"block": ` - Gnosis block of the current redistribution game. * `"reward": ` - Record of total reward received in [PLUR](./../../references/glossary.md#plur). * `"fees": ` - Record of total spent in 1E-18 xDAI on all redistribution related transactions. +* `"enabled": ` - Whether the node will commit in new rounds of the redistribution game. See [Pause Redistribution Participation](#pause-redistribution-participation). +* `"hasCommittedThisRound": ` - Whether the node has committed in the current round. +* `"hasRevealedThisRound": ` - Whether the node has revealed in the current round. :::warning Do not shut down or update your node during an active redistribution round as it may cause them to lose out on winnings or become frozen. To see if your node is playing the current round, check if `lastPlayedRound` equals `round` in the output from the [`/redistributionstate` endpoint](/api/#tag/RedistributionState/paths/~1redistributionstate/get). +From Bee v2.8.3, you can [pause participation](#pause-redistribution-participation) to find a safe moment to shut down. ::: You should also check the [`/status`](/api/#tag/Node-Status/paths/~1status/get) endpoint: @@ -203,6 +239,43 @@ curl -s http://localhost:1633/status | jq If your node is not operating properly such as getting frozen or not participating in any rounds, see the [troubleshooting section](#troubleshooting). ::: +### Pause Redistribution Participation + +Starting with Bee v2.8.3, you can stop a full node from committing in new redistribution rounds without restarting it, for example before planned maintenance. +Send a `PATCH` request to the [`/redistributionstate`](/api/#tag/RedistributionState) endpoint: + +```bash +curl -s -X PATCH http://localhost:1633/redistributionstate \ + -H "Content-Type: application/json" \ + -d '{"enabled": false}' | jq +``` + +```json +{ + "enabled": false +} +``` + +While participation is paused: + +- The node doesn't commit in new rounds, but it keeps calculating samples so that it can commit in the next commit phase after you resume. +- If the node already committed in the current round, it still reveals and claims for that round. +- Resuming during a commit phase that the node already skipped doesn't retry that round. +- Restarting the node resumes participation. + +To find a safe moment to shut down, pause participation, then check the `/redistributionstate` endpoint: + +- If `hasCommittedThisRound` is `false`, you can shut down without the risk of being frozen. +- If `hasCommittedThisRound` is `true`, wait until `hasRevealedThisRound` is `true` before you shut down. + +To resume participation, set `enabled` back to `true`: + +```bash +curl -s -X PATCH http://localhost:1633/redistributionstate \ + -H "Content-Type: application/json" \ + -d '{"enabled": true}' | jq +``` + ## Partial Stake Withdrawals @@ -269,7 +342,8 @@ curl -s http://localhost:1633/stake | jq ```bash { - "stakedAmount": "200000000000000000" + "stakedAmount": "200000000000000000", + "minimumDeposit": "1" } ``` @@ -517,7 +591,8 @@ The expected output after staking the minimum of 10 xBZZ: ```bash { - "stakedAmount": "100000000000000000" + "stakedAmount": "100000000000000000", + "minimumDeposit": "1" } ``` From a7c796951619a71290fd77c28d716017901fb8db Mon Sep 17 00:00:00 2001 From: Yejin Kelly Joo Date: Tue, 20 Oct 2026 21:06:14 +0900 Subject: [PATCH 3/8] docs(config): add postage-sync-block-range and new gas limit default - add postage-sync-block-range flag, config entry and section - change gas-limit-fallback default from 500000 to 900000 Co-Authored-By: Claude Sonnet 5.5 Signed-off-by: Yejin Kelly Joo --- docs/bee/working-with-bee/configuration.md | 23 ++++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-) diff --git a/docs/bee/working-with-bee/configuration.md b/docs/bee/working-with-bee/configuration.md index 4695c9b8d..66e6d0437 100644 --- a/docs/bee/working-with-bee/configuration.md +++ b/docs/bee/working-with-bee/configuration.md @@ -81,7 +81,7 @@ Flags: --db-open-files-limit uint number of open files allowed by database (default 200) --db-write-buffer-size uint size of the database write buffer in bytes (default 33554432) --full-node cause the node to start in full mode - --gas-limit-fallback uint gas limit fallback when estimation fails for contract transactions (default 500000) + --gas-limit-fallback uint gas limit fallback when estimation fails for contract transactions (default 900000) -h, --help help for printconfig --mainnet triggers connect to main net bootnodes. (default true) --minimum-gas-tip-cap uint minimum gas tip cap in wei for transactions, 0 means use suggested gas tip cap @@ -101,6 +101,7 @@ Flags: --payment-tolerance-percent int excess debt above payment threshold in percentages where you disconnect from your peer (default 25) --postage-stamp-address string postage stamp contract address --postage-stamp-start-block uint postage stamp contract start block number + --postage-sync-block-range uint maximum number of blocks per eth_getLogs request when syncing postage contract events (default 1000) --pprof-mutex enable pprof mutex profile --pprof-profile enable pprof block profile --price-oracle-address string price oracle contract address @@ -217,7 +218,7 @@ db-write-buffer-size: "33554432" # cause the node to start in full mode full-node: false # gas limit fallback when estimation fails for contract transactions -gas-limit-fallback: "500000" +gas-limit-fallback: "900000" # help for printconfig help: false # triggers connect to main net bootnodes. @@ -256,6 +257,8 @@ payment-tolerance-percent: 25 postage-stamp-address: "" # postage stamp contract start block number postage-stamp-start-block: "0" +# maximum number of blocks per eth_getLogs request when syncing postage contract events +postage-sync-block-range: "1000" # enable pprof mutex profile pprof-mutex: false # enable pprof block profile @@ -618,6 +621,22 @@ block-sync-interval: 10 The equivalent flag is `--block-sync-interval` and the environment variable is `BEE_BLOCK_SYNC_INTERVAL`. This is especially useful for operators on paid or rate-limited RPC providers who want to lower request volume. +### Postage sync block range + +Bee syncs postage stamp contract events by requesting logs from your RPC endpoint in fixed block ranges. +Starting with Bee v2.8.3, the `postage-sync-block-range` option sets the maximum number of blocks in each `eth_getLogs` request: + +```yaml +# bee.yaml +postage-sync-block-range: 1000 +``` + +- The default is `1000`, which works with RPC endpoints that limit log requests to 1000 blocks, such as Nethermind 2.0.0 and later with default settings. +- If your RPC endpoint allows wider ranges, a higher value lets your node catch up with the chain in fewer requests. +- `0` falls back to the default. + +The equivalent flag is `--postage-sync-block-range` and the environment variable is `BEE_POSTAGE_SYNC_BLOCK_RANGE`. + ## SIMD hashing (Optional) Bee can use a hardware-accelerated (SIMD) implementation of its chunk hasher, a frequent and CPU-intensive operation. From 33d61171994e12dd84fc0ac9bd07d3d186fd5afb Mon Sep 17 00:00:00 2001 From: Yejin Kelly Joo Date: Tue, 20 Oct 2026 21:06:14 +0900 Subject: [PATCH 4/8] docs(act): note ACT is unsupported on /chunks and /soc - add warning that Swarm-Act is no longer accepted on /chunks and /soc as of Bee v2.8.3 Co-Authored-By: Claude Sonnet 5.5 Signed-off-by: Yejin Kelly Joo --- docs/develop/access-control.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/develop/access-control.md b/docs/develop/access-control.md index 5169d5d33..e70bc3bb0 100644 --- a/docs/develop/access-control.md +++ b/docs/develop/access-control.md @@ -11,6 +11,13 @@ This is guide contains a detailed explanation of how to use the ACT feature, but In this section we'll provide information on how to use the **swarm-cli** to upload, download data with ACT or update the grantee list. +:::warning +ACT is not supported on the `/chunks` and `/soc` endpoints. +As of Bee v2.8.3, these endpoints no longer accept the `Swarm-Act` header, because ACT never protected data correctly on them. +To upload content with ACT, use the `/bzz` or `/bytes` endpoint. +If you uploaded data to `/chunks` or `/soc` with ACT on an earlier Bee version, don't rely on it being access-controlled, and re-upload it through `/bzz` or `/bytes`. +::: + ## Upload Uploading data without ACT to the network remains unchanged. From 4407200b9478e0e2bd15f52f4a37e792b4f61452 Mon Sep 17 00:00:00 2001 From: Yejin Kelly Joo Date: Tue, 20 Oct 2026 21:06:14 +0900 Subject: [PATCH 5/8] docs(gsoc): add subscribing with the Bee API - document /gsoc/subscribe/{address} and the swarm-soc-fields and swarm-cache-wrapped-chunk options - add SOC field size table and browser WebSocket example - note the 256-message buffer per subscription Co-Authored-By: Claude Sonnet 5.5 Signed-off-by: Yejin Kelly Joo --- docs/develop/tools-and-features/gsoc.md | 47 +++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/docs/develop/tools-and-features/gsoc.md b/docs/develop/tools-and-features/gsoc.md index fc045e9a8..8eba01601 100644 --- a/docs/develop/tools-and-features/gsoc.md +++ b/docs/develop/tools-and-features/gsoc.md @@ -79,6 +79,53 @@ The `Bee.gsocSubscribe` method is used by the service node to establish a WebSoc 3. Incoming messages are processed by the `handler` function. 4. The function returns a `GsocSubscription` object with a `cancel` method to terminate the subscription. +## Subscribe with the Bee API + +You can also subscribe to a GSOC address directly through the `/gsoc/subscribe/{address}` WebSocket endpoint. +Bee sends each incoming GSOC message as one binary WebSocket message. + +Starting with Bee v2.8.3, two options control what each message contains. +Set them as request headers, or as query parameters for clients that can't set headers, such as a browser `WebSocket`. +If both are set, the query parameter takes precedence. + +| Option | Description | +|---|---| +| `swarm-soc-fields` | Comma-separated list of SOC fields to include in each message, in the given order. Defaults to `payload`. | +| `swarm-cache-wrapped-chunk` | When `true`, Bee caches the chunk wrapped in each incoming SOC, so you can retrieve it through the `/bytes` endpoint by its `wrappedAddress`. This is useful when the wrapped chunk is the root chunk of content larger than 4 KB. | + +Bee concatenates the requested fields in the order you list them: + +| Field | Size (bytes) | +|---|---| +| `address` | 32 | +| `recoveredPubKey` | 33 (compressed public key) | +| `identifier` | 32 | +| `signature` | 65 | +| `wrappedAddress` | 32 | +| `span` | 8 | +| `payload` | Up to 4096 | + +`payload` is the only field with a variable length, so list it last to read the other fields at fixed offsets. +For example, this browser subscription receives the identifier followed by the payload: + +```js +const ws = new WebSocket( + "ws://localhost:1633/gsoc/subscribe/?swarm-soc-fields=identifier,payload" +) +ws.binaryType = "arraybuffer" + +ws.onmessage = (event) => { + const bytes = new Uint8Array(event.data) + const identifier = bytes.slice(0, 32) + const payload = bytes.slice(32) +} +``` + +:::info +Bee buffers up to 256 pending messages per subscription. +If your client reads messages more slowly than they arrive, Bee discards the oldest pending messages in favor of the newest ones. +::: + ## Example Scripts The service node and writer node scripts below are a minimalistic example of how to use `bee-js` to set up a service node to listen for GSOC messages, and a writer node to send GSOC messages. From 0f5b9bc0e5d605fd215e0d5de793ae74369b83d0 Mon Sep 17 00:00:00 2001 From: Yejin Kelly Joo Date: Tue, 20 Oct 2026 21:06:14 +0900 Subject: [PATCH 6/8] docs(upgrade): update for Bee v2.8.3 - change non-disruptive upgrade and stepwise upgrade versions to v2.8.3 - add notice listing v2.8.3 changes that may affect setups - link to pausing redistribution participation in the shutdown warning Co-Authored-By: Claude Sonnet 5.5 Signed-off-by: Yejin Kelly Joo --- docs/bee/working-with-bee/upgrade.md | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/docs/bee/working-with-bee/upgrade.md b/docs/bee/working-with-bee/upgrade.md index ebc951672..9cbe5997b 100644 --- a/docs/bee/working-with-bee/upgrade.md +++ b/docs/bee/working-with-bee/upgrade.md @@ -12,6 +12,7 @@ Bee sure to [back up](./backups.md) your keys and [cash out your cheques](./cash :::warning Nodes should not be shut down or updated in the middle of a round they are playing in as it may cause them to lose out on winnings or become frozen. To see if your node is playing the current round, check if `lastPlayedRound` equals `round` in the output from the [`/redistributionstate` endpoint](/api/#tag/RedistributionState/paths/~1redistributionstate/get). See [staking section](./staking.md) for more information on staking and troubleshooting. +From Bee v2.8.3, you can [pause redistribution participation](./staking.md#pause-redistribution-participation) to find a safe moment to shut down. ::: @@ -23,19 +24,31 @@ The minimum supported version is currently **v2.8.0**, the release that introduc When upgrading across a breaking protocol change, do not skip the release that introduced it. Upgrade *through* that version so any one-time data migrations run while they still exist in the code, since Bee removes old migration and compatibility code once a version is no longer supported. -Bee v2.8.2 is **non-disruptive for nodes already on v2.8.0 or v2.8.1**: it makes no breaking p2p protocol changes, so you can upgrade in place using the steps below. +Bee v2.8.3 is **non-disruptive for nodes already on v2.8.0, v2.8.1, or v2.8.2**: it makes no breaking p2p protocol changes, so you can upgrade in place using the steps below. :::warning **If you are running Bee v2.6.0 or older:** Bee v2.8.1 removed the last of the v2.6.0 backward-compatibility code, so you cannot upgrade directly to v2.8.1 or later. -Either upgrade stepwise (**v2.6.0 → v2.8.0 → v2.8.2**) so the data migrations run, or reinstall the node fresh on v2.8.2. +Either upgrade stepwise (**v2.6.0 → v2.8.0 → v2.8.3**) so the data migrations run, or reinstall the node fresh on v2.8.3. ::: :::info -If you have tracing enabled, note that Bee v2.8.2 replaces Jaeger/OpenTracing with OpenTelemetry (OTLP export). +If you are upgrading from v2.8.1 or older with tracing enabled, note that Bee v2.8.2 replaced Jaeger/OpenTracing with OpenTelemetry (OTLP export). Point `tracing-endpoint` at an OTLP-capable collector before upgrading, and review the new tracing options in the [v2.8.2 release notes](https://github.com/ethersphere/bee/releases/tag/v2.8.2). With tracing disabled, nothing changes. ::: +:::info +Bee v2.8.3 includes these changes that may affect your setup: + +- **One-time reserve migration:** On first start, full nodes re-verify stored chunks that are not content-addressed and remove any that are invalid. +- **ACT on `/chunks` and `/soc`:** These endpoints no longer accept the `Swarm-Act` header. Use `/bzz` or `/bytes` for ACT uploads (see [Access Control](./../../develop/access-control.md)). +- **Connection metrics:** `bee_libp2p_created_connection_count` and `bee_libp2p_handled_connection_count` now have `transport` and `public` labels. Update dashboards that use `count(...)` on these metrics to use `sum by (...)` instead. +- **Gas limit fallback:** The `gas-limit-fallback` default has increased from 500000 to 900000. +- **Postage sync:** The new [`postage-sync-block-range`](./configuration.md#postage-sync-block-range) option limits each postage log request to 1000 blocks by default. + +See the [v2.8.3 release notes](https://github.com/ethersphere/bee/releases/tag/v2.8.3) for the full list of changes. +::: + ### Ubuntu / Debian From aa5d94e5689c79c053c7e025f6c50aea80e68482 Mon Sep 17 00:00:00 2001 From: Yejin Kelly Joo Date: Wed, 21 Oct 2026 23:51:07 +0900 Subject: [PATCH 7/8] fix(docs): use v2.8.3 commit and api version in sample output - replace v2.8.2 commit hash 7e703f49 with v2.8.3's 8e9bb914 in sample version strings - bump sample apiVersion from 8.1.1 to 8.2.1 to match openapi/Swarm.yaml Co-Authored-By: Claude Opus 5.5 Signed-off-by: Yejin Kelly Joo --- docs/bee/installation/docker.md | 2 +- docs/bee/installation/quick-start.md | 6 +++--- docs/bee/working-with-bee/bee-api.md | 4 ++-- docs/bee/working-with-bee/staking.md | 4 ++-- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/bee/installation/docker.md b/docs/bee/installation/docker.md index efcfc742d..838cfa563 100644 --- a/docs/bee/installation/docker.md +++ b/docs/bee/installation/docker.md @@ -170,7 +170,7 @@ damage to hardware or loss of funds associated with the Ethereum account connect No developers or entity involved will be liable for any claims and damages associated with your use, inability to use, or your interaction with other nodes or the software. -"time"="2026-07-07 16:52:59.641444" "level"="info" "logger"="node" "msg"="bee version" "version"="2.8.3-7e703f49" +"time"="2026-07-07 16:52:59.641444" "level"="info" "logger"="node" "msg"="bee version" "version"="2.8.3-8e9bb914" "time"="2026-07-07 16:52:59.793257" "level"="info" "logger"="node" "msg"="swarm public key" "public_key"="02d8d7e1ca6b3b43653ae27e35a375dd74e3ce2f40587fd264bc7268ed918650ab" "time"="2026-07-07 16:53:00.087534" "level"="info" "logger"="node" "msg"="pss public key" "public_key"="02aaae4ede42f47f48aa5182df4b94039ca71254f44ebc5383d5a67f71fe7e6156" diff --git a/docs/bee/installation/quick-start.md b/docs/bee/installation/quick-start.md index fa7168898..7ad46ae99 100644 --- a/docs/bee/installation/quick-start.md +++ b/docs/bee/installation/quick-start.md @@ -109,7 +109,7 @@ damage to hardware or loss of funds associated with the Ethereum account connect No developers or entity involved will be liable for any claims and damages associated with your use, inability to use, or your interaction with other nodes or the software. -"time"="2026-07-07 16:52:59.641444" "level"="info" "logger"="node" "msg"="bee version" "version"="2.8.3-7e703f49" +"time"="2026-07-07 16:52:59.641444" "level"="info" "logger"="node" "msg"="bee version" "version"="2.8.3-8e9bb914" "time"="2026-07-07 16:52:59.793257" "level"="info" "logger"="node" "msg"="swarm public key" "public_key"="02d8d7e1ca6b3b43653ae27e35a375dd74e3ce2f40587fd264bc7268ed918650ab" "time"="2026-07-07 16:53:00.087534" "level"="info" "logger"="node" "msg"="pss public key" "public_key"="02aaae4ede42f47f48aa5182df4b94039ca71254f44ebc5383d5a67f71fe7e6156" @@ -181,7 +181,7 @@ swarm-cli status ```bash Bee API: http://localhost:1633 [OK] -Version: 2.8.3-7e703f49 +Version: 2.8.3-8e9bb914 Mode: light Chainsync @@ -211,7 +211,7 @@ swarm-cli status ```bash Bee API: http://localhost:1633 [OK] -Version: 2.8.3-7e703f49 +Version: 2.8.3-8e9bb914 Mode: light Chainsync diff --git a/docs/bee/working-with-bee/bee-api.md b/docs/bee/working-with-bee/bee-api.md index 19319cd3a..292de350b 100644 --- a/docs/bee/working-with-bee/bee-api.md +++ b/docs/bee/working-with-bee/bee-api.md @@ -590,8 +590,8 @@ curl -s http://localhost:1633/health | jq ```json { "status": "ok", - "version": "2.8.3-7e703f49", - "apiVersion": "8.1.1" + "version": "2.8.3-8e9bb914", + "apiVersion": "8.2.1" } ``` diff --git a/docs/bee/working-with-bee/staking.md b/docs/bee/working-with-bee/staking.md index 5b200dfe4..7349b1ccb 100644 --- a/docs/bee/working-with-bee/staking.md +++ b/docs/bee/working-with-bee/staking.md @@ -560,8 +560,8 @@ For example, if the latest version was 2.8.3, it would look like this: ```json { "status": "ok", - "version": "2.8.3-7e703f49", - "apiVersion": "8.1.1" + "version": "2.8.3-8e9bb914", + "apiVersion": "8.2.1" } ``` From 9fb4a6b8482f676ddd3e31f5b757712086859527 Mon Sep 17 00:00:00 2001 From: Yejin Kelly Joo Date: Tue, 20 Oct 2026 21:06:14 +0900 Subject: [PATCH 8/8] docs(resources): update developer tools links - point fdp-play link to fairDataSociety/fdp-play - remove Cafe137/pss-gsoc-learning-material link Co-Authored-By: Claude Sonnet 5.5 Signed-off-by: Yejin Kelly Joo --- docs/develop/resources-md.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/develop/resources-md.md b/docs/develop/resources-md.md index 49381cf53..63511254c 100644 --- a/docs/develop/resources-md.md +++ b/docs/develop/resources-md.md @@ -98,8 +98,7 @@ description: A curated list of Swarm developer resources — docs, SDKs, example ### Developer Tools - [ethersphere/create-swarm-app ↗](https://github.com/ethersphere/create-swarm-app) — Boilerplate for building Swarm apps with JavaScript -- [Cafe137/fdp-play ↗](https://github.com/Cafe137/fdp-play) — Docker-based local Bee cluster and FDP dev environment -- [Cafe137/pss-gsoc-learning-material ↗](https://github.com/Cafe137/pss-gsoc-learning-material) — Learning material for PSS and GSOC primitives +- [fairDataSociety/fdp-play ↗](https://github.com/fairDataSociety/fdp-play) — Docker-based local Bee cluster and FDP dev environment - [examples/dynamic-content ↗](https://github.com/ethersphere/examples/tree/main/dynamic-content) — Content addressing and feeds, introduction example - [examples/filesystem ↗](https://github.com/ethersphere/examples/tree/main/filesystem) — Filesystem-style operations using bee-js - [agazso/swarm-cid-converter ↗](https://github.com/agazso/swarm-cid-converter) — Convert Swarm hashes or links to CID and vice versa