logicsrc/docs/openswarm/paid2stream.md

paid2stream: The Server Protocol for Paid Live Streams

Status: 0.1 draft. Member of the OpenSwarm family. Depends on the core, iplive, ippay and paid2seed. Its client half is pay2stream.

1. Scope

paid2stream is the side that gets paid to carry a live stream. It is spoken by relays and gateways: peers on the iplive wire that take a lease from a hub, stay online for a window, fan out segments, and, for a gateway, turn the swarm into standard HLS for any player. It defines:

• Leases on a pay2stream.offer: one relay, one window, one price per relay-hour.
• Proof of relaying. Presence proofs by a verifier that connects as a peer and pulls segments, and a served-bytes ratio so a relay that is online and idle is not paid the floor for nothing.
• Settlement. Relay-hour accrual, a gateway bonus, receipts, payout through the ippay payee a relay already has for vouchers.
• The gateway role: the record, the HLS presentation in clear and sealed modes, the M3U and EPG, gateway-bound vouchers, and what a gateway must do when a channel is voided.
• Regions and standing.

Consent, offers, tickets and the viewer are pay2stream. A hub implements both; a relay or gateway implements only this document.

Non-goals

Deciding what a channel is. A relay sees a channel key, a basis, a visibility and a price, and decides whether to carry it.

2. Terminology

• Relay, viewer, channel, head, segment, part, epoch, origin. As iplive §2.
• Gateway. A relay that also speaks HTTP: presents the channel as HLS and M3U, holds a grant, and signs vouchers on behalf of the HLS viewers bound to it.
• Relay-hour. One relay, connected and serving, for one hour.
• Period. offer.proof.everyMinutes long.

3. Leases

A paid2stream.lease is a paid2seed.lease with priceUsdPerRelayHour in place of the GiB-month price, graceMinutes (default 5) in place of graceHours, a window copied from the offer, and a gateway boolean set when the relay commits to §5.

POST /relays with { "offer", "relay", "regions", "gateway": bool, "sig" }, sig by the relay key over "openswarm:paid2stream:lease:v1" || offer id. 201 with the lease; 409 when no slot is free or the relay already holds one for this window; 403 below the standing floor. A relay MUST be online and announced in the channel's peer set within the grace window, and holds at most one lease per channel window. When an offer is voided every lease on it is voided and the hub pushes paid2stream.lease.voided.

4. Proof and settlement

4.1 Presence

A leased relay is proven for a period when a verifier finds it, at its announced address, serving the channel: the verifier connects as an iplive peer, receives a head no older than two segments, requests one segment at each rendition in capacity.renditions, and receives them within one segment duration each. The verifier signs a paid2stream.proof with { "lease", "period", "head", "segments", "latencyMs" }. A relay that is connected but answers deny rate to a verifier fails the period.

For a gateway, the verifier also fetches the media playlist and one segment over HTTP (§5.3) and records hls: true.

4.2 Served bytes

Vouchers a relay redeems for this channel during the window are the second measure. A hub MAY require, per offer, a minimum ratio of served bytes to pulled bytes for a period to count, so a relay that is present and idle while others carry the viewers is not paid the floor for nothing. The default ratio is 1.0 after the first two periods.

4.3 Accrual and receipts

earnedUsd = priceUsdPerRelayHour * (everyMinutes / 60) * (1 + gatewayBonusBps / 10000 if gateway)

per proven period, integer micro-USD, rounded down, credited to the relay's ippay payee balance with a paid2stream.receipt shaped as paid2seed.receipt. Two consecutive failed periods end the lease and reopen the slot. Vouchers are separate and additive; the hub's fee is the broadcaster's at purchase, never the relay's.

4.4 Regions and standing

A relay declares regions in its lease request, self-reported and verified only in the sense that a verifier records the latency it saw. Standing is paid2seed §6.3 with periods in place of days; a hub shows a relay's median verified latency per region beside it.

5. Gateways and HLS

A gateway is what makes this usable by a person with a television. Any relay MAY be one; a c0mpute node with c0mpute:role:gateway is expected to be one; the reference hub runs one.

5.1 Record

{
  "openswarm": "0.1",
  "type": "paid2stream.gateway",
  "gateway": "ed25519:a41e…",
  "base": "https://gw-eu1.example.net/openswarm",
  "regions": ["eu"],
  "modes": ["clear", "sealed"],
  "lowLatency": true,
  "hubs": ["https://bittorrented.com/api/openswarm"],
  "createdAt": "2026-09-10T09:00:00.000Z",
  "sigs": [{ "alg": "ed25519", "key": "ed25519:a41e…", "sig": "…" }]
}

Registered with POST /gateways; listed in GET /gateways and, per channel, in the gateways array of GET /streams/<id>. An origin MAY name preferred gateways in its channel record's relays block.

5.2 Presenting a pass

A gateway MUST accept the ticket three ways: ?pass=<base64url pass> on the URL, as a cookie, and as Authorization: Bearer. It verifies the pass against the hub key and its scope (ippay §3.1), checks expiresAt, and MUST rate-limit failed presentations by source address. A pass bought against another gateway is valid here if the hub lists this gateway for the channel; the pass is the hub's record.

5.3 HLS presentation

For a channel it relays, a gateway serves:

Path	Body
hls/<channel>/master.m3u8	One EXT-X-STREAM-INF per rendition in the channel record, CODECS and BANDWIDTH from it, EXT-X-INDEPENDENT-SEGMENTS.
hls/<channel>/<rendition>.m3u8	A media playlist rebuilt from the latest signed head: EXT-X-MAP for the init segment, one EXTINF per segment in the DVR window, EXT-X-DISCONTINUITY at a key epoch boundary in sealed mode, EXT-X-PROGRAM-DATE-TIME from the head's timestamp. With lowLatency, EXT-X-PART entries from iplive parts and EXT-X-SERVER-CONTROL with CAN-BLOCK-RELOAD=YES.
hls/<channel>/<rendition>/<seq>.m4s	The segment.
hls/<channel>/init/<rendition>.mp4	The init segment.
hls/<channel>/key/<epoch>	sealed mode only: the 16-byte HLS key, to a pass holder.

clear mode. The gateway decrypts each iplive segment with the grant it holds and serves plaintext over TLS. Every IPTV player understands it, and it is exactly as private as the TLS session and the pass. A gateway MUST NOT serve clear for a channel whose record has keys.modes without gateway in it; that is how an origin refuses to be decrypted by anyone but viewers.

sealed mode. The gateway re-encrypts each segment under a per-epoch AES-128-CBC key and writes EXT-X-KEY:METHOD=AES-128,URI="key/<epoch>", so the playlist is standard HLS with standard encryption and the key endpoint is where the pass is checked. Segments may then be cached by any HTTP cache in the path. The re-encryption is the gateway's cost; the origin's content key never leaves the iplive layer.

Both modes are one segment behind the peer edge; lowLatency narrows that to one part.

5.4 The M3U and the EPG

GET <base>/channels.m3u?pass=<pass> returns #EXTM3U with one #EXTINF per channel the pass is in scope for, carrying tvg-id, tvg-name, tvg-logo and group-title from the channel record's title, logo and group fields (added to iplive.channel as OPTIONAL by this document), each pointing at that channel's master.m3u8 with the pass attached. GET <base>/epg.xml?pass= returns XMLTV built from the pay2stream.listing entries of those channels. This pair is what every IPTV app asks for on setup, and it is how a gateway looks, to a television, like the provider it replaces.

5.5 Gateway-bound vouchers

A gateway signs vouchers to its upstream for what it pulls, as any relay does, and signs vouchers to itself on behalf of each bound viewer for what it serves them, bounded by that viewer's ticket capUsd. It MUST NOT sign a voucher for bytes it did not serve; the hub compares signed bytes against the segment count in the window, and the gateway's standing is what it loses.

5.6 Stopping

On pay2stream.channel.voided a gateway MUST stop serving the channel within one segment duration, answer its playlists with 410, and drop the channel from channels.m3u. A gateway that keeps serving a voided channel is delisted and its standing zeroed.

6. Hub API, relay and gateway side

Relative to pay2stream.base. The client side is pay2stream §7.

Method and path	Auth	Purpose
GET /streams?open&region	none	Offers with free relay slots, and what each pays per hour.
POST /relays	relay signed	Take a lease (§3).
GET /relays/<key>	none	Standing, leases, median latency per region.
GET /relays/<key>/leases?status	none	What a relay resumes after a restart.
POST /proofs	verifier signed	Report a presence proof; returns the receipt.
POST /gateways	gateway signed	Register or update a gateway record.
GET /passes/<id>	none	Verify a presented ticket against the hub's record (ippay §5.2).
POST /vouchers	none	Redeem, as ippay §5.3; gateway-bound vouchers carry boundBy.
POST /webhooks	signed	Register a CloudEvents endpoint for a relay or gateway key.

7. Relay and gateway client behaviour

1. Holds a relay key, registered as an ippay payee, stored as an OpenCreds key item.
2. Polls GET /streams?open on its hubs, filtered by the operator's policy: which basis values to carry, minimum price per hour, regions, upload to keep in reserve.
3. Takes a lease, connects to the channel's peers using the offer's pass, accepts up to capacity.downstreamPerRelay downstream peers, and stays for the window.
4. As a gateway: holds a grant, serves §5.3 in at least clear mode, §5.4, and the three pass presentations of §5.2.
5. Answers verifiers as ordinary peer traffic, and over HTTP for the gateway probe.
6. On restart, resumes leases from GET /relays/<key>/leases?status=proven.
7. Stops on a void (§5.6). Shows the operator, per lease, the basis, earned so far, viewers served, and the next period due.

8. Events

type	Data	Subscriber
pay2stream.offer.listed, .active, .settled, .voided	offer id	broadcaster, market followers
paid2stream.lease.granted, .proven, .lapsed, .ended, .voided	lease id, period, earnedUsd	relay, broadcaster
pay2stream.channel.live, .ended, .voided	channel key, gateways	relays, gateways, viewers with tickets
pay2stream.listing.published	listing id	market followers

9. Security notes

• Presence without service. The served-bytes ratio (§4.2) is what stops a relay from collecting the floor while doing nothing.
• Gateway over-signing. Bounded per viewer by capUsd, and in aggregate by the hub's segment-count check and the gateway's standing.
• Clear mode is clear. A gateway is trusted with plaintext by the origin's choice of keys.modes; an origin that does not want that offers sealed only, or no gateways at all.
• Relay regions are self-declared. Only the verified latency beside them is evidence.

10. Implementations

Piece	Where	Status
Reference hub, server side, and the hub's own gateway	profullstack/media-streamer (bittorrented.com), Live TV	planned; the IPTV resale rail (/api/public/iptv/<slug>/stream) already seals HLS manifests per session, the central version of §5.3
Gateway on the storage network	profullstack/c0mpute c0mpute:role:gateway, DIP 0019 playlist rebuild	mapping; DIP 0019 already rebuilds playlists from swarmed segments
Relay client	torlink with the iplive extension	planned
Shared relay and gateway code	@profullstack/pay2seed (one package for the four protocols)	planned

11. Conformance

A hub on this side: leases as §3, at least one presence proof per period and pays only proven periods (§4), lists gateways per channel, pushes channel.voided to relays and gateways.

A relay: iplive §12 as a relay, plus §7. A gateway: a relay, plus §5.2, §5.3 in at least clear mode, §5.4, §5.5 and §5.6.

12. Version history

• 0.1 (2026-09-06): first draft, as the server half; leases per relay-hour with a gateway bonus, presence proofs and the served-bytes ratio, gateways with clear and sealed HLS, the M3U and EPG pair, gateway-bound vouchers, stopping on a void.