# ethereum/sourcify architecture

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

- Interactive diagram: https://gitdiagram.com/ethereum/sourcify
- Repository: https://github.com/ethereum/sourcify

## Overview

##### Project Type & Purpose
- This is a monorepo for a distributed, open-source smart-contract verification platform (Sourcify).
- Core services:
– sourcify-server: HTTP API for full/partial contract verification and storage
– sourcify-monitor: listener that watches EVM chains, fetches new deployments, and calls the server
– database service: PostgreSQL with migrations, schema upgrades, and ETL scripts
- Auxiliary packages: bytecode-utils, compilers-types, compilers, lib-sourcify

##### File-Structure Analysis
- Top-level “services/…” folders for each microservice (server, monitor, database).
- “packages/…” contains core libraries and compiler wrappers used by services.
- CI/CD: .circleci workflows, Dockerfiles, shell scripts for deployment to GCP, npm, multi-arch Docker, nightly tests.
- Scripts directory houses git utilities, chain updates, verification loops.

##### README Insights
- Overview of platform components and their roles.
- References to API docs and playground.
- Mentions Solc/Vyper metadata–based full verification.

a) Main components:
- Client/UI (external: Sourcify UI, CLI)
- sourcify-monitor service
- sourcify-server service (API)
- Verification core (lib-sourcify + compilers + bytecode-utils)
- Database (PostgreSQL)
- Object storage (S3 or local FS)
- External systems: EVM nodes, IPFS, Etherscan, Verifier-Alliance chains

b) Relationships & Data Flows:
1. Client/UI → HTTP → sourcify-server
2. monitor polls chain RPC / Etherscan for new contract creations
3. monitor fetches bytecode from decentralized storage (IPFS/Swarm)
4. monitor → HTTP → sourcify-server for automated verification
5. server invokes Verification core:
– uses bytecode-utils to extract metadata
– uses Solidity/Vyper compiler wrappers to recompile sources
6. server stores results & source files in DB + object storage
7. client queries server to retrieve verified contract files/details

c) Architectural Patterns & Principles:
- Microservices: separated monitor, server, database
- Hexagonal/ports-and-adapters in server (API adapters, storage adapters, compiler adapters)
- Event-driven triggers: monitor → server → database updates
- Shared libraries: code reuse via monorepo packages

d) Key Technologies:
- Node.js/TypeScript
- Hardhat config for local chain tests
- PostgreSQL with Knex-style migrations
- Docker/Docker-Compose for container orchestration
- CircleCI for CI/CD pipelines
- IPFS/Swarm for decentralized storage
- Ethers.js/chain RPC and Etherscan SDK

##### Detail Level
- Internal modules of each service only if relevant (e.g., server’s storageServices vs. generic DB adapter)
- Essential data stores (source files, verification results, chain metadata)
- Extensibility points: chain-support JSON configs, plug-in compilers, storage backends

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients
    subgraph "Clients"
        UI["Sourcify UI/CLI"]:::external
    end

    %% External Systems
    subgraph "External Systems"
        EVM["EVM Nodes"]:::external
        Etherscan["Etherscan & Chain RPC"]:::external
        IPFS["IPFS/Swarm"]:::external
        VerifierChains["Verifier-Alliance Chains"]:::external
    end

    %% Backend Services
    subgraph "Backend Services"
        Monitor["sourcify-monitor (TypeScript)"]:::service
        Server["sourcify-server (TypeScript/Express)"]:::service
    end

    %% Persistence Layer
    subgraph "Persistence"
        DB["PostgreSQL"]:::service
        ObjStorage["Object Storage (S3/Local FS)"]:::service
    end

    %% Verification Core
    subgraph "Verification Core"
        BC["bytecode-utils"]:::core
        CP["compilers (Solidity/Vyper wrappers)"]:::core
        CT["compilers-types"]:::core
        LS["lib-sourcify"]:::core
    end

    %% CI/CD & DevOps
    subgraph "CI/CD & DevOps"
        CircleCI[".circleci Workflows"]:::tool
        Scripts["scripts/"]:::tool
        DockerServer["services/server/Dockerfile"]:::tool
        DockerMonitor["services/monitor/Dockerfile"]:::tool
    end

    %% Data Flows
    UI -->|"HTTP/JSON"| Server
    UI -->|"HTTP/JSON"| Server
    EVM -.poll/RPC.-> Monitor
    Etherscan -.poll/EtherscanSDK.-> Monitor
    Monitor -->|"HTTP/JSON"| Server
    Server -->|"invokes"| BC
    Server -->|"invokes"| CP
    Server -->|"uses types from"| CT
    Server -->|"uses core lib"| LS
    Server -->|"store results"| DB
    Server -->|"store sources"| ObjStorage
    UI -->|"query via HTTP"| Server

    %% CI/CD flows
    CircleCI -->|build/deploy| DockerServer
    CircleCI -->|build/deploy| DockerMonitor
    CircleCI -->|run scripts| Scripts

    %% Click Events
    click Server "https://github.com/ethereum/sourcify/tree/staging/services/server"
    click Monitor "https://github.com/ethereum/sourcify/tree/staging/services/monitor"
    click DB "https://github.com/ethereum/sourcify/tree/staging/services/database"
    click LS "https://github.com/ethereum/sourcify/tree/staging/packages/lib-sourcify"
    click BC "https://github.com/ethereum/sourcify/tree/staging/packages/bytecode-utils"
    click CP "https://github.com/ethereum/sourcify/tree/staging/packages/compilers"
    click CT "https://github.com/ethereum/sourcify/tree/staging/packages/compilers-types"
    click CircleCI "https://github.com/ethereum/sourcify/blob/staging/.circleci"
    click Scripts "https://github.com/ethereum/sourcify/tree/staging/scripts/"
    click DockerServer "https://github.com/ethereum/sourcify/tree/staging/services/server/Dockerfile"
    click DockerMonitor "https://github.com/ethereum/sourcify/tree/staging/services/monitor/Dockerfile"

    %% Styles
    classDef service fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef core fill:#90EE90,stroke:#000,stroke-width:1px
    classDef external fill:#FFA500,stroke:#000,stroke-width:1px
    classDef tool fill:#FFD700,stroke:#000,stroke-width:1px
```
