Bitswarm Protocol Specification (Draft MVP)

Legal model (normative split):

1. Clients MAY seed any content their users choose (local-only magnets never required to hit a hosted index).
2. Hosted indexes / this demo site catalog SHOULD filter via the SPDX allowlist below and MUST NOT ingest arbitrary magnets into the server catalog API.
3. Primary intended indexed content: open AI model weights and open datasets, plus tiny demo fixtures.
4. Copyrighted movies, music, TV, games, warez are permanently out of scope for hosted indexes. Nothing here is legal advice.

Synced with /workspace/open-swarm-protocol v0.2.0.

1. Goals

Keep open models and datasets alive by combining:

Layer	Role
BitTorrent-style bytes	Piece hashes, infohash-like content id, swarm transfer
Lightning money	Per-piece payment + retainer (availability) bounties
Nostr gossip / identity	Listings, seeder ads, bounty notices, (optional) attestations

Tagline: Keep open models alive with Lightning — not piracy.

2. Roles

Role	Responsibility
Leecher	Discovers allowlisted listings; pays sats per piece; verifies piece hashes
Seeder	Advertises availability + rate card; serves pieces after invoice settle; answers retention challenges
Retainer funder	Opens / funds a daily (or epoch) bounty so seeders stay online even without continuous leechers
Attestor (optional MVP stub)	Observes challenge results; may publish attestation events. MVP may co-locate attestor with the client

3. License allowlist and rejection rules

Allowlist (SPDX)

MIT
Apache-2.0
BSD-2-Clause
BSD-3-Clause
CC0-1.0
CC-BY-4.0
Unlicense

Rules (MUST)

1. Every content listing MUST include license_spdx from the allowlist.
2. Hosted indexes SHOULD run a license gate before: publishing a listing into the public catalog, registering a seeder ad on the index, opening a retainer on the index, or mediating piece payment through the index.
3. If license is missing, unknown, or not allowlisted → hosted indexes reject / block. Do not index.
4. Hosted indexes MUST NEVER include magnets, indexes, or instructions for copyrighted movies/music/TV/games/warez.
5. Clients MAY still seed user-chosen magnets locally without uploading them to a hosted catalog.

4. Content addressing (bytes)

Inspired by BitTorrent, simplified for MVP:

Piece size: fixed per listing (demo fixtures use 256 bytes).
Piece hash: SHA-256 of piece bytes, hex.
File hash: SHA-256 of full payload.
Infohash-like id: SHA-256( concat(piece_hashes) || content_id || license_spdx ) hex.

Demo listings may use a local payload_ref (path under fixtures/) instead of a public magnet. Magnets are only appropriate for allowlisted redistributable content; this MVP ships local fixtures only.

5. Event kinds (draft private range)

Kinds 39000–39010 are a draft / experimental private range for Bitswarm. Treat as non-final; document names clearly. Prefer parameterized replaceable semantics via d tag where noted.

Kind	Name	Replaceable?	Content (JSON) highlights
39000	`content_listing`	parameterized (`d` = infohash)	`infohash`, `file_hash`, `piece_hashes[]`, `piece_size`, `license_spdx`, `payload_ref` or magnet (allowlisted only), `sats_per_mib`, `lnaddress`
39001	`seeder_ad`	parameterized (`d` = infohash)	`infohash`, rate card (`sats_per_piece` / `sats_per_mib`), `ln_receive`, `challenge_endpoint` stub
39002	`retainer_bounty`	parameterized (`d` = infohash)	`infohash`, `daily_bounty_sats`, `epoch_hours`, `license_spdx`
39003	`retainer_fund`	regular	`infohash`, `amount_sats`, `funded_total`
39004	`challenge_result`	regular	`infohash`, `piece_index`, `expected_hash`, `proof_hash`, `passed`, `payout_sats`
39005	`attestation`	regular (stub)	Optional third-party confirm of challenge / uptime

Common tags: ["i", "<infohash>"], ["license", "<spdx>"], ["d", "<infohash>"] for parameterized kinds.

MVP transport: local SQLite Nostr-like store (required, works offline). Optional best-effort publish to a public relay via WebSocket.

6. Piece invoice / HTLC memo format

infohash|piece_index|piece_hash|nonce

Example:

a5359f6d…|0|9c1a…|f3a91b02c8d4e7aa

infohash — content id
piece_index — integer
piece_hash — expected SHA-256 hex of piece
nonce — payer/seeder anti-replay token

Whole-file (demo + thick clients):

infohash|ALL|remaining_count|file_hash|nonce

Alias (accepted by parsers; future hold-invoice binding):

infohash|FILE|file_hash|nonce