feat: add load-test payload worker for base-load-test binary integration

Add a new payload worker type 'load-test' that integrates the Rust
base-load-test binary as an external transaction generator. The worker
follows the same proxy-based pattern as the tx-fuzz integration:

- New LoadTestPayloadWorker spawns the binary with a generated YAML
  config pointing to a proxy server that captures transactions
- CLI flag --load-test-bin (env: BASE_BENCH_LOAD_TEST_BIN) for binary path
- Config interface extended with LoadTestBinary() method
- Factory routes 'load-test' payload type to the new worker
- Generated config supports configurable sender_count, target_gps,
  and duration via YAML payload params

Author: meyer9

benchmark/flags/flags.go

@@ -15,22 +15,24 @@ func prefixEnvVars(name string) []string {
 }
 
 const (
-	ConfigFlagName          = "config"
-	RootDirFlagName         = "root-dir"
-	OutputDirFlagName       = "output-dir"
-	TxFuzzBinFlagName       = "tx-fuzz-bin"
-	ProxyPortFlagName       = "proxy-port"
-	BenchmarkRunIDFlagName  = "benchmark-run-id"
-	MachineTypeFlagName     = "machine-type"
-	MachineProviderFlagName = "machine-provider"
-	MachineRegionFlagName   = "machine-region"
-	FileSystemFlagName      = "file-system"
+	ConfigFlagName            = "config"
+	RootDirFlagName           = "root-dir"
+	OutputDirFlagName         = "output-dir"
+	TxFuzzBinFlagName         = "tx-fuzz-bin"
+	LoadTestBinFlagName       = "load-test-bin"
+	ProxyPortFlagName         = "proxy-port"
+	BenchmarkRunIDFlagName    = "benchmark-run-id"
+	MachineTypeFlagName       = "machine-type"
+	MachineProviderFlagName   = "machine-provider"
+	MachineRegionFlagName     = "machine-region"
+	FileSystemFlagName        = "file-system"
 	ParallelTxBatchesFlagName = "parallel-tx-batches"
 )
 
 // TxFuzz defaults
 const (
-	DefaultTxFuzzBin = "../tx-fuzz/cmd/livefuzzer/livefuzzer"
+	DefaultTxFuzzBin   = "../tx-fuzz/cmd/livefuzzer/livefuzzer"
+	DefaultLoadTestBin = "./base-load-test"
 )
 
 var (
@@ -62,6 +64,13 @@ var (
 		EnvVars: opservice.PrefixEnvVar(EnvVarPrefix, "TX_FUZZ_BIN"),
 	}
 
+	LoadTestBinFlag = &cli.StringFlag{
+		Name:    LoadTestBinFlagName,
+		Usage:   "Load test binary path",
+		Value:   DefaultLoadTestBin,
+		EnvVars: opservice.PrefixEnvVar(EnvVarPrefix, "LOAD_TEST_BIN"),
+	}
+
 	ProxyPortFlag = &cli.IntFlag{
 		Name:    "proxy-port",
 		Usage:   "Proxy port",
@@ -116,6 +125,7 @@ var RunFlags = []cli.Flag{
 	RootDirFlag,
 	OutputDirFlag,
 	TxFuzzBinFlag,
+	LoadTestBinFlag,
 	ProxyPortFlag,
 	BenchmarkRunIDFlag,
 	MachineTypeFlag,

runner/config/config.go

@@ -20,6 +20,7 @@ type Config interface {
 	DataDir() string
 	OutputDir() string
 	TxFuzzBinary() string
+	LoadTestBinary() string
 	ProxyPort() int
 	BenchmarkRunID() string
 	MachineType() string
@@ -30,36 +31,38 @@ type Config interface {
 }
 
 type config struct {
-	logConfig       oplog.CLIConfig
-	configPath      string
-	dataDir         string
-	outputDir       string
-	clientOptions   ClientOptions
-	txFuzzBinary    string
-	proxyPort       int
-	benchmarkRunID  string
-	machineType     string
-	machineProvider string
-	machineRegion   string
-	fileSystem      string
+	logConfig         oplog.CLIConfig
+	configPath        string
+	dataDir           string
+	outputDir         string
+	clientOptions     ClientOptions
+	txFuzzBinary      string
+	loadTestBinary    string
+	proxyPort         int
+	benchmarkRunID    string
+	machineType       string
+	machineProvider   string
+	machineRegion     string
+	fileSystem        string
 	parallelTxBatches int
 }
 
 func NewConfig(ctx *cli.Context) Config {
 	return &config{
-		logConfig:       oplog.ReadCLIConfig(ctx),
-		configPath:      ctx.String(appFlags.ConfigFlagName),
-		dataDir:         ctx.String(appFlags.RootDirFlagName),
-		outputDir:       ctx.String(appFlags.OutputDirFlagName),
-		txFuzzBinary:    ctx.String(appFlags.TxFuzzBinFlagName),
-		proxyPort:       ctx.Int(appFlags.ProxyPortFlagName),
-		benchmarkRunID:  ctx.String(appFlags.BenchmarkRunIDFlagName),
-		machineType:     ctx.String(appFlags.MachineTypeFlagName),
-		machineProvider: ctx.String(appFlags.MachineProviderFlagName),
-		machineRegion:   ctx.String(appFlags.MachineRegionFlagName),
-		fileSystem:      ctx.String(appFlags.FileSystemFlagName),
+		logConfig:         oplog.ReadCLIConfig(ctx),
+		configPath:        ctx.String(appFlags.ConfigFlagName),
+		dataDir:           ctx.String(appFlags.RootDirFlagName),
+		outputDir:         ctx.String(appFlags.OutputDirFlagName),
+		txFuzzBinary:      ctx.String(appFlags.TxFuzzBinFlagName),
+		loadTestBinary:    ctx.String(appFlags.LoadTestBinFlagName),
+		proxyPort:         ctx.Int(appFlags.ProxyPortFlagName),
+		benchmarkRunID:    ctx.String(appFlags.BenchmarkRunIDFlagName),
+		machineType:       ctx.String(appFlags.MachineTypeFlagName),
+		machineProvider:   ctx.String(appFlags.MachineProviderFlagName),
+		machineRegion:     ctx.String(appFlags.MachineRegionFlagName),
+		fileSystem:        ctx.String(appFlags.FileSystemFlagName),
 		parallelTxBatches: ctx.Int(appFlags.ParallelTxBatchesFlagName),
-		clientOptions:   ReadClientOptions(ctx),
+		clientOptions:     ReadClientOptions(ctx),
 	}
 }
 
@@ -112,6 +115,10 @@ func (c *config) TxFuzzBinary() string {
 	return c.txFuzzBinary
 }
 
+func (c *config) LoadTestBinary() string {
+	return c.loadTestBinary
+}
+
 func (c *config) BenchmarkRunID() string {
 	return c.benchmarkRunID
 }

runner/payload/factory.go

@@ -7,6 +7,7 @@ import (
 	clienttypes "github.com/base/base-bench/runner/clients/types"
 	benchtypes "github.com/base/base-bench/runner/network/types"
 	"github.com/base/base-bench/runner/payload/contract"
+	"github.com/base/base-bench/runner/payload/loadtest"
 	"github.com/base/base-bench/runner/payload/simulator"
 	"github.com/base/base-bench/runner/payload/transferonly"
 	"github.com/base/base-bench/runner/payload/txfuzz"
@@ -31,6 +32,13 @@ func NewPayloadWorker(ctx context.Context, log log.Logger, testConfig *benchtype
 	case "tx-fuzz":
 		worker, err = txfuzz.NewTxFuzzPayloadWorker(
 			log, sequencerClient.ClientURL(), params, privateKey, amount, config.TxFuzzBinary(), genesis.Config.ChainID)
+	case "load-test":
+		def, _ := definition.Params.(*loadtest.LoadTestPayloadDefinition)
+		if def == nil {
+			def = &loadtest.LoadTestPayloadDefinition{}
+		}
+		worker, err = loadtest.NewLoadTestPayloadWorker(
+			log, sequencerClient.ClientURL(), params, privateKey, amount, config.LoadTestBinary(), genesis.Config.ChainID, *def)
 	case "transfer-only":
 		worker, err = transferonly.NewTransferPayloadWorker(
 			ctx, log, sequencerClient.ClientURL(), params, privateKey, amount, &genesis, definition.Params)
@@ -77,6 +85,8 @@ func (t *Definition) UnmarshalYAML(node *yaml.Node) error {
 		params = &transferonly.TransferOnlyPayloadDefinition{}
 	case "tx-fuzz":
 		params = &txfuzz.TxFuzzPayloadDefinition{}
+	case "load-test":
+		params = &loadtest.LoadTestPayloadDefinition{}
 	case "contract":
 		params = &contract.ContractPayloadDefinition{}
 	case "simulator":

runner/payload/loadtest/load_test_worker.go

@@ -0,0 +1,183 @@
+package loadtest
+
+import (
+	"context"
+	"crypto/ecdsa"
+	"encoding/hex"
+	"fmt"
+	"math/big"
+	"os"
+	"os/exec"
+
+	"github.com/base/base-bench/runner/clients/common/proxy"
+	"github.com/base/base-bench/runner/network/mempool"
+	"github.com/base/base-bench/runner/network/types"
+	"github.com/base/base-bench/runner/payload/worker"
+	"github.com/ethereum/go-ethereum/log"
+	"github.com/pkg/errors"
+	"gopkg.in/yaml.v3"
+)
+
+const proxyPort = 8545
+
+// LoadTestPayloadDefinition is the YAML payload params for the load-test type.
+type LoadTestPayloadDefinition struct {
+	SenderCount uint64 `yaml:"sender_count"`
+	TargetGPS   uint64 `yaml:"target_gps"`
+	Duration    string `yaml:"duration"`
+}
+
+// loadTestConfig is the YAML config written to a temp file for the load-test binary.
+type loadTestConfig struct {
+	RPC           string                   `yaml:"rpc"`
+	SenderCount   uint64                   `yaml:"sender_count"`
+	TargetGPS     uint64                   `yaml:"target_gps"`
+	Duration      string                   `yaml:"duration"`
+	Seed          uint64                   `yaml:"seed"`
+	FundingAmount string                   `yaml:"funding_amount"`
+	Transactions  []loadTestTransactionDef `yaml:"transactions"`
+}
+
+type loadTestTransactionDef struct {
+	Type   string `yaml:"type"`
+	Weight uint64 `yaml:"weight"`
+}
+
+type loadTestPayloadWorker struct {
+	log            log.Logger
+	prefundSK      string
+	loadTestBin    string
+	elRPCURL       string
+	gasLimit       uint64
+	params         LoadTestPayloadDefinition
+	mempool        *mempool.StaticWorkloadMempool
+	proxyServer    *proxy.ProxyServer
+	configFilePath string
+}
+
+// NewLoadTestPayloadWorker creates a worker that runs the base-load-test binary
+// as an external transaction generator, capturing transactions via a proxy server.
+func NewLoadTestPayloadWorker(
+	log log.Logger,
+	elRPCURL string,
+	params types.RunParams,
+	prefundedPrivateKey ecdsa.PrivateKey,
+	prefundAmount *big.Int,
+	loadTestBin string,
+	chainID *big.Int,
+	definition LoadTestPayloadDefinition,
+) (worker.Worker, error) {
+	mp := mempool.NewStaticWorkloadMempool(log, chainID)
+	ps := proxy.NewProxyServer(elRPCURL, log, proxyPort, mp)
+
+	w := &loadTestPayloadWorker{
+		log:         log,
+		prefundSK:   hex.EncodeToString(prefundedPrivateKey.D.Bytes()),
+		loadTestBin: loadTestBin,
+		elRPCURL:    elRPCURL,
+		gasLimit:    params.GasLimit,
+		params:      definition,
+		mempool:     mp,
+		proxyServer: ps,
+	}
+
+	return w, nil
+}
+
+func (w *loadTestPayloadWorker) Mempool() mempool.FakeMempool {
+	return w.mempool
+}
+
+func (w *loadTestPayloadWorker) Setup(ctx context.Context) error {
+	if err := w.proxyServer.Run(ctx); err != nil {
+		return errors.Wrap(err, "failed to run proxy server")
+	}
+
+	configPath, err := w.writeConfig()
+	if err != nil {
+		return errors.Wrap(err, "failed to write load-test config")
+	}
+	w.configFilePath = configPath
+
+	w.log.Info("Starting load test", "binary", w.loadTestBin, "config", configPath)
+
+	cmd := exec.CommandContext(ctx, w.loadTestBin, configPath)
+	cmd.Stdout = os.Stdout
+	cmd.Stderr = os.Stdout
+	cmd.Env = append(os.Environ(), fmt.Sprintf("FUNDER_KEY=%s", w.prefundSK))
+
+	if err := cmd.Start(); err != nil {
+		return errors.Wrap(err, "failed to start load test binary")
+	}
+
+	return nil
+}
+
+func (w *loadTestPayloadWorker) Stop(ctx context.Context) error {
+	w.proxyServer.Stop()
+
+	if w.configFilePath != "" {
+		os.Remove(w.configFilePath)
+	}
+
+	return nil
+}
+
+func (w *loadTestPayloadWorker) SendTxs(ctx context.Context) error {
+	w.log.Info("Collecting txs from load test")
+	pendingTxs := w.proxyServer.PendingTxs()
+	w.proxyServer.ClearPendingTxs()
+
+	w.mempool.AddTransactions(pendingTxs)
+	return nil
+}
+
+// writeConfig generates a temporary YAML config file for the load-test binary
+// with the RPC URL pointing to the proxy server.
+func (w *loadTestPayloadWorker) writeConfig() (string, error) {
+	senderCount := w.params.SenderCount
+	if senderCount == 0 {
+		senderCount = 10
+	}
+
+	targetGPS := w.params.TargetGPS
+	if targetGPS == 0 {
+		targetGPS = w.gasLimit / 2
+	}
+
+	duration := w.params.Duration
+	if duration == "" {
+		duration = "600s"
+	}
+
+	config := loadTestConfig{
+		RPC:           fmt.Sprintf("http://localhost:%d", proxyPort),
+		SenderCount:   senderCount,
+		TargetGPS:     targetGPS,
+		Duration:      duration,
+		Seed:          12345,
+		FundingAmount: "10000000000000000000",
+		Transactions: []loadTestTransactionDef{
+			{Type: "transfer", Weight: 70},
+			{Type: "calldata", Weight: 20},
+			{Type: "precompile", Weight: 10},
+		},
+	}
+
+	data, err := yaml.Marshal(&config)
+	if err != nil {
+		return "", errors.Wrap(err, "failed to marshal load-test config")
+	}
+
+	tmpFile, err := os.CreateTemp("", "load-test-config-*.yaml")
+	if err != nil {
+		return "", errors.Wrap(err, "failed to create temp config file")
+	}
+	defer tmpFile.Close()
+
+	if _, err := tmpFile.Write(data); err != nil {
+		return "", errors.Wrap(err, "failed to write temp config file")
+	}
+
+	return tmpFile.Name(), nil
+}