How this works (ELI5)

Public brand: Bitswarm. Code folders may still say open-swarm or satswarm.

The big idea

Three jobs. Three tools.

1. 1. Find the file. That is Nostr gossip.
2. 2. Pay the person who has it. That is Lightning.
3. 3. Move the bytes. That is BitTorrent / WebTorrent.

Nostr does not carry files. Lightning does not carry files. Torrents do not carry money. Each piece stays in its lane.

What you can share here

Only files with an allowlisted open license.

Allowed labels (SPDX): MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause, CC0-1.0, CC-BY-4.0, Unlicense.

This demo is for tiny open stubs and open model-style fixtures. Not movies. Not commercial music. Not games. Not warez.

The site catalog checks the license. Bad licenses get blocked. You can still seed a magnet on your own machine. The site will not index it.

Catalog allowlist

Think of a shelf with a bouncer.

• Each listing must show an SPDX license.
• The bouncer only lets allowlisted licenses on the public shelf.
• Magnets for random stuff get a hard no from the hosted API.

That keeps the public demo legal and boring on purpose.

Earn / seed (lud16)

A lud16 is a Lightning address. It looks like an email. Example shape: you@wallet.example.

When you seed:

1. 1. Pick an allowlisted file.
2. 2. Paste your lud16.
3. 3. Set a tiny price (sats per piece or whole file).
4. 4. Register. The demo starts helping you seed (WebTorrent / local BT where wired).
5. 5. Copy a Nostr seeder ad. That ad says “I have this file, pay me here.”

When someone pays, sats go to your address. The demo host is not the payee unless you left the default demo address.

Get-file paywall + unlock

Getting a file is pay-then-bytes.

1. 1. Pick a file from the catalog.
2. 2. Choose next piece (1 sat class amounts in demos) or whole file.
3. 3. The seeder (or demo) makes a Lightning invoice. The memo ties the pay to that content id and piece hash.
4. 4. You pay with a wallet (Alby WebLN, QR, or paste Hub NWC in the browser). The box does not auto-pay for you in the main Get-file path.
5. 5. After settle, you get an unlock. Held bytes stay locked until claim/unlock succeeds.
6. 6. Your client checks the SHA-256. Wrong hash means reject.

Unpaid stays locked. Paid and verified unlocks.

WebTorrent / BitTorrent seeding

Bytes move like a normal torrent swarm when that path is on.

• Legal MIT / CC0 fixtures ship with real tiny payloads and, where present, .torrent / magnet metadata.
• The web UI can seed in-browser with WebTorrent for demos.
• A local seeder on the box can announce and serve pieces.
• Piece-pay for the protocol still goes through Lightning. BT moves bytes. LN moves money.

Thick client CLI

There is a Python CLI under thick-client/. Not an Electron app.

Agents and humans can:

• poll the catalog
• register as a seeder with a lud16
• ask for an invoice only (safe)
• optionally pay with a local NWC file and claim pieces
• prove that illegal magnets stay local and never hit the site index

Exit codes are simple: ok, usage/blocked, or pay/claim failed.

Nostr seeder ads

Listings and seeder ads are Nostr-shaped events (draft kinds in the 39000 range).

• Listing: what the file is, hashes, license.
• Seeder ad: who is online, rate card, lud16 to pay.

In this demo, events often live in a local SQLite store so it works offline. Optional publish to a real relay is a next step, not required to click around.

What is real vs demo

Where this can go (Napstr-inspired)

Napstr (napstr.net) shows a clean split: Nostr for discovery, private negotiation for who serves you, and a separate pipe for bytes (they use Tor onions; we use BT / WebTorrent for open content).

Ideas we can borrow for allowlisted bitswarm-style products:

1. 1. Separate catalogue vs live availability. Publish the listing once. Heartbeat “I am seeding now” on a timer so dead peers drop out.
2. 2. Private download negotiation. Keep onion/capability-style secrets (or BT peer tickets) out of the public feed. Public Nostr only for metadata and lud16 rate cards.
3. 3. Hash is identity. One content id (SHA-256 / infohash). Many seeders. Rank by who is actually online.
4. 4. Companion / thick client. Phone or CLI talks to your always-on seeder. The phone does not hold your Nostr secret or wallet keys.
5. 5. Withdraw when gone. When you delete a file, replace the Nostr ad so others stop asking you.

We keep Lightning in the money lane (Napstr today is not a zap client). We keep the SPDX bouncer so discovery stays on open licenses only.

One sentence

Find open files on Nostr, pay seeders with Lightning, move bytes with BitTorrent, and never put piracy on the public shelf.