Create a Ring Vault
Create a principal-owned Shielded Ring Vault, deposit SOL or SPL tokens into encrypted notes, and withdraw shielded funds.
Prerequisites
- A Solana wallet funded with SOL for account rent and deposits.
- A 32-byte hex Viewing Key (
viewingKeyHex32) stored locally by the principal, plus its 32-byte public tag (viewingKeyTag). - Optional: a 32-byte
auditorKeyTagif you want to delegate read-only audit access.
Step 1: Create and fund a vault
Web console
- Open Vaults and connect your principal wallet.
- Choose the settlement mint (
SOLorUSDC, or paste any SPL mint address). - Enter an initial deposit amount in lamports or token base units.
- Click Create & deposit. The console calls
POST /v1/vaults/build(bundlingcreate_vaultanddeposit_shieldedin one v0 transaction), prompts your wallet to sign, and submits viaPOST /v1/transactions/submit.
TypeScript SDK
import { randomBytes, createHash } from 'node:crypto'
import { TovaClient, computeAmountCommitment, encryptViewingPayload } from '@tova/sdk'
const tova = new TovaClient({ apiUrl: 'http://127.0.0.1:37402' })
const viewingKeyHex32 = randomBytes(32).toString('hex')
const viewingKeyTag = createHash('sha256')
.update(Buffer.from(viewingKeyHex32, 'hex'))
.digest('hex')
const amountLamports = 500_000_000n // 0.5 SOL
const salt = randomBytes(32)
const initialCommitment = computeAmountCommitment(amountLamports, salt).toString('hex')
const initialCiphertext = encryptViewingPayload(viewingKeyHex32, {
amountLamports: amountLamports.toString(),
asset: 'SOL',
salt: salt.toString('hex'),
})
const built = await tova.api.buildCreateVault({
principal: process.env.PRINCIPAL_PUBKEY!,
mint: 'So11111111111111111111111111111111111111112',
viewingKeyTag,
initialDepositLamports: amountLamports.toString(),
initialCommitment,
initialCiphertext,
})
console.log('Vault PDA:', built.targetAddress)
console.log('Unsigned v0 tx (base64):', built.transactionBase64)Sign built.transactionBase64 with the principal wallet, then call tova.api.submitTransaction({ id: built.id, signedTransactionBase64 }) (or pass signature after sending directly to RPC).
Step 2: Top up an existing vault
To add another encrypted note to an existing RingVault, call buildDepositShielded:
const salt2 = randomBytes(32)
const topUpLamports = 250_000_000n
const commitment = computeAmountCommitment(topUpLamports, salt2).toString('hex')
const ciphertext = encryptViewingPayload(viewingKeyHex32, {
amountLamports: topUpLamports.toString(),
asset: 'SOL',
salt: salt2.toString('hex'),
})
const depositTx = await tova.api.buildDepositShielded(built.targetAddress!, {
principal: process.env.PRINCIPAL_PUBKEY!,
amountLamports: topUpLamports.toString(),
commitment,
ciphertext,
})Each deposit advances RingVault.merkle_root, increments note_count, and adds amountLamports to vault_escrow.
Step 3: Inspect the vault via CLI
tova vault list --principal <principalPubkey>
tova vault get <vaultPda>tova vault get returns the vault's merkleRoot, noteCount, escrowBalanceLamports, activeMandateCount, and the notes array containing each leaf's commitment and ciphertext.
Step 4: Withdraw shielded funds
The principal can withdraw any unencumbered balance back to the principal wallet with withdraw_shielded, providing a unique 32-byte nullifierHash:
const nullifierHash = randomBytes(32).toString('hex')
const withdrawTx = await tova.api.buildWithdrawShielded(built.targetAddress!, {
principal: process.env.PRINCIPAL_PUBKEY!,
amountLamports: '100000000',
nullifierHash,
})withdraw_shielded initializes the NullifierRecord PDA (["nullifier", ring_vault, nullifier_hash]), transfers amountLamports from vault_escrow back to principal, and updates RingVault.merkle_root.
Common failures
| Error | Cause | Fix |
|---|---|---|
ZeroAmount | amount is 0 | Pass a positive u64 base-unit amount |
ProtocolPaused | ProtocolConfig.paused is true | Wait for protocol authority to unpause |
InsufficientVaultBalance | Withdrawal exceeds RingVault.escrow_balance | Reduce withdrawal amount below available escrow balance |
VALIDATION_ERROR | viewingKeyTag or commitment is not 64 hex characters | Pass a 32-byte lowercase hex string |
Next step
Delegate bounded spending authority to an autonomous agent in Issue an Agent Mandate.