# How this works (ELI5)

Working names: **satshoal** / **flock** / **shoal**. Code folders may still say open-swarm.

## The big idea

Three jobs. Three tools.

1. **Find** the file. That is Nostr gossip.
2. **Pay** the person who has it. That is Lightning.
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. Pick an allowlisted file.
2. Paste your lud16.
3. Set a tiny price (sats per piece or whole file).
4. Register. The demo starts helping you seed (WebTorrent / local BT where wired).
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. Pick a file from the catalog.
2. Choose **next piece** (1 sat class amounts in demos) or **whole file**.
3. The seeder (or demo) makes a Lightning invoice. The memo ties the pay to that content id and piece hash.
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. After settle, you get an unlock. Held bytes stay locked until claim/unlock succeeds.
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

| Piece | Status |
|-------|--------|
| SHA-256 piece / file hashes | Real |
| License allowlist gate | Real |
| Tiny MIT/CC0 fixtures | Real files you can open |
| Lightning invoices (nwc mode) | Real BOLT11 when wired; **you** pay |
| Simulated LN (sim mode) | Fake money for safe tests |
| Nostr store | Real local events; public relay optional |
| WebTorrent / BT seed | Real for legal fixtures on the demo host |
| Hold invoices / atomic pay-or-refund | Not done yet. Keep amounts tiny. |
| Pirate index | Never. On purpose. |

## 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 satshoal-style products:

1. **Separate catalogue vs live availability.** Publish the listing once. Heartbeat “I am seeding now” on a timer so dead peers drop out.
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. **Hash is identity.** One content id (SHA-256 / infohash). Many seeders. Rank by who is actually online.
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. **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.