Spamoor
A powerful Ethereum transaction generator for testnets
Install / Use
/learn @ethpandaops/SpamoorREADME
A powerful Ethereum transaction generator for testnets 🚀
Spamoor is a robust transaction spamming tool designed for stress testing, network validation, and continuous transaction testing on Ethereum testnets. With 14+ different transaction scenarios and a powerful web-based daemon mode, it's the ultimate tool for Ethereum network testing.
🚀 Quick Start
CLI Output Example
# 🐳 Using Docker
docker run ethpandaops/spamoor
# 🔧 Building from source
git clone https://github.com/ethpandaops/spamoor.git
cd spamoor
make
./bin/spamoor
📘 Usage
Basic Command Structure
# Run a single scenario
spamoor <scenario> [flags]
# Run multiple scenarios from YAML configuration
spamoor run <yaml-file> [flags]
🔑 Required Parameters
| Parameter | Description |
|-----------|-------------|
| --privkey | Private key for the root wallet (funds child wallets) |
| --rpchost | RPC endpoint(s) to send transactions to |
🔧 Advanced Configuration
# Basic usage
spamoor eoatx --privkey="0x..." --rpchost="http://localhost:8545"
# Multiple RPC endpoints
spamoor eoatx --privkey="0x..." \
--rpchost="http://node1:8545" \
--rpchost="http://node2:8545"
# With authentication
spamoor eoatx --privkey="0x..." \
--rpchost="headers(Authorization:Bearer token)http://node:8545"
💡 See the App User Guide for advanced RPC configuration options
🎯 Transaction Scenarios
Spamoor provides a comprehensive suite of transaction scenarios for different testing needs:
| Scenario | Description |
|----------|-------------|
| eoatx | EOA Transactions - Send standard ETH transfers with configurable amounts |
| erc20tx | ERC20 Transactions - Deploy ERC20 tokens and perform transfers |
| erc721tx | ERC721 Transactions - Deploy ERC721 NFTs and perform transfers |
| erc1155tx | ERC1155 Transactions - Deploy ERC1155 NFTs and perform transfers |
| calltx | Contract Calls - Deploy contracts and repeatedly call functions |
| deploytx | Contract Deployments - Deploy contracts with custom bytecode |
| deploy-destruct | Self-Destruct Deployments - Deploy self-destructing contracts |
| setcodetx | Set Code Transactions - EIP-7702 setcode transactions |
| uniswap-swaps | Uniswap Swaps - Deploy and test Uniswap V2 token swaps |
| blobs | Blob Transactions - Send blob transactions with random data |
| blob-average | Blob Average - Maintain network-wide average blob count per block |
| blob-replacements | Blob Replacements - Test blob transaction replacement |
| blob-conflicting | Conflicting Blobs - Test conflicting blob/normal transactions |
| blob-combined | Combined Blob Testing - Randomized blob scenario combinations |
| gasburnertx | Gas Burner - Burn specific amounts of gas |
| storagespam | Storage Spam - Stress test EVM storage |
| geastx | Geas Transactions - Execute custom geas bytecode |
| xentoken | XEN Sybil Attack - Simulate XEN token sybil attacks |
| taskrunner | Task Runner - Execute configurable task sequences with init and execution phases |
🚄 Run Command - Execute Multiple Scenarios
The spamoor run command allows you to execute multiple scenarios concurrently from a YAML configuration file, without needing the full daemon infrastructure.
Usage
spamoor run <yaml-file> [flags]
Flags
| Flag | Short | Description |
|------|-------|-------------|
| --spammers | -s | Indexes of spammers to run (e.g., -s 0,2). If not specified, runs all |
| --privkey | -p | Private key for the root wallet |
| --rpchost | -h | RPC endpoints (multiple allowed) |
| --rpchost-file | - | File containing RPC endpoints |
| --verbose | -v | Enable verbose logging |
| --trace | - | Enable trace logging |
Example Configuration
# example-run-config.yaml
- scenario: eoatx
name: "High Volume ETH Transfers"
description: "Basic ETH transfers with 400 tx/slot throughput"
config:
seed: eoatx-demo
refill_amount: 1000000000000000000 # 1 ETH in wei
refill_balance: 500000000000000000 # 0.5 ETH in wei
refill_interval: 600 # 10 minutes
throughput: 400
max_pending: 800
max_wallets: 200
base_fee: 20 # gwei
tip_fee: 2 # gwei
amount: 100 # 100 wei per transfer
random_amount: true
random_target: true
- scenario: erctx
name: "ERC20 Token Spammer"
description: "Deploy and transfer ERC20 tokens"
config:
seed: erctx-demo
refill_amount: 2000000000000000000 # 2 ETH
refill_balance: 1000000000000000000 # 1 ETH
throughput: 100
max_pending: 200
max_wallets: 100
amount: 50
random_amount: true
# Include other configuration files
- include: ./high-load-configs.yaml
Examples
# Run all spammers from configuration
spamoor run config.yaml -h http://localhost:8545 -p 0x...
# Run only specific spammers (0-based indexes)
spamoor run config.yaml -h http://localhost:8545 -p 0x... -s 0,2
# With multiple RPC endpoints
spamoor run config.yaml -p 0x... \
-h http://node1:8545 \
-h http://node2:8545
🖥️ Daemon Mode
Run Spamoor as a daemon with a powerful web interface for managing multiple concurrent spammers.
🚀 Starting the Daemon
spamoor-daemon [flags]
⚙️ Configuration Flags
| Flag | Short | Description | Default |
|------|-------|-------------|---------|
| --db | -d | Database file location | spamoor.db |
| --rpchost | -h | RPC endpoints (multiple allowed) | - |
| --rpchost-file | - | File containing RPC endpoints | - |
| --privkey | -p | Root wallet private key | - |
| --port | -P | Web UI port | 8080 |
| --startup-spammer | - | YAML file or URL with startup spammers | - |
| --startup-delay | - | Delay in seconds before starting spammers on startup | 30 |
| --fulu-activation | - | Unix timestamp of Fulu activation | 0 |
| --without-batcher | - | Disable transaction batching | false |
| --disable-tx-metrics | - | Disable transaction metrics collection | false |
| --verbose | -v | Enable verbose logging | false |
| --debug | - | Enable debug mode | false |
| --trace | - | Enable trace logging | false |
🌐 Web Interface Features
Access the web UI at http://localhost:8080 for:
📊 Dashboard - Real-time Spammer Management
- View all spammers at a glance with their status, scenario type, and actions
- Mass actions for bulk operations on multiple spammers
- Quick access to start, stop, edit, and delete spammers
- Expandable live logs for each spammer
💰 Wallets Overview
- Monitor wallet balances and transaction counts
- Track child wallets spawned from the root wallet
- Real-time balance updates
🔧 Client Management
- View and manage RPC client connections
- Group clients for load balancing
- Enable/disable clients dynamically
- Monitor client status and block height
📈 Performance Graphs
- Visual monitoring of transaction throughput
- Success/failure rates per spammer
- Network performance metrics
🔌 REST API
The daemon exposes a comprehensive REST API for automation:
Key Endpoints
-
📡 Client Management
GET /api/clients- List all RPC clientsPUT /api/client/{index}/groups- Update client groupsPUT /api/client/{index}/name- Set custom display name
-
🤖 Spammer Control
GET /api/spammers- List all spammersPOST /api/spammer- Create new spammerPUT /api/spammer/{id}/start- Start spammerPUT /api/spammer/{id}/pause- Pause spammer
-
💾 Import/Export
GET /api/export- Export configurationsPOST /api/import- Import configurations
📚 Full API documentation available at /docs when daemon is running
📦 Import/Export System
🎯 Create New Spammer Dialog
- Select from 13+ pre-configured scenarios
- Customize configuration with YAML editor
- Real-time YAML validation
- Access to pre-built configuration library
Export Configurations
# Export all spammers to YAML
curl http://localhost:8080/api/export > my-spammers.yaml
Import Configurations
Import dialog showing YAML validation and configuration options
*Pre-built con
