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..838cfa563 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-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 2db5b7cf5..7ad46ae99 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-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.2-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.2-7e703f49 +Version: 2.8.3-8e9bb914 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..292de350b 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_ @@ -584,8 +590,8 @@ curl -s http://localhost:1633/health | jq ```json { "status": "ok", - "version": "2.8.2-7e703f49", - "apiVersion": "8.1.1" + "version": "2.8.3-8e9bb914", + "apiVersion": "8.2.1" } ``` 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. diff --git a/docs/bee/working-with-bee/staking.md b/docs/bee/working-with-bee/staking.md index ada58d3e9..7349b1ccb 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" } ``` @@ -481,13 +555,13 @@ 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", - "apiVersion": "8.1.1" + "version": "2.8.3-8e9bb914", + "apiVersion": "8.2.1" } ``` @@ -517,7 +591,8 @@ The expected output after staking the minimum of 10 xBZZ: ```bash { - "stakedAmount": "100000000000000000" + "stakedAmount": "100000000000000000", + "minimumDeposit": "1" } ``` 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 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. 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 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. 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