Protocol

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:

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

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

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

text
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

ModeOn-chain valueBehavior
Permissionless0Standard open Privacy Ring for individual sponsors and trading agents
Allowlisted1Policy-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 += amount
  • lock_sealed_402: vault_balance -= amount (reserved for SealedEscrow)
  • refund_expired_escrow: vault_balance += escrow.amount (returned on timeout)
  • unshield_withdraw: vault_balance -= amount (transferred out to recipient_token_account)

All arithmetic uses checked u64 operations (checked_add, checked_sub) and reverts with MathOverflow (6003) or InsufficientShieldedBalance (6012) on violation.

Confidential commerce infrastructure for autonomous software.

Shielded treasuries, scoped mandates, and receipt-bound HTTP 402 settlement on Solana L1.

Open consoleRead the docs