migrating repo from old host server

2026-08-22 18:58:55 -04:00
commit 4968d7f575
153 changed files with 20009 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,157 @@
+# Koin Ping: Blockchain intelligence - - 2025-2026 @sjDev - LICENSE: MIT
+
+A lightweight on-chain monitoring and alerting system designed to give users situational awareness over blockchain addresses they care about.
+
+# Overview
+
+Koin Ping observes on-chain activity and notifies users when predefined conditions are met. It does not execute transactions, manage wallets, or speculate on prices.
+
+## 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
+
+```bash
+# 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/.env.example backend/.env
+# edit backend/.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 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 for development.
+
+## Rationale
+
+Crypto users may actively monitor addresses with webhooks integrating popular 
+messaging platforms: Discord, Slack, Telegram.
+This lightweight, reliable framework makes instant awareness of on-chain 
+activity trivial, without polling block explorers manually. Koin Ping watches 
+addresses, evaluates configurable alert rules (incoming transactions, outgoing 
+transactions, "large" transfers, balance thresholds), and sends notifications.
+
+## Design
+
+The system is split into two independently deployable processes and one
+frontend:
+
+```
+koin_ping_0.2.0/
+├── backend/                # 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.
+
+## Setting Up Your Alert Platforms
+
+Koin Ping can send real-time alerts to **Telegram**, **Discord**, **Slack**, and **Email**. Each channel is configured per-user through the **Notification Settings** panel on the Alerts page.
+
+Below are step-by-step guides for setting up each platform.
+
+---
+
+### Telegram
+
+To receive alerts via Telegram, you need to create a bot and get your chat ID.
+
+#### 1. Create a Telegram Bot
+
+1. Open Telegram and search for **@BotFather** (look for the blue verified checkmark).
+2. Open the conversation with BotFather and send: `/newbot`
+3. BotFather will ask for a **display name** — enter something like `Koin Ping Alerts`.
+4. BotFather will ask for a **username** — it must end in `bot`, e.g. `MyKoinPingBot`.
+5. BotFather will reply with your **Bot Token** — a string that looks like `123456789:ABCdefGHIjklMNOpqrSTUvwxYZ`. Copy it.
+
+#### 2. Get Your Chat ID
+
+1. In Telegram, search for the bot username you just created and open the chat.
+2. Tap **Start** or send any message (e.g. `hello`).
+3. Open the following URL in your browser, replacing `YOUR_BOT_TOKEN` with the token from step 1:
+
+   ```
+   https://api.telegram.org/botYOUR_BOT_TOKEN/getUpdates
+   ```
+
+4. In the JSON response, find the `"chat"` object — the `"id"` field is your **Chat ID** (a numeric value).
+
+   > **Tip:** If the `'result"` array is empty, make sure you sent a message to your bot first, then refresh the page.
+
+#### 3. Save in Koin Ping
+
+1. Go to the **Alerts** page in Koin Ping.
+2. In the **Notification Settings** panel, find the **Telegram** section.
+3. Paste your **Bot Token** and **Chat ID** into the corresponding fields.
+4. Click **Save Settings**.
+5. Click **Test All Channels** to verify — you should receive a test message from your bot in Telegram.
+
+---
+
+*Guides for Discord, Slack, and Email coming soon.*
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Author
+
+Steven Jannette
+
+