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

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

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.
• 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.

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.