# renegade-fi/renegade-solidity-contracts architecture

> Architecture diagram of the GitHub repository renegade-fi/renegade-solidity-contracts, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/renegade-fi/renegade-solidity-contracts
- Repository: https://github.com/renegade-fi/renegade-solidity-contracts

## Overview

##### Project Type and Purpose
- Project Type: A blockchain‐protocol repository (“darkpool” settlement contracts) combining on‐chain Solidity code, off‐chain code generation (Rust), deployment scripts (bash/Cargo), and integration tests (Rust + Anvil).
- Purpose: Encapsulate Merklized exchange state, on‐chain PlonK verifier, settlement logic; provide tooling to generate ABIs, verification keys, Poseidon constants; enable local testing and deployment.

##### File Structure for Architectural Components
Top‐Level Directories:
- abi/           → Rust code generating contract ABIs and JSON artifacts
- codegen/       → Rust binaries generating zero‐values, Poseidon constants, verification keys
- src/           → Solidity contracts, libraries (darkpool, merkle, poseidon2, verifier), proxies
- lib/           → Git‐submodules of standard libs (OpenZeppelin, forge‐std, huff, solmate)
- script/        → Shell scripts for deployment, ABI updates, integration tests
- integration/   → Rust integration test suite that spins up an Anvil node, deploys contracts, and invokes them
- tools/         → Additional Rust CLI tools for deploying dummy tokens or orchestrating multi‐chain deployment
- test/          → Unit tests: Solidity (Forge), Huff tests, Rust reference implementations

##### README for Additional Insights
- Builds on Foundry (forge & anvil) and Rust/Cargo toolchains.
- Unit tests run via “forge test --ffi” (Solidity + FFI calls into Rust reference impls).
- Integration tests run via a shell script that starts an Anvil node, deploys contracts, and executes Rust tests.
- Deployment scripts prompt for configuration and use forge to deploy to any EVM chain.

##### Main System Components and Their Interactions
a. Developer Workstation
– Installs Foundry (forge & anvil) and Rust/Cargo.
– Runs codegen binaries (abi/, codegen/) to produce JSON ABIs, Poseidon parameters, PlonK vkeys.
b. Build & Deployment Pipeline
– Foundry compiles Solidity contracts in src/, linking libraries from lib/.
– script/bin/deploy.sh uses forge to push compiled bytecode to a live EVM via RPC.
– script/bin/deploy-token.sh and tools/* deploy ERC20 mocks.
c. On‐Chain Component (EVM Node)
– Hosts deployed smart contracts:
- Darkpool Settlement contract (state + matching logic)
- Merkle tree contract (state root updates)
- PlonK Verifier contract (proof validation on-chain)
– Interacts via JSON RPC with off‐chain clients and scripts.
d. Off‐Chain Test Harness & Clients
– Integration tests (Rust) spawn Anvil (local EVM), deploy contracts, then call into them via ethers‐rs.
– Rust reference implementations under test/rust‐reference‐impls mirror on‐chain logic for unit testing via FFI (forge unit tests).
e. Code Generation & Artifacts
– abi/ and codegen/ produce:
- Combined JSON ABIs (ICombined.json)
- Poseidon constants & zero‐hashes
- PlonK vkeys for on‐chain verifier
– Artifacts consumed both by Solidity (embedded via include_bytes! or loaded dynamically) and by off‐chain clients/tests.

##### Architectural Patterns & Design Principles
- Modular Libraries: reuse OpenZeppelin, solmate, huffers, solidity‐bn254 for critical cryptographic primitives.
- On‐chain/off‐chain separation: heavy crypto pre‐computation off‐chain (codegen) vs. minimal verification on‐chain.
- Test‐driven: unit tests in Solidity + Rust FFI, integration tests in Rust + local Anvil.
- Script orchestration: bash wrappers for reproducible builds, tests, and deployments.

##### Elements
– Clear labels: “ABI Generator”, “Poseidon Constants Generator”, “Solidity Compiler (Foundry)”, “Anvil/EVM Node”, “Integration Test Suite”, “Deployment Script”
- From codegen to build artifacts (ABIs, vkeys)
- From build to on‐chain deployment
- From tests to EVM node via JSON RPC
- Off‐chain Rust tools (blue rectangles)
- Shell scripts/commands (rounded yellow)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Off-Chain Code Generation
    subgraph "Off-Chain Codegen & Artifacts"
        style OffChain fill:none,stroke:none
        ABI["ABI Generator"]:::rust
        click ABI "https://github.com/renegade-fi/renegade-solidity-contracts/tree/main/abi/"
        Poseidon["Poseidon Constants Generator"]:::rust
        click Poseidon "https://github.com/renegade-fi/renegade-solidity-contracts/tree/main/codegen/poseidon-constants/"
        MerkleZeros["Merkle Zero Hashes Generator"]:::rust
        click MerkleZeros "https://github.com/renegade-fi/renegade-solidity-contracts/tree/main/codegen/merkle-zeros/"
        VKeys["PlonK Verification Keys Generator"]:::rust
        click VKeys "https://github.com/renegade-fi/renegade-solidity-contracts/tree/main/codegen/vkeys/"
        ABI --> Artifacts1
        Poseidon --> Artifacts2
        MerkleZeros --> Artifacts3
        VKeys --> Artifacts4
        Artifacts1["Combined JSON ABIs"]:::artifact
        Artifacts2["Poseidon Constants"]:::artifact
        Artifacts3["Zero Hashes"]:::artifact
        Artifacts4["PlonK vKeys"]:::artifact
    end

    %% Build Pipeline
    subgraph "Build & Compile"
        style Build fill:none,stroke:none
        Foundry["Solidity Compiler (Foundry)"]:::solidity
        click Foundry "https://github.com/renegade-fi/renegade-solidity-contracts/blob/main/foundry.toml"
        Artifacts1 --> Foundry
        Artifacts2 --> Foundry
        Artifacts3 --> Foundry
        Artifacts4 --> Foundry
        Bytecode["Compiled Bytecode"]:::artifact
        Foundry --> Bytecode
    end

    %% Deployment Scripts
    subgraph "Deployment Scripts"
        style Deploy fill:none,stroke:none
        DeployMain["Deploy Script"]:::shell
        click DeployMain "https://github.com/renegade-fi/renegade-solidity-contracts/blob/main/script/bin/deploy.sh"
        DeployToken["Deploy-Token Script"]:::shell
        click DeployToken "https://github.com/renegade-fi/renegade-solidity-contracts/blob/main/script/bin/deploy-token.sh"
        UpdateABI["Update-ABI Script"]:::shell
        click UpdateABI "https://github.com/renegade-fi/renegade-solidity-contracts/blob/main/script/bin/update-abi.sh"
        Bytecode --> DeployMain
        Bytecode --> DeployToken
    end

    %% Additional Tools
    subgraph "Auxiliary Tools"
        style Tools fill:none,stroke:none
        DummyERC20["Dummy Token Tool"]:::rust
        click DummyERC20 "https://github.com/renegade-fi/renegade-solidity-contracts/tree/main/tools/deploy-dummy-erc20/"
        MultiChain["Multi-Chain Orchestrator"]:::rust
        click MultiChain "https://github.com/renegade-fi/renegade-solidity-contracts/tree/main/tools/deploy/"
        CLIUtils["Shared CLI Utilities"]:::rust
        click CLIUtils "https://github.com/renegade-fi/renegade-solidity-contracts/tree/main/tools/tool-utils/"
        DummyERC20 --> DeployToken
        CLIUtils --> DeployMain
        CLIUtils --> MultiChain
    end

    %% On-Chain Environment
    subgraph "On-Chain / EVM Node"
        style OnChain fill:none,stroke:none
        EVM["Anvil/Production EVM Node"]:::evm
        Contracts["Solidity Contracts"]:::contract
        click Contracts "https://github.com/renegade-fi/renegade-solidity-contracts/tree/main/src/"
        EVM --> Contracts
        DeployMain --> EVM
        DeployToken --> EVM
        MultiChain --> EVM
    end

    %% Testing
    subgraph "Testing"
        style Testing fill:none,stroke:none
        UnitTests["Unit Tests (Solidity & Huff)"]:::test
        click UnitTests "https://github.com/renegade-fi/renegade-solidity-contracts/tree/main/test/huff/"
        click UnitTests "https://github.com/renegade-fi/renegade-solidity-contracts/tree/main/test/libraries/darkpool/"
        click UnitTests "https://github.com/renegade-fi/renegade-solidity-contracts/tree/main/test/test-contracts/"
        RustRef["Rust FFI Implementations"]:::rust
        click RustRef "https://github.com/renegade-fi/renegade-solidity-contracts/tree/main/test/rust-reference-impls/"
        ForgeTest["forge test --ffi"]:::shell
        UnitTests --> ForgeTest
        RustRef --> ForgeTest
        IntegrationScript["Run Integration Tests Script"]:::shell
        click IntegrationScript "https://github.com/renegade-fi/renegade-solidity-contracts/blob/main/script/bin/run-integration-tests.sh"
        IntegrationSuite["Integration Test Suite"]:::rust
        click IntegrationSuite "https://github.com/renegade-fi/renegade-solidity-contracts/tree/main/integration/"
        IntegrationScript --> IntegrationSuite
        IntegrationSuite --> EVM
    end

    %% CI Workflow
    CI["CI Workflow"]:::ci
    click CI "https://github.com/renegade-fi/renegade-solidity-contracts/blob/main/.github/workflows/test.yml"
    ForgeTest --> CI
    IntegrationScript --> CI
    DeployMain --> CI

    %% Styles
    classDef rust fill:#D0E8FF,stroke:#0288D1,color:#000
    classDef solidity fill:#FFF3E0,stroke:#FB8C00,color:#000
    classDef shell fill:#FFFDE7,stroke:#FBC02D,color:#000
    classDef artifact fill:#ECEFF1,stroke:#607D8B,color:#000
    classDef contract fill:#E8F5E9,stroke:#43A047,color:#000
    classDef evm fill:#E0F7FA,stroke:#0097A7,color:#000
    classDef test fill:#F3E5F5,stroke:#8E24AA,color:#000
    classDef ci fill:#FFEBEE,stroke:#E53935,color:#000
```
