# Open Swarm 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 Open Swarm. 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
```

Invoices SHOULD target the seeder's lud16 from kind `39001`. MVP is pay→deliver→hash-verify; production SHOULD prefer hold invoices.

---

## 7. Piece-pay flow (HTLC mental model)

Sample implementation **simulates** Lightning; real deployment would use BOLT11 / hold invoices / NWC.

```
Leecher                         Seeder                      LN (sim or real)
   |                               |                              |
   |  discover listing (Nostr)     |                              |
   |  license gate PASS            |                              |
   |  request piece N              |                              |
   |------------------------------>|                              |
   |                               | create invoice               |
   |                               | memo = infohash|N|hash|nonce |
   |                               |----------------------------->|
   |  pay invoice (HTLC)           |                              |
   |------------------------------------------------------------->|
   |                               | <---- settled ---------------|
   |                               | verify local piece hash      |
   |  <---- piece bytes -----------|                              |
   |  verify piece hash            |                              |
   |  abort / dispute if mismatch  |                              |
```

**Honest trust (MVP):** seeder is paid on settle before bytes in the simulator (atomic in-process). Production SHOULD prefer proofs or hold-invoice patterns so payment settles only after verifiable delivery or within a short challenge window.

---

## 8. Retainer epoch payout flow

Goal: pay seeders for **availability**, not only for active downloads.

1. Funder publishes `retainer_bounty` (39002) for an allowlisted infohash.
2. Funder publishes `retainer_fund` (39003) and credits a fund balance (sim wallet / real LN escrow later).
3. Each epoch (e.g. 24h; demo runs one epoch on demand):
   - Attestor/client picks a random `piece_index`.
   - Seeder must prove it holds data whose SHA-256 equals the listing’s piece hash (MVP: return/hash the piece).
   - On pass: debit fund, credit seeder (`challenge_result` 39004).
   - On fail: no payout; optionally demote seeder ad.

---

## 9. Threat model and trust levels

| Threat | Notes | MVP mitigation |
|--------|-------|----------------|
| **Sybil seeders** | Many fake identities farm retainer | Stake / bond (future); rate-limit; attestation |
| **Fake seed** | Advertise without data | Piece challenge each epoch; leecher hash verify |
| **Exit scam** | Take piece payment, withhold data | Hold invoices / CLTV windows (future); reputation; small piece sizes |
| **License laundering** | Claim MIT on pirated media | Client allowlist + human/governance review; no media indexes |
| **Relay spam** | Junk events on Nostr | Local-first store; filter by license tag + known publishers |

**Honest trust levels (MVP):**

1. **Local fixtures + simulated wallets** — full control, for demos/tests.  
2. **Local store + optional public relay** — gossip is public; money still simulated.  
3. **Real LN (future)** — NWC / node hooks; same license gate.  
4. **Attested retainers (future)** — independent attestors, bonds, slashing.

---

## 10. Out of scope

- Copyrighted movies, music, TV, games, warez, or any non-allowlisted content  
- Building or shipping magnet indexes for such content  
- Circumventing copyright or license gates  
- Guaranteeing anonymity or legal advice  

---

## 11. Comparison note (Pirate Face)

Pirate Face–style projects surface **magnets + points** for open model discovery. Open Swarm adds **Lightning incentives** (piece-pay + retainers) and **Nostr gossip** for listings/seeders, with a hard **license allowlist** so the swarm stays on redistributable open content.