Concepts

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:

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

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

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

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

text
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

FieldPublic on-chain ledgerPrincipal or Auditor with Viewing Key
Vault PDA and principal pubkeyVisibleVisible
Mint pubkey and note_countVisibleVisible
merkle_root and note_commitment32-byte hashes onlyMatched to decrypted note amounts and salts
Individual settlement amountHidden behind amount_commitmentDecrypted locally from encryptedReceipt
viewing_key_tag and auditor_key_tag32-byte public tags onlyUsed 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.