feat: AEO/GEO Tier 3 — extraction aids

docs/bee/working-with-bee/backups.md

@@ -201,7 +201,7 @@ Note that `swarm.key` is in UTC / JSON keystores format and is encrypted by defa
 
 To import to Metamask:
 
-1. View and copy your `swarm.key` and `password` as shown above
+1. View and copy the contents of your exported `swarm.key` and `password` files
 2. Go to Metamask and click "Account 1" --> "Import Account"
 3. Choose the "Select Type" dropdown menu and choose "JSON file"
 4. Paste the password (Make sure to do this first)

docs/bee/working-with-bee/monitoring.md

@@ -8,11 +8,11 @@ Bee nodes expose runtime metrics in Prometheus format, which you can collect and
 
 Navigate to `http://localhost:1633/metrics`.
 
-This is the current state of Bee's metrics as they stand at this moment.
+The /metrics page shows a snapshot of your Bee node's metrics at the moment you load it.
 
-In order to use these metrics and view, we need to keep a record of these metrics over time.
+To make these raw metrics useful, you need to record them over time.
 
-To do this we will use [Prometheus](https://prometheus.io/docs/introduction/overview/). Simply install, configure as follows, and restart!
+To record Bee's metrics over time, we will use [Prometheus](https://prometheus.io/docs/introduction/overview/). Simply install, configure as follows, and restart!
 
 For Ubuntu and other Debian based Linux distributions install using `apt`:
 

docs/bee/working-with-bee/upgrade.md

@@ -18,7 +18,7 @@ Nodes should not be shut down or updated in the middle of a round they are playi
 ## Version compatibility and upgrade path
 
 The Swarm network has a **minimum supported Bee version**.
-It is currently **v2.8.0**, the release which introduced a breaking p2p protocol change, so nodes running an older protocol can no longer connect to the network.
+The minimum supported version is currently **v2.8.0**, the release that introduced a breaking p2p protocol change, so nodes running an older protocol can no longer connect to the network.
 
 When upgrading across a breaking protocol change, do not skip the release that introduced it.
 Upgrade *through* that version so any one-time data migrations run while they still exist in the code, since Bee removes old migration and compatibility code once a version is no longer supported.

docs/concepts/DISC/DISC.mdx

@@ -39,6 +39,13 @@ 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.
 
+| | Content-addressed chunk (CAC) | Single-owner chunk (SOC) |
+|---|---|---|
+| Address derived from | BMT hash of the payload (plus span) | Hash of a unique id + the owner's address |
+| Content mutable? | No — the address changes if the content changes | Yes — the address stays fixed while content updates |
+| Max payload | 4 KB | 4 KB (payload plus required headers) |
+| Basis for | Content integrity / file data | Feeds (mutable content at 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.

docs/concepts/DISC/kademlia.mdx

@@ -34,7 +34,7 @@ Kademlia's design allows it to scale to large networks, as each node only needs
 
 ## Kademlia in Swarm 
 
-As mentioned above, Swarm's version of Kademlia differs from commonly used implementations of Kademlia in several important ways:
+Swarm's version of Kademlia differs from commonly used implementations of Kademlia in several important ways:
 
 ### Proximity Order & Neighborhoods
 
@@ -52,6 +52,12 @@ In contrast, Swarm makes use of forwarding Kademlia. Here each node forwards the
 
 The main advantage of forwarding Kademlia is that it maintains the anonymity of the node which initiated the request.
 
+| | Iterative Kademlia | Forwarding Kademlia (Swarm) |
+|---|---|---|
+| Who queries the next node | The requesting node, directly | Each intermediate node forwards the query |
+| Chunk return path | Sent directly from storer to requester | Relayed back along the same chain of nodes |
+| Requester anonymity | No | Yes |
+
 <div style={{ textAlign: 'center' }}>
   <img src={bos_fig_2_3} className="responsive-image" />
   <p style={{ fontStyle: 'italic', marginTop: '0.5rem' }}>

docs/concepts/incentives/bandwidth-incentives.md

@@ -6,6 +6,13 @@ description: Explains SWAP protocol for managing bandwidth resource exchange bet
 
 The Swarm Accounting Protocol (SWAP) is a protocol used to manage the exchange of bandwidth resources between nodes. SWAP ensures that node operators collaborate in routing messages and data while protecting the network against frivolous use of bandwidth. The protocol combines off-chain peer-to-peer based accounting with on-chain settlement through the chequebook contract.
 
+:::info[Key facts]
+- **What it is**: SWAP (Swarm Accounting Protocol) manages the exchange of bandwidth between nodes.
+- **Accounting**: each pair of peers tracks their relative bandwidth usage off-chain.
+- **Settlement**: when one node's debt crosses a threshold, it either issues an xBZZ "cheque" (settled on-chain via the chequebook contract) or keeps serving bandwidth in kind until the debt is paid off.
+- **Thresholds & freeloaders**: each node sets its own debt threshold; nodes that do not pay risk being blacklisted.
+:::
+
 As nodes relay requests and responses, they keep track of their bandwidth usage with each of their peers. Peers engage in a service-for-service exchange, where they provide resources to each other based on their relative usage. 
 
 Once a node's relative debt with one of their peers crosses a certain threshold, the party in debt can either send a xBZZ payment in the form of a "cheque" (an off chain commitment to pay their debt), or can continue to provide bandwidth services in kind until their debt is paid off. Each node can set their own threshold for the level of relative debt they accept. Freeloader nodes which do not pay their debts are at risk of being blacklisted by other nodes. 

docs/concepts/incentives/postage-stamps.md

@@ -127,6 +127,13 @@ Therefore rather than speaking of the number of slots as determining the utilisa
 
 ### Which Type of Batch to Use
 
+| | Immutable batch | Mutable batch |
+|---|---|---|
+| Data retention | Uploaded data won't be overwritten by later uploads to the same batch | Older data may be overwritten once capacity is reached |
+| When capacity is full | Additional uploads are not accepted | Keeps accepting uploads; overwrites the oldest chunks |
+| Default? | Yes (`immutable` unset) | No (set the `immutable` header to `false`) |
+| Best for | Long-term or never-overwritten data (archives, legal documents, photos) | Frequently updated data (blogs, websites, messaging) |
+
 Immutable batches are suitable for long term storage of data or for data which otherwise does not need to be changed and should never be overwritten, such as records archival, legal documents, family photos, etc. 
 
 Mutable batches are great for data which needs to be frequently updated and does not require a guarantee of immutability. For example, a blog, personal or company websites, ephemeral messaging app, etc.
@@ -177,7 +184,7 @@ The implications of this behaviour are that even a small change to the data of a
 
 ### Implications for Swarm Users
 
-Due to the nature of batch utilisation described above, batches are often fully utilised before reaching their theoretical maximum storage amount. However as the batch depth increases, the chance of a postage batch becoming fully utilised early decreases. At batch depth 24 (unencrypted, no erasure coding), there is a 0.1% chance that a batch will be fully utilised/start replacing old chunks before reaching 68.48% of its theoretical maximum.
+Because of how buckets fill during batch utilisation, batches are often fully utilised before reaching their theoretical maximum storage amount. However as the batch depth increases, the chance of a postage batch becoming fully utilised early decreases. At batch depth 24 (unencrypted, no erasure coding), there is a 0.1% chance that a batch will be fully utilised/start replacing old chunks before reaching 68.48% of its theoretical maximum.
 
 Let's look at an example to make it clearer. Using the method of calculating the theoretical maximum storage amount [outlined above](./postage-stamps.md#batch-depth), we can see that for a batch depth of 24, the theoretical maximum amount which can be stored is 68.72 gb:
 
@@ -514,4 +521,4 @@ The title of each table below states whether it is for encrypted or unencrypted
 | 1.13 PB | 328.11 TB | 38 |
 | 2.25 PB | 656.76 TB | 39 |
 | 4.50 PB | 1.31 PB | 40 |
-| 9.01 PB | 2.63 PB | 41 |
+| 9.01 PB | 2.63 PB | 41 |

docs/concepts/incentives/price-oracle.md

@@ -6,10 +6,25 @@ description: Describes smart contract mechanism for dynamically adjusting postag
 
 ## How does the price oracle set stamp prices? {#stamp-prices}
 
+The price oracle targets a fourfold (4×) data-redundancy level as a safe minimum, and moves the stamp price to hold it there: when redundancy falls below 4 it raises the price, and when redundancy rises above 4 it lowers it — a negative-feedback loop that pulls redundancy back toward 4.
+
 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}
 
+The oracle runs a negative-feedback loop that keeps redundancy near the 4× target:
+
+```mermaid
+flowchart TD
+    T([Target: 4x data redundancy])
+    T -- redundancy falls below 4 --> U[Oracle raises the stamp price]
+    U --> V[Fewer stamps bought]
+    V -- redundancy rises --> T
+    T -- redundancy rises above 4 --> X[Oracle lowers the stamp price]
+    X --> Y[More stamps bought]
+    Y -- redundancy falls --> T
+```
+
 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.

docs/concepts/pss.md

@@ -6,10 +6,25 @@ description: Explains Postal Service over Swarm messaging protocol enabling secu
 
 PSS, or Postal Service over Swarm, is a messaging protocol that enables users to send and receive messages over Swarm. It is an essential component of Swarm's infrastructure, providing secure, private, and efficient communication between nodes.
 
+:::info[Key facts]
+- **What it is**: PSS (Postal Service over Swarm) is Swarm's node-to-node messaging protocol.
+- **How delivery works**: a message is encrypted to the recipient and wrapped in a content-addressed chunk whose address falls in the recipient's neighborhood, so the push-sync protocol delivers it; only the recipient can decrypt it.
+- **Anonymous inbound**: senders can be previously unknown identities.
+- **Offline recipients**: mailboxing lets a message wait for a recipient who is not online.
+:::
+
+## Security
+
 PSS is designed to be secure by encrypting messages for the intended recipient and wrapping them with a topic in a content-addressed chunk. The chunk is crafted in such a way that its content address falls into the recipient's neighborhood, ensuring that delivery is naturally taken care of by the push-sync protocol. This ensures that messages are delivered only to the intended recipient's neighborhood and cannot be intercepted or read by unauthorized parties. While the chunk will be delivered to all members of the recipient's neighborhood, only the recipient will be able to decrypt the message using their private key.
 
+## Privacy
+
 PSS also provides privacy by allowing users to receive messages from previously unknown identities. This makes it an ideal communication primitive for sending anonymous messages to public identities such as registrations or initial contact to start a thread by setting up secure communication.
 
+## Efficiency
+
 Efficiency is another key feature of PSS. It uses direct node-to-node messaging in Swarm, which means that messages are delivered directly from one node to another without the need for intermediaries. This reduces latency and ensures that messages are delivered quickly and reliably.
 
+## Mailboxing
+
 PSS also supports mailboxing, which allows users to deposit messages for download if the recipient is not online. This ensures that messages are not lost if the recipient is offline when they are sent.

docs/desktop/publish-a-website.md

@@ -106,7 +106,7 @@ If you plan to update your website in the future, it’s recommended that you se
   6. Select your website folder. NOTE: The index.html file should be in the root folder.
   7. Add Postage Stamp to publish your page. NOTE: Postage stamps cover storage costs for a specified duration.
   8. Upload the website to your Node.
-  9. Connect Feed hash to ENS domain as described above.
+  9. Connect the Feed hash to your ENS domain using the ENS steps shown earlier.
 
 ![](/img/upload-a-website4.gif)
 

docs/develop/contribute/protocols.md

@@ -73,7 +73,7 @@ This approach implies that every forwarding node - once it received a request -
 
 Because a forwarder can not reliably tell how much time the downstream peer will need to satisfy the request - the choice of a reasonable value for waiting period is a point of contention.
 
-It is constrained by these factors:
+The choice of a reasonable waiting period is constrained by these factors:
 
 - keeping the in-memory record for too long means that there's going to be a limit on how many concurrent requests a peer can keep "in-flight", because memory is limited.
 - if the peer decides to time out prematurely (while downstream peers are still processing the request) then the effort of all the downstream peers will be wasted.
@@ -132,7 +132,7 @@ Having a granular punishment strategy ensures that the peers who misbehave (perh
 
 The retrieval of a chunk is a process which fetches a given chunk from the network by its address.
 
-It follows the general semantics of the chunk syncing described above and follows the same network path as the push sync protocol, but in reverse.
+Chunk retrieval follows the general semantics of chunk syncing and takes the same network path as the push sync protocol, but in reverse.
 
 ### Protocol breach
 
@@ -214,7 +214,7 @@ message Delivery {
 
 Pushsync protocol is responsible for ensuring delivery of the chunk to its prescribed storer after it has been uploaded to any arbitrary node.
 
-It works in a similar way to the Retrieval protocol in the sense that the chunk is being passed to a peer whose address is closest to the chunk address and a custody receipt is received in response.
+The Pushsync protocol works in a similar way to the Retrieval protocol: the chunk is passed to the peer whose address is closest to the chunk address, and a custody receipt is received in response.
 
 Then the same process is repeated until the chunk eventually reaches the storer node located in a certain "neighborhood".
 
@@ -228,7 +228,7 @@ Multiplexing is a recommended node strategy for the push sync protocol that invo
 
 The current implementation of the push sync protocol aims to push a chunk to the closest node in the neighborhood which is then supposed to give out a receipt.
 
-This is motivated by the  retrieval protocol that aims to find the chunk at this closest node.
+Pushing the chunk to the single closest node is motivated by the retrieval protocol, which aims to find the chunk at that closest node.
 
 When the closest node hands out a receipt, this node also replicates the chunk to 3 peers in the neighborhood which are further away from the chunk than him.
 
@@ -398,6 +398,6 @@ At the implementation level the Kademlia component will offer (in exchange for a
 
 A reliable network transport is required for the proper functionality of DISC protocols.
 
-It can be a distinct component whose responsibilities would be ensuring delivery, re-tries on network issues and timeouts and optimal use of network related resources.
+The network transport can be a distinct component responsible for ensuring delivery, retrying on network issues and timeouts, and making optimal use of network resources.
 
 One example of usage for such a component could be embedding into the Kademlia driver so that the topology component is only concerned with overlay related operations, abstracting away any low level transport concerns.

docs/develop/gateway.md

@@ -171,7 +171,7 @@ Example (add these lines to the `docker run` command):
 -e SOFT_AUTH="true" \
 ```
 
-At this point, you have:
+A minimal gateway setup consists of:
 
 * A working Swarm HTTP gateway
 * Connected to your Bee node

docs/develop/tools-and-features/erasure-coding.md

@@ -88,7 +88,7 @@ An example download request may look something like this:
 
 For this request, the redundancy strategy is set to 3 (RACE), which means that it will initiate a request for all data and parity chunks and continue to retrieve chunks until enough have been retrieved to reconstruct the source data. This is in contrast with the default strategy of DATA where only the data chunks will be retrieved.
 
-However, as noted above, it is recommended to not adjust the default settings for these options, so a typical request would actually look like this (which is the exact same as a [normal download](./../upload-and-download.md) without any additional options set):
+However, it is recommended to not adjust the default settings for these options, so a typical request would actually look like this (which is the exact same as a [normal download](./../upload-and-download.md) without any additional options set):
 
 
 ```bash