The reading key
How the reading key is derived from one wallet signature, what it seals and reads, and what the chain and the API hold of it.
The key that reads your sealed balances and receipts, derived in the browser from one wallet signature. It is an x25519 key pair. Its secret half encrypts what you send below and decrypts what comes back to you. Its public half goes on chain beside every ciphertext, so the cluster can answer to you and to nobody else.
Derivation
The key is not generated and not stored. It is computed from your wallet each time:
The wallet signs one fixed message
The message is the same for every wallet and every session. Signing it is a message signature, not a transaction: it moves nothing and costs nothing.
The signature is hashed
The SHA-256 of the 64-byte signature is the 32-byte x25519 secret key.
The public key follows from the secret
The x25519 public key of that secret is the half that goes on chain.
A Solana wallet signs with Ed25519, and an Ed25519 signature is deterministic: the same key signing the same bytes always produces the same signature. So the same wallet always derives the same reading key, on any device and in any session, with nothing to back up. Whoever holds the wallet can read what the wallet holds below.
The signed message
The SDK exports the message as READING_KEY_MESSAGE. It is signed as UTF-8 bytes, exactly as written here, with one empty line after the first line:
Hadal reading key
Signing this derives the key that seals your orders and reads your sealed balances, orders and receipts on this device. It moves nothing and costs nothing.In code
deriveReadingKey takes any function that signs bytes with the wallet and returns the key pair:
import { deriveReadingKey } from '@hadal/sdk'
const key = await deriveReadingKey((message) => browserWallet.signMessage(message))
// key.secretKey: 32 bytes, stays here
// key.publicKey: 32 bytes, sent with every sealed valueDeriving it from a keypair in Node is shown in the script guide. The calls are in the SDK reference.
What it seals
Every private value you send is encrypted with the key before it leaves the device:
| Action | Sealed values |
|---|---|
Swap | Side, size and limit. |
Place order | Side, size and limit. |
Open deal | Size, minimum size and limit. The side of a deal is public. |
Answer | Size and limit. |
Add liquidity | The base amount and the quote amount. |
Remove liquidity | The number of shares. |
Each of these also seals the address of the wallet it is sealed for, and the circuit checks it against the account that acts: ciphertext copied from someone else's order or deal is void and tells the copier nothing. A deposit and a withdrawal carry a public amount and seal nothing on the way in. What each action shows on the surface is listed in What is sealed and what is seen.
What it reads
The cluster encrypts each result to the public half of your key, and the secret half opens it:
| Sealed record | Where it is | What you read |
|---|---|---|
Your ledger | Your balance account in each market | Base held, quote held, pool shares held, and the receipt of your last action. |
An order’s receipt | The order account | Your ledger as the order’s last computation left it: filled, crossed, swept, resting, fee. |
An order’s terms | The order account | The side, size and limit you placed. |
A deal’s terms | The deal account | The size, minimum size and limit you set as maker. A taker cannot open them. |
Receipts history | The program’s events, served by the API | Every ledger a computation left for you, one for each action. |
A sealed balance is bound to one key: the public half given when the balance is opened is stored on the balance account, and every later result for that balance is encrypted to it. Because the key always derives from the same wallet, that is the key you have. One reading key serves a wallet everywhere, in the app and in the SDK. A sealed value opened with any other key decodes to meaningless numbers, not to an error.
The book, the pool's reserves and a deal's escrow are sealed to the cluster alone. No reading key opens them.
The shared secret and the cipher
Encryption runs between two parties: you and the cluster. The cluster has one x25519 public key for the Hadal program, stored on chain.
- Your secret key and the cluster's public key give a shared secret by x25519 Diffie-Hellman. The cluster reaches the same secret from its side with your public key. Its nodes hold shares of what they compute on and never see a value in the clear.
- The cipher key is derived from the shared secret with the Rescue-Prime hash.
- Values are encrypted with the Rescue cipher in counter mode, at 128-bit security, over the field of integers modulo 2^255 - 19. Each value becomes one ciphertext of 32 bytes.
A ledger is ten 64-bit numbers packed three to a value, so it is four ciphertexts. An order's terms and a deal's terms are five each: their values, then the owner's address in two.
The trust model of the cluster is told in Arcium.
Nonces
Every encryption uses a nonce of 16 bytes. The SDK draws a fresh random one each time it seals, and sends it with the ciphertext. When the cluster writes a result it encrypts under a nonce of its own, which the account stores beside the ciphertext: nonce on a balance, receiptNonce on an order, termsNonce on a deal. The reader takes the nonce from where the ciphertext is. The same value sealed twice gives two unrelated ciphertexts.
What the chain and the API hold
| Place | Holds | Does not hold |
|---|---|---|
The chain | Ciphertexts, their nonces, and the public half of your key on your balance, your orders and your deals | The secret half, the shared secret, or any value in the clear. |
The HTTP API | The same ciphertexts and nonces, with the public half as encryptionKey | The secret half. It never receives one and never decrypts. |
Your device | The secret half, for as long as the session lasts | A stored copy. The key is derived again from the wallet when it is needed. |
The secret half never leaves the device. It is not sent to the chain, to the API or to the cluster, and no call of the SDK takes it anywhere: sealing and opening both happen locally, and only ciphertext and the public half go out. The shape of a sealed value in an API response is in Sealed values.
Unlock in the app
The app derives the key with the SDK's deriveReadingKey over the message above, so the app and a script hold the same key for the same wallet.
Connect a wallet
Press Connect wallet in the bar. While the key is not derived, sealed panels read Locked and the action button of every form reads Unlock: on Trade, on Deals, on Pools for Add liquidity, Remove liquidity and Create market, and on Portfolio for Deposit and Withdraw.
Press Unlock
The button is also in the bar beside your address. Your wallet shows the message above and asks for a signature.
Sign
The key is derived in the browser and kept in memory there. The app reads your accounts from chain, decrypts balances, shares and receipts with the key, and shows them. The wallet menu reads Reading key: unlocked.
Declining the signature leaves everything as it was: the app reports Still locked, and nothing moved. Markets and soundings are public and need no key.
The key lasts until the tab is reloaded or the wallet changes. The app is then locked again, and one more signature derives the same key. The key is never written to the browser's storage.