Skip to main content

Circuit artifacts loaders

This page explains how the SDK gets WASM, proving keys (zkey), and verification keys (vkey) into the prover. Three implementations cover different environments.

LocalCircuitArtifacts​

  • Where: Node-side.
  • Source: disk. You supply circuitArtifactsDir.
  • Expected layout: {dir}/{circuit}/{circuit}_js/{circuit}.wasm, {dir}/{circuit}/groth16_pkey.zkey, {dir}/{circuit}/groth16_vkey.json.
  • Use when: you are running a local Node tool, such as a CLI or a script on the user's own machine, with circuit binaries you've vendored locally. Proving still happens on that machine, so it honors client-side proving just as the browser loaders do.

FetchCircuitArtifacts (sample app, not the SDK)​

  • Where: browser.
  • Source: HTTP fetch.
  • Constructor: new FetchCircuitArtifacts(baseUrl).
  • URL composition: mirrors LocalCircuitArtifacts' path layout.
  • Use when: you serve circuits from your app's public/ (same-origin) or from a CDN or IPFS gateway.
  • Where it lives: this class is not exported from @privacy-pools-v2/sdk. The reference implementation lives in the sample app at v2-monorepo/apps/sample-web/src/FetchCircuitArtifacts.ts and implements the SDK's ICircuitArtifacts interface. To use it, copy the file into your app or write your own ICircuitArtifacts implementation against fetch.

IpfsCircuitArtifacts​

  • Where: browser or Node.
  • Source: IPFS via a configured gateway.
  • Configuration: {ipfsGatewayUrls: [...], circuitManifest: {circuit: {wasm: cid, provingKey: cid, verificationKey: cid}}, httpClient}. All three fields are required. httpClient is an IHTTPClient used to fetch binary artifacts from the gateway.
  • Caching: in-memory by CID, with concurrent fetches of the same CID coalesced.
  • Manifest: provide a populated manifest before using IPFS-backed artifacts, because placeholder manifests cannot prove.

Choosing between FetchCircuitArtifacts and IpfsCircuitArtifacts​

  • For a Vercel/Cloudflare-hosted app, FetchCircuitArtifacts pointing at an HTTPS CDN is simplest.
  • For decentralized hosting, IpfsCircuitArtifacts with a Pinata gateway and a pinned CID is the cleanest answer.
  • For local dev, FetchCircuitArtifacts pointing at /circuits (your Next.js public/) is fast.

Read-only sessions​

PoolSessionBuilder resolves circuit artifacts during .create(), even for sessions used only to discover or list notes. If you use the builder, supply artifacts. Prover-less read-only wiring is possible only with lower-level session construction, and is advanced integration work rather than a quick task. Any proving operation (deposit, transact, withdraw, ragequit) needs a real artifacts implementation.