0xDocs 0x.limo

Docs / JavaScript SDK

@x1/meshtorrent

The 0x swarm toolkit (WebTorrent based) with the asset manifest builder, browser client, tile cache, tracker and seeder that hosted sites and the 0x CLI use.

meshtorrent is how 0x moves static files between players. It uses WebTorrent over WebRTC in browsers, deterministic torrents (the same bytes always give the same infohash), SHA-256 content ids, and the origin as a last-resort web seed. Hosted sites and 0x dev use it through @0xlimo/swarm-sw, so most games never import it directly. Use it directly to:

  • build or check a site's swarm manifest yourself (asset-manifest.mjs);
  • fetch listed files from the swarm in your own loader (the browser client);
  • keep a persistent, verified cache of fetched files (openTileCache).

Registry version: 0.2.0 (Node.js 20+). It depends on webtorrent, bittorrent-tracker, create-torrent, parse-torrent, node-datachannel and webrtc-polyfill.

bash
npm install @x1/meshtorrent --@x1:registry=https://0x.limo/npm/

Deep imports only

The package's package.json has no main, exports or bin field. Import modules by path (@x1/meshtorrent/dist/src/asset-manifest.js), and run the tools with node node_modules/@x1/meshtorrent/bin/<tool>.mjs. The browser bundle is @x1/meshtorrent/dist-browser/meshtorrent.mjs (ES module) or …/meshtorrent.js (an IIFE that sets window.MeshTorrent).

#Build and verify a swarm manifest

bash
# what 0x publish does: the files your policy lists -> <site>/swarm/
node node_modules/@x1/meshtorrent/bin/asset-manifest.mjs --root dist --policy swarm-assets.json --verify

# check a published copy without writing anything
node node_modules/@x1/meshtorrent/bin/asset-manifest.mjs --root dist --verify-only

The output goes under <root>/swarm/:

PathWhat
manifest.json{version: 1, entries: {"/<site path>": {tileId, infoHash, size}}}, canonical JSON
t/<infoHash>.torrentmetadata bootstrap, so a swarm with no peers can start from the web seed
content/<id>, content/<id>.infothe content-addressed store that native 0x clients use as a web seed

Files are rewritten only when their bytes change. Torrents and copies of files that left the policy are removed. Without a policy nothing is taken (0x publish supplies its default; see what goes into the swarm).

js
import { parsePolicy, writeAssetManifest, verifyAssetManifest } from "@x1/meshtorrent/dist/src/asset-manifest.js";

const policy = parsePolicy(JSON.stringify({ include: ["assets/**"], minBytes: 16384 }));
const r = await writeAssetManifest("dist", policy);   // {files, bytes, skippedSmall, skippedLarge, ...}
const v = await verifyAssetManifest("dist");          // {entries, ok, mismatched, missing, bad}

#Guarantees

  • Integrity: everything fetched is hashed. sha256(bytes) must equal the entry's tileId, or the bytes are discarded and never seeded. Cache reads are re-hashed too.
  • Peers first: the web seed joins late (webseedDelayMs). A file that nobody seeds, per the tracker's /seeds, goes straight to a plain fetch.
  • Circuit breaker: after 3 swarm failures in a row, the client uses HTTP for 60 s (breakerFailures, breakerCooldownMs).
  • Fallback: without RTCPeerConnection, the client is origin-only.

The full option and type list is in the reference.