Prover CLI

Advanced command-line interface for zero-knowledge proof generation with ZKVAULT.

Basic Proving Workflow

Generate Proof from Circuit

zkvault prove \
  --circuit ./circuits/my_circuit.circom \
  --witness ./witnesses/input.json \
  --output ./proofs/proof.json

# With verbose output
zkvault prove \
  --circuit ./circuits/my_circuit.circom \
  --witness ./witnesses/input.json \
  --output ./proofs/proof.json \
  --verbose

# Output:
# [1/5] Loading circuit...
# [2/5] Generating witness... (2.3s)
# [3/5] Computing proof... (15.7s)
# [4/5] Compressing proof... (0.8s)
# [5/5] Writing output...
# ✓ Proof generated successfully
# Size: 256 bytes
# Public inputs: [123, 456, 789]

Interactive Proving

# Start interactive prover session
zkvault prove --interactive

# Interactive prompts:
# ? Select circuit file: ./circuits/my_circuit.circom
# ? Select witness file: ./witnesses/input.json
# ? Use GPU acceleration? Yes
# ? Output format: json
# 
# Generating proof...
# ✓ Proof complete (18.2s)

Advanced Proving Options

Backend Selection

# Use native CPU backend (default)
zkvault prove --backend native --circuit circuit.circom --witness input.json

# Use GPU backend (CUDA)
zkvault prove --backend gpu --circuit circuit.circom --witness input.json

# Use WebAssembly backend
zkvault prove --backend wasm --circuit circuit.circom --witness input.json

# Specify GPU device
zkvault prove \
  --backend gpu \
  --gpu-device 0 \
  --circuit circuit.circom \
  --witness input.json

Parallel Proving

# Prove multiple witnesses in parallel
zkvault prove-batch \
  --circuit ./circuits/my_circuit.circom \
  --witnesses ./witnesses/*.json \
  --output-dir ./proofs/ \
  --workers 8

# Output:
# Processing 24 witnesses with 8 workers...
# [████████████████████] 24/24 (100%)
# ✓ All proofs generated in 142.5s
# Average time per proof: 5.9s

Recursive Proving

# Generate recursive proof from multiple proofs
zkvault prove-recursive \
  --proofs ./proofs/proof_*.json \
  --circuit ./circuits/recursive_verifier.circom \
  --output ./proofs/recursive_proof.json

# Example: Aggregate 10 proofs into 1
zkvault prove-recursive \
  --proofs proof_1.json proof_2.json ... proof_10.json \
  --compression-level high \
  --output aggregated.json

# Output:
# Aggregating 10 proofs...
# Input size: 2,560 bytes (10 × 256 bytes)
# Output size: 288 bytes
# Compression ratio: 8.9x

Witness Generation

Generate Witness from Input

# Generate witness from JSON input
zkvault witness \
  --circuit ./circuits/my_circuit.circom \
  --input ./inputs/values.json \
  --output ./witnesses/witness.wtns

# Input file (values.json):
{
  "a": "123",
  "b": "456",
  "c": "789"
}

# Generate witness from command-line args
zkvault witness \
  --circuit circuit.circom \
  --args '{"a": 123, "b": 456}' \
  --output witness.wtns

Witness Validation

# Validate witness satisfies circuit constraints
zkvault witness validate \
  --circuit circuit.circom \
  --witness witness.wtns

# Output:
# ✓ Witness is valid
# Constraints satisfied: 15,234 / 15,234
# Public inputs: [123, 456, 789]
# Private inputs: 42

Circuit Management

Compile Circuit

# Compile Circom circuit
zkvault circuit compile \
  --source ./circuits/my_circuit.circom \
  --output ./compiled/ \
  --optimization O2

# Options:
# --optimization: O0 (none), O1 (basic), O2 (aggressive)
# --prime: bn128, bls12381
# --protocol: groth16, plonk, halo2

# Output:
# Compiling my_circuit.circom...
# Constraints: 15,234
# Public inputs: 3
# Private inputs: 42
# ✓ Circuit compiled successfully
# Output: ./compiled/my_circuit.r1cs

Circuit Information

# Get circuit statistics
zkvault circuit info ./circuits/my_circuit.circom

# Output:
# Circuit: my_circuit
# Constraints: 15,234
# Public inputs: 3
# Private inputs: 42
# Wires: 15,279
# Labels: 15,237
# 
# Constraint breakdown:
#   Linear: 12,450 (81.7%)
#   Quadratic: 2,784 (18.3%)
# 
# Estimated proving time:
#   CPU: ~12s
#   GPU: ~3s

Setup Ceremony

# Generate proving and verification keys
zkvault setup \
  --circuit ./compiled/my_circuit.r1cs \
  --output-dir ./keys/ \
  --protocol groth16 \
  --entropy-source /dev/urandom

# Output:
# Running trusted setup...
# [████████████████████] 100%
# ✓ Setup complete
# 
# Files generated:
#   ./keys/proving_key.json (8.2 MB)
#   ./keys/verification_key.json (1.4 KB)
# 
# Verification key hash:
#   0x3f7a8c...92d4e1

# Participate in multi-party setup
zkvault setup contribute \
  --phase1 ./ceremony/phase1.params \
  --output ./ceremony/my_contribution.params \
  --entropy "my secret random string"

# Verify contribution
zkvault setup verify \
  --phase1 ./ceremony/phase1.params \
  --contribution ./ceremony/my_contribution.params

Proof Optimization

Compression

# Compress proof for on-chain storage
zkvault compress \
  --proof ./proofs/proof.json \
  --output ./proofs/proof_compressed.bin \
  --level high

# Compression levels: low, medium, high, max
# 
# Output:
# Original size: 768 bytes
# Compressed size: 256 bytes
# Compression ratio: 3.0x
# 
# Note: Verification time increases with compression level

Proof Serialization

# Convert proof to different formats
zkvault proof convert \
  --input proof.json \
  --output proof.bin \
  --format binary

# Supported formats: json, binary, hex, base64

# Convert to Solana-compatible format
zkvault proof solana-format \
  --input proof.json \
  --output proof_solana.bin

# Output optimized for Solana BPF:
# - Packed binary format
# - Little-endian encoding
# - Minimized size (256 bytes for Groth16)

Benchmarking

Benchmark Proving Performance

# Run proving benchmark
zkvault benchmark prove \
  --circuit circuit.circom \
  --witness witness.json \
  --iterations 10

# Output:
# Running 10 iterations...
# 
# Results:
#   Mean: 12.3s
#   Median: 12.1s
#   Std dev: 0.8s
#   Min: 11.2s
#   Max: 14.1s
# 
# Breakdown:
#   Witness generation: 2.1s (17%)
#   Proof computation: 9.4s (76%)
#   Compression: 0.8s (7%)

# Compare backends
zkvault benchmark compare \
  --circuit circuit.circom \
  --witness witness.json \
  --backends native,gpu,wasm

# Output:
# Backend    | Time    | Speedup
# -----------|---------|--------
# native     | 12.3s   | 1.0x
# gpu        | 3.2s    | 3.8x
# wasm       | 18.7s   | 0.7x

Debugging

Trace Circuit Execution

# Run circuit with debug tracing
zkvault debug \
  --circuit circuit.circom \
  --witness witness.json \
  --trace-level verbose

# Output shows intermediate signal values:
# Signal 'a': 123
# Signal 'b': 456
# Signal 'intermediate_1': 56088
# Signal 'c': 789
# Constraint 1: 123 * 456 === 56088 ✓
# Constraint 2: 56088 - 789 === 55299 ✓
# ...

# Export trace to file
zkvault debug \
  --circuit circuit.circom \
  --witness witness.json \
  --export-trace trace.json

Constraint Analysis

# Analyze constraint satisfiability
zkvault analyze constraints \
  --circuit circuit.circom \
  --witness witness.json

# Output:
# Total constraints: 15,234
# Satisfied: 15,234 (100%)
# Unsatisfied: 0
# 
# Constraint types:
#   a * b = c: 12,450
#   a + b = c: 2,784
# 
# Most expensive constraints (by wire count):
#   Constraint 8923: 47 wires
#   Constraint 3421: 39 wires
#   Constraint 12001: 35 wires

Integration with Solana

Submit Proof On-Chain

# Generate and submit proof in one command
zkvault prove-and-submit \
  --circuit circuit.circom \
  --witness witness.json \
  --vault 7xKp...3m9X \
  --network devnet

# Output:
# [1/3] Generating proof... ✓
# [2/3] Compressing for Solana... ✓
# [3/3] Submitting transaction...
# 
# Transaction signature: 5Xm2...9kL4
# Proof ID: 3aF8...7dN2
# Status: Submitted
# 
# View on Solana Explorer:
# https://explorer.solana.com/tx/5Xm2...9kL4?cluster=devnet

# Dry run (don't submit)
zkvault prove-and-submit \
  --circuit circuit.circom \
  --witness witness.json \
  --vault 7xKp...3m9X \
  --dry-run

# Output shows estimated costs without submitting:
# Estimated compute units: 45,230
# Estimated transaction fee: 0.000005 SOL

Proof Caching

Cache Management

# Cache proof for reuse
zkvault prove \
  --circuit circuit.circom \
  --witness witness.json \
  --cache

# Retrieve from cache
zkvault prove \
  --circuit circuit.circom \
  --witness witness.json \
  --cache
# Output: ✓ Proof retrieved from cache (0.1s)

# Clear proof cache
zkvault cache clear proofs

# Show cache statistics
zkvault cache stats
# Output:
# Cached circuits: 5
# Cached proofs: 127
# Cache size: 3.2 GB
# Hit rate: 73%

Output Formats

JSON Output

zkvault prove --circuit c.circom --witness w.json --format json

{
  "proof": {
    "pi_a": ["0x...", "0x..."],
    "pi_b": [["0x...", "0x..."], ["0x...", "0x..."]],
    "pi_c": ["0x...", "0x..."],
    "protocol": "groth16",
    "curve": "bn254"
  },
  "publicInputs": [123, 456, 789],
  "metadata": {
    "circuit": "my_circuit",
    "timestamp": 1704067200,
    "provingTime": 12.3,
    "backend": "native"
  }
}

Binary Output

# Output raw binary proof
zkvault prove --circuit c.circom --witness w.json --format binary

# Binary format (Groth16, 256 bytes):
# Bytes 0-63:    pi_a (G1 point, 64 bytes)
# Bytes 64-191:  pi_b (G2 point, 128 bytes)
# Bytes 192-255: pi_c (G1 point, 64 bytes)

Configuration

Prover Settings

# Set default proving backend
zkvault config set proving.backend gpu

# Set worker count
zkvault config set proving.workers 8

# Enable proof caching
zkvault config set proving.cache true

# Set memory limit
zkvault config set proving.memory_limit 16384  # MB