# u2u-labs/event-pool architecture

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

- Interactive diagram: https://gitdiagram.com/u2u-labs/event-pool
- Repository: https://github.com/u2u-labs/event-pool

## Overview

##### Project type and purpose
- This is a full-blown blockchain node / event-pool service written in Go. It combines:
- A CLI (Cobra) for on-chain operations and secret management
- A long-running server exposing gRPC/HTTP/WebSocket APIs
- Core blockchain sub-systems (P2P networking, consensus, state, txpool, block sync)
- An “Event Pool” feature that listens for smart-contract events, persists them, backfills history, and pushes them to clients in real time via WebSocket.

##### File structure
Top-level directories map to architectural layers:
- cmd/            → CLI entrypoints and commands (serve, secrets, output, etc.)
- server/         → The HTTP/gRPC/WebSocket server, system services, metrics
- internal/       → Core application logic (config loading, DB access, listener, worker, monitor)
- blockchain/, chain/, consensus/, network/, state/, txpool/, syncer/ → Underlying blockchain engine sub-systems
- pkg/            → Reusable packages (e.g. Ethereum client, MQTT, gRPC server helpers)
- prisma/         → Database schema/migrations for PostgreSQL
- secrets/        → Key/secret management APIs
- helper/         → Utility libraries (hex, keccak, keystore, progress bars, test helpers)
- data/           → Local test keys for P2P, consensus
- go.mod, Dockerfile, docker-compose.yaml → Build, containerization, orchestration

##### README for additional insights
- Purpose: “Event Pool” – listens to smart-contract events on supported L1 chains, stores them (PostgreSQL), publishes in real time (WebSocket + Redis pub/sub), supports historical backfill.
- Tech stack calls out: Go, Cobra, Viper, Prisma, go-ethereum, asynq (background jobs), WebSocket, Redis, PostgreSQL, Ethereum RPC.
- Configuration via config.yaml (server, database, redis, ethereum, websocket, asynq).
- Endpoints: HTTP API for chain/contract registration, WebSocket subscriptions, background job processing.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "External Systems"
        CLI["CLI"]:::cli
        WSClient["WebSocket Clients"]:::external
        EthRPC["Ethereum RPC"]:::external
    end

    subgraph "API Server"
        APIServer["API Server (gRPC/HTTP/WebSocket)"]:::api
    end

    subgraph "Event Pool Service"
        Listener["Event Listener & Backfiller"]:::event
        Worker["Worker (Redis + asynq)"]:::event
        WebSocketSvc["WebSocket Service"]:::event
    end

    subgraph "Blockchain Engine"
        Network["P2P Network Stack"]:::core
        Consensus["Consensus Engine"]:::core
        TxPool["Transaction Pool"]:::core
        StateMgr["State Manager & Storage"]:::core
        Syncer["Block Syncer"]:::core
    end

    subgraph "Data Stores"
        Postgres["PostgreSQL"]:::db
        Redis["Redis"]:::db
        LevelDB["LevelDB / KV Storage"]:::db
    end

    subgraph "Infrastructure Services"
        CryptoUtil["Crypto Utilities"]:::infra
        Secrets["Secrets Management"]:::infra
    end

    %% Connections
    CLI -->|"gRPC/HTTP calls"| APIServer
    APIServer -->|"read/write registrations"| Postgres
    APIServer -->|"publish notifications"| Redis
    Listener -->|"publish events"| Redis
    EthRPC -->|"RPC call"| Listener
    Worker -->|"consume jobs/write events"| Postgres
    WebSocketSvc -->|"subscribe events/push"| WSClient
    Redis -->|"pub/sub"| WebSocketSvc
    APIServer -->|"WebSocket service"| WebSocketSvc
    Network -->|"peers gossip"| Consensus
    Network -->|"feeds"| Syncer
    TxPool -->|"receives txs"| APIServer
    TxPool -->|"gossips txs"| Network
    Syncer -->|"downloads blocks"| Network
    Syncer -->|"passes blocks"| Consensus
    Consensus -->|"state transitions"| StateMgr
    StateMgr -->|"reads/writes"| LevelDB
    Consensus -->|"validates blocks"| StateMgr
    Worker -->|"uses Redis"| Redis

    %% Click Events
    click CLI "https://github.com/u2u-labs/event-pool/tree/dev/cmd/"
    click APIServer "https://github.com/u2u-labs/event-pool/blob/dev/server/server.go"
    click Listener "https://github.com/u2u-labs/event-pool/blob/dev/internal/listener/listener.go"
    click Worker "https://github.com/u2u-labs/event-pool/blob/dev/internal/worker/worker.go"
    click Postgres "https://github.com/u2u-labs/event-pool/tree/dev/prisma/"
    click Redis "https://github.com/u2u-labs/event-pool/blob/dev/internal/worker/worker.go"
    click Network "https://github.com/u2u-labs/event-pool/tree/dev/network/"
    click Consensus "https://github.com/u2u-labs/event-pool/tree/dev/consensus/"
    click TxPool "https://github.com/u2u-labs/event-pool/tree/dev/txpool/"
    click StateMgr "https://github.com/u2u-labs/event-pool/tree/dev/state/"
    click Syncer "https://github.com/u2u-labs/event-pool/tree/dev/syncer/"
    click CryptoUtil "https://github.com/u2u-labs/event-pool/tree/dev/crypto/"
    click Secrets "https://github.com/u2u-labs/event-pool/tree/dev/secrets/"

    %% Styles
    classDef external fill:#DDDDDD,stroke:#333,stroke-width:1px
    classDef cli fill:#DDA0DD,stroke:#333,stroke-width:1px
    classDef api fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef core fill:#87CEFA,stroke:#333,stroke-width:1px
    classDef event fill:#FFA500,stroke:#333,stroke-width:1px
    classDef db fill:#90EE90,stroke:#333,stroke-width:1px
    classDef infra fill:#D3D3D3,stroke:#333,stroke-width:1px
```
