cmd/workload: introduce transaction-trace test (#31288)

This pull request introduces a new test suite in workload framework, for
transaction tracing.

**test generation**
`go run . tracegen --trace-tests trace-test.json http://host:8545`

and you can choose to store the trace result in a specific folder
`go run . tracegen --trace-tests trace-test.json --trace-output
./trace-result http://host:8545`

**test run**
`./workload test -run Trace/Transaction --trace-invalid ./trace-invalid
http://host:8545`

The mismatched trace result will be saved in the specific folder for
further investigation.

Author: rjl493456442

cmd/workload/README.md

@@ -26,4 +26,5 @@ the following commands (in this directory) against a synced mainnet node:
 ```shell
 > go run . filtergen --queries queries/filter_queries_mainnet.json http://host:8545
 > go run . historygen --history-tests queries/history_mainnet.json http://host:8545
+> go run . tracegen --trace-tests queries/trace_mainnet.json http://host:8545
 ```

cmd/workload/client.go

@@ -0,0 +1,104 @@
+// Copyright 2025 The go-ethereum Authors
+// This file is part of go-ethereum.
+//
+// go-ethereum is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// go-ethereum is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with go-ethereum. If not, see <http://www.gnu.org/licenses/>.
+
+package main
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/ethereum/go-ethereum/common"
+	"github.com/ethereum/go-ethereum/common/hexutil"
+	"github.com/ethereum/go-ethereum/core/types"
+	"github.com/ethereum/go-ethereum/ethclient"
+	"github.com/ethereum/go-ethereum/ethclient/gethclient"
+	"github.com/ethereum/go-ethereum/rpc"
+	"github.com/urfave/cli/v2"
+)
+
+type client struct {
+	Eth  *ethclient.Client
+	Geth *gethclient.Client
+	RPC  *rpc.Client
+}
+
+func makeClient(ctx *cli.Context) *client {
+	if ctx.NArg() < 1 {
+		exit("missing RPC endpoint URL as command-line argument")
+	}
+	url := ctx.Args().First()
+	cl, err := rpc.Dial(url)
+	if err != nil {
+		exit(fmt.Errorf("could not create RPC client at %s: %v", url, err))
+	}
+	return &client{
+		RPC:  cl,
+		Eth:  ethclient.NewClient(cl),
+		Geth: gethclient.New(cl),
+	}
+}
+
+type simpleBlock struct {
+	Number hexutil.Uint64 `json:"number"`
+	Hash   common.Hash    `json:"hash"`
+}
+
+type simpleTransaction struct {
+	Hash             common.Hash    `json:"hash"`
+	TransactionIndex hexutil.Uint64 `json:"transactionIndex"`
+}
+
+func (c *client) getBlockByHash(ctx context.Context, arg common.Hash, fullTx bool) (*simpleBlock, error) {
+	var r *simpleBlock
+	err := c.RPC.CallContext(ctx, &r, "eth_getBlockByHash", arg, fullTx)
+	return r, err
+}
+
+func (c *client) getBlockByNumber(ctx context.Context, arg uint64, fullTx bool) (*simpleBlock, error) {
+	var r *simpleBlock
+	err := c.RPC.CallContext(ctx, &r, "eth_getBlockByNumber", hexutil.Uint64(arg), fullTx)
+	return r, err
+}
+
+func (c *client) getTransactionByBlockHashAndIndex(ctx context.Context, block common.Hash, index uint64) (*simpleTransaction, error) {
+	var r *simpleTransaction
+	err := c.RPC.CallContext(ctx, &r, "eth_getTransactionByBlockHashAndIndex", block, hexutil.Uint64(index))
+	return r, err
+}
+
+func (c *client) getTransactionByBlockNumberAndIndex(ctx context.Context, block uint64, index uint64) (*simpleTransaction, error) {
+	var r *simpleTransaction
+	err := c.RPC.CallContext(ctx, &r, "eth_getTransactionByBlockNumberAndIndex", hexutil.Uint64(block), hexutil.Uint64(index))
+	return r, err
+}
+
+func (c *client) getBlockTransactionCountByHash(ctx context.Context, block common.Hash) (uint64, error) {
+	var r hexutil.Uint64
+	err := c.RPC.CallContext(ctx, &r, "eth_getBlockTransactionCountByHash", block)
+	return uint64(r), err
+}
+
+func (c *client) getBlockTransactionCountByNumber(ctx context.Context, block uint64) (uint64, error) {
+	var r hexutil.Uint64
+	err := c.RPC.CallContext(ctx, &r, "eth_getBlockTransactionCountByNumber", hexutil.Uint64(block))
+	return uint64(r), err
+}
+
+func (c *client) getBlockReceipts(ctx context.Context, arg any) ([]*types.Receipt, error) {
+	var result []*types.Receipt
+	err := c.RPC.CallContext(ctx, &result, "eth_getBlockReceipts", arg)
+	return result, err
+}

cmd/workload/filtertest.go

@@ -45,11 +45,11 @@ func newFilterTestSuite(cfg testConfig) *filterTestSuite {
 	return s
 }
 
-func (s *filterTestSuite) allTests() []utesting.Test {
-	return []utesting.Test{
-		{Name: "Filter/ShortRange", Fn: s.filterShortRange},
-		{Name: "Filter/LongRange", Fn: s.filterLongRange, Slow: true},
-		{Name: "Filter/FullRange", Fn: s.filterFullRange, Slow: true},
+func (s *filterTestSuite) allTests() []workloadTest {
+	return []workloadTest{
+		newWorkLoadTest("Filter/ShortRange", s.filterShortRange),
+		newSlowWorkloadTest("Filter/LongRange", s.filterLongRange),
+		newSlowWorkloadTest("Filter/FullRange", s.filterFullRange),
 	}
 }
 

cmd/workload/historytest.go

@@ -23,7 +23,6 @@ import (
 
 	"github.com/ethereum/go-ethereum/common"
 	"github.com/ethereum/go-ethereum/common/hexutil"
-	"github.com/ethereum/go-ethereum/core/types"
 	"github.com/ethereum/go-ethereum/internal/utesting"
 )
 
@@ -65,40 +64,16 @@ func (s *historyTestSuite) loadTests() error {
 	return nil
 }
 
-func (s *historyTestSuite) allTests() []utesting.Test {
-	return []utesting.Test{
-		{
-			Name: "History/getBlockByHash",
-			Fn:   s.testGetBlockByHash,
-		},
-		{
-			Name: "History/getBlockByNumber",
-			Fn:   s.testGetBlockByNumber,
-		},
-		{
-			Name: "History/getBlockReceiptsByHash",
-			Fn:   s.testGetBlockReceiptsByHash,
-		},
-		{
-			Name: "History/getBlockReceiptsByNumber",
-			Fn:   s.testGetBlockReceiptsByNumber,
-		},
-		{
-			Name: "History/getBlockTransactionCountByHash",
-			Fn:   s.testGetBlockTransactionCountByHash,
-		},
-		{
-			Name: "History/getBlockTransactionCountByNumber",
-			Fn:   s.testGetBlockTransactionCountByNumber,
-		},
-		{
-			Name: "History/getTransactionByBlockHashAndIndex",
-			Fn:   s.testGetTransactionByBlockHashAndIndex,
-		},
-		{
-			Name: "History/getTransactionByBlockNumberAndIndex",
-			Fn:   s.testGetTransactionByBlockNumberAndIndex,
-		},
+func (s *historyTestSuite) allTests() []workloadTest {
+	return []workloadTest{
+		newWorkLoadTest("History/getBlockByHash", s.testGetBlockByHash),
+		newWorkLoadTest("History/getBlockByNumber", s.testGetBlockByNumber),
+		newWorkLoadTest("History/getBlockReceiptsByHash", s.testGetBlockReceiptsByHash),
+		newWorkLoadTest("History/getBlockReceiptsByNumber", s.testGetBlockReceiptsByNumber),
+		newWorkLoadTest("History/getBlockTransactionCountByHash", s.testGetBlockTransactionCountByHash),
+		newWorkLoadTest("History/getBlockTransactionCountByNumber", s.testGetBlockTransactionCountByNumber),
+		newWorkLoadTest("History/getTransactionByBlockHashAndIndex", s.testGetTransactionByBlockHashAndIndex),
+		newWorkLoadTest("History/getTransactionByBlockNumberAndIndex", s.testGetTransactionByBlockNumberAndIndex),
 	}
 }
 
@@ -279,55 +254,3 @@ func (s *historyTestSuite) testGetTransactionByBlockNumberAndIndex(t *utesting.T
 		}
 	}
 }
-
-type simpleBlock struct {
-	Number hexutil.Uint64 `json:"number"`
-	Hash   common.Hash    `json:"hash"`
-}
-
-type simpleTransaction struct {
-	Hash             common.Hash    `json:"hash"`
-	TransactionIndex hexutil.Uint64 `json:"transactionIndex"`
-}
-
-func (c *client) getBlockByHash(ctx context.Context, arg common.Hash, fullTx bool) (*simpleBlock, error) {
-	var r *simpleBlock
-	err := c.RPC.CallContext(ctx, &r, "eth_getBlockByHash", arg, fullTx)
-	return r, err
-}
-
-func (c *client) getBlockByNumber(ctx context.Context, arg uint64, fullTx bool) (*simpleBlock, error) {
-	var r *simpleBlock
-	err := c.RPC.CallContext(ctx, &r, "eth_getBlockByNumber", hexutil.Uint64(arg), fullTx)
-	return r, err
-}
-
-func (c *client) getTransactionByBlockHashAndIndex(ctx context.Context, block common.Hash, index uint64) (*simpleTransaction, error) {
-	var r *simpleTransaction
-	err := c.RPC.CallContext(ctx, &r, "eth_getTransactionByBlockHashAndIndex", block, hexutil.Uint64(index))
-	return r, err
-}
-
-func (c *client) getTransactionByBlockNumberAndIndex(ctx context.Context, block uint64, index uint64) (*simpleTransaction, error) {
-	var r *simpleTransaction
-	err := c.RPC.CallContext(ctx, &r, "eth_getTransactionByBlockNumberAndIndex", hexutil.Uint64(block), hexutil.Uint64(index))
-	return r, err
-}
-
-func (c *client) getBlockTransactionCountByHash(ctx context.Context, block common.Hash) (uint64, error) {
-	var r hexutil.Uint64
-	err := c.RPC.CallContext(ctx, &r, "eth_getBlockTransactionCountByHash", block)
-	return uint64(r), err
-}
-
-func (c *client) getBlockTransactionCountByNumber(ctx context.Context, block uint64) (uint64, error) {
-	var r hexutil.Uint64
-	err := c.RPC.CallContext(ctx, &r, "eth_getBlockTransactionCountByNumber", hexutil.Uint64(block))
-	return uint64(r), err
-}
-
-func (c *client) getBlockReceipts(ctx context.Context, arg any) ([]*types.Receipt, error) {
-	var result []*types.Receipt
-	err := c.RPC.CallContext(ctx, &result, "eth_getBlockReceipts", arg)
-	return result, err
-}

cmd/workload/historytestgen.go

@@ -51,7 +51,7 @@ var (
 	}
 	historyTestEarliestFlag = &cli.IntFlag{
 		Name:     "earliest",
-		Usage:    "JSON file containing filter test queries",
+		Usage:    "The earliest block to test queries",
 		Value:    0,
 		Category: flags.TestingCategory,
 	}
@@ -139,7 +139,7 @@ func calcReceiptsHash(rcpt []*types.Receipt) common.Hash {
 func writeJSON(fileName string, value any) {
 	file, err := os.Create(fileName)
 	if err != nil {
-		exit(fmt.Errorf("Error creating %s: %v", fileName, err))
+		exit(fmt.Errorf("error creating %s: %v", fileName, err))
 		return
 	}
 	defer file.Close()

cmd/workload/main.go

@@ -20,10 +20,8 @@ import (
 	"fmt"
 	"os"
 
-	"github.com/ethereum/go-ethereum/ethclient"
 	"github.com/ethereum/go-ethereum/internal/debug"
 	"github.com/ethereum/go-ethereum/internal/flags"
-	"github.com/ethereum/go-ethereum/rpc"
 	"github.com/urfave/cli/v2"
 )
 
@@ -49,6 +47,7 @@ func init() {
 		runTestCommand,
 		historyGenerateCommand,
 		filterGenerateCommand,
+		traceGenerateCommand,
 		filterPerfCommand,
 	}
 }
@@ -57,26 +56,6 @@ func main() {
 	exit(app.Run(os.Args))
 }
 
-type client struct {
-	Eth *ethclient.Client
-	RPC *rpc.Client
-}
-
-func makeClient(ctx *cli.Context) *client {
-	if ctx.NArg() < 1 {
-		exit("missing RPC endpoint URL as command-line argument")
-	}
-	url := ctx.Args().First()
-	cl, err := rpc.Dial(url)
-	if err != nil {
-		exit(fmt.Errorf("Could not create RPC client at %s: %v", url, err))
-	}
-	return &client{
-		RPC: cl,
-		Eth: ethclient.NewClient(cl),
-	}
-}
-
 func exit(err any) {
 	if err == nil {
 		os.Exit(0)