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

OffsetLengthContent
08The magic GEODE001
824A random base nonce
32to the endThe 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:

OffsetLengthContent
04Length of the metadata, big-endian
48Length of the file, big-endian
12metadata lengthMetadata as UTF-8 JSON: {"name": "...", "type": "..."}
after metadatafile lengthThe file's bytes
after the fileto capacityRandom 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.

BucketBytesChunksLargest file plus metadata
64 KiB65,536165,476
128 KiB131,0722130,996
256 KiB262,1444262,036
512 KiB524,2888524,116
1 MiB1,048,576161,048,276
2 MiB2,097,152322,096,596
4 MiB4,194,304644,193,236
8 MiB8,388,6081288,386,516
16 MiB16,777,21625616,773,076
32 MiB33,554,43251233,546,196
64 MiB67,108,8641,02467,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.