feat(rpc): Add support for the EthTraceBlock V2 API

[akaladarshi]

Summary of changes

Changes introduced in this pull request:

• Adds EthTraceBlock API V2 support

Reference issue to close (if applicable)

Closes #6306

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

  • Added EthTraceBlock V2 API (Filecoin.EthTraceBlock / trace_block) to return traces for a given block; V1 now has a public description and both versions share unified trace-building behavior.

• Tests

  • Added tests for EthTraceBlock V2 covering Pending, Latest, Safe, Finalized, and specific block-number cases; updated test snapshots.

• Documentation

  • Changelog updated to note V2 API support.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

Added a v2 RPC for Filecoin.EthTraceBlock, extracted shared block-tracing into a helper used by both v1 and v2, updated EthTraceTransaction to use v2 tipset resolution and the helper, registered the new method, and added tests and snapshots.

Changes

Cohort / File(s)	Summary
Eth trace RPC methods & helper src/rpc/methods/eth.rs	Added EthTraceBlockV2 (ApiPaths::V2, alias trace_block), set DESCRIPTION on v1, extracted tracing logic into async fn eth_trace_block<DB>(...) used by v1/v2, and updated EthTraceTransaction to resolve via v2 and call the helper.
RPC dispatcher registration src/rpc/mod.rs	Registered EthTraceBlockV2 in the for_each_rpc_method macro to expose the new RPC method.
Tests & snapshots src/tool/subcommands/api_cmd/api_compare_tests.rs, src/tool/subcommands/api_cmd/test_snapshots.txt	Added RpcTest entries for EthTraceBlockV2 (identity/basic cases: Pending/Latest/Safe/Finalized) and added corresponding snapshot filenames.
Changelog CHANGELOG.md	Added entry documenting Filecoin.EthTraceBlock v2 support.

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant RPC_Dispatcher
  participant EthHandler as EthTraceBlockV2_Handler
  participant TipsetResolver
  participant EthHelper as eth_trace_block
  participant Blockstore
  participant Tracer

  Client->>RPC_Dispatcher: Filecoin.EthTraceBlock request
  RPC_Dispatcher->>EthHandler: dispatch to handler
  EthHandler->>TipsetResolver: resolve block param (v2)
  TipsetResolver-->>EthHandler: Tipset
  EthHandler->>EthHelper: eth_trace_block(ctx, tipset)
  EthHelper->>Blockstore: load blocks, receipts, state_root
  Blockstore-->>EthHelper: block data & receipts
  EthHelper->>Tracer: execute traces / collect execution traces & messages
  Tracer-->>EthHelper: traces
  EthHelper-->>EthHandler: Vec<EthBlockTrace>
  EthHandler-->>RPC_Dispatcher: return traces
  RPC_Dispatcher-->>Client: respond

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• feat: enable V2 API support for basic Eth and Filecoin RPC methods #6171 — Related changes to Eth trace RPCs and V2 exposure/refactor.
• Add support for the Filecoin.EthGetTransactionByBlockNumberAndIndex V2 #6469 — Adds V2 RPC variants and extracts shared helpers around eth trace logic.
• Add support for the Filecoin.EthCall V2 #6339 — Implements V2 variants of Eth RPCs and touches v2 tipset resolution helpers.

Suggested reviewers

• hanabi1224
• LesnyRumcajs

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat(rpc): Add support for the EthTraceBlock V2 API' clearly and concisely describes the main change: adding V2 API support for the EthTraceBlock RPC method.
Linked Issues check	✅ Passed	The pull request successfully implements Filecoin.EthTraceBlock for RPC v2, adding a new EthTraceBlockV2 method with V2 API path, tests, and changelog entry as required by issue #6306.
Out of Scope Changes check	✅ Passed	All changes are directly related to implementing EthTraceBlock V2 API support: new RPC method variant, helper function, test cases, snapshots, and changelog entry are all in scope.

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

---

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

[codecov]

Codecov Report

❌ Patch coverage is 82.14286% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 61.03%. Comparing base (7f2f0db) to head (11a8143).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
src/rpc/methods/eth.rs	82.14%	2 Missing and 3 partials ⚠️

Additional details and impacted files

Files with missing lines	Coverage Δ
src/rpc/mod.rs	24.47% <ø> (ø)
src/rpc/methods/eth.rs	68.88% <82.14%> (+0.04%)	⬆️

... and 1 file with indirect coverage changes

---

Continue to review full report in Codecov by Sentry.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 7f2f0db...11a8143. Read the comment docs.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[sudo-shashank]

@akaladarshi let's update changelog and it would be good to update the change checklist in PR details.

[coderabbitai]

Actionable comments posted: 0

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/rpc/methods/eth.rs (1)

3711-3753: Fix transaction_position off‑by‑one.

msg_idx is incremented before it is used, so the first trace in a block reports transaction_position = 1 instead of 0. This will misalign trace output with eth_getTransactionByBlockNumberAndIndex and other zero‑based indices.

🐛 Proposed fix

-    let mut msg_idx = 0;
+    let mut msg_idx: i64 = 0;
     for ir in trace.into_iter() {
         // ignore messages from system actor
         if ir.msg.from == system::ADDRESS.into() {
             continue;
         }
-        msg_idx += 1;
+        let tx_position = msg_idx;
+        msg_idx += 1;
         let tx_hash = EthGetTransactionHashByCid::handle(ctx.clone(), (ir.msg_cid,)).await?;
         let tx_hash = tx_hash
             .with_context(|| format!("cannot find transaction hash for cid {}", ir.msg_cid))?;
         let mut env = trace::base_environment(&state, &ir.msg.from)
             .map_err(|e| format!("when processing message {}: {}", ir.msg_cid, e))?;
         if let Some(execution_trace) = ir.execution_trace {
             trace::build_traces(&mut env, &[], execution_trace)?;
             for trace in env.traces {
                 all_traces.push(EthBlockTrace {
@@
-                    transaction_position: msg_idx as i64,
+                    transaction_position: tx_position,
                 });
             }
         }
     }