ZK Provers

Overview

Stealth Pool Note creation and burning require client-side generation of Groth16 zero-knowledge proofs. The SDK does not bundle a default prover — you provide one as a dependency injection. The prover ships inside @umbra-privacy/sdk/zk-prover. The standalone @umbra-privacy/web-zk-prover package has been deleted. All factories listed below wrap snarkjs and handle proving-key loading from Umbra’s CDN by default.

Quick start

Per-circuit factories are exported from @umbra-privacy/sdk/zk-prover. Pair each one with the matching high-level factory in /deposit or /burn.

import {
  getETAIntoStealthPoolNoteCreatorProver,
  getClaimReceiverClaimableUtxoIntoEncryptedBalanceProver,
} from "@umbra-privacy/sdk/zk-prover";
import { getETAIntoReceiverBurnableStealthPoolNoteCreatorFunction } from "@umbra-privacy/sdk/deposit";
import { getReceiverBurnableStealthPoolNoteIntoETABurnerFunction } from "@umbra-privacy/sdk/burn";
import { getUmbraRelayer } from "@umbra-privacy/sdk";

// 1. Create the provers (uses CDN asset provider by default).
const createProver = getETAIntoStealthPoolNoteCreatorProver();
const burnProver   = getClaimReceiverClaimableUtxoIntoEncryptedBalanceProver();

// 2. Pass them to the SDK factories.
const createNote = getETAIntoReceiverBurnableStealthPoolNoteCreatorFunction(
  { client },
  { zkProver: createProver },
);

const r = getUmbraRelayer({ apiEndpoint: "https://relayer.api.umbraprivacy.com" });
const burn = getReceiverBurnableStealthPoolNoteIntoETABurnerFunction(
  { client },
  {
    fetchBatchMerkleProof: client.fetchBatchMerkleProof!,
    zkProver: burnProver,
    relayer: {
      submitBurn:        r.submitClaim,
      pollBurnStatus:    r.pollClaimStatus,
      getRelayerAddress: r.getRelayerAddress,
    },
  },
);

Available factory functions

All factories accept an optional provider parameter of type IZkAssetProvider. When omitted, the default CDN provider is used. Creator provers (renamed in V5):

getETAIntoStealthPoolNoteCreatorProver(provider?) → IZkProverForETAIntoStealthPoolNote. Shared by both self-burnable and receiver-burnable ETA-source creators.
getATAIntoStealthPoolNoteCreatorProver(provider?) → IZkProverForATAIntoStealthPoolNote. Shared by both self-burnable and receiver-burnable ATA-source creators.

Burner provers:

getClaimSelfClaimableUtxoIntoEncryptedBalanceProver(provider?) → IZkProverForClaimSelfClaimableUtxoIntoEncryptedBalance.
getClaimReceiverClaimableUtxoIntoEncryptedBalanceProver(provider?) → IZkProverForClaimReceiverClaimableUtxoIntoEncryptedBalance.
getClaimSelfClaimableUtxoIntoPublicBalanceProver(provider?) → IZkProverForClaimSelfClaimableUtxoIntoPublicBalance.

Registration:

getUserRegistrationProver(provider?) → IZkProverForUserRegistration.

The burner prover factory names use the getClaim…ClaimableUtxo… spelling, while the creator prover factories use the Stealth Pool Note vocabulary (getETAIntoStealthPoolNoteCreatorProver, getATAIntoStealthPoolNoteCreatorProver). Both sets coexist — the naming difference is by design to match the high-level factory vocabulary.

Custom asset provider

By default, all prover factories use getCdnZkAssetProvider() to fetch proving keys from Umbra’s CDN — no configuration required. For advanced use cases, customise the asset provider.

Custom CDN URL

To load assets from a different CDN or self-hosted location, use getCdnZkAssetProvider with a custom baseUrl:

import { getCdnZkAssetProvider } from "@umbra-privacy/sdk/zk-prover/cdn";
import { getUserRegistrationProver } from "@umbra-privacy/sdk/zk-prover";

const myProvider = getCdnZkAssetProvider({
  baseUrl: "https://my-cdn.example.com/zk-assets",
});

const prover = getUserRegistrationProver(myProvider);

Fully custom provider

Implement the IZkAssetProvider interface directly:

import type {
  IZkAssetProvider,
  ZkAssetUrls,
  ZKeyType,
  ClaimVariant,
} from "@umbra-privacy/sdk/zk-prover";
import { getUserRegistrationProver } from "@umbra-privacy/sdk/zk-prover";

function createMyAssetProvider(storageBaseUrl: string): IZkAssetProvider {
  return {
    async getAssetUrls(type: ZKeyType, variant?: ClaimVariant): Promise<ZkAssetUrls> {
      const name = variant ? `${type}-${variant}` : type;
      return {
        zkeyUrl: `${storageBaseUrl}/${name}.zkey`,
        wasmUrl: `${storageBaseUrl}/${name}.wasm`,
      };
    },
  };
}

const myProvider = createMyAssetProvider("https://my-storage.example.com/zk-assets");
const prover = getUserRegistrationProver(myProvider);

The ZK prover interface

The prover-interface and result types ship at @umbra-privacy/sdk/zk-prover. See ZK Prover Interfaces for the full list. All provers return the same proof shape:

interface Groth16Proof {
  a: Groth16ProofA; // G1 point — 64 bytes (x, y uncompressed)
  b: Groth16ProofB; // G2 point — 128 bytes
  c: Groth16ProofC; // G1 point — 64 bytes
}

Web Worker pattern

Proof generation is CPU-intensive — generating a Groth16 proof takes 2-8 seconds in the browser and 1-3 seconds in Node.js. In browser applications, run the prover in a Web Worker to avoid blocking the main thread:

// prover-worker.ts
import { expose } from "comlink";
import { getETAIntoStealthPoolNoteCreatorProver } from "@umbra-privacy/sdk/zk-prover";

const prover = getETAIntoStealthPoolNoteCreatorProver();

expose(prover);

// main.ts
import { wrap } from "comlink";
import type { IZkProverForETAIntoStealthPoolNote } from "@umbra-privacy/sdk/zk-prover";

const worker   = new Worker(new URL("./prover-worker.ts", import.meta.url));
const zkProver = wrap<IZkProverForETAIntoStealthPoolNote>(worker);

const createNote = getATAIntoReceiverBurnableStealthPoolNoteCreatorFunction(
  { client },
  { zkProver },
);

comlink is a convenient library for wrapping Web Workers with a promise-based RPC interface. Any similar mechanism works.

Custom prover implementation

If the bundled prover does not fit your environment, you can implement the prover interface directly:

import type { IZkProverForETAIntoStealthPoolNote, ETAIntoStealthPoolNoteCircuitInputs } from "@umbra-privacy/sdk/zk-prover";
import type { Groth16ProofA, Groth16ProofB, Groth16ProofC } from "@umbra-privacy/sdk/types";

function createRemoteZkProver(endpoint: string): IZkProverForETAIntoStealthPoolNote {
  return {
    prove: async (inputs: ETAIntoStealthPoolNoteCircuitInputs): Promise<{
      a: Groth16ProofA;
      b: Groth16ProofB;
      c: Groth16ProofC;
    }> => {
      const response = await fetch(`${endpoint}/prove`, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify(inputs),
      });
      if (!response.ok) throw new Error(`Proving server returned ${response.status}`);
      return response.json();
    },
  };
}

A remote prover receives the circuit inputs, which include private data such as the note amount and recipient. Only use a remote prover if you fully trust the operator of the proving service.

Proof generation timing

Proof generation time varies by device and prover implementation:

WebAssembly in browser: 2–8 seconds.
Native binary (Node.js): 1–3 seconds.
Remote proving service: depends on network latency and server capacity.

Show a loading indicator while proof generation is in progress.

Circuit details

The Umbra circuits are written in Circom. The self-burnable Stealth Pool Note circuit proves:

Knowledge of the secret inputs (amount, recipient, nonce, blinding_factor) whose Poseidon hash equals a commitment in the Merkle tree.
A valid Merkle inclusion proof from that commitment to the current tree root.
The nullifier is correctly computed as Poseidon(poseidon_private_key, commitment).
The destination address matches the one embedded in the commitment.

All four facts are proven simultaneously in a single Groth16 proof, which is then verified on-chain in a single transaction.

Get Started

Concepts

Foundations

Setup

Registration

Transfer Models

Encrypted Balances

Stealth Pool

Compliance

Advanced

Migrations

Overview

Quick start

Available factory functions

Custom asset provider

Custom CDN URL

Fully custom provider

The ZK prover interface

Web Worker pattern

Custom prover implementation

Proof generation timing

Circuit details

​Overview

​Quick start

​Available factory functions

​Custom asset provider

​Custom CDN URL

​Fully custom provider

​The ZK prover interface

​Web Worker pattern

​Custom prover implementation

​Proof generation timing

​Circuit details

Overview

Quick start

Available factory functions

Custom asset provider

Custom CDN URL

Fully custom provider

The ZK prover interface

Web Worker pattern

Custom prover implementation

Proof generation timing

Circuit details