Guides

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

  1. Navigate to Rings & Shielded Treasury and connect your wallet.
  2. Click Create Ring.
  3. Select the settlement mint (USDC, SOL, or any SPL / Token-2022 mint address).
  4. Choose a compliance mode: Permissionless (0) or Allowlisted (1).
  5. Optionally enter an auditor public key. The program stores SHA256(auditor_pubkey) in auditor_key_hash and sets has_auditor = true.
  6. 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:

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',
    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
FieldTypeConstraints
ownerBase58 addressSigner and Ring owner
mintBase58 addressSPL or Token-2022 mint
symbolstring (optional)1 to 16 characters; defaults to SOL for native mint, otherwise USDC
decimalsnumber (optional)0 to 18; defaults to 9 for SOL, 6 otherwise
complianceMode`'Permissionless' \'Allowlisted'`Stored on-chain as 0 or 1
auditorPubkeyBase58 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:

ts
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,
  }),
})
TIPKeep 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:

ts
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

ErrorCauseResolution
InvalidComplianceMode (6001)compliance_mode outside {0, 1}Use 'Permissionless' (0) or 'Allowlisted' (1)
ZeroAmount (6002)amount == 0Pass a positive base-unit integer
InsufficientShieldedBalance (6012)Unshield amount exceeds privacy_ring.vault_balanceShield additional funds or lower the withdrawal amount
NULLIFIER_SPENT (HTTP 409)Nullifier already initialized in NullifierSetDerive a fresh nullifier for an unspent commitment

Next step

Delegate bounded spending authority from your funded Ring in Issuing Agent Mandates.

Confidential commerce infrastructure for autonomous software.

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

Open consoleRead the docs