SDK quickstart
Open an inbox, buy a pass, send a message and scan for replies from TypeScript, in a browser or in Node.
@talaria/sdk is the client the Talaria app itself is built on. It derives the keys, encrypts, proves in the browser or in Node, hands each post to a relay and reads the Log back. One call sends a message:
await talaria.send(to, text)
This page goes from an empty project to that line and to the scan that receives the answer. SDK reference gives every method and type.
Install#
npm install @talaria/sdk
The package is ESM only and runs in the browser and on Node 22 or newer; its browser build imports no Node module. It brings @talaria/contract, the schemas and HTTP client for the API, as a dependency.
The prover artifacts#
Every message carries a Groth16 proof made on the writer's device. The prover needs three files from the circuit build. They ship beside the package as a prover/ folder, with a manifest.json that records each file's SHA-256.
| File | What it is | Size |
|---|---|---|
talaria.wasm | The compiled circuit, run to compute the witness | 2,487,805 bytes |
final.zkey | The proving key | 4,513,207 bytes |
verification_key.json | The verifying key, used by demoProof | 4,135 bytes |
The program checks proofs against a verifying key built from the same setup, so use the folder that matches the deployed program. In a browser, serve the files as static assets of your app and pass their URLs; the Talaria app serves them under /prover/. In Node, pass file paths and a readArtifact function that reads them. The prover is loaded on the first proof, not when the client is created.
Create a client in a browser#
A browser client signs with the wallet the visitor connected. The signer gives the SDK the wallet's address and two functions over raw bytes: one signs a message, one signs a serialized transaction and returns it serialized.
import { VersionedTransaction } from '@solana/web3.js'
import { createTalaria } from '@talaria/sdk'
const talaria = createTalaria({
apiUrl: 'http://127.0.0.1:6710',
relayUrls: ['http://127.0.0.1:6711', 'http://127.0.0.1:6712'],
signer: {
address: wallet.publicKey.toBase58(),
signMessage: (message) => wallet.signMessage(message),
signTransaction: async (bytes) =>
(await wallet.signTransaction(VersionedTransaction.deserialize(bytes))).serialize(),
},
prover: {
wasm: '/prover/talaria.wasm',
zkey: '/prover/final.zkey',
verificationKey: '/prover/verification_key.json',
},
})
wallet is the connected wallet adapter. The URLs are the development defaults: the API on port 6710 and two relays on 6711 and 6712. Leave out relayUrls and the client takes the relays the API lists at GET /relays.
The first call that needs keys asks the wallet to sign one fixed message. It is not a transaction and costs nothing. Every key the client uses is derived from that signature on the device: the inbox key, the secret behind each pass, the private link keys and the key that encrypts local history. Cryptography gives the derivation. History is kept in IndexedDB, encrypted.
Create a client in Node#
In Node, createKeypairSigner turns a secret key into the same signer. It takes the 64-byte secret key of a Solana keypair file, or its 32-byte seed.
import { readFile } from 'node:fs/promises'
import { createKeypairSigner, createTalaria } from '@talaria/sdk'
const secretKey = Uint8Array.from(JSON.parse(await readFile('wallet.json', 'utf8')) as number[])
const talaria = createTalaria({
apiUrl: 'http://127.0.0.1:6710',
relayUrls: ['http://127.0.0.1:6711', 'http://127.0.0.1:6712'],
signer: createKeypairSigner(secretKey),
prover: {
wasm: 'prover/talaria.wasm',
zkey: 'prover/final.zkey',
verificationKey: 'prover/verification_key.json',
readArtifact: async (path) => new Uint8Array(await readFile(path)),
},
})
A Node client keeps its history in memory unless you pass storage. Passes are derived again from the wallet on every start, so a new process can send at once; a scan from a fresh process starts at the beginning of the Log. EncryptedStorage shows a store on disk.
Open an inbox#
const { inbox } = await talaria.openInbox()
openInbox derives the keys, has the API build an open_inbox transaction, asks the signer to sign it, submits it and waits until the API reads the new Inbox back. The wallet pays the account's rent and the transaction fee. From then on anyone can write to this wallet. A wallet opens its inbox once; rotateInboxKey replaces the key later.
Buy a pass#
const pass = await talaria.buyPass({ tier: 'light', days: 30 })
A pass is a daily limit and a length. The tier ids are light, daily and frequent, for 25, 250 and 2,500 messages a day, and the lengths are 30, 90 and 365 days (development defaults; GET /pool gives the live tiers, lengths and exact prices). A pass costs its daily limit times its days times the message fee: the call above costs 0.0075 SOL at the development default fee.
buyPass returns once the pass's leaf is in the pool. The pass secret never leaves the device: the client derives it from the wallet signature and finds the pass again from the public leaves on any device. See Passes.
Send a message#
const receipt = await talaria.send(to, text)
to is a wallet address, a .sol name, or a target object for a room or a private link. A .sol name resolves on the device through the client's nameService: the local build's table by default (ari.sol, bo.sol, cy.sol, talaria.sol), or the SPL Name Service read over rpcUrl with nameService: 'sns' (see lookup). The client then finds the reader's inbox key in the whole inbox directory it downloads, so no request names the name or the wallet it writes to. For each part of the text the client encrypts to the reader's inbox key with two key slots, proves with the oldest pass that has messages left today, hands the proof and payload to a relay and waits until the API has indexed the entry. receipt.signatures holds one transaction signature per part, in order.
Text longer than 700 UTF-8 bytes is sent as several parts, one post each, and each part uses one message of the day. talaria.countParts(text) says how many a text takes before it is sent.
Each part starts at the next relay in the list, so a client's posts take turns across its relays. If a relay fails, the client checks whether the post landed anyway and otherwise sends the same payload and nullifier through the next relay, with a new proof bound to that relay. A message that still fails stays in pendingMessages() for retry.
Scan for messages#
for await (const message of talaria.scan({ follow: true })) {
if (message.direction === 'received') console.log(message.writer, message.text)
}
scan downloads the whole Log and tries every entry with the device's keys. It yields each message once all its parts are found, with the writer's inbox key checked against the writer's Inbox at the entry's slot. Messages this wallet sent from another device come back too, with direction: 'sent'. The scan remembers its position, so the next scan starts where this one stopped.
Without follow the loop ends at the head of the Log. With follow it keeps reading new entries until its signal aborts or talaria.close() is called; the loop then throws the abort reason. To read a whole history on a new device, call restore.
Follow progress#
Every long call takes an onProgress callback. Sending reports encrypting, proving, relaying, landed or failed for each zero-based part; wallet transactions report building, signing, confirming, indexed or failed; a scan reports downloading, scanning, following or complete with its Log position.
await talaria.buyPass({ tier: 'light', days: 30 }, {
onProgress: (progress) => console.log(progress.stage),
})
const receipt = await talaria.send(to, text, {
onProgress: (progress) => {
const part = `${progress.part + 1}/${progress.totalParts}`
if (progress.stage === 'relaying') console.log(part, 'relaying through', progress.relayUrl, 'attempt', progress.attempt)
else if (progress.stage === 'landed') console.log(part, 'landed', progress.signature)
else if (progress.stage === 'failed') console.error(part, progress.error.code, progress.error.message)
else console.log(part, progress.stage)
},
})
console.log(receipt.signatures)
for await (const message of talaria.scan({
onProgress: ({ stage, nextLogIndex, headLogIndex }) => console.log(stage, nextLogIndex, '/', headLogIndex),
})) {
console.log(message.text)
}
landed means the entry is in the Log the API serves. A failure also throws: catch it around the call, and read its code in SDK errors.