logicsrc/docs/openswarm/spec.md

The OpenSwarm Core Specification

Version: 0.1 (draft) Status: draft. Nothing below is implemented yet. Wire formats are expected to change before 1.0, and this document says where.

The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT and MAY are to be interpreted as described in RFC 2119.

1. Scope

The core defines what every member protocol shares:

1. Records (§3): the JSON shape, canonicalisation, identifiers and signatures of every object in the family.
2. Keys (§4): publisher identities, derived per-file keys, box keys, and the rules for reuse, rotation and loss.
3. Hashing and chunking (§5): what a content identifier is and why it is a BitTorrent v2 merkle root.
4. Transports (§6): the BitTorrent wire, the extension protocol, browser peers, webseeds, and the optional Moshpit tunnel.
5. Discovery (§7): DHT, trackers, Moshpit names.
6. Events (§8): the CloudEvents envelope and webhook signing.
7. Versioning and conformance (§9, §10).

Member protocols (ipfile, ippay, ipdb, ipaudio, ipvideo, iplive, ipname) add record types and extension messages. They MUST NOT redefine anything in this document.

2. Terminology

Term	Meaning
record	A signed JSON object with an openswarm version and a type.
record id	sha256: plus the hex SHA-256 of the record's canonical bytes without sigs.
publisher	The Ed25519 identity that owns files and feeds.
file key	A per-file Ed25519 pair derived from the publisher key. Its public half is the file's identity.
box key	An X25519 pair used to receive sealed content keys. Every identity has one.
content key	32 random bytes that encrypt one file version's pieces.
swarm	One BitTorrent swarm carrying one ciphertext payload.
piece	A BEP 52 piece: a power-of-two length, at least 16 KiB.
block	16 KiB, the unit of a BitTorrent request and of a v2 merkle leaf.
peer	Any participant in a swarm. A seeder has all pieces, a leecher wants some, a relay forwards live segments.
gateway	An HTTP server that serves ciphertext by range (a BEP 19 webseed) and answers catalogue queries.
hub	The settlement service that sells passes and redeems vouchers. See ippay.
pass	A hub-signed record that lets a peer spend up to a cap on named swarms.
voucher	A payer-signed cumulative IOU for bytes received from one payee.
grant	A record carrying a content key sealed to one recipient's box key.
feed	An ipdb log owned by one key.

3. Records

3.1 Shape

Every object in the family is a record:

{
  "openswarm": "0.1",
  "type": "ipfile.manifest",
  "createdAt": "2026-09-05T18:00:00.000Z",
  "sigs": [
    {
      "alg": "ed25519",
      "key": "ed25519:0d87e09c7fea3ad6ba6c2f3e027ea47f5b245452899910948470906704c5295d",
      "sig": "RGRH7pDpXYcagULqj+8z05pLH99Lc6yLmfdbYgtGeRpjX5l0NcT3QSq9AWBtLw+5+JJiKoZ3s4ty74q/zBSE8w=="
    }
  ]
}

Field	Type	Rule
openswarm	string	Family version the record was written under. "0.1".
type	string	<protocol>.<noun>, lower case. Registered types are listed by each member document.
createdAt	string	RFC 3339, UTC, millisecond precision.
sigs	array	One or more signatures (§3.4). MAY be empty only for record types a member document marks as unsigned.

Every other field is defined by the member document for that type. An implementation reading an unknown field MUST preserve it on round trip.

3.2 Canonical form

The canonical bytes of a record are the RFC 8785 (JSON Canonicalization Scheme) serialisation of the record with the sigs member removed. JCS sorts keys, strips whitespace and fixes number formatting. Amounts and hashes are strings in this family precisely so that JCS never has to touch a float.

3.3 Record id

id = "sha256:" + lowercase_hex(SHA-256(canonical bytes))

The id is never stored inside the record. A reader computes it. Two records with the same canonical bytes are the same record, which is what makes ipdb replication idempotent.

3.4 Signatures

A signature entry is { "alg", "key", "sig" }. The signed message is:

"openswarm:sig:v1:" + type + "\n" + canonical bytes

The prefix is domain separation. A signature over an ipfile.manifest can not be replayed as a signature over an ippay.voucher with the same body.

alg	key prefix	Signature	Status
ed25519	ed25519:	64 bytes, base64	REQUIRED
mldsa65	mldsa65:	3309 bytes, base64	OPTIONAL, for post-quantum ownership

A record MUST carry at least one ed25519 signature by the key the member document names as its signer. It MAY carry an mldsa65 signature by a key the same identity has bound (§4.6). A verifier that does not implement mldsa65 MUST ignore those entries and MUST NOT treat their presence as an error.

Key strings are <alg>:<hex>. Ed25519 and X25519 public keys are 32 bytes, so 64 hex characters. ML-DSA-65 public keys are 1952 bytes.

3.5 Amounts and times

Money is a decimal string with exactly six fractional digits, in USD: "0.002500". Six digits is USDC's precision and is what CoinPay's x402 dialect already carries. Integer arithmetic is specified where rounding matters (ippay §4). Times are RFC 3339 UTC. Byte counts are JSON integers and MUST stay below 2^53.

4. Keys

4.1 Publisher identity

A publisher identity is a 32-byte seed. From it:

publisher signing key  = Ed25519 keypair from seed
publisher box key      = X25519 keypair from HKDF-SHA256(seed, salt = "", info = "openswarm:box:v1")

The identity string is ed25519:<hex of the signing public key>. The box public key is published in the records that need it (§4.4).

ip init creates one seed. It is reused for every file, feed and channel the publisher adds. The seed SHOULD be stored as an OpenCreds key item with keyType: "openswarm-seed"; it is the one thing in this family that cannot be regenerated.

4.2 Per-file keys are derived, and reusable by default

Adding a file mints a key pair for that file. By default the pair is derived, not random:

fileId     = 16 random bytes, recorded in the manifest as hex
fileSeed   = HKDF-SHA256(ikm = publisher seed, salt = fileId, info = "openswarm:file:v1")
file key   = Ed25519 keypair from fileSeed
file box   = X25519 keypair from HKDF-SHA256(fileSeed, salt = "", info = "openswarm:box:v1")

Consequences, all intended:

• Holding the publisher seed and any manifest (which carries fileId) is enough to recover that file's private key. There is no key database to back up beyond the seed.
• Two files never share a key. Compromise of one file seed does not expose another, because HKDF output is one-way from the seed.
• The public half is stable across revisions of the file. A re-encode keeps the same fileId, so it keeps the same identity and the same BEP 46 pointer (§7.2).

ip file add --standalone-key mints a random fileSeed instead. The manifest records "keyDerivation": "standalone" so tooling knows the seed must be backed up on its own. Use it for a file whose ownership will be transferred: handing over a standalone seed transfers exactly one file.

4.3 What each half does

Half	Used for
File public key	The file's identity in every reference ("file": "ed25519:..."), the BEP 44 key under which the latest manifest is announced, the key peers verify manifests against.
File private key	Signs every manifest revision. Signs ipfile.grant records that delegate the content key to a keeper. Signs payout changes: the pricing.payTo a hub pays a publisher's share to is whatever the latest signed manifest says.
File box key	Receives the owner's own sealed copy of the content key (keys.owner in the manifest), so the content key is recoverable from the manifest plus the seed.
Content key	Encrypts the pieces. Random, 32 bytes, per file version. Never signs anything.

The file key is not a wallet. It authorises where money goes; the money goes to an EVM address the manifest names. A seeder's payout address is likewise its own, registered at the hub against the seeder's identity key (ippay §6). Nothing in this family derives a wallet from a signing key.

4.4 Box keys and sealing

Any content key that travels does so inside a sealed box:

sealed = X25519 anonymous sealed box (libsodium crypto_box_seal) to the recipient's box public key

This is the construction the OpenCreds team profile already uses to wrap a vault key to a member, and it is chosen for the same reason: a seeder can hand a key to a peer it has never met, given only that peer's box public key from the hello message. When the link is already an MTP/1 session (§6.5) the box is still applied; the transport protects the link, the box protects the key at rest in a grant record.

4.5 Rotation

Publisher rotation. Mint a new seed. For each file, publish a manifest revision signed by the old file key (derived from the old seed) that names the new publisher, and that carries a new fileId and a new file key derived from the new seed in successor. Readers that already hold the old file key follow successor once and re-pin. The old seed is kept only to derive old file keys during the transition.

File rotation. Same mechanism for one file: a final revision under the old file key with successor set. A reader MUST NOT follow a successor chain more than 8 deep, and MUST refuse a successor whose own latest manifest does not name the predecessor in predecessor. Both links are required so a compromised old key cannot redirect a file to an attacker's swarm; the attacker would also need to sign as the new key.

Content key rotation. Re-encrypt under a fresh content key and publish a new revision with a new cipherRoot and new swarm. Old grants stop working for the new swarm. Rotation is the only way to revoke a key that has been delivered; a delivered key is held by the peer, and the spec does not pretend otherwise.

4.6 Post-quantum binding

An identity MAY bind an ML-DSA-65 key by publishing an openswarm.binding record signed by both keys:

{
  "openswarm": "0.1",
  "type": "openswarm.binding",
  "subject": "ed25519:5d292428e8a68946e5225136c8b10e8f33ab78a45e1663d0730996dd2b63d59e",
  "pq": "mldsa65:0f3a51c0a3e6d1e2f4c99b3d3b6a2c5a9f1e8d7c6b5a4f3e2d1c0b9a8f7e6d5c",
  "createdAt": "2026-09-05T18:00:00.000Z",
  "sigs": [
    {
      "alg": "ed25519",
      "key": "ed25519:5d292428e8a68946e5225136c8b10e8f33ab78a45e1663d0730996dd2b63d59e",
      "sig": "RGRH7pDpXYcagULqj+8z05pLH99Lc6yLmfdbYgtGeRpjX5l0NcT3QSq9AWBtLw+5+JJiKoZ3s4ty74q/zBSE8w=="
    }
  ]
}

(pq is truncated above for readability; a real value is 1952 bytes of hex, and the record carries a second entry with "alg": "mldsa65" whose 3309-byte signature is omitted here for the same reason.) This matches the Moshpit registry's mtp pin kind, which is an ML-DSA-65 identity. A verifier that trusts the binding accepts an mldsa65 signature from pq as a signature by subject.

4.7 Loss

If the publisher seed is lost and no standalone seeds exist:

• Every file's ciphertext stays servable. Seeders hold pieces, not keys.
• Every grant already delivered keeps working.
• No manifest can be revised: prices, payout address, trackers and successor are frozen at the last signed revision.
• Payouts continue to the frozen pricing.payTo.
• No new keeper can be delegated. Existing keepers keep granting.

That is the failure mode, stated so that it can be planned for. Store the seed in a vault.

5. Hashing and chunking

5.1 The content identifier

The identifier of a file's bytes is its BEP 52 pieces root: the SHA-256 merkle root over 16 KiB leaves, padded per BEP 52. It is written sha256:<64 hex>.

This is chosen over a flat SHA-256 or an IPFS CID because a swarm peer can verify a single 16 KiB block against it with a merkle proof, which is what lets a leecher sign a voucher the moment a block arrives. A flat hash would make every payment wait for the whole file. A CID would be a second tree that no BitTorrent client checks.

An ipfile manifest carries two roots: plainRoot over the plaintext and cipherRoot over the ciphertext. The swarm verifies against cipherRoot through the torrent's own hashes; the client verifies its decrypted output against plainRoot.

c0mpute's chunk store addresses objects by blake3 (c0mpute://blake3:<hex>). That stays internal to the node. A c0mpute storage node maps piece index to blake3 chunk however it likes; what it puts on the wire is verified by SHA-256.

5.2 Piece length

A piece length MUST be a power of two and at least 16 KiB (BEP 52). Members recommend defaults: ipfile 1 MiB for files over 64 MiB and 256 KiB below; ipaudio 256 KiB; ipvideo 1 MiB; iplive one segment per piece.

5.3 Hybrid torrents

A swarm's info dictionary MUST be a hybrid v1/v2 torrent per BEP 52: it carries both pieces (SHA-1, v1) and file tree with piece layers (SHA-256, v2). Two infohashes result:

• infohashV1: SHA-1 of the info dictionary, 20 bytes. This is what WebTorrent in a browser uses, and what today's trackers and the bitmagnet crawl behind bittorrented.com/dht record.
• infohashV2: SHA-256 of the info dictionary, truncated to 20 bytes for DHT and tracker use, full 32 bytes in records.

The info dictionary MUST NOT contain plaintext file names. name is the ciphertext root in hex. A crawler that fetches metadata over BEP 9 learns a size and a hash.

6. Transports

6.1 The wire

Peer connections are BitTorrent (BEP 3) over TCP, uTP, or WebRTC data channels (the WebTorrent dialect). Every standard message keeps its meaning. OpenSwarm never changes choke, unchoke, have, request, piece or the bitfield. That is what makes a vanilla client a valid, if unpaid, participant.

6.2 Extension messages

All family messages ride on the extension protocol (BEP 10). The extension handshake advertises:

{ "m": { "ipfile": 20, "ipdb": 21, "iplive": 22, "ut_metadata": 3, "ut_pex": 1 },
  "v": "ip/0.1",
  "openswarm": "0.1" }

The numbers are local ids chosen by the sender, as BEP 10 requires. The names are fixed: ipfile, ipdb, iplive. Message payloads are bencoded dictionaries with a string key t naming the message. Records embedded in a message are carried as their UTF-8 JSON bytes under key r, so the bencode layer never has to understand JSON.

A peer that did not advertise a name MUST NOT be sent that extension's messages. A peer receiving a message for an extension it advertised but a t it does not know MUST ignore it.

6.3 Browser peers

WebTorrent supports BEP 10 extensions via wire.use(), and the four wss trackers bittorrented.com's player already announces to (wss://tracker.webtorrent.dev, wss://tracker.openwebtorrent.com are the two that handshake today) find WebRTC peers. A browser peer signs vouchers with WebCrypto Ed25519 and seals with X25519 from the same API. Nothing in this family requires a native binary in a browser.

A browser can only reach WebRTC peers. A swarm that wants browser reach MUST have at least one hybrid peer (a native seeder that also announces to a wss tracker), which is what media-streamer's StreamingService already is.

6.4 Webseeds and gateways

A gateway is a BEP 19 webseed: it serves ciphertext by HTTP range under the URL the manifest lists. A gateway MAY require a pass (Authorization: Bearer with the pass's token) and MAY require vouchers in a request header (ippay §7). A gateway that requires neither is a free webseed and is how a publisher pays for its own distribution instead of charging for it.

6.5 Moshpit tunnel

Between two native peers that both hold Moshpit identities, the BitTorrent connection MAY be tunnelled through an MTP/1 session (@profullstack/moshpit-transport: X25519 + ML-KEM-768 key agreement, ML-DSA-65 server identity, ChaCha20-Poly1305 records, TCP). The hello message carries the peer's MTP pin (base64(SHA-256(SPKI))) so a peer can reconnect over the tunnel after meeting on the plain wire. MTP/1 has no client authentication; ownership on the tunnel is still proved by hello signatures (ipfile §5.1), not by the transport.

MTP/1 is TCP only and 64 KiB per record. It is not available to browsers and it does not replace the swarm wire. It is the confidentiality option for node-to-node links, and it is the transport the hub API SHOULD be reachable over in addition to HTTPS.

7. Discovery

7.1 Peers

A swarm is found the way any torrent is: DHT get_peers on infohashV1 and on the truncated infohashV2 (BEP 5), tracker announces (BEP 15, HTTP, and wss for browsers), PEX (BEP 11), LSD. A manifest lists the trackers it wants. A manifest MAY set swarm.private to true (BEP 27), which disables DHT and PEX and leaves only trackers and webseeds; that is the choice for a swarm whose existence should not be public.

7.2 Latest manifest by file key

The latest manifest for a file is announced as a BEP 44 mutable item:

k    = file public key (32 bytes)
salt = "ipfile"
seq  = manifest rev
v    = bencoded { "ih": <infohashV1, 20 bytes>, "ih2": <infohashV2, 32 bytes>, "m": <manifest record id, 32 bytes> }

v is 100 bytes, well inside the 1000 byte BEP 44 limit. The item is signed by the file key, which is why the file key is Ed25519 and why it is the file's identity. This is BEP 46 with an extra pointer: the magnet form is magnet:?xs=urn:btpk:<file key hex>&s=ipfile.

The manifest itself is fetched from any peer in the swarm over the ipfile manifest message, from a gateway at /swarm/<infohashV2>/manifest, or from an ipdb replica.

7.3 Feeds and names

An ipdb feed head is a BEP 44 mutable item under the feed key with salt ipdb:<feed name>. A Moshpit name resolves to a publisher key and a gateway through ipname. A client that starts from a name, a feed, a file key or an infohash reaches the same manifest.

8. Events

8.1 Envelope

Every event is a CloudEvents 1.0 envelope, as @profullstack/autoblog already emits:

{
  "specversion": "1.0",
  "id": "7f2b5a7e-2b0e-4c8f-9a4d-3d6c0b9c1e10",
  "type": "com.logicsrc.openswarm.ipfile.voucher.redeemed.v1",
  "source": "https://coinpayportal.com/api/openswarm",
  "subject": "sha256:41d10f45e705e0526c9eeedf62b32dda3daaf552dd9b6a7b09e01776b05813bb",
  "time": "2026-09-05T18:02:11.000Z",
  "datacontenttype": "application/json",
  "data": {
    "record": { "openswarm": "0.1", "type": "ippay.voucher" }
  }
}

type is com.logicsrc.openswarm.<protocol>.<noun>.<verb>.v1. subject is the record id the event is about. data.record is the full record where the event carries one. Each member document registers its types.

8.2 Delivery

Webhooks are Standard Webhooks as autoblog signs them: POST with content-type: application/cloudevents+json, headers webhook-id (the event id), webhook-timestamp (unix seconds) and webhook-signature (v1,<base64 HMAC-SHA256> over <id>.<timestamp>.<body>), a five minute tolerance window, retries at 0, 10 and 60 seconds on network error, 5xx, 408 and 429. Receivers verify with a constant-time compare.

9. Versioning

• openswarm on a record is the family version. A 0.x reader MUST accept any 0.x record and MUST preserve unknown fields.
• Each member document has its own version history. Adding a record type, a message t or a field is additive and does not bump the family version.
• Wire changes that break an existing message get a new t name. A message name is never redefined, for the same reason an OpenCreds label is never edited: peers that shipped it are still running.
• Extension names in the BEP 10 handshake (ipfile, ipdb, iplive) are permanent. A breaking revision would ship as ipfile2.

10. Conformance

A conforming implementation of the core:

1. Reads and writes records per §3, computes ids and verifies ed25519 signatures with the domain prefix.
2. Derives file keys and box keys per §4 from a seed, and produces a manifest that a second implementation given the same seed and fileId can sign identically.
3. Computes BEP 52 pieces roots and builds hybrid torrents per §5.
4. Speaks BEP 10 and ignores unknown t values per §6.2.
5. Publishes and reads the BEP 44 pointer per §7.2.
6. Emits events per §8 where it emits events at all.

Member conformance is defined per document; the checklist is collected in conformance.md.

11. Registered record types

Type	Signer	Document
openswarm.binding	subject and pq	this document §4.6
ipfile.manifest	file key (and publisher key)	ipfile
ipfile.grant	grantor	ipfile
ippay.hub	hub key	ippay
ippay.pass	hub key	ippay
ippay.voucher	payer key	ippay
ippay.receipt	hub key	ippay
ipdb.entry	feed key	ipdb
ipdb.head	feed key	ipdb
ipdb.tombstone	feed key	ipdb
ipaudio.release, ipaudio.track	publisher key	ipaudio
ipvideo.title	publisher key	ipvideo
iplive.channel, iplive.head	channel key	iplive
ipname.pin	publisher key	ipname

12. Version history

Version	Date	Change
0.1	2026-09-05	Initial draft. Records, derived file keys, BEP 52 identifiers, BEP 10 extensions, BEP 44 pointers, CloudEvents.