231 lines
8.4 KiB
Markdown
231 lines
8.4 KiB
Markdown
# Koin Ping
|
|
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-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.
|
|
|
|
## 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.
|
|
|
|
---
|
|
|
|
### Discord
|
|
|
|
To receive alerts in a Discord channel, you need to create a webhook.
|
|
|
|
#### 1. Create a Discord Webhook
|
|
|
|
1. Open **Discord** and navigate to the server where you want to receive alerts.
|
|
2. Go to the channel you want alerts posted in (or create a new one, e.g. `#koin-alerts`).
|
|
3. Click the **gear icon** next to the channel name to open **Channel Settings**.
|
|
4. Go to **Integrations** > **Webhooks**.
|
|
5. Click **New Webhook**.
|
|
6. Give it a name (e.g. `Koin Ping`) and click **Copy Webhook URL**.
|
|
|
|
The URL will look like: `https://discord.com/api/webhooks/123456789/AbCdEfGhIjKl...`
|
|
|
|
#### 2. Save in Koin Ping
|
|
|
|
1. Go to the **Alerts** page in Koin Ping.
|
|
2. In the **Notification Settings** panel, find the **Discord** section.
|
|
3. Paste your **Webhook URL** into the field.
|
|
4. Click **Save Settings**.
|
|
5. Click **Test All Channels** to verify — you should see a test message appear in your Discord channel.
|
|
|
|
---
|
|
|
|
### Slack
|
|
|
|
To receive alerts in a Slack channel, you need to create an Incoming Webhook.
|
|
|
|
#### 1. Create a Slack App with Incoming Webhooks
|
|
|
|
1. Go to [https://api.slack.com/apps](https://api.slack.com/apps) and click **Create New App**.
|
|
2. Choose **From scratch**, give it a name (e.g. `Koin Ping`), and select your workspace.
|
|
3. In the app settings, go to **Incoming Webhooks** in the left sidebar.
|
|
4. Toggle **Activate Incoming Webhooks** to **On**.
|
|
5. Click **Add New Webhook to Workspace**.
|
|
6. Select the channel where you want alerts posted (e.g. `#koin-alerts`) and click **Allow**.
|
|
7. Copy the **Webhook URL** — it will start with `https://hooks.slack.com/services/...`
|
|
|
|
#### 2. Save in Koin Ping
|
|
|
|
1. Go to the **Alerts** page in Koin Ping.
|
|
2. In the **Notification Settings** panel, find the **Slack** section.
|
|
3. Paste your **Webhook URL** into the field.
|
|
4. Click **Save Settings**.
|
|
5. Click **Test All Channels** to verify — you should see a test message appear in your Slack channel.
|
|
|
|
---
|
|
|
|
### Email
|
|
|
|
Koin Ping sends email alerts and digests via [Resend](https://resend.com). To enable email notifications, the application owner must configure a Resend account and verified sending domain.
|
|
|
|
#### For Application Owners (Deployment Setup)
|
|
|
|
1. Create an account at [resend.com](https://resend.com).
|
|
2. Go to [resend.com/domains](https://resend.com/domains) and add your sending domain.
|
|
3. Add the DNS records Resend provides (SPF, DKIM, etc.) to your domain's DNS settings.
|
|
4. Once verified, create an API key at [resend.com/api-keys](https://resend.com/api-keys).
|
|
5. Set the following in your `.env` file:
|
|
|
|
```
|
|
RESEND_API_KEY=re_your_api_key_here
|
|
EMAIL_FROM=Your App <alerts@yourdomain.com>
|
|
```
|
|
|
|
6. Restart the API server and poller to pick up the changes.
|
|
|
|
#### For Users
|
|
|
|
1. Go to the **Alerts** page in Koin Ping.
|
|
2. In the **Notification Settings** panel, find the **Email** section.
|
|
3. Enter the email address where you want to receive alerts.
|
|
4. Click **Save Settings**.
|
|
5. Click **Verify Email** to receive a confirmation message.
|
|
6. Click **Test All Channels** to verify — you should receive a test alert at your email address.
|
|
|
|
## License
|
|
|
|
MIT. See [LICENSE](LICENSE).
|
|
|
|
## Author
|
|
|
|
Steven Jannette
|