# succinctlabs/sp1-project-template architecture

> Architecture diagram of the GitHub repository succinctlabs/sp1-project-template, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/succinctlabs/sp1-project-template
- Repository: https://github.com/succinctlabs/sp1-project-template

## Overview

##### Project type and purpose
- This is a Rust-based end-to-end “SP1” proof generation template:
- It compiles and executes a RISC-V program (in `program/`)
- It generates zk-proofs (core, Groth16, PLONK) via CLI scripts (`script/`)
- It contains Solidity contracts (`contracts/`) to verify those proofs on EVM
- Use case: developers write RISC-V code, run it, generate proofs, and optionally verify on-chain.

##### File structure
- Top-level:
- `program/` – the RISC-V application (Rust `main.rs`)
- `lib/` – shared Rust library (`lib.rs`) used by both `program/` and `script/`
- `script/` – CLI entrypoints (`build.rs`, `src/bin/*.rs`) to drive execution and proof generation
- `contracts/` – Solidity smart contracts, Foundry tests, and proof fixtures
- config: `Cargo.toml` files in each crate, Foundry config (`foundry.toml`), `.env.example`, GitHub workflows
- Patterns:
- Multi-crate workspace (Cargo workspaces)
- Clear separation: compute (program), proof API (script), on-chain verification (contracts)

##### Key insights from README
- Three execution modes via `script` CLI:
a. `--execute` – run the RISC-V program
b. `--prove` – generate an SP1 core proof
c. `--bin evm` – produce EVM-compatible proofs (Groth16/PLONK)
- Optionally emits JSON fixtures for Solidity tests and a verification key (`vkey` bin)
- Integration point: Succinct Prover Network (via env vars SP1_PROVER, NETWORK_PRIVATE_KEY)

##### Main components
a. RISC-V Program Component
- Contains `program/src/main.rs`
b. Shared Library Component
- Contains `lib/src/lib.rs`
c. CLI/Script Component
- builder (`build.rs`)
- executors (`src/bin/main.rs`)
- prover (`src/bin/vkey.rs`, `src/bin/evm.rs`)
d. Proof Engine
- Connection from CLI to SP1 core & backend proving libraries (external SP1 crates)
e. Smart Contracts Component
- Contains `contracts/src/*.sol`, `contracts/test/*`, Foundry config
f. External Services
g. Artifacts & Data Flows
- RISC-V binary
- Proof JSON fixtures (e.g. `groth16-fixture.json`)
- Verification key (`programVKey`)

##### Relationships and interactions
- “Program” → produces RISC-V binary
- “CLI Script”
- invokes build (runs `build.rs`), compiles `program`
- calls SP1 APIs in `lib` to execute or prove
- outputs proof artifacts → stored in `script/target` & `contracts/src/fixtures`
- “Solidity Contracts”
- import JSON fixtures
- Foundry tests verify proofs on local EVM
- “Succinct Prover Network”
- Optional remote prover for heavy proofs
- Controlled via environment (`.env`)
- “Ethereum/EVM”
- Deploy & verify the contract on-chain

##### Architectural patterns & design principles
- Modularity: separate crates for program, library, and CLI
- Reusability: `lib/` is the core integration point with SP1
- Extensibility: add new CLI bins under `script/src/bin/` or new proof systems
- CI/CD: GitHub workflows automate testing (`foundry-test.yml`) and on-chain proof CI (`prove.yml`)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Development Layer
    subgraph "Development"
        Program["Program (Rust)\nprogram/src/main.rs"]:::rust
        Library["SP1 Library (Rust)\nlib/src/lib.rs"]:::rust
        subgraph "CLI Script (Rust)"
            Builder["Builder\nscript/build.rs"]:::rust
            Executor["Executor (--execute)\nscript/src/bin/main.rs"]:::rust
            VKey["VKey Prover (--prove)\nscript/src/bin/vkey.rs"]:::rust
            EVMProver["EVM Prover (--bin evm)\nscript/src/bin/evm.rs"]:::rust
        end
        Cargo["Cargo Workspace Config\nCargo.toml"]:::ci
        Env["Env Config\n.env.example"]:::external
        CI1["CI: Foundry Tests\n.github/workflows/foundry-test.yml"]:::ci
        CI2["CI: Proof CI\n.github/workflows/prove.yml"]:::ci
    end

    %% Execution & Proving Layer
    subgraph "Execution & Proving"
        Binary["RISC-V Binary"]:::rust
        ProofEngine["SP1 Proving Libraries"]:::external
        Succinct["Succinct Prover Network"]:::external
        Groth16["groth16-fixture.json"]:::ci
        Plonk["plonk-fixture.json"]:::ci
        VKeyBin["Verification Key (vkey)"]:::ci
    end

    %% On-Chain Verification Layer
    subgraph "On-Chain Verification"
        Contracts["Solidity Contracts & Tests"]:::solidity
        FoundryConfig["Foundry Config\ncontracts/foundry.toml"]:::solidity
        Tests["Solidity Tests\ncontracts/test/"]:::solidity
        EVM["Ethereum/EVM"]:::external
    end

    %% Relationships
    Builder -->|compiles Program & Library| Binary
    Executor -->|--execute| Binary
    Executor -->|uses Library APIs| Library
    Executor -->|calls| ProofEngine
    Executor -->|env configured| Env
    Executor -->|remote optional| Succinct

    VKey -->|--prove| Groth16
    VKey -->|outputs vkey| VKeyBin
    VKey -->|calls| ProofEngine
    VKey -->|env configured| Env
    VKey -->|remote optional| Succinct

    EVMProver -->|--bin evm| Plonk
    EVMProver -->|calls| ProofEngine
    EVMProver -->|env configured| Env
    EVMProver -->|remote optional| Succinct

    Binary -->|produces| Contracts
    Groth16 -->|import fixtures| Contracts
    Plonk -->|import fixtures| Contracts
    VKeyBin -.->|use in tests| Contracts
    Contracts -->|deploy & verify| EVM

    %% Click Events
    click Program "https://github.com/succinctlabs/sp1-project-template/blob/main/program/src/main.rs"
    click Library "https://github.com/succinctlabs/sp1-project-template/blob/main/lib/src/lib.rs"
    click Builder "https://github.com/succinctlabs/sp1-project-template/blob/main/script/build.rs"
    click Executor "https://github.com/succinctlabs/sp1-project-template/blob/main/script/src/bin/main.rs"
    click VKey "https://github.com/succinctlabs/sp1-project-template/blob/main/script/src/bin/vkey.rs"
    click EVMProver "https://github.com/succinctlabs/sp1-project-template/blob/main/script/src/bin/evm.rs"
    click Contracts "https://github.com/succinctlabs/sp1-project-template/tree/main/contracts/"
    click FoundryConfig "https://github.com/succinctlabs/sp1-project-template/blob/main/contracts/foundry.toml"
    click Tests "https://github.com/succinctlabs/sp1-project-template/tree/main/contracts/test/"
    click Groth16 "https://github.com/succinctlabs/sp1-project-template/blob/main/contracts/src/fixtures/groth16-fixture.json"
    click Plonk "https://github.com/succinctlabs/sp1-project-template/blob/main/contracts/src/fixtures/plonk-fixture.json"
    click Env "https://github.com/succinctlabs/sp1-project-template/blob/main/.env.example"
    click CI1 "https://github.com/succinctlabs/sp1-project-template/blob/main/.github/workflows/foundry-test.yml"
    click CI2 "https://github.com/succinctlabs/sp1-project-template/blob/main/.github/workflows/prove.yml"
    click Cargo "https://github.com/succinctlabs/sp1-project-template/blob/main/Cargo.toml"

    %% Styles
    classDef rust fill:#ccffcc,stroke:#009900,stroke-width:2px
    classDef solidity fill:#cce5ff,stroke:#005cbf,stroke-width:2px
    classDef external fill:#eeeeee,stroke:#666666,stroke-width:2px
    classDef ci fill:#fff2cc,stroke:#cc7a00,stroke-width:2px
```
