Crypto Wallet Tracker

A privacy-conscious monitoring platform that tracks Ethereum wallet activity, pushes alerts through a Telegram-powered login flow, and exposes a responsive React dashboard for invite-only users.

This is intentionally a MERN stack app to practice my abilties.

Website Dashboard

Telegram Alerts

Getting started

Prerequisites

• Node 20+ / npm (TypeScript/Vite expectations).
• Docker & Docker Compose (for containerized mode).
• Access to an Ethereum RPC endpoint (publicnode, Alchemy, etc.).

Install dependencies

npm install                      # root tooling (Biome)
cd server && npm install         # API + watcher
cd ../client && npm install      # Vite frontend

Environment variables

Server (server/.env or process env)

Name	Required	Description
MONGO_URI	✅	MongoDB connection string the watcher uses.
RPC_URL	✅	Ethereum RPC the watcher polls (e.g., https://ethereum-rpc.publicnode.com).
CLIENT_URL	❌	Frontend URL for magic links (default http://localhost:5173).
PORT	❌	API port (default 4000).
ALLOWED_ORIGINS	❌	Comma-separated origins allowed by CORS (defaults to CLIENT_URL).
TELEGRAM_TOKEN	❌	Telegram bot token to enable /start login links. Without it Telegram features are skipped.
INVITE_CODE	❌	Set it to enable invite-only access; leaving empty lets first Telegram user get auto-allowed.
SESSION_TTL_MS	❌	Magic-link TTL (default 2h; min 5m).
START_BLOCK_NUMBER	❌	Optional starting block for the watcher to seed watcherMetrics.

Client (client/.env or build args)

Name	Required	Description
VITE_API_URL	❌	API base URL; defaults to http://localhost:4000/api. Docker Compose passes it into the build.

Run locally

1. Start the API:

   cd server
   npm run dev

2. In a separate shell, start the frontend:

   cd client
   npm run dev

3. Visit http://localhost:5173 (or your Vite dev port) and request a Telegram magic link via /login.
4. Observe /health on the API for uptime, watcher lag, and block metrics.

Docker Compose (production-style)

docker compose up --build
docker compose down

• MongoDB listens on 27017, API on 4000, and client on 4173.
• Build args and env fall back to repo defaults; supply RPC_URL, TELEGRAM_TOKEN, and optional INVITE_CODE via shell when launching.

Testing & quality

• server: npm run test runs Vitest integration/unit suites with V8 coverage.
• biome format && biome check at the repo root keep formatting and linting aligned.

Security & observability

• Helmet, CSRF middleware, and HTTP-only cookies protect authentication flows.
• Rate limiters guard API, session creation, and invite submissions.
• Pino logs plus /health expose watcher lag, processed blocks, and telemetry for automation.
• Graceful shutdown closes MongoDB, Telegram polling, and the watcher before exiting.

License

MIT