# scroll-tech/scroll-contracts architecture

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

- Interactive diagram: https://gitdiagram.com/scroll-tech/scroll-contracts
- Repository: https://github.com/scroll-tech/scroll-contracts

## Overview

##### Project type and purpose
- This is a blockchain smart-contract project implementing the Scroll L1 (Ethereum) ↔ L2 (Scroll rollup) bridge and rollup system.
- It includes:
- L1 contracts for message passing, rollup finalization, gateways.
- L2 contracts for message passing, gateways, predeploys.
- Shared libraries for hashing, proofs, codecs.
- Deployment scripting (Hardhat, Foundry).
- Integration and unit tests.

##### File structure
- Top level: configuration (.env, eslint, prettier, foundry.toml, hardhat.config.ts).
- Directories:
- lib/ holds external submodules (ds-test, forge-std, solmate).
- scripts/ contains deployment scripts for Foundry and Hardhat.
- hardhat-test/ holds integration tests using Hardhat.
- src/ contains the Solidity code, organized by:
– L1/ (gateways, rollup, messenger)
– L2/ (gateways, predeploys, messenger)
– libraries/ (verifier binaries, Poseidon, PatriciaMerkleTrie, common codecs)
– gas-swap, rate-limiter, batch-bridge, interfaces, mocks, misc
- src/test/ duplicates Solidity unit tests.

##### README for additional insights
- Confirms L1 vs L2 separation and contract responsibilities.
- Specifies toolchain: Node.js + Yarn, Foundry for build and unit tests, Hardhat for integration.

##### Main components and their interactions
a. On-Chain Components
- Ethereum L1:
– L1ScrollMessenger: receives proof commitments from L2 and finalizes them
– Rollup contracts (data availability, state root commit)
– Gateway router + token gateways (USDCGateway, others) to move tokens/chains messages
- Scroll L2:
– L2ScrollMessenger: passes user messages to L1
– Gateway router + token gateways to accept deposits and route withdrawals
– Predeploys: system contracts pre-loaded at genesis
– Utility contracts (gas-swap, rate-limiter)
- Shared libraries:
– Verifier libraries (PLONK, Poseidon hash, PatriciaMerkleTrie) used by rollup and gateways for proof verification

b. Off-Chain Components
- Deployment scripts (scripts/hardhat, scripts/foundry) that compile, deploy, and configure contracts
- Testing frameworks:
– Foundry (forge build/test) for unit tests
– Hardhat (npx hardhat test) for integration tests
- GitHub Actions workflows for CI (contracts.yml, docker-release)

c. Data flows
- User deposits on L1 → L1Gateway → L2 predeploy → credited on L2
- User triggers withdrawal on L2 → L2Gateway → proof generated off-chain → L1ScrollMessenger finalizes on L1
- Rollup sequencer submits batch commitment → proof verification via verifier libs on L1 rollup contract → L1 records state root

##### Architectural patterns and principles
- Layer separation: L1 vs L2 codebases clearly isolated in directories
- Modular gateways: a router delegates to specific token gateway contracts
- Library approach: cryptographic primitives and verifier binaries stored separately and imported
- Scripts + multi-toolchain build: support both Foundry (Rust-based) and Hardhat (TypeScript) flows

##### Relevant technologies and frameworks
- Solidity (contracts in src/)
- Foundry (forge build, forge test)
- Hardhat (npx hardhat compile, test)
- TypeScript (scripts/, hardhat.config.ts)
- Submodules: ds-test, forge-std, solmate
- Verifier binaries (plonk, poseidon) under src/libraries/verifier

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Ethereum L1 On-Chain Components
    subgraph "Ethereum L1" 
        direction TB
        L1RollupCoordinator["L1RollupCoordinator\n(data availability & state root commit)"]:::l1
        L1ScrollMessenger["L1ScrollMessenger"]:::l1
        GatewayRouterL1["GatewayRouter"]:::l1
        subgraph "Token Gateways" 
            direction TB
            USDCGatewayL1["USDCGateway"]:::l1
            OtherTokenGatewayL1["OtherTokenGateway"]:::l1
        end
    end

    %% Scroll L2 On-Chain Components
    subgraph "Scroll L2" 
        direction TB
        L2ScrollMessenger["L2ScrollMessenger"]:::l2
        GatewayRouterL2["GatewayRouter"]:::l2
        subgraph "Token Gateways" 
            direction TB
            USDCGatewayL2["USDCGateway"]:::l2
            OtherTokenGatewayL2["OtherTokenGateway"]:::l2
        end
        Predeploys["Predeploys"]:::l2
        GasSwap["GasSwap"]:::l2
        RateLimiter["RateLimiter"]:::l2
        BatchBridge["BatchBridge"]:::l2
    end

    %% Shared Libraries
    subgraph "Shared Libraries" 
        direction TB
        PLONKVerifier["PLONK Verifier"]:::lib
        CommonCodecs["Common Codecs\n& PatriciaMerkleTrie"]:::lib
        GatewayHelpers["Gateway Helper Modules"]:::lib
        TokenHelpers["Token Helper Modules"]:::lib
    end

    %% Off-Chain Tools & CI/CD
    subgraph "Off-Chain / CI-CD" 
        direction TB
        Hardhat["Hardhat"]:::offchain
        Foundry["Foundry"]:::offchain
        ScriptsFH["Scripts\n(Hardhat & Foundry)"]:::offchain
        CI["GitHub Actions"]:::offchain
    end

    %% Data Flows and Interactions
    L2ScrollMessenger -->|"Message + Proof Submission"| L1ScrollMessenger
    BatchBridge -->|"Batch Commit"| L1RollupCoordinator
    L2ScrollMessenger -->|"State Root Commit"| L1RollupCoordinator
    GatewayRouterL1 -->|"Deposit / Withdraw Calls"| Predeploys
    USDCGatewayL1 -->|calls| GatewayRouterL1
    USDCGatewayL2 -->|calls| GatewayRouterL2

    %% Off-chain deploy/test flows
    ScriptsFH -->|"deploy L1/L2"| L1RollupCoordinator
    ScriptsFH -->|"deploy L1/L2"| L2ScrollMessenger
    Hardhat -->|"integration tests"| L1RollupCoordinator
    Foundry -->|"unit tests"| PLONKVerifier
    CI -->|"trigger"| Hardhat
    CI -->|"trigger"| Foundry

    %% Click Events
    click L1RollupCoordinator "https://github.com/scroll-tech/scroll-contracts/tree/main/src/L1/rollup"
    click L1ScrollMessenger "https://github.com/scroll-tech/scroll-contracts/tree/main/src/L1/system-contract"
    click GatewayRouterL1 "https://github.com/scroll-tech/scroll-contracts/tree/main/src/L1/gateways"
    click USDCGatewayL1 "https://github.com/scroll-tech/scroll-contracts/tree/main/src/L1/gateways/usdc"
    click L2ScrollMessenger "https://github.com/scroll-tech/scroll-contracts/tree/main/src/L2"
    click GatewayRouterL2 "https://github.com/scroll-tech/scroll-contracts/tree/main/src/L2/gateways"
    click USDCGatewayL2 "https://github.com/scroll-tech/scroll-contracts/tree/main/src/L2/gateways/usdc"
    click Predeploys "https://github.com/scroll-tech/scroll-contracts/tree/main/src/L2/predeploys"
    click GasSwap "https://github.com/scroll-tech/scroll-contracts/tree/main/src/gas-swap"
    click RateLimiter "https://github.com/scroll-tech/scroll-contracts/tree/main/src/rate-limiter"
    click BatchBridge "https://github.com/scroll-tech/scroll-contracts/tree/main/src/batch-bridge"
    click PLONKVerifier "https://github.com/scroll-tech/scroll-contracts/tree/main/src/libraries/verifier/plonk-verifier"
    click CommonCodecs "https://github.com/scroll-tech/scroll-contracts/tree/main/src/libraries/common"
    click GatewayHelpers "https://github.com/scroll-tech/scroll-contracts/tree/main/src/libraries/gateway"
    click TokenHelpers "https://github.com/scroll-tech/scroll-contracts/tree/main/src/libraries/token"
    click ScriptsFH "https://github.com/scroll-tech/scroll-contracts/tree/main/scripts/hardhat"
    click Foundry "https://github.com/scroll-tech/scroll-contracts/tree/main/scripts/foundry"
    click Hardhat "https://github.com/scroll-tech/scroll-contracts/tree/main/scripts/hardhat"
    click CI "https://github.com/scroll-tech/scroll-contracts/blob/main/.github/workflows/contracts.yml"

    %% Styles
    classDef l1 fill:#e0f7e9,stroke:#2e7d32,stroke-width:2px;
    classDef l2 fill:#e3f2fd,stroke:#1565c0,stroke-width:2px;
    classDef offchain fill:#fff3e0,stroke:#ef6c00,stroke-width:2px,stroke-dasharray: 5 5;
    classDef lib fill:#f5f5f5,stroke:#9e9e9e,stroke-width:2px;
```
