0xDocs 0x.limo

Docs / P2P and the swarm

Tracker and web seed

The tracker, ICE and seed-count endpoints a hosted page talks to, how CORS works for <site>-play origins, and how the origin acts as web seed.

A hosted page talks to two hosts: its own origin (https://<site>-play.0x.limo) and play.0x.limo, where the tracker lives. The 0x runtime handles all of this for you. This page describes what it does, so you can debug it and so your own code doesn't get in the way.

#The tracker

Each version's x1.json names the tracker:

json
{
  "manifest": "swarm/manifest.json",
  "timeoutMs": 20000,
  "tracker": "wss://play.0x.limo/p2p/tracker"
}

The tracker is a WebSocket BitTorrent tracker (the WebTorrent offer/answer protocol). It relays WebRTC offers and answers between players, so two players behind NATs can connect without a separate signalling server. The tracker never carries file data: file data moves only over WebRTC data channels between players, or over HTTPS from the origin.

  • Groups by origin. The tracker puts a page into a swarm group by the browser's Origin header. Every hosted site's origin (https://*-play.0x.limo, where * is one run of letters, digits and dashes) is in the same group. Identical bytes have the same infohash, so a file shared by two versions, or by two sites, is one swarm. A page from an origin in no group is refused.
  • Seeders. 0x runs an always-on seeder for every published version that has a swarm manifest. It picks up a new version within seconds of finalize.

#HTTP endpoints next to the tracker

x1/host.js derives these from the tracker URL (wss://play.0x.limo/p2p/tracker → https://play.0x.limo/p2p/...):

endpointwhat it returnsused for
GET /p2p/health{"ok": true, ...}A 3-second reachability check before the swarm starts.
GET /p2p/ice{"iceServers": [...]}: STUN servers and 0x's TURN relay with short-lived credentialsThe page's RTCPeerConnection configuration.
GET /p2p/seeds?ih=<infohash>,...{"group": "hosted", "seeds": {"<infohash>": n}}How many complete peers each file has, in the page's own group. Asked in batches of 400, every 20 s.

Your site also answers ./p2p/ice (under your version directory, for example /sites/<site>/<n>/p2p/ice) with the same ICE servers, for code that wants them from the page's own origin. The SDK templates use it.

bash
curl -s https://play.0x.limo/p2p/health

#CORS and origins

Hosted pages are on their own origin, https://<site>-play.0x.limo, so their requests to play.0x.limo/p2p/* are cross-origin:

  • play.0x.limo/p2p/* echoes Access-Control-Allow-Origin for origins that match https://[a-z0-9-]+-play.0x.limo, and only those, with Vary: Origin. A preflight (OPTIONS) is answered for GET and POST with content-type.
  • The tracker WebSocket needs no CORS.
  • The platform API, https://api.0x.limo, allows https://*-play.0x.limo too, so @0xlimo/platform works from every hosted game, and from nothing else.

A page opened from another host (your own domain, localhost) is in no group: its swarm start fails, and every file loads from the origin. Use 0x dev locally (it runs a local tracker) and test the swarm on a published version.

#The web seed: your origin

Every file in the manifest is also a normal file on your site. The swarm client uses the origin as a web seed, and the service worker uses it as the fallback:

  • The worker asks the page's swarm for a listed file and waits up to timeoutMs (20 s by default). The swarm only asks peers for files that /p2p/seeds says somebody holds.
  • When no peer has the file, a peer is too slow, or the bytes fail the hash check, the worker fetches the original request from the origin, with Range and all. That is exactly what the browser would have done without the runtime.
  • After an origin fetch of a whole file, the page adopts the bytes and seeds them, so the next player gets the file from this one.

Files under swarm/ (t/<infoHash>.torrent, content/<id>, content/<id>.info) bootstrap a swarm that has no peers yet, and serve as the web seed for 0x's native clients.

#WebRTC, STUN and TURN

Connections between players are WebRTC data channels. /p2p/ice hands out public STUN servers and 0x's TURN relay (UDP and TCP on 3478, and TCP on 443) with credentials that expire after an hour. When the player picked Private in the launcher (?p2p=relay), the page uses only the relay (iceTransportPolicy: "relay"), so peers never learn the player's address.

WebRTC is not governed by your site's Content-Security-Policy, so you don't declare the peers or the TURN relay. The tracker and /p2p/* on play.0x.limo are always in the policy's connect-src (see Content-Security-Policy).

#Limits

The swarm host opens at most 8 connections, uploads at most 2 MiB/s in total and 128 MiB to any one peer, and seeds at most 400 files at a time. These limits keep a game tab from saturating a player's uplink.