Creating a Privacy Ring
Create Permissionless or Allowlisted Rings for SOL, USDC, or SPL / Token-2022 mints, shield funds, and unshield back to a public account.
Prerequisites
- A Solana wallet holding the SPL token you want to shield (for example USDC or wrapped SOL) plus SOL for account rent and transaction fees.
- Access to the Kalo console at `/app` or the REST API (
POST /v1/rings/build).
Step 1: Create a Privacy Ring
A PrivacyRing PDA is derived from ["privacy_ring", owner, ring_id.to_le_bytes()] and owns a dedicated ring_vault token account derived from ["ring_vault", privacy_ring].
In the web console
- Navigate to Rings & Shielded Treasury and connect your wallet.
- Click Create Ring.
- Select the settlement mint (USDC, SOL, or any SPL / Token-2022 mint address).
- Choose a compliance mode:
Permissionless(0) orAllowlisted(1). - Optionally enter an auditor public key. The program stores
SHA256(auditor_pubkey)inauditor_key_hashand setshas_auditor = true. - Confirm the transaction in your wallet.
Via the REST API
Build an unsigned v0 create_ring transaction, sign it with the owner wallet, and submit it through /v1/transactions/submit:
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',
symbol: 'USDC',
decimals: 6,
complianceMode: 'Permissionless',
auditorPubkey: auditorPubkey, // optional
}),
})
const built = await res.json()
// built.transactionBase64 -> sign with wallet
// built.derivedAddresses.ringAddress -> new PrivacyRing PDA| Field | Type | Constraints | |
|---|---|---|---|
owner | Base58 address | Signer and Ring owner | |
mint | Base58 address | SPL or Token-2022 mint | |
symbol | string (optional) | 1 to 16 characters; defaults to SOL for native mint, otherwise USDC | |
decimals | number (optional) | 0 to 18; defaults to 9 for SOL, 6 otherwise | |
complianceMode | `'Permissionless' \ | 'Allowlisted'` | Stored on-chain as 0 or 1 |
auditorPubkey | Base58 address (optional) | Hashed to auditor_key_hash on-chain |
Step 2: Shield funds into encrypted UTXOs
Depositing moves tokens from owner_token_account into ring_vault, rolls privacy_ring.merkle_root = SHA256("kalo:spr:leaf" || prev_root || commitment), and increments commitment_count.
You can generate the commitment and encrypted note locally using @kalo/sdk before calling POST /v1/rings/:address/shield/build:
import { createCommitment, encryptWithViewingKey } from '@kalo/sdk'
const amountBaseUnits = 500_000_000n // 500 USDC (6 decimals)
const { commitment, blinding } = createCommitment(amountBaseUnits)
const encryptedNoteHex = encryptWithViewingKey(
JSON.stringify({ amount: amountBaseUnits.toString(), blinding }),
sponsorViewingKey,
)
const buildRes = await fetch(`http://127.0.0.1:41202/v1/rings/${ringAddress}/shield/build`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
owner: sponsorPubkey,
amountBaseUnits: amountBaseUnits.toString(),
commitmentHex: commitment,
encryptedNoteHex,
}),
})blinding and your viewing key in local storage or your secret manager. The chain and indexer store only commitment, view_tag, and encryptedNote.Step 3: Inspect shielded UTXOs locally
Query GET /v1/rings/:address without a viewing key to see public ciphertext (amountPlaintext: null). Pass X-Kalo-Viewing-Key (or toggle Viewing key in /app) to decrypt note amounts locally.
Step 4: Unshield back to a public token account
To move funds out of ring_vault back to any SPL token account of the same mint, derive a fresh 32-byte nullifier and submit unshield_withdraw via POST /v1/rings/:address/unshield/build:
import { deriveNullifier } from '@kalo/sdk'
const nullifierHex = deriveNullifier(commitment, sponsorPubkey)
const res = await fetch(`http://127.0.0.1:41202/v1/rings/${ringAddress}/unshield/build`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
owner: sponsorPubkey,
recipient: recipientWalletPubkey,
nullifierHex,
amountBaseUnits: '100000000', // 100 USDC
}),
})On-chain, unshield_withdraw initializes a NullifierSet PDA (["nullifier", privacy_ring, nullifier]), deducts amount from privacy_ring.vault_balance, transfers tokens from ring_vault to recipient_token_account signed by the privacy_ring PDA, and emits UnshieldWithdrawEvent.
Common failures
| Error | Cause | Resolution |
|---|---|---|
InvalidComplianceMode (6001) | compliance_mode outside {0, 1} | Use 'Permissionless' (0) or 'Allowlisted' (1) |
ZeroAmount (6002) | amount == 0 | Pass a positive base-unit integer |
InsufficientShieldedBalance (6012) | Unshield amount exceeds privacy_ring.vault_balance | Shield additional funds or lower the withdrawal amount |
NULLIFIER_SPENT (HTTP 409) | Nullifier already initialized in NullifierSet | Derive a fresh nullifier for an unspent commitment |
Next step
Delegate bounded spending authority from your funded Ring in Issuing Agent Mandates.