SDK Quickstart

npm install @permissionless-technologies/upp-sdk viem wagmi

import { getDeploymentOrThrow } from '@permissionless-technologies/upp-sdk'

const deployment = getDeploymentOrThrow(11155111)
// {
//   UniversalPrivatePool, ASPRegistryHub, UPPSwapModule,
//   implementations: { … },
//   verifiers: { Transfer, Merge, Withdraw, JoinSplit, MergeTransfer2x2, MergeTransfer4x2 },
//   TestToken, TestToken2,
//   chainId: 11155111,
//   deployBlock: 10846101,
//   deployTimestamp,
// }

import {
  UPPAccountProvider, useUPPAccount,
  useShield, usePoolTransfer, useWithdraw,
} from '@permissionless-technologies/upp-sdk/react'
import {
  encodeShieldTxFromBuildData,
  encodeTransferTxFromBuildData,
  encodeWithdrawTxFromBuildData,
  getDeploymentOrThrow,
} from '@permissionless-technologies/upp-sdk'
import {
  useAccount, useChainId, usePublicClient,
  useSignTypedData, useWriteContract,
} from 'wagmi'
import { parseUnits } from 'viem'

const { UniversalPrivatePool: poolAddress, UPPSwapModule: swapModuleAddress, TestToken: UPD, deployBlock } =
  getDeploymentOrThrow(11155111)

function App({ children }: { children: React.ReactNode }) {
  const { address } = useAccount()
  const chainId = useChainId()
  const publicClient = usePublicClient()
  const { signTypedDataAsync } = useSignTypedData()

  return (
    <UPPAccountProvider
      ethAddress={address}
      chainId={chainId}
      publicClient={publicClient}
      signTypedData={signTypedDataAsync}
      indexerConfig={{ contractAddress: poolAddress, swapModuleAddress, fromBlock: deployBlock }}
      activeProofSystem="snark"
    >
      {children}
    </UPPAccountProvider>
  )
}

function PrivacyPanel() {
  const { address } = useAccount()
  const { writeContractAsync } = useWriteContract()
  const { isSetup, balance, addNote, markNoteSpent, connect } = useUPPAccount()

  const shield = useShield({ poolAddress, tokenAddress: UPD })
  const xfer = usePoolTransfer({ poolAddress, tokenAddress: UPD, publicClient: usePublicClient() })
  const wdraw = useWithdraw({ poolAddress, tokenAddress: UPD, publicClient: usePublicClient() })

  if (!isSetup) return <button onClick={() => connect()}>Unlock privacy layer</button>

  const onShield = async () => {
    const d = await shield.build({ amount: parseUnits('100', 18), originAddress: address! })
    // ERC20 approve to the pool is yours to do
    await writeContractAsync({ address: poolAddress, ...encodeShieldTxFromBuildData(d) })
    addNote(d.noteData.note)
  }

  const onTransfer = async (recipient: string) => {
    const d = await xfer.build({ amount: parseUnits('10', 18), recipient })
    await writeContractAsync({ address: poolAddress, ...encodeTransferTxFromBuildData(d) })
    markNoteSpent(d.spentNote.commitment)
    addNote(d.changeNoteData.note)
  }

  const onRagequit = async () => {
    const d = await wdraw.build({
      amount: parseUnits('50', 18),
      recipient: address!,
      isRagequit: true,
    })
    await writeContractAsync({ address: poolAddress, ...encodeWithdrawTxFromBuildData(d) })
    markNoteSpent(d.spentNote.commitment)
    if (d.changeNoteData) addNote(d.changeNoteData.note)
  }

  return (
    <div>
      <p>Private balance: {balance.toString()} (wei)</p>
      <button onClick={onShield}>Shield 100</button>
      <button onClick={() => onTransfer('0zk1…')}>Transfer 10</button>
      <button onClick={onRagequit}>Ragequit 50 (no ASP)</button>
    </div>
  )
}

import {
  encodeShieldTx,
  createNote, encryptNote,
  generateStealthAddress,
  deriveDualKeysFromSignature,
  getDeploymentOrThrow,
} from '@permissionless-technologies/upp-sdk'

const { UniversalPrivatePool: poolAddress, TestToken: token } = getDeploymentOrThrow(11155111)

// 1. Derive keys from a one-shot EIP-712 signature (same input → same keys, every time)
const signature = await walletClient.signTypedData(EIP712_DOMAIN_AND_MESSAGE)
const { snark } = await deriveDualKeysFromSignature(signature)

// 2. Build a shielded note for self
const { stealthAddress, ephemeralPubKey } = generateStealthAddress(snark.metaAddress)
const note = createNote({ amount: 100n * 10n**18n, token, origin: depositor })
const encryptedNote = await encryptNote(note, ephemeralPubKey)

// 3. Encode + submit
const tx = encodeShieldTx({
  token: note.token,
  amount: note.amount,
  ownerHash: note.ownerHash,
  blinding: note.blinding,
  encryptedNote,
})
await walletClient.writeContract({ address: poolAddress, ...tx })

import {
  startASPService,
  SubsquidEventSource,
  SanctionsGate,
} from '@permissionless-technologies/upc-asp-whitelist'
import { parseAbiItem } from 'viem'

const shieldedEvent = parseAbiItem(
  'event Shielded(address indexed token, address indexed depositor, bytes32 indexed commitment, uint256 leafIndex, bytes encryptedNote)'
)

startASPService({
  rpcUrl: process.env.RPC_URL!,
  registryAddress: '0xB71129021E6f1C45D206aa15233d9B1DcEfdeb97',
  operatorPrivateKey: process.env.OPERATOR_PRIVATE_KEY as `0x${string}`,
  chainId: 11155111,
  port: 3001,
  eventSource: new SubsquidEventSource({
    archive: 'https://v2.archive.subsquid.io/network/ethereum-sepolia',
    apiKey: process.env.SQD_KEY,            // ← required since mid-2026
    rpcUrl: process.env.RPC_URL!,
    watchAddress: '0xCDA138FFd4789670e0034aE30946b8873bb51740',
    event: shieldedEvent,
    addressTopicIndex: 2,
    deployBlock: 10846101n,
    finalityConfirmation: 2,
  }),
  gate: new SanctionsGate({ blocklist: [/* OFAC etc. */] }),
})