⚡ Blockpulse

Ethereum contract watcher with Redis cache invalidation.

Blockpulse listens to new blocks, detects transactions to your contracts, and instantly deletes the affected Redis keys — so your next request always hits the RPC with fresh data. Cache TTL can be infinite; invalidation is event-driven, not time-based.

---

💡 The Key Insight

Most backends cache contract reads with a 60-second TTL: stale for 60 seconds by design.

Blockpulse flips the model:

Without Blockpulse                  With Blockpulse
──────────────────────              ────────────────────────────
cache(balance, TTL=60s)             cache(balance, TTL=∞)
→ stale for up to 60s               → stale only between tx and next block
→ RPC call every 60s regardless     → RPC call only when state actually changed

Scenario	60s TTL	Blockpulse (TTL=0)
No activity, 1h	60 RPC calls	0 RPC calls
1 tx per minute	60 RPC calls	1 RPC call
10 tx per second	60 RPC calls	10 RPC calls

---

🏗️ Architecture

  Ethereum Node
  (WebSocket / HTTP)
        │
        ▼
  ┌─────────────┐     new block / tx
  │  Blockpulse │ ──────────────────────────► Redis DEL
  │   watcher   │                             (configured key patterns)
  └──────┬──────┘
         │
         ▼
  ┌─────────────┐
  │ Health API  │  :3002
  │  REST + WS  │  /health · /api/call · /api/events · /api/batch
  └──────┬──────┘
         │
         ▼
  ┌──────────────┐
  │    Redis     │  TTL=0, invalidated on tx
  └──────────────┘

---

✨ Features

• 🔴 Event-driven invalidation — Redis keys deleted on every matching transaction; no fixed TTL needed
• 📜 Event & transaction indexing — stores decoded logs and tx history per contract in Redis
• 🌐 REST API — /api/call, /api/batch, /api/events, /api/transactions, /api/eth/getBalance
• 📡 Historical sync — backfills past events via Etherscan-compatible API on startup
• 🔗 Cache dependencies — invalidate contract B's keys whenever contract A changes
• 🔁 Event dependencies — re-index contract B's events when contract A triggers them (e.g. DEX swaps → token Transfer)
• 🔍 fullScan mode — scan every block for token transfers regardless of to address (DEX-transferred tokens)
• 🎯 Pool ID filtering — index only specific Uniswap V4 pool IDs
• ⛓️ Multi-chain — Ethereum, Polygon, Arbitrum, Base, or any EVM chain via CHAIN_ID
• 💓 WebSocket health broadcast — real-time status stream on port HEALTH_BROADCAST_PORT+1

---

🚀 Quick Start

Docker Compose

cp .env.example .env
cp config/config.example.js config/config.js
# edit .env and config/config.js

docker compose up
# health: http://localhost:3002/health

Native

npm install
cp .env.example .env
cp config/config.example.js config/config.js
# edit .env and config/config.js

npm start

---

⚙️ Configuration

Environment variables (.env)

Variable	Required	Default	Description
REDIS_URL	✅	—	Redis connection URL
RPC_WS_URL	✅	—	WebSocket RPC endpoint
RPC_HTTP_URL	✅	—	HTTP RPC endpoint
CHAIN_ID	—	1	Chain ID (1=mainnet, 137=polygon, 42161=arbitrum, 8453=base…)
ETHERSCAN_API_KEY	—	—	For historical sync
ETHERSCAN_API_URL	—	etherscan.io	Etherscan-compatible API URL
START_BLOCK	—	0	Starting block for historical sync
HEALTH_BROADCAST_PORT	—	3002	HTTP API port (WS is port+1)
LOG_LEVEL	—	info	debug / info / warn / error
USE_WS	—	—	Set to 1 to force WebSocket mode (default: HTTP polling)

Contract config (config/config.js)

module.exports = {
  contracts: [
    {
      address: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      name: "usdc",
      abi: require("./abis/usdc.json"),       // optional: enables /api/call + event decoding
      events: ["Transfer", "Approval"],        // optional: events to index
      fullScan: false,                         // true = scan every block (for DEX-transferred tokens)
      cacheKeys: [                             // Redis patterns to delete on any tx to this contract
        "myapp:balance:*",
        "myapp:token:usdc:*"
      ]
    }
  ],

  // Invalidate contract B's keys whenever contract A changes
  cacheDependencies: {
    "myPool": ["usdc"]
  },

  // Re-index contract B's events whenever contract A changes
  // (e.g. DEX swap triggers token Transfer on a different contract)
  eventDependencies: {
    "myPool": ["usdc"]
  },

  settings: {
    blockConfirmations: 1,     // wait N blocks before processing
    cacheTTL: 0                // 0 = no TTL, pure event-driven invalidation
  }
};

---

🌐 REST API

All endpoints are on http://localhost:${HEALTH_BROADCAST_PORT} (default 3002).

Health & status

Method	Path	Description
GET	/health	Liveness — always 200; includes Redis stats
GET	/ready	Readiness — 503 if Redis not connected
GET	/api/contracts	List all watched contracts

Contract calls (cached)

Method	Path	Description
GET	/api/call/:contract/:method?args=[...]	Call a contract method, result cached in Redis
GET	/api/call/:contract/:method?noCache=1	Bypass cache (time-dependent methods)
POST	/api/batch	Multiple calls in one request
GET	/api/eth/getBalance?address=0x...	ETH balance, cached

Indexed data

Method	Path	Description
GET	/api/events/:address?event=Transfer&page=1&limit=25	Decoded event logs
GET	/api/transactions/:address?page=1&limit=25	Transaction history

Cache management

Method	Path	Description
POST	/api/renewCache/:name	Invalidate + re-index a contract
POST	/api/invalidateCache/:name	Invalidate only (no re-index)
POST	/api/resync	Full re-index from START_BLOCK

Batch call example

curl -X POST http://localhost:3002/api/batch \
  -H "Content-Type: application/json" \
  -d '[
    {"contract": "usdc", "method": "totalSupply"},
    {"contract": "usdc", "method": "balanceOf", "args": ["0x..."]},
    {"contract": "usdc", "method": "decimals", "noCache": false}
  ]'

---

💓 WebSocket Health Stream

Connect to ws://localhost:3003 (port+1) to receive real-time health broadcasts:

const ws = new WebSocket('ws://localhost:3003');
ws.onmessage = (e) => console.log(JSON.parse(e.data));
// { status, blockNumber, watchedContracts, uptime, redis, ... }

---

🐳 Docker

FROM node:20-alpine
# ...
HEALTHCHECK CMD node -e "require('http').get('http://localhost:${HEALTH_BROADCAST_PORT:-3002}/health', ...)"

The container exposes both the HTTP API port and the WebSocket port (port+1). Mount your config/config.js as a volume or bake it into a custom image.

---

📄 License

MIT — free for commercial use. See LICENSE.