Inboxes and keys
The one signature every key comes from, the Inbox account, the inbox directory and .sol names, and rotating and restoring keys.
An inbox is the key a wallet registers so anyone can write to it. The wallet's keys, the inbox key among them, come from one signature the wallet makes in the app. Nothing secret leaves the device, and no key is kept that the wallet can't derive again.
The one signature#
The first time a wallet connects on a device, the app asks it to sign a fixed message. The message names Talaria, its version and the wallet's address, and says it does not send a transaction. It costs nothing and moves nothing.
A Solana wallet signs with Ed25519, which gives the same signature for the same message every time. The same wallet therefore derives the same keys on every device. From that signature the app derives, with HKDF-SHA256:
| Key | Derived by | What it is for |
|---|---|---|
| Inbox key pair (X25519) | key version: 1, 2, 3, … | Anyone encrypts to its public key; the current version is registered in the wallet's Inbox. |
| Pass secrets | pass index: 0, 1, 2, … | The secret behind each pass the wallet buys. Its commitment goes into the pool; the secret stays here and feeds every proof. |
| Private-link seed | one per wallet | The source of every private link's key, derived from it by link index. |
| Local history key | one per wallet | Encrypts this device's history at rest. |
Cryptography gives the exact message, the derivation labels and the curves.
Pass secrets are derived again whenever they are needed, never stored. The app finds the wallet's passes by deriving each index's secret and looking for its commitment among the pool's leaves.
Local history#
What the app knows on this device lives in one record, encrypted with XChaCha20-Poly1305 under the local history key: messages, threads and whether each is a request, rooms and their keys, private links, blocked wallets, pass purchases, sends still in progress, and how far the Log has been read. A browser keeps it in IndexedDB; Node keeps it in memory unless the caller passes its own store. The record is unreadable without the wallet's signature.
The Inbox account#
Each wallet has at most one Inbox, a program account at a fixed address derived from the wallet. It holds the wallet, the current inbox key, its key version, the slot and time it was opened, and the time it was last changed. Program accounts lists the fields with their sizes and seeds.
The Inbox holds a key and nothing else. It records no message, no thread and no writer. A writer reads it to find the key to encrypt to, and a reader's app reads a writer's Inbox to check the key that writer claims.
Both read every Inbox, their own included, from the device's copy of the inbox directory.
The inbox directory#
The inbox directory is every open_inbox and rotate_inbox_key the program has accepted, as one event each, in chain order. Every device downloads all of it, the same way it downloads the Log.
| Request | What comes back |
|---|---|
GET /inboxes/head | the number of events, the number of sealed segments, the segment size (256), and the tail: every event after the last sealed segment |
GET /inboxes/segments/:n | one sealed segment of 256 events, for every n from 0 to the segment count minus one; a sealed segment never changes |
Each event is { index, wallet, inboxKey, keyVersion, slot, blockTime }: its position in the directory from 0, the wallet, the X25519 key it registered (base64), that key's version, and the slot and time of the transaction. A device keeps the segments it already has and downloads only new ones, then the tail.
The device folds the events in order into one Inbox per wallet. The first event of a wallet gives its opened slot and time; each event sets the current key, the key version and the time it last changed, and adds a key to the wallet's key history, valid from its event's slot. The next event of the same wallet closes the previous key at its own slot. The result has the same shape as the Inbox account, with its whole key history beside it.
Every lookup reads that copy: the wallet a thread is started with, each member of a room, the writer of each message a scan opens, and the device's own Inbox when it unlocks, opens an inbox or rotates its key. When a wallet is missing from the copy and the copy is more than two seconds old, the device downloads what is new and looks again. For its own Inbox it always downloads what is new first. Every device downloads the same directory whoever it belongs to, so the API never learns which wallet a device looks up, hears from or writes to, its own included.
.sol names#
A .sol name resolves on the device too, to a wallet whose Inbox is then read from the directory. The SDK's nameService option says where names come from:
nameService | Where a name resolves |
|---|---|
'local', the default | the local build's table, LOCAL_NAMES: ari.sol, bo.sol and cy.sol, each a fixed development wallet, and talaria.sol, Talaria's own wallet |
'sns' | the SPL Name Service: the name's account is read over the client's own rpcUrl, and its owner is the wallet; second-level names only, such as name.sol |
| a table | a Record<string, string> of name to wallet the app supplies |
A name that is not registered resolves to no wallet. The app uses 'sns' on mainnet and 'local' on the local build. The API never sees a name.
import { createTalaria, type WalletSigner } from '@talaria/sdk'
declare const signer: WalletSigner
const talaria = createTalaria({ apiUrl: 'http://127.0.0.1:6710', signer, nameService: 'local' })
await talaria.syncDirectory({ onProgress: (p) => console.log(p.loadedEvents, p.totalEvents) })
const result = await talaria.lookup('bo.sol')
if (result.status === 'found') console.log(result.wallet, result.inbox?.keyVersion ?? 'no inbox')
lookup answers found with the wallet, the name and the Inbox or null, not_found for a name that resolves to no wallet, or invalid for text that is neither an address nor a .sol name. findInbox reads one wallet's Inbox from the same copy, and syncDirectory fills it.
Opening an inbox#
Sign the key message
The app derives the keys above. Version 1 of the inbox key is the one to register.
Sign open_inbox
The app asks the API to build an
open_inboxtransaction with the public key, the wallet signs it, and the API submits it. The app shows Sign in your wallet, Confirming, Done.The Inbox exists
The program creates the Inbox with key version 1 and the slot it was opened. The app downloads the inbox directory until its
InboxOpenedevent is there with this key, then reads the Log.
A wallet that already has an Inbox can't open a second one: the build is refused in simulation with INBOX_ALREADY_OPEN.
The wallet pays the account's rent and the network fee. The Inbox takes 101 bytes, and its rent is 1,593,840 lamports on the local validator and 1,163,320 lamports at the mainnet rate. open_inbox gives the instruction, and Errors the reasons it can be refused.
Once the Inbox exists, anyone can write to the wallet. The first message comes from Talaria's own wallet, talaria.sol, a few seconds later: a welcome sent through the pool like any other message, waiting under Requests. A wallet without one can't be written to: there is no key to encrypt to, and the app says so in place of the composer.
Rotating the inbox key#
Rotate inbox key in Keys at /app/keys replaces the registered key with the next version.
Derive the next version
The app reads the Inbox's key version and derives the key pair for the version after it, from the same signature.
Sign rotate_inbox_key
The wallet signs the transaction. The program requires the new key to differ from the old one, raises the key version by one and records the time. The app shows Sign in your wallet, Confirming, New key in use.
New messages use the new key
Writers encrypt to whatever key the Inbox holds when they write, so messages written from then on use the new version.
Rotation creates no account, so it costs only the network fee. If it fails, the app shows the reason and says the key was not changed. rotate_inbox_key gives the instruction.
Old keys after a rotation#
Every earlier version stays usable on the reader's side. When the app starts, it reads the Inbox's current key version and derives every version from 1 up to it, and a scan tries each of them. Messages written to an older key, including any written while the rotation was confirming, still open.
Writer key history#
Each wallet's key history comes from the inbox directory, folded on the device: every key version with the slot from which it was registered and the slot at which it was replaced. Inside each message the writer names their wallet, their inbox key and its version. A reader's app accepts the message only if that key and version were the writer's registered key at the slot of the message's Log entry. A message a writer sent before rotating still verifies after; a message signed with a key the writer had already replaced does not. Scanning covers the check in order.
Restoring on another device#
Connect the same wallet
Open /app on the other device and connect.
Sign the key message
The same signature gives the same keys: every inbox key version, every pass secret and the same history key.
Read the Log
A device with no history reads the Log from its first entry, so everything written to this wallet and everything it sent comes back. Restore in Keys reads the whole Log again from the first entry at any time, showing the entry reached, the Log's length and how many messages were found, then Done with the count.
A restore rebuilds threads, sent messages, rooms, private links and passes:
- Sent messages return through the self slot: every message carries a second key slot encrypted to the writer's own inbox key.
- Threads return from the messages in them. A thread this wallet started or replied in comes back accepted; a thread another wallet started that this wallet never answered comes back as a request.
- Rooms return through their invitations, which are messages in the wallet's threads. A room this wallet created or wrote in comes back joined. A room it was invited to and never wrote in waits to be accepted on this device, a room it was removed from comes back removed, and a room it left comes back left.
- Private links return through the notes their creation and revocation sent to the wallet's own inbox: every link with its index, name and URL, and every revoked link marked revoked. Private links gives the details.
- Passes return by deriving their secrets again and finding their leaves in the pool, and the meter counts today's messages from the Log.
Blocking, accepting a request and declining a room are kept on the device where they were done. Replying in a thread or writing in a room is what carries acceptance to every device.