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:
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.
| Key | Derived as | Size |
|---|---|---|
| Seed | HKDF(ikm = signature, salt = "geode:seed:v1", info = "wallet signature") | 32 bytes |
| Spending key | HKDF(ikm = seed, salt = empty, info = "geode:spending:v1") read as a big-endian integer, reduced mod the BN254 scalar field | One field element |
| View key | HKDF(ikm = seed, salt = empty, info = "geode:view:v1") | 32 bytes |
| Locator | SHA-256(view key), written as 0x and 64 lowercase hex digits | 32 bytes |
| Owner | Poseidon(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
| Key | On the device | In the manifest | Sent anywhere |
|---|---|---|---|
| Signature, seed | In memory for the life of the client | No | Never |
| Spending key | In memory | No | Never |
| View key | In memory | No | Never |
| Locator | In memory | No | To the relayer, as the manifest's tag and lookup |
| File key | In memory while sealing or opening | Yes, encrypted under the view key | Only in a share link's fragment, which browsers never send to a server |