37ff644aa7
- #1: remove mock alert events that poisoned production responses - #2: add Notifier interface + Send implementations for all channels - #3/#4: notification goroutines now carry a 30s context timeout and retry up to 3x with exponential backoff - #5: schedule email digest in poller via DIGEST_INTERVAL_HOURS (default 24h) - #6: SystemStatus queries real checkpoint data; returns starting/active/idle with latestBlock and lag - #7: Ethereum RPC client retries on network errors, 429, and 5xx with 1s/2s backoff - #8: alert_events dedup index + ON CONFLICT DO NOTHING to prevent duplicate events on poller restart - #9: PATCH /v1/addresses/{id} for label editing; frontend address list gains inline edit and remove buttons
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-lintv2 (formake 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.
License
MIT. See LICENSE.
Author
Steven Jannette