[bal-devnet-3] cmd/utils: expose executor perf toggles as --exec.* CLI flags (#20862)

Cherry-pick of #20797 to bal-devnet-3.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: mh0lt

cmd/utils/flags.go

@@ -46,6 +46,7 @@ import (
 	"github.com/erigontech/erigon/cmd/utils/flags"
 	"github.com/erigontech/erigon/common"
 	libkzg "github.com/erigontech/erigon/common/crypto/kzg"
+	"github.com/erigontech/erigon/common/dbg"
 	"github.com/erigontech/erigon/common/log/v3"
 	"github.com/erigontech/erigon/db/config3"
 	"github.com/erigontech/erigon/db/datadir"
@@ -1149,6 +1150,31 @@ var (
 		Name:  "erigondb.domain.steps-in-frozen-file",
 		Usage: `Override erigondb.toml "steps_in_frozen_file" for the domain merge cap only (history/inverted-index merges are unaffected). Pass a positive integer to set an explicit cap, or "Inf" to leave the domain merge unbounded. Default: unset, meaning the domain uses the same cap as determined by erigondb.toml.`,
 	}
+	ExecBatchedIOFlag = cli.BoolFlag{
+		Name:  "exec.batched-io",
+		Usage: "Enable BAL-driven I/O and write-dependency optimisations: (1) read-ahead pre-warms the DB page cache with account/code/storage reads before block execution (READ_AHEAD=true), and (2) the parallel executor pre-populates the version map from BAL hints (IGNORE_BAL=false). Disable for cold-read or non-BAL scheduling performance measurements.",
+		Value: true,
+	}
+	ExecStateCacheFlag = cli.BoolFlag{
+		Name:  "exec.state-cache",
+		Usage: "Enable the executor domain-shared read cache (equivalent to USE_STATE_CACHE=true). Disable for cold-read performance measurements.",
+		Value: true,
+	}
+	ExecWorkersFlag = cli.IntFlag{
+		Name:  "exec.workers",
+		Usage: "Parallel executor worker count (equivalent to EXEC3_WORKERS). Default: half the number of CPU cores, other half reserved for snapshots build/merge/prune.",
+		Value: runtime.NumCPU() / 2,
+	}
+	ExecNoMergeFlag = cli.BoolFlag{
+		Name:  "exec.no-merge",
+		Usage: "Disable state-aggregator file merges for Domain / History / Inverted-Index (equivalent to NO_MERGE=true). Diagnostic / perf-comparison use only.",
+		Value: false,
+	}
+	ExecNoPruneFlag = cli.BoolFlag{
+		Name:  "exec.no-prune",
+		Usage: "Disable state-aggregator pruning of historical steps (equivalent to NO_PRUNE=true). Diagnostic / perf-comparison use only.",
+		Value: false,
+	}
 )
 
 var MetricFlags = []cli.Flag{&MetricsEnabledFlag, &MetricsHTTPFlag, &MetricsPortFlag}
@@ -1955,6 +1981,34 @@ func SetEthConfig(ctx *cli.Context, nodeConfig *nodecfg.Config, cfg *ethconfig.C
 	cfg.FcuTimeout = ctx.Duration(FcuTimeoutFlag.Name)
 	cfg.FcuBackgroundPrune = ctx.Bool(FcuBackgroundPruneFlag.Name)
 	cfg.FcuBackgroundCommit = ctx.Bool(FcuBackgroundCommitFlag.Name)
+
+	// Executor performance toggles. When the user explicitly sets the CLI
+	// flag, it overrides the env-var default that dbg read at package init.
+	// Otherwise env vars (IGNORE_BAL, USE_STATE_CACHE, EXEC3_WORKERS,
+	// NO_MERGE, NO_PRUNE) remain the source of truth.
+	if ctx.IsSet(ExecBatchedIOFlag.Name) {
+		// --exec.batched-io toggles two BAL-driven optimisations together:
+		// read-ahead pre-warming (ReadAhead) and version-map pre-population
+		// (IgnoreBAL, inverted). Flipped in lockstep so perf comparisons
+		// test "all BAL I/O off" vs "all BAL I/O on".
+		v := ctx.Bool(ExecBatchedIOFlag.Name)
+		dbg.SetReadAhead(v)
+		dbg.SetIgnoreBAL(!v)
+	}
+	if ctx.IsSet(ExecStateCacheFlag.Name) {
+		dbg.SetUseStateCache(ctx.Bool(ExecStateCacheFlag.Name))
+	}
+	if ctx.IsSet(ExecWorkersFlag.Name) {
+		n := ctx.Int(ExecWorkersFlag.Name)
+		dbg.SetExec3Workers(n)
+		cfg.ExecWorkerCount = n
+	}
+	if ctx.IsSet(ExecNoMergeFlag.Name) {
+		dbg.SetNoMerge(ctx.Bool(ExecNoMergeFlag.Name))
+	}
+	if ctx.IsSet(ExecNoPruneFlag.Name) {
+		dbg.SetNoPrune(ctx.Bool(ExecNoPruneFlag.Name))
+	}
 	if ctx.IsSet(RPCGlobalGasCapFlag.Name) {
 		cfg.RPCGasCap = ctx.Uint64(RPCGlobalGasCapFlag.Name)
 	}

cmd/utils/flags_test.go

@@ -26,6 +26,8 @@ import (
 
 	"github.com/stretchr/testify/require"
 	"github.com/urfave/cli/v2"
+
+	"github.com/erigontech/erigon/common/dbg"
 )
 
 func Test_SplitTagsFlag(t *testing.T) {
@@ -97,3 +99,107 @@ func TestResolveChainName(t *testing.T) {
 		})
 	}
 }
+
+// TestExecPerfFlags_OverrideDbg verifies each --exec.* flag, when explicitly
+// set, flips the corresponding dbg package toggle. Also asserts the no-flag
+// path leaves dbg values untouched so env vars remain the source of truth.
+func TestExecPerfFlags_OverrideDbg(t *testing.T) {
+	// Snapshot and restore dbg values so tests don't leak into each other.
+	origIgnoreBAL := dbg.IgnoreBAL
+	origReadAhead := dbg.ReadAhead
+	origUseStateCache := dbg.UseStateCache
+	origExec3Workers := dbg.Exec3Workers
+	origNoPrune := dbg.NoPrune()
+	origNoMerge := dbg.NoMerge()
+	t.Cleanup(func() {
+		dbg.SetIgnoreBAL(origIgnoreBAL)
+		dbg.SetReadAhead(origReadAhead)
+		dbg.SetUseStateCache(origUseStateCache)
+		dbg.SetExec3Workers(origExec3Workers)
+		dbg.SetNoPrune(origNoPrune)
+		dbg.SetNoMerge(origNoMerge)
+	})
+
+	apply := func(ctx *cli.Context) error {
+		if ctx.IsSet(ExecBatchedIOFlag.Name) {
+			v := ctx.Bool(ExecBatchedIOFlag.Name)
+			dbg.SetReadAhead(v)
+			dbg.SetIgnoreBAL(!v)
+		}
+		if ctx.IsSet(ExecStateCacheFlag.Name) {
+			dbg.SetUseStateCache(ctx.Bool(ExecStateCacheFlag.Name))
+		}
+		if ctx.IsSet(ExecWorkersFlag.Name) {
+			dbg.SetExec3Workers(ctx.Int(ExecWorkersFlag.Name))
+		}
+		if ctx.IsSet(ExecNoMergeFlag.Name) {
+			dbg.SetNoMerge(ctx.Bool(ExecNoMergeFlag.Name))
+		}
+		if ctx.IsSet(ExecNoPruneFlag.Name) {
+			dbg.SetNoPrune(ctx.Bool(ExecNoPruneFlag.Name))
+		}
+		return nil
+	}
+
+	run := func(args ...string) {
+		app := cli.NewApp()
+		app.Flags = []cli.Flag{
+			&ExecBatchedIOFlag, &ExecStateCacheFlag, &ExecWorkersFlag,
+			&ExecNoMergeFlag, &ExecNoPruneFlag,
+		}
+		app.Action = apply
+		require.NoError(t, app.Run(append([]string{"test"}, args...)))
+	}
+
+	t.Run("no flags set leaves dbg untouched", func(t *testing.T) {
+		dbg.SetIgnoreBAL(false)
+		dbg.SetReadAhead(true)
+		dbg.SetUseStateCache(true)
+		dbg.SetExec3Workers(42)
+		dbg.SetNoMerge(false)
+		dbg.SetNoPrune(false)
+		run()
+		require.Equal(t, false, dbg.IgnoreBAL)
+		require.Equal(t, true, dbg.ReadAhead)
+		require.Equal(t, true, dbg.UseStateCache)
+		require.Equal(t, 42, dbg.Exec3Workers)
+		require.Equal(t, false, dbg.NoMerge())
+		require.Equal(t, false, dbg.NoPrune())
+	})
+
+	t.Run("batched-io=false disables read-ahead and sets IgnoreBAL", func(t *testing.T) {
+		dbg.SetIgnoreBAL(false)
+		dbg.SetReadAhead(true)
+		run("--exec.batched-io=false")
+		require.True(t, dbg.IgnoreBAL)
+		require.False(t, dbg.ReadAhead)
+	})
+
+	t.Run("batched-io=true enables read-ahead and clears IgnoreBAL", func(t *testing.T) {
+		dbg.SetIgnoreBAL(true)
+		dbg.SetReadAhead(false)
+		run("--exec.batched-io=true")
+		require.False(t, dbg.IgnoreBAL)
+		require.True(t, dbg.ReadAhead)
+	})
+
+	t.Run("state-cache=false flips UseStateCache", func(t *testing.T) {
+		dbg.SetUseStateCache(true)
+		run("--exec.state-cache=false")
+		require.False(t, dbg.UseStateCache)
+	})
+
+	t.Run("workers=7 sets Exec3Workers", func(t *testing.T) {
+		dbg.SetExec3Workers(1)
+		run("--exec.workers=7")
+		require.Equal(t, 7, dbg.Exec3Workers)
+	})
+
+	t.Run("no-merge and no-prune set to true", func(t *testing.T) {
+		dbg.SetNoMerge(false)
+		dbg.SetNoPrune(false)
+		run("--exec.no-merge=true", "--exec.no-prune=true")
+		require.True(t, dbg.NoMerge())
+		require.True(t, dbg.NoPrune())
+	})
+}

common/dbg/experiments.go

@@ -111,6 +111,7 @@ var (
 	UseTxDependencies     = EnvBool("USE_TX_DEPENDENCIES", false)
 	UseStateCache         = EnvBool("USE_STATE_CACHE", true)
 	AssertStateCache      = EnvBool("ASSERT_STATE_CACHE", false)
+	ReadAhead             = EnvBool("READ_AHEAD", true)
 
 	BorValidateHeaderTime = EnvBool("BOR_VALIDATE_HEADER_TIME", true)
 	TraceDeletion         = EnvBool("TRACE_DELETION", false)
@@ -132,6 +133,16 @@ func NoMergeHistory() bool       { return noMergeHistory }
 func NoDeepMergeHistory() bool   { return noDeepMergeHistory }
 func PruneTotalDifficulty() bool { return pruneTotalDifficulty }
 
+// CLI-override setters for the performance toggles that also have env-var
+// twins. The env var sets the initial value at package init; the CLI layer
+// calls these at node startup only when the user explicitly set the flag.
+func SetIgnoreBAL(b bool)     { IgnoreBAL = b }
+func SetUseStateCache(b bool) { UseStateCache = b }
+func SetReadAhead(b bool)     { ReadAhead = b }
+func SetExec3Workers(n int)   { Exec3Workers = n }
+func SetNoPrune(b bool)       { noPrune = b }
+func SetNoMerge(b bool)       { noMerge = b }
+
 var (
 	dirtySace     uint64
 	dirtySaceOnce sync.Once

execution/exec/blocks_read_ahead.go

@@ -10,6 +10,7 @@ import (
 	"golang.org/x/sync/errgroup"
 
 	"github.com/erigontech/erigon/common"
+	"github.com/erigontech/erigon/common/dbg"
 	"github.com/erigontech/erigon/common/length"
 	"github.com/erigontech/erigon/common/log/v3"
 	"github.com/erigontech/erigon/db/kv"
@@ -108,6 +109,10 @@ func AddSendersToGlobalReadAheader(senders []byte, blockHash common.Hash) {
 func (bra *blockReadAheader) warmBody(ctx context.Context, db kv.RoDB, header *types.Header, body *types.Body, workers int) {
 	defer bra.warming.Store(false)
 
+	if !dbg.ReadAhead {
+		return
+	}
+
 	if workers <= 0 {
 		workers = 1
 	}

node/cli/default_flags.go

@@ -47,6 +47,11 @@ var DefaultFlags = []cli.Flag{
 	&utils.FcuTimeoutFlag,
 	&utils.FcuBackgroundPruneFlag,
 	&utils.FcuBackgroundCommitFlag,
+	&utils.ExecBatchedIOFlag,
+	&utils.ExecStateCacheFlag,
+	&utils.ExecWorkersFlag,
+	&utils.ExecNoMergeFlag,
+	&utils.ExecNoPruneFlag,
 	&BatchSizeFlag,
 	&BodyCacheLimitFlag,
 	&DatabaseVerbosityFlag,