Cryptography
How every key comes from one wallet signature, and how a message is sealed, opened and checked.
Every secret a wallet uses in Talaria comes from one signature over one fixed message. Nothing else needs to be stored for the keys to come back on another device. The SDK does all of this on the device, with @noble/curves (X25519), @noble/ciphers (XChaCha20-Poly1305) and @noble/hashes (HKDF, SHA-256, HMAC).
Keys#
The key derivation message#
The wallet signs this text, UTF-8 encoded, with its Ed25519 key. <address> is the wallet's base58 address. Lines end with a single line feed and there is no final newline.
Talaria private inbox
Version: 1
Wallet: <address>
Sign to derive your inbox and local history keys. This does not send a transaction.
Signing it sends no transaction. Ed25519 signatures are deterministic, so the same wallet produces the same 64 bytes every time, on every device. The SDK exports the bytes as keyDerivationMessage(wallet).
Derivation#
Every key below is HKDF-SHA256 with the salt Talaria/v1, an info string, and 32 bytes of output:
derive(key, info) = HKDF-SHA256(ikm = key, salt = "Talaria/v1", info = info, length = 32)
| Key | Derived as | Use |
|---|---|---|
| master | derive(signature, "wallet/<address>") | The root of every key below. Never leaves the device. |
inbox secret, version v | derive(master, "inbox/<v>") | The X25519 private key of the inbox at that version. |
| pass seed | derive(master, "passes") | The source of every pass secret. |
| private link seed | derive(master, "links") | The source of every private link key. |
| local history key | derive(master, "history") | Encrypts what the device keeps. |
Info strings are UTF-8. <address> is the base58 address and <v> a decimal integer from 1.
import { createKeypairSigner, deriveKeys, keyDerivationMessage } from '@talaria/sdk'
declare const secretKey: Uint8Array
const signer = createKeypairSigner(secretKey)
const signature = await signer.signMessage(keyDerivationMessage(signer.address))
const keys = await deriveKeys(signer.address, signature, 1)
// keys.inbox.publicKey is the key open_inbox registers
Inbox keys#
The inbox secret for version v is used as an X25519 private key as it comes out of HKDF; its public key is what open_inbox registers for version 1 and rotate_inbox_key for each next version. On unlock the SDK reads the Inbox's key_version and derives every version from 1 to it, so messages sent to an older key still open.
Pass secrets#
The secret of the wallet's pass number i, counting purchases from 0, is
secret_i = (int(derive(passSeed, "pass/<i>")) mod (r − 1)) + 1
with int reading the 32 bytes big-endian and r the BN254 scalar field modulus, 21888242871839275222246405745257275088548364400416034343698204186575808495617. The pass is bought with id_commitment = Poseidon(secret_i). To find its passes again, a device computes the commitments for i = 0, 1, 2, … up to the number of leaves in the pool and looks each one up among the public leaves. The proof covers what the secret proves.
Private link keys#
Private link number i, counting from 0 on this wallet, has the X25519 private key derive(linkSeed, "link/<i>"). Its public key travels in the link's URL fragment, which a browser never sends to a server:
<app>/l#key=<base64 public key>&name=<name>
name is optional. A device scans with the key of every link it has not revoked.
Creating a link first scans the Log to its head, then takes the index after the highest link the device holds and sends one message to the wallet's own inbox, with the text Private link: <name> (or Private link without a name) and the control { "type": "link-created", "index": …, "name": …, "url": … }. Revoking sends the text Private link revoked with { "type": "link-revoked", "index": … }. A device takes either control only when the writer is its own wallet: link-created adds the link with that index, name and URL, and link-revoked marks it revoked, so every device of the wallet holds the same links and stops scanning a revoked one. The device also tries the keys of every index from 0 up to the number of links it holds plus 7 that it does not hold; when one of those opens a message, it adds that link with the URL and name it reads from the message's target.link.
Sealing a message#
The body#
The plaintext is the UTF-8 JSON of one object. Its fields:
- version1
- Always 1.
Required
- idstring (UUID)
- The message id, shared by all its parts.
Required
- partinteger
- This part's position, from 0.
Required
- totalinteger
- How many parts the message has, 1 to 10,000.
Required
- writeraddress
- The writer's wallet.
Required
- writerInboxKeybase64, 32 bytes
- The writer's inbox public key when writing.
Required
- writerKeyVersioninteger
- Its version.
Required
- sentAtstring (ISO 8601)
- When the message was written, the same in every part.
Required
- targetobject
{ "kind": "wallet", "wallet": … },{ "kind": "room", "roomId": … }or{ "kind": "private-link", "link": … }.Required
- textstring
- This part's text.
Required
- controlany
- A control message, such as a room invite.
- authRecord<string, string>
- Writer MACs, keyed by the base64 inbox key each one is for.
Required
The object is strict: an unknown field makes the body invalid and the entry is skipped.
Content and slots#
Content key
A fresh random 32-byte content key for this payload.
Two slots
Slot 0 is for the reader's key: the reader's inbox key, a room's key or a private link's key. Slot 1 is for the writer's own inbox key. For each, a fresh random X25519 ephemeral key pair, and
shared = X25519(ephemeral secret, target public key).View tag
SHA-256(shared)[0], one byte. It lets a scanner skip all but about one slot in 256 without decrypting.Wrap
The slot key is
derive(shared, "key-slot"). The wrapped key is a random 24-byte nonce, then XChaCha20-Poly1305 of the content key under the slot key, with no additional data: 72 bytes.Header
The version byte, then each slot as ephemeral public key (32), view tag (1), wrapped key (72): 211 bytes.
Encrypt
The ciphertext is a random 24-byte nonce, then XChaCha20-Poly1305 of the body under the content key, with the 211-byte header as additional data.
The tag over the ciphertext authenticates the body and the whole slot header together: a changed ephemeral key, view tag or wrapped key in either slot fails to open. The bytes are laid out on Log entry format.
Opening#
For each entry, a scanner tries every key it holds (each inbox version, each unrevoked link key, each room key) against both slots: shared = X25519(own secret, ephemeral key); if SHA-256(shared)[0] matches the view tag, it unwraps the content key and opens the ciphertext with the header as additional data. A matching view tag that fails to open is a collision and the scanner moves on. Scanning covers the whole pass over the Log.
Writer MACs#
The writer proves inside the ciphertext which wallet wrote, without another wallet prompt. For each key the message is for, and for the writer's own inbox key, the writer adds
auth[base64(K)] = base64(HMAC-SHA256(derive(X25519(writer inbox secret, K), "writer-auth"), body))
where body is the JSON of the body's fields without auth, in the order version, id, part, total, writer, writerInboxKey, writerKeyVersion, sentAt, target, text, then control when present. For a room, K runs over every member's inbox key.
The reader accepts a body only when all of these hold:
- the writer has an Inbox in the inbox directory, and
writerInboxKeyatwriterKeyVersionwas the writer's key at the entry's slot, by the Inbox's key history (valid from its event's slot until the next one); - the MAC under the reader's own key matches: for a room,
authof one of the reader's inbox keys; otherwiseauthof the key that opened the slot; computed asHMACwithderive(X25519(reader secret, writerInboxKey), "writer-auth"); - a body with
target.kindwalletnames the reader, unless the reader wrote it; - the writer is not blocked on this device.
The inbox directory is every InboxOpened and InboxKeyRotated event in chain order. The SDK downloads it whole, the sealed segments of GET /inboxes/segments/:n and the tail of GET /inboxes/head, and folds it on the device into each wallet's Inbox and key history (findInbox, which downloads what is new at most every two seconds when a wallet is missing). The API never learns which wallet a device looks up.
Both ends of a pair can compute the same MAC: it authenticates the writer to the reader, and to no third party.
The self slot#
Slot 1 seals the content key to the writer's own current inbox key, and auth carries the MAC under that key. Any device that derives the writer's keys finds its sent messages in the Log and reads them back as sent, the way Restore rebuilds history.
Rooms#
A room key is a random 32-byte X25519 private key. A message to the room fills slot 0 for the room key's public key, so every member who holds the secret opens it with one key.
The key reaches members as an ordinary message to each one's wallet, with the text Invitation to <room name> and this control:
- typestring
- Marks the control as a room invite.
Required
- roomRoom
- The room as the writer holds it:
id,name,membersandkeyVersion, with the writer's ownstate. Each member carries itswalletandname, withinboxnull;lastMessageisnullandunreadCount0.Required
- secretKeybase64, 32 bytes
- The room key.
Required
A member's device takes an invite only when its members include the reader, the writer is in members or among the room's members as the device holds it, and the secret is 32 bytes. An invite for a room it already holds is taken only from a current member and with a higher keyVersion. An invite the wallet itself wrote whose members leave the wallet out is its leaving: the device sets the room to left and drops its key. The room is joined when the device had already joined it or wrote the invite itself, and invited otherwise; sending to a room also marks it joined, so a restore brings back as joined every room the wallet created or wrote in.
- Create: a new key at
keyVersion1, sent to every member. - Add: the same key at
keyVersion + 1, sent to every member, the new one included. - Remove or leave: a new key at
keyVersion + 1, sent to the remaining members; on leaving, the writer is no longer inmembers. A removed member is first sent a message with the textRemoved from <room name>and the control{ "type": "room-removed", "roomId": … }; from a current member, it sets the room toremovedon the member's device and drops its key.
See Rooms.
Multi-part messages#
The SDK splits text into parts of at most 700 UTF-8 bytes, never inside a character. Each part is its own body (same id, total, writer, target and sentAt, its own part and text), its own payload and its own post with its own nullifier. countParts(text) gives the number.
A scanner collects parts by id and keeps only parts that agree on writer, total and target. When parts 0 to total − 1 are all present it joins their text in order and yields one message. Until then it resumes the next scan from the earliest Log index of an incomplete message.
Before proving a part, the SDK records its payload, pass and counter on the device. A retry reuses them, so a part is never sent twice with two nullifiers.
Local history#
Threads, rooms and their keys, private links, blocks, purchases and pending parts are kept as one JSON document, sealed with the local history key: a random 24-byte nonce, then XChaCha20-Poly1305 with no additional data. In a browser it is stored in IndexedDB, database talaria, object store encrypted, under the wallet's address; elsewhere in memory unless the app passes its own storage. The document opens only after the wallet signs the key derivation message on that device.