Circuit Setup

This guide covers downloading and testing zERC20 circuit artifacts using the zerc20-circuit-setup CLI tool.

Why You Need Circuit Artifacts

Circuit artifacts are required for:

• Running the Indexer: The indexer uses these artifacts to generate Nova proofs for transfer root transitions
• Running the Decider Prover: The decider-prover uses these artifacts to finalize Nova proofs into Decider proofs for on-chain verification
• CLI Proof Generation: The CLI uses these artifacts to generate withdrawal proofs (both Nova and Groth16) and Proof of Innocence IVC proofs

Without these artifacts, you cannot run the indexer, decider-prover, or generate proofs using the CLI.

The full artifact set can include:

• root_* for transfer-root proving
• withdraw_local_* and withdraw_global_* for teleport proofs
• proof_of_innocence_nova_pp.bin and proof_of_innocence_nova_vp.bin for CLI Proof of Innocence generation and verification
• proof_of_innocence_decider_pp.bin and proof_of_innocence_decider_vp.bin for decider-prover deployments that explicitly enable this circuit

The currently published official versions listed below do not include the proof_of_innocence_* files. They are sufficient for withdrawal, indexer, and decider-prover flows that use the published root and withdrawal circuits, but they cannot be used for zerc20-cli proof-of-innocence generate.

Official Manifest Digests

Always verify that the manifest digest displayed during download matches the official value.

Proof of Innocence requires an artifact version whose manifest includes proof_of_innocence_nova_pp.bin and proof_of_innocence_nova_vp.bin. No official published version in the table below includes those files yet. Until a POI-enabled artifact version and manifest digest are published here, generate the circuit artifacts locally before using the Proof of Innocence CLI commands.

Version	Manifest Digest	Proof of Innocence
1.0.0	f8181f89d502cd5bebc4445c4305c6c692f92deb202a18ce5d7c41694b10a7a4	Not included
1.1.0	f22882b901ac1585f665f3aa7c812dc688a0cc08d91f84c2af3c390448a85373	Not included

Installation

# Clone the repository
git clone https://github.com/zerc20io/zERC20.git
cd zERC20

# Install the CLI
cargo install --path circuit-setup

Configuration

Set environment variables or use a .env file.

# Copy the example environment file
cp circuit-setup/.env.example circuit-setup/.env

Contents of .env.example:

# Artifact version
ARTIFACTS_VERSION=<ARTIFACTS_VERSION>

# Local directory for circuit artifacts
NOVA_ARTIFACTS_DIR=../nova_artifacts

# Base URL for download (public HTTP/HTTPS)
ARTIFACTS_BASE_URL=https://zerc20-prod-public-uploads.s3.ap-southeast-1.amazonaws.com/circuit-setup

# Logging level (error, warn, info, debug, trace)
RUST_LOG=info

Commands

Download

Download circuit artifacts from a public URL and automatically verify SHA256 hashes.

zerc20-circuit-setup download --version <ARTIFACTS_VERSION>

Or specify the URL explicitly:

zerc20-circuit-setup download \
  --version <ARTIFACTS_VERSION> \
  --base-url https://zerc20-prod-public-uploads.s3.ap-southeast-1.amazonaws.com/circuit-setup \
  --artifacts-dir ./nova_artifacts

Option	Environment Variable	Description
--version	ARTIFACTS_VERSION	Version to download
--base-url	ARTIFACTS_BASE_URL	Public URL for artifacts
--artifacts-dir	NOVA_ARTIFACTS_DIR	Local output directory

Test

Test downloaded artifacts by generating and verifying dummy proofs.

zerc20-circuit-setup test --artifacts-dir ./nova_artifacts

Proof of Innocence

The download command only enables Proof of Innocence when the selected manifest includes proof_of_innocence_nova_pp.bin and proof_of_innocence_nova_vp.bin. The currently published 1.0.0 and 1.1.0 manifests do not include them, so Proof of Innocence currently requires locally generated artifacts:

cargo run --release --bin generate_circuit_artifacts

Then point the CLI at the directory that contains the generated proof_of_innocence_nova_pp.bin and proof_of_innocence_nova_vp.bin files:

zerc20-cli proof-of-innocence generate \
  --nova-artifacts-dir ./nova_artifacts \
  --recipient <GENERAL_RECIPIENT_HASH> \
  --ofac-root <OFAC_TREE_ROOT> \
  --transfer-root <TRANSFER_TREE_ROOT> \
  --transfers-file ./transfers.json \
  --exclusion-proofs-file ./exclusion_proofs.json \
  --output ./innocence_proof.bin

zerc20-cli proof-of-innocence verify \
  --nova-artifacts-dir ./nova_artifacts \
  --proof ./innocence_proof.bin \
  --recipient <GENERAL_RECIPIENT_HASH> \
  --total-teleported <TOTAL_VALUE> \
  --ofac-root <OFAC_TREE_ROOT> \
  --transfer-root <TRANSFER_TREE_ROOT>

More Information

See the README for full usage instructions.