SDK Quickstart

npm install @permissionless-technologies/upp-sdk

import { createUPPClient } from '@permissionless-technologies/upp-sdk'
import { createWalletClient, createPublicClient, http } from 'viem'
import { sepolia } from 'viem/chains'

const publicClient = createPublicClient({ chain: sepolia, transport: http() })
const walletClient = createWalletClient({ chain: sepolia, transport: http() })

// Initialize UPP client — keys derive from wallet signature (no extra seed phrases)
const upp = await createUPPClient({ publicClient, walletClient })

import { parseUnits } from 'viem'

// Approve UPP to spend your tokens
await upp.approve({ token: UPD_TOKEN_ADDRESS, amount: parseUnits('1000', 18) })

// Shield tokens — creates an encrypted note in the shared pool
const { commitment } = await upp.shield({
  token: UPD_TOKEN_ADDRESS,
  amount: parseUnits('1000', 18),
})

console.log('Shielded! Note commitment:', commitment)

// Get recipient's stealth meta-address (they share this publicly)
const recipientAddress = '0zk1sepolia1...'

// Transfer — proves you own the note without revealing which one
const { recipientCommitment, changeCommitment } = await upp.transfer({
  amount: parseUnits('500', 18),
  to: recipientAddress,
})

// Recipient gets 500 UPD, you get a change note

// Scans encrypted notes, decrypts yours using your viewing key
const notes = await upp.scan()

const balance = notes
  .filter(n => n.token === UPD_TOKEN_ADDRESS && !n.spent)
  .reduce((sum, n) => sum + n.amount, 0n)

console.log('Private balance:', balance)

const { txHash } = await upp.unshield({
  amount: parseUnits('200', 18),
  to: '0xRecipientAddress',
  aspId: 1n, // Which ASP to use for the compliance proof
})

import { UPPAccountProvider, useUPPAccount } from '@permissionless-technologies/upp-sdk/react'

function App() {
  return (
    <UPPAccountProvider>
      <PrivateBalance />
    </UPPAccountProvider>
  )
}

function PrivateBalance() {
  const { notes, isScanning, shield, transfer, unshield } = useUPPAccount()

  const balance = notes
    ?.filter(n => !n.spent)
    .reduce((sum, n) => sum + n.amount, 0n) ?? 0n

  if (isScanning) return <div>Scanning notes...</div>

  return (
    <div>
      <p>Private balance: {balance.toString()}</p>
      <button onClick={() => shield({ token: UPD_TOKEN_ADDRESS, amount: parseUnits('100', 18) })}>
        Shield 100 UPD
      </button>
    </div>
  )
}

// Generate your stealth meta-address to share publicly
const myStealthAddress = upp.getStealthMetaAddress()

// Share specific notes only (Tier 1 — minimal disclosure)
const auditExport = await upp.exportViewingKeys({
  notes: [note1, note2],
})

// The export includes a nonce chain for completeness verification
// and an EIP-712 signed note count — auditors can verify nothing is hidden

const notes = await upp.getNotes()
// Each note: { amount, token, commitment, spent, leafIndex }

try {
  await upp.transfer({ amount, to })
} catch (e) {
  if (e.code === 'INSUFFICIENT_BALANCE') {
    // Not enough private balance
  } else if (e.code === 'ASP_PROOF_FAILED') {
    // Origin not in any ASP allowlist — may need to ragequit
  } else if (e.code === 'PROOF_GENERATION_FAILED') {
    // ZK proof failed — check inputs
  }
}