Pioneer Watchtower

Real-time blockchain transaction monitoring via Blockbook WebSocket.

Features

• ✅ Multi-Chain Support: 12 blockchains via Blockbook
  • UTXO: BTC, LTC, DOGE, BCH, DASH, QTUM
  • EVM: ETH, BSC, BASE, MATIC, AVAX, ARB
• ✅ Real-Time Monitoring: WebSocket-based transaction detection
• ✅ Redis Integration: Pub/sub for user connection events and transaction broadcasts
• ✅ Reference Counting: Efficient address subscription management
• ✅ Health Monitoring: RESTful health check endpoint
• ✅ Auto-Reconnection: Resilient connection handling
• ✅ TypeScript: Full type safety and modern development experience

Quick Start

# Install dependencies
npm install

# Development (with auto-reload)
npm run dev

# Production build
npm run build
npm start

Environment Variables

Create a .env file:

NOW_NODES_API=your_api_key_here
REDIS_URL=redis://localhost:6379
HEALTH_PORT=19646

Testing

Automated Test Suite

We provide comprehensive test modules for all supported chains:

# Run comprehensive multi-chain test
node __tests__/test-module.js

# Run Bitcoin-specific payment test
node __tests__/payments/test-bitcoin-input.js

Test Features:

• ✅ Automated address registration for all 12 chains
• ✅ Real-time transaction event monitoring
• ✅ Health check validation
• ✅ Event logging to file
• ✅ Manual testing instructions
• ✅ Comprehensive test fixtures (36 addresses across 12 chains)

See tests/README.md for detailed testing guide.

Manual Testing

1. Add test address to Redis

redis-cli SADD user:test:addresses:BTC bc1qnjwxq90ugvp6aza2mal6fl2kx2gnccy28448ka

2. Trigger subscription

redis-cli PUBLISH connections '{"type":"user_connect","username":"test"}'

3. Monitor transaction events

redis-cli SUBSCRIBE pioneer:tx:BTC

4. Send test transaction

Send 0.0001 BTC to bc1qnjwxq90ugvp6aza2mal6fl2kx2gnccy28448ka

5. Health check

curl http://localhost:19646/health | jq

Architecture

• Redis Listener: Subscribes to connections channel for user connect/disconnect events
• Blockbook WebSocket: Maintains persistent WebSocket connections to Blockbook for all 12 chains
• Refcount Manager: Tracks address subscriptions to prevent duplicates and optimize resources
• Event Publisher: Publishes transaction events to pioneer:tx:{SYMBOL} Redis channels (BTC, ETH, etc.)
• Multi-Chain State: Independent state management per chain for reliability

Message Formats

Input: User Connect

{
  "type": "user_connect",
  "username": "alice"
}

Output: Transaction Event

{
  "chain": "BTC",
  "address": "bc1q...",
  "txid": "abc123...",
  "value": "50000000",
  "confirmations": 0,
  "blockHeight": 800000,
  "timestamp": 1704067200000
}

Deployment

Systemd Service

[Unit]
Description=Pioneer Watchtower
After=network.target redis.service

[Service]
Type=simple
WorkingDirectory=/opt/pioneer-watchtower
ExecStart=/usr/bin/node dist/index.js
Restart=always
RestartSec=10
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target

Docker

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --production
COPY tsconfig.json ./
COPY src ./src
RUN npm run build
CMD ["node", "dist/index.js"]

License

MIT