Protocol

The manifest

The vault's encrypted file list on Irys, what it holds, how it is found and how each store replaces it.

The manifest is how a vault exists without a server account. It is the list of the vault's files and their keys, sealed under the view key and stored on Irys under the vault's locator. Any device that derives the same keys finds it and opens every file in it.

What it holds

The manifest is UTF-8 JSON:

JSON
{
  "version": 1,
  "files": [
    {
      "id": "<Irys id>",
      "key": "<file key, 43 chars base64url>",
      "receipt": "<receipt, 0x + 64 hex>",
      "bucket": 1048576,
      "term": "permanent",
      "link": "/s/<Irys id>#<file key>",
      "name": "<file name>",
      "type": "<media type>",
      "size": 0,
      "storedAt": "<ISO 8601 time>"
    }
  ]
}
FieldTypeMeaning
version1Format version. Other values are refused.
files[].idstringThe file's Irys id, 43 characters of base64url.
files[].keystringThe file key, 32 bytes as 43 characters of base64url.
files[].receiptstringThe receipt the file was paid under.
files[].bucketnumberThe bucket the ciphertext fills, in bytes.
files[].term'30d' | '1y' | 'permanent'The storage term.
files[].linkstringThe relative share link.
files[].namestringThe file name, file for an unnamed Blob.
files[].typestringThe media type the file was stored with.
files[].sizenumberThe exact plaintext size in bytes.
files[].storedAtstringWhen the store finished, ISO 8601 UTC.

Notes are not in the manifest. They are rebuilt from the encrypted memos beside the pool's commitments, so the balance never depends on the latest manifest. See Notes and the pool.

How it is stored

  • Sealed like any file (Sealing) with the name geode-manifest.json, the type application/vnd.geode.manifest+json and the view key as its key.
  • Paid with its own proof and receipt, always at the permanent term, from the shielded balance.
  • Uploaded with the vault's locator, which the relayer adds as the Irys tag Geode-Locator beside Geode-Receipt.

How each store replaces it

After every file is stored, the client writes the whole list again, the new file included, as a new manifest under the same locator. GET /manifest?locator= returns the id of the latest one. Earlier manifests stay on Irys and are superseded.

store of several files writes the manifest after each file, so the list on Irys is never behind the files already paid for.

How it is found

  1. Derive the locator

    Sign the key message and derive the view key and its locator. See Keys.

  2. Look it up

    GET /manifest?locator=<locator> returns { id, storedAt }, or { id: null, storedAt: null } for a vault that has stored nothing yet.

  3. Open it

    Fetch the ciphertext by id from the Irys gateway and open it with the view key.

Recover on a new device walks through it in the app and in code.