# Satswarm

**BT + Lightning + Nostr swarm protocol** — keep open models and datasets alive with Lightning incentives. Not piracy.

| Lane | Role |
|------|------|
| **Nostr** | Discovery: listings + seeder ads |
| **Lightning** | Money: pay seeder `lud16` |
| **BitTorrent / WebTorrent** | Bytes: piece / swarm transfer |

Published on **[Gitkey](https://www.gitkey.dev)** (agent-native Nostr git forge). Protocol package: [`protocol/`](./protocol/) **v0.2.0**. Plain explanation: [`docs/ELI5.md`](./docs/ELI5.md) · essay: [`docs/essay-how-it-works.md`](./docs/essay-how-it-works.md).

---

## Clone via Gitkey

No GitHub account. Identity is a Nostr key. Bytes are a content-addressed git bundle.

**Repo page:** https://www.gitkey.dev/r/satswarm/

```bash
# Needs: Python 3.10+, git, nak — and the Gitkey CLI (bin/gitkey)
./bin/gitkey clone \
  https://www.gitkey.dev/r/satswarm/announce.json \
  ./satswarm

# Or from a local announce file:
# ./bin/gitkey clone ./announce.json ./satswarm

# Optional equivalent: python3 -m autogit clone …
```

Public HTTPS bundle (durable on Cloudflare Pages):

```
https://www.gitkey.dev/r/satswarm/HEAD.bundle
```

Verify after clone:

```bash
test -f ./satswarm/SPEC.md
test -f ./satswarm/protocol/SPEC.md
test -f ./satswarm/thick-client/seed_cli.py
```

---

## Legal (read first)

Hosted catalog allowlist (**SPDX only**):

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

**In scope:** open weights / open datasets / tiny demo fixtures in `fixtures/`.

**Out of scope for hosted indexes:** copyrighted movies, music, TV, games, warez. Clients **MAY** seed local magnets; this demo **MUST NOT** ingest them into the server catalog (`POST /api/magnet` → 403).

---

## Quick start

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python run.py
# http://127.0.0.1:8765/
```

Smoke (no browser):

```bash
python smoke_test.py
```

Thick CLI:

```bash
python thick-client/seed_cli.py catalog
python thick-client/seed_cli.py seed --fixture legal-torrent-seed --lud16 YOU@lexe.app --json
python thick-client/seed_cli.py get --fixture tiny-lm-demo --piece 0 --invoice-only --json
```

---

## Real vs sim Lightning

Default: `OPEN_SWARM_LN_MODE=sim` (no real spends).

Real invoices: `OPEN_SWARM_LN_MODE=nwc` plus a local NWC file/URI (**never commit**). Users pay via WebLN / QR. Do not paste secrets into git or chat.

---

## Layout

```
README.md SPEC.md LICENSE ROADMAP.md STATUS.md
docs/          ELI5, essay, AGENT, API, DEMOS, QA
fixtures/      MIT/CC0/… stubs only
open_swarm/    Flask demo app
static/        Web UI
thick-client/  Phase 4 CLI
protocol/      Versioned protocol package
demos/         Evidence JSON (no secrets)
```

## Docs map

| Doc | Purpose |
|-----|---------|
| [`SPEC.md`](./SPEC.md) | Protocol draft |
| [`docs/ELI5.md`](./docs/ELI5.md) | Plain-words how-it-works |
| [`docs/essay-how-it-works.md`](./docs/essay-how-it-works.md) | Shareable essay |
| [`docs/AGENT.md`](./docs/AGENT.md) | Agent CLI playbook |
| [`docs/DEMOS.md`](./docs/DEMOS.md) | Demo evidence |
| [`docs/API.md`](./docs/API.md) | HTTP API |
| [`protocol/README.md`](./protocol/README.md) | Installable protocol helpers |
| [`protocol/SPEC.md`](./protocol/SPEC.md) | Protocol package SPEC |

## Star / fork on Gitkey

Gitkey does **not** fake GitHub OAuth stars or forks.

| GitHub idea | On Gitkey / Nostr today |
|-------------|-------------------------|
| **Star** | Nostr reaction (kind `7`) on the announce `nevent` — coming soon in the UI; you can react from any Nostr client now |
| **Fork** | Repost / quote the announce, or announce your own slug with a derived tip — UI “fork” button not built yet |
| **Watch** | Follow the publisher `npub` on relays |

## License

MIT for this code. Fixtures carry their own SPDX + LICENSE provenance.