Protocol

Keys

What the one wallet signature derives, what each key unlocks, and where each one lives.

A Geode vault has no account and no password. Every key comes from one wallet signature over a fixed message, so the same wallet opens the same vault on any device.

The key message

The wallet signs this message, byte for byte, as UTF-8:

Text
Geode key derivation v1
Sign to unlock your encrypted vault. This does not send a transaction.

It is exported as SIGNING_MESSAGE from @geode/sdk and @geode/contract, and served by GET /config as signingMessage. Signing it sends nothing and costs nothing. Solana signatures (Ed25519) are deterministic, so a wallet signs this message to the same 64 bytes every time, and every key below comes out the same.

Derivation

All derivation uses HKDF with SHA-256 and runs on the holder's device.

KeyDerived asSize
SeedHKDF(ikm = signature, salt = "geode:seed:v1", info = "wallet signature")32 bytes
Spending keyHKDF(ikm = seed, salt = empty, info = "geode:spending:v1") read as a big-endian integer, reduced mod the BN254 scalar fieldOne field element
View keyHKDF(ikm = seed, salt = empty, info = "geode:view:v1")32 bytes
LocatorSHA-256(view key), written as 0x and 64 lowercase hex digits32 bytes
OwnerPoseidon(spending key)One field element

The BN254 scalar field modulus is 21888242871839275222246405745257275088548364400416034343698204186575808495617, exported as FIELD_MODULUS from @geode/contract.

What each key does

Spending key

Owns the holder's notes. Every note's owner field is Poseidon(spending key), and a proof that spends a note must know the spending key behind it. The spending key never leaves the device and never appears in a request. See Notes and the pool.

View key

Decrypts what belongs to the vault:

  • Note memos. Each note created for the holder is published beside its commitment as a memo encrypted with XChaCha20-Poly1305 under the view key. Scanning the tree's memos with the view key finds every note the holder owns.
  • The manifest. The vault's file list is sealed with the view key as its file key. See The manifest.

Locator

The tag value the manifest is stored under on Irys (Geode-Locator). Anyone can read a locator from a tag; only the view key behind it decrypts the manifest it points to, and the locator does not lead back to the wallet. GET /manifest?locator= returns the latest manifest stored under it.

File keys

Each file is sealed under its own random 32-byte key, written as 43 characters of unpadded base64url. File keys are kept in the manifest, so the view key opens every file in the vault. A share link carries one file's key and opens that file alone.

Where keys live

KeyOn the deviceIn the manifestSent anywhere
Signature, seedIn memory for the life of the clientNoNever
Spending keyIn memoryNoNever
View keyIn memoryNoNever
LocatorIn memoryNoTo the relayer, as the manifest's tag and lookup
File keyIn memory while sealing or openingYes, encrypted under the view keyOnly in a share link's fragment, which browsers never send to a server