# oasysgames/verse-verifier architecture

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

- Interactive diagram: https://gitdiagram.com/oasysgames/verse-verifier
- Repository: https://github.com/oasysgames/verse-verifier

## Overview

##### Project Type and Purpose
- This is an open-source, Go-based command-line application (“Verse Verifier”) whose primary purpose is to validate rollup state produced by the Verse-Layer on the Oasys blockchain, collect signatures from validators, share them over a P2P network, and—once a quorum (≥51% stake) is reached—submit the aggregated signature to an on-chain verification contract.
- It can be run in three modes (state verification, P2P networking, and signature submission) either together or independently.

##### High-Level File-Structure Analysis
- **cmd/**: CLI entrypoints (root, start, status, ping, wallet unlock, IPC commands).
- **config/**: Configuration loading and validation (YAML).
- **contract/**: Go bindings for on-chain contracts (L2→Oasis output oracle, multicall, stake manager, SCC, etc.).
- **database/**: Local persistence of blocks, proposals, signatures, state, etc., with models and optimizations.
- **p2p/**: Peer node setup, circuit relay, hole punching, message filters, node status.
- **ipc/**: IPC server and client for JSON-RPC or local socket communication (used by other services).
- **verifier/** & **verse/**: Core rollup state verification logic, block-range management, proof generation, event logs, op stack handling.
- **submitter/**: Signature collection and submission loops.
- **ethutil/**: Ethereum-style utilities (EIP-712 hashing, signing).
- **metrics/** & **logger/**: Metrics registry (Prometheus integration) and structured logging handlers.
- **proto/**: Protobuf definitions (gRPC messages for P2P).
- **main.go** orchestrates initialization and dispatch to modules.

##### Key Insights from README
- Confirms three primary functions: verification, P2P signature sharing, on-chain submission.
- Emphasizes running alongside a full node (same keystore, EIP-712).
- Requires a YAML config, systemd service, and firewall rules for P2P.

##### Main Components
a. Configuration Loader (config package)
b. Core Service Orchestrator (main → cmd/)
c. P2P Network Node (p2p package + proto/gRPC)
d. IPC Server (ipc package)
e. Rollup Verifier Engine (verifier + verse)
f. Signature Submitter (submitter package)
g. Contract Interfaces (contract/*)
h. Ethereum JSON-RPC Client & Signer (ethutil + wallet)
i. Local Database (database package)
j. Metrics & Logging (metrics + logger)
k. External Dependencies:
- Oasys/Ethereum Node (JSON-RPC)
- P2P Peers
- On-chain Verification Contract

##### Relationships & Data Flows
- Config Loader → Core Orchestrator initializes all modules.
- Orchestrator spawns:
- P2P Node ←→ Peers (send/receive state commitment & signatures via proto messages)
- IPC Server ←→ Local tools (JSON-RPC style)
- Verifier Engine → consumes rollup batch data → stores intermediate results in DB
- Submitter → reads collected signatures from DB → calls Ethereum JSON-RPC to submit transaction via contract bindings
- All modules emit metrics to the Prometheus registry and logs to the structured logger.

##### Architectural Patterns & Principles
- Modular domain separation (config, network, verification, submission, persistence).
- Pub/Sub (job queues and worker pools in util/) may be used internally to decouple tasks.
- Single-process micro-services: each domain runs as a Goroutine or worker pool.
- Dependency inversion by passing interfaces (e.g., database, p2p, ipc) into core services for testability.

##### Technologies, Frameworks & Libraries
- Language: Go modules (go.mod)
- RPC: gRPC / Protobuf for P2P messaging
- Data Store: Embedded SQL/bolt or similar via database package
- Ethereum interaction: JSON-RPC over HTTP, EIP-712 hashing
- Metrics: Prometheus client
- Logging: Custom handler with levels and contexts
- Deployment: Dockerfile, Makefile, systemd unit

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Deployment
    subgraph "Deployment"
        Deployer["Systemd / Docker"]:::external
        NodeExt["Oasys/Ethereum Node"]:::external
        Peers["P2P Peers"]:::external
    end

    %% Core Orchestrator
    subgraph "Core Service"
        CoreOrch["Core Service Orchestrator<br/>(main & cmd)"]:::service
        ConfigLoader["Configuration Loader"]:::service
    end

    %% Modules
    subgraph "Network Layer"
        P2PNode["P2P Network Node"]:::network
        IPCServer["IPC Server & CLI"]:::ipc
    end

    subgraph "Processing Layer"
        Verifier["Rollup Verifier Engine"]:::service
        Submitter["Signature Submitter"]:::service
    end

    subgraph "Persistence Layer"
        Database["Local Database"]:::datastore
    end

    subgraph "Integration"
        Contracts["Contract Interfaces"]:::contract
        EthClient["Ethereum JSON-RPC Client & Signer"]:::network
    end

    subgraph "Cross-Cutting"
        Metrics["Metrics & Logging"]:::util
        Util["Utilities & Worker Infra"]:::util
    end

    %% Connections
    Deployer -->|triggers| CoreOrch
    ConfigLoader -->|initializes| CoreOrch

    CoreOrch -->|spawns| P2PNode
    CoreOrch -->|spawns| IPCServer
    CoreOrch -->|spawns| Verifier
    CoreOrch -->|spawns| Submitter

    P2PNode <-->|gRPC / Proto| Peers
    IPCServer <-->|JSON-RPC / Socket| CoreOrch

    Verifier -->|writes| Database
    Submitter -->|reads| Database
    Submitter -->|submits tx| EthClient
    EthClient -->|calls| Contracts

    Verifier -->|emits| Metrics
    Submitter -->|emits| Metrics
    P2PNode -->|emits| Metrics
    IPCServer -->|emits| Metrics

    Verifier -->|logs to| Metrics
    Submitter -->|logs to| Metrics
    CoreOrch -->|logs to| Metrics
    P2PNode -->|logs to| Metrics
    IPCServer -->|logs to| Metrics

    Util -->|pub/sub & workers| Verifier
    Util -->|pub/sub & workers| Submitter
    Util -->|pub/sub & workers| P2PNode

    %% Click Events
    click ConfigLoader "https://github.com/oasysgames/verse-verifier/blob/main/config/config.go"
    click ConfigLoader "https://github.com/oasysgames/verse-verifier/blob/main/config/verse_discovery.go"
    click CoreOrch "https://github.com/oasysgames/verse-verifier/blob/main/main.go"
    click CoreOrch "https://github.com/oasysgames/verse-verifier/blob/main/cmd/root.go"
    click CoreOrch "https://github.com/oasysgames/verse-verifier/blob/main/cmd/start.go"
    click CoreOrch "https://github.com/oasysgames/verse-verifier/blob/main/cmd/status.go"
    click CoreOrch "https://github.com/oasysgames/verse-verifier/blob/main/cmd/ping.go"
    click CoreOrch "https://github.com/oasysgames/verse-verifier/blob/main/cmd/unlock.go"
    click P2PNode "https://github.com/oasysgames/verse-verifier/blob/main/p2p/node.go"
    click P2PNode "https://github.com/oasysgames/verse-verifier/blob/main/p2p/p2p.go"
    click P2PNode "https://github.com/oasysgames/verse-verifier/blob/main/p2p/circuit_relay.go"
    click P2PNode "https://github.com/oasysgames/verse-verifier/blob/main/p2p/holepunch.go"
    click P2PNode "https://github.com/oasysgames/verse-verifier/blob/main/p2p/filters.go"
    click P2PNode "https://github.com/oasysgames/verse-verifier/blob/main/proto/p2p/v1/message.proto"
    click P2PNode "https://github.com/oasysgames/verse-verifier/blob/main/proto/p2p/v1/gen/message.pb.go"
    click IPCServer "https://github.com/oasysgames/verse-verifier/blob/main/ipc/server.go"
    click IPCServer "https://github.com/oasysgames/verse-verifier/blob/main/ipc/client.go"
    click IPCServer "https://github.com/oasysgames/verse-verifier/blob/main/cmd/ipccmd/ipccmd.go"
    click IPCServer "https://github.com/oasysgames/verse-verifier/blob/main/cmd/ipccmd/ping.go"
    click IPCServer "https://github.com/oasysgames/verse-verifier/blob/main/cmd/ipccmd/status.go"
    click IPCServer "https://github.com/oasysgames/verse-verifier/blob/main/cmd/ipccmd/wallet_unlock.go"
    click Verifier "https://github.com/oasysgames/verse-verifier/blob/main/verifier/verifier.go"
    click Verifier "https://github.com/oasysgames/verse-verifier/blob/main/verifier/block_range_manager.go"
    click Verifier "https://github.com/oasysgames/verse-verifier/blob/main/verse/verse.go"
    click Verifier "https://github.com/oasysgames/verse-verifier/blob/main/verse/event_log.go"
    click Verifier "https://github.com/oasysgames/verse-verifier/blob/main/verse/opstack.go"
    click Verifier "https://github.com/oasysgames/verse-verifier/blob/main/verse/opstack_proof.go"
    click Submitter "https://github.com/oasysgames/verse-verifier/blob/main/submitter/submitter.go"
    click Submitter "https://github.com/oasysgames/verse-verifier/blob/main/submitter/signature_iter.go"
    click Contracts "https://github.com/oasysgames/verse-verifier/blob/main/contract/l2oo/oasysl2outputoracle.go"
    click Contracts "https://github.com/oasysgames/verse-verifier/blob/main/contract/l2ooverifier/oasysl2outputoracleverifier.go"
    click Contracts "https://github.com/oasysgames/verse-verifier/blob/main/contract/multicall2/multicall2.go"
    click Contracts "https://github.com/oasysgames/verse-verifier/blob/main/contract/scc/scc.go"
    click Contracts "https://github.com/oasysgames/verse-verifier/blob/main/contract/sccverifier/sccverifier.go"
    click Contracts "https://github.com/oasysgames/verse-verifier/blob/main/contract/stakemanager/stakemanager.go"
    click EthClient "https://github.com/oasysgames/verse-verifier/blob/main/ethutil/client.go"
    click EthClient "https://github.com/oasysgames/verse-verifier/blob/main/ethutil/signer.go"
    click EthClient "https://github.com/oasysgames/verse-verifier/blob/main/ethutil/message.go"
    click EthClient "https://github.com/oasysgames/verse-verifier/blob/main/wallet/keystore.go"
    click Database "https://github.com/oasysgames/verse-verifier/blob/main/database/database.go"
    click Database "https://github.com/oasysgames/verse-verifier/blob/main/database/models.go"
    click Database "https://github.com/oasysgames/verse-verifier/blob/main/database/block.go"
    click Database "https://github.com/oasysgames/verse-verifier/blob/main/database/op_state.go"
    click Database "https://github.com/oasysgames/verse-verifier/blob/main/database/op_signature.go"
    click Database "https://github.com/oasysgames/verse-verifier/blob/main/database/op_proposal.go"
    click Metrics "https://github.com/oasysgames/verse-verifier/blob/main/metrics/registry.go"
    click Metrics "https://github.com/oasysgames/verse-verifier/blob/main/metrics/prometheus.go"
    click Metrics "https://github.com/oasysgames/verse-verifier/blob/main/metrics/metrics.go"
    click Metrics "https://github.com/oasysgames/verse-verifier/blob/main/logger/handler.go"
    click Util "https://github.com/oasysgames/verse-verifier/blob/main/util/pubsub.go"
    click Util "https://github.com/oasysgames/verse-verifier/blob/main/util/jobqueue_worker.go"
    click Util "https://github.com/oasysgames/verse-verifier/blob/main/util/worker_pool.go"
    click Util "https://github.com/oasysgames/verse-verifier/blob/main/util/worker_group.go"

    %% Styles
    classDef external fill:#f9f,stroke:#333,stroke-width:1px
    classDef service fill:#bbf,stroke:#333,stroke-width:1px
    classDef network fill:#fcf,stroke:#333,stroke-width:1px
    classDef ipc fill:#cfc,stroke:#333,stroke-width:1px
    classDef datastore fill:#cff,stroke:#333,stroke-width:1px
    classDef contract fill:#fbb,stroke:#333,stroke-width:1px
    classDef util fill:#ffc,stroke:#333,stroke-width:1px
```
