diff --git a/CODING.md b/CODING.md index 8ebd0e9f4..fff641d90 100644 --- a/CODING.md +++ b/CODING.md @@ -22,3 +22,21 @@ Note that the Bee client supports running/forming multiple Swarm swarms, i.e. yo > when your node joins the designated swarm [`Bee`](https://github.com/ethersphere/bee), with a capital, refers to a specific bee client, written in the `go` programming language, while `bee`, in lower case, refers to any worker that can join a swarm (e.g. any client implementation that speaks the Swarm protocol). + +## Writing for answer engines (AEO/GEO) + +These conventions keep pages easy for search and AI answer engines to extract: + +- **Answer first**: open each page with a 1–2 sentence direct answer to its implied question (a definition, or the outcome/first step), before context, citations, or marketing. + A friendly or on-brand line can follow the factual one. + +- **One H1 per page**: the frontmatter `title` renders as the page's H1, so don't add a body `# H1`. + +- **Descriptive, question-shaped headings**: phrase a heading as the question a reader would ask (e.g. "What is a full node?", "How do I pin content during upload?"), on concept, reference, and how-to pages alike, rather than generic labels like "Overview" or "Introduction". + When you rename an existing heading, pin its original slug with `{#old-slug}` so existing anchor links keep working. + +- **Self-contained sentences**: avoid "as mentioned above", "at this point", and bare "this/it/here" — name the entity or section, so a sentence still makes sense when quoted on its own. + +- **`description` frontmatter**: write one concise, factual, self-contained sentence stating the page's key fact (not "Guide for…" / "Overview of…"), and make sure any acronym expansion matches the body. + +- **Prefer extraction aids**: definition-first paragraphs, lists, tables, and `:::info`/`:::tip` callouts for key facts, rather than long walls of prose. diff --git a/docs/bee/installation/build-from-source.md b/docs/bee/installation/build-from-source.md index 7bcf232ab..f69d78720 100644 --- a/docs/bee/installation/build-from-source.md +++ b/docs/bee/installation/build-from-source.md @@ -14,7 +14,7 @@ Prerequisites for installing directly from source are: - **git** - download from [git-scm.com](https://git-scm.com/). - **make** - [make](https://www.gnu.org/software/make/) is usually included by default in most UNIX operating systems, and can be installed and used on almost any other operating system where it is not included by default. -### Build from Source +## Build steps 1. Clone the repository: diff --git a/docs/bee/installation/docker.md b/docs/bee/installation/docker.md index 9caf67483..c997f784f 100644 --- a/docs/bee/installation/docker.md +++ b/docs/bee/installation/docker.md @@ -4,8 +4,6 @@ id: docker description: Provides comprehensive steps for deploying Bee nodes using Docker containers with volume management and network configuration. --- -# Docker Install - 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 diff --git a/docs/bee/installation/getting-started.md b/docs/bee/installation/getting-started.md index dba2f5a60..6551c8d21 100644 --- a/docs/bee/installation/getting-started.md +++ b/docs/bee/installation/getting-started.md @@ -4,7 +4,11 @@ id: getting-started description: Introduces Bee node types their requirements and available installation methods to help users choose appropriate setup approaches. --- -*If you want to get a Bee node up and running ASAP, check out the [Quick Start](./quick-start.md) guide.* +Running a Bee node means choosing a node type (full, light, or ultra-light), meeting the software, hardware, and network requirements, and picking an installation method. This guide covers each so you can choose the right setup. + +:::tip +If you want to get a Bee node up and running ASAP, check out the [Quick Start](./quick-start.md) guide. +::: ## Overview diff --git a/docs/bee/installation/hive.md b/docs/bee/installation/hive.md index cff46d8de..eefa30a2c 100644 --- a/docs/bee/installation/hive.md +++ b/docs/bee/installation/hive.md @@ -7,21 +7,21 @@ description: Describes tools and orchestration methods for managing multiple Bee Due to the mechanics of Swarm's [storage incentives](./../../concepts/incentives/redistribution-game.md), node operators may wish to run multiple nodes in order to maximize earning potential. Read [The Book of Swarm](https://www.ethswarm.org/the-book-of-swarm-2.pdf) for more information on how the swarm comes together. -### Docker +## Docker Up-to-date [Docker images for Bee](./docker.md) are provided. -### Docker Compose +## Docker Compose Running multiple Bee nodes is easier with `docker-compose`. Check out the Docker compose section of the [Docker README](https://github.com/ethersphere/bee/tree/master/packaging/docker). -### Helm +## Helm If you plan to run a large number of Bee nodes and you have experience using Kubernetes with Helm, you can have a look at how we manage our cluster under [Ethersphere/helm](https://github.com/ethersphere/helm/tree/master/charts/bee). -### Manual Setup +## Manual Setup If you just want to run a handful of Bee nodes, you can run multiple Bee nodes by creating separate configuration files. @@ -35,6 +35,6 @@ Make as many copies of bee-config-1.yaml as you want to run Bee nodes. Increment Configure your nodes as desired, but ensure that the values `api-addr`, `data-dir` and `p2p-addr` are unique for each configuration. -### Monitoring +## Monitoring See the [logging section](./../working-with-bee/logs-and-files.md) for more information on how to access your node's metrics. Share your community creations (such as [swarmMonitor](https://github.com/doristeo/SwarmMonitoring) - thanks doristeo!) in the [#node-operators](https://discord.gg/kHRyMNpw7t) channel of our Discord server so we can add you to our list of all things that are [awesome](https://github.com/ethersphere/awesome-swarm) and Swarm. 🧡 diff --git a/docs/bee/installation/set-target-neighborhood.md b/docs/bee/installation/set-target-neighborhood.md index e01d5213d..79c4ba23f 100644 --- a/docs/bee/installation/set-target-neighborhood.md +++ b/docs/bee/installation/set-target-neighborhood.md @@ -13,14 +13,14 @@ Therefore the default Bee configuration now includes the `neighborhood-suggester The Swarmscan neighborhood selector prioritizes the least populated neighborhood. If a neighborhood contains imbalanced sub-neighborhoods, it will suggest the least populated sub-neighborhood instead. Furthermore, the suggester will temporarily de-prioritize previously suggested neighborhoods based on the assumption that a new node is being created in each suggested neighborhood so that multiple nodes do not simultaneously attempt to join the same neighborhood. ::: -#### Setting Neighborhood Manually +## Setting Neighborhood Manually It's recommended to use the default `neighborhood-suggester` configuration for choosing your node's neighborhood, however you may also set your node's neighborhood manually using the `target-neighborhood` option. To use this option, it's first necessary to identify potential target neighborhoods. You can find underpopulated neighborhoods using the [Swarmscan website](https://swarmscan.io/neighborhoods). It ranks neighborhoods from least to most populated and displays their leading binary bits. Simply copy the leading bits from one of the least populated neighborhoods (for example, `0010100001`) and use it to set `target-neighborhood`. After doing so, an overlay address within that neighborhood will be generated when starting Bee for the first time. ```yaml -## bee.yaml +# bee.yaml target-neighborhood: "0010100001" ``` diff --git a/docs/bee/installation/shell-script.md b/docs/bee/installation/shell-script.md index fb7f70489..8ecd3537a 100644 --- a/docs/bee/installation/shell-script.md +++ b/docs/bee/installation/shell-script.md @@ -7,8 +7,6 @@ description: Provides flexible installation using an automated shell script supp import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -# Swarm Shell Script Installation Guide - The official [shell script](https://github.com/ethersphere/bee/blob/master/install.sh) provided by Swarm automatically detects your system and installs the correct version of Bee. This installation method is an excellent choice if you're looking for a minimalistic and flexible option for your Bee node installation. :::warning diff --git a/docs/bee/working-with-bee/configuration.md b/docs/bee/working-with-bee/configuration.md index 8b12620a9..4695c9b8d 100644 --- a/docs/bee/working-with-bee/configuration.md +++ b/docs/bee/working-with-bee/configuration.md @@ -586,7 +586,7 @@ Full and light Bee nodes require a Gnosis Chain RPC endpoint in order to sync bl To set your RPC endpoint, specify it with the `blockchain-rpc-endpoint` value, which is set to an empty string by default. ```yaml -## bee.yaml +# bee.yaml blockchain-rpc-endpoint: https://xdai.fairdatasociety.org ``` @@ -606,7 +606,7 @@ Bee periodically reads the current block number from your blockchain RPC endpoin The `block-sync-interval` option controls how frequently the real block number is refreshed: ```yaml -## bee.yaml +# bee.yaml block-sync-interval: 10 ``` @@ -629,7 +629,7 @@ It is currently available **only on Linux x86-64 (amd64)**; on all other platfor To enable it, set the `use-simd-hashing` option: ```yaml -## bee.yaml +# bee.yaml use-simd-hashing: true ``` @@ -648,7 +648,7 @@ This feature is **disabled by default** and only applies to full nodes with cheq To enable chequebook verification, set `chequebook-verification` to `true`: ```yaml -## bee.yaml +# bee.yaml chequebook-verification: true ``` @@ -657,7 +657,7 @@ The value is set in the token's smallest unit (PLUR), where 1 BZZ = 10^16 PLUR, To configure a different threshold, set `chequebook-min-balance` accordingly: ```yaml -## bee.yaml +# bee.yaml chequebook-verification: true chequebook-min-balance: "110000000000000000" # 11 BZZ, expressed in PLUR ``` @@ -694,7 +694,7 @@ curl icanhazip.com Then configure your node, including your p2p port (default 1634). ```yaml -## bee.yaml +# bee.yaml nat-addr: "123.123.123.123:1634" ``` @@ -707,7 +707,7 @@ The [ENS](https://ens.domains/) domain resolution system is used to host website If you do not wish to run your own Ethereum node, you may use a blockchain RPC service provider such as [Infura](https://infura.io). After signing up for Infura, simply set your `--resolver-options` to `https://mainnet.infura.io/v3/your-api-key`. ```yaml -## bee.yaml +# bee.yaml resolver-options: ["https://mainnet.infura.io/v3/<>"] ``` diff --git a/docs/bee/working-with-bee/logs-and-files.md b/docs/bee/working-with-bee/logs-and-files.md index cb061d350..c0b483186 100644 --- a/docs/bee/working-with-bee/logs-and-files.md +++ b/docs/bee/working-with-bee/logs-and-files.md @@ -4,8 +4,6 @@ id: logs-and-files description: Guides log access rotation verbosity levels and structured logging integration with monitoring tools like Prometheus and Grafana. --- -# Logging in Bee - This section provides an overview of logging in Bee, including log locations, exporting logs, managing verbosity levels, and using fine-grained control for specific loggers. :::info diff --git a/docs/bee/working-with-bee/monitoring.md b/docs/bee/working-with-bee/monitoring.md index 8e80795d0..b83beb30a 100644 --- a/docs/bee/working-with-bee/monitoring.md +++ b/docs/bee/working-with-bee/monitoring.md @@ -4,7 +4,7 @@ id: monitoring description: Explains how to monitor Bee node metrics using Prometheus and Grafana for tracking cheque rates and network performance. --- -Your Bee node is equipped with tools to help you understand what your Bee has been up to! +Bee nodes expose runtime metrics in Prometheus format, which you can collect and visualise with Grafana to understand what your Bee has been up to. Navigate to `http://localhost:1633/metrics`. diff --git a/docs/bee/working-with-bee/node-types.md b/docs/bee/working-with-bee/node-types.md index 35f7e7cdb..ae3ea43f8 100644 --- a/docs/bee/working-with-bee/node-types.md +++ b/docs/bee/working-with-bee/node-types.md @@ -13,7 +13,7 @@ Bee nodes can operate in three different modes depending on the user's needs, ra 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. -## Node Types Overview +## What are the Bee node types? {#node-types-overview} Bee can operate in different modes, each tailored to specific use cases: @@ -28,14 +28,14 @@ Bee can operate in different modes, each tailored to specific use cases: | [PSS messaging](./../../develop/tools-and-features/pss.md) | ✅ | ❌ | ❌ | -## Full Node +## 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 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. -### Recommended Specifications +### 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. @@ -50,7 +50,7 @@ Requires significant storage and processing power compared to other node types: - **Storage**: 30 GB SSD (HDD not recommended). - **Internet**: High-speed and stable connection. -### Configuration +### Full node configuration To run Bee as a full node, set: @@ -69,7 +69,7 @@ To run Bee as a full node, set: - Supports full PSS messaging and GSOC. -## Light Node +## What is a light node? {#light-node} 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. @@ -81,11 +81,11 @@ Light node operators cannot earn xBZZ by participating in Swarm's incentives sys Light nodes do not benefit from plausible deniability when requesting data from the network. They are always the originator of requests. ::: -### Recommended Specifications +### Light node specifications No specific hardware is required to run a light node. It can run well on practically any commercially available computer released in recent years, including lightweight single-board computers such as [Raspberry Pi](https://en.wikipedia.org/wiki/Raspberry_Pi). Your downloads / uploads may be limited by your network speed, however, so if you plan on interacting extensively with the Swarm network, you should take your connection speed into consideration. -### Configuration +### Light node configuration To run Bee as a light node, set: @@ -109,7 +109,7 @@ To run Bee as a light node, set: - Can send outgoing GSOC updates but ***cannot*** receive them. -## Ultra-Light Node +## What is an ultra-light node? {#ultra-light-node} Ultra-light nodes allow users to run a node without requiring a blockchain RPC endpoint. These nodes can download data within the free consumption threshold set by full nodes (this threshold may vary since it is [configurable](./configuration.md) by full node operators using the `payment-tolerance-percent` and `payment-threshold` options). @@ -123,11 +123,11 @@ As with light nodes, ultra-light nodes do not benefit from plausible deniability When running without a blockchain connection, [bandwidth incentive payments (SWAP)](./../../concepts/incentives/bandwidth-incentives.md) cannot be made, increasing the risk of being blocklisted by other peers for exceeding their free-tier download limits. ::: -### Recommended Specifications +### Ultra-light node specifications As with the light node, there are no specific requirements to run an ultra-light node, and it will run on practically any commercially available hardware from recent years. -### Configuration +### Ultra-light node configuration Bee will start in ultra-light mode by default, but in order to explicitly configure your node to run as an ultra-light node, use the following options: diff --git a/docs/bee/working-with-bee/staking.md b/docs/bee/working-with-bee/staking.md index 1faedfa0d..736de5a76 100644 --- a/docs/bee/working-with-bee/staking.md +++ b/docs/bee/working-with-bee/staking.md @@ -4,6 +4,8 @@ id: staking description: Walkthrough of depositing xBZZ to participate in the storage incentives redistribution game and earn network rewards. --- +Staking locks up xBZZ so your full node can join the **redistribution game** and earn a share of the network's storage-rent rewards. Staking requires a fully synced full node and a minimum of 10 xBZZ, and the stake is non-refundable. + ## Quickstart Guide This guide will walk you through **staking xBZZ** and participating in the **redistribution game** to earn storage incentives. @@ -123,7 +125,7 @@ Only stake your xBZZ if you intend to participate as a full node, as withdrawals ### Requirements -- A [full node](./node-types.md) - see full node [recommend specs](./node-types.md#recommended-specifications). +- A [full node](./node-types.md) - see full node [recommend specs](./node-types.md#full-node-specifications). - A [high-performance RPC endpoint](./configuration.md#setting-blockchain-rpc-endpoint) connection to Gnosis Chain. - A minimum of 10 xBZZ to be used as ***non-refundable*** stake (the requirement is increased if [reserve doubling](./staking.md#reserve-doubling) is used). @@ -404,7 +406,7 @@ Copy the binary number returned from the API: Use the binary number you just copied and set it as a string value for the `target-neighborhood` option in your config. ```bash -## bee.yaml +# bee.yaml target-neighborhood: "01100011110" ``` diff --git a/docs/concepts/DISC/DISC.mdx b/docs/concepts/DISC/DISC.mdx index 5f1fb6d90..d9d927cb8 100644 --- a/docs/concepts/DISC/DISC.mdx +++ b/docs/concepts/DISC/DISC.mdx @@ -1,31 +1,31 @@ --- title: DISC id: disc -description: Overview of Swarm's Distributed Immutable Storage of Chunks system using Kademlia neighborhoods and synchronization protocols. +description: Overview of Swarm's Distributed Immutable Store for Chunks system using Kademlia neighborhoods and synchronization protocols. --- import bos_fig_2_7 from '/static/img/bos_fig_2_7.jpg'; -DISC (Distributed Immutable Storage of Chunks) is a storage solution developed by Swarm based on a modified implementation of a [Kademlia DHT](./kademlia.mdx) which has been specialized for data storage. Swarm's implementation of a DHT differs significantly in that it stores the content in the DHT directly, rather than just storing a list of seeders who are able to serve the content. This approach allows for much faster and more efficient retrieval of data. +DISC (Distributed Immutable Store for Chunks) is a storage solution developed by Swarm based on a modified implementation of a [Kademlia DHT](./kademlia.mdx) which has been specialized for data storage. Swarm's implementation of a DHT differs significantly in that it stores the content in the DHT directly, rather than just storing a list of seeders who are able to serve the content. This approach allows for much faster and more efficient retrieval of data. -### Kademlia Topology and Routing +## Kademlia Topology and Routing [Kademlia](./kademlia.mdx) is a distributed hash table (DHT) widely used in peer-to-peer networks such as Ethereum and Bittorent. It serves as the routing and topology foundation for communication between nodes in the Swarm network. It organizes nodes based on their overlay addresses and ensures that messages are relayed efficiently, even in a dynamic, decentralized environment. One of the advantages of using Kademlia as a model for network topology is that both the number of forwarding "hops" required to route a chunk to its destination and the number of peer connections required to maintain Kademlia topology are logarithmic to the size of the network (a minimum of two connections is required in order to maintain Kademlia topology in case of network churn - nodes dropping in and out of the network). This makes Swarm a highly scalable system which is efficient even at very large scales. -### Neighborhoods +## Neighborhoods [Neighborhoods](./neighborhoods.md) are groups of nodes which are responsible for sharing the same chunks. The chunks which each neighborhood is responsible for storing are defined by the proximity order of the nodes and the chunks. In other words, each node is responsible for storing chunks with which their overlay addresses share a certain number of prefix bits, and together with other nodes which share the same prefix bits, make up neighborhoods which share the responsibility for storing the same chunks. Neighborhoods play a key role in providing data redundancy for chunks stored on Swarm since each node in a neighborhood will keep copies of the same chunks. The optional [erasure coding](./erasure-coding.md) feature can also be enabled for added redundancy and greater data protection. -### Chunks +## Chunks In the DISC model, chunks are the canonical unit of data. When a file is uploaded to Swarm, it gets broken down into 4kb pieces with attached metadata. The pieces then get distributed amongst nodes in the Swarm network based on their [overlay addresses](./../../references/glossary.md#overlay). There are two fundamental chunk types: content-addressed chunks and single-owner chunks. -#### Content-Addressed Chunks and Single-Owner Chunks +### Content-Addressed Chunks and Single-Owner Chunks Content-addressed chunks are chunks whose address is based on the hash digest of their data. Using a hash as the chunk address makes it possible to verify the integrity of chunk data. Swarm uses the BMT hash function based on a binary Merkle tree over small segments of the chunk data. A content-addressed chunk has an at most 4KB payload, and its address is calculated as the hash of the span (chunk metadata) and the Binary Merkle Tree hash of the payload. @@ -39,7 +39,6 @@ Content-addressed chunks are chunks whose address is based on the hash digest of For single-owner chunks on the other hand, the address is calculated as the hash of a unique id and the owner's overlay address. The content consists of an arbitrary data payload along with required headers. Unlike a content-addressed chunk, the contents of a single-owner chunk may be updated while the address remains unchanged. Single owner chunks form the basis for feeds, which are data structures that allow for mutable content with a static address. -### Push-Sync, Pull-Sync, and Retrieval Protocols - -When a file is first uploaded to Swarm, it gets broken down by the uploading Bee node chunks which are then distributed amongst other Bee nodes in the Swarm network. Chunks get distributed to the target neighborhood by the ***push-sync*** protocol. Once a chunk reaches its destination, it will then be duplicated and synced to other nodes in order to achieve data redundancy through the ***pull-sync*** protocol. The pull-sync protocol operates continuously as nodes enter or exit the network – ensuring that data redundancy is always maintained. When a client node requests a file for download, its request gets forwarded by the ***retrieval-protocol*** to all the nodes storing the relevant chunks, and then those chunks get returned to the requesting node and the file gets reconstructed from its constituent chunks. +## Push-Sync, Pull-Sync, and Retrieval Protocols +When a file is first uploaded to Swarm, it gets broken down by the uploading Bee node chunks which are then distributed amongst other Bee nodes in the Swarm network. Chunks get distributed to the target neighborhood by the ***push-sync*** protocol. Once a chunk reaches its destination, it will then be duplicated and synced to other nodes in order to achieve data redundancy through the ***pull-sync*** protocol. The pull-sync protocol operates continuously as nodes enter or exit the network – ensuring that data redundancy is always maintained. When a client node requests a file for download, its request gets forwarded by the ***retrieval-protocol*** to all the nodes storing the relevant chunks, and then those chunks get returned to the requesting node and the file gets reconstructed from its constituent chunks. diff --git a/docs/concepts/DISC/erasure-coding.md b/docs/concepts/DISC/erasure-coding.md index 830cad6f1..29d741c51 100644 --- a/docs/concepts/DISC/erasure-coding.md +++ b/docs/concepts/DISC/erasure-coding.md @@ -6,7 +6,7 @@ description: Explains optional data protection technique using redundant chunks Erasure coding (also known as erasure code) is an efficient and flexible approach to data protection which is an optional feature for Swarm uploads. It is a technique that increases data protection by enabling the recovery of original data even when some encoded chunks are lost or corrupted. When used, it ensures that data on Swarm can always be accessed reliably, even if some nodes or entire neighborhoods go offline. Refer to the [official erasure coding paper](https://papers.ethswarm.org/p/erasure/) for more in depth details. -## How It Works +## How does erasure coding work? {#how-it-works} Erasure coding enhances data protection by dividing the source data into "chunks" and adding additional redundant chunks. diff --git a/docs/concepts/incentives/price-oracle.md b/docs/concepts/incentives/price-oracle.md index 6d0d52cd3..4690d259d 100644 --- a/docs/concepts/incentives/price-oracle.md +++ b/docs/concepts/incentives/price-oracle.md @@ -4,9 +4,12 @@ id: price-oracle description: Describes smart contract mechanism for dynamically adjusting postage stamp prices based on network utilization data. --- +## How does the price oracle set stamp prices? {#stamp-prices} + The job of the [oracle contract](https://github.com/ethersphere/storage-incentives/blob/master/src/PriceOracle.sol) is to set the price of postage stamps. The oracle contract uses data from the [redistribution contract](https://github.com/ethersphere/storage-incentives/blob/master/src/Redistribution.sol) in order to set the appropriate price for postage stamps through the [postage stamp contract](https://github.com/ethersphere/storage-incentives/blob/master/src/PostageStamp.sol). The data from the redistribution contract is used to calculate a "utilisation signal". This signal is an indicator of how much the Swarm network’s data storage capacity is being utilized. Specifically, the signal is a measure of data redundancy on the network. Redundancy is a measure of how many copies of each piece of data can be stored by the network. The protocol targets a fourfold level of data redundancy as a safe minimum. +## How does the price adjust to network demand? {#network-demand} + For example, if there is an increase in postage stamps being purchased while the number of nodes remains constant, the data redundancy level will begin to fall as data storers’ available space begins to become reserved. If too many postage stamps are purchased without an equivalent increase in storage providers, the redundancy level may fall below four. In this case, the oracle will increase the price of postage stamps so that it becomes more expensive to store data on Swarm. The higher cost of storage will then lead to less postage stamps being purchased, and will push the redundancy level back up towards four. Conversely, if the amount of Stamps being purchased decreases while the number of storage provider nodes remains constant, the redundancy level will increase as there are fewer chunks of data to be distributed amongst the same number of nodes. In this case, the oracle will decrease the Postage Stamp price in order to promote more data storers to store their data on Swarm. The lower cost of storage will then lead to more Postage Stamps being purchased and push the redundancy level back down towards four. - diff --git a/docs/concepts/incentives/redistribution-game.md b/docs/concepts/incentives/redistribution-game.md index cf87cdde9..a2c90cb57 100644 --- a/docs/concepts/incentives/redistribution-game.md +++ b/docs/concepts/incentives/redistribution-game.md @@ -6,7 +6,7 @@ description: Explains game-theoretic system distributing xBZZ from postage stamp The redistribution game distributes xBZZ collected from [postage stamp](./postage-stamps.md) purchases, rewarding nodes for providing storage. Redistribution rewards incentivize nodes to continue providing storage to the network. The game is designed so that the most profitable strategy for participants is to store their assigned data honestly. -### Redistribution Game Details +## How does the redistribution game work? {#redistribution-game-details} Uploading data to Swarm requires purchasing postage stamp batches with xBZZ. The collected xBZZ is later redistributed as rewards to storage nodes. Every 152 Gnosis Chain blocks ***a single [neighborhood](./../DISC/neighborhoods.md)*** is selected to play the redistribution game. For each round of the game, one node from the selected neighborhood will have the chance to win a reward which is paid out from the accumulated xBZZ. @@ -21,7 +21,7 @@ $$ $$ -### Penalties +## What penalties apply for dishonest nodes? {#penalties} During the `reveal` phase if a nodes' revealed hash does not match the honest nodes' hash, that node will be temporarily frozen and will not be able to participate in a number of upcoming rounds. Currently the freeze period is defined in the [redistribution smart contract](https://github.com/ethersphere/storage-incentives/blob/master/src/Redistribution.sol#L536C1-L536C100) as: diff --git a/docs/concepts/what-is-swarm.mdx b/docs/concepts/what-is-swarm.mdx index 606245601..fb8536be8 100644 --- a/docs/concepts/what-is-swarm.mdx +++ b/docs/concepts/what-is-swarm.mdx @@ -6,16 +6,14 @@ description: Details Swarm's four-layer architecture including underlay overlay import bos_fig_1_1 from '/static/img/bos_fig_1_1.jpg'; -# What is Swarm? +Swarm is a peer-to-peer network of nodes which work together to provide decentralised storage and communication infrastructure. The complete vision of Swarm is described in detail in [The Book of Swarm](https://papers.ethswarm.org/p/book-of-swarm/) written by Swarm founder Viktor Tron, with further high level details described in the [whitepaper](https://papers.ethswarm.org/p/whitepaper/). More in depth low level implementation details can be found in the [Swarm Specification paper](https://papers.ethswarm.org/p/swarm-protocol-spec/). The latest research and technical papers from Swarm can be found on the ["Papers" section](https://papers.ethswarm.org/) of the Ethswarm homepage. -Swarm is peer-to-peer network of nodes which work together to provide decentralised storage and communication infrastructure. - Swarm can be divided into four main parts: 1. Underlay Network - A peer-to-peer network protocol to serve as underlay transport. Swarm's underlay network is built with [libp2p](https://libp2p.io/). -2. Overlay Network - An overlay network with protocols powering a distributed immutable storage of chunks (fixed size data blocks). +2. Overlay Network - An overlay network with protocols powering a distributed immutable store for chunks (fixed size data blocks). 3. Data Access Layer - A component providing high-level data access and defining APIs for base-layer features. 4. Application Layer - An application layer defining standards and outlining best practices for more elaborate use cases. @@ -61,5 +59,4 @@ Swarm's high-level data access component provides [APIs that allow developers to ### 4. Application Layer -The fourth part of Swarm is an application layer that defines standards and outlines best practices for more elaborate use cases. This layer is responsible for providing guidance to developers on [how to build complex applications](./../develop/introduction.md) on top of Swarm's underlying infrastructure. - +The fourth part of Swarm is an application layer that defines standards and outlines best practices for more elaborate use cases. This layer is responsible for providing guidance to developers on [how to build complex applications](./../develop/introduction.md) on top of Swarm's underlying infrastructure. diff --git a/docs/desktop/access-content.md b/docs/desktop/access-content.md index c3918cdcf..6c84976b4 100644 --- a/docs/desktop/access-content.md +++ b/docs/desktop/access-content.md @@ -1,7 +1,7 @@ --- title: Access Content id: access-content -description: Guide for using Swarm Desktop application to download and retrieve content from the Swarm network. +description: Download and retrieve content from Swarm using the Swarm Desktop app. --- Accessing content on Swarm using Swarm Desktop is easy. All you need to get started is the Swarm hash for the content you wish to access. Whenever content is [uploaded to Swarm](./upload-content.md) a Swarm hash is generated as a reference to that content. diff --git a/docs/desktop/backup-restore.md b/docs/desktop/backup-restore.md index 8d27ae0a3..cbac256b5 100644 --- a/docs/desktop/backup-restore.md +++ b/docs/desktop/backup-restore.md @@ -1,7 +1,7 @@ --- title: Backup and Restore id: backup-restore -description: Instructions for backing up and restoring wallet keys and data in the Swarm Desktop application. +description: Back up and restore your Bee node's wallet keys and data in the Swarm Desktop app. --- ## Create a Backup diff --git a/docs/desktop/configuration.md b/docs/desktop/configuration.md index f349eac7e..38a3e11ba 100644 --- a/docs/desktop/configuration.md +++ b/docs/desktop/configuration.md @@ -1,7 +1,7 @@ --- title: Configuration id: configuration -description: Explains configuration options and settings available in the Swarm Desktop user interface. +description: Adjust your Bee node's settings through the Swarm Desktop app. --- diff --git a/docs/desktop/install.md b/docs/desktop/install.md index 6555f9e7d..1dbe439b2 100644 --- a/docs/desktop/install.md +++ b/docs/desktop/install.md @@ -1,7 +1,7 @@ --- title: Install id: install -description: Provides installation instructions for the Swarm Desktop GUI application on Windows macOS and Linux. +description: Install the Swarm Desktop app on Windows, macOS, or Linux to run a Bee node with a graphical interface. --- ## Download and Install Swarm Desktop @@ -34,7 +34,7 @@ Once the installation is complete, Swarm Desktop will open up in your default br If the installation went smoothly, you should see the message "Your node is connected" above the "Access Content" button along with a status message of "Node OK". -#### What Just Happened? +### What Just Happened? Running the Swarm Desktop app for the first time set up a new Bee node on your system. The installation process generated and saved private keys for your node in the Swarm Desktop's data directory. Those keys were used to start up a new Bee node in ultra-light mode. diff --git a/docs/desktop/introduction.md b/docs/desktop/introduction.md index b9eee866d..40d31f2c2 100644 --- a/docs/desktop/introduction.md +++ b/docs/desktop/introduction.md @@ -1,13 +1,13 @@ --- title: Introduction id: introduction -description: Overview of Swarm Desktop graphical interface for managing nodes uploading and downloading content. +description: Swarm Desktop is a graphical app for Windows, Mac, and Linux that runs a Bee node and uploads and downloads content without the command line. --- ![](/img/swarm-desktop.png) -While running Bee from the terminal is a powerful and flexible approach for developers and node operators, it may not be the best option for more simple use cases. +The Swarm Desktop app provides an easy-to-use graphical user interface for running a Bee node and interacting seamlessly with the Swarm network. -The Swarm Desktop app is an alternative which provides an easy-to-use graphical user interface for running a Bee node and interacting seamlessly with the Swarm network. +While running Bee from the terminal is a powerful and flexible approach for developers and node operators, the Swarm Desktop app is a simpler alternative for more basic use cases. The Swarm Desktop App was designed to simplify the Swarm onboarding process so that anyone can benefit from decentralized storage while maintaining privacy and control over their data. Available for Windows, Mac, and Linux operating systems, the Swarm Desktop App serves as a personal gateway to the Swarm network. diff --git a/docs/desktop/postage-stamps.md b/docs/desktop/postage-stamps.md index 26bbd3147..9484ebe09 100644 --- a/docs/desktop/postage-stamps.md +++ b/docs/desktop/postage-stamps.md @@ -1,7 +1,7 @@ --- title: Postage Stamps id: postage-stamps -description: Guide for purchasing and managing postage stamp batches through the Swarm Desktop interface. +description: Buy and manage postage stamp batches — the prepaid storage needed to upload — from the Swarm Desktop app. --- diff --git a/docs/desktop/publish-a-website.md b/docs/desktop/publish-a-website.md index 63548efcd..c035e44fa 100644 --- a/docs/desktop/publish-a-website.md +++ b/docs/desktop/publish-a-website.md @@ -1,7 +1,7 @@ --- title: Publish a Website id: publish-a-website -description: Step-by-step instructions for uploading and hosting websites on Swarm using the Desktop application. +description: Publish a static website to Swarm from the Swarm Desktop app and access it via a Swarm hash. --- ## Step by Step Guide diff --git a/docs/desktop/start-a-blog.md b/docs/desktop/start-a-blog.md index dda3d9e9b..ac4aa7bd4 100644 --- a/docs/desktop/start-a-blog.md +++ b/docs/desktop/start-a-blog.md @@ -1,7 +1,7 @@ --- title: Start a Blog id: start-a-blog -description: Tutorial for creating and publishing blog content on Swarm with the Desktop application. +description: Create and publish a blog on Swarm using the Swarm Desktop app. --- ## A Guide to Starting Your Blog on Swarm diff --git a/docs/desktop/upload-content.md b/docs/desktop/upload-content.md index 5233538f6..571b90dff 100644 --- a/docs/desktop/upload-content.md +++ b/docs/desktop/upload-content.md @@ -1,7 +1,7 @@ --- title: Upload Content id: upload-content -description: Instructions for uploading files and directories to Swarm through the Desktop application interface. +description: Upload files and directories to Swarm from the Swarm Desktop app and get a shareable Swarm reference. --- After [purchasing a batch of postage stamps](./postage-stamps.md) you will be able to upload files. First go to the “Files” tab. Here you can choose between three options, depending on what you want to upload: a single file, a folder or a website. After choosing your option you’ll need to add a postage stamp. diff --git a/docs/develop/access-control.md b/docs/develop/access-control.md index bc2135da0..5169d5d33 100644 --- a/docs/develop/access-control.md +++ b/docs/develop/access-control.md @@ -11,7 +11,7 @@ This is guide contains a detailed explanation of how to use the ACT feature, but In this section we'll provide information on how to use the **swarm-cli** to upload, download data with ACT or update the grantee list. -### Upload +## Upload Uploading data without ACT to the network remains unchanged. @@ -26,7 +26,7 @@ If the provided **act-history-address** is invalid then the request will fail wi The response returns the newly created reference encrypted with ACT and the header contains history reference. -### Download +## Download Downloading data which was uploaded without ACT from the network remains unchanged. @@ -39,11 +39,11 @@ Here **act** indicates that the **swarm_hash** shall be decrypted using the cont If the **act-history-address** or **act-publisher** flags are omitted then the request is treated as a "usual" download. If the data was uploaded with ACT and we try to download it without the ACT flags then the request will fail with a not found error. -### Grantee management +## Grantee management Updating a grantee list literally means patching a json file containing the list of grantee swarm public keys. -#### Create +### Create A brand new grantee list can be created using the following command: ```bash @@ -61,7 +61,7 @@ where **grantees.json** shall contain the key **grantees** with the list of publ The response returns the newly created and encrypted grantee list and the history reference. Only the publisher can decrypt and therefore access the list. If **act-history-address** is provided then the grantee list is uploaded as the newest version under that history. -#### Patch +### Patch ```bash swarm-cli grantee patch grantees-patch.json --reference $grantee_reference --history $grantee_history_reference --stamp $stamp_id @@ -80,7 +80,7 @@ The **grantee_history_reference** indicates the reference of historical version **Limitation**: If an update is called again within a second from the latest upload/update of a grantee list, then mantaray save fails with an invalid input error, because the key (timestamp) already exists, hence a new fork is not created. -#### Get +### Get As stated above, only the publisher can decrypt and therefore access the list with the following command: ```bash diff --git a/docs/develop/contribute/introduction.md b/docs/develop/contribute/introduction.md index fc361c56f..bfdeb3270 100644 --- a/docs/develop/contribute/introduction.md +++ b/docs/develop/contribute/introduction.md @@ -1,14 +1,13 @@ --- -title: Introduction +title: Contribute to Bee Development id: introduction +sidebar_label: Overview description: Overview of how to contribute to Bee development including code standards and contribution process. --- -# Contribute to Bee Development +Bee is developed in the open on GitHub, and contributions are welcome via pull request. We love PRs! 🐝 -Welcome to the Dev area! We love PR's! 🐝 - -We would would love you to get involved with our [Github repo](https://github.com/ethersphere/bee). +We would love you to get involved with our [Github repo](https://github.com/ethersphere/bee). Connect with other Bee developers over at the official [Discord Server](https://discord.gg/kHRyMNpw7t). Sign up and get involved with our buzzing hive of daily dev chat. diff --git a/docs/develop/files.md b/docs/develop/files.md index c6fedb0bc..6954f29ea 100644 --- a/docs/develop/files.md +++ b/docs/develop/files.md @@ -2,12 +2,10 @@ title: Manage Files id: files sidebar_label: Manage Files -description: Guide for working with file operations including chunking and handling in Swarm applications. +description: Upload, download, and manage files, directories, and collections on Swarm using the Bee API and bee-js. --- -# Manage Files - In the [Host a Webpage](/docs/develop/host-your-website) guide you uploaded a directory and got back a single Swarm reference that serves your site. That reference points to a **manifest** — a data structure that maps relative paths to content. This guide explores manifests directly: how to inspect them, add a file without re-uploading everything, and move a file by remapping a path. Swarm does not have a traditional filesystem — there are no mutable directories, in-place updates, or a built-in directory structure that preserves relationships between files. Instead, these capabilities are provided through the use of [manifests](./tools-and-features/manifests.md), which map relative paths (such as `/images/cat.jpg`) to immutable Swarm content references. When you upload a directory, Bee creates a manifest automatically and returns its reference. Files can then be accessed using paths that are relative to that manifest reference, based on the original directory structure. This provides filesystem-like behavior for your data, and the directory structure can later be changed by publishing a new version of the manifest with the desired updates. diff --git a/docs/develop/gateway.md b/docs/develop/gateway.md index 4b0313c27..4694c2e08 100644 --- a/docs/develop/gateway.md +++ b/docs/develop/gateway.md @@ -1,10 +1,10 @@ --- title: Run a Gateway id: gateway-proxy -description: Explains Bee gateway functionality for accessing Swarm content through HTTP interfaces. +description: Run a Bee node as a public HTTP gateway so anyone can access Swarm-hosted content from an ordinary web browser. --- -At this point you can build and deploy complete Swarm-hosted websites with working routing. This guide is an **operational step**: it shows how to make those sites accessible to the public web through an HTTP gateway, so that anyone with a browser can reach them without running their own Bee node. +A Swarm gateway is an HTTP server that makes Swarm-hosted websites reachable from an ordinary web browser, without visitors needing to run their own Bee node. This guide shows how to run your Bee node as a public HTTP gateway. This guide explains how to use the [swarm-gateway](https://github.com/ethersphere/swarm-gateway) tool to set up your node in gateway mode. Running your node in gateway mode exposes it publicly, allowing access through any typical browser or http API. diff --git a/docs/develop/host-your-website.md b/docs/develop/host-your-website.md index 556ecb6c9..2d70d5cee 100644 --- a/docs/develop/host-your-website.md +++ b/docs/develop/host-your-website.md @@ -96,7 +96,7 @@ Anyone with access to it can publish to your feed. *It is recommended to use a separate publishing key for each feed.* ::: -#### Example Script +### Example Script :::tip The script below refers to some core feed concepts such as the feed "topic" and "writer". To learn more about these concepts and feeds in general, refer to the [bee-js documentation](https://bee-js.ethswarm.org/docs/soc-and-feeds/#feeds). @@ -174,7 +174,7 @@ or through your own node: http://localhost:1633/bzz/yourname.eth/ ``` -#### Using the Official ENS Guide +### Using the Official ENS Guide ENS provides a clear walkthrough with screenshots showing how to add a content hash to your domain with their [easy to use app](https://app.ens.domains/): @@ -188,7 +188,7 @@ The guide covers: * Confirming the transaction -#### Swarm-Specific Step +### Swarm-Specific Step When you reach Step 2 in the ENS guide (“Add content hash record”), enter your Swarm reference in the following format: diff --git a/docs/develop/introduction.md b/docs/develop/introduction.md index 49073bd91..e1755e23c 100644 --- a/docs/develop/introduction.md +++ b/docs/develop/introduction.md @@ -1,15 +1,13 @@ --- -title: Start Building +title: Building on Swarm id: introduction sidebar_label: Start Building hide_table_of_contents: false pagination_prev: null pagination_next: null -description: Overview of development on Swarm including APIs tools and use cases for building applications. +description: Swarm lets developers store data, host websites, and build decentralised apps using the Bee HTTP API and the bee-js SDK. --- -# Building on Swarm - This is the go-to starting point for web3 developers who want to build with Swarm. The guides on this page will help you get started with setting up a Bee node, using that node to integrate your dApp with Swarm, and to begin exploring some example applications to better understand the possibilities of building on Swarm. ## Setup diff --git a/docs/develop/routing.md b/docs/develop/routing.md index 58f6e72b1..d5c10392b 100644 --- a/docs/develop/routing.md +++ b/docs/develop/routing.md @@ -5,8 +5,6 @@ description: Explains message routing protocols and peer discovery mechanisms in --- -# Routing on Swarm - In the [Manage Files](/docs/develop/files) guide you saw that a directory upload creates a manifest — a data structure mapping paths to content. Routing on Swarm is a direct consequence: every URL your site serves must correspond to an entry in that manifest. This guide covers the two main strategies for giving your site clean, navigable URLs. Swarm does not behave like a traditional web server — there is no server-side routing, and every route must correspond to a real file inside the site [manifest](./tools-and-features/manifests.md). @@ -47,7 +45,7 @@ Swarm has no server backend running code and so can’t rewrite paths. One appro You can do this easily using a template from **create-swarm-app** and then adding your own pages. -#### 1. Create a New Vite + React Project (with `create-swarm-app`) +### 1. Create a New Vite + React Project (with `create-swarm-app`) Run: @@ -70,7 +68,7 @@ package.json You now have a fully working Vite/React app ready for Swarm uploads. -#### 2. Install React Router +### 2. Install React Router Navigate to the project directory: @@ -88,7 +86,7 @@ This gives you client-side navigation capability. -#### 3. Switch the App to Use Hash-Based Routing +### 3. Switch the App to Use Hash-Based Routing Swarm only serves literal files, so `/#/about` is the only reliable way to have “pages.” @@ -126,7 +124,7 @@ This gives you usable routes: /#/anything → React 404 page ``` -#### 4. Add Your Page Components +### 4. Add Your Page Components Create your page components inside `./src`: @@ -169,7 +167,7 @@ export function NotFound() { } ``` -#### 5. Add a Static `404.html` for Non-Hash URLs +### 5. Add a Static `404.html` for Non-Hash URLs Swarm still needs a fallback for URLs like: @@ -209,7 +207,7 @@ Vite will automatically include this in `dist/`. This file handles **non-hash** missing paths. React handles **hash** missing paths. -#### 6. Build the Project +### 6. Build the Project Before uploading, compile the Vite app into a static bundle: @@ -228,7 +226,7 @@ dist/ Everything inside `dist/` will be uploaded to your Swarm feed. -#### 7. Deploy Site +### 7. Deploy Site The project includes an `upload.js` script that uploads `./dist` to Swarm and publishes the result to a feed (so your URL stays stable across re-uploads). Set up your `.env` and run it: diff --git a/docs/develop/tools-and-features/buy-a-stamp-batch.md b/docs/develop/tools-and-features/buy-a-stamp-batch.md index be51797c9..ff23b7749 100644 --- a/docs/develop/tools-and-features/buy-a-stamp-batch.md +++ b/docs/develop/tools-and-features/buy-a-stamp-batch.md @@ -84,8 +84,6 @@ values={[ ]}> -#### API - ```bash curl -s -X POST http://localhost:1633/stamps/100000000/20 ``` @@ -101,8 +99,6 @@ curl -s -X POST http://localhost:1633/stamps/100000000/20 -#### Swarm CLI - ```bash swarm-cli stamp buy --depth 20 --amount 100000000 ``` @@ -184,8 +180,6 @@ values={[ ]}> -#### API - ```bash curl http://localhost:1633/stamps @@ -216,8 +210,6 @@ curl http://localhost:1633/stamps -#### Swarm CLI - ```bash swarm-cli stamp list ``` @@ -258,9 +250,6 @@ values={[ ]}> -#### API - - ```bash curl http://localhost:1633/stamps ``` @@ -290,8 +279,6 @@ curl http://localhost:1633/stamps -#### Swarm CLI - ```bash swarm-cli stamp list ``` @@ -324,8 +311,6 @@ values={[ ]}> -#### API - ```bash curl -X PATCH "http://localhost:1633/stamps/topup/6d32e6f1b724f8658830e51f8f57aa6029f82ee7a30e4fc0c1bfe23ab5632b27/10000000" ``` @@ -334,8 +319,6 @@ curl -X PATCH "http://localhost:1633/stamps/topup/6d32e6f1b724f8658830e51f8f57aa -#### Swarm CLI - List available stamps. ```bash @@ -383,8 +366,6 @@ values={[ ]}> -#### API - Here we call the `/stamps` endpoint and find a batch with `depth` 24 and a `batchTTL` of 2083223 which we wish to dilute: @@ -460,8 +441,6 @@ We can see the new `depth` of 26 and a decreased `batchTTL` of 519265. -#### Swarm CLI - List available stamps, make sure to use the `--verbose` flag so that we can see the batch depth. ```bash @@ -528,4 +507,4 @@ If the content is not retrievable, an HTTP PUT request can be used to re-upload curl -X PUT "http://localhost:1633/stewardship/c0c2b70b01db8cdfaf114cde176a1e30972b556c7e72d5403bea32ec0207136f" ``` -Note that for the re-upload to succeed, the associated content must be available locally, either pinned or cached. Since it isn't easy to predict if the content will be cached, for important content pinning is recommended. \ No newline at end of file +Note that for the re-upload to succeed, the associated content must be available locally, either pinned or cached. Since it isn't easy to predict if the content will be cached, for important content pinning is recommended. diff --git a/docs/develop/tools-and-features/feeds.md b/docs/develop/tools-and-features/feeds.md index de7ce47ef..abe031d95 100644 --- a/docs/develop/tools-and-features/feeds.md +++ b/docs/develop/tools-and-features/feeds.md @@ -20,11 +20,11 @@ share your implementations in other languages in the [Discord Server](https://discord.gg/kHRyMNpw7t). ::: -### What are Feeds? +## What are Feeds? A feed is a collection of Single Owner Chunks with predicatable addresses. This enables creators to upload pointers to data so that consumers of the feed are able to find the data in Swarm using only an _Ethereum address_ and _Topic ID_. -### Creating and Updating a Feed +## Creating and Updating a Feed In order to edit a feed, you will need to sign your chunks using an Ethereum keypair. For the intrepid, check out the [The Book of Swarm](https://www.ethswarm.org/the-book-of-swarm-2.pdf) on precise details on how to do @@ -33,10 +33,10 @@ and [swarm-cli](./../../bee/working-with-bee/swarm-cli.md) provide facilities to achieve this using JavaScript and a node-js powered command line tool respectively. -### No More ENS Transaction Charges +## No More ENS Transaction Charges Swarm's feeds provide the ability to update your immutable content in a mutable world. Simply reference your feed's `manifest address` as the `content hash` in your ENS domain's resolver, and Bee will automatically provide the latest version of your website. -### Use Cases for Feeds +## Use Cases for Feeds Feeds are a hugely versatile data structure. They allow you to host frequently updated content such as websites, RSS feeds (for podcasts, news, etc.), or even a DNS style architecture on top of Swarm's decentralized DISC. diff --git a/docs/develop/tools-and-features/gateway-proxy.md b/docs/develop/tools-and-features/gateway-proxy.md index bb0610686..f4733d69d 100644 --- a/docs/develop/tools-and-features/gateway-proxy.md +++ b/docs/develop/tools-and-features/gateway-proxy.md @@ -12,7 +12,7 @@ Another tool which is currently popular for running Bee in gateway mode is [Gate It acts as a reverse proxy that runs in front of a Bee node, allowing you to expose your node publicly. It proxies the Bee HTTP API and content endpoints, while optionally adding access control, postage batch auto-buy, and other optional features. -### Public Access to Swarm +## Public Access to Swarm A gateway can be used to run a public endpoint that allows users to: @@ -22,7 +22,7 @@ A gateway can be used to run a public endpoint that allows users to: This makes Swarm content accessible to any web client, even if the user is not running a Bee node locally. -### Authentication, Access Control, and Policy +## Authentication, Access Control, and Policy The Swarm Gateway also acts as an access control and content moderation layer in front of a Bee node. @@ -37,7 +37,7 @@ This makes it possible to run public, private, or semi-public gateways while ret For production deployments, the gateway is typically run behind an HTTPS reverse proxy to ensure encrypted connections. -### Stamp Management +## Stamp Management The Swarm Gateway can optionally manage postage stamps on behalf of the operator, including: diff --git a/docs/develop/tools-and-features/gsoc.md b/docs/develop/tools-and-features/gsoc.md index 9a6d2d651..fc045e9a8 100644 --- a/docs/develop/tools-and-features/gsoc.md +++ b/docs/develop/tools-and-features/gsoc.md @@ -1,7 +1,7 @@ --- title: GSOC id: gsoc -description: Documentation for Group Send Over Content messaging feature in Swarm. +description: Graffiti Several Owner Chunk (GSOC) — a many-to-one messaging feature that lets one full Bee node receive messages from many writer nodes. --- ## Introduction diff --git a/docs/develop/tools-and-features/introduction.md b/docs/develop/tools-and-features/introduction.md index 19eb7f5b0..717197382 100644 --- a/docs/develop/tools-and-features/introduction.md +++ b/docs/develop/tools-and-features/introduction.md @@ -1,16 +1,12 @@ --- -title: Introduction +title: Hosting Your Dapps & Storing Their Data id: introduction -description: Overview of advanced tools and features available for Swarm development. +sidebar_label: Overview +description: Swarm's developer tools and features for hosting dapps and storing their data, including feeds, stamps, encryption, and messaging. --- -# Hosting Your Dapps & Storing Their Data - -Swarm is hugely versatile, but at a very basic level you can think of -it as storage for your dapps data that is too big for blockchain, but -still needs to live in our totally decentralised universe. Swarm is -perfect for storing your NFT meta-data and images in a web3 way that -won't break the bank and can live forever! +Swarm is hugely versatile, but at a very basic level you can think of it as storage for your dapps data that is too big for blockchain, but still needs to live in our totally decentralised universe. +Swarm is perfect for storing your NFT meta-data and images in a web3 way that won't break the bank and can live forever! ## Tools and Features @@ -66,4 +62,3 @@ The `bee dev` mode was removed in Bee v2.8.1; use bee-factory instead. ### Starting a Test Network While bee-factory already runs multiple nodes locally, setting up a [test network](./starting-a-test-network.md) gives you even greater control over simulating interactions between nodes in a more customised environment. - diff --git a/docs/develop/tools-and-features/manifests.md b/docs/develop/tools-and-features/manifests.md index c2db13467..bb1ba8cc0 100644 --- a/docs/develop/tools-and-features/manifests.md +++ b/docs/develop/tools-and-features/manifests.md @@ -5,8 +5,6 @@ description: Guide for using manifests to organize and address multiple files as --- -# Manifests - Manifests define how files and folders are organized in Swarm. Instead of a flat list of uploaded files, Bee encodes directory structure as a compact prefix [trie](https://en.wikipedia.org/wiki/Trie). This allows URLs like `/images/logo.png`, `/docs/readme.txt`, or `/` to resolve efficiently to the correct Swarm references. Whenever you upload a directory — via `/bzz`, `bee-js`, or `swarm-cli` — Bee automatically creates and uploads a manifest that enables a filesystem-like layer inside Swarm. The manifest reference itself is the root reference for your uploaded directory. Manifests provide: diff --git a/docs/develop/tools-and-features/pinning.md b/docs/develop/tools-and-features/pinning.md index ecb8169c2..29257c70b 100644 --- a/docs/develop/tools-and-features/pinning.md +++ b/docs/develop/tools-and-features/pinning.md @@ -11,7 +11,7 @@ Each time a chunk is accessed, it is moved back to the end of the deletion queue Bee nodes provide a facility to **pin** important content so that it is not deleted by the node's garbage collection routine. Chunks can be _pinned_ either during upload, or retrospectively using the Swarm reference. -## Pin During Upload +## How do I pin content during upload? {#pin-during-upload} To store content so that it will persist even when Bee's garbage collection routine is deleting old chunks, we simply pass the `Swarm-Pin` header set to `true` when uploading. @@ -25,7 +25,7 @@ curl -H "Swarm-Pin: true" -H "Swarm-Postage-Batch-Id: 78a26be9b42317fe6f0cbea3e4 } ``` -## Administer Pinned Content +## How do I manage pinned content? {#administer-pinned-content} To check what content is currently pinned on your node, query the `pins` endpoint of your Bee API: @@ -49,7 +49,7 @@ curl localhost:1633/pins/1bfe7c3ce4100ae7f02b62e38d3e8d4c3a86ea368349614a8782740 A `404` response indicates the content is not available. -### Unpinning Content +### How do I unpin content? {#unpinning-content} We can unpin content by sending a `DELETE` request to the pinning endpoint using the same reference: @@ -75,7 +75,7 @@ curl localhost:1633/pins/1bfe7c3ce4100ae7f02b62e38d3e8d4c3a86ea368349614a8782740 Pinning and unpinning is possible for files (as in the example) and also the chunks, directories, and bytes endpoints. See the [API](/api/) documentation for more details. ::: -### Pinning Already Uploaded Content +### How do I pin already-uploaded content? {#pinning-already-uploaded-content} The previous example showed how we can pin content upon upload. It is also possible to pin content that is already uploaded and present in the Swarm. diff --git a/docs/develop/ultra-light-nodes.md b/docs/develop/ultra-light-nodes.md index 5c98a7b04..920bfdb9c 100644 --- a/docs/develop/ultra-light-nodes.md +++ b/docs/develop/ultra-light-nodes.md @@ -8,11 +8,11 @@ description: Guide for running minimal ultra-light nodes with limited functional When running without a blockchain connection, bandwidth incentive payments (SWAP) cannot be made so there is a risk of getting blocklisted by other peers for unpaid services. ::: -#### Configuration +## Configuration To run Bee as an ultra-light node `full-node` and `swap-enable` must both be set to `false`, and the `blockchain-rpc-endpoint` value should be set to an empty string `""` or commented out in the [configuration](./../bee/working-with-bee/configuration.md). -#### Mode of Operation +## Mode of Operation The target audience for this mode of operations are users who want to try out running a node but don't want to go through the hassle of blockchain onboarding. Ultra-light nodes will be able to download data as long as the data consumed does not exceed the payment threshold (`payment-threshold` in [configuration](./../bee/working-with-bee/configuration.md)) set by peers they connect to. diff --git a/docs/develop/upload-and-download.md b/docs/develop/upload-and-download.md index 7a726d8ab..6275ec401 100644 --- a/docs/develop/upload-and-download.md +++ b/docs/develop/upload-and-download.md @@ -295,7 +295,7 @@ The Bee API exposes three HTTP endpoints: - **`/bytes`** — upload & download raw data - **`/chunks`** — upload & download individual chunks -#### Upload with **/bzz** +### Upload with **/bzz** While `bee-js` allows postage stamp batches to be purchased by specifying storage duration and data size, the raw Bee API requires `amount` and `depth` parameters directly. The relationship between these parameters and the storage size and duration of the batch is complex, so `bee-js` is strongly encouraged for newcomers. [Learn more](./tools-and-features/buy-a-stamp-batch.md). diff --git a/docs/references/community.md b/docs/references/community.md index 335821ef6..d8c2357b5 100644 --- a/docs/references/community.md +++ b/docs/references/community.md @@ -1,7 +1,7 @@ --- title: Community id: community -description: Information about Swarm community channels resources and contribution opportunities. +description: Where to find the Swarm community — Discord, forums, social channels, and ways to contribute. --- diff --git a/docs/references/faq.md b/docs/references/faq.md index c4378ca48..6b24d1f9d 100644 --- a/docs/references/faq.md +++ b/docs/references/faq.md @@ -1,12 +1,10 @@ --- title: FAQ id: faq -description: Frequently asked questions about Swarm protocols and general usage. +description: Answers to common questions about Swarm, the BZZ token, and community channels. --- -# Swarm FAQ - ## Community ### What are the Swarm Foundation's official channels? diff --git a/docs/references/smart-contracts.mdx b/docs/references/smart-contracts.mdx index f01d3c7d7..4e7e3c5fe 100644 --- a/docs/references/smart-contracts.mdx +++ b/docs/references/smart-contracts.mdx @@ -5,14 +5,14 @@ description: Reference documentation for Swarm smart contracts including address --- import { globalVariables } from '/src/config/globalVariables'; -### Token Contracts +## Token Contracts |Contract|Blockchain | Address | | ---------------------- | ------------------------------- |--------- | |BZZ token| Ethereum | [`0x19062190b1925b5b6689d7073fdfc8c2976ef8cb`](https://ethplorer.io/address/0x19062190b1925b5b6689d7073fdfc8c2976ef8cb) | |xBZZ token | Gnosis Chain | [`0xdBF3Ea6F5beE45c02255B2c26a16F300502F68da`](https://gnosisscan.io/token/0xdbf3ea6f5bee45c02255b2c26a16f300502f68da) | |sBZZ token| Sepolia (Ethereum testnet) | [`0x543dDb01Ba47acB11de34891cD86B675F04840db`](https://sepolia.etherscan.io/address/0x543dDb01Ba47acB11de34891cD86B675F04840db) | -### Storage Incentives Contracts +## Storage Incentives Contracts You can find the Solidity source code for each contract in the [storage incentives Github repo](https://github.com/ethersphere/storage-incentives ). diff --git a/docusaurus.config.mjs b/docusaurus.config.mjs index 9035e19ef..2ea1281dd 100644 --- a/docusaurus.config.mjs +++ b/docusaurus.config.mjs @@ -26,6 +26,52 @@ export default { type: 'application/openapi+yaml', }, }, + // Machine-readable pointer to the hand-curated llms.txt index (no standard rel yet; + // rel="alternate" + text/plain is the least-surprising choice for AI-agent discovery). + { + tagName: 'link', + attributes: { + rel: 'alternate', + type: 'text/plain', + title: 'llms.txt', + href: '/llms.txt', + }, + }, + // Site-wide structured data: Organization + WebSite. The @id values below are a shared + // contract with the per-doc TechArticle in src/theme/DocItem/Layout — keep them identical. + { + tagName: 'script', + attributes: { type: 'application/ld+json' }, + innerHTML: JSON.stringify({ + '@context': 'https://schema.org', + '@graph': [ + { + '@type': 'Organization', + '@id': 'https://docs.ethswarm.org/#organization', + name: 'Swarm Foundation', + url: 'https://www.ethswarm.org', + logo: 'https://docs.ethswarm.org/img/logo-512.png', + sameAs: [ + 'https://twitter.com/ethswarm', + 'https://github.com/ethersphere', + 'https://www.reddit.com/r/ethswarm', + ], + }, + { + '@type': 'WebSite', + '@id': 'https://docs.ethswarm.org/#website', + name: 'Swarm Documentation', + url: 'https://docs.ethswarm.org', + publisher: { '@id': 'https://docs.ethswarm.org/#organization' }, + potentialAction: { + '@type': 'SearchAction', + target: 'https://docs.ethswarm.org/search?q={search_term_string}', + 'query-input': 'required name=search_term_string', + }, + }, + ], + }), + }, ], stylesheets: [ diff --git a/src/pages/index.js b/src/pages/index.js index f6382e08f..2e2f84b23 100644 --- a/src/pages/index.js +++ b/src/pages/index.js @@ -14,13 +14,13 @@ function Home() { return ( - + - + - +
diff --git a/src/theme/DocItem/Layout/index.js b/src/theme/DocItem/Layout/index.js new file mode 100644 index 000000000..e311dfe76 --- /dev/null +++ b/src/theme/DocItem/Layout/index.js @@ -0,0 +1,45 @@ +import React from 'react'; +import Layout from '@theme-original/DocItem/Layout'; +import Head from '@docusaurus/Head'; +import {useDoc} from '@docusaurus/plugin-content-docs/client'; +import useDocusaurusContext from '@docusaurus/useDocusaurusContext'; + +/** + * Swizzled wrapper (wrap, not eject) around @theme-original/DocItem/Layout. + * + * Adds a per-doc schema.org TechArticle JSON-LD block for AEO/GEO. The theme already emits + * BreadcrumbList structured data (see @theme/DocBreadcrumbs/StructuredData), so we deliberately + * do NOT re-emit BreadcrumbList here — that would produce duplicate structured data. + * + * The #organization / #website @ids referenced below MUST stay byte-identical to the site-wide + * Organization/WebSite JSON-LD in docusaurus.config.mjs (shared contract) — search engines merge + * all JSON-LD on a page, so these cross-block references resolve only if the strings match exactly. + * + * NOTE: per README/CLAUDE.md, swizzled components do NOT auto-upgrade with the Docusaurus theme. + * After a theme bump, re-verify this still renders — it only wraps the original Layout and adds a + * , so the risk surface is small. + */ +export default function DocItemLayoutWrapper(props) { + const {metadata} = useDoc(); + const {siteConfig} = useDocusaurusContext(); + + const jsonLd = { + '@context': 'https://schema.org', + '@type': 'TechArticle', + headline: metadata.title, + description: metadata.description, + url: siteConfig.url + metadata.permalink, + inLanguage: 'en', + isPartOf: {'@id': 'https://docs.ethswarm.org/#website'}, + publisher: {'@id': 'https://docs.ethswarm.org/#organization'}, + }; + + return ( + <> + + + + + + ); +} diff --git a/static/img/logo-512.png b/static/img/logo-512.png new file mode 100644 index 000000000..02cb28401 Binary files /dev/null and b/static/img/logo-512.png differ diff --git a/static/llms.txt b/static/llms.txt index 96760dcc4..eaf13564c 100644 --- a/static/llms.txt +++ b/static/llms.txt @@ -68,7 +68,7 @@ This is the documentation for [Swarm](https://www.ethswarm.org/) and its referen - [Feeds](https://docs.ethswarm.org/docs/develop/tools-and-features/feeds): Mutable data references using single-owner chunks - [Manifests](https://docs.ethswarm.org/docs/develop/tools-and-features/manifests): Trie-based path mapping for file collections - [PSS Messaging (usage)](https://docs.ethswarm.org/docs/develop/tools-and-features/pss): Send messages through the Swarm network -- [GSOC](https://docs.ethswarm.org/docs/develop/tools-and-features/gsoc): Graffiti SOC for pub/sub messaging patterns +- [GSOC](https://docs.ethswarm.org/docs/develop/tools-and-features/gsoc): Graffiti Several Owner Chunk for pub/sub messaging patterns - [Add Access Control (usage)](https://docs.ethswarm.org/docs/develop/act): Encrypt content for specific recipients using ACT - [Gateway Proxy](https://docs.ethswarm.org/docs/develop/tools-and-features/gateway-proxy): Proxy for browser-based Swarm access - [bee-factory](https://docs.ethswarm.org/docs/develop/tools-and-features/bee-dev-mode): Local Swarm development stack (5 Bee nodes plus a local chain) started with a single command @@ -80,7 +80,7 @@ This is the documentation for [Swarm](https://www.ethswarm.org/) and its referen ## Understand Swarm concepts - [What is Swarm?](https://docs.ethswarm.org/docs/concepts/what-is-swarm): Architecture overview and design goals -- [DISC](https://docs.ethswarm.org/docs/concepts/DISC): Distributed Immutable Store for Chunks +- [DISC](https://docs.ethswarm.org/docs/concepts/DISC/): Distributed Immutable Store for Chunks - [Kademlia](https://docs.ethswarm.org/docs/concepts/DISC/kademlia): Distributed hash table and routing - [Neighborhoods](https://docs.ethswarm.org/docs/concepts/DISC/neighborhoods): Address space, proximity, and storage responsibility - [Erasure Coding (theory)](https://docs.ethswarm.org/docs/concepts/DISC/erasure-coding): Reed-Solomon redundancy for chunk reliability diff --git a/static/robots.txt b/static/robots.txt index 6f27bb66a..438319a26 100644 --- a/static/robots.txt +++ b/static/robots.txt @@ -1,2 +1,5 @@ User-agent: * -Disallow: \ No newline at end of file +Disallow: + +Sitemap: https://docs.ethswarm.org/sitemap.xml +# llms.txt: https://docs.ethswarm.org/llms.txt