Ring Vaults
How Tova Shielded Ring Vaults hold SOL and SPL assets behind encrypted UTXO commitments, Merkle roots, and nullifier PDAs.
Overview
A Shielded Ring Vault (RingVault) is a principal-owned on-chain treasury PDA that stores funds in a program-controlled escrow account (vault_escrow) while tracking encrypted note commitments in a rolling Merkle root. Agents never receive direct custody of vault funds; they spend only through a Shielded Mandate attached to the vault.
Each vault is uniquely addressed per principal and asset mint:
RingVault PDA: ["ring_vault", principal_pubkey, mint_pubkey]
Vault Escrow PDA: ["vault_escrow", ring_vault_pubkey]Open-mint asset model
Tova accepts SOL (So11111111111111111111111111111111111111112), USDC (EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v), and any SPL or Token-2022 mint. A single principal can maintain separate vaults per mint because mint is part of the RingVault PDA seeds.
Note commitments and Merkle root
When a principal deposits funds via deposit_shielded, the client derives a 32-byte note commitment using domain-separated SHA-256 over the amount in base units (u64 little-endian) and a 32-byte random salt:
amount_commitment = SHA256("TOVA_PRIVACY_RING_V1" || amount_u64_le || salt_32)On-chain, deposit_shielded updates the vault's merkle_root and increments note_count:
next_root = SHA256("TOVA_MERKLE_NODE" || vault.merkle_root || note_commitment)The encrypted note ciphertext (AES-256-GCM under the principal's Viewing Key) is stored off-chain in the vault's note list so the principal can reconstruct note values and salts locally without exposing them on the public ledger.
Nullifier PDAs and double-spend prevention
Spending a note through withdraw_shielded or open_settlement requires initializing a NullifierRecord PDA derived from the vault address and the 32-byte nullifier_hash:
NullifierRecord PDA: ["nullifier", ring_vault_pubkey, nullifier_hash_32]In @tova/sdk, the nullifier is derived deterministically from the note commitment, the spending key, and the settlement ID:
nullifier_hash = SHA256("TOVA_NULLIFIER_V1" || note_commitment_32 || agent_pubkey_32 || settlement_id_u64_le)Because Solana account initialization (init) fails unconditionally if the PDA already exists, any attempt to replay a spent note or reuse a nullifier reverts at runtime.
Public ledger vs. Viewing Key visibility
| Field | Public on-chain ledger | Principal or Auditor with Viewing Key |
|---|---|---|
| Vault PDA and principal pubkey | Visible | Visible |
Mint pubkey and note_count | Visible | Visible |
merkle_root and note_commitment | 32-byte hashes only | Matched to decrypted note amounts and salts |
| Individual settlement amount | Hidden behind amount_commitment | Decrypted locally from encryptedReceipt |
viewing_key_tag and auditor_key_tag | 32-byte public tags only | Used to locate matching encrypted payloads |
Viewing key tags
Every RingVault stores a mandatory 32-byte viewing_key_tag for the principal and an optional auditor_key_tag for read-only selective disclosure. Neither tag reveals the secret viewing key; tags identify which key can decrypt a vault's notes and settlement receipts.
See Viewing Keys & Disclosure for encryption, decryption, and commitment verification steps, and Create a Ring Vault to fund your first vault.