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:
{
"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>"
}
]
}| Field | Type | Meaning |
|---|---|---|
version | 1 | Format version. Other values are refused. |
files[].id | string | The file's Irys id, 43 characters of base64url. |
files[].key | string | The file key, 32 bytes as 43 characters of base64url. |
files[].receipt | string | The receipt the file was paid under. |
files[].bucket | number | The bucket the ciphertext fills, in bytes. |
files[].term | '30d' | '1y' | 'permanent' | The storage term. |
files[].link | string | The relative share link. |
files[].name | string | The file name, file for an unnamed Blob. |
files[].type | string | The media type the file was stored with. |
files[].size | number | The exact plaintext size in bytes. |
files[].storedAt | string | When 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 typeapplication/vnd.geode.manifest+jsonand the view key as its key. - Paid with its own proof and receipt, always at the
permanentterm, from the shielded balance. - Uploaded with the vault's locator, which the relayer adds as the Irys tag
Geode-LocatorbesideGeode-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
Derive the locator
Sign the key message and derive the view key and its locator. See Keys.
Look it up
GET /manifest?locator=<locator>returns{ id, storedAt }, or{ id: null, storedAt: null }for a vault that has stored nothing yet.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.