Ethereum Validator API

This project provides a RESTful API for retrieving Ethereum validator data, focused on:

• Block rewards: Includes MEV vs vanilla classification and exact reward amounts (in Gwei) based on consensus-layer reward accounting and execution-layer MEV detection.
• Sync committee duties: Lists validators assigned to sync committee roles for a given slot.

Features

• Hybrid reward computation using:
  • Beacon API (for proposer info and consensus rewards)
  • Execution layer (for MEV relay detection via ExtraData)
• Handles edge cases:
  • Future slots (400)
  • Missed slots (404)
• Optimized validator lookup via batched queries

Endpoints

Method	Path	Description
GET	/blockreward/{slot}	Get block reward status and value
GET	/syncduties/{slot}	Get sync committee validator assignments

Third-Party Libraries

Library	Purpose
github.com/ethereum/go-ethereum	Provides client bindings for interacting with the Ethereum execution layer — e.g., retrieving blocks, balances, coinbase addresses.
github.com/pkg/errors	Enhances Go’s native error handling by adding stack traces and context with Wrap and Cause. Used for consistent error wrapping.
github.com/gorilla/mux	HTTP request router and dispatcher used to define clean and parameterized REST endpoints (like /blockreward/{slot}).
golang.org/x/sync/errgroup	Simplifies managing concurrent goroutines with error handling. Used to parallelize validator lookups safely.
github.com/swaggo/swag	Generates Swagger 2.0/OpenAPI 3.0 documentation automatically from Go annotations. Used for maintaining API specs (/docs endpoint) without manual syncing.

Why These Were Chosen

• ✅ Standard ecosystem support: All are widely used in the Go and Ethereum developer community.
• ✅ Minimal and idiomatic: The libraries complement the Go standard library without introducing complexity.
• ✅ Purpose-built: Each dependency is used precisely where the standard library lacks ergonomic or Ethereum-specific support.

Development Setup

Step 0. Install pre-commit:

pip install pre-commit

# For macOS users.
brew install pre-commit

Then run pre-commit install to setup git hook scripts. Used hooks can be found here.

---

NOTE

pre-commit aids in running checks (end of file fixing, markdown linting, go linting, runs go tests, json validation, etc.) before you perform your git commits.

---

Step 1. Install external tooling (golangci-lint, swaggo etc.):

make install

Step 2. Setup project for local testing (init env file, code lint, test run, etc.):

make all

Step 3. Edit newly created .env file with the needed values (if needed):

vim <project_root>/.env

Step 4. Run server:

make run-server

and open http://0.0.0.0:8080/swagger/index.html#/ to open Swagger UI.

Step 5. (OPTIONAL) Run the manual test script:

./scripts/manual_api_test.sh

to run curl commands covering all HTTP status codes.

---

NOTE

Check Makefile for other useful commands.

---

Docker Setup

If you prefer a containerized environment, you can run the server with:

make compose-up

and open http://0.0.0.0:8080/swagger/index.html#/ to open Swagger UI.

Also run:

make compose-down

to clean up the environment.