# layr-labs/hello-world-avs architecture

> Architecture diagram of the GitHub repository layr-labs/hello-world-avs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/layr-labs/hello-world-avs
- Repository: https://github.com/layr-labs/hello-world-avs

## Overview

##### Main Components
a. On-Chain Components (Blockchain Layer)
- Local Anvil Chain (Ethereum JSON-RPC endpoint)
- Core EigenLayer Contracts
– IAVSDirectory
– ECDSAStakeRegistry
– IDelegationManager
- Hello World AVS Contracts
– HelloWorldServiceManager.sol
– HelloWorldServiceManagerFactory (if present)
b. Off-Chain Components (Operator Services & Tools)
- TypeScript Operator (operator/index.ts)
- Rust Operator (operator/rust/crates/operator)
- Rust Challenger (operator/rust/crates/operator/challenger.rs)
- Task-generator / Traffic Script (operator/createNewTasks.ts)
- Distribution Scripts (scripts/*, npm make targets)
- ABI Extraction Utility (utils/abis.js)
c. Developer Tooling & CI/CD
- Foundry (forge, anvil, contracts/foundry.toml)
- npm / ts-node / Rust toolchain
- GitHub Actions workflows (.github/workflows)
- Dockerfile & Makefile for reproducible builds

##### Relationships & Data Flows
- Consumer (CLI / HTTP client) → invokes HelloWorldServiceManager via JSON-RPC →
contracts emit NewTaskCreated event.
- Off-chain Operators subscribe to events (via ethers.js in TS, web3 in Rust),
generate + sign “Hello World” message, and send tx back to HelloWorldServiceManager.
- HelloWorldServiceManager checks stake (via ECDSAStakeRegistry) and records responses.
- Challenger listens for unresponded tasks past threshold → issues slashOperator tx.
- Distribution scripts read contract state (using ABIs) → build merkle roots → claim distributions.

##### Architectural Patterns
- Event-driven Architecture: On-chain events trigger off-chain services.
- Separation of Concerns:
– Smart contracts handle staking, task-lifecycle, slashing.
– Off-chain operators handle computation, signing, and monitoring.
- Polyglot Operator Clients:
– TypeScript for rapid prototyping / CI integration.
– Rust for performance / challenger logic.
- Local Devnet CI:
– Anvil snapshotting for deterministic tests (make build-anvil-state-with-deployed-contracts).

##### Incorporate Key Technologies
- Solidity + Foundry for contracts
- Anvil as local Ethereum node
- ethers.js / ts-node for TypeScript operator
- Rust (tokio, web3 bindings) for challenger & operator
- JSON ABI artifacts (abis/*.json) for off-chain bindings
- Nix / Docker for reproducible environments
- GitHub Actions for CI

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Consumer
    Consumer["Consumer CLI / HTTP Client"]:::external
    Consumer -->|"invoke JSON-RPC"| Anvil

    %% On-Chain Layer
    subgraph "On-Chain Components" 
        direction TB
        Anvil["Local Anvil Chain\n(Ethereum JSON-RPC)"]:::onchain
        IAVSDir["IAVSDirectory ABI"]:::onchain
        ECDSAReg["ECDSAStakeRegistry ABI"]:::onchain
        DelegMgr["IDelegationManager ABI"]:::onchain
        CoreConfig["Core Deployment Config\n(31337)"]:::onchain
        subgraph "Hello World AVS Contracts"
            direction TB
            HWManager["HelloWorldServiceManager"]:::onchain
            HWConfig["HelloWorldServiceManager Config"]:::onchain
        end
    end

    %% Off-Chain Services
    subgraph "Off-Chain Operators & Tools"
        direction TB
        TSOp["TypeScript Operator"]:::offchain
        TaskGen["Task Generator / Traffic Script"]:::offchain
        TS_E2E["TS Operator E2E Test"]:::offchain
        ABIUtil["ABI Extraction Utility"]:::offchain
        subgraph "Rust Operator Crate"
            direction TB
            RustOp["Rust Operator Crate"]:::offchain
            Challenger["Challenger Logic"]:::offchain
            SpamTasks["Spam Task Generator"]:::offchain
            AnvilHelper["Anvil Integration Helper"]:::offchain
            Bindings["Rust Contract Bindings"]:::offchain
            StartOp["Rust Entrypoint"]:::offchain
        end
        DistScripts["Distribution Scripts"]:::offchain
    end

    %% Developer Tooling & CI/CD
    subgraph "Developer Tooling & CI/CD"
        direction TB
        FoundryCfg["Foundry Configuration"]:::devops
        AnvilScripts["Anvil Snapshot & Deploy Scripts"]:::devops
        CIWorkflows["GitHub Actions Workflows"]:::devops
        DockerEnv["Dockerfile & Makefile"]:::devops
        TSConfig["TypeScript Config"]:::devops
        RustConfig["Rust Toolchain Config"]:::devops
    end

    %% Flows
    Anvil -->|calls| IAVSDir
    Anvil -->|calls| ECDSAReg
    Anvil -->|calls| DelegMgr
    Anvil -->|deploy| HWManager
    CoreConfig -->|used by| HWManager
    HWConfig -->|applies to| HWManager

    HWManager -->|"emit NewTaskCreated"| TSOp
    HWManager -->|"emit NewTaskCreated"| RustOp
    TSOp -->|"sign & submitResponse(tx)"| Anvil
    Challenger -->|"slashOperator(tx)"| Anvil
    DistScripts -->|"read state & build merkle"| Anvil

    ABIUtil -->|provides ABIs| TSOp
    ABIUtil -->|provides ABIs| RustOp

    TaskGen -->|generate tasks| TSOp
    TS_E2E -->|test flows| TSOp

    AnvilHelper -->|assist RPC| RustOp
    Bindings -->|generate bindings| RustOp
    StartOp -->|start service| RustOp
    SpamTasks -->|create spam tasks| RustOp

    FoundryCfg -->|configures| AnvilScripts
    CIWorkflows -->|runs| FoundryCfg
    DockerEnv -->|reproducible env| TSOp
    DockerEnv -->|reproducible env| RustOp
    TSConfig -->|configures| TSOp
    RustConfig -->|configures| RustOp

    %% Click Events
    click Anvil "https://github.com/layr-labs/hello-world-avs/tree/master/contracts/anvil"
    click IAVSDir "https://github.com/layr-labs/hello-world-avs/blob/master/abis/IAVSDirectory.json"
    click ECDSAReg "https://github.com/layr-labs/hello-world-avs/blob/master/abis/ECDSAStakeRegistry.json"
    click DelegMgr "https://github.com/layr-labs/hello-world-avs/blob/master/abis/IDelegationManager.json"
    click CoreConfig "https://github.com/layr-labs/hello-world-avs/blob/master/contracts/config/core/31337.json"
    click HWManager "https://github.com/layr-labs/hello-world-avs/blob/master/abis/HelloWorldServiceManager.json"
    click HWConfig "https://github.com/layr-labs/hello-world-avs/blob/master/contracts/src/HelloWorldServiceManager.sol"
    click TSOp "https://github.com/layr-labs/hello-world-avs/blob/master/operator/index.ts"
    click TaskGen "https://github.com/layr-labs/hello-world-avs/blob/master/operator/createNewTasks.ts"
    click TS_E2E "https://github.com/layr-labs/hello-world-avs/blob/master/operator/e2e.test.ts"
    click ABIUtil "https://github.com/layr-labs/hello-world-avs/blob/master/utils/abis.js"
    click RustOp "https://github.com/layr-labs/hello-world-avs/tree/master/operator/rust/crates/operator"
    click Challenger "https://github.com/layr-labs/hello-world-avs/blob/master/operator/rust/crates/operator/src/challenger.rs"
    click StartOp "https://github.com/layr-labs/hello-world-avs/blob/master/operator/rust/crates/operator/src/start_operator.rs"
    click SpamTasks "https://github.com/layr-labs/hello-world-avs/blob/master/operator/rust/crates/operator/src/spam_tasks.rs"
    click AnvilHelper "https://github.com/layr-labs/hello-world-avs/blob/master/operator/rust/crates/operator/src/anvil.rs"
    click Bindings "https://github.com/layr-labs/hello-world-avs/tree/master/operator/rust/crates/utils/src/bindings"
    click DistScripts "https://github.com/layr-labs/hello-world-avs/blob/master/scripts/rewards-script-check.sh"
    click FoundryCfg "https://github.com/layr-labs/hello-world-avs/blob/master/contracts/foundry.toml"
    click AnvilScripts "https://github.com/layr-labs/hello-world-avs/blob/master/contracts/anvil/build-state.sh"
    click CIWorkflows "https://github.com/layr-labs/hello-world-avs/tree/master/.github/workflows/"
    click DockerEnv "https://github.com/layr-labs/hello-world-avs/tree/master/Dockerfile"
    click TSConfig "https://github.com/layr-labs/hello-world-avs/blob/master/tsconfig.json"
    click RustConfig "https://github.com/layr-labs/hello-world-avs/blob/master/rust-toolchain.toml"

    %% Styles
    classDef onchain fill:#D0E6FF,stroke:#0366d6,color:#0366d6;
    classDef offchain fill:#E6FFEA,stroke:#067d3b,color:#067d3b;
    classDef devops fill:#FFF4E5,stroke:#d97706,color:#d97706;
    classDef external fill:#F0F0F0,stroke:#888888,color:#444444;
```
