Protocol
Sealing
The exact sealed format of a Geode file, how it is chunked and encrypted, and which bucket it lands in.
Sealing happens on the holder's device before anything is priced or sent. The output is a byte string of exactly one bucket's length that only the file key opens. Irys stores those bytes and nothing else.
The sealed format
| Offset | Length | Content |
|---|---|---|
| 0 | 8 | The magic GEODE001 |
| 8 | 24 | A random base nonce |
| 32 | to the end | The encrypted chunks |
The first 32 bytes are the header. The rest of the bucket is the encrypted payload, cut into chunks of 65,536 plaintext bytes, each followed by its 16-byte Poly1305 tag. The last chunk is shorter, sized so the whole output fills the bucket exactly.
The payload
Before encryption, the payload holds:
| Offset | Length | Content |
|---|---|---|
| 0 | 4 | Length of the metadata, big-endian |
| 4 | 8 | Length of the file, big-endian |
| 12 | metadata length | Metadata as UTF-8 JSON: {"name": "...", "type": "..."} |
| after metadata | file length | The file's bytes |
| after the file | to capacity | Random fill |
The name, the media type and the exact size are inside the ciphertext. The fill is random, so two sealings of the same file never produce the same bytes.
Encryption
- Cipher: XChaCha20-Poly1305 with a 32-byte key and a 24-byte nonce.
- Key: a fresh random 32-byte file key per file. The manifest is sealed the same way with the view key as its key.
- Nonce per chunk: the header's base nonce with its last 8 bytes replaced by the chunk index, big-endian.
- Associated data per chunk: the 32-byte header, then the bucket length as 8 bytes big-endian, then the chunk index as 4 bytes big-endian. A chunk moved, a header changed or a ciphertext cut to another length fails to open.
Opening checks the magic and that the length is a bucket, decrypts every chunk, and reads the metadata (at most 16,384 bytes) and the file back. Any failure, from a wrong key to a changed byte, raises WRONG_KEY.
The ciphertext root
The ciphertext root is SHA-256 of the whole sealed byte string, written as 0x and 64 hex digits. It names this exact ciphertext in the receipt, and the relayer refuses an upload whose bytes hash to anything else.
Buckets
The sealed output is padded to the smallest power-of-two bucket from 64 KiB to 64 MiB that holds it. The chain and Irys see the bucket, never the size.
The largest file each bucket holds is its capacity, less 12 bytes of lengths, less the length of the metadata JSON.
| Bucket | Bytes | Chunks | Largest file plus metadata |
|---|---|---|---|
| 64 KiB | 65,536 | 1 | 65,476 |
| 128 KiB | 131,072 | 2 | 130,996 |
| 256 KiB | 262,144 | 4 | 262,036 |
| 512 KiB | 524,288 | 8 | 524,116 |
| 1 MiB | 1,048,576 | 16 | 1,048,276 |
| 2 MiB | 2,097,152 | 32 | 2,096,596 |
| 4 MiB | 4,194,304 | 64 | 4,193,236 |
| 8 MiB | 8,388,608 | 128 | 8,386,516 |
| 16 MiB | 16,777,216 | 256 | 16,773,076 |
| 32 MiB | 33,554,432 | 512 | 33,546,196 |
| 64 MiB | 67,108,864 | 1,024 | 67,092,436 |
A file of exactly 64 KiB lands in the 128 KiB bucket, since its header, tag and metadata come on top. The bucket list is exported as BUCKETS from @geode/contract and served by GET /config as buckets.