purgatory

Purgatory

A local mempool proxy for Ethereum that intercepts, holds, and controls transaction forwarding to upstream nodes. Perfect for debugging, testing, and understanding mempool behavior.

Overview

Purgatory acts as an RPC proxy between your application and an Ethereum node. It intercepts eth_sendRawTransaction calls, stores transactions in a local mempool, and gives you full control over when and how they're forwarded to the actual network.

Key Features

• Transaction Interception: Captures all eth_sendRawTransaction calls
• Gas Price Filtering: Set minimum gas price thresholds
• Auto-Forward Control: Toggle automatic forwarding to upstream node
• Transaction Replacement: Configurable replacement bump requirements (like EIP-1559 pools)
• Batch Operations: Include or drop multiple transactions at once
• REST API: Full mempool management via REST endpoints
• Web Dashboard: Visual UI for monitoring and managing transactions
• Multi-Platform: Deploy on Node.js or Cloudflare Workers

Quick Start

Prerequisites

• Node.js 18+
• pnpm

Installation

npm i purgatory

Using it

purgatory [options]

Options:
  -p, --port <port>    Port to listen on (default: 8545)
  --db <sqlite.db>     Path to SQLite database file (default: in-memory)
  --rpc-url <url>      RPC URL for the upstream Ethereum node
  --reset-db           Reset the database on startup

Architecture

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Your DApp     │────▶│    Purgatory    │────▶│  Ethereum Node  │
│                 │     │   (port 8545)   │     │  (port 8546)    │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                              │
                              ▼
                        ┌───────────┐
                        │  SQLite   │
                        │  Storage  │
                        └───────────┘

API Reference

JSON-RPC Endpoint

POST /

Standard Ethereum JSON-RPC proxy. All methods are forwarded to the upstream node except for intercepted methods:

Intercepted Methods

• eth_sendRawTransaction: Transactions are decoded, validated, and stored in the local mempool. Forwarding depends on the autoForward setting.

• eth_getTransactionByHash: Returns transactions from local mempool if pending locally, otherwise queries upstream.

• eth_getTransactionCount: Accounts for local pending transactions when blockTag is "pending".

REST API

State Management

Method	Endpoint	Description
GET	/api/mempool/state	Get current mempool state
POST	/api/mempool/gas-price	Set minimum gas price
POST	/api/mempool/auto-forward	Enable/disable auto-forwarding
POST	/api/mempool/replacement-mode	Enable/disable transaction replacement
POST	/api/mempool/replacement-bump	Set minimum replacement bump percentage

Transaction Queries

Method	Endpoint	Description
GET	/api/mempool/stats	Get mempool statistics
GET	/api/mempool/pending	List all pending transactions
GET	/api/mempool/history	Get transaction history
GET	/api/mempool/tx/:hash	Get specific transaction
GET	/api/mempool/sender/:address	Get transactions by sender

Transaction Management

Method	Endpoint	Description
POST	/api/mempool/include/:hash	Forward a specific transaction
POST	/api/mempool/drop/:hash	Drop a pending transaction
POST	/api/mempool/include-batch	Forward multiple transactions
POST	/api/mempool/drop-batch	Drop multiple transactions
POST	/api/mempool/flush	Forward all pending transactions
DELETE	/api/mempool/clear	Clear all pending transactions

Health

Method	Endpoint	Description
GET	/health	Health check
GET	/health/upstream	Upstream node health check

Web Dashboard

Access the visual dashboard at /ui to:

• View pending, forwarded, and dropped transactions
• Monitor mempool statistics
• Control auto-forward and gas price settings
• Manually include or drop transactions

Development

Running Tests

# Run all tests
pnpm test

# Run server tests
cd packages/server
pnpm test

Development Mode

# Start with hot reload
pnpm nodejs:dev

# Or run the full local setup with Zellij
pnpm start:nodejs

Formatting

pnpm format        # Format all files
pnpm format:check  # Check formatting

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.