Guides

Viewing Keys & Disclosure

Encrypt vault notes and receipts locally, share read-only auditor keys, and verify decrypted amounts against on-chain commitments.

How selective disclosure works

On-chain accounts (RingVault, Mandate, SettlementEscrow) store 32-byte commitments and nullifiers rather than plaintext spend metadata. Principals and optional auditors decrypt exact amounts, fees, unit prices, and response hashes off-chain using a 32-byte hex Viewing Key (viewingKeyHex32).

@tova/sdk encrypts viewing payloads with AES-256-GCM using a domain-separated key derivation:

text
aes_key = SHA256("TOVA_VIEWING_KEY_AES_V1" || viewing_key_bytes_32)
payload = base64(iv_12 || auth_tag_16 || ciphertext)

No viewing key is ever sent to the Solana program or stored on-chain. Only the public 32-byte viewing_key_tag (and optional auditor_key_tag) sits on RingVault and Mandate.

Step 1: Decrypt in the web console

  1. Open Vaults or Settle.
  2. Click Unlock viewing key (or switch the ledger view from Public ledger to Viewing key).
  3. The browser decodes each vault note and settlement encryptedReceipt locally, displaying exact lamport amounts, protocol fees, unit prices, and response hashes alongside the opaque on-chain commitment and nullifier.

Step 2: Encrypt and decrypt with @tova/sdk

ts
import { randomBytes } from 'node:crypto'
import {
  computeAmountCommitment,
  encryptViewingPayload,
  decryptViewingPayload,
} from '@tova/sdk'

const viewingKeyHex32 = randomBytes(32).toString('hex')
const amountLamports = 50_000_000n
const salt = randomBytes(32)

// Encrypt a receipt payload locally
const ciphertext = encryptViewingPayload(viewingKeyHex32, {
  amountLamports: amountLamports.toString(),
  feeLamports: '125000',
  mintSymbol: 'SOL',
  salt: salt.toString('hex'),
})

// Decrypt later using the principal or auditor viewing key
const decoded = decryptViewingPayload<{
  amountLamports: string
  feeLamports: string
  mintSymbol: string
  salt: string
}>(viewingKeyHex32, ciphertext)

// Verify the decrypted amount and salt match the on-chain commitment
const recomputed = computeAmountCommitment(
  BigInt(decoded.amountLamports),
  Buffer.from(decoded.salt, 'hex'),
).toString('hex')

console.log('Recomputed commitment:', recomputed)

Compare recomputed against SettlementEscrow.amount_commitment (fetched via tova.api.settlement(id) or direct RPC account decode). An exact 32-byte match proves that the decrypted amount is the exact value committed in the on-chain escrow.

Step 3: Decrypt from the CLI

bash
tova decrypt <ciphertextBase64> --key <viewingKeyHex32>

tova decrypt prints the decrypted JSON payload to stdout. For unencrypted localnet fixture receipts, --key defaults to 64 zero hex characters (00...00).

Step 4: Share read-only auditor access

To give an external auditor or internal finance reviewer visibility over a specific vault or mandate:

  1. Generate a dedicated 32-byte auditorViewingKey and derive its public auditorKeyTag = SHA256(auditorViewingKey).
  2. Pass auditorKeyTag when calling buildCreateVault or buildIssueMandate.
  3. Encrypt audit copies of note and receipt payloads with auditorViewingKey and deliver the key out of band.

An auditor holding auditorViewingKey can decrypt and verify every commitment in scope, while holding zero signing authority to move funds, issue mandates, or open settlements.