feat: Implement Forest.EthTraceCall

[akaladarshi]

Summary of changes

Changes introduced in this pull request:

• Continuing the work done in the feat: Implement Forest.EthTraceCall #6195

Reference issue to close (if applicable)

Closes #6185

Other information and links

Change checklist

• I have performed a self-review of my own code,
• I have made corresponding changes to the documentation. All new code adheres to the team's documentation standards,
• I have added tests that prove my fix is effective or that my feature works (if possible),
• I have made sure the CHANGELOG is up-to-date. All user-facing changes should be reflected in this document.

Summary by CodeRabbit

• New Features

  • Implemented EthTraceCall RPC method for detailed transaction tracing
  • Added state diff support to show account and storage changes during transaction execution

• Documentation

  • Added developer guide for trace_call implementation and testing workflows
  • Added user documentation for trace_call RPC method with usage examples and troubleshooting

• Tests

  • Added integration test harness for validating trace outputs
  • Added Tracer contract for EVM behavior testing

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

Walkthrough

This PR implements the trace_call RPC method for Forest with support for trace types and state diffs. It introduces new types for trace results and state diffs, adds state diff computation logic, includes an integration test suite with a test contract, and provides comprehensive documentation for users and developers.

Changes

Cohort / File(s)	Summary
Core RPC Implementation src/rpc/methods/eth.rs, src/rpc/mod.rs	Added public EthTraceCall RPC method with EthTraceType and EthTraceResults types; pre/post state computation, trace generation, and conditional state-diff output; updated call paths to use non-clone semantics for block_hash.
Type System & State Diffs src/rpc/methods/eth/types.rs	Introduced Delta, ChangedType, AccountDiff, and StateDiff types for tracking account/storage changes; updated EthAddress and EthHash to derive PartialOrd, Ord, Copy; changed to_filecoin_address signature from &self to self.
State Diff Computation src/rpc/methods/eth/trace.rs	Implemented build_state_diff with storage-diff integration using KAMT; added helpers for pre/post actor comparison, EVM storage diffing, and storage entry extraction; replaced env.caller.clone() with direct usage.
State Manager Updates src/state_manager/mod.rs	Updated apply_on_state_with_gas and call_with_gas to accept flush: bool parameter; returns now include optional state root Cid via vm.flush() when requested.
EVM Accessors src/shim/actors/builtin/evm/mod.rs	Added three new accessor methods: bytecode(), bytecode_hash(), contract_state() to expose EVM state data.
Clone Optimizations src/rpc/methods/eth/filter/mod.rs, src/tool/subcommands/api_cmd/api_compare_tests.rs, src/tool/subcommands/api_cmd/stateful_tests.rs	Replaced block_hash and address clones with direct values; adjusted test setups to use moved values instead of clones.
Dependencies & Configuration Cargo.toml	Added fvm_ipld_kamt = "0.4.5" dependency for KAMT-based storage diffing.
Gas Estimation Update src/rpc/methods/gas.rs	Updated call_with_gas invocation to handle new return signature with two additional unused values and extra boolean argument.
Testing & Test Contracts scripts/tests/trace_call_integration_test.sh, src/tool/subcommands/api_cmd/contracts/tracer/Tracer.sol, src/tool/subcommands/api_cmd/test_snapshots_ignored.txt	Added comprehensive bash integration test script with Forest/Anvil trace comparison; created Tracer contract with storage, ETH flow, and trace-testing functions; updated snapshot ignore list.
Documentation docs/docs/developers/guides/trace_call_guide.md, docs/docs/users/knowledge_base/RPC/trace_call.md, docs/dictionary.txt	Added developer guide covering Tracer.sol usage and integration testing; added user guide detailing trace_call RPC method, request/response formats, and examples; expanded dictionary with blockchain terminology.

Sequence Diagram

sequenceDiagram
    participant Client
    participant RPC as RPC Handler<br/>(trace_call)
    participant StateManager
    participant VM
    participant Store as Blockstore
    
    Client->>RPC: call trace_call(message, traceTypes, blockTag)
    RPC->>StateManager: Get state for blockTag
    StateManager->>Store: Load pre-execution state
    Store-->>StateManager: pre_state
    
    RPC->>VM: Invoke transaction with gas
    VM->>VM: Execute message
    VM-->>RPC: execution result, gas usage
    
    RPC->>StateManager: Get post-execution state
    StateManager->>Store: Load post-execution state
    Store-->>StateManager: post_state
    
    alt if StateDiff requested
        RPC->>RPC: build_state_diff(pre_state, post_state, touched_addresses)
        RPC->>Store: Extract EVM storage entries
        Store-->>RPC: storage map
        RPC->>RPC: Compute Delta for each slot
        RPC->>RPC: Compare balance, nonce, code
    end
    
    RPC->>RPC: Format traces and state diffs
    RPC-->>Client: EthTraceResults (traces + optional stateDiff)

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• feat(rpc): Add support for the EthTraceReplayBlockTransactions V2 API #6444: Modifies Ethereum trace RPC implementation (src/rpc/methods/eth.rs) and adjusts trace/state-diff handling and serialization with overlapping code-level changes.
• fix: avoid unecessary clone(s) in some Eth RPC methods #6253: Updates Eth RPC code to remove unnecessary clones in src/rpc/methods/eth/filter/mod.rs, sharing similar optimization patterns.
• fix: contract deployment via forge failing #6118: Modifies state_manager and Eth RPC code (call_with_gas signatures and eth_getCode handling) with overlapping function-level changes.

Suggested reviewers

• LesnyRumcajs
• sudo-shashank

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 57.45% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Out of Scope Changes check	❓ Inconclusive	While most changes directly support trace_call implementation, several modifications appear tangential: Cargo.toml dependency (fvm_ipld_kamt), dictionary entries, and numerous clone-to-value refactorings lack clear justification.	Clarify the necessity of the fvm_ipld_kamt dependency, dictionary additions, and whether clone removal changes are essential vs. optimization-only.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat: Implement Forest.EthTraceCall' clearly and specifically describes the main change—implementing the EthTraceCall RPC method.
Linked Issues check	✅ Passed	The PR implements the trace_call RPC method, includes comprehensive tests (integration test script, extended test coverage in eth.rs and trace.rs), and adds extensive documentation (trace_call.md, trace_call_guide.md).

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch akaladarshi/eth-trace-call

Tip

Issue Planner is now in beta. Read the docs and try it out! Share your feedback on Discord.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[LesnyRumcajs]

As discussed, let's have a short guide in docs outlining its usage. This is important in light of various formats used across the Ethereum ecosystem for the output of this method.