Verifier CLI

Command-line tools for verifying zero-knowledge proofs locally and on-chain with ZKVAULT.

Local Verification

Verify Proof Locally

zkvault verify \
  --proof ./proofs/proof.json \
  --vk ./keys/verification_key.json \
  --public-inputs '[123, 456, 789]'

# Output:
# Verifying proof...
# ✓ Proof is valid
# Verification time: 8.7ms
# Public inputs: [123, 456, 789]

# Verify with verbose output
zkvault verify \
  --proof proof.json \
  --vk vk.json \
  --public-inputs '[123, 456, 789]' \
  --verbose

# Verbose output:
# [1/4] Deserializing proof... ✓
# [2/4] Validating curve points... ✓
# [3/4] Preparing public inputs... ✓
# [4/4] Pairing check... ✓
# 
# ✓ Proof is valid (8.7ms)
# 
# Details:
#   Protocol: Groth16
#   Curve: BN254
#   Proof size: 256 bytes
#   Public inputs: 3
#   Pairing operations: 4

Batch Verification

# Verify multiple proofs
zkvault verify-batch \
  --proofs ./proofs/*.json \
  --vk ./keys/verification_key.json \
  --public-inputs-file ./inputs/public_inputs.json

# Output:
# Verifying 24 proofs...
# [████████████████████] 24/24 (100%)
# 
# Results:
#   Valid: 23
#   Invalid: 1
#   Total time: 198.3ms
#   Avg time per proof: 8.3ms
# 
# Failed proofs:
#   proof_15.json: Pairing check failed

# Parallel batch verification
zkvault verify-batch \
  --proofs ./proofs/*.json \
  --vk vk.json \
  --parallel \
  --workers 8

# Output:
# Verifying 24 proofs with 8 workers...
# ✓ Complete in 34.2ms (7.1x speedup)

On-Chain Verification

Verify on Solana

# Submit proof for on-chain verification
zkvault verify-onchain \
  --proof proof.json \
  --vault 7xKp...3m9X \
  --network devnet

# Output:
# Submitting proof to vault 7xKp...3m9X...
# Transaction signature: 5Xm2...9kL4
# 
# Verification status: Pending
# Waiting for confirmation...
# 
# ✓ Proof verified on-chain
# Compute units used: 45,230
# Transaction fee: 0.000005 SOL
# 
# View on explorer:
# https://explorer.solana.com/tx/5Xm2...9kL4?cluster=devnet

# Watch verification status
zkvault verify-onchain \
  --proof proof.json \
  --vault 7xKp...3m9X \
  --network devnet \
  --wait

# Check existing proof verification
zkvault verify-status \
  --proof-id 3aF8...7dN2 \
  --network devnet

# Output:
# Proof ID: 3aF8...7dN2
# Status: Verified
# Result: Valid
# Verified at: 2024-01-15 10:23:45 UTC
# Compute units: 45,230

Estimate Verification Cost

# Estimate compute units before submitting
zkvault estimate \
  --proof proof.json \
  --vault 7xKp...3m9X \
  --network devnet

# Output:
# Estimated compute units: 45,230
# Estimated transaction fee: 0.000005 SOL
# 
# Breakdown:
#   Proof deserialization: 5,000 CU
#   Curve operations: 28,000 CU
#   Pairing computation: 12,000 CU
#   State updates: 230 CU
# 
# Recommendation: Within limits ✓

Verification Key Management

Upload Verification Key

# Upload VK to Solana
zkvault vk upload \
  --vault 7xKp...3m9X \
  --vk-file ./keys/verification_key.json \
  --protocol groth16 \
  --network devnet

# Output:
# Uploading verification key...
# VK size: 1,432 bytes
# VK hash: 0x3f7a8c...92d4e1
# 
# Transaction signature: 8Nq3...5mP7
# ✓ Verification key uploaded
# 
# Vault updated:
#   Vault: 7xKp...3m9X
#   VK hash: 0x3f7a8c...92d4e1
#   Protocol: Groth16
#   Curve: BN254

Download Verification Key

# Download VK from vault
zkvault vk download \
  --vault 7xKp...3m9X \
  --output ./keys/downloaded_vk.json \
  --network devnet

# Output:
# Fetching verification key from vault...
# ✓ Downloaded verification_key.json (1,432 bytes)
# VK hash: 0x3f7a8c...92d4e1

# Verify VK integrity
zkvault vk verify \
  --vault 7xKp...3m9X \
  --vk-file ./keys/verification_key.json \
  --network devnet

# Output:
# ✓ Verification key matches vault VK
# Hash: 0x3f7a8c...92d4e1

Proof Inspection

Display Proof Contents

# Show proof details
zkvault proof inspect ./proofs/proof.json

# Output:
# Proof: proof.json
# Protocol: Groth16
# Curve: BN254
# Size: 256 bytes
# 
# Components:
#   π_A (G1): 0x1a2b3c... (64 bytes)
#   π_B (G2): 0x4d5e6f... (128 bytes)
#   π_C (G1): 0x7g8h9i... (64 bytes)
# 
# Public Inputs (3):
#   [0]: 123
#   [1]: 456
#   [2]: 789
# 
# Metadata:
#   Generated: 2024-01-15 10:20:15 UTC
#   Circuit: my_circuit
#   Proving time: 12.3s
#   Backend: native

# Show as hex
zkvault proof inspect proof.json --format hex

# Show as base64
zkvault proof inspect proof.json --format base64

Validate Proof Format

# Validate proof structure without verification
zkvault proof validate ./proofs/proof.json

# Output:
# ✓ Proof format is valid
# ✓ All curve points are valid
# ✓ Points are in correct subgroup
# ✓ Size matches protocol spec (256 bytes)
# 
# Warnings: None

# Validate with strict checks
zkvault proof validate proof.json --strict

# Strict mode checks:
# ✓ Point coordinates in field
# ✓ Points on curve
# ✓ Subgroup membership
# ✓ Non-zero points (where required)
# ✓ Compressed encoding valid

Query On-Chain State

Query Vault Information

# Get vault details
zkvault vault info 7xKp...3m9X --network devnet

# Output:
# Vault: 7xKp...3m9X
# Authority: 9Abc...4XyZ
# Status: Active
# 
# Configuration:
#   Protocol: Groth16
#   Curve: BN254
#   VK hash: 0x3f7a8c...92d4e1
#   Max data size: 10 MB
# 
# Statistics:
#   Total proofs submitted: 1,247
#   Total proofs verified: 1,238
#   Total data stored: 8.3 MB
# 
# Created: 2024-01-10 08:15:30 UTC
# Last updated: 2024-01-15 10:23:45 UTC

List Proofs

# List all proofs for a vault
zkvault proof list --vault 7xKp...3m9X --network devnet

# Output:
# Proof ID              | Status    | Submitted           | Result
# ----------------------|-----------|---------------------|-------
# 3aF8...7dN2          | Verified  | 2024-01-15 10:23:45 | Valid
# 5Bc9...2eM3          | Verified  | 2024-01-15 10:22:31 | Valid
# 7Cd0...4fN4          | Failed    | 2024-01-15 10:21:18 | Invalid
# 9De1...6gO5          | Pending   | 2024-01-15 10:25:02 | -
# 
# Total: 1,247 proofs

# Filter by status
zkvault proof list \
  --vault 7xKp...3m9X \
  --status verified \
  --limit 10 \
  --network devnet

# Filter by date range
zkvault proof list \
  --vault 7xKp...3m9X \
  --from "2024-01-15" \
  --to "2024-01-16" \
  --network devnet

Verification Reports

Generate Verification Report

# Generate detailed verification report
zkvault report \
  --proof proof.json \
  --vk vk.json \
  --output report.json

# Report contents (report.json):
{
  "proof": {
    "file": "proof.json",
    "size": 256,
    "hash": "0x8f3a..."
  },
  "verification": {
    "result": "valid",
    "time": 8.7,
    "timestamp": "2024-01-15T10:23:45Z"
  },
  "protocol": {
    "name": "Groth16",
    "curve": "BN254",
    "pairingCount": 4
  },
  "publicInputs": [123, 456, 789],
  "checks": {
    "curvePoints": "passed",
    "subgroupMembership": "passed",
    "pairingEquation": "passed"
  }
}

# Generate HTML report
zkvault report \
  --proof proof.json \
  --vk vk.json \
  --format html \
  --output report.html

Audit Log

# Export verification audit log
zkvault audit export \
  --vault 7xKp...3m9X \
  --from "2024-01-01" \
  --to "2024-01-31" \
  --output audit_jan2024.csv \
  --network devnet

# CSV format:
# timestamp,proof_id,prover,status,result,compute_units
# 2024-01-15T10:23:45Z,3aF8...7dN2,9Abc...4XyZ,verified,valid,45230
# 2024-01-15T10:22:31Z,5Bc9...2eM3,9Abc...4XyZ,verified,valid,45118
# ...

Performance Monitoring

Benchmark Verification

# Benchmark verification performance
zkvault benchmark verify \
  --proof proof.json \
  --vk vk.json \
  --iterations 100

# Output:
# Running 100 verification iterations...
# 
# Results:
#   Mean: 8.7ms
#   Median: 8.6ms
#   Std dev: 0.4ms
#   Min: 8.1ms
#   Max: 10.2ms
# 
# Breakdown:
#   Deserialization: 0.3ms (3%)
#   Point validation: 1.2ms (14%)
#   Pairing: 7.1ms (82%)
#   Final checks: 0.1ms (1%)

# Compare verification methods
zkvault benchmark verify-compare \
  --proof proof.json \
  --vk vk.json \
  --methods local,onchain

# Output:
# Method     | Time     | Cost
# -----------|----------|-------------
# local      | 8.7ms    | Free
# onchain    | ~400ms   | 0.000005 SOL

Troubleshooting

Debug Failed Verification

# Debug why verification failed
zkvault verify \
  --proof proof.json \
  --vk vk.json \
  --public-inputs '[123, 456, 789]' \
  --debug

# Debug output:
# [DEBUG] Loading proof... ✓
# [DEBUG] Loading verification key... ✓
# [DEBUG] Deserializing π_A... ✓
# [DEBUG] Deserializing π_B... ✓
# [DEBUG] Deserializing π_C... ✓
# [DEBUG] Validating curve points... ✓
# [DEBUG] Checking subgroup membership... ✓
# [DEBUG] Preparing public inputs... ✓
# [DEBUG] Computing input contribution... ✓
# [DEBUG] Pairing check:
#   LHS: Fq12(0x1a2b...)
#   RHS: Fq12(0x4d5e...)
# [ERROR] Pairing equation failed: LHS ≠ RHS
# 
# ✗ Proof is invalid
# 
# Possible causes:
#   1. Proof was generated with different circuit
#   2. Public inputs don't match
#   3. Verification key mismatch
#   4. Corrupted proof data

Verify Circuit-VK Compatibility

# Check if VK matches circuit
zkvault vk check-compatibility \
  --circuit circuit.r1cs \
  --vk vk.json

# Output:
# ✓ Verification key matches circuit
# 
# Circuit constraints: 15,234
# VK commitment count: 46 (3 public + 42 private + 1 constant)
# Curve: BN254
# Protocol: Groth16

Configuration

Verifier Settings

# Set verification timeout
zkvault config set verification.timeout 30000  # ms

# Enable automatic retry
zkvault config set verification.retry_on_failure true
zkvault config set verification.max_retries 3

# Set compute unit limit for on-chain verification
zkvault config set verification.max_compute_units 400000