Sample Generated Technical Documentation

0-prompt.txt

Write a Markdown file for technical documentation of "any-zkvm" library.

The goal of this document is to teach future engineers to understand and maintain this library correctly.

This document should also include {@docs: C4 Model} diagrams in {@docs: Mermaid} syntax at three different levels:
1. System context diagram
2. Container diagram
3. Component diagram

any-zkvm-technical-documentation.md

Any-zkVM Technical Documentation

Table of Contents

1. Overview
2. Architecture
3. Core Components
4. ZkVM Implementations
5. Development Guide
6. Maintenance Guide
7. C4 Model Architecture Diagrams

Overview

The any-zkvm library is a Rust template that provides a unified abstraction layer for developing applications across multiple zero-knowledge virtual machines (zkVMs). It enables developers to write code once and execute it on different zkVM backends without modification, facilitating benchmarking and comparison between various zkVM implementations.

Key Features

• Unified API: Single trait-based interface for multiple zkVMs
• Multi-zkVM Support: SP1, RiscZero, PowdrVM (with Jolt in development)
• Benchmarking: Easy performance comparison across different zkVMs
• Type Safety: Rust's type system ensures correctness
• Modularity: Each zkVM implementation is isolated and optional

Supported zkVMs

• SP1: Succinct's zkVM with RISC-V execution
• RiscZero: General-purpose zkVM with RISC-V ISA
• PowdrVM: Modular zkVM with custom ISA support
• Jolt (In Progress): High-performance zkVM with lookup-based approach

Architecture

The library follows a trait-based architecture pattern where:

1. Core Library (lib/) defines the abstract interfaces
2. zkVM Implementations provide concrete implementations
3. Cargo Workspace manages dependencies and builds

Project Structure

any-zkvm/
├── lib/                    # Core abstraction library
│   └── src/lib.rs         # Main trait definitions
├── sp1/                   # SP1 zkVM implementation
│   ├── program/           # Guest program code
│   ├── script/            # Host execution code
│   └── lib/              # SP1-specific bindings
├── risczero/             # RiscZero zkVM implementation
│   ├── host/             # Host execution code
│   ├── methods/          # Guest methods
│   └── methods/guest/    # Guest program code
├── powdr/                # PowdrVM implementation
├── build.sh              # Installation script
└── Cargo.toml           # Workspace configuration

Core Components

ZkvmProcessor Trait

The central abstraction that all zkVM implementations must implement:

pub trait ZkvmProcessor {
    type Output;
    type Input;
    
    fn get_guest_inputs() -> Result<Self::Input, ZkvmProcessError>;
    fn get_host_inputs() -> Self::Input;
    fn prove(input: Self::Input) -> Result<Self::Output, ZkvmProcessError>;
    fn process_outputs(output: Self::Output);
}

Method Responsibilities

• get_guest_inputs(): Reads inputs from the zkVM runtime environment
• get_host_inputs(): Provides inputs from the host environment
• prove(input): Contains the computational logic to be proven
• process_outputs(output): Handles the verified outputs

zkVM-Specific Traits

Each zkVM backend extends the base functionality with specialized traits:

SP1ZkvmProcessor

pub trait Sp1ZkvmProcessor {
    fn process_internal_outputs(
        receipt: &mut sp1_sdk::SP1PublicValues,
    ) -> <Processor as ZkvmProcessor>::Output;
    
    fn secp256k1_add(p: *mut [u32; 16], q: *mut [u32; 16]);
}

RiscZeroZkvmProcessor

pub trait RiscZeroZkvmProcessor {
    fn process_internal_outputs(
        receipt: &risc0_zkvm::Receipt,
    ) -> <Processor as ZkvmProcessor>::Output;
    
    fn secp256k1_add(p: *mut [u32; 16], q: *mut [u32; 16]);
}

PowdrZkvmProcessor

pub trait PowdrZkvmProcessor {
    fn process_internal_outputs(receipt: [u32; 8]) -> <Processor as ZkvmProcessor>::Output;
    fn secp256k1_add(p: *mut [u32; 16], q: *mut [u32; 16]);
}

Error Handling

#[derive(Debug)]
pub enum ZkvmProcessError {
    NotImplemented,
}

ZkVM Implementations

SP1 Implementation

Directory: sp1/

SP1 is Succinct's zkVM that executes RISC-V programs and generates zero-knowledge proofs.

Architecture:

• Program (sp1/program/): Guest code compiled to RISC-V
• Script (sp1/script/): Host code that manages proving and verification
• Features: EVM-compatible proofs, Groth16/PLONK support

Key Characteristics:

• High performance for large computations
• EVM compatibility for on-chain verification
• Requires significant RAM (128GB+ for Groth16/PLONK)

RiscZero Implementation

Directory: risczero/

RiscZero provides a general-purpose zkVM with RISC-V instruction set architecture.

Architecture:

• Host (risczero/host/): Prover and verifier logic
• Methods (risczero/methods/): Method definitions and guest code
• Guest (risczero/methods/guest/): Actual computation logic

Key Characteristics:

• Mature ecosystem and tooling
• Strong RISC-V compliance
• Excellent developer experience

PowdrVM Implementation

Directory: powdr/

PowdrVM is a modular zkVM that supports custom instruction set architectures.

Key Characteristics:

• Modular architecture
• Custom ISA support
• AVX optimization capabilities
• Experimental Valida ISA support (planned)

Development Guide

Setting Up Development Environment

1. Install Dependencies:

   ./build.sh

2. Configure Your Logic: Edit lib/src/lib.rs to implement your computational logic in the prove() method.

3. Run Specific zkVM:

   cargo run -p [sp1|risczero|powdrVM] --release

4. Enable AVX Optimization (for supported zkVMs):

   RUSTFLAGS='-C target-cpu=native' cargo run -p [zkVM] --release

Implementing New Computational Logic

1. Define Input/Output Types:

   impl ZkvmProcessor for Processor {
       type Output = YourOutputType;
       type Input = YourInputType;
       // ...
   }

2. Implement Core Logic:

   fn prove(input: Self::Input) -> Result<Self::Output, ZkvmProcessError> {
       // Your computational logic here
       // This code will be executed in the zkVM
   }

3. Handle Outputs:

   fn process_outputs(output: Self::Output) {
       // Process verified outputs
   }

Adding New zkVM Support

1. Create zkVM Directory: new_zkvm/
2. Implement Traits: Extend ZkvmProcessor and create zkVM-specific trait
3. Add Cargo Configuration: Update workspace Cargo.toml
4. Implement Guest/Host Split: Follow the pattern of existing implementations
5. Add Feature Flags: Enable conditional compilation
6. Update Build Script: Include installation steps in build.sh

Maintenance Guide

Code Organization Best Practices

1. Trait Consistency: Ensure all zkVM implementations follow the same trait interface
2. Feature Flags: Use cargo features to conditionally compile zkVM-specific code
3. Error Handling: Extend ZkvmProcessError as needed for new error conditions
4. Documentation: Maintain inline documentation for all public interfaces

Testing Strategy

1. Unit Tests: Test each trait implementation independently
2. Integration Tests: Verify cross-zkVM compatibility
3. Benchmarking: Regular performance comparisons between implementations
4. CI/CD: Automated testing across all supported zkVMs

Performance Considerations

1. Memory Usage: Monitor RAM requirements, especially for SP1
2. Compilation Time: Track build times across different zkVMs
3. Proof Generation: Benchmark proving times for various workloads
4. AVX Support: Leverage hardware acceleration where available

Common Maintenance Tasks

1. Update Dependencies: Regular updates to zkVM SDKs
2. Feature Parity: Ensure all implementations support the same core features
3. Documentation Sync: Keep README and documentation current
4. Security Audits: Regular review of cryptographic implementations

Troubleshooting

Common Issues

1. Build Failures: Check zkVM-specific dependencies and toolchain requirements
2. Memory Issues: Verify sufficient RAM for proof generation
3. Feature Conflicts: Ensure only one zkVM feature is enabled at build time
4. Runtime Errors: Check input/output type compatibility

Debug Strategies

1. Logging: Enable verbose logging for zkVM operations
2. Isolation: Test each zkVM implementation separately
3. Validation: Verify inputs and outputs at boundaries
4. Profiling: Use performance tools to identify bottlenecks

C4 Model Architecture Diagrams

Level 1: System Context Diagram

graph TB
    User["👤 Developer<br/>(Person)<br/><br/>Develops zkVM applications<br/>using any-zkvm"]
    
    AnyZkvm["📦 Any-zkVM Library<br/>(Software System)<br/><br/>Unified abstraction layer for<br/>developing applications across<br/>multiple zkVMs"]
    
    SP1["🔷 SP1 zkVM<br/>(External System)<br/><br/>Succinct's zero-knowledge<br/>virtual machine"]
    
    RiscZero["🔷 RiscZero zkVM<br/>(External System)<br/><br/>General-purpose zkVM with<br/>RISC-V ISA"]
    
    PowdrVM["🔷 PowdrVM<br/>(External System)<br/><br/>Modular zkVM with<br/>custom ISA support"]
    
    Blockchain["🔷 Blockchain Network<br/>(External System)<br/><br/>Target blockchain for<br/>proof verification"]
    
    User -->|"Develops applications using"| AnyZkvm
    AnyZkvm -->|"Generates proofs via"| SP1
    AnyZkvm -->|"Generates proofs via"| RiscZero
    AnyZkvm -->|"Generates proofs via"| PowdrVM
    AnyZkvm -->|"Submits proofs to"| Blockchain
    
    classDef person fill:#08427b
    classDef system fill:#1168bd
    classDef external fill:#999999
    
    class User person
    class AnyZkvm system
    class SP1,RiscZero,PowdrVM,Blockchain external

Loading

Level 2: Container Diagram

graph TB
    subgraph "Any-zkVM Library"
        CoreLib["📚 Core Library<br/>(Rust Library)<br/><br/>Defines ZkvmProcessor trait<br/>and common abstractions"]
        
        SP1Container["📦 SP1 Implementation<br/>(Rust Module)<br/><br/>SP1-specific zkVM<br/>implementation"]
        
        RiscZeroContainer["📦 RiscZero Implementation<br/>(Rust Module)<br/><br/>RiscZero-specific zkVM<br/>implementation"]
        
        PowdrContainer["📦 PowdrVM Implementation<br/>(Rust Module)<br/><br/>PowdrVM-specific zkVM<br/>implementation"]
        
        BuildSystem["🔧 Build System<br/>(Cargo Workspace)<br/><br/>Manages dependencies<br/>and compilation"]
    end
    
    Developer["👤 Developer"]
    SP1SDK["🔷 SP1 SDK"]
    RiscZeroSDK["🔷 RiscZero SDK"]
    PowdrSDK["🔷 PowdrVM SDK"]
    
    Developer -->|"Implements ZkvmProcessor"| CoreLib
    CoreLib -->|"Extended by"| SP1Container
    CoreLib -->|"Extended by"| RiscZeroContainer
    CoreLib -->|"Extended by"| PowdrContainer
    
    SP1Container -->|"Uses"| SP1SDK
    RiscZeroContainer -->|"Uses"| RiscZeroSDK
    PowdrContainer -->|"Uses"| PowdrSDK
    
    BuildSystem -->|"Builds"| CoreLib
    BuildSystem -->|"Builds"| SP1Container
    BuildSystem -->|"Builds"| RiscZeroContainer
    BuildSystem -->|"Builds"| PowdrContainer
    
    classDef person fill:#08427b
    classDef container fill:#1168bd
    classDef external fill:#999999
    
    class Developer person
    class CoreLib,SP1Container,RiscZeroContainer,PowdrContainer,BuildSystem container
    class SP1SDK,RiscZeroSDK,PowdrSDK external

Loading

Level 3: Component Diagram (Core Library)

graph TB
    subgraph "Core Library (lib/src/lib.rs)"
        ZkvmProcessor["🎯 ZkvmProcessor Trait<br/>(Rust Trait)<br/><br/>Main abstraction interface<br/>- get_guest_inputs()<br/>- get_host_inputs()<br/>- prove()<br/>- process_outputs()"]
        
        SP1Trait["🎯 Sp1ZkvmProcessor Trait<br/>(Rust Trait)<br/><br/>SP1-specific extensions<br/>- process_internal_outputs()<br/>- secp256k1_add()"]
        
        RiscZeroTrait["🎯 RiscZeroZkvmProcessor Trait<br/>(Rust Trait)<br/><br/>RiscZero-specific extensions<br/>- process_internal_outputs()<br/>- secp256k1_add()"]
        
        PowdrTrait["🎯 PowdrZkvmProcessor Trait<br/>(Rust Trait)<br/><br/>PowdrVM-specific extensions<br/>- process_internal_outputs()<br/>- secp256k1_add()"]
        
        ErrorTypes["📋 Error Types<br/>(Rust Enum)<br/><br/>ZkvmProcessError<br/>- NotImplemented"]
        
        ProcessorStruct["🏗️ Processor Struct<br/>(Rust Struct)<br/><br/>Default implementation<br/>with fibonacci example"]
        
        FibonacciFunc["⚙️ Fibonacci Function<br/>(Rust Function)<br/><br/>Example computation<br/>fibonacci(n: u32) -> (u32, u32)"]
        
        TypeDefinitions["📝 Type Definitions<br/>(Rust Types)<br/><br/>Input/Output type aliases<br/>for each zkVM"]
    end
    
    ZkvmProcessor -->|"Extended by"| SP1Trait
    ZkvmProcessor -->|"Extended by"| RiscZeroTrait
    ZkvmProcessor -->|"Extended by"| PowdrTrait
    ZkvmProcessor -->|"Uses"| ErrorTypes
    ZkvmProcessor -->|"Implemented by"| ProcessorStruct
    ProcessorStruct -->|"Uses"| FibonacciFunc
    ProcessorStruct -->|"Defines"| TypeDefinitions
    
    SP1Trait -->|"Implemented by"| ProcessorStruct
    RiscZeroTrait -->|"Implemented by"| ProcessorStruct
    PowdrTrait -->|"Implemented by"| ProcessorStruct
    
    classDef component fill:#1168bd
    classDef trait fill:#2e8b57
    classDef struct fill:#ff6b35
    classDef function fill:#ffd23f
    classDef types fill:#ee6c4d
    
    class ZkvmProcessor,SP1Trait,RiscZeroTrait,PowdrTrait trait
    class ProcessorStruct struct
    class FibonacciFunc function
    class ErrorTypes,TypeDefinitions types

Loading

Conclusion

The any-zkvm library provides a powerful abstraction for zkVM development, enabling developers to write once and deploy across multiple zero-knowledge virtual machines. Its modular architecture, comprehensive trait system, and focus on maintainability make it an excellent foundation for zkVM application development and benchmarking.

For future engineers maintaining this library, focus on:

1. Maintaining trait consistency across implementations
2. Regular updates to keep pace with zkVM ecosystem changes
3. Performance optimization and benchmarking
4. Clear documentation and examples
5. Robust error handling and debugging capabilities

The C4 model diagrams above provide a clear architectural overview at different levels of abstraction, helping both newcomers and experienced developers understand the system's structure and relationships.