docs: sync protocol docs to canonical decdn/decdn state

[yigitdot]

Summary

Audits the public Mintlify docs (website/docs/) against the source-of-truth decdn/decdn repo (ADRs, contracts, CLAUDE.md) and fixes claims that had drifted out of date.

Stale facts corrected

1. Payment token → single immutable USDC (was "governance-allowlisted ERC-20s"). ADR 010 multi-token was dropped pre-launch; PaymentChannel.sol fixes USDC at deployment (ADR 003).
   • introduction, participants, architecture, how-it-works, payments (incl. dropping the token arg from the openChannel mermaid call and "per-token bounds" → "rate bounds in USDC").
2. Governance voting weight → delivered-bytes (was "TOKEN voting / 4% of circulating TOKEN"). ADR 036 makes FeeRouter served-bytes over a trailing window the canonical vote weight (tenure ramp + per-operator cap; passive holders have no vote; slashed operators zero out).
   • governance.mdx: Decision line, new Voting weight section, proposal-flow steps, quorum rationale, emergency-multisig appeal triage; introduction "Token-weighted" → "weighted by delivered bytes".
3. Blacklist slash schedule → 5% / 15% / 50% by lifetime offense count (was "10% / 25% / 50% within 90 days"). CapacityBond.sol tiers 500/1500/5000 bps; capped 50%/offense; auto-eject below 50% of min bond (ADR 026/011).

Light polish

• glossary: rewrote the TOKEN entry, added a USDC term, noted capacity-bond staking.
• design-decisions: added 037 Regional proxy warming (new ADR).

Out of scope (intentionally unchanged)

• slashing.mdx "portion to challenger, remainder burned" — vague but still correct (50/50 finality).
• "stake" terminology kept; no new SlashAppeal/blacklist-appeal pages.

Test plan

• prettier --check docs/overview docs/protocol clean (and pre-commit markdownlint + prettier ran on commit)
• grep confirms no remaining allowlisted erc-20 / token voting / circulating token / 10% / 25% / per-token bounds strings
• each claim cross-checked against adr/003-payments.md, adr/036-served-bytes-voting-weight.md, CapacityBond.sol, adr/011-content-takedown.md

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
decdn	🟢 Ready	View Preview	May 30, 2026, 2:21 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[cloudflare-workers-and-pages]

Deploying website with    Cloudflare Pages

Latest commit:	9d2d31b
Status:	✅  Deploy successful!
Preview URL:	https://0d5e3dd0.website-70y.pages.dev
Branch Preview URL:	https://docs-sync-protocol-docs-to-s.website-70y.pages.dev

View logs

[Copilot]

Pull request overview

Documentation-only sync of the public Mintlify docs to the current canonical protocol state: payments are USDC-only (not allowlisted ERC-20s), governance voting weight is delivered bytes (not TOKEN balance), and the blacklist slash schedule is 5/15/50% by lifetime offense (not 10/25/50% in 90 days). Light glossary/ADR-index polish included.

Changes:

• Replace "governance-allowlisted ERC-20" language with USDC across overview/protocol pages, and drop the token arg from the openChannel mermaid call.
• Rewrite governance to served-bytes voting weight (new "Voting weight" section, updated proposal-flow/quorum/multisig wording).
• Update takedown slash schedule to 5/15/50% with lifetime accrual and auto-eject; add ADR 037 row and a USDC glossary entry.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
docs/protocol/takedown.mdx	Updates slash schedule tiers and adds lifetime-accrual / auto-eject note.
docs/protocol/payments.mdx	USDC-only channel wording; drops token arg from openChannel diagram; per-token → USDC bounds.
docs/protocol/governance.mdx	Adds served-bytes voting-weight section; updates quorum, proposal flow, and multisig triage scope.
docs/overview/participants.mdx	Node earnings / client channels are USDC.
docs/overview/introduction.mdx	Core-properties bullets switched to USDC + delivered-bytes governance.
docs/overview/how-it-works.mdx	Narrative updated to USDC channel.
docs/overview/glossary.mdx	Rewrites TOKEN entry, adds USDC, notes capacity-bond staking.
docs/overview/design-decisions.mdx	Adds ADR 037 row.
docs/overview/architecture.mdx	Flow step 4 updated to USDC payment channel.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[gemini-code-assist]

Code Review

This pull request updates the deCDN documentation to reflect major protocol changes, including migrating payment channels from general ERC-20 tokens to USDC, transitioning from token-weighted governance to operator governance weighted by delivered bytes, and revising the slash schedule for blacklist violations. The feedback recommends updating the glossary to align with the protocol's transition from 'staking' to 'bonding' terminology.

[gemini-code-assist]

To align with the protocol's migration from 'staking' to 'bonding' terminology, all technical protocol references to 'stake', 'staked', and 'staking' in the glossary should be updated to 'bond', 'bonded', and 'bonding' respectively.

| Term                   | Definition                                                                                                                                                                        |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Blob**               | A content-addressed byte sequence. Every blob is identified by its hash; clients verify received bytes against the known hash.                                                    |
| **Channel (payment)**  | On-chain escrow between client and node that backs off-chain vouchers. Opens with a deposit; settles with the latest voucher.                                                     |
| **Client**             | A lightweight QUIC endpoint that streams content and pays per MB. No bond, no gossip publish.                                                                                     |
| **DHT**                | Kademlia-subset content discovery. Nodes self-publish records when caching a blob.                                                                                                |
| **Gossip**             | Epidemic broadcast over topic channels for node metadata and rate updates.                                                                                                        |
| **Hash sequence**      | An ordered collection of blob hashes (a directory or manifest equivalent).                                                                                                        |
| **Node**               | A bonded QUIC endpoint that caches and delivers blobs. Some are origin-backed; others are pure caches.                                                                            |
| **Origin-backed node** | A node configured with an S3-compatible store, NFS mount, or local disk — the canonical source for specific blobs. Never experiences a true cache miss.                           |
| **Origin backend**     | The opaque storage behind an origin-backed node (S3, R2, B2, MinIO, NFS, local disk). Never exposed to the network.                                                               |
| **Peer mesh**          | The flat set of all bonded nodes. Discovery via gossip; content location via DHT.                                                                                                 |
| **Probe**              | Parallel latency + availability check that runs before any delivery commitment.                                                                                                   |
| **Selection score**    | A combined ranking over advertised price, observed latency, and reputation. Lower is better.                                                                                      |
| **Bond**               | TOKEN locked on-chain by a node to join the mesh — a capacity bond that scales with declared bandwidth. Returned on deregistration after an unbonding period.                     |
| **TOKEN**              | The deCDN bonding token: locked as a node's capacity bond and burned by the buyback sink. Not used for payments; governance weight comes from delivered bytes, not TOKEN balance. |
| **USDC**               | The payment currency for all delivery. Fixed at deployment; channels deposit, voucher, and settle in USDC.                                                                        |
| **Voucher**            | A signed off-chain payment message. The primary payment instrument between client and node.                                                                                       |

References

1. When migrating terminology from 'staking' to 'bonding' in documentation, preserve 'stake' when used in idiomatic expressions (e.g., 'having a stake' or 'skin-in-the-game') rather than as a technical protocol verb or noun.