Entropy is a Layer 2 protocol for decentralized social networks that enables the exchange of heavy multimedia content (video, 4K, audio, images) without relying on centralized servers or expensive storage relays. It runs entirely in the browser using a Browser-as-a-Node architecture and a bandwidth reciprocity incentive system.

Content is split into 5 MB chunks, hashed into a Merkle tree, and published as a Nostr kind:7001 Chunk Map event. Peers discover content through Nostr relays and exchange chunks directly via WebRTC DataChannels — encrypted, verifiable, and fully decentralized.

Download and install the extension from the releases folder.

Navigate to Entropy

• P2P Streaming — Progressive playback via MediaSource Extensions while chunks download from multiple peers in parallel
• Chunk Maps on Nostr — Content metadata lives on Nostr (kind:7001); binary data travels peer-to-peer
• Credit Economy — Bandwidth reciprocity with cryptographically signed Proof of Upstream receipts
• Background Seeding — Browser extension keeps serving chunks even when the tab is closed
• Cold Storage — High-ratio seeders earn premium credits by hosting unpopular content
• Plausible Deniability — Nodes only hold opaque binary fragments; no single node possesses recognizable content
• Keyframe-Aligned Chunking — Video chunks align to keyframes (IDR) for seamless MSE playback from any segment
• Credit Integrity — Tamper-resistant hash-chain ledger + peer-signed receipts prevent credit manipulation

┌─────────────────────────────────────────────────────────────────────┐
│                         USER'S BROWSER                              │
│                                                                     │
│  ┌──────────────────────┐     ┌──────────────────────────────────┐  │
│  │   Extension Entropy  │◄───►│        Web App Entropy           │  │
│  │  (Manifest V3)       │     │     (SPA — React + Vite)         │  │
│  │                      │     │                                  │  │
│  │ • Service Worker     │     │ • Social Feed (Nostr)            │  │
│  │ • Background Seeding │     │ • Media Player (MSE)             │  │
│  │ • Node Dashboard     │     │ • Upload Pipeline                │  │
│  │ • Credit Ledger      │     │ • Profile & Settings             │  │
│  └──────────┬───────────┘     └───────────────┬──────────────────┘  │
│             └────────────┬────────────────────┘                     │
│                          ▼                                          │
│              ┌───────────────────────┐                              │
│              │    @entropy/core      │                              │
│              │   (Shared Library)    │                              │
│              │                       │                              │
│              │ • Chunking + Merkle   │                              │
│              │ • WebRTC Transport    │                              │
│              │ • Nostr Protocol      │                              │
│              │ • Credit Ledger       │                              │
│              │ • IndexedDB Storage   │                              │
│              └───────────┬───────────┘                              │
│                          │                                          │
└──────────────────────────┼──────────────────────────────────────────┘
                           │
            ┌──────────────┼──────────────────┐
            ▼              ▼                  ▼
     ┌────────────┐ ┌────────────┐   ┌──────────────┐
     │ Nostr      │ │ WebRTC     │   │ STUN / TURN  │
     │ Relays     │ │ Peers      │   │ Servers      │
     │ (Metadata) │ │ (Data P2P) │   │ (Signaling)  │
     └────────────┘ └────────────┘   └──────────────┘

Upload → Seed → Play in 5 stages:

1. Chunk — File is split into ~5 MB pieces (keyframe-aligned for video)
2. Hash — SHA-256 per chunk → Merkle root for integrity
3. Store — Chunks persisted in IndexedDB via the browser extension
4. Delegate — Extension activates WebRTC seeding in the background
5. Publish — kind:7001 Chunk Map event signed and published to Nostr relays

Other users discover the content in their feed, connect via WebRTC signaling over Nostr ephemeral events (kind:20001), and download chunks in parallel from multiple peers with progressive streaming playback.

📖 Deep dives: architecture.md · flow.md

A regular web page is ephemeral — the moment you close or navigate away from a tab, all JavaScript execution stops. For a P2P network that depends on nodes staying online to serve chunks to other peers, this is a fundamental problem.

The Entropy browser extension solves this by running a Manifest V3 Service Worker — a persistent background process that continues operating even when the web app tab is closed. This is the architectural reason the extension is not optional for uploaders and seeders.

Browser Tab (closed)              Extension Service Worker (alive)
                                  ┌──────────────────────────────┐
                                  │  • Listens for WebRTC offers │
                                  │    via Nostr ephemeral events │
                                  │  • Serves chunk requests from │
                                  │    the IndexedDB chunk store  │
                                  │  • Earns credits for uploads  │
                                  │  • Verifies cold storage      │
                                  │    custody challenges         │
                                  │  • Prunes stale data (LRU)   │
                                  └──────────────────────────────┘

Without the extension, Entropy still works as a viewer and downloader — you can watch content and browse the feed. But to upload, seed, or earn credits, the extension is required. This is by design: it ensures that seeders are reliable long-term nodes, not ephemeral browser tabs.

🔌 Install the extension → see Build the Browser Extension below.

  @entropy/core
       ▲     ▲
       │     │
       │     └──────────────┐
       │                    │
  @entropy/web      @entropy/extension

• core is pure and portable — no internal dependencies.
• web and extension depend on core but never on each other.
• Communication between web and extension is exclusively via message passing (postMessage / chrome.runtime).

• Node.js 18+
• pnpm 9+

pnpm install

pnpm dev:web

Opens the Entropy web app at http://localhost:5173. Requires a Nostr identity (NIP-07 extension like Alby or nos2x) or the Entropy extension for key management.

Pre-built packages are available in the releases/ folder while the extensions are pending store review. Download the .zip for your browser and follow the sideload instructions below.

Chrome / Chromium / Brave / Edge:

1. Download releases/entropy-extension-chrome-v*.zip and unzip it to a local folder.
2. Open chrome://extensions → enable Developer mode (top-right toggle).
3. Click Load unpacked → select the unzipped folder.

Firefox:

1. Download releases/entropy-extension-firefox-v*.zip.
2. Open about:addons → click the gear icon → Install Add-on From File…
3. Select the .zip file directly (Firefox accepts signed or temporary .zip installs).

   For persistent install (survives restart) without signing, open about:config → set xpinstall.signatures.required to false — for development/testing only.

Chrome:

pnpm --filter @entropy/extension build

Load unpacked from apps/extension/dist/ in chrome://extensions (enable Developer mode).

Firefox:

pnpm --filter @entropy/extension build:firefox

Load as temporary add-on from apps/extension/dist/ in about:debugging#/runtime/this-firefox.

To regenerate the distributable .zip files in releases/ (builds both targets in sequence):

# Both Chrome + Firefox in one command
pnpm package:extensions

# Or individually
pnpm --filter @entropy/extension package           # → releases/entropy-extension-chrome-v*.zip
pnpm --filter @entropy/extension package:firefox   # → releases/entropy-extension-firefox-v*.zip

• Click the Entropy icon in the toolbar to see the popup with node status, credit ratio, and integrity info.
• Click Open Dashboard (or go to extension options) for the full node dashboard: chunk inventory, relay configuration, peer reputation, cold storage assignments, and network metrics.

# Run all tests across all packages
pnpm test

# TypeScript type checking
pnpm typecheck

# Per-package
pnpm --filter @entropy/core test
pnpm --filter @entropy/web test
pnpm --filter @entropy/extension test

Tests use Vitest with fake-indexeddb for storage tests. Core package has 190+ unit tests covering chunking, hashing, Merkle trees, Nostr events, credit ledger, proof of upstream, peer reputation, chunk transfer protocol, and credit integrity.

Content is not uploaded to Nostr relays. Instead, a Chunk Map event is published containing the Merkle root hash, individual chunk hashes, file size, MIME type, and a list of active seeders (gatekeepers). Peers use this map to discover and verify content.

{
  "kind": 7001,
  "tags": [
    ["x-hash", "<merkle_root_sha256>"],
    ["chunk", "<hash_0>", "0"],
    ["chunk", "<hash_1>", "1"],
    ["size", "157286400"],
    ["mime", "video/mp4"],
    ["title", "My Video"]
  ]
}

Entropy uses bandwidth reciprocity to prevent free-riding:

• Earn credits by seeding chunks to other peers (upload)
• Spend credits by downloading chunks (download)
• Proof of Upstream (kind:7772) — cryptographic receipt signed by the receiver proving that a transfer happened
• Credit Gating — seeders verify requester's credit balance before serving chunks
• Onboarding — new users host "popular" content to earn their first credits

Users with high upload ratios (≥ 2.0) become eligible to host unpopular ("cold") chunks. In exchange, they earn premium credits that unlock priority bandwidth and faster downloads. The extension runs periodic cycles to assign, verify (via Custody Challenge/Proof), and prune cold storage assignments.

The credit ledger is protected by three layers:

1. Hash Chain — each entry links to the previous via SHA-256, detecting any tampering
2. Chunk-Backed Verification — entries are cross-referenced against the real IndexedDB chunk inventory
3. Peer-Signed Receipts — every credit is backed by a Schnorr signature from the participating peer (kind:7772)

If integrity verification fails, the ledger resets to zero and cold storage eligibility is revoked.

📖 Full design: credit-integrity.md

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).