Guides

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 auditorKeyTag if you want to delegate read-only audit access.

Step 1: Create and fund a vault

Web console

  1. Open Vaults and connect your principal wallet.
  2. Choose the settlement mint (SOL or USDC, or paste any SPL mint address).
  3. Enter an initial deposit amount in lamports or token base units.
  4. Click Create & deposit. The console calls POST /v1/vaults/build (bundling create_vault and deposit_shielded in one v0 transaction), prompts your wallet to sign, and submits via POST /v1/transactions/submit.

TypeScript SDK

ts
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:

ts
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

bash
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:

ts
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

ErrorCauseFix
ZeroAmountamount is 0Pass a positive u64 base-unit amount
ProtocolPausedProtocolConfig.paused is trueWait for protocol authority to unpause
InsufficientVaultBalanceWithdrawal exceeds RingVault.escrow_balanceReduce withdrawal amount below available escrow balance
VALIDATION_ERRORviewingKeyTag or commitment is not 64 hex charactersPass a 32-byte lowercase hex string

Next step

Delegate bounded spending authority to an autonomous agent in Issue an Agent Mandate.