docs: clarify prestateTracer behavior regarding code inclusion

This improves documentation to clarify that prestateTracer captures
full account state by default, including code, even when only specific
fields like balance are accessed. The trace output can be controlled
using the disableCode configuration option.

Resolves #31794

eth/tracers/TRACERS.md

@@ -0,0 +1,31 @@
+# Ethereum Go Client Tracers
+
+This document provides additional details about the tracers available in the Ethereum Go client.
+
+## Prestate Tracer
+
+The prestateTracer captures the state of accounts before transaction execution. It provides a detailed view of account states including balances, nonces, code, and storage.
+
+### Important Behaviors
+
+1. **Complete Account Capture**: When an account is accessed, the tracer captures its complete state by default, including code, even if only specific fields like balance were accessed during execution.
+
+2. **Configuration Options**:
+   - `diffMode`: If true, returns state modifications
+   - `disableCode`: If true, excludes contract code from the output (useful to reduce response size or when code isn't needed)
+   - `disableStorage`: If true, excludes contract storage from the output
+
+### Example Usage with CLI tools
+
+```bash
+# Include code (default behavior)
+cast rpc debug_traceCall \
+  '{"to":"$CONTRACT_ADDR","data":"$DATA"}' \
+  latest \
+  '{"tracer":"prestateTracer", "tracerConfig": { "diffMode": false } }'
+
+# Exclude code
+cast rpc debug_traceCall \
+  '{"to":"$CONTRACT_ADDR","data":"$DATA"}' \
+  latest \
+  '{"tracer":"prestateTracer", "tracerConfig": { "diffMode": false, "disableCode": true } }'

test/prestate-tracer-example/BalanceReader.sol

@@ -0,0 +1,8 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+contract BalanceReader {
+    function getExternalBalance(address account) external view returns (uint256) {
+        return account.balance;
+    }
+}

test/prestate-tracer-example/README.md

@@ -0,0 +1,15 @@
+# prestateTracer Behavior Test
+
+This directory contains a simple test case to demonstrate the behavior of the prestateTracer when accessing account balance.
+
+The test shows that when a contract calls `address.balance`, the prestateTracer will by default include the code of the target address in the trace output, even though only the balance field is accessed. This is the expected behavior of the tracer, but can be modified using the `disableCode` configuration option.
+
+## Files
+
+- `BalanceReader.sol`: A simple contract that reads an external account's balance
+- `test_commands.sh`: Shell commands to deploy and test the contract
+
+## Expected Results
+
+1. Without `disableCode`: The trace includes the full account state including code
+2. With `disableCode: true`: The trace includes only balance and nonce, but no code

test/prestate-tracer-example/test_commands.sh

@@ -0,0 +1,23 @@
+#!/bin/bash
+# This script demonstrates the behavior of the prestateTracer
+# when accessing account balance with and without disableCode option
+
+# Set up variables
+# Replace these values with actual addresses when deploying
+CONTRACT_ADDR="0xd343fdd530afc898c23f5d0db2d9849b71303425"
+OTHER_CONTRACT_ADDR="0x7d161ee7becca09e22ebf5fc22a17eecceded6b5"
+
+# Generate calldata for getExternalBalance function
+DATA=$(cast calldata "getExternalBalance(address)" $OTHER_CONTRACT_ADDR)
+
+echo "Testing prestateTracer without disableCode (default):"
+cast rpc debug_traceCall \
+  '{"to":"'"$CONTRACT_ADDR"'","data":"'"$DATA"'"}' \
+  latest \
+  '{"tracer":"prestateTracer", "tracerConfig": { "diffMode": false } }' --rpc-url http://localhost:8546 | jq
+
+echo -e "\nTesting prestateTracer with disableCode=true:"
+cast rpc debug_traceCall \
+  '{"to":"'"$CONTRACT_ADDR"'","data":"'"$DATA"'"}' \
+  latest \
+  '{"tracer":"prestateTracer", "tracerConfig": { "diffMode": false, "disableCode": true } }' --rpc-url http://localhost:8546 | jq