@privium/sdk runs every account flow from TypeScript: one wallet signature opens the account, and every key derives from it inside the caller’s process. It is ESM over the platform’s fetch and Web Crypto, so the same package runs in the browser and in Node 22.
Install#
npm install https://privium.io/sdk/privium-sdk-0.1.25.tgz
The SDK ships as one versioned tarball from privium.io, self-contained: it bundles the contract and every runtime dependency, so the install fetches nothing from the npm registry. The SDK’s entry points (@privium/sdk, /wire, /crypto, /fixtures, /program, and the bundled contract as /contract and /contract/fixtures) are listed in the Type reference.
Connect#
import { Privium } from '@privium/sdk'
const privium = await Privium.connect({ apiUrl: 'https://api.privium.io', wallet })
console.log(privium.account.id)
Privium.connect resolves to a connected account. In order, it:
- Creates the contract client for
apiUrland readsGET /v1/config. - Asks the wallet to sign
ACCOUNT_MESSAGE, once. - Verifies the signature against
wallet.publicKeyby strict Ed25519. - Derives the account’s keys from the signature.
The configuration read is the only request. Nothing is sealed, sent to intake or landed on chain.
ConnectOptions#
| Field | Type | Meaning |
|---|---|---|
apiUrl |
string |
The API's base URL, https://api.privium.io. |
wallet |
Wallet |
The wallet that signs the account message once. Deposits use its transaction signing. |
fetch |
typeof fetch (optional) |
The fetch every API request and the event stream use; the global fetch when absent. |
fixture |
string (optional) |
A scenario name sent as X-Fixture on every request, for an API in fixture mode. |
origin |
string (optional) |
The site origin disclose and receipt build links on; https://privium.io when absent. |
publicData |
ReceiptPublicData (optional) |
The records privium.receipts.verify reads; receiptPublicData over this API when absent. |
Errors#
| Code | Stage | Message |
|---|---|---|
SIGNATURE_INVALID |
wallet | The wallet signature is invalid. |
A failed configuration read throws the API’s ApiClientError. Whatever the wallet’s signMessage throws, a declined request included, reaches the caller unchanged.
The wallet adapter#
Wallet#
| Field | Type | Meaning |
|---|---|---|
publicKey |
string |
The wallet's address, base58. The account message's signature is verified against it. |
signMessage |
(message: Uint8Array) => Promise<Uint8Array> |
Signs raw bytes and resolves to the 64-byte Ed25519 signature. |
signTransaction |
(transaction: Uint8Array) => Promise<Uint8Array> (optional) |
Signs serialized transaction bytes and resolves to the signed bytes. deposit uses it when signAndSendTransaction is absent. |
signAndSendTransaction |
(transaction: Uint8Array, options?: { preflightCommitment: 'confirmed' }) => Promise<string> (optional) |
Signs and sends serialized transaction bytes and resolves to the transaction signature, base58. deposit prefers it. |
signMessage must resolve to the raw 64-byte signature over exactly the bytes it was given. Only deposit uses the transaction methods; every other call signs with the account’s own keys and never prompts the wallet.
From a Wallet Standard wallet#
Wallet Standard’s Solana features resolve to arrays of outputs and return the sent transaction’s signature as bytes, so the adapter takes the first output and encodes that signature in base58:
import type { Wallet } from '@privium/sdk'
import { toBase58 } from '@privium/sdk/contract'
// The parts of a Wallet Standard account and its Solana features this adapter reads.
interface StandardAccount { address: string; publicKey: Uint8Array }
interface SolanaFeatures {
'solana:signMessage': {
signMessage(input: { account: StandardAccount; message: Uint8Array }): Promise<readonly { signature: Uint8Array }[]>
}
'solana:signTransaction'?: {
signTransaction(input: { account: StandardAccount; transaction: Uint8Array; chain: string }): Promise<readonly { signedTransaction: Uint8Array }[]>
}
'solana:signAndSendTransaction'?: {
signAndSendTransaction(input: { account: StandardAccount; transaction: Uint8Array; chain: string }): Promise<readonly { signature: Uint8Array }[]>
}
}
export function fromWalletStandard(features: SolanaFeatures, account: StandardAccount, chain: string): Wallet {
const signer = features['solana:signTransaction']
const sender = features['solana:signAndSendTransaction']
return {
publicKey: account.address,
async signMessage(message) {
const [output] = await features['solana:signMessage'].signMessage({ account, message })
return output.signature
},
signTransaction: signer && (async (transaction) => (await signer.signTransaction({ account, transaction, chain }))[0].signedTransaction),
signAndSendTransaction: sender && (async (transaction) => toBase58((await sender.signAndSendTransaction({ account, transaction, chain }))[0].signature)),
}
}
Pass the wallet’s features and the connected account, with the Wallet Standard chain id of the cluster the API serves (solana:mainnet for Privium’s API). A wallet that returns a signature over altered bytes fails step 3 of connect with SIGNATURE_INVALID.
The one signature#
The wallet signs this message, UTF-8 with no trailing newline:
Privium account v1
This signature derives your Privium keys. It moves no funds.
Ed25519 signatures are deterministic, so the same wallet always gives the same signature and therefore the same account, on any device. Each key is HKDF-SHA256 of the 64-byte signature with 32 zero bytes of salt and its own info label. Your account and keys tells what each key is for.
AccountKeys#
| Field | Type | Meaning |
|---|---|---|
id |
string |
The display account id: base58 of SHA-256 of privium/account-id/v1 and the auth public key. |
authSeed |
Uint8Array |
The auth key's Ed25519 seed. It signs every Intent. HKDF info privium/auth/v1. |
authPublicKey |
Uint8Array |
The auth public key: the account's identifier in every Intent. |
viewSeed |
Uint8Array |
The viewing root. It decrypts balances, history and bundles. HKDF info privium/view/v1. |
escapeSeed |
Uint8Array |
The escape key's seed. HKDF info privium/escape/v1. |
escapeScalar |
bigint |
The escape key as a ristretto255 scalar, scalar(escapeSeed). |
escapePublicKey |
Uint8Array |
The escape scalar times the ristretto255 base point. |
salt |
Uint8Array |
The owner tag salt. HKDF info privium/salt/v1. |
noteSeed |
Uint8Array |
The X25519 private key that opens the enclave's replies. HKDF info privium/note/v1. |
notePublicKey |
Uint8Array |
The reply key the enclave seals replies to. |
deriveAccountKeys(signature) in @privium/sdk/crypto derives the same keys from a signature the caller already holds.
The enclave learns the account from its first Intent. Before an instance’s first Intent of any kind, it sends a register Intent carrying the account’s public keys (auth public key, viewing root, escape public key, owner salt and reply key), signed and sealed like every Intent. If intake is unreachable at that moment, the call throws INTAKE_UNAVAILABLE at stage send. Once intake accepts it, the instance does not send it again.
What an instance holds#
| Member | Holds |
|---|---|
privium.account |
id, the display account id, and authPublicKey, the key every Intent names its account by. No route takes either. |
privium.keys |
The AccountKeys above, secret halves included. The SDK holds them in memory and writes them nowhere; a new process signs the message again. |
privium.config |
The Config: the program id, the Pool’s parameters and the active enclave key every new Intent is sealed to. Read at connect and kept current as The enclave key gives. |
privium.api |
The contract client (PriviumApi) built from apiUrl, fetch and fixture: every route as a typed method (API reference). |
privium.receipts |
verify, which checks a Receipt against the API’s public records, each pinned to the chain through the RPC relay (receipts.verify). |
Every member with its signature is in the Type reference.
The enclave key#
Before it seals new work, an instance reads GET /v1/config again: at the start of trade, exit and deposit, before every Intent of another kind (cancel, receipt, status and the registration), and when watchEvents opens and after each crossing event. The new configuration replaces privium.config, so a new Intent seals to the enclave key active at that moment, with the account’s keys unchanged. Every key the instance has seen, active or previous, stays with it to open replies, newest first, and a retry sends its bytes under the key they were sealed to. A configuration that names another program than the one connected to throws CONFIGURATION_REQUIRED at stage read: connect again.
With each of these configuration reads the instance checks the active key’s registration on chain with verifyEnclaveRegistration, and it checks a key the same way before it takes a reply opened under it; each key is checked once. A key whose quoteHash reads as zeros, its attestation not yet indexed, throws PROGRAM_UNAVAILABLE at stage read: retry once it is.
Before new secrets are sealed to the active key, the instance also checks that the key holds a live slot of the program’s Registry account with verifyActiveEnclave: once in each call that seals an Intent under the account’s queue (Nonces), and in each deposit. A retry seals nothing new and sends its bytes as they are. A key whose slot has ended or been replaced takes no new Intent or deposit note, and the check throws a plain Error, UNKNOWN_ENCLAVE_KEY. Replies and Receipts signed under a key are checked against its EnclaveKey record alone, which stays on chain after its epoch.
Nonces#
Every Intent carries a 64-bit nonce from nextNonce: Unix milliseconds shifted left 20 bits, joined with 20 random bits, and raised to at least one above the last nonce the process issued and one above the instance’s floor. The sequence is shared by every instance in a process. The floor starts at zero; openOrders() raises it to the account’s signed watermark and the highest nonce of its open orders.
No nonce store is kept or needed. Nonces rise with the clock, two tabs draw independent low bits, and a device whose clock trails another’s calls openOrders() once to start above every nonce the enclave has accepted. Submission.retry sends the same sealed bytes under the same nonce, and intake answers them once (Nonces and replay).
An account’s signed calls run one at a time in a process, across instances: trade, cancel, exit, receipt, openOrders, readBalances, the status reads of disclose and readHistory, and every retry each hold a queue keyed by the auth public key from nonce allocation through sealing and intake, and exit holds it through all of its pieces, so within a process an account’s Intents reach intake in nonce order.