Contender

High-performance Ethereum transaction spammer and benchmarking tool.

🚀 Quick Start

Install:

cargo install --git https://github.com/flashbots/contender --locked

Run a simple spam scenario:

contender spam --tps 50 -r $RPC_URL fill-block

Run a bundled scenario from the repo:

contender setup scenario:stress.toml -r $RPC_URL -p $PRIVATE_KEY
contender spam  scenario:stress.toml -r $RPC_URL --tps 10 -d 3

See examples for more usage patterns.

Docker Instructions

Fetch the latest image:

docker pull flashbots/contender

Double-check your RPC URL:

export RPC="http://host.docker.internal:8545"
# uncomment if host.docker.internal doesn't work:
# export RPC="http://172.17.0.1:8545"

Run contender in a container with persistent state:

docker run -it -v /tmp/.contender:/root/.local/state/contender \
contender spam --tps 20 -r $RPC transfers

-v maps /tmp/.contender on the host machine to /root/.local/state/contender in the container, which contains the DB; used for generating reports and saving contract deployments.

⚙️ Prerequisites

• Rust toolchain (latest stable)
• SQLite development headers (libsqlite3-dev on Linux)
• A JSON-RPC endpoint for the target Ethereum node

📚 Docs

Contender is a high-performance Ethereum transaction spammer and benchmarking tool, built for repeatable load tests against EL clients and live networks. It supports both per-second (TPS) and per-block (TPB) timing, seeded fuzzing for reproducibility, and SQLite-backed state for contracts, runs, and reports.

1. Introduction

• Overview

2. Getting Started

• Installation
• CLI Reference
• Example Commands

3. Writing Scenarios

• Scenario File Structure
• Placeholders
• Creating a New Scenario
• Constructor Args

4. Advanced Usage

• Engine API Spamming
• Reports, Database, and Admin Tools
• Using Contender as a Library
• Composite Campaigns

5. Internals

• Architecture