# leonardoalt/fusion architecture

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

- Interactive diagram: https://gitdiagram.com/leonardoalt/fusion
- Repository: https://github.com/leonardoalt/fusion

## Overview

##### Project Type and Purpose
- This is an experimental Ethereum zkRollup project written in Rust that focuses on performance and modularity in building a Layer 2 scaling solution.
- Its core functionality uses ZoKrates for SNARK-based circuits that verify state and signature correctness, with separate components for proof generation (prover), block sequencing (sequencer), on-chain verification (L1 verifier), and a client interface (wallet).
- Overall, the project represents a complete tool suite for a zkRollup including the cryptographic circuits, transaction processing, and integration with Ethereum L1.

##### Analyzing the File Structure
- Top-Level Directories:
- circuits: Contains ZoKrates files (.zok) for SNARK circuits including signature, state verification (e.g., babyjubjub_signature.zok, merkle_tree.zok).
- fusion-prover: Implements the Rust prover that leverages the circuits to generate Groth16 SNARKs for each transaction.
- fusion-sequencer: Contains the node responsible for receiving L2 transactions from a CLI wallet and building blocks; it integrates the prover as a dependency.
- fusion-wallet: A command-line interface to sign and send transactions.
- l1-verifier: Holds the deployed smart contracts (with Makefiles and Foundry config) that run on Ethereum for on-chain verification.
- Additional Rust crates (fusion-api, fusion-config, fusion-types) support configurations, shared types, or API abstractions across the system.
- Auxiliary Directories and Scripts:
- .github and scripts directories help with CI/CD and node orchestration (e.g., starting an anvil EVM node, deploying contracts, etc.).
- Build scripts such as Cargo.toml, Makefiles, and rust-toolchain definitions indicate a multi-crate Rust workspace with clear separation of concerns.

##### Core Components & Their Responsibilities
- Clients and Interaction:
- fusion-wallet: Provides a CLI for users to sign and broadcast transactions.
- Transaction Handling & Block Formation:
- fusion-sequencer: Acts as the main node that receives L2 transactions (via RPC), builds blocks, and coordinates with the prover.
- SNARK Proof Generation:
- fusion-prover: Processes signed transactions received from the sequencer, then uses ZoKrates circuits (in the circuits folder) to generate SNARK proofs (using Groth16, with experiments on Nova for recursive batching).
- circuits: Contains the cryptographic circuits (e.g., verification for signatures with Baby Jubjub, Merkle tree construction) written in ZoKrates.
- On-Chain Verification:
- l1-verifier: Implements smart contracts (with Foundry tooling) deployed on Ethereum L1. These smart contracts verify blocks and update canonical state roots based on proofs generated off-chain.
- Shared Configurations and Types:
- fusion-config, fusion-types, fusion-api: Provide shared libraries and configurations that manage the settings and data structures for inter-component communication and state management.
- External Dependencies:
- The project relies on Rust (for the core implementations), ZoKrates (for circuits), Foundry (for contract testing/deployment), and Ethereum (L1 environment via RPC endpoints).

##### Relationships and Interactions
- Fusion-wallet sends signed transaction data to the fusion-sequencer.
- The sequencer (fusion-sequencer) receives and queues transactions, then builds blocks, and executes the proving process by interfacing with fusion-prover.
- Fusion-prover uses ZoKrates-based circuits from the circuits module to generate SNARK proofs for each transaction, which are subsequently used by the sequencer.
- Blocks along with their proofs are then sent to the l1-verifier smart contracts deployed on Ethereum for on-chain verification.
- The entire process is driven by configuration (fusion-config, fusion.toml) that contains critical parameters (e.g., Ethereum RPC, contract addresses, private keys).
- Auxiliary scripts (in the scripts directory) and CI/CD workflows (in the .github folder) automate testing, deployment, and execution.

- Details of critical technologies (Rust, ZoKrates, Groth16/Nova, Foundry) adjacent to their related components.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Off-chain Components
    subgraph "Client"
        fusion_wallet["Client (fusion-wallet)"]:::offchain
    end

    subgraph "Sequencer & Block Builder"
        fusion_sequencer["Transaction Handling & Block Formation (fusion-sequencer)"]:::offchain
    end

    subgraph "Proof Generator"
        fusion_prover["SNARK Proof Generation (fusion-prover)"]:::offchain
    end

    subgraph "Circuits"
        circuits["Cryptographic Circuits (circuits)"]:::offchain
    end

    %% On-chain Component
    subgraph "On-Chain Verifier"
        l1_verifier["On-Chain Verification (l1-verifier)"]:::onchain
    end

    %% Shared Configurations and Types
    subgraph "Shared Config & Types"
        shared_config["Shared Configurations & Types (fusion-config, fusion-types, fusion-api)"]:::shared
    end

    %% External Dependencies
    subgraph "External Dependencies"
        rust["Rust"]:::external
        zokrates["ZoKrates"]:::external
        foundry["Foundry"]:::external
        ethereum["Ethereum"]:::external
    end

    %% Connections between Components
    fusion_wallet -->|"transaction_data"| fusion_sequencer
    fusion_sequencer -->|"proof_request"| fusion_prover
    fusion_prover -->|"circuit_invocation"| circuits
    fusion_sequencer -->|"block_proof_submission"| l1_verifier
    
    %% Shared Config influences key components
    shared_config --- fusion_wallet
    shared_config --- fusion_sequencer
    shared_config --- fusion_prover

    %% External Dependencies relations
    rust --> fusion_wallet
    rust --> fusion_sequencer
    rust --> fusion_prover

    zokrates --> circuits

    foundry --> l1_verifier
    ethereum --> l1_verifier

    %% Click Events for Component Mappings
    click fusion_wallet "https://github.com/leonardoalt/fusion/blob/main/fusion-wallet/src/main.rs"
    click fusion_sequencer "https://github.com/leonardoalt/fusion/blob/main/fusion-sequencer/src/main.rs"
    click fusion_sequencer "https://github.com/leonardoalt/fusion/blob/main/fusion-sequencer/src/sequencer.rs"
    click fusion_sequencer "https://github.com/leonardoalt/fusion/blob/main/fusion-sequencer/src/node.rs"
    click fusion_sequencer "https://github.com/leonardoalt/fusion/blob/main/fusion-sequencer/src/server.rs"
    click fusion_prover "https://github.com/leonardoalt/fusion/blob/main/fusion-prover/src/lib.rs"
    click fusion_prover "https://github.com/leonardoalt/fusion/blob/main/fusion-prover/src/merkle_tree.rs"
    click fusion_prover "https://github.com/leonardoalt/fusion/blob/main/fusion-prover/src/poseidon_hasher.rs"
    click fusion_prover "https://github.com/leonardoalt/fusion/blob/main/fusion-prover/src/state.rs"
    click circuits "https://github.com/leonardoalt/fusion/blob/main/circuits/babyjubjub_signature.zok"
    click circuits "https://github.com/leonardoalt/fusion/blob/main/circuits/merkle_tree.zok"
    click circuits "https://github.com/leonardoalt/fusion/blob/main/circuits/fusion.zok"
    click circuits "https://github.com/leonardoalt/fusion/blob/main/circuits/types.zok"
    click l1_verifier "https://github.com/leonardoalt/fusion/tree/main/l1-verifier/"
    click shared_config "https://github.com/leonardoalt/fusion/blob/main/fusion-config/src/lib.rs"
    click shared_config "https://github.com/leonardoalt/fusion/blob/main/fusion-types/src/lib.rs"
    click shared_config "https://github.com/leonardoalt/fusion/blob/main/fusion-api/src/lib.rs"

    %% Styles for Nodes
    classDef offchain fill:#a2d2ff,stroke:#000,stroke-width:2px;
    classDef onchain fill:#ffadad,stroke:#000,stroke-width:2px;
    classDef shared fill:#ffd6a5,stroke:#000,stroke-width:2px;
    classDef external fill:#caffbf,stroke:#000,stroke-width:2px;
```
