Ethereum Transactions API v1.0.0

A high-performance Rust application for monitoring and storing Ethereum blockchain transactions and mempool data.

Features

• Mempool Monitoring: Real-time tracking of pending transactions in the Ethereum mempool
• Transaction Polling: Continuous polling of confirmed blockchain transactions
• PostgreSQL Storage: Persistent storage with efficient querying capabilities
• REST API: JSON API with pagination, filtering, and statistics endpoints
• OpenAPI Documentation: Auto-generated API documentation at /openapi.json
• Prometheus Metrics: Built-in metrics endpoint for monitoring
• Rate Limiting: Configurable rate limiting (100 req/min with burst of 20)
• Graceful Shutdown: Proper handling of SIGINT/SIGTERM signals
• Structured Logging: Comprehensive logging to console and file

Prerequisites

• Rust: 1.71+
• PostgreSQL: 14+
• Ethereum RPC: Access to an Ethereum JSON-RPC endpoint (e.g., Infura, Alchemy, local node)
• Docker (optional): For containerized deployment

Quick Start with Docker

# Set your Ethereum RPC URL
export ETHEREUM_RPC_URL="https://mainnet.infura.io/v3/YOUR_PROJECT_ID"

# Start the application with PostgreSQL
docker compose up --build

# Or run in detached mode
docker compose up --build -d

# View logs
docker compose logs -f app

Docker Commands

# Build the image only
docker build -t eth-txs-api .

# Stop all services
docker compose down

# Stop and remove volumes (WARNING: deletes data)
docker compose down -v

# Rebuild after code changes
docker compose up --build

Local Development

1. Start PostgreSQL

docker compose -f docker-compose.psql.yaml up -d

2. Configure Environment

cp .env.example .env

Edit .env:

POSTGRESQL_DSN=postgresql://ethtxs_user:ethtxs_password@localhost:6789/ethtxs?sslmode=disable
ETHEREUM_RPC_URL=https://mainnet.infura.io/v3/YOUR_PROJECT_ID
SERVER_PORT=8080

3. Build and Run

# Build
cargo build --release

# Run
cargo run --release

# Run with custom config
cargo run --release -- --config configs/config.toml

4. Run Tests

cargo test

API Endpoints

Endpoint	Description
GET /api/health	Health check
GET /api/v1/mempool/stats	Mempool statistics
GET /api/v1/mempool/latest	Latest mempool transactions
GET /api/v1/txs/stats	Transaction statistics
GET /api/v1/txs/latest	Latest confirmed transactions
GET /metrics	Prometheus metrics
GET /openapi.json	OpenAPI specification

Query Parameters

For /mempool/latest and /txs/latest:

Parameter	Type	Description
limit	u32	Max results (default: 100, max: 1000)
offset	u32	Pagination offset
from	string	Start date (RFC3339 format)
to	string	End date (RFC3339 format)
min_gas	i64	Minimum gas (txs only)

Configuration

Environment Variables

Variable	Description	Default
POSTGRESQL_DSN	PostgreSQL connection string	postgresql://ethtxs_user:ethtxs_password@localhost:6789/ethtxs?sslmode=disable
ETHEREUM_RPC_URL	Ethereum JSON-RPC endpoint	http://localhost:8545
SERVER_PORT	HTTP server port	8080

Configuration File

See configs/config.toml:

# Mempool polling
sync_interval_mempool = 60          # Seconds between polls
mempool_retention_seconds = 3600    # Data retention period
enable_mempool = true

# TX Poller  
number_of_historical_blocks = 10    # Historical blocks to backfill
sync_interval_check_for_latest_backfill = 10
enable_tx_poller = true

# Logging
log_level = "INFO"

Configuration Priority

1. Default values
2. Configuration file (via --config)
3. Environment variables

CLI Options

eth-txs-api [OPTIONS]

Options:
  -c, --config <FILE>    Path to config file [default: configs/config.toml]
  -h, --help             Print help
  -V, --version          Print version

Database Schema

mempool_data

Stores pending mempool transactions.

Column	Type	Description
hash	TEXT	Transaction hash (PK)
pool_state	TEXT	pending/queued
from_address	TEXT	Sender address
to_address	TEXT	Recipient address
value_wei	TEXT	Value in wei
value_eth	TEXT	Value in ETH
gas	BIGINT	Gas limit
gas_price	TEXT	Gas price
method_id	TEXT	Function selector
updated_at	TEXT	Last update time

tx_data

Stores confirmed blockchain transactions.

Column	Type	Description
hash	TEXT	Transaction hash (PK)
block_number	BIGINT	Block number
block_hash	TEXT	Block hash
from_address	TEXT	Sender address
to_address	TEXT	Recipient address
value	TEXT	Value in wei
gas_price	TEXT	Gas price
gas	BIGINT	Gas used
miner	TEXT	Block miner
timestamp	BIGINT	Block timestamp
created_at	TEXT	Record creation time

Migrations

Migrations are auto-applied on startup from migrations/:

• 001_create_mempool_data_table.sql
• 002_alter_numeric_to_text.sql
• 003_create_tx_data_table.sql
• 004_alter_tx_data_numeric_to_text.sql
• 005_add_api_indexes.sql

Logging

Logs are written to stdout and logs/ directory.

Configure via:

• Config file: log_level = "INFO"
• Environment: RUST_LOG=info

Levels: TRACE, DEBUG, INFO, WARN, ERROR

Project Structure

src/
├── api/           # HTTP handlers, routes, models
├── config/        # Configuration loading, constants
├── models/        # Data models
├── services/      # Business logic, database, polling
└── main.rs        # Application entry point

tests/
├── integration/   # API integration tests
└── unit/          # Unit tests

migrations/        # SQL migration files
configs/           # Configuration files

License

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.