Real-time mempool monitoring for any EVM-compatible blockchain with a React frontend and Python analysis tools.

• 🔄 Real-time monitoring - WebSocket-based live transaction feed using viem
• ⛓️ Multi-chain support - Ethereum, Base, Arbitrum, Optimism, Polygon, and any EVM chain
• 💾 Persistent storage - PostgreSQL database for historical analysis
• 🎨 Modern React dashboard - Live updates, filtering, and comprehensive statistics
• 📊 Python analytics - Advanced transaction analysis with pandas and matplotlib
• 🧪 Comprehensive tests - 32 passing tests with 70% coverage threshold
• 🚀 Production ready - Docker Compose, CI/CD, and security best practices

┌─────────────────┐     WebSocket     ┌──────────────────┐
│  EVM RPC Node   │◄─────────────────►│  TypeScript      │
│  (configurable) │                   │  Backend (viem)  │
└─────────────────┘                   └────────┬─────────┘
                                               │
                                               ▼
                                      ┌──────────────────┐
                                      │   PostgreSQL     │
                                      └────────┬─────────┘
                                               │
                    ┌──────────────────────────┼──────────────────────────┐
                    │                          │                          │
                    ▼                          ▼                          ▼
           ┌──────────────┐           ┌──────────────┐           ┌──────────────┐
           │React Frontend│           │ REST API     │           │ Python       │
           │(real-time)   │◄─────────►│ (Express)    │           │ Analysis     │
           └──────────────┘  WebSocket└──────────────┘           └──────────────┘

• Node.js 18+
• Docker & Docker Compose
• Python 3.10+ (for analysis scripts)
• WebSocket-enabled RPC endpoint (QuickNode, Alchemy, etc.)

docker-compose up -d

# Backend
cp backend/.env.example backend/.env
# Edit backend/.env with your RPC WebSocket URLs

# Frontend (optional)
cp frontend/.env.example frontend/.env

cd backend
npm install
npx prisma generate
npx prisma migrate dev
npm run dev

cd frontend
npm install
npm run dev

Open http://localhost:5173

Configure your provider in backend/.env.

Recommended: Use a Provider Simplifies setup by requiring only one API key for multiple chains.

PROVIDER=alchemy
ALCHEMY_API_KEY=your_alchemy_key

# Chains configuration (URLs auto-generated)
CHAIN_1_NAME=ethereum
CHAIN_1_ID=1
CHAIN_2_NAME=base
CHAIN_2_ID=8453

Legacy: Manual Configuration You can still specify WebSocket URLs manually if needed.

CHAIN_1_NAME=custom
CHAIN_1_ID=123
CHAIN_1_WS_URL=wss://...

Any EVM chain works - just provide the correct chain ID and WebSocket URL.

GET /api/transactions supports:

• chainId - Filter by chain
• from - Filter by sender address
• to - Filter by recipient address
• status - Filter by status (pending/confirmed/dropped)
• limit - Results per page (max 100)
• offset - Pagination offset

cd analysis
pip install -r requirements.txt
cp .env.example .env
# Edit .env with DATABASE_URL

# Full report
python analyze.py --hours 24 --report full

# Specific reports
python analyze.py --report gas
python analyze.py --report senders --limit 20
python analyze.py --report value
python analyze.py --chain 8453 --report overview

• full - Complete analysis
• overview - Transaction summary
• gas - Gas price statistics
• senders - Top senders
• recipients - Top recipients
• time - Hourly distribution
• value - Value analysis

mempool/
├── backend/                # TypeScript backend
│   ├── src/
│   │   ├── index.ts       # Entry point
│   │   ├── mempool/       # Watcher logic
│   │   ├── api/           # REST routes
│   │   ├── websocket/     # WS broadcaster
│   │   ├── db/            # Prisma client
│   │   └── config/        # Chain config
│   └── prisma/            # Database schema
├── frontend/              # React frontend
│   └── src/
│       ├── components/    # UI components
│       ├── hooks/         # React hooks
│       └── types/         # TypeScript types
├── analysis/              # Python scripts
└── docker-compose.yml     # PostgreSQL

cd backend
npm run dev        # Development with hot reload
npm run build      # Build for production
npm run lint       # ESLint
npm run db:migrate # Run migrations

cd frontend
npm run dev      # Development server
npm run build    # Production build
npm run preview  # Preview production build

This project has comprehensive test coverage across both backend and frontend:

# Backend tests (21 passing)
cd backend && npm test
npm run test:coverage    # Generate coverage report

# Frontend tests (11 passing)  
cd frontend && npm test
npm run test:ui          # Open Vitest UI

Test Coverage:

• ✅ Backend: Type conversions, chain configuration, validation logic
• ✅ Frontend: Component rendering, user interactions, state management
• 🎯 Coverage target: 70% minimum (critical paths >90%)

Contributions are welcome! Please see CONTRIBUTING.md for:

• Development setup
• Code style guidelines
• Testing requirements
• Pull request process

The project is configured for automated deployment to a VPS using GitHub Actions.

• A DigitalOcean Droplet (or similar VPS)
• SSH access to the VPS
• Docker & Docker Compose installed on VPS

Add the following secrets to your GitHub repository (Settings > Secrets and variables > Actions):

The deployments use the following ports:

• Backend: Port 3002 (Mapped to container 3001)
• Frontend: Port 3003 (Mapped to container 80)

Ensure these ports are open on your firewall:

ufw allow 3002/tcp
ufw allow 3003/tcp

This project is licensed under the MIT License - see the LICENSE file for details.

• viem - TypeScript blockchain library
• Prisma - Next-generation ORM
• Vitest - Blazing fast unit test framework
• Research inspiration from BlockJayn and Gasflow

Made with ❤️ for the Ethereum ecosystem