GHOst is a high-performance Ethereum event observation and processing engine built with Clean Architecture and high-concurrency principles. It is designed to serve as the backbone for real-time applications such as self-custodial wallets, gas oracles, and DeFi monitoring systems.
GHOst prioritizes system robustness, separation of concerns, and resilience against network failures.
The system utilizes a Fan-out / Worker Pool pattern. New blocks are ingested via WebSockets and dispatched through Go Channels to asynchronous processors. This ensures that latency in business logic (e.g., database persistence or external API calls) does not block the ingestion of subsequent network blocks.
Features a subscription monitoring system with Graceful Shutdown capabilities. If the Ethereum node (Infura, Alchemy, or a self-hosted node) terminates the connection, the service handles the closure of active processes and enables a clean reconnection, preventing memory leaks or inconsistent states.
Following the Standard Go Project Layout:
/internal: Encapsulates domain logic and prevents circular dependencies./cmd: Clean, decoupled entry points for various services (observer, api, etc.)./deployments: Infrastructure as Code (IaC) and orchestration configurations.
- Runtime: Go 1.22+ (leveraging generics and efficient memory management).
- Blockchain SDK:
go-ethereum(Geth) - Official client. - Configuration: Viper (dynamic support for
.envand environment variables). - Observability: Native integration prepared for Prometheus (network latency metrics).
- Infrastructure: Docker (Multi-stage builds) and Kubernetes manifests ready for production.
- Go 1.22+
- An API Key from a node provider (Infura, Alchemy) or access to a local node.
Create a .env file in the root directory or export variables directly:
ETH_RPC_URL=wss://mainnet.infura.io/ws/v3/YOUR_API_KEY
LOG_LEVEL=info# Download dependencies
go mod download
# Run the observation service
go run cmd/observer/main.goThis project includes a CI/CD pipeline via GitHub Actions configured for:
-
Linting: Strict code standard validation using
golangci-lint. -
Unit Testing: Automated testing of processing logic.
-
Build: Generation of an ultra-lightweight Docker image based on
alpineto minimize the attack surface.
To deploy on a Kubernetes cluster:
kubectl apply -f deployments/k8s/-
Gas Oracle: Implementation of moving average calculations for real-time fee prediction.
-
GraphQL API: Exposing processed data through a typed and efficient schema.
-
Persistence Layer: Support for Redis (high-speed cache) and PostgreSQL (transactional history).
-
EVM Event Decoder: Automatic log decoding for popular smart contracts (ERC-20, Uniswap).
This project is open-source under the MIT License.