How succinctlabs/rsp works
Project Type & Purpose
• RSP is a Rust-based command-line tool that generates zero-knowledge proofs for EVM block execution using Reth. It targets Ethereum, OP Stack, and similar EVM-compatible chains.
• Its primary function is to fetch and execute block data (from a JSON-RPC archive node), generate execution reports, and eventually produce ZK proofs of the block’s execution.
• The project is not just a single binary—it consists of multiple client and host binaries (as seen in the “bin” folder) and reusable crates (under the “crates” directory) that encapsulate core logic like execution (host and client executors), storage access, Merkle Patricia Trie (MPT) functionalities, and provider abstractions.
File Structure
• Top-Level Files & Configurations:
• Rust-specific files (Cargo.toml, rust-toolchain.toml, rustfmt.toml) indicate a Rust project using Cargo.
• Docker-related files (.dockerignore, Dockerfile, docker-compose files within some bin directories) suggest containerized development/testing or deployment.
• GitHub workflows indicate CI/CD pipelines for tasks like cycle tracking and PR validation.
• The “bin” Directory:
• Contains several binaries such as “client-op”, “client”, “continuous”, “eth-proofs”, and “host”. These suggest multiple ways of interacting with or testing the system:
▸ “host” is the main CLI, orchestrating block execution, fetching data from RPC nodes, and triggering the ZK proof generation process.
▸ “client” variants likely compose the witness data required for ZKVM execution.
▸ “continuous” appears to be set up for continuous integration/testing (with migrations and docker-compose files) and possibly running continuous proof generation or monitoring.
▸ “eth-proofs” might be dedicated to Ethereum-specific proof work.
• The “crates” Directory:
• Includes folders like “executor” (with both client and host libraries), “mpt” (for Merkle-Patricia Trie logic), “primitives” (for common types used in chain specification and genesis handling), “provider” (for RPC abstraction), and “storage” (likely providing a persistent layer, e.g., witness or RPC-db).
• This modular breakdown shows a clear separation of concerns within the overall architecture.
a. Main Components:
• CLI Host Component:
– This is the primary interface (installed via “rsp” command) that initiates block fetching, sets up the execution environment, and invokes the ZK proof routine.
– It also accepts various flags like block number, RPC URL, genesis path, caching options, and proof generation toggles.
• RPC Integration Module:
– Responsible for communicating with external JSON-RPC nodes (archive nodes) to fetch block and state data.
– This module will also validate inputs and detect chain type (using the “eth_chainId” call).
• Execution Engine:
– Uses the “executor” crates (both host and client sublibraries) to simulate or execute the block, generating an offline execution report.
– Has components for state verification and cycle counting.
• ZKVM / Proof Generation Module:
– After block execution is simulated, this component (potentially integrated with hardware acceleration via CUDA) takes over the generation of the zero-knowledge proofs.
– It interacts with external services (prover network if configured) or runs locally.
• Database & Caching Layer:
– The “continuous” binary and “storage” crates are responsible for managing database migrations and caching the client inputs to speed up repeated executions.
• Ancillary Components:
– MPT & Primitives Libraries: Provide support for Ethereum’s state trie operations, chain specification, and genesis data handling.
– CLI/Configuration Handlers: Manage environment variables (like the .env file) and CLI argument parsing.
b. Relationships & Data Flow:
• The CLI Host accepts user commands and forwards parameters to the RPC Integration Module.
• The RPC Integration Module fetches block and state data from an external node.
• This data is passed to the Execution Engine, which simulates block execution (with interactions to modules provided in the “executor” and “provider” crates) and produces necessary witness inputs.
• The witness data is then processed by the ZKVM component (optionally utilizing GPU acceleration) to generate zero-knowledge proofs.
• Optionally, results, cycle counts, and execution reports are stored or output as CSV logs.
• Continuous testing/monitoring and benchmarking flow similarly, but with persistent caching and docker-compose managed environments.
Architectural Patterns & Design Principles
• Modularization: The split between “bin” binaries and separate “crates” illustrates a layered and modular system with clear separation of responsibility.
• Client-Server Interaction: Even though this is a CLI tool rather than a full web server, it clearly separates between external RPC services (as a “server”) and the local processing client.
• Configurability & Extensibility: The use of environment variables and CLI arguments, along with support for multiple chains and proof generation options, suggests a design built for flexibility.
• Containerization: Dockerfiles and docker-compose files in several directories indicate support for containerized operation, useful for both development and deployment.