# filecoin-project/rust-fil-proofs architecture

> Architecture diagram of the GitHub repository filecoin-project/rust-fil-proofs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/filecoin-project/rust-fil-proofs
- Repository: https://github.com/filecoin-project/rust-fil-proofs

## Overview

##### Project type and purpose
- This is a Rust “monorepo” workspace implementing Filecoin proof‐of‐replication (PoRep), proof‐of‐spacetime (PoSt), proof updates, and associated tooling. It consists of reusable cryptographic kernels (hashing, field gadgets), proof circuits, high‐level APIs, parameter management utilities, and CI workflows for parameter generation and testing.

##### File structure
- Top‐level workspace: Cargo.toml, multiple subdirectories each with their own Cargo.toml (e.g. `filecoin‐proofs`, `storage‐proofs‐core`, `storage‐proofs‐porep`, `storage‐proofs‐post`, `storage‐proofs‐update`, `filecoin‐hashers`, `fr32`, `sha2raw`, `fil‐proofs‐param`, `fil‐proofs‐tooling`).
- Core cryptography & gadgets: `storage‐proofs‐core` (merkle trees, SLoth, AES, constraint gadgets).
- Circuit libraries: `storage‐proofs‐porep` (stacked circuits & vanilla proofs), `storage‐proofs‐post` (fallback & vanilla PoSt), `storage‐proofs‐update` (circuit and compound proof update logic).
- High‐level API: `filecoin‐proofs` exposes a unified API for sealing, window PoSt, winning PoSt, proof verification, etc.
- Parameter management: `fil‐proofs‐param` (download, verify, cache parameters from IPFS or manifests).
- Tooling: `fil‐proofs‐tooling` (benchmarks, parameter checks, graph cache generators, fdlimit, micro‐bench scripts).
- Low‐level libs: `filecoin‐hashers` (Blake2s, SHA‐256, Poseidon), `sha2raw`, `fr32` (file‐to‐root conversion).
- CI/CD: `.github/workflows/ci.yml` for tests; `proof‐params‐generate.yml` to pre‐generate Groth16 parameters; custom action `proof‐params‐download`.

##### README for additional insights
- Emphasis on GitHub Actions generating and downloading Groth16 parameters as artifacts.
- Testing and benchmarking are automated via CI workflows and shell scripts.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CI/CD and External Storage
    CIWorkflows["CI/CD Workflows"]:::gray
    ExternalStorage["Artifact Storage (IPFS/GitHub)"]:::gray

    CIWorkflows -->|triggers tests & param tasks| CoreCrypto
    CIWorkflows --> CircuitModules
    CIWorkflows --> FilecoinProofs
    CIWorkflows --> FilProofsParam
    CIWorkflows --> FilProofsTooling
    CIWorkflows -->|uploads/downloads artifacts| ExternalStorage

    ExternalStorage -->|provides parameters| FilProofsParam

    %% Low-Level Crypto Libraries
    subgraph "Low-Level Crypto Libraries"
        direction TB
        CoreCrypto["storage-proofs-core"]:::lowblue
        FilecoinHashers["filecoin-hashers"]:::lowblue
        Sha2Raw["sha2raw"]:::lowblue
        FR32["fr32"]:::lowblue
    end

    CoreCrypto -->|uses hashing| FilecoinHashers
    CoreCrypto --> Sha2Raw
    CoreCrypto --> FR32

    %% Circuit Modules
    subgraph "Circuit Modules"
        direction TB
        PoRep["storage-proofs-porep"]:::green
        PoSt["storage-proofs-post"]:::green
        Update["storage-proofs-update"]:::green
    end

    CoreCrypto -->|provides gadgets| PoRep
    CoreCrypto --> PoSt
    CoreCrypto --> Update

    %% High-Level API
    FilecoinProofs["filecoin-proofs"]:::orange

    PoRep -->|wraps in API| FilecoinProofs
    PoSt --> FilecoinProofs
    Update --> FilecoinProofs

    %% Parameter Management
    FilProofsParam["fil-proofs-param"]:::orange
    FilProofsParam -->|feeds parameters| PoRep
    FilProofsParam --> PoSt
    FilProofsParam --> Update
    FilProofsParam --> FilecoinProofs

    %% Tooling & Benchmarks
    FilProofsTooling["fil-proofs-tooling"]:::orange

    FilProofsTooling -->|benchmarks & checks| Engineers[Engineers/CI Consumers]:::gray

    %% Click Events
    click CoreCrypto "https://github.com/filecoin-project/rust-fil-proofs/tree/master/storage-proofs-core/"
    click FilecoinHashers "https://github.com/filecoin-project/rust-fil-proofs/tree/master/filecoin-hashers/"
    click Sha2Raw "https://github.com/filecoin-project/rust-fil-proofs/tree/master/sha2raw/"
    click FR32 "https://github.com/filecoin-project/rust-fil-proofs/tree/master/fr32/"
    click PoRep "https://github.com/filecoin-project/rust-fil-proofs/tree/master/storage-proofs-porep/"
    click PoSt "https://github.com/filecoin-project/rust-fil-proofs/tree/master/storage-proofs-post/"
    click Update "https://github.com/filecoin-project/rust-fil-proofs/tree/master/storage-proofs-update/"
    click FilecoinProofs "https://github.com/filecoin-project/rust-fil-proofs/tree/master/filecoin-proofs/"
    click FilProofsParam "https://github.com/filecoin-project/rust-fil-proofs/tree/master/fil-proofs-param/"
    click FilProofsTooling "https://github.com/filecoin-project/rust-fil-proofs/tree/master/fil-proofs-tooling/"
    click CIWorkflows "https://github.com/filecoin-project/rust-fil-proofs/tree/master/.github/workflows/"

    %% Styles
    classDef lowblue fill:#E0F7FA,stroke:#006064,color:#004D40;
    classDef green fill:#E8F5E9,stroke:#1B5E20,color:#1B5E20;
    classDef orange fill:#FFF3E0,stroke:#E65100,color:#E65100;
    classDef gray fill:#ECEFF1,stroke:#607D8B,color:#37474F;
```
