Guides

Auditor Viewing Keys

Attach a read-only auditor viewing key to a Privacy Ring, decrypt shielded notes locally, and query encrypted UTXOs by view tag.

How viewing keys work

Kalo separates spending authority from visibility. On-chain accounts store only encrypted UTXO commitments, view tags, and ciphertext notes. Plaintext amounts, request summaries, and response previews are decrypted locally using AES-256-GCM keyed from the viewing key:

text
aes_key = SHA256("kalo:vk:v1:" || viewing_key)
ciphertext = 0x || iv (12B) || auth_tag (16B) || encrypted_payload

An auditor holding a Ring's viewing key can read every shielded deposit and settlement record associated with that Ring without being able to move funds, issue mandates, or sign transactions.

Step 1: Attach an auditor key when creating a Ring

Pass auditorPubkey in POST /v1/rings/build (or fill the optional Auditor public key field in `/app`). On-chain, create_ring stores auditor_key_hash = SHA256(auditor_pubkey) and sets has_auditor = true.

ts
const res = await fetch('http://127.0.0.1:41202/v1/rings/build', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    owner: sponsorPubkey,
    mint: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
    complianceMode: 'Allowlisted',
    auditorPubkey: auditorEd25519Pubkey,
  }),
})

Step 2: Query encrypted UTXOs by view tag (SPR JSON-RPC)

Kalo exposes a Helius Solana Privacy Rings-compatible JSON-RPC endpoint at POST /v1/spr/rpc supporting three methods:

  • getUserRecords: Lists PrivacyRing records (ringAddress, mint, merkleRoot, commitmentCount, complianceMode) for an owner.
  • getEncryptedUtxosByTags: Returns up to 100 encrypted UTXOs matching an array of tags (viewTag values).
  • getShieldedTransactionsByTags: Returns up to 50 SealedEscrow records (escrowAddress, nullifier, commitmentIn, providerCommitment, feeCommitment, state, transaction signatures) for a ring.
ts
const rpcRes = await fetch('http://127.0.0.1:41202/v1/spr/rpc', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'getEncryptedUtxosByTags',
    params: { tags: ['vt_9f4a21c8'] },
  }),
})

const { result } = await rpcRes.json()

Step 3: Decrypt UTXO notes and receipts locally

Pass each encryptedNote or encryptedReceipt ciphertext to decryptWithViewingKey() from @kalo/sdk:

ts
import { decryptWithViewingKey } from '@kalo/sdk'

for (const utxo of result.utxos) {
  const plaintext = decryptWithViewingKey(utxo.encryptedNote, auditorViewingKey)
  if (!plaintext) continue
  const note = JSON.parse(plaintext)
  console.log({
    leafIndex: utxo.leafIndex,
    commitment: utxo.commitment,
    amount: note.amount,
    spent: utxo.spent,
  })
}

If the viewing key does not match or the ciphertext was modified, AES-256-GCM authentication fails and decryptWithViewingKey() returns null.

Step 4: Inspect settlements with a viewing key

When querying GET /v1/settlements or GET /v1/settlements/:address, omit the viewing key to inspect the public chain representation (viewingKeyPayload: null). Include X-Kalo-Viewing-Key in the request header (or ?viewingKey=... query parameter) to populate viewingKeyPayload:

Field in viewingKeyPayloadTypeContent
amountBaseUnitsstringExact settled price in mint base units
feeBaseUnitsstringProtocol fee routed to the KALO launch wallet
requestSummary`string \null`Request summary captured at settlement
responsePreview`string \null`Decrypted response payload
piiStrippedHeadersstring[]PII headers removed before provider dispatch

Multi-auditor compliance portals

The current build supports one optional auditor key hash per PrivacyRing. Build 3 in Kalo's road extends PrivacyRing with multi-auditor viewing-key registries (separate finance, tax, and risk roles), multi-signer allowlist governance, and local Merkle-verified CSV and JSON accounting exports.

Confidential commerce infrastructure for autonomous software.

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

Open consoleRead the docs