DecentWeb — High-Level Design Document

Version: 0.2 (DHT-native rewrite) Status: Draft Purpose: Establish design goals, architectural overview, and rationale for a decentralized, privacy-preserving content web. Each architectural layer defined here will be expanded in separate documents and agent sessions. This document also serves as the basis for future standards publication, including options considered and reasoning for each decision.

1. Motivation

The contemporary web has converged on a set of structural pathologies that cannot be fixed incrementally:

• Hosting costs money, so content must monetize attention. Every popup, paywall, cookie banner, and email capture form is downstream of this single economic fact.
• Servers are surveillance infrastructure. Any content served from a server can log who requested it, when, and from where. Privacy tools mitigate this but cannot eliminate it while the architecture remains client-server.
• Search is captured by SEO economics. When ranking in a central index is the primary discovery mechanism, the incentive to game that index overwhelms the incentive to produce good content.
• JavaScript enables hostile client-side behavior. Bot detection walls, consent dark patterns, and tracking scripts are all JS-dependent. Removing JS from content rendering removes the attack surface entirely.
• Cloudflare and similar services have made “no-JS browsing” practically non-functional on the modern web, not because content requires JS, but because bot detection does. A separate network sidesteps this entirely.

Gemini protocol correctly identified these problems but overcorrected — removing images is an unnecessary constraint that limits legitimate expression. This project aims for the minimal sufficient set of constraints to eliminate the pathologies without sacrificing expressive capability.

2. Design Goals

2.1 Core Properties (Non-Negotiable)

2.2 Secondary Goals (Strong Preference)

• Interoperability with the existing web: Content may link to the regular web. Those links open externally in a conventional browser context, clearly marked as leaving the local network.
• Author identity portability: An author’s identity is their keypair. It cannot be deplatformed, suspended, or transferred by any third party.
• Reader anonymity by default: No account, login, or registration is required to read anything. Subscriptions are local state only.
• Graceful degradation: A feed that goes unupdated simply stops appearing in new content. There is no broken-link equivalent; content either exists in the swarm or it doesn’t.
• Low implementation complexity: Every layer of the stack should be specifiable in a document a competent engineer can implement independently.

2.3 Explicit Non-Goals

• Real-time communication. This is a content distribution network, not a messaging system or social network. Latency tolerances are measured in minutes, not milliseconds.
• E-commerce or transactional capability. If you need to take payments, run a form, or operate a login wall, you need the regular web. This network provides a link mechanism to go there.
• Guaranteed permanence. Content lives as long as peers seed it. Archival is a separate concern and out of scope.
• Anonymity for publishers. Readers are anonymous. Publishers are pseudonymous at best — their keypair is their identity, but linking a keypair to a real person is outside the protocol’s scope.

3. Architectural Overview

The system is composed of five loosely coupled layers. Each layer has a single responsibility and communicates with adjacent layers through well-defined interfaces. No layer depends on anything above it.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

┌─────────────────────────────────────────────────────────────┐
│  5. RENDERING LAYER                                         │
│     Custom browser / stripped renderer                      │
│     HTML + CSS + WebP + WebM only                          │
│     Zero outbound requests from content                     │
├─────────────────────────────────────────────────────────────┤
│  4. DISCOVERY LAYER                                         │
│     Local full-text index of fetched content               │
│     Trust-graph recommendations from followed feeds         │
│     No central search engine                               │
├─────────────────────────────────────────────────────────────┤
│  3. CONTENT LAYER                                           │
│     BitTorrent for content bundle distribution              │
│     Bundle: HTML + assets, addressed by hash               │
│     Hash referenced and verified via Feed layer            │
├─────────────────────────────────────────────────────────────┤
│  2. FEED LAYER                                              │
│     BEP 44 mutable DHT item → feed manifest torrent        │
│     Author-controlled, Ed25519 signed                      │
│     Maps author identity → content hashes                  │
│     Canonical address: btpk magnet link                    │
├─────────────────────────────────────────────────────────────┤
│  1. IDENTITY LAYER                                          │
│     Ed25519 keypair — identity IS the public key           │
│     No registration, no authority, no account              │
│     Signs feeds; verified locally by all readers           │
└─────────────────────────────────────────────────────────────┘

Layer interfaces

The canonical DecentWeb author address is a BEP 46-compatible magnet link: magnet:?xs=urn:btpk:<base32-encoded-public-key>

Once a reader has the public key or btpk link — acquired through any channel — all feed refresh and content retrieval happen entirely over the DHT and BitTorrent network. No old-web dependency.

Each layer is described briefly below. Each will be expanded in a dedicated document.

4. Layer Summaries

Layer 1 — Identity

Author identity is an Ed25519 keypair. The public key is the author’s permanent identifier — analogous to a username that nobody can take away. The private key signs all feed manifests published by that author.

There is no registration step, no server involved, and no authority that can suspend or transfer the identity. A keypair can be generated offline. The public key is how readers subscribe to an author and how the browser verifies content authenticity.

Key design decision recorded here: Ed25519 over secp256k1 (used by Bitcoin/nostr). Ed25519 is faster, signatures are smaller, and implementations are available in every major language without external dependencies. The nostr ecosystem’s use of secp256k1 is noted; interoperability with nostr is desirable but not at the cost of unnecessary complexity. Compatibility shim options will be explored in the Identity Layer document.

Key design decision recorded here: The same Ed25519 keypair serves three purposes: it is the author’s identity, it signs feed manifests, and it authorises updates to the author’s BEP 44 mutable DHT item. One key, three roles. Authors who have an existing Ed25519 SSH key may reuse it if tooling supports extracting the raw 32-byte public key and producing BEP 44-compatible signatures. SSH is not part of the protocol; RSA and ECDSA SSH key types are incompatible with BEP 44.

Key design decision recorded here: Key lifecycle is a social and application-layer concern, not a protocol mechanism. If an author loses or rotates a key, they publish new content under the new key and announce the transition out of band — via chat, email, a notice in their existing content, or by any other channel available to them. Readers update trust locally. Old content under the old key remains in the swarm and continues to verify; readers decide individually whether to keep or remove trust for the old key. There is no protocol-level revocation infrastructure. A future ecosystem extension may standardise a signed successor-key field in the feed manifest, but none exists at this version.

Design principle: Once content enters the swarm, no author can make it inaccessible. Key changes, feed updates, and client removals affect what a reader chooses to display; they cannot retract content from the network. This is a property of the architecture, not a limitation. Published is public.

Layer 2 — Feed

The feed is a signed manifest file associating an author’s public key with their published content hashes and an optional peer recommendation block. The current version of the feed is located through a BEP 44 mutable item in the BitTorrent DHT. The BEP 44 item is a small signed pointer — not the feed itself — which contains the infohash of the latest feed manifest torrent. The BEP 44 value size limit (1000 bytes) is not a constraint because the DHT item stores only the pointer; the feed manifest itself is a full-size torrent with no size limit.

Publication flow:

1. Author assembles a content bundle and creates a torrent for it → content_infohash
2. Author updates the signed feed manifest to include the new entry → creates a torrent for the updated manifest → feed_manifest_infohash
3. Author increments the sequence number, signs {seq: N, v: feed_manifest_infohash} with their Ed25519 private key, and pushes the updated BEP 44 mutable item to the DHT

No HTTP is required. The author needs only a DHT-capable BitTorrent client.

Read flow:

1. Reader obtains the author’s public key or btpk magnet link through any channel
2. Reader derives the DHT key (SHA1(pubkey)) and resolves the BEP 44 mutable item; verifies the Ed25519 signature against the public key
3. Extracts feed_manifest_infohash; fetches the feed manifest torrent
4. Fetches desired content bundles via BitTorrent

Feed mirrorability: Because the signed feed manifest is cryptographically bound to the author’s key, the same signed file may be served from multiple hosts interchangeably. This is an explicitly supported property — the same feed_manifest_infohash may be distributed via BitTorrent, served over HTTP, or relayed by peers. HTTP-hosted mirror feeds are a useful fallback transport in environments where DHT access is degraded, but they are secondary transports, not trust anchors. Signature verification against the author’s public key applies regardless of transport.

Mutable content is handled at this layer: when an author updates an article, they publish a new content hash in the feed manifest. The old hash remains valid. The client follows the feed to find the latest version.

Key design decision recorded here: DHT-native feed addressing over ActivityPub or HTTP-only RSS. ActivityPub requires server infrastructure per identity and two-way federation. HTTP-only RSS requires a hosting arrangement and a server to go offline. BEP 44 mutable items are DHT-native, Ed25519-signed, and update without any server. The social graph functionality of ActivityPub is not a goal; peer recommendations in the feed manifest serve discovery without server federation.

Layer 3 — Content

Content is distributed as BitTorrent bundles. Each bundle contains one logical publication: an HTML entry point, its associated CSS, and any images or video (WebP and WebM respectively). The bundle is addressed by its torrent hash, which appears in the author’s feed manifest.

BitTorrent’s swarm model means popular content costs the publisher nothing — readers collectively seed it. Obscure or old content naturally stops being seeded and disappears, which is the desired behaviour.

Both feed manifest torrents (Layer 2) and content bundle torrents are transported at this layer. BitTorrent handles both; there is no separate transport for feed metadata.

Key design decision recorded here: BitTorrent over IPFS. IPFS requires a persistent daemon, has a slow global DHT for unpopular content, and its mutable pointer system (IPNS) is unreliable in practice. Its ideological commitment to permanent storage conflicts with this project’s goal of natural content expiry. BitTorrent is simpler, more widely implemented, and its economic model (seeder attrition) produces the right emergent behaviour.

Layer 4 — Discovery

Discovery is entirely local. The browser maintains a full-text search index over all content the user has fetched. There is no central index to submit to, no ranking algorithm to optimise for, and no third party involved.

New content is found through two mechanisms:

1. Feed subscriptions — you follow an author’s public key; their new content appears as they publish it.
2. Trust-graph recommendations — feed manifests may include a signed list of other public keys the author recommends. The browser can optionally fetch and surface those feeds, building a web of trust from subscriptions outward.

Key design decision recorded here: Local index over federated search. Federated search requires coordination infrastructure and reintroduces a surface for gaming. Local indexing over personally-fetched content means search results are by definition relevant to what the user has already expressed interest in.

Cold-start: A new user’s first trusted author key comes from receiving a btpk magnet link through any channel — a link shared via chat, email, QR code, printed material, a post on the regular web, or a starter pack pre-loaded by the client application. Once the first key is acquired, the trust graph expands outward through author recommendations. There is no required universal index and no protocol-mandated directory.

Starter pack caveat: Client implementations may distribute optional starter packs — curated sets of btpk magnet links for seed authors. These lower the barrier for new users but introduce a de facto trust authority: the entity that curates the starter pack shapes who new users first encounter. This is the same structural issue as certificate authorities, expressed at the social layer rather than the protocol layer. Starter packs are explicitly outside the protocol, replaceable by the user, and non-authoritative. Client implementations should make starter pack provenance visible and allow users to modify or remove them.

Layer 5 — Rendering

The browser (or browser-like application) renders content bundles with a strictly constrained capability set: HTML, CSS, WebP images, WebM video. No JavaScript. No cookies. No remote resource loading of any kind. No forms with remote action targets.

Links to the regular web are permitted but visually distinguished and open in a separate conventional browser context. The rendering layer enforces the guarantee that no request leaves the machine as a result of viewing content.

Key design decision recorded here: Custom renderer vs. stripped Chromium vs. existing minimal browser. Chromium forks are large and will resist JS removal at the architecture level. A fork of a minimal renderer (NetSurf, Servo, or a purpose-built engine) is preferable. The rendering surface is small enough — HTML + CSS only — that a purpose-built renderer is not unreasonable as a long-term goal. The browser document will explore implementation options.

5. Content Format Constraints

The permitted content format set is chosen to be minimal but not gratuitously restrictive:

Excluded and rationale:

A detailed content format specification will be produced as a separate document.

6. Security and Trust Model

6.1 What the protocol guarantees

• Content integrity: A bundle whose hash matches the value in a signed feed manifest was produced by the holder of the corresponding private key and has not been modified in transit.
• Render-time privacy (strong, architectural): Once a bundle is locally available, rendering it causes zero outbound network requests. The rendering layer cannot leak reader identity or reading behaviour to any party.
• Retrieval-time privacy (transport-dependent): Feed fetching and BitTorrent swarm participation are observable at the network level. Swarm peers can observe other peers. Privacy at retrieval time depends on transport choices made by the client (Tor, I2P, VPN) and is not guaranteed by the protocol itself.
• No impersonation of an established key: Content cannot be falsely attributed to a known public key without access to the corresponding private key. Continuity of key control proves authorship continuity; it does not prove real-world identity. First-contact trust is social, not web-anchored.

6.2 What the protocol does not guarantee

• Author identity in the real world: A public key is a pseudonym. Linking it to a real person is outside the protocol.
• Content legality: The protocol is neutral infrastructure. Illegal content can be published. Mitigation is at the client layer (blocklists of known-bad public keys, content filtering) not the protocol layer.
• Availability: Content lives as long as peers seed it. The protocol makes no availability guarantee.
• DHT reachability: Feed freshness depends on DHT access. Hostile networks can block or degrade BitTorrent DHT. When DHT is unavailable, the client cannot learn of feed updates until DHT becomes reachable again (or until it fetches an alternative transport mirror of the feed manifest).
• Key continuity: If an author loses their private key, they cannot update their feed. If a key is compromised, the attacker can publish content under the author’s identity. Readers must be notified out of band. There is no protocol mechanism to revoke or rotate a key.

6.3 Threat model (summary — to be expanded)

7. Relationship to Existing Web

This network is not a replacement for the existing web. It is a parallel network optimised for a specific class of content: articles, essays, documentation, photography, short video, and similar long-form or static media.

The regular web remains appropriate for:

• E-commerce and transactional services
• Social networking with interactive features
• Real-time communication
• Applications requiring server-side logic

DecentWeb is operationally independent of the existing web. Publishing, subscribing, and reading require no DNS, HTTPS, or old-web infrastructure.

The two networks relate in the following ways:

• DecentWeb → old web (content links): Content on this network may link outward to the regular web. Those links open in a conventional browser context, clearly marked as leaving the network. This is a reader-initiated action, not a protocol operation.
• Old web → DecentWeb (informal, social): Authors may post btpk magnet links on their websites, in their old-web RSS feeds, or in any other channel. This is social convention, not a protocol dependency. The old web is neither a trust anchor nor a required onboarding path.
• Canonical DecentWeb address: magnet:?xs=urn:btpk:<base32-public-key> is the address format for a DecentWeb author. It can be embedded in a web page, printed on a card, or shared in any medium. Resolving it requires only a DHT-capable client, not a browser or web connection.

8. Open Questions for Future Documents

The following questions are deferred to layer-specific documents:

1. Identity document: Key lifecycle model is decided (see Layer 1 summary). Remaining questions: should the feed manifest include an explicit successor-key field for announced rotation? What is the reader-local trust store format? What UX should clients show when a key transition is detected?
2. Feed document: Exact schema for the signed feed manifest. Encoding format (CBOR is preferred for compactness; JSON for debuggability). BEP 44 payload encoding. Feed manifest torrent seeding expectations. Polling cadence and cache strategy for mutable DHT items. Should recommendation blocks carry raw public keys, btpk magnet links, or both?
3. Content document: Bundle format specification. Maximum bundle size. Handling of multi-part long-form content. Seeding expectations for authors. Are feed updates append-only or replace-in-place? How are minor corrections (e.g. typos) surfaced without requiring a full re-seed? Are shared assets (stylesheets, fonts) duplicated across bundles or addressed separately?
4. Discovery document: Trust graph traversal depth and cycle prevention. Local index format and update strategy. Should clients support signed starter packs or starter-pack bundles, and if so, what is the signing and provenance model? Handling of recommended feeds the user has not explicitly chosen.
5. Rendering document: HTML and CSS subset definition. Handling of unsupported elements. Browser implementation strategy.
6. Feed transport document (or appendix to feed document): What fallback transport strategies should exist when DHT access is degraded? How are HTTP mirror feeds discovered? How is the canonical BEP 44 item reconciled with HTTP-hosted copies?
7. Governance document: How are format standards updated? Who may propose changes? How are breaking changes handled?

9. Document Roadmap

This document is the root of a tree of specifications. The intended expansion order:

1
2
3
4
5
6
7
8
9

decenweb-design-v0.1.md          ← this document
├── decenweb-identity.md         Ed25519 identity layer
├── decenweb-feed.md             Feed manifest format and signing
├── decenweb-content.md          Bundle format and BitTorrent integration
├── decenweb-discovery.md        Local indexing and trust-graph discovery
├── decenweb-rendering.md        Browser constraints and implementation
├── decenweb-security.md         Full threat model and mitigations
├── decenweb-formats.md          HTML/CSS/media subset specification
└── decenweb-governance.md       Standards process

10. Version History

This document was produced through a design conversation exploring alternatives to the advertising-dependent, server-hosted web. The options-considered sections within each layer summary are intentionally brief here; each will be expanded with full analysis in the corresponding layer document.