From b8123222f4da189223ace509a8b20e887bb6e049 Mon Sep 17 00:00:00 2001
From: zeroXbrock <2791467+zeroXbrock@users.noreply.github.com>
Date: Fri, 12 Dec 2025 11:16:42 -0500
Subject: [PATCH] add contender instructions to readme

---
 README.md | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/README.md b/README.md
index 5d7f81a..477ed63 100644
--- a/README.md
+++ b/README.md
@@ -76,6 +76,31 @@ Here's a complete example showing how to run the L1 recipe with the latest fork
 $ builder-playground cook l1 --latest-fork --output ~/my-builder-testnet --genesis-delay 15 --log-level debug
 ```
 
+### Generate transaction flow with contender
+
+builder-playground can generate transaction flow to its nodes with [contender](https://github.com/flashbots/contender). Just pass the `--contender` flag to send spam transactions that fill each block:
+
+```bash
+go run main.go cook l1 --contender
+```
+
+The default contender flags are as follows:
+
+- `--min-balance "10 ether"` -- gives each spammer account 10 ETH.
+- `--tps 20` -- sends 20 transactions per second.
+- `-l` -- runs spammer indefinitely (pass `-l <num>` to set a finite number of spam runs).
+
+To add or modify contender flags, use `--contender.arg`:
+
+```bash
+# run the builtin erc20 scenario instead of the default "fill block" scenario, at 100 TPS
+go run main.go cook l1 --contender \
+  --contender.arg "--tps 100" \
+  --contender.arg "erc20"
+```
+
+To read about more contender flag options, see the [contender CLI docs](https://github.com/flashbots/contender/blob/main/docs/cli.md). To see all available flags, [install contender](https://github.com/flashbots/contender/blob/main/docs/installation.md) or [run it in docker](https://github.com/flashbots/contender?tab=readme-ov-file#docker-instructions), and run `contender --help`.
+
 ## Common Options
 
 - `--output` (string): The directory where the chain data and artifacts are stored. Defaults to `$HOME/.playground/devnet`