From 74d86c3e23a67338e58e04f78f84d98139d728b3 Mon Sep 17 00:00:00 2001 From: yjkellyjoo <34478004+yjkellyjoo@users.noreply.github.com> Date: Tue, 7 Jul 2026 07:12:05 +0000 Subject: [PATCH 1/3] chore: update OpenAPI specs and version refs to Bee v2.8.1 --- docs/bee/installation/build-from-source.md | 4 +- docs/bee/installation/docker.md | 14 +- docs/bee/installation/quick-start.md | 14 +- docs/bee/installation/shell-script.md | 6 +- docs/bee/working-with-bee/bee-api.md | 2 +- docs/bee/working-with-bee/configuration.md | 2 +- docs/bee/working-with-bee/staking.md | 4 +- openapi/Swarm.yaml | 540 ++++++++++++++------- openapi/SwarmCommon.yaml | 171 ++++--- 9 files changed, 492 insertions(+), 265 deletions(-) diff --git a/docs/bee/installation/build-from-source.md b/docs/bee/installation/build-from-source.md index d354d2690..182807f09 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.0 + git checkout v2.8.1 ``` 4. Build the binary: @@ -48,7 +48,7 @@ Prerequisites for installing directly from source are: ``` ``` - 2.8.0 + 2.8.1 ``` 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 41e278497..2f86a719d 100644 --- a/docs/bee/installation/docker.md +++ b/docs/bee/installation/docker.md @@ -9,7 +9,7 @@ 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.0. 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.0 in the commands below if there is a newer full release. +In the examples below we specify the exact image version as 2.8.1. 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.1 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.0 start + ethersphere/bee:2.8.1 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.0 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.1 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.0 start`**: Runs Bee version 2.8.0 and starts the node. +- **`ethersphere/bee:2.8.1 start`**: Runs Bee version 2.8.1 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.0 "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.1 "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,9 +170,9 @@ 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. -version: 2.8.0-06a0aca7 - planned to be supported until 11 December 2024, please follow https://ethswarm.org/ +version: 2.8.1-06a0aca7 - planned to be supported until 11 December 2024, please follow https://ethswarm.org/ -"time"="2024-09-24 22:21:04.543661" "level"="info" "logger"="node" "msg"="bee version" "version"="2.8.0-06a0aca7" +"time"="2024-09-24 22:21:04.543661" "level"="info" "logger"="node" "msg"="bee version" "version"="2.8.1-06a0aca7" "time"="2024-09-24 22:21:04.590823" "level"="info" "logger"="node" "msg"="swarm public key" "public_key"="02f0e59eafa3c5c06542c0a7a7fe9579c55a163cf1d28d9f6945a34469f88d1b2a" "time"="2024-09-24 22:21:04.686430" "level"="info" "logger"="node" "msg"="pss public key" "public_key"="02ea739530bbf48eed49197f21660f3b6564709b95bf558dc3b472688c34096418" "time"="2024-09-24 22:21:04.686464" "level"="info" "logger"="node" "msg"="using ethereum address" "address"="0x8288F1c8e3dE7c3bf42Ae67fa840EC61481D085e" diff --git a/docs/bee/installation/quick-start.md b/docs/bee/installation/quick-start.md index 888286068..972f7e86d 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.0` 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.1` 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.0 bash +curl -s https://raw.githubusercontent.com/ethersphere/bee/master/install.sh | TAG=v2.8.1 bash ``` OR ```bash -wget -q -O - https://raw.githubusercontent.com/ethersphere/bee/master/install.sh | TAG=v2.8.0 bash +wget -q -O - https://raw.githubusercontent.com/ethersphere/bee/master/install.sh | TAG=v2.8.1 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. -version: 2.8.0-390a402e - planned to be supported until 22 April 2025, please follow https://ethswarm.org/ +version: 2.8.1-390a402e - planned to be supported until 22 April 2025, please follow https://ethswarm.org/ "time"="2025-03-04 11:13:10.113050" "level"="info" "logger"="node" "msg"="bee version" "version"="2.6.0-390a402e" "time"="2025-03-04 11:13:10.164801" "level"="info" "logger"="node" "msg"="swarm public key" "public_key"="02b19880b8d024eac3bf8afa3fa85b31b72fcfd491cebc6af78ddd85ff97f65416" @@ -184,7 +184,7 @@ swarm-cli status ```bash Bee API: http://localhost:1633 [OK] -Version: 2.8.0-d0aa8b93 +Version: 2.8.1-d0aa8b93 Mode: light Chainsync @@ -214,7 +214,7 @@ swarm-cli status ```bash Bee API: http://localhost:1633 [OK] -Version: 2.8.0-d0aa8b93 +Version: 2.8.1-d0aa8b93 Mode: light Chainsync @@ -235,7 +235,7 @@ Total xBZZ: 0.0000000000000000 noah@NoahM16:~$ swarm-cli status Bee API: http://localhost:1633 [OK] -Version: 2.8.0-d0aa8b93 +Version: 2.8.1-d0aa8b93 Mode: light Chainsync diff --git a/docs/bee/installation/shell-script.md b/docs/bee/installation/shell-script.md index 7d9c19d42..4ac75723f 100644 --- a/docs/bee/installation/shell-script.md +++ b/docs/bee/installation/shell-script.md @@ -28,7 +28,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.0`. 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.1`. 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 @@ -61,7 +61,7 @@ values={[ ```bash -curl -s https://raw.githubusercontent.com/ethersphere/bee/master/install.sh | TAG=v2.8.0 bash +curl -s https://raw.githubusercontent.com/ethersphere/bee/master/install.sh | TAG=v2.8.1 bash ``` @@ -69,7 +69,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.0 bash +wget -q -O - https://raw.githubusercontent.com/ethersphere/bee/master/install.sh | TAG=v2.8.1 bash ``` diff --git a/docs/bee/working-with-bee/bee-api.md b/docs/bee/working-with-bee/bee-api.md index 8e00fca65..ccdc3f7f5 100644 --- a/docs/bee/working-with-bee/bee-api.md +++ b/docs/bee/working-with-bee/bee-api.md @@ -548,7 +548,7 @@ The `/health` endpoint provides a quick status check for your Bee node which sim ```bash { "status": "ok", - "version": "2.8.0-d0aa8b93", + "version": "2.8.1-d0aa8b93", "apiVersion": "7.3.0" } ``` diff --git a/docs/bee/working-with-bee/configuration.md b/docs/bee/working-with-bee/configuration.md index 092089532..34e81eef4 100644 --- a/docs/bee/working-with-bee/configuration.md +++ b/docs/bee/working-with-bee/configuration.md @@ -671,7 +671,7 @@ bee start \ ``` :::info -Chequebook verification is an optional defense layer for full node operators who want to avoid connecting to peers that do not maintain a sufficient chequebook balance. It was introduced in Bee v2.8.0. +Chequebook verification is an optional defense layer for full node operators who want to avoid connecting to peers that do not maintain a sufficient chequebook balance. It was introduced in Bee v2.8.1. ::: ## NAT address diff --git a/docs/bee/working-with-bee/staking.md b/docs/bee/working-with-bee/staking.md index 85f5403b4..ca2bc8177 100644 --- a/docs/bee/working-with-bee/staking.md +++ b/docs/bee/working-with-bee/staking.md @@ -479,12 +479,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.0, it would look like this: +For example, if the latest version was 2.8.1, it would look like this: ```bash { "status": "ok", - "version": "2.8.0-d0aa8b93", + "version": "2.8.1-d0aa8b93", "apiVersion": "7.3.0" } ``` diff --git a/openapi/Swarm.yaml b/openapi/Swarm.yaml index 04c17b0ee..a0b3e296b 100644 --- a/openapi/Swarm.yaml +++ b/openapi/Swarm.yaml @@ -1,12 +1,12 @@ openapi: 3.0.3 info: - version: 7.3.0 + version: 8.1.0 title: Bee API - description: "A list of the currently provided Interfaces to interact with the swarm, implementing file operations and sending messages" + description: "API endpoints for interacting with the Swarm network, supporting file operations, messaging, and node management" externalDocs: - description: Browse the documentation @ the Swarm Docs + description: Browse the documentation at the Swarm Docs url: "https://docs.ethswarm.org" servers: @@ -30,7 +30,7 @@ servers: paths: "/grantee": post: - summary: "Create grantee list" + summary: "Create a grantee list" tags: - ACT parameters: @@ -59,6 +59,11 @@ paths: $ref: "SwarmCommon.yaml#/components/parameters/SwarmActHistoryAddress" name: swarm-act-history-address required: false + - in: header + schema: + $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyLevelParameter" + name: swarm-redundancy-level + required: false requestBody: required: true content: @@ -77,18 +82,23 @@ paths: "500": $ref: "SwarmCommon.yaml#/components/responses/500" - "/grantee/{reference}": + "/grantee/{address}": get: - summary: "Get grantee list" + summary: "Get the grantee list" tags: - ACT parameters: - in: path - name: reference + name: address schema: $ref: "SwarmCommon.yaml#/components/schemas/SwarmEncryptedReference" required: true description: Grantee list reference + - in: header + schema: + $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyLevelParameter" + name: swarm-redundancy-level + required: false responses: "200": description: OK @@ -103,13 +113,13 @@ paths: "500": $ref: "SwarmCommon.yaml#/components/responses/500" patch: - summary: "Update grantee list" + summary: "Update the grantee list" description: "Add or remove grantees from an existing grantee list" tags: - ACT parameters: - in: path - name: reference + name: address schema: $ref: "SwarmCommon.yaml#/components/schemas/SwarmEncryptedReference" required: true @@ -139,6 +149,11 @@ paths: $ref: "SwarmCommon.yaml#/components/parameters/SwarmDeferredUpload" name: swarm-deferred-upload required: false + - in: header + schema: + $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyLevelParameter" + name: swarm-redundancy-level + required: false requestBody: required: true content: @@ -163,37 +178,14 @@ paths: tags: - Bytes parameters: - - in: header - schema: - $ref: "SwarmCommon.yaml#/components/parameters/SwarmPostageBatchId" - name: swarm-postage-batch-id - required: true - - in: header - schema: - $ref: "SwarmCommon.yaml#/components/parameters/SwarmTagParameter" - name: swarm-tag - required: false - - in: header - schema: - $ref: "SwarmCommon.yaml#/components/parameters/SwarmPinParameter" - name: swarm-pin - required: false - - in: header - schema: - $ref: "SwarmCommon.yaml#/components/parameters/SwarmDeferredUpload" - name: swarm-deferred-upload - required: false - - in: header - schema: - $ref: "SwarmCommon.yaml#/components/parameters/SwarmEncryptParameter" - name: swarm-encrypt - required: false - - in: header - schema: - $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyLevelParameter" - name: swarm-redundancy-level - required: false - + - $ref: "SwarmCommon.yaml#/components/parameters/SwarmPostageBatchId" + - $ref: "SwarmCommon.yaml#/components/parameters/SwarmTagParameter" + - $ref: "SwarmCommon.yaml#/components/parameters/SwarmPinParameter" + - $ref: "SwarmCommon.yaml#/components/parameters/SwarmDeferredUpload" + - $ref: "SwarmCommon.yaml#/components/parameters/SwarmEncryptParameter" + - $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyLevelParameter" + - $ref: "SwarmCommon.yaml#/components/parameters/SwarmAct" + - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActHistoryAddress" requestBody: content: application/octet-stream: @@ -219,14 +211,14 @@ paths: default: description: Default response - "/bytes/{reference}": + "/bytes/{address}": get: - summary: "Get referenced data" + summary: "Retrieve data by reference" tags: - Bytes parameters: - in: path - name: reference + name: address schema: $ref: "SwarmCommon.yaml#/components/schemas/SwarmReference" required: true @@ -236,6 +228,7 @@ paths: - $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyFallbackModeParameter" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyLevelParameter" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmChunkRetrievalTimeoutParameter" + - $ref: "SwarmCommon.yaml#/components/parameters/SwarmLookaheadBufferSizeParameter" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActTimestamp" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActPublisher" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActHistoryAddress" @@ -252,7 +245,7 @@ paths: default: description: Default response head: - summary: Requests the headers containing the content type and length for the reference + summary: Retrieve headers containing the content type and length for the reference tags: - Bytes parameters: @@ -293,7 +286,7 @@ paths: "/chunks": post: - summary: "Upload chunk" + summary: "Upload a chunk" tags: - Chunk parameters: @@ -307,7 +300,7 @@ paths: - $ref: "SwarmCommon.yaml#/components/parameters/SwarmAct" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActHistoryAddress" requestBody: - description: Chunk binary data that has to have at least 8 bytes. + description: Chunk binary data containing at least 8 bytes. content: application/octet-stream: schema: @@ -318,7 +311,7 @@ paths: description: OK headers: "swarm-tag": - description: Tag UID if it was passed to the request `swarm-tag` header. + description: Tag UID from the request `swarm-tag` header if provided. schema: $ref: "SwarmCommon.yaml#/components/schemas/Uid" "swarm-act-history-address": @@ -338,13 +331,24 @@ paths: "/chunks/stream": get: - summary: "Upload stream of chunks" - description: "Returns a WebSocket connection on which stream of chunks can be uploaded. Each chunk sent is acknowledged using a binary response `0` which serves as confirmation of upload of single chunk. Chunks should be packaged as binary messages for uploading. If a tag is specified, the chunks will be streamed into local storage and then be uploaded to the network once the stream is closed. If a tag is not specified, the chunks will bypass local storage and be directly uploaded to the network through the stream as they arrive." + summary: "Stream chunks for upload" + description: "Establishes a WebSocket connection for streaming chunks. Each uploaded chunk receives a binary acknowledgment (`0`). Chunks are sent as binary messages. When a tag is specified, chunks are stored locally and uploaded to the network after the stream closes. Without a tag, chunks are directly uploaded to the network as they arrive." tags: - Chunk parameters: - $ref: "SwarmCommon.yaml#/components/parameters/SwarmTagParameter" - - $ref: "SwarmCommon.yaml#/components/parameters/SwarmPostageBatchId" + - in: query + name: swarm-tag + schema: + $ref: "SwarmCommon.yaml#/components/schemas/Uid" + required: false + description: "Associate upload with an existing Tag UID (use when WebSocket client cannot set custom headers)" + - in: header + name: swarm-postage-batch-id + description: "ID of Postage Batch that is used to upload data with. Optional when chunks include pre-signed postage stamps." + required: false + schema: + $ref: "SwarmCommon.yaml#/components/schemas/SwarmAddress" responses: "200": description: "Connection established" @@ -354,13 +358,9 @@ paths: description: Default response "/bzz": post: - summary: "Upload file or a collection of files" + summary: "Upload a file or collection of files" description: - "In order to upload a collection, user can send a multipart request with all the files populated in the form data with appropriate headers.\n\n - User can also upload a tar file along with the swarm-collection header. This will upload the tar file after extracting the entire directory structure.\n\n - If the swarm-collection header is absent, all requests (including tar files) are considered as single file uploads.\n\n - A multipart request is treated as a collection regardless of whether the swarm-collection header is present. This means in order to serve single files - uploaded as a multipart request, the swarm-index-document header should be used with the name of the file." + "Upload single files or collections of files. For a single file, `Content-Type` is optional: when present it is stored as metadata as-is; when absent the server infers a type from the start of the body. To upload a collection, send a multipart request with files in the form data with appropriate headers. Tar files can be uploaded with the `swarm-collection` header to extract and upload the directory structure. Without the `swarm-collection` header, requests are treated as single file uploads. Multipart requests are always treated as collections; use the `swarm-index-document` header to specify a single file to serve." tags: - BZZ parameters: @@ -423,14 +423,14 @@ paths: default: description: Default response - "/bzz/{reference}": + "/bzz/{address}": get: - summary: "Get file or index document from a collection of files" + summary: "Retrieve a file or index document from a collection" tags: - BZZ parameters: - in: path - name: reference + name: address schema: $ref: "SwarmCommon.yaml#/components/schemas/SwarmReference" required: true @@ -440,6 +440,7 @@ paths: - $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyFallbackModeParameter" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyLevelParameter" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmChunkRetrievalTimeoutParameter" + - $ref: "SwarmCommon.yaml#/components/parameters/SwarmLookaheadBufferSizeParameter" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActTimestamp" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActPublisher" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActHistoryAddress" @@ -453,6 +454,11 @@ paths: schema: type: string format: binary + headers: + "swarm-feed-resolved-version": + $ref: "SwarmCommon.yaml#/components/headers/SwarmFeedResolvedVersion" + + "400": $ref: "SwarmCommon.yaml#/components/responses/400" "404": @@ -462,7 +468,7 @@ paths: default: description: Default response head: - summary: Get the headers containing the content type and length for the reference + summary: Retrieve headers with content type and length for the reference tags: - BZZ parameters: @@ -485,14 +491,14 @@ paths: default: description: Default response - "/bzz/{reference}/{path}": + "/bzz/{address}/{path}": get: - summary: "Get referenced file from a collection of files" + summary: "Retrieve a file from a collection by path" tags: - BZZ parameters: - in: path - name: reference + name: address schema: $ref: "SwarmCommon.yaml#/components/schemas/SwarmReference" required: true @@ -506,6 +512,9 @@ paths: - $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyStrategyParameter" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyFallbackModeParameter" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmChunkRetrievalTimeoutParameter" + - $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyLevelParameter" + - $ref: "SwarmCommon.yaml#/components/parameters/SwarmCache" + - $ref: "SwarmCommon.yaml#/components/parameters/SwarmLookaheadBufferSizeParameter" responses: "200": description: OK @@ -514,6 +523,9 @@ paths: schema: type: string format: binary + headers: + "swarm-feed-resolved-version": + $ref: "SwarmCommon.yaml#/components/headers/SwarmFeedResolvedVersion" "400": $ref: "SwarmCommon.yaml#/components/responses/400" @@ -563,12 +575,6 @@ paths: tags: - Tag description: Tags can be thought of as upload sessions which can be tracked using the tags endpoint. It will keep track of the chunks that are uploaded as part of the tag and will push them out to the network once a done split is called on the Tag. This happens internally if you use the `Swarm-Deferred-Upload` header. - requestBody: - required: true - content: - application/json: - schema: - $ref: "SwarmCommon.yaml#/components/schemas/NewTagRequest" responses: "201": description: New Tag Info @@ -582,14 +588,14 @@ paths: default: description: Default response - "/tags/{uid}": + "/tags/{id}": get: summary: "Get Tag information using Uid" tags: - Tag parameters: - in: path - name: uid + name: id schema: $ref: "SwarmCommon.yaml#/components/schemas/Uid" required: true @@ -615,7 +621,7 @@ paths: - Tag parameters: - in: path - name: uid + name: id schema: $ref: "SwarmCommon.yaml#/components/schemas/Uid" required: true @@ -637,7 +643,7 @@ paths: - Tag parameters: - in: path - name: uid + name: id schema: $ref: "SwarmCommon.yaml#/components/schemas/Uid" required: true @@ -672,12 +678,18 @@ paths: required: true description: Swarm reference of the root hash post: - summary: Pin the root hash with the given reference + summary: Pin a root hash by reference tags: - Pinning + parameters: + - in: header + schema: + $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyLevelParameter" + name: swarm-redundancy-level + required: false responses: "200": - description: Pin already exists, so no operation + description: Pin already exists content: application/json: schema: @@ -697,12 +709,12 @@ paths: default: description: Default response delete: - summary: Unpin the root hash with the given reference + summary: Unpin a root hash by reference tags: - Pinning responses: "200": - description: Unpinning root hash with reference + description: Root hash has been unpinned content: application/json: schema: @@ -714,12 +726,12 @@ paths: default: description: Default response get: - summary: Get pinning status of the root hash with the given reference + summary: Get the pinning status of a root hash tags: - Pinning responses: "200": - description: Reference of the pinned root hash + description: The pinned root hash reference content: application/json: schema: @@ -752,7 +764,11 @@ paths: "/pins/check": get: - summary: Validate pinned chunks integerity + summary: Validate pinned chunks integrity + description: | + Returns a stream of newline-delimited JSON objects (NDJSON), one per pinned reference checked. + The response uses chunked transfer encoding; clients should parse each line as an independent + `PinIntegrityResponse` object rather than buffering the body into a single JSON value. tags: - Pinning parameters: @@ -761,10 +777,10 @@ paths: schema: $ref: "SwarmCommon.yaml#/components/schemas/SwarmOnlyReference" required: false - description: The number of items to skip before starting to collect the result set. + description: Optional reference to check; if not provided, all pinned references are checked responses: "200": - description: List of checked root hash references + description: NDJSON stream of integrity results, one object per line content: application/json: schema: @@ -776,7 +792,7 @@ paths: "/pss/send/{topic}/{targets}": post: - summary: Send to recipient or target with Postal Service for Swarm + summary: Send a message using the Postal Service for Swarm tags: - Postal Service for Swarm parameters: @@ -813,7 +829,7 @@ paths: "/pss/subscribe/{topic}": get: - summary: Subscribe for messages on the given topic. + summary: Subscribe to messages on a topic tags: - Postal Service for Swarm parameters: @@ -825,7 +841,7 @@ paths: description: Topic name responses: "200": - description: Returns a WebSocket with a subscription for incoming message data on the requested topic. + description: Establishes a WebSocket subscription for incoming messages on the topic "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: @@ -838,14 +854,14 @@ paths: - GSOC parameters: - in: path - name: reference + name: address schema: - $ref: "SwarmCommon.yaml#/components/schemas/SwarmReference" + $ref: "SwarmCommon.yaml#/components/schemas/SwarmAddress" required: true description: "Single Owner Chunk address (which may have multiple payloads)" responses: "200": - description: Returns a WebSocket with a subscription for incoming message data on the requested SOC address. + description: Establishes a WebSocket subscription for incoming messages on the Single Owner Chunk address "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: @@ -853,7 +869,7 @@ paths: "/soc/{owner}/{id}": post: - summary: Upload single owner chunk + summary: Upload a Single Owner Chunk tags: - Single owner chunk parameters: @@ -862,13 +878,13 @@ paths: schema: $ref: "SwarmCommon.yaml#/components/schemas/EthereumAddress" required: true - description: Owner + description: Ethereum address of the chunk owner - in: path name: id schema: $ref: "SwarmCommon.yaml#/components/schemas/HexString" required: true - description: Id + description: Unique identifier for the chunk - in: query name: sig schema: @@ -879,13 +895,17 @@ paths: name: swarm-postage-batch-id schema: $ref: "SwarmCommon.yaml#/components/parameters/SwarmPostageBatchId" - required: true + required: false + description: ID of the postage batch to use. Either this or `swarm-postage-stamp` must be supplied. - $ref: "SwarmCommon.yaml#/components/parameters/SwarmPostageStamp" + - $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 is composed of the span (8 bytes) and the at most 4KB payload. + description: The SOC binary data, composed of the span (8 bytes) and up to 4KB of payload. content: application/octet-stream: schema: @@ -899,6 +919,10 @@ paths: schema: $ref: "SwarmCommon.yaml#/components/schemas/ReferenceResponse" headers: + "swarm-tag": + 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": @@ -907,12 +931,14 @@ paths: $ref: "SwarmCommon.yaml#/components/responses/401" "402": $ref: "SwarmCommon.yaml#/components/responses/402" + "404": + $ref: "SwarmCommon.yaml#/components/responses/404" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response get: - summary: Resolve Single Owner Chunk data + summary: Retrieve Single Owner Chunk data tags: - Single owner chunk parameters: @@ -927,7 +953,7 @@ paths: schema: $ref: "SwarmCommon.yaml#/components/schemas/HexString" required: true - description: Arbitrary identifier of the related data + description: Unique identifier for the chunk data - $ref: "SwarmCommon.yaml#/components/parameters/SwarmOnlyRootChunkParameter" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmCache" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyStrategyParameter" @@ -955,7 +981,7 @@ paths: "/feeds/{owner}/{topic}": post: - summary: Create an initial feed root manifest + summary: Create a feed root manifest tags: - Feed parameters: @@ -964,13 +990,13 @@ paths: schema: $ref: "SwarmCommon.yaml#/components/schemas/EthereumAddress" required: true - description: Owner + description: Ethereum address of the feed owner - in: path name: topic schema: $ref: "SwarmCommon.yaml#/components/schemas/HexString" required: true - description: Topic + description: Topic identifier for the feed - in: query name: type schema: @@ -981,6 +1007,12 @@ paths: - $ref: "SwarmCommon.yaml#/components/parameters/SwarmPostageBatchId" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmAct" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActHistoryAddress" + - in: header + schema: + $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyLevelParameter" + name: swarm-redundancy-level + required: false + description: Redundancy level for the feed manifest upload pipeline and ACT encryption responses: "201": description: Created @@ -1002,7 +1034,7 @@ paths: default: description: Default response get: - summary: Find feed update + summary: Retrieve the latest feed update tags: - Feed parameters: @@ -1011,13 +1043,13 @@ paths: schema: $ref: "SwarmCommon.yaml#/components/schemas/EthereumAddress" required: true - description: Owner + description: Ethereum address of the feed owner - in: path name: topic schema: $ref: "SwarmCommon.yaml#/components/schemas/HexString" required: true - description: Topic + description: Topic identifier for the feed - in: query name: at schema: @@ -1051,6 +1083,9 @@ paths: $ref: "SwarmCommon.yaml#/components/headers/SwarmFeedIndex" "swarm-feed-index-next": $ref: "SwarmCommon.yaml#/components/headers/SwarmFeedIndexNext" + "swarm-feed-resolved-version": + $ref: "SwarmCommon.yaml#/components/headers/SwarmFeedResolvedVersion" + content: application/octet-stream: schema: @@ -1065,18 +1100,23 @@ paths: default: description: Default response - "/stewardship/{reference}": + "/stewardship/{address}": get: - summary: "Check if content is available" + summary: "Check content availability" tags: - Stewardship parameters: - in: path - name: reference + name: address schema: $ref: "SwarmCommon.yaml#/components/schemas/SwarmReference" required: true description: "Root hash of content (can be of any type: collection, file, chunk)" + - in: header + schema: + $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyLevelParameter" + name: swarm-redundancy-level + required: false responses: "200": description: Returns if the content is retrievable @@ -1091,12 +1131,12 @@ paths: default: description: Default response put: - summary: "Re-upload content for specified root hash" + summary: "Re-upload content by reference" tags: - Stewardship parameters: - in: path - name: reference + name: address schema: $ref: "SwarmCommon.yaml#/components/schemas/SwarmReference" required: true @@ -1105,7 +1145,13 @@ paths: schema: $ref: "SwarmCommon.yaml#/components/parameters/SwarmPostageBatchId" name: swarm-postage-batch-id - description: Postage batch to use for re-upload. If none is provided and the file was uploaded on the same node before, it will reuse the same batch. If not found, it will return error. If a new batch is provided, the chunks are stamped again with the new batch. + required: true + description: Postage batch to use for re-upload. The chunks are re-stamped with this batch. + - in: header + schema: + $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyLevelParameter" + name: swarm-redundancy-level + required: false responses: "200": description: OK @@ -1137,7 +1183,7 @@ paths: "/health": get: - summary: Get node overall health Status + summary: Get the overall health status of the node description: | Health Status will indicate node healthiness. @@ -1156,7 +1202,7 @@ paths: "/readiness": get: - summary: Readiness endpoint indicates if node is ready to start accepting traffic + summary: Check if the node is ready to accept traffic tags: - Status responses: @@ -1171,7 +1217,7 @@ paths: "/balances": get: - summary: Get the balances with all known peers including prepaid services + summary: Get balances with all known peers tags: - Balance responses: @@ -1186,14 +1232,14 @@ paths: default: description: Default response - "/balances/{address}": + "/balances/{peer}": get: - summary: Get the balances with a specific peer including prepaid services + summary: Get the balance with a specific peer tags: - Balance parameters: - in: path - name: address + name: peer schema: $ref: "SwarmCommon.yaml#/components/schemas/SwarmAddress" required: true @@ -1231,7 +1277,7 @@ paths: "/consumed": get: - summary: Get the past due consumption balances with all known peers + summary: Get past due consumption balances with all known peers tags: - Balance responses: @@ -1246,14 +1292,14 @@ paths: default: description: Default response - "/consumed/{address}": + "/consumed/{peer}": get: - summary: Get the past due consumption balance with a specific peer + summary: Get past due consumption balance with a specific peer tags: - Balance parameters: - in: path - name: address + name: peer schema: $ref: "SwarmCommon.yaml#/components/schemas/SwarmAddress" required: true @@ -1274,7 +1320,7 @@ paths: "/chequebook/address": get: - summary: Get the address of the chequebook contract used + summary: Get the chequebook contract address tags: - Chequebook responses: @@ -1304,12 +1350,12 @@ paths: "/chunks/{address}": get: - summary: "Get chunk" + summary: "Retrieve a chunk" tags: - Chunk parameters: - in: path - name: reference + name: address schema: $ref: "SwarmCommon.yaml#/components/schemas/SwarmReference" required: true @@ -1339,7 +1385,7 @@ paths: default: description: Default response head: - summary: Check if chunk at address exists locally + summary: Check if a chunk exists locally tags: - Chunk parameters: @@ -1364,10 +1410,16 @@ paths: "/envelope/{address}": post: - summary: "Create postage stamp signature against given chunk address" + summary: "Create a postage stamp for a chunk" tags: - Envelope parameters: + - in: path + name: address + schema: + $ref: "SwarmCommon.yaml#/components/schemas/SwarmAddress" + required: true + description: Swarm address of the chunk to stamp - in: header name: swarm-postage-batch-id schema: @@ -1389,15 +1441,15 @@ paths: default: description: Default response - "/connect/{multiAddress}": + "/connect/{multi-address}": post: - summary: Connect to address + summary: Connect to a peer address tags: - Connectivity parameters: - in: path allowReserved: true - name: multiAddress + name: multi-address schema: $ref: "SwarmCommon.yaml#/components/schemas/MultiAddress" required: true @@ -1418,7 +1470,7 @@ paths: "/reservestate": get: - summary: Get reserve state + summary: Get the reserve state tags: - Status responses: @@ -1433,7 +1485,7 @@ paths: "/chainstate": get: - summary: Get chain state + summary: Get the chain state tags: - Status responses: @@ -1446,9 +1498,59 @@ paths: default: description: Default response + "/debugstore": + get: + summary: Get a snapshot of local storage debug info + tags: + - Status + responses: + "200": + description: Local storage debug info + content: + application/json: + schema: + type: object + properties: + Upload: + type: object + properties: + TotalUploaded: { type: integer } + TotalSynced: { type: integer } + PendingUpload: { type: integer } + Pinning: + type: object + properties: + TotalCollections: { type: integer } + TotalChunks: { type: integer } + Cache: + type: object + properties: + Size: { type: integer } + Capacity: { type: integer } + Reserve: + type: object + properties: + SizeWithinRadius: { type: integer } + TotalSize: { type: integer } + Capacity: { type: integer } + LastBinIDs: + type: array + items: { type: integer } + Epoch: { type: integer } + ChunkStore: + type: object + properties: + TotalChunks: { type: integer } + SharedSlots: { type: integer } + ReferenceCount: { type: integer } + "500": + $ref: "SwarmCommon.yaml#/components/responses/500" + default: + description: Default response + "/node": get: - summary: Get information about the node + summary: Get node information tags: - Status responses: @@ -1463,7 +1565,7 @@ paths: "/peers": get: - summary: Get a list of peers + summary: Get the list of connected peers tags: - Connectivity responses: @@ -1478,7 +1580,7 @@ paths: "/peers/{address}": delete: - summary: Remove peer + summary: Disconnect from a peer tags: - Connectivity parameters: @@ -1490,7 +1592,7 @@ paths: description: Swarm address of peer responses: "200": - description: Disconnected peer + description: Peer has been disconnected content: application/json: schema: @@ -1504,7 +1606,7 @@ paths: "/pingpong/{address}": post: - summary: Try connection to node + summary: Ping a peer to measure latency tags: - Connectivity parameters: @@ -1530,21 +1632,21 @@ paths: default: description: Default response - "/settlements/{address}": + "/settlements/{peer}": get: - summary: Get amount of sent and received from settlements with a peer + summary: Get settlement amounts sent and received with a peer tags: - Settlements parameters: - in: path - name: address + name: peer schema: $ref: "SwarmCommon.yaml#/components/schemas/SwarmAddress" required: true description: Swarm address of peer responses: "200": - description: Amount of sent or received from settlements with a peer + description: Settlement amounts sent and received with the peer content: application/json: schema: @@ -1558,7 +1660,7 @@ paths: "/settlements": get: - summary: Get settlements with all known peers and total amount sent or received + summary: Get settlements with all known peers and totals tags: - Settlements responses: @@ -1575,7 +1677,7 @@ paths: "/timesettlements": get: - summary: Get time based settlements with all known peers and total amount sent or received + summary: Get time-based settlements with all known peers and totals tags: - Settlements responses: @@ -1592,7 +1694,7 @@ paths: "/topology": get: - summary: Get topology of known network + summary: Get the network topology tags: - Connectivity responses: @@ -1605,7 +1707,7 @@ paths: "/welcome-message": get: - summary: Get configured P2P welcome message + summary: Get the P2P welcome message tags: - Connectivity responses: @@ -1620,7 +1722,7 @@ paths: default: description: Default response post: - summary: Set P2P welcome message + summary: Set the P2P welcome message tags: - Connectivity requestBody: @@ -1642,12 +1744,12 @@ paths: default: description: Default response - "/chequebook/cashout/{peer-id}": + "/chequebook/cashout/{peer}": get: - summary: Get last cashout action for the peer + summary: Get the last cashout status for a peer parameters: - in: path - name: peer-id + name: peer schema: $ref: "SwarmCommon.yaml#/components/schemas/SwarmAddress" required: true @@ -1668,10 +1770,10 @@ paths: default: description: Default response post: - summary: Cashout the last cheque for the peer + summary: Cash out the last cheque for a peer parameters: - in: path - name: peer-id + name: peer schema: $ref: "SwarmCommon.yaml#/components/schemas/SwarmAddress" required: true @@ -1682,7 +1784,7 @@ paths: - Chequebook responses: "201": - description: OK + description: Cheque has been cashed out content: application/json: schema: @@ -1696,12 +1798,12 @@ paths: default: description: Default response - "/chequebook/cheque/{peer-id}": + "/chequebook/cheque/{peer}": get: - summary: Get last cheques for the peer + summary: Get the last cheques for a peer parameters: - in: path - name: peer-id + name: peer schema: $ref: "SwarmCommon.yaml#/components/schemas/SwarmAddress" required: true @@ -1710,7 +1812,7 @@ paths: - Chequebook responses: "200": - description: Last cheques + description: The last cheques for the peer content: application/json: schema: @@ -1724,12 +1826,12 @@ paths: "/chequebook/cheque": get: - summary: Get last cheques for all peers + summary: Get the last cheques for all peers tags: - Chequebook responses: "200": - description: Last cheques + description: The last cheques for all peers content: application/json: schema: @@ -1743,26 +1845,26 @@ paths: "/chequebook/deposit": post: - summary: Deposit tokens from overlay address into chequebook + summary: Deposit tokens into the chequebook parameters: - in: query name: amount schema: type: integer required: true - description: amount of tokens to deposit + description: Amount of tokens to deposit - $ref: "SwarmCommon.yaml#/components/parameters/GasPriceParameter" tags: - Chequebook responses: - "201": + "200": description: Transaction hash of the deposit transaction content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/TransactionResponse" "400": - $ref: "SwarmCommon.yaml#/components/responses/404" + $ref: "SwarmCommon.yaml#/components/responses/400" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: @@ -1770,26 +1872,26 @@ paths: "/chequebook/withdraw": post: - summary: Withdraw tokens from the chequebook to the overlay address + summary: Withdraw tokens from the chequebook parameters: - in: query name: amount schema: type: integer required: true - description: amount of tokens to withdraw + description: Amount of tokens to withdraw - $ref: "SwarmCommon.yaml#/components/parameters/GasPriceParameter" tags: - Chequebook responses: - "201": + "200": description: Transaction hash of the withdraw transaction content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/TransactionResponse" "400": - $ref: "SwarmCommon.yaml#/components/responses/404" + $ref: "SwarmCommon.yaml#/components/responses/400" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: @@ -1812,12 +1914,12 @@ paths: default: description: Default response - "/transactions/{txHash}": + "/transactions/{hash}": get: - summary: Get information about a sent transaction + summary: Retrieve transaction information parameters: - in: path - name: txHash + name: hash schema: $ref: "SwarmCommon.yaml#/components/schemas/TransactionHash" required: true @@ -1826,7 +1928,7 @@ paths: - Transaction responses: "200": - description: Get info about transaction + description: Transaction information content: application/json: schema: @@ -1838,10 +1940,10 @@ paths: default: description: Default response post: - summary: Rebroadcast existing transaction + summary: Rebroadcast a transaction parameters: - in: path - name: txHash + name: hash schema: $ref: "SwarmCommon.yaml#/components/schemas/TransactionHash" required: true @@ -1865,7 +1967,7 @@ paths: summary: Cancel existing transaction parameters: - in: path - name: txHash + name: hash schema: $ref: "SwarmCommon.yaml#/components/schemas/TransactionHash" required: true @@ -1889,12 +1991,12 @@ paths: "/stamps": get: - summary: Get stamps for this node + summary: Get postage stamps for this node tags: - Postage Stamps responses: "200": - description: Returns an array of postage batches. + description: An array of postage stamps content: application/json: schema: @@ -1930,6 +2032,37 @@ paths: $ref: "SwarmCommon.yaml#/components/responses/400" default: description: Default response + patch: + summary: Update the label of an existing postage batch + tags: + - Postage Stamps + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + label: + type: string + description: New label for the postage batch + required: + - label + responses: + "200": + description: Label updated successfully + content: + application/json: + schema: + $ref: "SwarmCommon.yaml#/components/schemas/Response" + "400": + $ref: "SwarmCommon.yaml#/components/responses/400" + "404": + $ref: "SwarmCommon.yaml#/components/responses/404" + "500": + $ref: "SwarmCommon.yaml#/components/responses/500" + default: + description: Default response "/stamps/{batch_id}/buckets": parameters: @@ -1961,7 +2094,7 @@ paths: post: summary: Buy a new postage batch. description: | - Be aware, this endpoint creates an on-chain transactions and transfers BZZ from the node's Ethereum account and hence directly manipulates the wallet balance! + Be aware, this endpoint creates an on-chain transaction and transfers BZZ from the node's Ethereum account, directly affecting the wallet balance! tags: - Postage Stamps parameters: @@ -1976,7 +2109,7 @@ paths: schema: type: integer required: true - description: Batch depth which specifies how many chunks can be signed with the batch. It is a logarithm. Must be higher than default bucket depth (16) + description: Batch depth (logarithm) specifying the maximum number of chunks this stamp can cover. Must be greater than the default bucket depth (16) - in: query name: label schema: @@ -2010,7 +2143,7 @@ paths: patch: summary: Top up an existing postage batch. description: | - Be aware, this endpoint creates on-chain transactions and transfers BZZ from the node's Ethereum account and hence directly manipulates the wallet balance! + Be aware, this endpoint creates an on-chain transaction and transfers BZZ from the node's Ethereum account, directly affecting the wallet balance! tags: - Postage Stamps parameters: @@ -2050,7 +2183,7 @@ paths: patch: summary: Dilute an existing postage batch. description: | - Be aware, this endpoint creates on-chain transactions and transfers BZZ from the node's Ethereum account and hence directly manipulates the wallet balance! + Be aware, this endpoint creates an on-chain transaction and transfers BZZ from the node's Ethereum account, directly affecting the wallet balance! tags: - Postage Stamps parameters: @@ -2065,7 +2198,7 @@ paths: schema: type: integer required: true - description: New batch depth. Must be higher than the previous depth. + description: The new batch depth, which must be greater than the current depth - $ref: "SwarmCommon.yaml#/components/parameters/GasPriceParameter" - $ref: "SwarmCommon.yaml#/components/parameters/GasLimitParameter" responses: @@ -2086,12 +2219,12 @@ paths: "/batches": get: - summary: Get all globally available batches that were purchased by all nodes. + summary: Get all globally available postage batches tags: - Postage Stamps responses: "200": - description: Returns an array of all available and currently valid postage batches. + description: An array of all available and valid postage batches content: application/json: schema: @@ -2100,6 +2233,32 @@ paths: default: description: Default response + "/batches/{batch_id}": + parameters: + - in: path + name: batch_id + schema: + $ref: "SwarmCommon.yaml#/components/schemas/BatchID" + required: true + description: ID of the postage batch + get: + summary: Get a single globally available postage batch by ID + tags: + - Postage Stamps + responses: + "200": + description: The postage batch state + content: + application/json: + schema: + $ref: "SwarmCommon.yaml#/components/schemas/PostageBatchShort" + "400": + $ref: "SwarmCommon.yaml#/components/responses/400" + "404": + $ref: "SwarmCommon.yaml#/components/responses/404" + default: + description: Default response + "/rchash/{depth}/{anchor1}/{anchor2}": get: summary: Get reserve commitment hash with sample proofs @@ -2140,7 +2299,7 @@ paths: "/accounting": get: - summary: Get all accounting associated values with all known peers + summary: Get accounting values for all known peers tags: - Balance responses: @@ -2157,7 +2316,7 @@ paths: "/redistributionstate": get: - summary: Get current status of node in redistribution game + summary: Get the node's redistribution game status tags: - RedistributionState responses: @@ -2175,7 +2334,7 @@ paths: description: Default response "/wallet": get: - summary: Get wallet balance for BZZ and xDai + summary: Get wallet balance for BZZ and xDAI tags: - Wallet responses: @@ -2191,7 +2350,7 @@ paths: description: Default response "/wallet/withdraw/{coin}": post: - summary: Allows withdrawals of BZZ or xDAI to provided (whitelisted) address + summary: Withdraw BZZ or xDAI to a whitelisted address tags: - Wallet parameters: @@ -2209,7 +2368,7 @@ paths: name: coin required: true schema: - $ref: "SwarmCommon.yaml#/components/schemas/SwarmAddress" + $ref: "SwarmCommon.yaml#/components/schemas/WithdrawCoin" responses: "200": content: @@ -2266,8 +2425,8 @@ paths: "/stake/{amount}": post: - summary: Deposit some amount for staking. - description: Be aware, this endpoint creates an on-chain transactions and transfers BZZ from the node's Ethereum account and hence directly manipulates the wallet balance. + summary: Deposit an amount for staking. + description: Be aware, this endpoint creates an on-chain transaction and transfers BZZ from the node's Ethereum account, directly affecting the wallet balance. tags: - Staking parameters: @@ -2311,8 +2470,8 @@ paths: default: description: Default response delete: - summary: Withdraws all past staked amount back to the wallet. - description: Be aware, this endpoint can only be called when the contract is paused and is in the process of being migrated to a new contract. + summary: Withdraw all previously staked amounts. + description: Be aware, this endpoint can only be called when the contract is paused and undergoing migration to a new contract. tags: - Staking parameters: @@ -2372,6 +2531,8 @@ paths: $ref: "SwarmCommon.yaml#/components/responses/400" default: description: Default response + + "/loggers/{exp}/{verbosity}": put: summary: Set logger(s) verbosity level. parameters: @@ -2381,6 +2542,13 @@ paths: $ref: "SwarmCommon.yaml#/components/schemas/LoggerExp" required: true description: Regular expression or a subsystem that matches the logger(s). + - in: path + name: verbosity + schema: + type: string + enum: [none, error, warning, info, debug, all] + required: true + description: Verbosity level to apply to the matching logger(s). tags: - Logging responses: diff --git a/openapi/SwarmCommon.yaml b/openapi/SwarmCommon.yaml index e4c30bc71..ffcbbac3b 100644 --- a/openapi/SwarmCommon.yaml +++ b/openapi/SwarmCommon.yaml @@ -1,9 +1,8 @@ openapi: 3.0.3 info: - version: 4.3.0 + version: 5.0.0 title: Common Data Types - description: | - \*****bzzz***** + description: Common data structures and types used throughout the Bee API externalDocs: description: Browse the documentation @ the Swarm Docs @@ -37,7 +36,7 @@ components: $ref: "#/components/schemas/PublicKey" BigInt: - description: Numeric string that represents integer which might exceed `Number.MAX_SAFE_INTEGER` limit (2^53-1) + description: Numeric string representing an integer that may exceed `Number.MAX_SAFE_INTEGER` (2^53-1) type: string example: "1000000000000000000" @@ -50,6 +49,8 @@ components: type: integer commitment: type: integer + reserveCapacityDoubling: + type: integer ChainState: type: object @@ -62,6 +63,8 @@ components: $ref: "#/components/schemas/BigInt" currentPrice: $ref: "#/components/schemas/BigInt" + minimumValidityBlocks: + type: integer PeerAccountingData: type: object @@ -76,10 +79,16 @@ components: properties: balance: $ref: "#/components/schemas/BigInt" + consumedBalance: + $ref: "#/components/schemas/BigInt" thresholdReceived: $ref: "#/components/schemas/BigInt" thresholdGiven: $ref: "#/components/schemas/BigInt" + currentThresholdReceived: + $ref: "#/components/schemas/BigInt" + currentThresholdGiven: + $ref: "#/components/schemas/BigInt" surplusBalance: $ref: "#/components/schemas/BigInt" reservedBalance: @@ -126,6 +135,10 @@ components: $ref: "#/components/schemas/SwarmAddress" balance: $ref: "#/components/schemas/BigInt" + thresholdreceived: + $ref: "#/components/schemas/BigInt" + thresholdgiven: + $ref: "#/components/schemas/BigInt" Balances: type: object @@ -240,12 +253,12 @@ components: example: "2020-06-11T11:26:42.6969797+02:00" Duration: - description: Go time.Duration format + description: Time duration in Go time.Duration format (e.g., 5.0018ms) type: string example: "5.0018ms" Seconds: - description: Go time.Duration format in seconds + description: Time duration in seconds (Go time.Duration format) type: number example: 30.5 @@ -293,17 +306,14 @@ components: MultiAddress: type: string - NewTagRequest: - type: object - properties: - address: - $ref: "#/components/schemas/SwarmAddress" - NewTagResponse: type: object properties: uid: $ref: "#/components/schemas/Uid" + address: + $ref: "#/components/schemas/SwarmAddress" + description: Root reference associated with the tag once the upload is finalized; zero value before that. startedAt: $ref: "#/components/schemas/DateTime" split: @@ -368,21 +378,31 @@ components: type: array nullable: false items: - $ref: "#/components/schemas/Address" + type: object + properties: + address: + $ref: "#/components/schemas/SwarmAddress" + fullNode: + type: boolean BlockListedPeers: - type: array - items: - type: object - properties: - address: - $ref: "#/components/schemas/Address" - fullNode: - type: boolean - reason: - type: string - duration: - type: integer + type: object + properties: + peers: + type: array + nullable: false + items: + type: object + properties: + address: + $ref: "#/components/schemas/SwarmAddress" + fullNode: + type: boolean + reason: + type: string + duration: + type: integer + description: Block duration in seconds PssRecipient: type: string @@ -472,12 +492,11 @@ components: properties: beeMode: type: string - enum: [light, full, dev, ultra-light, unknown] + enum: [light, full, ultra-light, unknown] description: > Gives back in what mode the Bee client has been started. The modes are mutually exclusive * `light` - light node; does not participate in forwarding or storing chunks * `full` - full node - * `dev` - development mode; Bee client for development purposes, blockchain operations are mocked * `ultra-light` - ultra-light node; a light node with chain disabled * `unknown` - unknown mode chequebookEnabled: @@ -510,8 +529,29 @@ components: $ref: "#/components/schemas/BatchID" utilization: type: integer + description: > + Raw batch fullness indicator: the highest write count among the + `2^bucketDepth` collision buckets of the batch. This is **not** a + percentage; one unit corresponds to one chunk written into the + fullest bucket. Total batch capacity is `2^depth` chunks, while + the fullest bucket caps at `2^(depth - bucketDepth)` chunks, so + the fractional usage of the batch is + `utilization / 2^(depth - bucketDepth)` (also exposed directly as + `utilizationRatio`). When the value reaches + `2^(depth - bucketDepth)` the batch is effectively full and any + further write to the fullest bucket would overflow it. + utilizationRatio: + type: number + format: double + minimum: 0 + maximum: 1 + description: > + Fractional batch fullness in the range `[0, 1]`, computed as + `utilization / 2^(depth - bucketDepth)`. A value of `1` means the + fullest bucket has reached its capacity and the batch can no + longer accept writes that would land in that bucket. usable: - description: Indicate that the batch was discovered by the Bee node, but it awaits enough on-chain confirmations before declaring the batch as usable. + description: Indicates whether the batch was discovered by the Bee node and has received sufficient on-chain confirmations type: boolean label: type: string @@ -549,18 +589,16 @@ components: $ref: "#/components/schemas/BigInt" start: type: integer + owner: + $ref: "#/components/schemas/EthereumAddress" depth: type: integer bucketDepth: type: integer - immutableFlag: + immutable: type: boolean batchTTL: type: integer - owner: - $ref: "#/components/schemas/EthereumAddress" - storageRadius: - type: integer DebugPostageBatch: anyOf: @@ -596,17 +634,17 @@ components: peer: $ref: "#/components/schemas/SwarmAddress" received: - type: integer + $ref: "#/components/schemas/BigInt" sent: - type: integer + $ref: "#/components/schemas/BigInt" Settlements: type: object properties: totalReceived: - type: integer + $ref: "#/components/schemas/BigInt" totalSent: - type: integer + $ref: "#/components/schemas/BigInt" settlements: type: array nullable: false @@ -676,7 +714,7 @@ components: SwarmOnlyReferencesList: type: object properties: - reference: + references: type: array nullable: false items: @@ -768,6 +806,12 @@ components: walletAddress: $ref: "#/components/schemas/EthereumAddress" + WithdrawCoin: + type: string + enum: + - "bzz" + - "nativetoken" + RedistributionStatusResponse: type: object properties: @@ -832,7 +876,7 @@ components: LoggerExp: type: string - description: Base 64 encoded regular expression or subsystem string. + description: Base64-encoded regular expression or subsystem string pattern: "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$" example: "b25lL25hbWU=" @@ -888,7 +932,6 @@ components: enum: - "light" - "full" - - "dev" - "ultra-light" - "unknown" reserveSize: @@ -914,6 +957,8 @@ components: type: integer committedDepth: type: integer + isWarmingUp: + type: boolean StatusPeersResponse: type: object @@ -1067,6 +1112,13 @@ components: schema: type: string + SwarmFeedResolvedVersion: + schema: + type: string + required: false + description: "Indicates which feed version was resolved (v1 or v2)" + + parameters: GasPriceParameter: in: header @@ -1099,7 +1151,7 @@ components: type: boolean required: false description: > - Represents if the uploaded data should be also locally pinned on the node. + Indicates whether the uploaded data should also be locally pinned on this node SwarmEncryptParameter: in: header @@ -1108,7 +1160,7 @@ components: type: boolean required: false description: > - Represents the encrypting state of the file + Indicates whether the file should be encrypted SwarmRedundancyLevelParameter: in: header @@ -1129,14 +1181,11 @@ components: enum: [0, 1, 2, 3] required: false description: > - Specify the retrieve strategy on redundant data. - The numbers stand for NONE, DATA, PROX and RACE, respectively. - Strategy NONE means no prefetching takes place. - Strategy DATA means only data chunks are prefetched. - Strategy PROX means only chunks that are close to the node are prefetched. - Strategy RACE means all chunks are prefetched: n data chunks and k parity chunks. The first n chunks to arrive are used to reconstruct the file. - Multiple strategies can be used in a fallback cascade if the swarm redundancy fallback mode is set to true. - The default strategy is NONE, DATA, falling back to PROX, falling back to RACE + Specify the retrieval strategy for redundant data. + Values represent: NONE (0), DATA (1), PROX (2), RACE (3). + NONE: no prefetching. DATA: prefetch only data chunks. PROX: prefetch chunks near this node. RACE: prefetch all chunks and use the first n to arrive. + Multiple strategies can be cascaded if fallback mode is enabled. + Default: NONE > DATA > PROX > RACE SwarmRedundancyFallbackModeParameter: in: header @@ -1156,6 +1205,16 @@ components: description: > Specify the timeout for chunk retrieval. The default is 30 seconds. + SwarmLookaheadBufferSizeParameter: + in: header + name: swarm-lookahead-buffer-size + schema: + type: integer + required: false + description: > + Override the lookahead buffer size used during retrieval, in bytes. When unset the node + picks 8x or 16x the io.Copy default buffer (32 kB) depending on file size. + SwarmOnlyRootChunkParameter: in: header name: swarm-only-root-chunk @@ -1169,7 +1228,7 @@ components: name: Content-Type schema: type: string - description: The specified content-type is preserved for download of the asset + description: "Single file: trimmed Content-Type is stored as-is or, if omitted or empty, inferred from the first bytes without validating against the body; tar (`swarm-collection`) and multipart collection uploads still need a full-body Content-Type (e.g. `application/x-tar` or `multipart/form-data` with boundary) so the request can be parsed." SwarmIndexDocumentParameter: in: header @@ -1178,7 +1237,7 @@ components: type: string example: index.html required: false - description: Default file to be referenced on path, if exists under that path + description: Default file to serve when a directory path is accessed SwarmErrorDocumentParameter: in: header @@ -1187,7 +1246,7 @@ components: type: string example: error.html required: false - description: Configure custom error document to be returned when a specified path can not be found in collection + description: Custom error document to return when a path is not found in the collection SwarmCollection: in: header @@ -1227,7 +1286,7 @@ components: default: "true" required: false description: > - Determines if the uploaded data should be sent to the network immediately or in a deferred fashion. By default the upload will be deferred. + Indicates whether the uploaded data should be sent to the network immediately or deferred. Default: deferred (true) SwarmCache: in: header @@ -1236,7 +1295,7 @@ components: type: boolean default: "true" required: false - description: "Determines if the download data should be cached on the node. By default the download will be cached" + description: "Indicates whether downloaded data should be cached on the node. Default: cached (true)" SwarmAct: in: header @@ -1274,7 +1333,7 @@ components: responses: "200": - description: OK. + description: Success "204": description: The resource was deleted successfully. "400": From d39353c1f8edced4b412f461b35a2b9f1d9949fd Mon Sep 17 00:00:00 2001 From: Yejin Kelly Joo Date: Tue, 7 Jul 2026 19:37:46 +0900 Subject: [PATCH 2/3] Update Bee install docs and examples to reflect actual v2.8.1 results Signed-off-by: Yejin Kelly Joo --- docs/bee/installation/docker.md | 13 +- docs/bee/installation/quick-start.md | 37 +---- docs/bee/working-with-bee/bee-api.md | 235 ++++++++++++++------------- docs/bee/working-with-bee/staking.md | 10 +- 4 files changed, 135 insertions(+), 160 deletions(-) diff --git a/docs/bee/installation/docker.md b/docs/bee/installation/docker.md index 2f86a719d..9caf67483 100644 --- a/docs/bee/installation/docker.md +++ b/docs/bee/installation/docker.md @@ -9,7 +9,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.1. 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.1 in the commands below if there is a newer full release. +In the examples below we specify the exact image version as 2.8.1. +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.1 in the commands below if there is a newer full release. ::: :::warning @@ -170,11 +172,10 @@ 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. -version: 2.8.1-06a0aca7 - planned to be supported until 11 December 2024, please follow https://ethswarm.org/ - -"time"="2024-09-24 22:21:04.543661" "level"="info" "logger"="node" "msg"="bee version" "version"="2.8.1-06a0aca7" -"time"="2024-09-24 22:21:04.590823" "level"="info" "logger"="node" "msg"="swarm public key" "public_key"="02f0e59eafa3c5c06542c0a7a7fe9579c55a163cf1d28d9f6945a34469f88d1b2a" -"time"="2024-09-24 22:21:04.686430" "level"="info" "logger"="node" "msg"="pss public key" "public_key"="02ea739530bbf48eed49197f21660f3b6564709b95bf558dc3b472688c34096418" +"time"="2026-07-07 16:52:59.641444" "level"="info" "logger"="node" "msg"="bee version" "version"="2.8.1-7cf53193" +"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" "time"="2024-09-24 22:21:04.686464" "level"="info" "logger"="node" "msg"="using ethereum address" "address"="0x8288F1c8e3dE7c3bf42Ae67fa840EC61481D085e" "time"="2024-09-24 22:21:04.700711" "level"="info" "logger"="node" "msg"="using overlay address" "address"="22dc155fe072e131449ec7ea2f77de16f4735f06257ebaa5daf2fdcf14267fd9" "time"="2024-09-24 22:21:04.700741" "level"="info" "logger"="node" "msg"="starting with an enabled chain backend" diff --git a/docs/bee/installation/quick-start.md b/docs/bee/installation/quick-start.md index 972f7e86d..7a1933dfc 100644 --- a/docs/bee/installation/quick-start.md +++ b/docs/bee/installation/quick-start.md @@ -109,13 +109,10 @@ 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. -version: 2.8.1-390a402e - planned to be supported until 22 April 2025, please follow https://ethswarm.org/ - -"time"="2025-03-04 11:13:10.113050" "level"="info" "logger"="node" "msg"="bee version" "version"="2.6.0-390a402e" -"time"="2025-03-04 11:13:10.164801" "level"="info" "logger"="node" "msg"="swarm public key" "public_key"="02b19880b8d024eac3bf8afa3fa85b31b72fcfd491cebc6af78ddd85ff97f65416" -"time"="2025-03-04 11:13:10.216657" "level"="debug" "logger"="node" "msg"="using existing libp2p key" -"time"="2025-03-04 11:13:10.268431" "level"="debug" "logger"="node" "msg"="using existing pss key" -"time"="2025-03-04 11:13:10.268474" "level"="info" "logger"="node" "msg"="pss public key" "public_key"="03a3166e04b749ab3d04fda8a41180598ff2eed01a8096fb72d2c7da393a47c46a" +"time"="2026-07-07 16:52:59.641444" "level"="info" "logger"="node" "msg"="bee version" "version"="2.8.1-7cf53193" +"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" "time"="2025-03-04 11:13:10.268479" "level"="info" "logger"="node" "msg"="using ethereum address" "address"="0x003842B26B3dB292Cf84d5969E71c0d1e93F5578" "time"="2025-03-04 11:13:10.288418" "level"="info" "logger"="node" "msg"="using overlay address" "address"="fe38346dd89e4211c0e60195ee73e38d2c2ee2fe2b914b771d4ad503cfedbd3c" "time"="2025-03-04 11:13:10.288474" "level"="info" "logger"="node" "msg"="starting with an enabled chain backend" @@ -184,7 +181,7 @@ swarm-cli status ```bash Bee API: http://localhost:1633 [OK] -Version: 2.8.1-d0aa8b93 +Version: 2.8.1-7cf53193 Mode: light Chainsync @@ -214,28 +211,7 @@ swarm-cli status ```bash Bee API: http://localhost:1633 [OK] -Version: 2.8.1-d0aa8b93 -Mode: light - -Chainsync -Block: 41,710,955 / 41,710,962 (Δ 7) - -Topology -Connected Peers: 151 -Population: 2257 -Depth: 10 - -Wallet -xBZZ: 0.0000000000000000 -xDAI: 0.009787142484816165 - -Chequebook -Available xBZZ: 0.0000000000000000 -Total xBZZ: 0.0000000000000000 -noah@NoahM16:~$ swarm-cli status -Bee -API: http://localhost:1633 [OK] -Version: 2.8.1-d0aa8b93 +Version: 2.8.1-7cf53193 Mode: light Chainsync @@ -258,4 +234,3 @@ Total xBZZ: 0.0000000000000000 ## Next Steps With your node now fully synced, you're ready start start learning how to [develop on Swarm](./../../develop/introduction.md). - diff --git a/docs/bee/working-with-bee/bee-api.md b/docs/bee/working-with-bee/bee-api.md index ccdc3f7f5..b06a12daa 100644 --- a/docs/bee/working-with-bee/bee-api.md +++ b/docs/bee/working-with-bee/bee-api.md @@ -53,10 +53,10 @@ Let's review a handful of endpoints which will provide you with important inform The `/status` endpoint returns a quick summary of some important metrics for your node. ```bash - curl -s http://localhost:1633/status | jq +curl -s http://localhost:1633/status | jq ``` -```bash +```json { "overlay": "1e2054bec3e681aeb0b365a1f9a574a03782176bd3ec0bcf810ebcaf551e4070", "proximity": 256, @@ -102,7 +102,7 @@ Here are the last few entries: curl -s http://localhost:1633/status/peers | jq ``` -```bash +```json ... { "overlay": "1e1547d0d629469ff0d8fd2cbb6435df8fd913f2e948f177d733356d784b7ea4", @@ -258,7 +258,7 @@ And we can compare these entries to our own node's `/status` results for diagnos curl -s http://localhost:1633/status | jq ``` -```bash +```json { "overlay": "1e2054bec3e681aeb0b365a1f9a574a03782176bd3ec0bcf810ebcaf551e4070", "proximity": 256, @@ -281,115 +281,116 @@ From the results we can see that our node's neighborhood size and batch commitme ### _/redistributionstate_ - This endpoint provides an overview of values related to storage fee redistribution game (in other words, staking rewards). You can use this endpoint to check whether or not your node is participating properly in the redistribution game. +This endpoint provides an overview of values related to storage fee redistribution game (in other words, staking rewards). You can use this endpoint to check whether or not your node is participating properly in the redistribution game. - ```bash - curl -s http://localhost:1633/redistributionstate | jq - ``` +```bash +curl -s http://localhost:1633/redistributionstate | jq +``` - ```bash - { - "minimumGasFunds": "11080889201250000", - "hasSufficientFunds": true, - "isFrozen": false, - "isFullySynced": true, - "phase": "claim", - "round": 212859, - "lastWonRound": 207391, - "lastPlayedRound": 210941, - "lastFrozenRound": 210942, - "lastSelectedRound": 212553, - "lastSampleDuration": 491687776653, - "block": 32354719, - "reward": "1804537795127017472", - "fees": "592679945236926714", - "isHealthy": true - } - ``` - - * `"minimumGasFunds"` - The minimum required xDAI denominated in wei (1 xDAI = 10^18 wei) required for a node to participate in the redistribution game. - * `"hasSufficientFunds"` - Whether your node has at least the `"minimumGasFunds"` amount of xDAI. - * `"isFrozen"` - Indicates if your node is frozen, which may occur for [several reasons](./staking.md#diagnosing-freezing-issues). - * `"isFullySynced"` - Whether your node has fully synced all the chunks in its `"storageRadius"` (the value returned from the `/reservestate` endpoint.) - * `"phase"` - The current phase of the redistribution game (this does not indicate whether or not your node is participating in the current phase). - * `"round"` - The current number of the round of the redistribution game. - * `"lastWonRound"` - The last round number in which your node won the redistribution game. - * `"lastPlayedRound"` - The last round number in which your node participating in the redistribution game. If this number matches the number of the current round shown in `"round"`, then your node is participating in the current round. - * `"lastFrozenRound"` - The last round in which your node was frozen. - * `"lastSelectedRound"` - The last round in which your node's neighborhood was selected. Note that it is possible for your node's neighborhood to be selected without your node playing in the redistribution game. This may potentially indicate your node's hardware is not sufficient to calculate the commitment hash fast enough. See [section on the `/rchash` endpoint](#rchash) for more information. - * `"lastSampleDuration"` - The time it took for your node to calculate the sample commitment hash in nanoseconds. - * `"block"` - current Gnosis block number - * `"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 +```json +{ + "minimumGasFunds": "11080889201250000", + "hasSufficientFunds": true, + "isFrozen": false, + "isFullySynced": true, + "phase": "claim", + "round": 212859, + "lastWonRound": 207391, + "lastPlayedRound": 210941, + "lastFrozenRound": 210942, + "lastSelectedRound": 212553, + "lastSampleDuration": 491687776653, + "block": 32354719, + "reward": "1804537795127017472", + "fees": "592679945236926714", + "isHealthy": true +} +``` + +* `"minimumGasFunds"` - The minimum required xDAI denominated in wei (1 xDAI = 10^18 wei) required for a node to participate in the redistribution game. +* `"hasSufficientFunds"` - Whether your node has at least the `"minimumGasFunds"` amount of xDAI. +* `"isFrozen"` - Indicates if your node is frozen, which may occur for [several reasons](./staking.md#diagnosing-freezing-issues). +* `"isFullySynced"` - Whether your node has fully synced all the chunks in its `"storageRadius"` (the value returned from the `/reservestate` endpoint.) +* `"phase"` - The current phase of the redistribution game (this does not indicate whether or not your node is participating in the current phase). +* `"round"` - The current number of the round of the redistribution game. +* `"lastWonRound"` - The last round number in which your node won the redistribution game. +* `"lastPlayedRound"` - The last round number in which your node participating in the redistribution game. If this number matches the number of the current round shown in `"round"`, then your node is participating in the current round. +* `"lastFrozenRound"` - The last round in which your node was frozen. +* `"lastSelectedRound"` - The last round in which your node's neighborhood was selected. Note that it is possible for your node's neighborhood to be selected without your node playing in the redistribution game. This may potentially indicate your node's hardware is not sufficient to calculate the commitment hash fast enough. See [section on the `/rchash` endpoint](#rchash) for more information. +* `"lastSampleDuration"` - The time it took for your node to calculate the sample commitment hash in nanoseconds. +* `"block"` - current Gnosis block number +* `"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 ### _/reservestate_ - This endpoint shows key information about the reserve state of your node. You can use it to identify problems with your node related to its reserve (whether it is syncing chunks properly into its reserve for example). +This endpoint shows key information about the reserve state of your node. You can use it to identify problems with your node related to its reserve (whether it is syncing chunks properly into its reserve for example). - ```bash - curl -s http://localhost:1633/reservestate | jq - ``` - ```bash - { - "radius": 15, - "storageRadius": 10, - "commitment": 134121783296, - "reserveCapacityDoubling": 0 - } - ``` +```bash +curl -s http://localhost:1633/reservestate | jq +``` +```json +{ + "radius": 15, + "storageRadius": 10, + "commitment": 134121783296, + "reserveCapacityDoubling": 0 +} +``` + +Let's take a look at each of these values: +* `"radius"` - Represents the maximum storage radius assuming all postage stamp batches are fully utilized. +* `"storageRadius"` - The radius of responsibility - the proximity order of chunks for which your node is responsible for storing. It should generally match the radius shown on [Swarmscan](https://swarmscan.io/neighborhoods). +* `"commitment"` - The total number of chunks which would be stored on the Swarm network if 100% of all postage batches were fully utilised. +* `"reserveCapacityDoubling"` - Indicates whether your node is currently using the reserve doubling mechanism. See [Reserve Doubling](./staking.md#reserve-doubling) for details. - Let's take a look at each of these values: - * `"radius"` - Represents the maximum storage radius assuming all postage stamp batches are fully utilized. - * `"storageRadius"` - The radius of responsibility - the proximity order of chunks for which your node is responsible for storing. It should generally match the radius shown on [Swarmscan](https://swarmscan.io/neighborhoods). - * `"commitment"` - The total number of chunks which would be stored on the Swarm network if 100% of all postage batches were fully utilised. - * `"reserveCapacityDoubling"` - Indicates whether your node is currently using the reserve doubling mechanism. See [Reserve Doubling](./staking.md#reserve-doubling) for details. ### _/chainstate_ - This endpoint relates to your node's interactions with the Swarm Smart contracts on the Gnosis Chain. +This endpoint relates to your node's interactions with the Swarm Smart contracts on the Gnosis Chain. - ```bash - curl -s http://localhost:1633/chainstate | jq +```bash + curl -s http://localhost:1633/chainstate | jq - { - "chainTip": 41786513, - "block": 41786505, - "totalAmount": "293796491451", - "currentPrice": "56774" - } - ``` - * `"chainTip"` - The latest Gnosis Chain block number. Should be as high as or almost as high as the block number shown at [GnosisScan](https://gnosisscan.io/). - * `"block"` - The latest block your node has fully synced from Gnosis Chain. If significantly behind `"chainTip"`, your node may still be catching up. Should be very close to `"chainTip"` if your node has already been operating for a while. - * `"totalAmount"` - Cumulative value of all prices per chunk in PLUR for each block. - * `"currentPrice"` - The price in PLUR to store a single chunk for each Gnosis Chain block. +{ + "chainTip": 41786513, + "block": 41786505, + "totalAmount": "293796491451", + "currentPrice": "56774" +} +``` +* `"chainTip"` - The latest Gnosis Chain block number. Should be as high as or almost as high as the block number shown at [GnosisScan](https://gnosisscan.io/). +* `"block"` - The latest block your node has fully synced from Gnosis Chain. If significantly behind `"chainTip"`, your node may still be catching up. Should be very close to `"chainTip"` if your node has already been operating for a while. +* `"totalAmount"` - Cumulative value of all prices per chunk in PLUR for each block. +* `"currentPrice"` - The price in PLUR to store a single chunk for each Gnosis Chain block. ### _/topology_ - This endpoint allows you to explore the topology of your node within the Kademlia network. The results are split into 32 bins from bin_0 to bin_32. Each bin represents the nodes in the same neighborhood as your node at each proximity order from PO 0 to PO 32. +This endpoint allows you to explore the topology of your node within the Kademlia network. The results are split into 32 bins from bin_0 to bin_32. Each bin represents the nodes in the same neighborhood as your node at each proximity order from PO 0 to PO 32. - As the output of this file can be very large, we save it to the `topology.json` file for easier inspection: +As the output of this file can be very large, we save it to the `topology.json` file for easier inspection: - ```bash - curl -s http://localhost:1633/topology | jq '.' > topology.json - ``` - We open the file in vim for inspection: - ```bash - vim topology.json - ``` +```bash + curl -s http://localhost:1633/topology | jq '.' > topology.json +``` +We open the file in vim for inspection: +```bash +vim topology.json +``` - The `/topology` endpoint provides insights into how your node is positioned within the Swarm network. The response starts with global network statistics, followed by detailed bin-by-bin peer connections (for 32 bins). Lets first look at the global stats: +The `/topology` endpoint provides insights into how your node is positioned within the Swarm network. The response starts with global network statistics, followed by detailed bin-by-bin peer connections (for 32 bins). Lets first look at the global stats: - ```json - "baseAddr": "da7e5cc3ed9a46b6e7491d3bf738535d98112641380cbed2e9ddfe4cf4fc01c4", - "population": 20514, - "connected": 176, - "timestamp": "2024-02-08T20:57:03.815537925Z", - "nnLowWatermark": 3, - "depth": 10, - "reachability": "Public", - "networkAvailability": "Available", - ... - ``` +```json + "baseAddr": "da7e5cc3ed9a46b6e7491d3bf738535d98112641380cbed2e9ddfe4cf4fc01c4", + "population": 20514, + "connected": 176, + "timestamp": "2024-02-08T20:57:03.815537925Z", + "nnLowWatermark": 3, + "depth": 10, + "reachability": "Public", + "networkAvailability": "Available", + ... +``` - `"baseAddr"` - Your node's overlay address. - `"population"` - The total number of nodes your node has collected information about. This number should be around ####. If it is far higher or lower it likely indicates a problem. @@ -454,23 +455,23 @@ From the results we can see that our node's neighborhood size and batch commitme ### _/node_ - This endpoint returns info about options related to your node type and also displays your current node type. +This endpoint returns info about options related to your node type and also displays your current node type. - ```bash - curl -s http://localhost:1633/node | jq - ``` - ```bash - { - "beeMode": "full", - "chequebookEnabled": true, - "swapEnabled": true - } - ``` - * `"beeMode"` - The mode of your node, can be `"full"`, `"light"`, or `"ultraLight"`. - * `"chequebookEnabled"` - Whether or not your node's `chequebook-enable` option is set to `true`. - * `"swapEnabled"` - Whether or not your node's `swap-enable` option is set to `true`. +```bash +curl -s http://localhost:1633/node | jq +``` +```json +{ + "beeMode": "full", + "chequebookEnabled": true, + "swapEnabled": true +} +``` +* `"beeMode"` - The mode of your node, can be `"full"`, `"light"`, or `"ultraLight"`. +* `"chequebookEnabled"` - Whether or not your node's `chequebook-enable` option is set to `true`. +* `"swapEnabled"` - Whether or not your node's `swap-enable` option is set to `true`. - If your node is not operating in the correct mode, this can help you to diagnose whether you have set your options correctly. +If your node is not operating in the correct mode, this can help you to diagnose whether you have set your options correctly. ### _/rchash_ @@ -542,15 +543,15 @@ eviction will interrupt the sampler process. The `/health` endpoint provides a quick status check for your Bee node which simply indicates whether the node is operating or not. It is often used in tools like Docker and Kubernetes. ```bash - curl -s http://localhost:1633/health | jq +curl -s http://localhost:1633/health | jq ``` -```bash - { - "status": "ok", - "version": "2.8.1-d0aa8b93", - "apiVersion": "7.3.0" - } +```json +{ + "status": "ok", + "version": "2.8.1-7cf53193", + "apiVersion": "8.1.0" +} ``` - `"status"` - "ok" if the server is responsive. diff --git a/docs/bee/working-with-bee/staking.md b/docs/bee/working-with-bee/staking.md index ca2bc8177..1faedfa0d 100644 --- a/docs/bee/working-with-bee/staking.md +++ b/docs/bee/working-with-bee/staking.md @@ -481,11 +481,11 @@ To confirm a successful update, check that the value for the `"version"` field i For example, if the latest version was 2.8.1, it would look like this: -```bash +```json { "status": "ok", - "version": "2.8.1-d0aa8b93", - "apiVersion": "7.3.0" + "version": "2.8.1-7cf53193", + "apiVersion": "8.1.0" } ``` @@ -850,6 +850,4 @@ Confirm that `hasSufficientFunds` is `true`, and `isFullySynced` is `true` befor One of the most common issues affecting staking is the `sampler` process failing. The sampler is a resource intensive process which is run by nodes which are selected to take part in redistribution. The process may fail or time out if the node's hardware specifications aren't high enough. To check a node's performance the `/rchash` endpoint of the API may be used. See the `/rchash` section of the [Bee API page for usage details](./bee-api.md). -If you are still experiencing problems, you can find more help in the [node-operators](https://discord.gg/kHRyMNpw7t) Discord channel (for your safety, do not accept advice from anyone sending a private message on Discord). - - +If you are still experiencing problems, you can find more help in the [node-operators](https://discord.gg/kHRyMNpw7t) Discord channel (for your safety, do not accept advice from anyone sending a private message on Discord). From 03ca2fc95e3bcba90c1e3c70780536d29fedc7ec Mon Sep 17 00:00:00 2001 From: Yejin Kelly Joo Date: Tue, 7 Jul 2026 19:48:47 +0900 Subject: [PATCH 3/3] Fix chequebook verification version Signed-off-by: Yejin Kelly Joo --- docs/bee/working-with-bee/configuration.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/bee/working-with-bee/configuration.md b/docs/bee/working-with-bee/configuration.md index 34e81eef4..8b12620a9 100644 --- a/docs/bee/working-with-bee/configuration.md +++ b/docs/bee/working-with-bee/configuration.md @@ -671,7 +671,8 @@ bee start \ ``` :::info -Chequebook verification is an optional defense layer for full node operators who want to avoid connecting to peers that do not maintain a sufficient chequebook balance. It was introduced in Bee v2.8.1. +Chequebook verification is an optional defense layer for full node operators who want to avoid connecting to peers that do not maintain a sufficient chequebook balance. +It was introduced in Bee v2.8.0. ::: ## NAT address