From b8a94876109c1c6849c9dcf7b27556872bffdc03 Mon Sep 17 00:00:00 2001 From: Yejin Kelly Joo Date: Wed, 12 Aug 2026 16:45:58 +0900 Subject: [PATCH 1/6] docs: Clarify Bee full node requirements and types - have `node-types.md` as the single source of truth of requirements and others refer to that Signed-off-by: Yejin Kelly Joo --- docs/bee/faq.md | 31 ++++++++++-------------- docs/bee/installation/getting-started.md | 28 ++++++++++----------- docs/bee/working-with-bee/node-types.md | 14 ++++++++--- 3 files changed, 36 insertions(+), 37 deletions(-) diff --git a/docs/bee/faq.md b/docs/bee/faq.md index dbaf1c01d..895aed903 100644 --- a/docs/bee/faq.md +++ b/docs/bee/faq.md @@ -14,42 +14,37 @@ Depending on your needs you can run an ultra-light, light or full node. ### What are the differences between Bee node types? -A bee node can be configured to run in various modes based on specific use cases and requirements. [See here](./installation/getting-started.md) for an overview of the differences. +A bee node can be configured to run in various modes based on specific use cases and requirements. +[See here](./working-with-bee/node-types.md#node-types-overview) for an overview of the differences. +### What are the requirements for running a Bee node? -#### What are the requirements for running a Bee node? +See the [getting started section](./installation/getting-started.md#requirements) for more information about running a Bee node. -See the [getting started section](./installation/getting-started.md#software-requirements) for more information about running a Bee node. +#### Full node -##### Full node +Light and ultra-light nodes run on practically any modern computer, while full nodes have specific hardware and funding requirements. +See [full node specifications](./working-with-bee/node-types.md#full-node-specifications) for the current list. -- 20GB -30GB SSD (ideally NVME). -- 8GB RAM -- CPU with 2+ cores -- RPC connection to Gnosis Chain -- Min 0.1 xDAI for Gnosis GAS fees -- 1 xBZZ for initial chequebook deployment -- 10 xBZZ for staking (optional) - -##### How much bandwidth is required for each node? +### How much bandwidth is required for each node? Typically, each node requires around 10 megabits per second (Mbps) of bandwidth during normal operation. -##### How do I Install Bee on Windows? +### How do I Install Bee on Windows? Bee is compatible with Windows and a Bee `.exe` file can be found on the [`releases` page](https://github.com/ethersphere/bee/releases) of the Bee repo. It is also possible to [build from the source](./installation/build-from-source.md). -##### How do I get the node's wallet's private key (use-case for Desktop app)? +### How do I get the node's wallet's private key (use-case for Desktop app)? See the [backup section](./working-with-bee/backups.md) for more info. -##### How do I import my private key to Metamask? +### How do I import my private key to Metamask? You can import the `swarm.key` json file in MetaMask using your password file or the password you have set in your bee config file. -##### Where can I find my password? +### Where can I find my password? You can find the password in the root of your data directory. See the [backup section](./working-with-bee/backups.md) for more info. @@ -174,4 +169,4 @@ If you are using a different wallet which does not have an easy option for addin Network name: Gnosis RPC URL: https://xdai.fairdatasociety.org Chain ID: 100 -Currency symbol: XDAI \ No newline at end of file +Currency symbol: XDAI diff --git a/docs/bee/installation/getting-started.md b/docs/bee/installation/getting-started.md index 6551c8d21..6acff4eba 100644 --- a/docs/bee/installation/getting-started.md +++ b/docs/bee/installation/getting-started.md @@ -43,16 +43,18 @@ The node type you need to run will differ depending on your use-case: Refer to the [Node Types](./../working-with-bee/node-types.md) page for deep dive into each node type, their features and limitations, and configuration instructions. -## Software Requirements +## Requirements -### Recommended Operating Systems +### Software Requirements + +#### Recommended Operating Systems - Officially supported systems are listed in the [Bee releases](https://github.com/ethersphere/bee/releases). - You can [build from source](./build-from-source.md) if your OS is unsupported. - **Swarm Desktop users** can use macOS, Windows, or Linux. - **Linux/macOS recommended**: Most tools and documentation are designed for Unix-based systems. - **Windows users**: While a Window release of Bee is available, you may also consider using [WSL](https://learn.microsoft.com/en-us/windows/wsl/install) and using a Linux version of Bee. -### Essential Tools +#### Essential Tools While not strictly required, these tools will *greatly* simplify your experience working with Bee nodes: @@ -61,23 +63,20 @@ While not strictly required, these tools will *greatly* simplify your experience - **[Swarm CLI](./../working-with-bee/swarm-cli.md)**: Terminal-based Bee node management. - **[Bee JS](./../../develop/tools-and-features/bee-js.md)**: JavaScript library for programmatic API access. -## Hardware Requirements +### Hardware Requirements -### Light and Ultra-Light +#### Light and Ultra-Light Light and ultra-light nodes can be run with practically any commercially available modern computer hardware and internet provider, and have very minimal CPU, RAM and network requirements. -### Full Node +#### Full Node -Requires significant storage and processing power: -- **Processor**: Recent 2 GHz dual-core. -- **RAM**: 8 GB. -- **Storage**: 30 GB SSD (HDD not recommended). -- **Internet**: High-speed and stable connection. +Full nodes require significant storage and processing power, a Gnosis Chain RPC endpoint, and enough xDAI and xBZZ to cover gas fees and chequebook deployment. +See [full node specifications](./../working-with-bee/node-types.md#full-node-specifications) on the Node Types page for the complete list of hardware and funding requirements. For staking and storage incentives, test node performance with [`/rchash`](https://docs.ethswarm.org/docs/bee/working-with-bee/bee-api/#rchash). -## Network Requirements +### Network Requirements A reliable, high-speed internet connection is recommended when running a full node, while ultra-light and light nodes require less bandwidth. The actual amount of bandwidth consumption depends on the node type and use-case: @@ -85,7 +84,7 @@ A reliable, high-speed internet connection is recommended when running a full no - **Light Node**: Moderate usage, based on data transfer volume. - **Ultra-Light Node**: Minimal usage, bandwidth utilization restricted based on free-tier download limits. -### RPC Endpoint +#### RPC Endpoint :::warning ***Free public RPC endpoints are discouraged*** since they may enforce rate limiting or may not store the historical smart contract data required by Bee nodes. [Read more](./../working-with-bee/configuration.md#setting-blockchain-rpc-endpoint). @@ -110,7 +109,7 @@ Without a properly configured RPC endpoint, a Bee node cannot interact with the * Stake tokens * Make blockchain transactions -### NAT and Port Forwarding +#### NAT and Port Forwarding If running Bee on a home network, there is a good chance it is behind NAT by default. Often simply [enabling port forwarding](https://www.noip.com/support/knowledgebase/general-port-forwarding-guide) will be enough to allow your node to start communicating smoothly with the rest of the network. @@ -140,4 +139,3 @@ If your home network happens to be using [CGNAT (Carrier-Grade NAT)](https://en. ### [Building from Source](./build-from-source.md) - Most flexible, but requires advanced setup. - diff --git a/docs/bee/working-with-bee/node-types.md b/docs/bee/working-with-bee/node-types.md index ae3ea43f8..2fe7c0f99 100644 --- a/docs/bee/working-with-bee/node-types.md +++ b/docs/bee/working-with-bee/node-types.md @@ -45,11 +45,18 @@ If you intend to participate in the redistribution game to earn storage incentiv Requires significant storage and processing power compared to other node types: -- **Processor**: Recent 2 GHz dual-core. -- **RAM**: 8 GB. -- **Storage**: 30 GB SSD (HDD not recommended). +- **Processor**: Recent 2 GHz dual-core (2+ cores). +- **RAM**: 500 MB. +- **Storage**: 20~30 GB SSD, ideally NVMe (HDD not recommended). - **Internet**: High-speed and stable connection. +A full node must also be connected to Gnosis Chain and hold enough funds to cover its on-chain operations: + +- **RPC endpoint**: A connection to Gnosis Chain (see [setting the blockchain RPC endpoint](./configuration.md#setting-blockchain-rpc-endpoint)). +- **xDAI**: Minimum 0.1 xDAI for Gnosis Chain gas fees. +- **xBZZ**: 1 xBZZ for the initial chequebook deployment. +- **(optional) xBZZ for staking**: 10 xBZZ, required only to participate in [storage incentives](./staking.md). + ### Full node configuration To run Bee as a full node, set: @@ -146,4 +153,3 @@ Bee will start in ultra-light mode by default, but in order to explicitly config - Cannot earn xBZZ by staking xBZZ and participating in the storage incentive system. - Cannot earn xBZZ by participating in the bandwidth incentives system. - Cannot use PSS or GSOC for sending or receiving. - From 2e6e0e0517ffc681303ba779d294ec1977bec82a Mon Sep 17 00:00:00 2001 From: Yejin Kelly Joo Date: Fri, 14 Aug 2026 18:35:05 +0900 Subject: [PATCH 2/6] docs: Clarify Bee node hardware requirements - Document modest baseline requirements for all node modes - explain the added disk, bandwidth, blockchain, and CPU needs for full nodes and staking. Signed-off-by: Yejin Kelly Joo --- docs/bee/faq.md | 4 +-- docs/bee/installation/getting-started.md | 11 +++++--- docs/bee/working-with-bee/bee-api.md | 11 +++----- docs/bee/working-with-bee/node-types.md | 33 +++++++++++++++--------- docs/bee/working-with-bee/staking.md | 6 ++++- 5 files changed, 40 insertions(+), 25 deletions(-) diff --git a/docs/bee/faq.md b/docs/bee/faq.md index 895aed903..fb13e6d4e 100644 --- a/docs/bee/faq.md +++ b/docs/bee/faq.md @@ -23,8 +23,8 @@ See the [getting started section](./installation/getting-started.md#requirements #### Full node -Light and ultra-light nodes run on practically any modern computer, while full nodes have specific hardware and funding requirements. -See [full node specifications](./working-with-bee/node-types.md#full-node-specifications) for the current list. +All three node types run on ordinary consumer hardware. +Full nodes use more disk space and bandwidth than the lighter modes and additionally need a Gnosis Chain connection and funds — see [full node specifications](./working-with-bee/node-types.md#full-node-specifications) for the current list. ### How much bandwidth is required for each node? diff --git a/docs/bee/installation/getting-started.md b/docs/bee/installation/getting-started.md index 6acff4eba..87f4d0862 100644 --- a/docs/bee/installation/getting-started.md +++ b/docs/bee/installation/getting-started.md @@ -65,16 +65,21 @@ While not strictly required, these tools will *greatly* simplify your experience ### Hardware Requirements +All three node types run on ordinary consumer hardware. +None of them requires a powerful machine. + #### Light and Ultra-Light -Light and ultra-light nodes can be run with practically any commercially available modern computer hardware and internet provider, and have very minimal CPU, RAM and network requirements. +Light and ultra-light nodes have very minimal CPU, RAM, disk and network requirements, and run on practically any commercially available computer hardware and internet connection. #### Full Node -Full nodes require significant storage and processing power, a Gnosis Chain RPC endpoint, and enough xDAI and xBZZ to cover gas fees and chequebook deployment. +Full nodes have modest CPU and RAM requirements too, but they use more disk space and require a more sustained bandwidth than the lighter modes. +They also need a Gnosis Chain RPC endpoint and some xDAI and xBZZ to cover gas fees and chequebook deployment. See [full node specifications](./../working-with-bee/node-types.md#full-node-specifications) on the Node Types page for the complete list of hardware and funding requirements. -For staking and storage incentives, test node performance with [`/rchash`](https://docs.ethswarm.org/docs/bee/working-with-bee/bee-api/#rchash). +Staking and receiving storage incentives may require more CPU power. +Test node performance with [`/rchash`](https://docs.ethswarm.org/docs/bee/working-with-bee/bee-api/#rchash) before deciding to participate in the redistribution game. ### Network Requirements diff --git a/docs/bee/working-with-bee/bee-api.md b/docs/bee/working-with-bee/bee-api.md index ccb503fb1..dc8dcb378 100644 --- a/docs/bee/working-with-bee/bee-api.md +++ b/docs/bee/working-with-bee/bee-api.md @@ -475,15 +475,12 @@ If your node is not operating in the correct mode, this can help you to diagnose ### _/rchash_ -Calling the `/rchash` endpoint triggers the generation of a reserve commitment hash, -which is used in the [redistribution game](/docs/concepts/incentives/redistribution-game), -and will report the amount of time it took to generate the hash. This is useful for -getting a performance benchmark to ensure that your node's hardware is sufficient. +Calling the `/rchash` endpoint triggers the generation of a reserve commitment hash, which is used in the [redistribution game](/docs/concepts/incentives/redistribution-game), and will report the amount of time it took to generate the hash. +This is useful for getting a performance benchmark to ensure that your node's processor is fast enough. The `/rchash` endpoint has 3 parameters: `depth`, `anchor1`, and `anchor2`. -For both anchor parameters, use the first 4 hex digits from your node's overlay -address (which you can find from the `/addresses` endpoint). For depth, use the -current storage depth of your node from the `/status` endpoint (`storageRadius` value): +For both anchor parameters, use the first 4 hex digits from your node's overlay address (which you can find from the `/addresses` endpoint). +For depth, use the current storage depth of your node from the `/status` endpoint (`storageRadius` value): ```text /rchash/{depth}/{anchor1}/{anchor2} diff --git a/docs/bee/working-with-bee/node-types.md b/docs/bee/working-with-bee/node-types.md index 2fe7c0f99..045ae5b1d 100644 --- a/docs/bee/working-with-bee/node-types.md +++ b/docs/bee/working-with-bee/node-types.md @@ -8,7 +8,11 @@ description: Compares full light and ultra-light node types with their features import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -Bee nodes can operate in three different modes depending on the user's needs, ranging from full-featured nodes that contribute to the network and earn incentives to lightweight modes that allow for basic interaction with minimal resource requirements. This guide outlines the three primary node types — **_Full_**, **_Light_**, and **_Ultra-Light_** — along with their configurations, capabilities, and limitations. +Bee nodes can operate in three different modes depending on the user's needs, ranging from full-featured nodes that contribute storage to the network and earn incentives to simpler modes that only download and upload data. +This guide outlines the three primary node types — **_Full_**, **_Light_**, and **_Ultra-Light_** — along with their configurations, capabilities, and limitations. + +All three modes can run on ordinary consumer computers, without requiring any extraordinary hardware. +What differs between them is the feature set, how much disk space and bandwidth the node uses, and whether it needs a blockchain connection and funds. Choosing the right node type depends on your goals, whether it's participating in the Swarm network as a storage provider, developing applications that use Swarm's decentralized storage and messaging, or simply exploring the technology with minimal setup. @@ -30,26 +34,31 @@ Bee can operate in different modes, each tailored to specific use cases: ## What is a full node? {#full-node} -Full nodes are the most feature-rich nodes in the Swarm network. They provide full upload and download capabilities, store and serve data, and participate in storage and bandwidth incentives. Running a full node requires more system resources, but it allows users to fully engage with and support the network. +Full nodes are the most feature-rich nodes in the Swarm network. +They provide full upload and download capabilities, store and serve data, and participate in storage and bandwidth incentives. +A full node uses more disk space and bandwidth than the lighter modes and needs a funded blockchain connection, but its CPU and memory requirements stay low enough for everyday consumer hardware. Full nodes are ideal for users who want to contribute to the Swarm network and earn incentives, as well as developers who require access to all Bee features including messaging features such as PSS and GSOC. ### Full node specifications -:::warning -Full nodes require significant system resources, including storage and bandwidth. Additionally, they must be connected to the blockchain to participate in incentives. - -If you intend to participate in the redistribution game to earn storage incentives, you should test your setup using [the `/rchash` endpoint](./bee-api.md#rchash) in order to ensure that your hardware is sufficient. Participation in the redistribution game requires a process with high computational and memory requirements, along with significant bandwidth usage. -::: - -Requires significant storage and processing power compared to other node types: +A full node does not need powerful hardware. +The requirements below are met by most laptops and desktops, and even single-board computers such as a [Raspberry Pi](https://en.wikipedia.org/wiki/Raspberry_Pi) with an attached SSD. +Disk space and sustained bandwidth are the main differences from the lighter node types: -- **Processor**: Recent 2 GHz dual-core (2+ cores). -- **RAM**: 500 MB. +- **Processor**: Recent 2 GHz dual-core (2+ cores). 4-cores is comfortable if you intend to take part in the redistribution game. +- **RAM**: 500 MB. - **Storage**: 20~30 GB SSD, ideally NVMe (HDD not recommended). - **Internet**: High-speed and stable connection. +:::info +Staking raises the CPU demand but not the memory demand. +Nodes selected for the redistribution game run the sampler process, which is CPU-bound and bandwidth-hungry; 4 cores are sufficient for it. + +Before staking, test your setup using [the `/rchash` endpoint](./bee-api.md#rchash) in order to confirm your node can complete a sample in time. +::: + A full node must also be connected to Gnosis Chain and hold enough funds to cover its on-chain operations: - **RPC endpoint**: A connection to Gnosis Chain (see [setting the blockchain RPC endpoint](./configuration.md#setting-blockchain-rpc-endpoint)). @@ -80,7 +89,7 @@ To run Bee as a full node, set: Light nodes provide a balance between functionality and resource efficiency. They can upload and download data but do not participate in chunk forwarding or storage for other nodes. -Light nodes are suited for users who want to interact with Swarm without the overhead of running a full node. They can serve the needs of developers who need to access Swarm's download / upload features but do not need advanced messaging features such as PSS and GSOC which are available only in full nodes. +Light nodes are suited for users who want to interact with Swarm without contributing storage to the network or maintaining a reserve. They can serve the needs of developers who need to access Swarm's download / upload features but do not need advanced messaging features such as PSS and GSOC which are available only in full nodes. Light node operators cannot earn xBZZ by participating in Swarm's incentives systems, as they do not participate in chunk forwarding or storage but only consume services, paying xBZZ for downloading data from full nodes and buying postage stamp batches for uploading data. diff --git a/docs/bee/working-with-bee/staking.md b/docs/bee/working-with-bee/staking.md index 736de5a76..209b221d6 100644 --- a/docs/bee/working-with-bee/staking.md +++ b/docs/bee/working-with-bee/staking.md @@ -849,7 +849,11 @@ Confirm that `hasSufficientFunds` is `true`, and `isFullySynced` is `true` befor #### Run sampler process to benchmark performance -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). +One of the most common issues affecting staking is the `sampler` process failing. +The sampler is a CPU-intensive process which is run by nodes which are selected to take part in redistribution. +It does not need much memory, but on a slow processor it may fail or time out; 4 cores are sufficient. +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). From 17a7b09a7dd365de2f75bddf855719920ebf7b94 Mon Sep 17 00:00:00 2001 From: Yejin Kelly Joo Date: Wed, 19 Aug 2026 22:30:29 +0900 Subject: [PATCH 3/6] fix(docs): drop xBZZ from full node chequebook requirements xBZZ is not required to deploy a chequebook. Deploying the contract costs xDAI gas only, and the initial xBZZ deposit is optional: `swap-initial-deposit` defaults to `0`, and the chequebook init path only requires xBZZ to be greater than or equal to that deposit. The claim also contradicted two existing pages, which already document the deployment as xDAI-only: - fund-your-node.md lists "Chequebook Deployment" as < 0.001 xDAI and no xBZZ. - configuration.md describes the deposit as optional and defaulting to zero. Co-Authored-By: Claude Opus 5 (1M context) Signed-off-by: Yejin Kelly Joo --- docs/bee/installation/getting-started.md | 2 +- docs/bee/working-with-bee/node-types.md | 1 - 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/bee/installation/getting-started.md b/docs/bee/installation/getting-started.md index 87f4d0862..a7523b767 100644 --- a/docs/bee/installation/getting-started.md +++ b/docs/bee/installation/getting-started.md @@ -75,7 +75,7 @@ Light and ultra-light nodes have very minimal CPU, RAM, disk and network require #### Full Node Full nodes have modest CPU and RAM requirements too, but they use more disk space and require a more sustained bandwidth than the lighter modes. -They also need a Gnosis Chain RPC endpoint and some xDAI and xBZZ to cover gas fees and chequebook deployment. +They also need a Gnosis Chain RPC endpoint and some xDAI to cover gas fees, including the chequebook deployment transaction. See [full node specifications](./../working-with-bee/node-types.md#full-node-specifications) on the Node Types page for the complete list of hardware and funding requirements. Staking and receiving storage incentives may require more CPU power. diff --git a/docs/bee/working-with-bee/node-types.md b/docs/bee/working-with-bee/node-types.md index 045ae5b1d..3365e4dd6 100644 --- a/docs/bee/working-with-bee/node-types.md +++ b/docs/bee/working-with-bee/node-types.md @@ -63,7 +63,6 @@ A full node must also be connected to Gnosis Chain and hold enough funds to cove - **RPC endpoint**: A connection to Gnosis Chain (see [setting the blockchain RPC endpoint](./configuration.md#setting-blockchain-rpc-endpoint)). - **xDAI**: Minimum 0.1 xDAI for Gnosis Chain gas fees. -- **xBZZ**: 1 xBZZ for the initial chequebook deployment. - **(optional) xBZZ for staking**: 10 xBZZ, required only to participate in [storage incentives](./staking.md). ### Full node configuration From 4e86b257c6c5ece296f7919c74d93708254e1e87 Mon Sep 17 00:00:00 2001 From: Yejin Kelly Joo Date: Wed, 19 Aug 2026 22:30:57 +0900 Subject: [PATCH 4/6] fix(docs): correct what the sampler is actually bound by The sampler was described as "bandwidth-hungry", and the /rchash troubleshooting advice named RAM as a main bottleneck. Neither holds: pkg/storer/sample.go imports no networking or retrieval package and reads chunks from the local chunk store, skipping any that fail to load. It never fetches from the network. What it does do is walk every chunk in radius, so the real constraints are processor speed and disk I/O. This is also why the specifications call for an SSD rather than an HDD. - node-types.md: describe staking as raising CPU demand and disk I/O. - bee-api.md: name disk and processor as the bottlenecks in the slow results warning, and drop the "consider more RAM" advice, which contradicted the corrected 500 MB figure. - staking.md: note that a slow disk can also cause a sampler timeout. Co-Authored-By: Claude Opus 5 (1M context) Signed-off-by: Yejin Kelly Joo --- docs/bee/working-with-bee/bee-api.md | 11 ++++------- docs/bee/working-with-bee/node-types.md | 6 +++--- docs/bee/working-with-bee/staking.md | 2 +- 3 files changed, 8 insertions(+), 11 deletions(-) diff --git a/docs/bee/working-with-bee/bee-api.md b/docs/bee/working-with-bee/bee-api.md index dc8dcb378..9676cffae 100644 --- a/docs/bee/working-with-bee/bee-api.md +++ b/docs/bee/working-with-bee/bee-api.md @@ -476,7 +476,7 @@ If your node is not operating in the correct mode, this can help you to diagnose ### _/rchash_ Calling the `/rchash` endpoint triggers the generation of a reserve commitment hash, which is used in the [redistribution game](/docs/concepts/incentives/redistribution-game), and will report the amount of time it took to generate the hash. -This is useful for getting a performance benchmark to ensure that your node's processor is fast enough. +This is useful for getting a performance benchmark to ensure that your node's processor and disk are fast enough. The `/rchash` endpoint has 3 parameters: `depth`, `anchor1`, and `anchor2`. For both anchor parameters, use the first 4 hex digits from your node's overlay address (which you can find from the `/addresses` endpoint). @@ -517,12 +517,9 @@ successful result: The `durationSeconds` value should not exceed roughly 6 minutes (360 seconds). :::warning Slow results -If `durationSeconds` is much longer than 360 seconds (for example, 1191 seconds / -~20 minutes), the node will likely fail to submit proofs in time during the -redistribution game, resulting in missed rewards or freezing. SSD speed and RAM -are typically the main bottlenecks, since the sampler does heavy random I/O -across the reserve. Upgrade to a faster SSD first, then consider more RAM or a -faster processor. +If `durationSeconds` is much longer than 360 seconds (for example, 1191 seconds / ~20 minutes), the node will likely fail to submit proofs in time during the redistribution game, resulting in missed rewards or freezing. +The sampler reads every chunk in radius from local storage, so disk and processor speed are typically the bottlenecks. +Upgrade to a faster SSD first, then consider a faster processor or more cores. ::: If while running the `/rchash` command there is an evictions related error such diff --git a/docs/bee/working-with-bee/node-types.md b/docs/bee/working-with-bee/node-types.md index 3365e4dd6..a9dc0d714 100644 --- a/docs/bee/working-with-bee/node-types.md +++ b/docs/bee/working-with-bee/node-types.md @@ -53,10 +53,10 @@ Disk space and sustained bandwidth are the main differences from the lighter nod - **Internet**: High-speed and stable connection. :::info -Staking raises the CPU demand but not the memory demand. -Nodes selected for the redistribution game run the sampler process, which is CPU-bound and bandwidth-hungry; 4 cores are sufficient for it. +Staking means taking part in the redistribution game, which raises CPU demand and disk I/O. +This calls for more than 2 processor cores and SSD storage rather than an HDD. -Before staking, test your setup using [the `/rchash` endpoint](./bee-api.md#rchash) in order to confirm your node can complete a sample in time. +Before staking, test your setup using [the `/rchash` endpoint](./bee-api.md#rchash) to confirm your node can complete a sample in time. ::: A full node must also be connected to Gnosis Chain and hold enough funds to cover its on-chain operations: diff --git a/docs/bee/working-with-bee/staking.md b/docs/bee/working-with-bee/staking.md index 209b221d6..f430a8df6 100644 --- a/docs/bee/working-with-bee/staking.md +++ b/docs/bee/working-with-bee/staking.md @@ -851,7 +851,7 @@ 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 CPU-intensive process which is run by nodes which are selected to take part in redistribution. -It does not need much memory, but on a slow processor it may fail or time out; 4 cores are sufficient. +It does not need much memory, but on a slow processor or a slow disk it may fail or time out; 4 cores are sufficient. 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). From a3946edf4108100674b149e3afd97acdf3346daf Mon Sep 17 00:00:00 2001 From: Yejin Kelly Joo Date: Wed, 19 Aug 2026 22:31:23 +0900 Subject: [PATCH 5/6] docs: recommend swarm-cli utility rchash alongside the API `swarm-cli utility rchash` needs no arguments: it reads the node's overlay address and committed depth and derives the anchor and depth parameters itself. The raw endpoint requires assembling both by hand, so the CLI is the better default. The API form stays fully documented in a second tab. Also corrects the depth guidance to use `committedDepth` rather than `storageRadius`, matching what swarm-cli passes. The two are equal unless `reserve-capacity-doubling` is set, in which case benchmarking at `storageRadius` measures a smaller sample than the node actually has to produce. Co-Authored-By: Claude Opus 5 (1M context) Signed-off-by: Yejin Kelly Joo --- docs/bee/working-with-bee/bee-api.md | 37 +++++++++++++++++++++++++++- docs/bee/working-with-bee/staking.md | 4 +-- 2 files changed, 38 insertions(+), 3 deletions(-) diff --git a/docs/bee/working-with-bee/bee-api.md b/docs/bee/working-with-bee/bee-api.md index 9676cffae..b4e21c31c 100644 --- a/docs/bee/working-with-bee/bee-api.md +++ b/docs/bee/working-with-bee/bee-api.md @@ -3,6 +3,8 @@ title: Bee API id: bee-api description: Comprehensive reference for Bee's HTTP API endpoints enabling programmatic access to node management uploads downloads and monitoring. --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; The Bee HTTP API is the primary interface to a running Bee node. API-endpoints can be queried using familiar HTTP requests, and will respond with semantically accurate [HTTP status and error codes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status) as well as data payloads in [JSON](https://www.json.org/json-en.html) format where appropriate. @@ -478,9 +480,38 @@ If your node is not operating in the correct mode, this can help you to diagnose Calling the `/rchash` endpoint triggers the generation of a reserve commitment hash, which is used in the [redistribution game](/docs/concepts/incentives/redistribution-game), and will report the amount of time it took to generate the hash. This is useful for getting a performance benchmark to ensure that your node's processor and disk are fast enough. + + + +The [`swarm-cli`](./swarm-cli.md) command doesn't require arguments. +It reads the node's overlay address and committed depth, and derives the anchor and depth parameters from them. + +```bash +swarm-cli utility rchash +``` + +Pass `--depth` to benchmark against a depth other than the node's current one. + +The command gives as a result the time it took to generate the reserve commitment hash. + +```bash +$ swarm-cli utility rchash +Reserve sampling duration: 360.37808911 seconds +``` + + + + + The `/rchash` endpoint has 3 parameters: `depth`, `anchor1`, and `anchor2`. For both anchor parameters, use the first 4 hex digits from your node's overlay address (which you can find from the `/addresses` endpoint). -For depth, use the current storage depth of your node from the `/status` endpoint (`storageRadius` value): +For depth, use your node's `committedDepth` from the `/status` endpoint. +For nodes which do not use [reserve doubling](./staking.md#reserve-doubling), `committedDepth` is equal to `storageRadius`: ```text /rchash/{depth}/{anchor1}/{anchor2} @@ -514,6 +545,10 @@ successful result: } ``` + + + + The `durationSeconds` value should not exceed roughly 6 minutes (360 seconds). :::warning Slow results diff --git a/docs/bee/working-with-bee/staking.md b/docs/bee/working-with-bee/staking.md index f430a8df6..fa1f8b844 100644 --- a/docs/bee/working-with-bee/staking.md +++ b/docs/bee/working-with-bee/staking.md @@ -852,8 +852,8 @@ 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 CPU-intensive process which is run by nodes which are selected to take part in redistribution. It does not need much memory, but on a slow processor or a slow disk it may fail or time out; 4 cores are sufficient. -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). +To check a node's performance, run `swarm-cli utility rchash`, or call the `/rchash` endpoint of the API directly. +See the `/rchash` section of the [Bee API page for usage details](./bee-api.md#rchash). 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 22b03ffd11bf3948f591803ab002e6e80544e751 Mon Sep 17 00:00:00 2001 From: Yejin Kelly Joo Date: Wed, 19 Aug 2026 22:32:12 +0900 Subject: [PATCH 6/6] docs: note that one rchash result is not a lasting guarantee Sampling time scales with how full the reserve is within radius, since the sampler walks every chunk in radius. Reserve occupancy follows network conditions and is not something an operator can choose, so a node measured against a half-full reserve can take roughly twice as long once the reserve approaches the default capacity of ~4M chunks. A marginal pass under the 360 second ceiling therefore says little about the same node later. Operators should look for real headroom rather than treating a single passing measurement as sufficient. Co-Authored-By: Claude Opus 5 (1M context) Signed-off-by: Yejin Kelly Joo --- docs/bee/working-with-bee/bee-api.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/bee/working-with-bee/bee-api.md b/docs/bee/working-with-bee/bee-api.md index b4e21c31c..9ee0cbb46 100644 --- a/docs/bee/working-with-bee/bee-api.md +++ b/docs/bee/working-with-bee/bee-api.md @@ -500,7 +500,6 @@ Pass `--depth` to benchmark against a depth other than the node's current one. The command gives as a result the time it took to generate the reserve commitment hash. ```bash -$ swarm-cli utility rchash Reserve sampling duration: 360.37808911 seconds ``` @@ -551,6 +550,13 @@ successful result: The `durationSeconds` value should not exceed roughly 6 minutes (360 seconds). +:::caution A single measurement is not a guarantee +Sampling time scales with how full the node's reserve is within its radius, since the sampler walks every chunk in radius. +Reserve occupancy depends on network conditions rather than on anything the operator sets, so a result measured against a half-full reserve says little about the same node once the reserve fills up. +A node holding around 2M chunks can complete a sample in roughly half the time of one at the full default reserve capacity of about 4M chunks. +Aim for a comfortable margin below 360 seconds; a marginal pass is not enough. +::: + :::warning Slow results If `durationSeconds` is much longer than 360 seconds (for example, 1191 seconds / ~20 minutes), the node will likely fail to submit proofs in time during the redistribution game, resulting in missed rewards or freezing. The sampler reads every chunk in radius from local storage, so disk and processor speed are typically the bottlenecks.