Architecture
The prover system consists of three main components:Prover Server
Go-based HTTP server that generates ZK proofs using Gnark circuits
Prover Client
Rust client library for submitting proof requests and polling for results
Proving Keys
Pre-computed circuit parameters downloaded on-demand or at startup
Circuit Types
The prover supports multiple circuit types for different operations:State Tree Circuits (V2)
Batch Append Circuit Appends new leaves to state Merkle trees in batches. Used when processing output queue items that represent newly created compressed accounts.- Purpose: Batch insertion of new leaves into state trees
- Tree Height: 26 or 32
- Batch Size: Up to 500 items per proof
- Circuit Name:
batch_append_{height}_{batch_size}
- Purpose: Batch nullification of existing leaves
- Tree Height: 26 or 32
- Batch Size: Up to 500 items per proof
- Circuit Name:
batch_update_{height}_{batch_size}
Address Tree Circuits (V2)
Batch Address Append Circuit Appends new addresses to indexed Merkle trees. Used when creating new compressed accounts that need unique addresses.- Purpose: Batch insertion into indexed address trees
- Tree Height: 26 or 32
- Batch Size: Up to 500 items per proof
- Circuit Name:
batch_address_append_{height}_{batch_size}
Merkle Proof Circuits (V1)
Inclusion Circuit Proves that specific leaves exist in a Merkle tree at a given root.- Purpose: Prove account existence
- Tree Height: Configurable (typically 26)
- Accounts: 1-8 accounts per proof
- Purpose: Prove address uniqueness
- Tree Height: Configurable (typically 26)
- Accounts: 1-8 accounts per proof
- Purpose: Prove both existence and non-existence
- Accounts: Multiple accounts per proof
Proof Generation Flow
Submit Proof Request
Client sends circuit inputs as JSON to the prover server via HTTP POST to
/proveQueue or Process
Server either returns proof immediately (small circuits) or queues the job and returns a job ID
Generate Proof
Prover loads the appropriate circuit and proving keys, then generates the ZK proof using Gnark
Key Management
The prover uses a lazy loading system for circuit proving keys:- On-Demand Download: Keys are downloaded from a CDN when first needed
- Local Cache: Keys are cached in
./proving-keys/directory - Preloading: Keys can be preloaded at startup for specific run modes
- Run Modes:
local-rpc,rpc,forester,forester-test,full,full-test
Proving keys are large files (GB-sized) that contain pre-computed parameters for the circuits. The prover can automatically download missing keys or you can manually download them using the
download command.Performance Characteristics
Proof Generation Time
| Circuit Type | Batch Size | Typical Time | Memory |
|---|---|---|---|
| Batch Append 26 | 100 | ~2-5s | ~4GB |
| Batch Append 26 | 500 | ~8-15s | ~8GB |
| Batch Update 26 | 100 | ~2-5s | ~4GB |
| Batch Update 26 | 500 | ~8-15s | ~8GB |
| Address Append 26 | 100 | ~3-6s | ~4GB |
| Inclusion 26 | 4 accounts | ~1-3s | ~2GB |
Redis Queue Mode
The prover supports Redis-backed job queuing for distributed proof generation:- Update Worker: Processes batch update (nullify) requests
- Append Worker: Processes batch append requests
- Address Append Worker: Processes address append requests
Next Steps
Running the Server
Learn how to start and configure the prover server
Circuit Details
Deep dive into circuit implementations and parameters