# gasp-xyz/gasp-monorepo architecture

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

- Interactive diagram: https://gitdiagram.com/gasp-xyz/gasp-monorepo
- Repository: https://github.com/gasp-xyz/gasp-monorepo

## Overview

##### Major Components
- Ethereum/Layer 1 Contracts:
– Include the “Gasp ETH Contract” from the contracts directory, plus the Eigen ETH contracts (in contracts/lib/eigenlayer-contracts). Indicate that these smart contracts handle ERC20 deposits/withdrawals and manage critical state (e.g., Merkle roots, operator lists).
- Sequencer:
– Represent the “sequencer/” service that processes transactions and submits them to the collator.
- Collator:
– Use a node labeled “Gasp Node” (from gasp-node/) to show the block builder powered by Substrate.
- Updater:
– Include the “updater/” service that monitors the Eigen Layer and submits on-chain results, ensuring smart contract states are synchronized.
- Aggregator & Task Manager:
– Show the “avs-aggregator/” module that generates tasks and aggregates operator outputs.
- Gasp AVS Operators:
- Ferry Services:
– Include “ferry-deposit/” and “ferry-withdrawal/” — these handle cross-chain asset transfers.
- Stash (Data Management):
- External Infrastructure & Tooling:
– Optionally, represent the Docker Compose setup (ops/ directories), Helm charts, and monitoring (Grafana) which handle deployment and observability.
- Development & Toolchain:
– You may add an “Infrastructure & Tooling” block mentioning Proto, Moon, Husky, and commitlint that help synchronize toolchain versions across the monorepo.

##### Establish Relationships and Data Flow
- The Task Generator (within avs-aggregator) publishes new tasks to the Aggregator.
- Aggregator collects BLS signatures from the AVS operators (in gasp-avs) and then posts aggregated responses.
- The Updater monitors Eigen Layer activity and updates the Ethereum contracts.
- The Sequencer processes transactions and interacts with the collator (Gasp Node) to build L2 blocks.
- Ferry Services interact with smart contracts on Ethereum as well as external chains to handle asset deposits and withdrawals.
- Stash (data management) aggregates data coming from multiple services (for example, scraping, metrics, transaction history) and might expose APIs to external dashboards.

##### Architectural Patterns and Technologies
- Microservices Architecture: Represent each service (written in Go, Rust, or Node.js) as an independent module communicating over well-defined APIs.
- Layered Architecture: Separate the blockchain layer (contracts and on-chain functions), service layer (sequencer, updater, aggregator, ferry services), and management/data layer (stash).
- That the system uses container orchestration (Docker Compose) and multiple toolchain guarantees (Proto, Moon).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Blockchain Layer
    subgraph "Blockchain Layer"
        C1["Ethereum/Layer 1 Contracts"]:::contracts
    end

    %% Service Layer
    subgraph "Service Layer"
        S1["Sequencer"]:::service
        S2["Gasp Node"]:::service
        S3["Updater"]:::service
        S4["AVS Aggregator"]:::service
        S5["Gasp AVS Operators"]:::operator
        S6["Ferry Deposit"]:::service
        S7["Ferry Withdrawal"]:::service
    end

    %% Data Management Layer
    subgraph "Data Management Layer"
        D1["Stash (Data Management)"]:::data
    end

    %% Supporting Infrastructure
    SI1["External Infrastructure & Tooling"]:::external
    SI2["Development & Toolchain"]:::external

    %% Interactions and Data Flows
    %% AVS Task Flow
    S4 -->|"TaskRequest"| S5
    S5 -->|"SignatureSubmission"| S4
    S4 -->|"AggregatedResponse"| C1

    %% Sequencer and Collator Flow
    S1 -->|"BlockBuilding"| S2

    %% Updater State Flow
    S3 -->|"StateUpdate"| C1

    %% Ferry Services Interactions
    S6 -->|"Deposit"| C1
    S7 -->|"Withdrawal"| C1

    %% Data Aggregation to Stash
    S1 -->|"TransactionData"| D1
    S3 -->|"Metrics"| D1
    S4 -->|"TaskData"| D1

    %% External Infrastructure Deployment/Monitoring
    SI1 -->|"DeployedBy"| S1
    SI1 -->|"DeployedBy"| S3
    SI1 -->|"DeployedBy"| S6
    SI1 -->|"DeployedBy"| S7
    SI1 -->|"ManagedBy"| D1

    %% Development & Toolchain Contribution
    SI2 -->|"CodeSync"| S4
    SI2 -->|"CodeSync"| S5

    %% Click Events
    click C1 "https://github.com/gasp-xyz/gasp-monorepo/tree/develop/contracts/"
    click S1 "https://github.com/gasp-xyz/gasp-monorepo/tree/develop/sequencer/"
    click S2 "https://github.com/gasp-xyz/gasp-monorepo/tree/develop/gasp-node/"
    click S3 "https://github.com/gasp-xyz/gasp-monorepo/tree/develop/updater/"
    click S4 "https://github.com/gasp-xyz/gasp-monorepo/tree/develop/avs-aggregator/"
    click S5 "https://github.com/gasp-xyz/gasp-monorepo/tree/develop/gasp-avs/"
    click S6 "https://github.com/gasp-xyz/gasp-monorepo/tree/develop/ferry-deposit/"
    click S7 "https://github.com/gasp-xyz/gasp-monorepo/tree/develop/ferry-withdrawal/"
    click D1 "https://github.com/gasp-xyz/gasp-monorepo/tree/develop/stash/"
    click SI1 "https://github.com/gasp-xyz/gasp-monorepo/tree/develop/ops/"
    click SI2 "https://github.com/gasp-xyz/gasp-monorepo/tree/develop/.moon/"

    %% Styles
    classDef contracts fill:#ffdddd,stroke:#aa0000,stroke-width:2px;
    classDef service fill:#ddffdd,stroke:#006600,stroke-width:2px;
    classDef operator fill:#ffffcc,stroke:#999900,stroke-width:2px;
    classDef data fill:#ddeeff,stroke:#003366,stroke-width:2px;
    classDef external fill:#ffeedd,stroke:#cc6600,stroke-width:2px;
```
