# tornadocash/tornado-core architecture

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

- Interactive diagram: https://gitdiagram.com/tornadocash/tornado-core
- Repository: https://github.com/tornadocash/tornado-core

## Overview

##### Main Components
- Smart Contracts & Blockchain Layer: Represented by the “contracts” folder (with multiple contract types, including mock contracts and contracts for ETH/erc20 tornado applications) along with “migrations” and “truffle-config.js” that manage deployment.
- Zero-Knowledge Circuits: Found in the “circuits” directory (e.g., merkleTree.circom and withdraw.circom), along with related build and trusted setup scripts in the “scripts” folder and even commands in the README to emulate an MPC trusted setup ceremony.
- Application/CLI and Frontend: The “src” folder contains CLI functionality (cli.js and minimal-demo.js) and the “index.html” file indicates a browser interface. These components allow users to interact with the Tornado Cash solution either via command line or via a web-based interface.
- Supporting Scripts and Configuration: This includes various build, compile, and utility scripts in “scripts” (like compileHasher.js, ganacheHelper.js) plus configuration files (.env.example, .nvmrc, prettier, eslint, etc.) which set up the development and build environments.
- Testing and Development Environment: Notably, the “test” folder houses tests for ERC20, ETH, and Merkle trees. A local blockchain simulation (via ganache-cli) is used as indicated by instructions in the README.
- External Services & Deployment Tools: The README also walks through using Infura RPC endpoints, relayer services, and external block explorers (Etherscan) for transaction verification. There is also integration with GitHub Actions (via .github/workflows) for CI/CD.

##### Relationships and Interactions
- zkSNARK Circuit Interaction: From the CLI or a dedicated module, illustrate how data flows to the zkSNARK proving system. The circuits (in the “circuits” folder) take inputs (e.g., user secrets and deposit commitments) and produce a proof which is then submitted.
- Deployment and Testing: Show how the “migrations” and “scripts” interact with the blockchain environment (local Ganache or public networks such as Kovan/Mainnet) using Truffle. Indicate directions of deployment commands launching from the developer machine to the network.
- External Trusted Setup & Relayer Service: In a sidebar or additional component, include elements for the trusted setup ceremony (using zkutil and circom commands) and the relayer service used during withdrawal (as described in the README example).

##### Architectural Patterns and Design Principles
- Layer Separation: Clearly separate blockchain (smart contracts), off-chain computation (zkSNARK generation and trusted setup), and user interaction layers (CLI/browser).
- Modular Design: Note how circuits, smart contracts, and the application logic are encapsulated in separate directories, following a modular approach.
- CI/CD Integration: Include an element for automated testing/build (via GitHub workflows) – even if it’s not core to the runtime, it’s essential for maintenance and quality assurance.

##### Relevant Technologies and Frameworks
- Ethereum Smart Contracts (Solidity)
- zkSNARK circuits using circom and websnark library
- Truffle for deployments and migrations
- Node.js for scripting and CLI functions
- Testing frameworks (likely using Mocha/Chai or similar via yarn/npm test)
- Optionally, external services like Infura for RPC endpoints and Etherscan for transaction verification

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entity
    User("User"):::external

    %% User Interface Layer
    subgraph "User Interface"
        CLI["CLI Interface (cli.js, minimal-demo.js)"]:::ui
        Browser["Browser Interface (index.html)"]:::ui
    end

    %% Off-chain Modules Layer
    subgraph "Off-chain Modules"
        ZK["zkSNARK Circuits (merkleTree.circom, withdraw.circom)"]:::offchain
        TS["Trusted Setup & Build Scripts (compileHasher.js, downloadKeys.js)"]:::offchain
    end

    %% Blockchain Layer
    subgraph "Blockchain Layer"
        SC["Smart Contracts (contracts, Mocks)"]:::blockchain
        DM["Deployment & Migrations (migrations, truffle-config.js)"]:::blockchain
    end

    %% Supporting Scripts, Testing & External Tools
    subgraph "Supporting & Testing"
        US["Utility Scripts (ganacheHelper.js)"]:::support
        CF["Configuration Files (.env.example, .nvmrc, .eslintrc, .prettierrc, .prettierignore)"]:::support
        TSys["Tests (ERC20Tornado.test.js, ETHTornado.test.js, MerkleTreeWithHistory.test.js)"]:::support
        CICD["CI/CD Workflows (.github/workflows/build.yml)"]:::external
        DS["Deployment Script (deploy.js)"]:::external
    end

    %% External Services
    ExtServ["External Services (Infura,Relayer,Etherscan)"]:::external

    %% Data Flow Connections
    User --> CLI
    User --> Browser
    CLI -->|"initiate_tx"| ZK
    Browser -->|"initiate_tx"| ZK
    TS -->|"setup"| ZK
    ZK -->|"on-chain_interaction"| SC
    DM -->|"deploys"| SC
    US -->|"simulate_chain"| DM
    CICD -->|"automated_deploy"| DM
    DS -->|"manual_deploy"| DM
    CF --- US
    CF --- TSys
    TSys -->|"validate_contracts"| SC
    SC -->|"verify_tx"| ExtServ
    ExtServ -->|"relay_withdrawal"| SC

    %% Click Events
    click SC "https://github.com/tornadocash/tornado-core/tree/master/contracts"
    click DM "https://github.com/tornadocash/tornado-core/tree/master/migrations"
    click CLI "https://github.com/tornadocash/tornado-core/tree/master/src"
    click Browser "https://github.com/tornadocash/tornado-core/blob/master/index.html"
    click ZK "https://github.com/tornadocash/tornado-core/tree/master/circuits"
    click TS "https://github.com/tornadocash/tornado-core/tree/master/scripts"
    click US "https://github.com/tornadocash/tornado-core/blob/master/scripts/ganacheHelper.js"
    click CF "https://github.com/tornadocash/tornado-core/blob/master/.env.example"
    click TSys "https://github.com/tornadocash/tornado-core/tree/master/test"
    click CICD "https://github.com/tornadocash/tornado-core/tree/master/.github/workflows"
    click DS "https://github.com/tornadocash/tornado-core/blob/master/deploy.js"

    %% Styles
    classDef ui fill:#fff3c4,stroke:#b38f00,stroke-width:2px;
    classDef offchain fill:#d0f0c0,stroke:#357a38,stroke-width:2px;
    classDef blockchain fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef support fill:#f8d7da,stroke:#842029,stroke-width:2px;
    classDef external fill:#f5e6ff,stroke:#5a2a83,stroke-width:2px;
```
