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:
aes_key = SHA256("kalo:vk:v1:" || viewing_key)
ciphertext = 0x || iv (12B) || auth_tag (16B) || encrypted_payloadAn 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.
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: ListsPrivacyRingrecords (ringAddress,mint,merkleRoot,commitmentCount,complianceMode) for anowner.getEncryptedUtxosByTags: Returns up to 100 encrypted UTXOs matching an array oftags(viewTagvalues).getShieldedTransactionsByTags: Returns up to 50SealedEscrowrecords (escrowAddress,nullifier,commitmentIn,providerCommitment,feeCommitment,state, transaction signatures) for aring.
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:
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 viewingKeyPayload | Type | Content | |
|---|---|---|---|
amountBaseUnits | string | Exact settled price in mint base units | |
feeBaseUnits | string | Protocol fee routed to the KALO launch wallet | |
requestSummary | `string \ | null` | Request summary captured at settlement |
responsePreview | `string \ | null` | Decrypted response payload |
piiStrippedHeaders | string[] | 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.