How oasysgames/verse-verifier works
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