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/2] 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/2] 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).