logicsrc/docs/openswarm/paid2seed.md

# paid2seed: The Server Protocol for Paid Seeding

Status: 0.1 draft. Member of the [OpenSwarm](../openswarm.md) family.
Depends on the [core](./spec.md), [`ipfile`](./ipfile.md) and
[`ippay`](./ippay.md). Its client half is [`pay2seed`](./pay2seed.md).

## 1. Scope

`paid2seed` is the side that gets paid. It is spoken by a seeder, a
BitTorrent client with disk and uptime to sell, to a hub over HTTPS and to
the swarm over the ordinary wire. It defines:

- **Leases.** The hub's binding of one seeder to one `pay2seed.offer` for
  one period at one price.
- **Proof of seeding.** Storage challenges answered from held pieces, and
  probes in which a verifier fetches pieces over BEP 3 or the `ipfile`
  extension. Both work on a vanilla torrent, which is what makes seeding
  a public swarm payable.
- **Settlement.** GiB-month accrual per proven period, receipts, and
  payout through the `ippay` payee a seeder already has for vouchers.
- **The seeder client**: how a torrent client polls a market, takes work,
  seeds it, proves it, and resumes after a restart. torlink's headless
  daemon is the reference.

Consent, offers, the requester's view and notices are
[`pay2seed`](./pay2seed.md). A hub implements both. A seeder client
implements only this document.

### Non-goals

Anything about what the data is. A seeder sees an infohash or a file key,
a size, a basis and a visibility, and decides whether to hold it. It is
never asked to judge it and never able to read a private swarm.

## 2. Terminology

- **Seeder.** An identity that holds a lease and serves the swarm.
- **Verifier.** Whoever issues challenges and probes: the hub, a c0mpute
  verifier node, or the requester. The offer names who may.
- **Lease.** One seeder's share of an offer (§3). **Period.** The unit of
  accrual and proof, `offer.proof.everyHours` long.
- Other terms as `pay2seed` §2.

## 3. Leases

### 3.1 Record

```json
{
  "openswarm": "0.1",
  "type": "paid2seed.lease",
  "hub": "ed25519:c9f1…",
  "offer": "sha256:1b7f…",
  "seeder": "ed25519:a41e…",
  "slot": 1,
  "priceUsdPerGibMonth": "0.150000",
  "startsAt": "2026-09-05T18:30:00.000Z",
  "endsAt": "2026-10-05T18:00:00.000Z",
  "graceHours": 24,
  "createdAt": "2026-09-05T18:30:00.000Z",
  "sigs": [{ "alg": "ed25519", "key": "ed25519:c9f1…", "sig": "…" }]
}
```

| Field | Rule |
| --- | --- |
| `offer` | Record id of the `pay2seed.offer`. |
| `seeder` | The seeder key. MUST be a registered `ippay` payee (§5.4). |
| `slot` | 1-based, at most `offer.seeders.max`. One lease per seeder per offer. |
| `priceUsdPerGibMonth` | Copied from the offer at lease time so a later edit never changes what was agreed. |
| `graceHours` | Time from `startsAt` in which the seeder MUST pass its first proof, or the lease is `abandoned` and the slot reopens. Long enough to fetch the swarm. |

A lease is `fetching` until its first proof, `proven` while its most recent
period passed, `lapsed` when a period failed, `abandoned` after
`graceHours` without a first proof, `ended` at `endsAt`, and `voided` with
its offer.

### 3.2 Taking and losing a lease

`POST /leases` with `{ "offer": <id>, "seeder": <key>, "sig" }`, `sig` by
the seeder key over `"openswarm:paid2seed:lease:v1" || offer id`. The hub
answers `201` with the lease, `409` when the offer has no free slot or this
seeder already holds one, or `403` when the seeder's standing (§6.3) is
below the offer's or hub's floor.

A hub SHOULD hand out slots in order of standing and MUST NOT hand out
more than `seeders.max`. A seeder SHOULD NOT take a lease it cannot serve
within `graceHours`; an abandoned lease counts against standing. When an
offer is voided (`pay2seed` §8) every lease on it is `voided`, the hub
pushes `paid2seed.lease.voided`, and a seeder learns of it on its next
poll at the latest.

## 4. Proof of seeding

### 4.1 Storage challenges

Once per period, a verifier named in the offer sends the seeder:

```json
{
  "openswarm": "0.1",
  "type": "paid2seed.challenge",
  "lease": "sha256:5c02…",
  "period": 7,
  "nonce": "1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f",
  "pieces": [17, 2048, 91, 4400],
  "deadline": "2026-09-07T12:10:00.000Z",
  "createdAt": "2026-09-07T12:00:00.000Z",
  "sigs": [{ "alg": "ed25519", "key": "ed25519:c9f1…", "sig": "…" }]
}
```

The seeder answers within `deadline`:

```json
{
  "openswarm": "0.1",
  "type": "paid2seed.proof",
  "challenge": "sha256:9d3a…",
  "answers": ["sha256:…", "sha256:…", "sha256:…", "sha256:…"],
  "createdAt": "2026-09-07T12:00:04.000Z",
  "sigs": [{ "alg": "ed25519", "key": "ed25519:a41e…", "sig": "…" }]
}
```

Each answer is `SHA-256(nonce || piece bytes)` for the piece at that index,
which a verifier holding a copy can check and which cannot be answered
from the piece hash alone. `pieces` MUST be at least four indices chosen
uniformly at random per challenge; `deadline` MUST be at least ten minutes
after `createdAt`, enough to read four pieces from a spinning disk and not
enough to fetch them from the swarm.

### 4.2 Probes

A verifier connects to the seeder as an ordinary peer, over BEP 3 for a
vanilla torrent or the `ipfile` extension for a private swarm, and requests
the challenge's pieces. The seeder's ordinary serving is the proof; the
verifier records `{ "lease", "period", "pieces", "receivedBytes", "peer" }`
signed by its own key, `type` still `paid2seed.proof`. A probe MUST fetch
from the seeder's own announced address; a swarm being alive is not
evidence that this seeder is keeping it alive.

For a `private` swarm whose `pricing.perGib` is non-zero the verifier pays
vouchers for the probe like any leecher, and those are the seeder's in the
usual way. Hubs SHOULD prefer probes for public swarms and challenges for
private swarms they already pin.

### 4.3 Delivery

A hub pushes challenges to a seeder's registered webhook when it has one,
and otherwise leaves them to be polled from `GET /leases/<id>/challenges`.
A seeder without a webhook MUST poll at least every `everyHours / 4`
hours. `deadline` is measured from `createdAt`, not delivery, so a seeder
that polls slowly fails challenges; the cadence is the seeder's to meet.

## 5. Settlement

### 5.1 Accrual

A lease earns, for each period in which its proof passed:

```
earnedUsd = priceUsdPerGibMonth * (sizeBytes / 2^30) * (everyHours / 720)
```

in integer micro-USD, rounding down. A failed or missed period earns
nothing and moves the lease to `lapsed`; two consecutive failures end it
and reopen the slot.

### 5.2 Receipts

```json
{
  "openswarm": "0.1",
  "type": "paid2seed.receipt",
  "lease": "sha256:5c02…",
  "period": 7,
  "proof": "sha256:e77b…",
  "earnedUsd": "0.002604",
  "balanceUsd": "0.018228",
  "createdAt": "2026-09-07T12:00:05.000Z",
  "sigs": [{ "alg": "ed25519", "key": "ed25519:c9f1…", "sig": "…" }]
}
```

### 5.3 Fees and payout

The hub's fee is charged to the requester at purchase, `hubBps` of
`budgetUsd` with `hubBps` no less than the hub record's `minHubBps`; it is
never deducted from a seeder's earnings. Payout is `ippay` §5.6, on the
same schedule and floor as voucher earnings.

### 5.4 Payees

A seeder is an `ippay` payee (`ippay` §6.1). Registering once covers
vouchers, key grants and leases. A seeder key that is not registered
cannot take a lease, because there would be nowhere to pay.

## 6. The seeder's hub

### 6.1 API, seeder side

Paths relative to the `pay2seed.base` in the hub record (`pay2seed`
§6.1). The requester side is `pay2seed` §6.2.

| Method and path | Auth | Purpose |
| --- | --- | --- |
| `GET /offers?visibility&basis&minPrice&maxSize&feed&status` | none | The market: open offers with free slots. |
| `POST /leases` | seeder signed | Take a slot (§3.2). |
| `GET /leases/<id>` | none | The lease, status, periods proven, `earnedUsd`. |
| `GET /seeders/<key>/leases?status` | none | A seeder's leases; what a client resumes after a restart. |
| `GET /leases/<id>/challenges?since` | seeder | Pending challenges for a seeder that cannot receive them pushed. |
| `POST /proofs` | seeder or verifier signed | Answer a challenge or report a probe. Returns the receipt. |
| `GET /seeders/<key>` | none | `{ "standing", "leases", "proven", "failed", "abandoned", "balanceUsd" }`. |
| `POST /webhooks` | signed | Register a CloudEvents endpoint for a seeder key. |

### 6.2 The market listing

`GET /offers` is what a seeder client shows its operator, or chooses from
on its own. Each row carries the offer, the attestation's `basis`,
`description` and `visibility`, the free slot count, and the projected
`earnedUsd` for a full lease. A client MUST show `basis` and `visibility`
wherever it shows an offer, so an operator knows whether they are being
asked to hold ciphertext for a stranger's backup or to seed an openly
licensed dataset in the clear.

### 6.3 Standing

Seeder standing is `proven - 2 * failed - 3 * abandoned` over the trailing
year, floored at zero. Requester standing is `honoured - 3 * voided`, the
same way. Both are public and are one hub's opinion signed by that hub; a
second hub MAY read it and MAY ignore it.

## 7. Seeder client behaviour

A seeder client (torlink's headless daemon is the reference) does the
following, and a conformant one does all of it:

1. Holds a seeder key, registered as an `ippay` payee with a payout
   address, and stores the key as an OpenCreds `key` item.
2. Polls `GET /offers` on the hubs it is configured for, filtered by the
   operator's policy: which `visibility` and `basis` values to accept, the
   minimum `priceUsdPerGibMonth`, the maximum `sizeBytes`, free disk to keep
   in reserve.
3. Takes a lease, fetches the swarm (as a paying peer when `offer.pass` is
   set), adds the offer's `trackers`, and seeds with a per-torrent seed time
   of at least `lease.endsAt`, so its own reaper never drops a swarm it is
   being paid to keep.
4. For a feed offer, follows the feed (`ipdb` §5.4), fetches each new
   segment within one period of its appearance in the head, seeds all of
   them, and re-announces the head as a BEP 44 mutable item at least once
   per period so the catalogue stays findable when the publisher is
   offline.
5. Answers challenges from local pieces within `deadline`, and serves
   probes as ordinary peer traffic.
6. On restart, resumes every lease in
   `GET /seeders/<key>/leases?status=proven,fetching` before taking new ones.
7. Stops seeding and deletes the data when a lease ends or is voided,
   unless the operator has chosen to keep it; for a `private` swarm the
   ciphertext is worthless without a grant, and for a `personal` one it
   MUST be deleted.
8. Shows the operator, for every held lease, the `basis`, `visibility`,
   `earnedUsd` so far, and the next challenge due.

## 8. Relationship to `ipfile.pin`

An `ipfile.pin` job (c0mpute §3.1) is a `pay2seed.offer` with
`visibility: "private"`, `seeders.min = seeders.max = 1`, `days` and
`proof.everyHours` copied, `priceUsdPerGibMonth` derived from
`max_price_usd`, and c0mpute's storage challenge standing in for §4.1. A
c0mpute node that wins such a job holds a lease in this document's sense
and MAY report proofs to the hub to build standing there. A hub MAY
republish a `pay2seed.offer` as an `ipfile.pin` job on the c0mpute auction
when no other seeder takes it, which is how the market reaches the paid
storage network without the requester doing anything.

## 9. Events

CloudEvents as core §8, `source` the hub base:

| `type` | Data | Subscriber |
| --- | --- | --- |
| `pay2seed.attestation.registered`, `.honoured`, `.voided` | attestation id | requester |
| `pay2seed.offer.listed`, `.active`, `.settled`, `.voided` | offer id, status | requester, market followers |
| `paid2seed.lease.granted`, `.proven`, `.lapsed`, `.ended`, `.voided` | lease id, period, `earnedUsd` | seeder, requester |
| `paid2seed.challenge.issued` | the challenge record | seeder |
| `pay2seed.notice.received`, `.resolved` | notice id, outcome | requester |

## 10. Security notes

- **Sybil seeders.** One machine holding several leases on one offer under
  several keys earns several times for one copy. `seeders.max` bounds the
  loss; probes from distinct verifiers to the announced addresses, and a
  hub refusing leases to keys that share a payout address on one offer,
  bound it further. Standing makes it expensive to repeat.
- **Answer relaying.** A seeder that holds nothing could fetch challenged
  pieces from the swarm within `deadline`. Ten minutes is the floor; a hub
  SHOULD set shorter deadlines for small swarms, and probes measure the
  seeder's own serving rather than what it can fetch.
- **Payout addresses are the identity that matters.** A seeder key is
  cheap; the address it pays to is where a hub's Sybil checks bite.

## 11. Implementations

| Piece | Where | Status |
| --- | --- | --- |
| Reference hub, seeder side: leases, challenges, probes, receipts, standing | `profullstack/media-streamer` (bittorrented.com) | planned |
| Seeder client: market polling, leases, per-lease seed time, challenges | `torlink` (`torlnk serve` and `watch`) | planned; per-torrent seed time landed as baairon/torlink#186 |
| Shared seeder client and records | `@profullstack/pay2seed` | planned |
| Seeder and verifier on the storage network | `profullstack/c0mpute` via `ipfile.pin` | mapping in §8 |

## 12. Conformance

A **hub** is conformant on this side when it hands out leases as §3,
issues at least one challenge or probe per period and pays only proven
periods (§4, §5), and publishes seeder standing (§6.3). It MUST also be
conformant to `pay2seed`.

A **seeder client** is conformant when it does all of §7.

## 13. Version history

- 0.1 (2026-09-06): split out of the first pay2seed draft (2026-09-05) as
  the server half; leases, challenges and probes, accrual and receipts,
  the seeder API and client, the `ipfile.pin` mapping.