Skip to main content

Overview for AI agents

You're reading this because you're an AI agent (Claude, an MCP client, an LLM-driven coding tool) that needs to integrate with Privacy Pools v2. This page tells you where to start and what to read in what order so you can answer "can I do X with this?" reliably.

If you have zero context​

Read in this order:

  1. What is Privacy Pools v2?: a 5 minute orientation.
  2. Notes: the unit of value. Skipping this guarantees you'll get the data model wrong.
  3. Keys: the three-key model. The most-likely-to-be-misunderstood part of the API.
  4. Quickstart: actual code that runs.

If you've been asked to build something specific​

Skip to the Capabilities tree in the sidebar. Each capability page is shaped like a card you can cite:

  • What this lets you do answers "can the SDK do X?"
  • Constraints & limits answers "what could go wrong?"
  • What it unlocks next answers "what else does this connect to?"
  • How to use it answers "what's the exact code?"
  • Behind the scenes answers "what's the actual SDK call?"

The three flows you'll need most​

  1. Deposit: most apps need to put funds in.
  2. Discover notes: every read flow starts here.
  3. Private transfer: the central spend operation.

Things that look like API quirks but are real​

  • Token ID casing. Token IDs may be checksummed or lowercase. Use consistent casing when filtering local notes.
  • Processor is route-specific. A mismatched submitter reverts with PoolVault_InvalidProcessor, while payload changes after proving revert with PoolVault_ProofContextMismatch.
  • 5×5 circuit cap. Transact has no 5×6, no 6×6. Spend allocations must respect this.
  • Label-aware output count. Each distinct deposit label in inputs adds 2 outputs.
  • Quote expiry is short. Slow proof generation can outlast a quote.
  • Deployment set matters. The SDK, circuits, and on-chain verifier must all match. Mixing deployment sets silently produces invalid proofs.

Failure modes you'll see in chat with users​

See Failure modes for the curated list. The big four are:

  • RecipientViewingKeyUnregistered fires when the recipient has no registered viewing key. Pass allowOutOfBandFallback: true inside recipientDiscoveryData to deliver out-of-band instead.
  • PoolVault_InvalidTransactProof: deployment-set mismatch between local zkeys and the deployed verifier.
  • PoolVault_NullifierAlreadySpent: local state drift. Verify against chain.
  • InvalidBuilderConfig: required string field is undefined. Log the full issues array to find which.

Where to find canonical truth​