feat: AEO/GEO Tier 3 — extraction aids - #832
Conversation
- add a leading :::info key-facts block to pss and bandwidth-incentives - split the pss wall-of-text into Security / Privacy / Efficiency / Mailboxing sections - add a key-fact lede and a Mermaid feedback-loop diagram to price-oracle Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Yejin Kelly Joo <yejinkellyjoo@gmail.com>
- add an iterative-vs-forwarding Kademlia table - add a content-addressed-vs-single-owner chunk table - add an immutable-vs-mutable batch table (leading with a content-guarantee row) - also make two back-referencing sentences self-contained in these pages Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Yejin Kelly Joo <yejinkellyjoo@gmail.com>
- rewrite sentences that opened with a bare pronoun or an 'above/below' back-reference so each stands alone when extracted - covers monitoring, protocols (5 pinpoint openers), upgrade, glossary, erasure-coding, backups, publish-a-website, and gateway Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Yejin Kelly Joo <yejinkellyjoo@gmail.com>
✅ Deploy Preview for test-twitter-preview-testing-3 ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
| | | 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 | |
There was a problem hiding this comment.
"Yes — the address stays fixed while content updates"
No, that would be a feed, a construct on top of Single-owner chunk.
If you upload the same SOC twice (same owner + identifier), you are "double signing", and that has undefined behavior: no guarantees can be made about which version the network will return to you.
So we should say something like "Only when using feeds (link to feeds)"
There was a problem hiding this comment.
That sounds like the paragraph above is also incorrect then, because this table is based on that.
Unlike a content-addressed chunk, the contents of a single-owner chunk may be updated while the address remains unchanged. ??
Could you also review the paragraph above?
There was a problem hiding this comment.
Yes, to be honest, I have multiple issues with the existing paragraph.
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.
"unique id": It is consistently called the identifier in specs, API, code, etc., so I'd prefer it in the format "the hash of the identifier and the owner Ethereum address" (NOT overlay address!!!)
The content consists of an arbitrary data payload along with required headers.
OK
Unlike a content-addressed chunk, the contents of a single-owner chunk may be updated while the address remains unchanged.
Ugh. I still think this is very misleading. No, the content of a single-owner chunk cannot be updated on its own. Content update is only "observable" when using higher-level concepts - feeds - that mimick mutable data. SOC simply has a different, guessable address scheme, but the same SOC is not supposed to be "overwritten" with different payload: undefined behavior.
Single owner chunks form the basis for feeds, which are data structures that allow for mutable content with a static address.
Acceptable. But for full picture, the static address is a "feed manifest", which is a specific mantaray metadata which uses content-addressed chunks under the hood.
|
|
||
| | | Immutable batch | Mutable batch | | ||
| |---|---|---| | ||
| | Content guarantee | Uploaded data can never be overwritten — it is permanent for the batch's lifetime | Older data may be overwritten once capacity is reached | |
There was a problem hiding this comment.
No, an immutable batch only protects you locally from overwriting your data. It is enforced by Bee, not the network.
Immutable is local overwrite protection, while mutable lets the postage batch "roll over" and overwrite old data.
There was a problem hiding this comment.
Ok, that may be the correct statement on the technical level, but this page of the docs is talking about the batches from user's point of view. Maybe it's the "guarantee-ness" tone of the explanation that makes this statement wrong.
6cfcf2c How does this look?
There was a problem hiding this comment.
Yes, the new version is perfect!
Signed-off-by: Yejin Kelly Joo <yejinkellyjoo@gmail.com>
2 participants
What does this PR resolve? 🚀
AEO/GEO Tier 3 — extraction aids. Follow-up to the merged #831, making dense pages easier for AI answer engines (and readers) to extract correct, self-contained answers from.
Details 📝
Three workstreams, one commit each:
1. Callouts + segmentation (
9520a986)concepts/pss.md: leading:::infokey-facts block; split the 5-paragraph wall of text into## Security / Privacy / Efficiency / Mailboxing(headings only — no prose rewrite).concepts/incentives/bandwidth-incentives.md: leading:::infokey-facts block.concepts/incentives/price-oracle.md: a key-fact lede (surfaces the 4× redundancy target that was buried mid-paragraph) and a Mermaid diagram of the price/redundancy negative-feedback loop (renders client-side via@docusaurus/theme-mermaid).2. Table conversions (
97dc8028)concepts/DISC/kademlia.mdx: iterative-vs-forwarding Kademlia table.concepts/DISC/DISC.mdx: content-addressed-vs-single-owner chunk table.concepts/incentives/postage-stamps.md: immutable-vs-mutable batch table — leads with a content-guarantee row so immutability reads as a feature (permanence), not just a limitation.3. De-deictic prose (
877580c6)monitoring,contribute/protocols(5 pinpoint openers only — it's an internal spec, not fully normalized),upgrade,references/glossary,erasure-coding,backups,desktop/publish-a-website, anddevelop/gateway.develop/access-control("ACT lookup table" is a specific term) andconcepts/DISC/neighborhoods(a sentence tightly coupled to adjacent example blockquotes).Deferred (not in this PR):
FAQPageJSON-LD;agent-card.jsonorg realignment ("Ethersphere" → "Swarm Foundation"); a purpose-built 1200×630 OG image +themeConfig.image; fixingawesome-listheading levels in thefetch-awesome-swarm.mjsgenerator.Checklist ✅
masterand resolved conflictsnpm run buildsucceedsnpm run check:links) where relevantstatic/llms.txtupdated if pages were added / renamed / deletedSwarmvsswarm, ..)git commit -s)