How the lanes run.

›› Pull lifecycle

1. [1] requestA pull names a manifest hash. The manifest lists every chunk hash of the file, so the client knows what to expect before any byte arrives. The price is quoted up front.
2. [2] piecesThe scheduler cuts the file into pieces and each piece into lanes. Lanes are the stretches of a piece that travel at the same time.
3. [3] assignEach piece is striped across 3 peers drawn among lines that have enough uplink, stake and spare capacity near the requester. Each peer carries one third.
4. [4] sendPeers stream their stretch in 4 MiB chunks. The client hashes every chunk as it lands.
5. [5] verifyA chunk that matches its hash is kept. One that does not is dropped, the stretch resumes on a spare peer from the last good byte, and the sender is marked.
6. [6] settleThe buyer is charged for verified gigabytes only, peers are paid for the chunks that matched, bad senders are slashed and the receipt is written.

›› Verification

Bandwidth is cheaper to verify than computation. Files are content-addressed: the manifest carries the hash of every 4 MiB chunk, so the client does not need a second opinion. It hashes what arrives and keeps it or drops it. A wrong byte cannot be accepted, and nobody pays twice for the same byte.

What a hash cannot show is speed. For that, random spot-checks time a fetch of a file the network already knows. A line that throttles or fakes a share of what it is given fails one with probability that grows with every check, and a failed check cuts its stake and its pay. Payouts follow measured throughput, not the number a line claims.

A share of every payment funds the spot-check pool, so the lines that run the checks are paid for it.

›› Handoff and failures

Home connections change without notice: the owner starts a call, the router restarts, the Wi-Fi drops. Every transfer is addressable by byte offset. When a peer leaves, its stretch resumes on a spare peer with a range request from the last verified byte, and the first peer is paid for the chunks it completed.

A peer that goes silent is simply replaced. It is not slashed for leaving, only for sending bytes that fail their hash or failing a spot-check.

›› Pricing

Bandwidth is billed per verified gigabyte, by class of line. Prices are quoted in dollars and settled in $ROOM. The rate card below is a proposal for launch, not a market price.

Of each payment, 90% goes to the lines that carried the bytes, 5% to the spot-check pool and 5% is burned. For comparison, large cloud providers list outbound internet traffic at roughly 8 to 12 cents per GB for the first terabytes; check their current price lists.

›› Privacy and limits

Headroom serves public, content-addressed files only. It does not proxy browsing, it has no exit nodes, and a line owner's IP address is never used to reach a website. A buyer should assume peers can see which public file they ask for, and a line owner should assume the buyer's address can be seen by the peers they serve. Do not use Headroom for anything secret: encrypt it before publishing.

Owners set the hours, the share of their uplink and a monthly data cap in GB. The network never exceeds them.

›› API

One endpoint takes a pull, one returns its receipt. Example payloads in the demo:

• ubuntu-24.04-desktop-amd64.iso200 Mbps up and over
• llama-3.1-8b-instruct-q4_k_m.gguf200 Mbps up and over
• documentary-1080p.m3u8100 Mbps up and over
• game-update-1.42.pak100 Mbps up and over

curl https://api.headroom.fun/v1/pulls \
  -H "Authorization: Bearer $HEADROOM_KEY" \
  -d '{
    "manifest": "sha256:9f2c...e41a",
    "lanes": 3
  }'

# -> { "id": "iso-1b9x2k", "status": "settled",
#      "receipt": "https://headroom.fun/r/iso-1b9x2k" }

This API is a design. It is not deployed.