logicsrc/prd/0006-add-pay2seed-spec.md

---
openprd: "0.2"
id: "0006"
title: "Add pay2seed, paid2seed, pay2stream and paid2stream to the OpenSwarm family"
status: Draft
authors:
  - anthony@profullstack.com
created: 2026-09-05
updated: 2026-09-05
repo: profullstack/logicsrc
discussion:
implementation:
tags:
  - openswarm
  - pay2seed
  - paid2seed
  - pay2stream
  - paid2stream
  - iplive
  - hls
  - ipfile
  - ippay
  - ipdb
  - bittorrent
  - torlink
  - bittorrented
  - c0mpute
supersedes:
superseded-by:
---

## Problem

BitTorrent is the best distribution network ever built and it has never
been a legitimate business, because two things are missing from the
protocol. Nobody is paid to seed, so a swarm lives exactly as long as
somebody feels like leaving a client open. And nothing about an upload says
who put it there or whether they were allowed to, so every index is a pile
of unattributed infohashes and every seeder is presumed to be doing
something wrong.

OpenSwarm (PRD 0005) fixed the first half for encrypted media: `ippay` pays
a seeder per verified piece served. It does not pay anyone to *stay*. A
piece that nobody downloads this month earns nothing, so an archive, a
backup, a dataset waiting for its buyer or a podcast's back catalogue is
exactly as unfunded as it was before. `ipfile.pin` on c0mpute pays a
storage node to hold a swarm, but only a c0mpute node, only for a private
`ipfile` swarm, and only through c0mpute's auction.

The second half, consent, is not addressed anywhere. bittorrented.com
indexes what the DHT crawl finds and runs a seedbox rental rail, and
neither has a place for "I made this, here is the licence, here is where to
send a notice". A user of ours who wants to share their own work, keep an
off-site copy of their own data, or seed an openly licensed dataset for
money has no way to say so that anyone else can check.

## Naming

`pay2*` is the client protocol: the side that pays, over HTTPS, and plays.
`paid2*` is the server protocol: the BitTorrent side that earns. One hub
implements both halves of a pair; a requester or viewer client implements
only `pay2*`; a seeder, relay or gateway implements only `paid2*`. The
first draft of pay2seed carried both halves in one document and was split
the same day.

## Goals

- **Consent is part of the upload.** A signed attestation with a fixed set
  of bases (`own`, `licensed`, `open-license`, `public-domain`, `personal`)
  and a notice endpoint, without which no hub lists the swarm. Public
  claims get a claim window and a public standing; false ones are voided
  on notice and count against the requester.
- **Anyone can pay to have anything kept.** An offer escrows a budget at a
  hub for a swarm to be held for N days by M seeders at a price per
  GiB-month. Public offers cover vanilla torrents and `ipdb` feeds; private
  offers cover `ipfile` ciphertext.
- **Anyone can be paid to keep it.** A seeder takes a lease, proves each
  period by challenge or probe, and is paid per proven period through the
  same `ippay` payee it already has for vouchers. torlink's headless daemon
  is the reference client; a laptop qualifies.
- **The market is one HTTP surface.** `GET /offers` is what a client picks
  work from. bittorrented.com is the reference hub.
- **Encryption on by default, access as the product.** Private swarms are
  the default; teams, invitations, member grants via the hub as keeper,
  rotation on removal, and per-seat pricing are in the spec. Public is
  opt-out and rides the DHT for free.
- **Reuse.** Offers are bought like passes (x402, `X-OpenSwarm-Payer`),
  payouts are `ippay` §5.6, challenges are c0mpute's storage challenge,
  feeds are `ipdb`, events are the family envelope. One new document, six
  new record types, no new primitive.

## Business model

Encryption is on by default: every private swarm is `ipfile` ciphertext
under a key the requester holds. Seeding is priced at the cost of disk and
is not where the money is. **Access is.** A requester invites team,
group or organisation members, and the hub (as keeper) issues them grants
to decrypt, at three in the morning, when the requester is offline, with
an audit trail and rotation on removal. A few seats are free so a family
or a three-person shop never pays; above that, seats and organisations
are billed monthly through the same CoinPay rail as everything else.
Public distribution is encryption switched off: a vanilla torrent that
the DHT finds for nothing and that the hub never charges for.

## Non-Goals

- Deciding what content is acceptable. The hub enforces that an
  attestation exists, is signed and is honoured on notice. Its truth is
  the requester's liability.
- Encrypting public swarms. Public is public; private is `ipfile`.
- A reputation system that crosses hubs. Standing is one hub's signed
  opinion.
- A token, a chain, or a DAO.
- The seeder client, the hub, or the library themselves. This PRD adds the
  specification; implementation is tracked in each repo (§ Requirements
  lists them).

## Users

- **A creator or label** who wants their own release kept online for a
  year without running a server, and wants it on record that they are the
  one who put it there.
- **A person keeping a backup** who wants three copies of ciphertext held
  by strangers for 30 days and deleted after, and never wants the strangers
  to know what it is.
- **An open data or open source publisher** with a 4 GB installer or a
  dataset who wants ten seeders paid to stay, and downloaders to pay
  nothing.
- **A seedbox operator or torlink user** with disk and bandwidth to spare
  who wants to be paid for holding swarms, and to see, before accepting,
  whether they would be holding a stranger's ciphertext or seeding a
  CC-BY dataset in the clear.
- **bittorrented.com** as the hub: attestations, offers, the market, and
  the seedbox rental rail it already runs, with IPTV and other passes sold
  beside it.
- **A c0mpute node** that already bids on `ipfile.pin` and now sees the
  same offers from any hub.

## Requirements

1. `docs/openswarm/pay2seed.md` and `paid2seed.md` together specify: the attestation record and
   basis table; the claim window and requester standing; the offer record,
   its purchase over x402, and its lifecycle; public swarms, public feeds
   on `ipdb`, private swarms; the lease record and slot rules; storage
   challenges and probes; GiB-month accrual, receipts and payout through
   `ippay`; the hub record extension and API; seeder client behaviour;
   notices and takedown; the `ipfile.pin` mapping; events; conformance.
1b. `docs/openswarm/pay2stream.md` and `paid2stream.md` specify the
   same for a live channel over `iplive`: consent for channels with the
   two rules for licensed feeds; relay offers per relay-hour with a
   gateway bonus; tickets and listings; presence proofs and the
   served-bytes ratio; gateways serving standard HLS in clear and sealed
   modes with an M3U and XMLTV EPG, so any IPTV player works with no new
   client; gateway-bound vouchers; stopping on a void.
2. `docs/openswarm.md` lists the four in the family table, the stack
   diagram, "What it defines" and "What already exists".
3. `docs/openswarm/spec.md` §11 registers the `pay2seed.*`, `paid2seed.*`, `pay2stream.*` and `paid2stream.*` record
   types and their signers.
4. `docs/openswarm/cli.md` gains the `ip seed` and `ip stream` command groups.
5. The `/openswarm` page on logicsrc.com lists the four among the
   protocols.
6. Implementations, tracked outside this repo:
   - bittorrented.com (`profullstack/media-streamer`): the reference hub.
   - torlink (`baairon/torlink`, via the `ralyodio` fork): the seeder
     client. Per-torrent seed time (#186) is the first piece.
   - `@profullstack/pay2seed`: the shared client (hub calls, records,
     signing) and the promo surfaces the Profullstack media sites embed.
   - c0mpute: `ipfile.pin` interop per §11.

## UX Notes

- An attestation is one form on the upload screen: what is it, why may
  you share it, where do notices go. The basis list is a radio group;
  `personal` is greyed out unless the swarm is private.
- The market listing shows, for every offer, the basis and visibility in
  words a seeder can act on: "Open licence (CC-BY-4.0), public, 7.4 GB,
  30 days, earns about $1.04". A seeder client MUST show the same.
- A seeder's own view is a table of leases: what, basis, earned so far,
  next challenge due, ends on. torlink's `/downloads` grows a `lease`
  block per torrent.
- A requester sees, per offer: status, seeders held out of wanted, proven
  periods, and a spend bar against the budget.

## Success Metrics

- A public swarm with an honoured attestation and a funded offer on
  bittorrented.com is held by its `seeders.min` within `graceHours`, and
  still has that many proven seeders at `expiresAt`.
- A torlink daemon takes a lease, passes every challenge for 30 days, and
  is paid out without an operator touching it.
- An `ipfile.pin` job from c0mpute and a `pay2seed.offer` from
  bittorrented.com are served by the same node with one code path.
- A notice against a public attestation ends every lease on it within
  `claimHours` and the requester's standing shows it.

## Risks & Open Questions

- **Sybil seeding.** One machine, many keys, one copy. `seeders.max`,
  probes to announced addresses, and refusing a shared payout address on
  one offer bound it; they do not remove it. Open: whether a hub should
  require a small stake per lease that a failed period forfeits.
- **Answer relaying on challenges.** A seeder holding nothing can fetch
  the four pieces inside a ten-minute deadline on a fast link. Probes are
  the stronger evidence for public swarms; deadlines should scale with
  piece count. Open: whether a challenge should also demand a piece the
  swarm currently has no other seeder for.
- **Claim window versus liveness.** Twenty-four hours before a public
  offer is listed is a day of nobody being paid. Open: a shorter window
  for `open-license` and `public-domain` bases, which a licence file in
  the swarm can substantiate.
- **Hub as escrow.** Budgets sit with the hub for up to a year. A hub
  going away takes them. Same trust as `ippay` passes, longer duration.
  Open: whether budgets should be released to the hub per period rather
  than at purchase.
- **Private and `personal` swarms are unreviewable by design.** Consent is
  the requester's signature and standing, nothing else. This is stated
  in the spec rather than hidden.
- **Naming.** The rest of the family uses `ip` names. `pay2seed` is the
  product name and reads as one to a seeder choosing work; the record
  types are `pay2seed.*` so the two never need reconciling.