How openvm-org/openvm works
Main components
• Core Virtual Machine (VM) Layer:
• Represented by the “crates/vm” directory, this is the core execution environment.
• It handles the VM “architecture” (e.g., the no-CPU design) and manages system subcomponents such as memory, system modules (e.g., native adapter, memory controllers), and the public values.
• Instruction Set and Extensions Layer:
• This layer includes “extensions” (e.g. algebra, bigint, ecc, keccak256, native, pairing, rv32im) as well as the “crates/toolchain” which implements and integrates these custom instructions and chips.
• The “crates/cli” and “crates/sdk” also provide access to these extended instructions from the Rust frontend.
• Circuit and Proof Generation Layer:
• Found in “crates/circuits” (and submodules like mod-builder, poseidon2-air, primitives, sha256-air, etc.), this layer builds the zk-proof circuits.
• This segment also reflects the integration of circuits (borrowed ideas from projects like Plonky3) which underlie the zero-knowledge proof functionality.
• Toolchain / Compiler Layer:
• Several subdirectories under “crates/toolchain” (including instructions, macros, openvm and transpiler) indicate that the project compiles high-level code into VM bytecode and circuit representations.
• This toolchain is responsible for handling the native compiler, translation (e.g., RISC-V instruction translation), and optimizations.
• CLI & SDK User Interfaces:
• The command-line interface (in “crates/cli”) is the user’s primary tool to interact with the VM, build applications, generate proofs, etc.
• The “crates/sdk” provides programmable APIs and examples (also seen in the “examples” folder) for developers to integrate and develop on top of OpenVM.
• Supporting Components:
• Benchmarking (“benchmarks”), tests, audits and documentation (docs, book, and assets) provide quality assurance and visibility into design decisions.
• Continuous integration components (like the .github workflows) ensure system reliability.
Relationships and interactions
• The CLI and SDK interface with the toolchain – they call the native compiler, transpiler, and verification modules.
• The toolchain converts high-level instructions and calls into VM bytecode and sometimes directly into circuit representations, thereby interacting with both the VM core and the circuit builder.
• At runtime, the VM executes the compiled program while interfacing with circuit components to generate or verify zk proofs.
• The Extensions form a plug-in-like layer with directional interconnections: the core VM delegates extended arithmetic or cryptographic operations (like ECC or pairing) to specialized extension components.
• The audits, benchmarks, and tests are on the periphery; they interact with almost every core module to ensure performance and correctness.
• External services (e.g., on-chain verifiers as mentioned in “On-chain Verification” in the README) can be indicated as external systems connected to the VM for verifying proofs.
Architectural Patterns and Design Principles
• Modularity and Extensibility: Clearly separate core VM execution, circuit creation, toolchain compilation, and extensions.
• Layered Design: Each component (UI, compiler/toolchain, runtime, proof system) is self-contained, with well-defined interfaces.
• Customization Without Core Forking: Emphasize the plug-in nature of the extensions by showing how new modules can be “plugged into” the core without modifying it.
• Integration Points: Highlight the integration of Rust’s intrinsic functions (for a smooth developer experience) and the use of cargo workspaces (indicated by many Cargo.toml files) to manage dependencies.