How Bitswarm works

Public brand: Bitswarm

Internal code paths may still say open-swarm or satswarm.

Keep open models and open datasets alive with Lightning. Not piracy.

Three lanes

Lane	Job	Tool
Discovery	Who has what, at what price	Nostr events
Money	Pay the seeder	Lightning (lud16 → BOLT11)
Bytes	Move the payload	BitTorrent / WebTorrent

Nostr never carries file bytes. Invoices never embed the payload. Torrents never settle sats. Keeping those lanes apart is the whole design.

Legal shelf, not a pirate index

Hosted catalogs use a hard SPDX allowlist:

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

Intended indexed content: open weights, open datasets, and the tiny demo fixtures in this repo.

Out of scope for the hosted shelf: copyrighted movies, commercial music, TV, games, warez, or anything without an allowlisted license.

Clients may seed user-chosen magnets on a local machine. The site catalog API must not ingest those magnets. That split is intentional.

Catalog allowlist

Every public listing carries license_spdx. Before publish, seeder register, retainer, or mediated piece pay, the hosted index runs a license gate. Missing or unknown licenses are rejected. The bouncer is boring on purpose. Boring is how you stay legal.

Earn as a seeder (lud16)

A Lightning address (lud16) looks like name@domain. It is where sats land.

Flow:

1. Choose an allowlisted fixture or listing.
2. Paste your lud16 and set a rate (sats per piece or whole file).
3. Register. The demo helps you seed (WebTorrent in the browser, local BT where configured).
4. Copy a Nostr seeder ad (draft kind in the 39000 range). Peers learn you are online and how to pay you.

Downloads pay your address. The demo default lud16 is only a fallback for show-and-tell.

Get-file: paywall, then unlock

1. Pick a file.
2. Pay for the next piece, or buy the whole remaining file in one invoice.
3. Invoice memo binds payment to content id and expected hash (infohash|piece|hash|nonce, or whole-file forms).
4. You pay with WebLN (e.g. Alby), QR, or a browser-pasted Hub NWC. The main Get-file path does not silently spend a server wallet for you.
5. After settle, claim unlock. Held bytes stay locked until unlock succeeds.
6. Verify SHA-256 locally. Mismatch means discard.

Unpaid means locked. Paid and verified means unlocked.

Bytes on BitTorrent / WebTorrent

Legal fixtures include tiny real payloads. Some ship .torrent / magnet metadata for open content only.

Browser WebTorrent can seed for demos.
A box-local seeder can announce and serve pieces.
Protocol piece-pay still settles on Lightning. BT is the byte pipe.

Thick client CLI

thick-client/seed_cli.py is a Python CLI for humans and agents. Not Electron.

It can poll the catalog, register seeders, emit invoices without paying, optionally pay via a local NWC file, claim and hash-check pieces, and prove that arbitrary magnets stay local (seed-local / prove-blocked). Exit codes distinguish success, usage/block, and pay/claim failure.

Nostr seeder ads

Draft event kinds (experimental private range):

Kind	Role
39000	Content listing
39001	Seeder ad + rate card + lud16
39002–39004	Retainer bounty / fund / challenge result
39005	Attestation stub

The demo stores events in local SQLite so everything works offline. Publishing to a public relay is optional.

What is real vs what is demo

Real today

Piece and file SHA-256
SPDX allowlist enforcement on the hosted catalog
Tiny MIT / Apache / BSD / CC0 / Unlicense fixtures
Real LNURL invoices when OPEN_SWARM_LN_MODE=nwc (user pays)
Local Nostr-like event store
WebTorrent / BT seeding for legal fixtures

Demo or unfinished

Simulated Lightning when mode is sim
Optional public Nostr relay (not required for the UI)
Hold invoices / HTLC-preimage binding (prefer tiny amounts until this exists)
Full attested retainer markets

Never

A hosted pirate magnet index

Where this can go (ideas from Napstr)

Napstr rebuilt peer music sharing with Nostr for discovery and Tor for private transfers. It is not a Lightning value-for-value client today. The architecture still teaches useful patterns for an open-license bitswarm product:

1. Catalogue ≠ heartbeat. Publish metadata once (Napstr kind 30421). Publish short-lived “I am seeding these ids” heartbeats (30422) so dead peers expire.
2. Negotiate in private. Use encrypted DMs (NIP-17 style) for capability tickets or peer intro; keep public relays free of transfer secrets. Map that to BT peer exchange or webseed tickets while lud16 stays public on the seeder ad.
3. Content id is the hash. Aggregate many authors per file id. Rank by live availability, not by who shouted first.
4. Thick desktop + thin companion. Phone or CLI pairs to your seeder (Napstrfy uses Iroh). Secrets and Tor/BT stay on the always-on box.
5. Explicit withdrawal. Replace catalogue events when files leave the share folder so the graph does not lie.

Our money lane stays Lightning. Our byte lane stays BitTorrent for redistributable open files. Our discovery lane stays Nostr. The SPDX gate stays non-negotiable for anything the hosted index will show.