Koin Ping

Koin Ping is an MIT-licensed blockchain monitoring system by Steven Jannette that polls Ethereum addresses for on-chain activity and delivers real-time alerts to users via a Go REST API backend and a React single-page application frontend.

Getting Started

Prerequisites

• Go 1.24+
• Node.js 18+ and npm (or yarn — preferred per repo policy)
• PostgreSQL 15+
• golangci-lint v2 (for make lint)

Setup

# Clone and enter the repo
git clone <repo-url>
cd koin_ping_0.2.0

# Install pre-commit hook
make hooks

# Install frontend dependencies
cd frontend && npm install && cd ..

# Copy and fill in environment variables
cp backend-go/.env.example backend-go/.env
# edit backend-go/.env with your DATABASE_URL, FIREBASE_PROJECT_ID, ETH_RPC_URL

# Run checks (requires golangci-lint)
make check

# Start the API server
make run

# Start the poller (separate terminal)
cd backend-go && go run ./cmd/poller

# Start the frontend dev server (separate terminal)
cd frontend && npm run dev

The API listens on http://localhost:3001 and the frontend on http://localhost:3000 by default.

Rationale

Crypto users who hold or actively monitor addresses need a lightweight, reliable way to know when on-chain activity occurs without polling block explorers manually. Koin Ping fills that gap: it watches a set of Ethereum addresses, evaluates configurable alert rules (incoming transactions, outgoing transactions, large transfers, balance thresholds), and notifies the user through Discord webhooks.

Design

The system is split into two independently deployable processes and one frontend:

koin_ping_0.2.0/
├── backend-go/                # Go monorepo root
│   ├── cmd/api/               # HTTP REST API server
│   ├── cmd/poller/            # Blockchain polling daemon
│   └── internal/
│       ├── config/            # Environment-based config loading
│       ├── database/          # pgx connection pool
│       ├── domain/            # Shared domain types
│       ├── firebase/          # Firebase auth client
│       ├── handlers/          # HTTP handler wiring
│       ├── middleware/         # Auth middleware
│       ├── models/            # SQL persistence layer
│       ├── notifications/     # Discord webhook delivery
│       ├── protocols/ethereum/ # Ethereum JSON-RPC client
│       ├── services/          # Observer and evaluator business logic
│       └── wei/               # ETH/Wei conversion utilities
└── frontend/                  # React + Vite SPA
    └── src/
        ├── api/               # Fetch wrappers for the REST API
        ├── components/        # Reusable UI components
        ├── contexts/          # React contexts (auth, etc.)
        ├── firebase/          # Firebase SDK initialization
        └── pages/             # Top-level route pages

API server (cmd/api): standard-library net/http with Firebase JWT authentication middleware. Exposes CRUD endpoints for addresses, alert rules, alert events, and notification configuration.

Poller (cmd/poller): long-running daemon that polls Ethereum via JSON-RPC, compares observed transactions against persisted alert rules, fires alert events to the database, and dispatches Discord notifications.

Frontend (frontend/): React 19 SPA built with Vite. Authenticates with Firebase, communicates with the API via fetch, and renders the address/alert management UI.

TODO

• Switch frontend package manager from npm to yarn (per repo policy)
• Rename go.mod module path from github.com/kjannette/koin-ping to sneak.berlin/go/koin-ping (per repo policy)
• Move database migrations to internal/db/migrations/ and embed them in the binary
• Pin all Docker base images by @sha256 in Dockerfile
• Install golangci-lint locally and pass make lint
• Add vitest unit tests for the React frontend
• Add a make db-reset / make migrate target for schema management
• Set HTTP server read/write timeouts (currently unbounded)
• Replace log.Printf calls with structured log/slog

License

MIT. See LICENSE.

Author

Steven Jannette