ethclient/gethclient: add tracing API methods

ethclient/gethclient/gethclient.go

@@ -20,6 +20,7 @@ package gethclient
 import (
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"math/big"
 	"runtime"
@@ -29,6 +30,7 @@ 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/eth/tracers"
 	"github.com/ethereum/go-ethereum/p2p"
 	"github.com/ethereum/go-ethereum/rpc"
 )
@@ -204,6 +206,66 @@ func (ec *Client) SubscribePendingTransactions(ctx context.Context, ch chan<- co
 	return ec.c.EthSubscribe(ctx, ch, "newPendingTransactions")
 }
 
+// TxTraceResult is the result of a single transaction trace.
+type TxTraceResult struct {
+	TxHash common.Hash `json:"txHash"`           // Transaction hash
+	Result interface{} `json:"result,omitempty"` // Trace results produced by the tracer
+	Error  string      `json:"error,omitempty"`  // Trace failure produced by the tracer
+}
+
+// BlockTraceResult represents the results of tracing a single block.
+type BlockTraceResult struct {
+	Block  hexutil.Uint64   `json:"block"`  // Block number corresponding to this trace
+	Hash   common.Hash      `json:"hash"`   // Block hash corresponding to this trace
+	Traces []*TxTraceResult `json:"traces"` // Trace results produced by the task
+}
+
+// TraceTransaction returns the structured logs created during the execution of EVM
+// and returns them as a JSON object.
+func (ec *Client) TraceTransaction(ctx context.Context, txHash common.Hash, config *tracers.TraceConfig) (interface{}, error) {
+	var result interface{}
+	err := ec.c.CallContext(ctx, &result, "debug_traceTransaction", txHash, config)
+	return result, err
+}
+
+// TraceCall lets you trace a given eth_call. It collects the structured logs
+// created during the execution of EVM if the given transaction was added on
+// top of the provided block and returns them as a JSON object.
+func (ec *Client) TraceCall(ctx context.Context, msg ethereum.CallMsg, blockNrOrHash rpc.BlockNumberOrHash, config *tracers.TraceCallConfig) (interface{}, error) {
+	var result interface{}
+	err := ec.c.CallContext(ctx, &result, "debug_traceCall", toCallArg(msg), blockNrOrHash, config)
+	return result, err
+}
+
+// TraceBlock returns the structured logs created during the execution of EVM
+// for a specific block. This can be by block number, hash, or the latest/pending block.
+func (ec *Client) TraceBlock(ctx context.Context, blockNrOrHash rpc.BlockNumberOrHash, config *tracers.TraceConfig) ([]*TxTraceResult, error) {
+	var result []*TxTraceResult
+
+	// Determine the method to call based on the type of blockNrOrHash
+	var method string
+	var arg interface{}
+
+	if hash, ok := blockNrOrHash.Hash(); ok {
+		method = "debug_traceBlockByHash"
+		arg = hash
+	} else if number, ok := blockNrOrHash.Number(); ok {
+		method = "debug_traceBlockByNumber"
+		arg = number
+	} else {
+		return nil, errors.New("invalid arguments; neither block nor hash specified")
+	}
+
+	err := ec.c.CallContext(ctx, &result, method, arg, config)
+	return result, err
+}
+
+// TraceChain returns the structured logs created during the execution of EVM between
+// two blocks (inclusive) and returns them as an array of JSON objects.
+func (ec *Client) TraceChain(ctx context.Context, start, end rpc.BlockNumber, config *tracers.TraceConfig) (*rpc.ClientSubscription, error) {
+	return ec.c.EthSubscribe(ctx, make(chan *BlockTraceResult), "debug_traceChain", start, end, config)
+}
+
 func toBlockNumArg(number *big.Int) string {
 	if number == nil {
 		return "latest"
@@ -348,3 +410,45 @@ func (o BlockOverrides) MarshalJSON() ([]byte, error) {
 	}
 	return json.Marshal(output)
 }
+
+// CallTracerResult represents the result of a call trace for transactions or calldata.
+type CallTracerResult struct {
+	Type    string             `json:"type"`
+	From    common.Address     `json:"from"`
+	To      common.Address     `json:"to"`
+	Value   *hexutil.Big       `json:"value"`
+	Gas     hexutil.Uint64     `json:"gas"`
+	GasUsed hexutil.Uint64     `json:"gasUsed"`
+	Input   hexutil.Bytes      `json:"input"`
+	Output  hexutil.Bytes      `json:"output"`
+	Error   string             `json:"error,omitempty"`
+	Calls   []CallTracerResult `json:"calls,omitempty"`
+}
+
+// TraceCallWithCallTracer performs a call trace using the specialized
+// call tracer, which provides detailed information about nested calls.
+func (ec *Client) TraceCallWithCallTracer(ctx context.Context, msg ethereum.CallMsg, blockNrOrHash rpc.BlockNumberOrHash) (*CallTracerResult, error) {
+	callTracer := "callTracer"
+	config := &tracers.TraceCallConfig{
+		TraceConfig: tracers.TraceConfig{
+			Tracer: &callTracer,
+		},
+	}
+
+	var result CallTracerResult
+	err := ec.c.CallContext(ctx, &result, "debug_traceCall", toCallArg(msg), blockNrOrHash, config)
+	return &result, err
+}
+
+// TraceTransactionWithCallTracer performs a transaction trace using the specialized
+// call tracer, which provides detailed information about nested calls.
+func (ec *Client) TraceTransactionWithCallTracer(ctx context.Context, txHash common.Hash) (*CallTracerResult, error) {
+	callTracer := "callTracer"
+	config := &tracers.TraceConfig{
+		Tracer: &callTracer,
+	}
+
+	var result CallTracerResult
+	err := ec.c.CallContext(ctx, &result, "debug_traceTransaction", txHash, config)
+	return &result, err
+}

ethclient/gethclient/gethclient_test.go

@@ -145,6 +145,24 @@ func TestGethClient(t *testing.T) {
 		}, {
 			"TestCallContractWithBlockOverrides",
 			func(t *testing.T) { testCallContractWithBlockOverrides(t, client) },
+		}, {
+			"TestTraceTransaction",
+			func(t *testing.T) { testTraceTransaction(t, client) },
+		}, {
+			"TestTraceCall",
+			func(t *testing.T) { testTraceCall(t, client) },
+		}, {
+			"TestTraceBlock",
+			func(t *testing.T) { testTraceBlock(t, client) },
+		}, {
+			"TestTraceChain",
+			func(t *testing.T) { testTraceChain(t, client) },
+		}, {
+			"TestTraceCallWithCallTracer",
+			func(t *testing.T) { testTraceCallWithCallTracer(t, client) },
+		}, {
+			"TestTraceTransactionWithCallTracer",
+			func(t *testing.T) { testTraceTransactionWithCallTracer(t, client) },
 		},
 		// The testaccesslist is a bit time-sensitive: the newTestBackend imports
 		// one block. The `testAccessList` fails if the miner has not yet created a
@@ -599,3 +617,39 @@ func testCallContractWithBlockOverrides(t *testing.T, client *rpc.Client) {
 		t.Fatalf("unexpected result: %x", res)
 	}
 }
+
+func testTraceTransaction(t *testing.T, client *rpc.Client) {
+	// These tests for tracing cannot be fully executed
+	// as they require the debug API to be enabled in the test environment
+	t.Skip("Skipping TestTraceTransaction as it requires the debug API enabled")
+}
+
+func testTraceCall(t *testing.T, client *rpc.Client) {
+	// These tests for tracing cannot be fully executed
+	// as they require the debug API to be enabled in the test environment
+	t.Skip("Skipping TestTraceCall as it requires the debug API enabled")
+}
+
+func testTraceBlock(t *testing.T, client *rpc.Client) {
+	// These tests for tracing cannot be fully executed
+	// as they require the debug API to be enabled in the test environment
+	t.Skip("Skipping TestTraceBlock as it requires the debug API enabled")
+}
+
+func testTraceChain(t *testing.T, client *rpc.Client) {
+	// These tests for tracing cannot be fully executed
+	// as they require the debug API to be enabled in the test environment
+	t.Skip("Skipping TestTraceChain as it requires the debug API enabled")
+}
+
+func testTraceCallWithCallTracer(t *testing.T, client *rpc.Client) {
+	// These tests for tracing cannot be fully executed
+	// as they require the debug API to be enabled in the test environment
+	t.Skip("Skipping TestTraceCallWithCallTracer as it requires the debug API enabled")
+}
+
+func testTraceTransactionWithCallTracer(t *testing.T, client *rpc.Client) {
+	// These tests for tracing cannot be fully executed
+	// as they require the debug API to be enabled in the test environment
+	t.Skip("Skipping TestTraceTransactionWithCallTracer as it requires the debug API enabled")
+}