Shielded UTXOs & Privacy Rings
UTXO Merkle commitments, single-use nullifiers, balance conservation, compliance modes, and view-tag indexing.
Ring vault and commitment tree
A PrivacyRing pairs a standard SPL TokenAccount (ring_vault, owned by the privacy_ring PDA) with an append-only commitment Merkle root (merkle_root).
At create_ring, the program initializes the root:
merkle_root_0 = SHA256("kalo:ring:init" || privacy_ring_pubkey)Each shield_deposit transfers amount from owner_token_account into ring_vault, rolls the Merkle root forward, and increments commitment_count:
merkle_root_{n+1} = SHA256("kalo:spr:leaf" || merkle_root_n || commitment)The ShieldDepositEvent records ring, owner, commitment, view_tag (8 bytes), leaf_index, and the updated merkle_root. The deposit amount is not included in the event payload.
Commitments and blinding
In @kalo/sdk, createCommitment(amountBaseUnits, blindingHex?) computes a 32-byte blinded commitment using a 32-byte random blinding factor:
commitment = SHA256("kalo:spr:commitment:v1" || amount_decimal_utf8 || blinding_32B)On mainnet Helius Solana Privacy Rings, single-transaction shielded transfers verify ~192-byte Groth16 proofs in ~1,400 compute units. Kalo's localnet adapter mirrors the same commitment, view-tag, and JSON-RPC surface and switches to live Helius v1/spr/* endpoints via HELIUS_SPR_URL.
Nullifier replay protection
Every spend from a PrivacyRing (lock_sealed_402 or unshield_withdraw) requires a 32-byte nullifier derived from the commitment and owner/agent key (deriveNullifier()).
On-chain, the instruction initializes a NullifierSet PDA at:
PDA = find_program_address(["nullifier", privacy_ring, nullifier], kalo_protocol)NullifierSet stores ring, nullifier, spent_slot, and bump (81 bytes total). Attempting to reuse a nullifier fails at Anchor's init constraint before any token movement occurs.
Compliance modes
| Mode | On-chain value | Behavior |
|---|---|---|
Permissionless | 0 | Standard open Privacy Ring for individual sponsors and trading agents |
Allowlisted | 1 | Policy-gated Ring intended for institutional treasuries and auditor-reviewed flows |
Both modes support an optional auditor_key_hash ([u8; 32], paired with has_auditor: bool). Setting an auditor key does not grant spending rights; it commits the auditor's read-only identity on-chain while decryption stays local under AES-256-GCM.
View-tag indexing
Scanning every encrypted UTXO across a busy Ring wastes bandwidth. Each shield_deposit tags its commitment with an 8-byte view_tag. Clients and auditors query POST /v1/spr/rpc with getEncryptedUtxosByTags to fetch only ciphertexts matching their derived view tags, then decrypt locally with decryptWithViewingKey().
Balance conservation
privacy_ring.vault_balance tracks the available shielded balance inside ring_vault:
shield_deposit:vault_balance += amountlock_sealed_402:vault_balance -= amount(reserved forSealedEscrow)refund_expired_escrow:vault_balance += escrow.amount(returned on timeout)unshield_withdraw:vault_balance -= amount(transferred out torecipient_token_account)
All arithmetic uses checked u64 operations (checked_add, checked_sub) and reverts with MathOverflow (6003) or InsufficientShieldedBalance (6012) on violation.