0xDocs 0x.limo

Docs / REST API

Transfers

The content tracker (announce and peers), web seeds, gated-content keys, content blocks and the opt-in transfer reports that feed the swarm statistics.

Game files move between players. These routes are the API side of that: a tracker that tells clients who has a file, web seeds that serve a file over HTTP when no peer has it, and reports of how many bytes came from where. The launcher, sg-steamclient and the @0xlimo/swarm-sw site runtime call them for you. You only need them for your own client.

Files are named by content ID (cid): the lowercase hex SHA-256 of the file, or of its ciphertext when the file is gated (encrypted).

#Tracker

RouteDoes
POST /v1/content/{cid}/announcethe caller has (some of) this file; counts for 90 s
POST /v1/content/announce {ids}the same for up to 1000 content IDs at once
GET /v1/content/{cid}/peersup to 40 SteamIDs that announced the file in the last 90 s, shuffled

The same operations run over the push stream, which is cheaper for a client that is connected anyway:

json
{"op": "announce", "id": "<cid>"}
{"op": "announce", "ids": ["<cid>", "..."]}
{"op": "peers", "id": "<cid>", "req": 7}

A peers request is answered with {"type": "peers", "id": "<cid>", "req": 7, "peers": ["7656...", "..."]}. Content that an operator blocked answers 451 content blocked over REST, and blocked: true with no peers over the stream.

GET /v1/content/blocks lists blocked content IDs and their WebTorrent infohashes. Clients enforce the list on paths that don't go through a tracker of ours.

#Web seeds and keys

RouteDoes
GET /v1/content/{cid}/seed{data, info} URLs (CDN or pre-signed bucket URLs) that support HTTP range requests
GET /v1/content/{cid}/keythe AES-256 key of a gated file, for owners of its app only (403 otherwise)

#Hosted sites in the browser

Hosted sites use WebTorrent in the browser instead of the REST tracker:

  • the WebSocket tracker wss://play.0x.limo/p2p/tracker (the tracker in GET /v1/hosting/config);
  • ./p2p/ice under the site version's own URL, which hands out STUN and TURN servers;
  • the site's own origin as the fallback when no peer has a piece.

#Transfer reports

Clients report, opt-in, how many bytes of each file came from peers, from the origin and from the WebTorrent swarm. These reports feed 0x's swarm statistics and the public network map at https://p2p.0x.limo. They are never used for billing or enforcement.

RouteAuthBody
POST /v1/content/transferstoken{session, seq, app, items: [{id, peer, origin, webtorrent, up, bad_pieces}]} (at most 500 items)
POST /v1/content/transfers/siteanonymousthe same with site in place of app
POST /v1/content/reporttoken{session, app, counters: {peer, origin, webtorrent, duplicate, bad_pieces, wt_up}} (cumulative per session)
POST /v1/net/livetokenlive gauges: up/down rate, seeding, DHT state
  • seq rises by one per report of a session. A report whose seq isn't above the last one is acknowledged and ignored, so retries are safe.
  • A hosted page opened directly (no one signed in) posts to /x1/xfer on its own origin, which the front forwards to /v1/content/transfers/site. These reports are limited per address to one every 10 s (burst 6). Nothing is sent when the player turned sharing off.
  • Reports from a node with telemetry off answer 403 telemetry disabled.

See the generated content reference.