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:
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
- Open Vaults or Settle.
- Click Unlock viewing key (or switch the ledger view from Public ledger to Viewing key).
- The browser decodes each vault note and settlement
encryptedReceiptlocally, 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
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
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:
- Generate a dedicated 32-byte
auditorViewingKeyand derive its publicauditorKeyTag = SHA256(auditorViewingKey). - Pass
auditorKeyTagwhen callingbuildCreateVaultorbuildIssueMandate. - Encrypt audit copies of note and receipt payloads with
auditorViewingKeyand 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.