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

@@ -5,6 +5,7 @@ description: Overview of Swarm's Distributed Immutable Store for Chunks system u
 ---
 
 import bos_fig_2_7 from '/static/img/bos_fig_2_7.jpg';
+import bos_fig_2_10 from '/static/img/bos_fig_2_10.jpg';
 
 
 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.
@@ -23,11 +24,20 @@ Neighborhoods play a key role in providing data redundancy for chunks stored on
 
 ## 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. 
+In the DISC model, **chunks** are the basic storage unit of the network layer. 
+When a file is uploaded to Swarm, it gets broken down into chunks - pieces of at most 4KB, each with a small metadata header. 
+Every chunk gets its own address, and each chunk is stored by the nodes whose [overlay addresses](./../../references/glossary.md#overlay) are closest to that chunk address. 
+Chunk addressing is *deterministic, collision-free, and uniformly distributed,* which is what gives Swarm local validity, integrity guarantee, and load balancing across nodes. 
+There are two fundamental chunk types: 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.
+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, a binary Merkle tree (BMT) built with Keccak256 over the 32-byte segments of the chunk data; payloads shorter than 4KB are hashed as if zero-padded up to 4KB. 
+A content-addressed chunk has an at most 4KB payload, and its address is calculated as the hash of the 8-byte span and the BMT root of the payload. 
+Because the address is derived from the content, a content-addressed chunk cannot be changed in place. 
+Different content yields a different address.
 
 <div style={{ textAlign: 'center' }}>
   <img src={bos_fig_2_7} className="responsive-image" />
@@ -37,7 +47,29 @@ Content-addressed chunks are chunks whose address is based on the hash digest of
 </div>
 
 
-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.
+For single-owner chunks on the other hand, the address is calculated as the hash of an identifier and an owner's Ethereum address. 
+The content consists of an arbitrary data payload along with required headers: a 32-byte identifier, a 65-byte signature, and the same 8-byte span used by content-addressed chunks. 
+The signature signs off on the identifier and the BMT hash of the span and payload, so integrity comes from the owner's signature rather than from the content itself.
+Validating a single-owner chunk means recovering the owner's address from the signature and checking the hash of the identifier and that address against the chunk address, which is in effect, an authentication that the owner has write access to that address. 
+
+<div style={{ textAlign: 'center' }}>
+  <img src={bos_fig_2_10} className="responsive-image" />
+  <p style={{ fontStyle: 'italic', marginTop: '0.5rem' }}>
+    Source: <a href="https://www.ethswarm.org/the-book-of-swarm-2.pdf#subsection.2.2.3" target="_blank">The Book of Swarm - Figure 2.10 - "Single owner chunk"</a>
+  </p>
+</div>
+
+Single-owner chunks form the basis for feeds. 
+A feed chunk is a single-owner chunk whose identifier is the hash of a feed topic and an index, so each update is published as a new chunk at a new, deterministically derivable address. 
+A reader can therefore find the latest update from the owner's address and the topic alone, even though no individual chunk is ever overwritten, meaning the chunk store itself remains immutable.
+
+| | Content-addressed chunk (CAC) | Single-owner chunk (SOC) |
+|---|---|---|
+| Address derived from | Hash of the 8-byte span and the BMT root of the payload | Hash of the 32-byte identifier and the owner's Ethereum address |
+| Integrity attested by | The content itself — the address is the hash of the content | The owner's signature over the identifier and the BMT hash of span and payload |
+| Chunk mutable? | No — different content yields a different address | No — signing a second payload for the same identifier makes network behaviour unpredictable; mutability is achieved at the feed layer |
+| Max payload | 4 KB + 8-byte span header | 4 KB + 105 bytes of headers (identifier, signature, span) |
+| Basis for | File and manifest data | Feeds (a mutable resource resolved from owner address + topic) |
 
 ## Push-Sync, Pull-Sync, and Retrieval Protocols
 

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)