feat(rpc): Add support for the `EthTraceReplayBlockTransactions` V2 API by akaladarshi · Pull Request #6444 · ChainSafe/forest

akaladarshi · 2026-01-19T18:32:30Z

Summary of changes

Changes introduced in this pull request:

Adds support for the EthTraceReplayBlockTransactions V2 API
Small Refactor
Fix the discrepancy in EthTraceReplayBlockTransactions response

Reference issue to close (if applicable)

Closes #6308

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 a V2 Ethereum trace-replay RPC endpoint (new API path) returning the same trace items with updated parameters.
Changes
- Trace responses always include stateDiff and vmTrace (nullable) for compatibility.
- Improved validation and clearer error responses for trace type parameters.
- Aligned V1/V2 handling to a shared implementation for consistent results.
Tests
- Extended RPC test coverage and updated snapshots to include the V2 endpoint.

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

coderabbitai · 2026-01-19T18:32:47Z

Walkthrough

Adds a V2 RPC method EthTraceReplayBlockTransactionsV2, centralizes trace replay logic into a new async helper eth_trace_replay_block_transactions used by both V1 and V2, enforces V2 traceTypes validation, changes serialization to always emit state_diff and vm_trace (nullable), and updates tests, snapshots, and RPC registration.

Changes

Cohort / File(s)	Summary
RPC method implementation `src/rpc/methods/eth.rs`	Added `EthTraceReplayBlockTransactionsV2` (Params = `(ExtBlockNumberOrHash, Vec<String>)`, Ok = `Vec<EthReplayBlockTransactionTrace>`). Introduced `async fn eth_trace_replay_block_transactions<DB>(ctx, ts)` and updated V1 to delegate to it. V2 validates `traceTypes` and uses a V2 tipset resolver.
Types / serialization `src/rpc/methods/eth/types.rs`	Removed `#[serde(skip_serializing_if = "Option::is_none")]` from `state_diff` and `vm_trace` on `EthReplayBlockTransactionTrace`, so those fields serialize as `null` when absent.
RPC registration `src/rpc/mod.rs`	Registered `EthTraceReplayBlockTransactionsV2` in the `for_each_rpc_method` macro.
Tests & snapshots `src/tool/subcommands/api_cmd/api_compare_tests.rs`, `src/tool/subcommands/api_cmd/test_snapshots.txt`	Added test entry for V2 (`EthTraceReplayBlockTransactionsV2::request((ExtBlockNumberOrHash, Vec<String>))`) and replaced/added snapshot files for the V2 output.
Docs / changelog `CHANGELOG.md`	Documented the new API v2 method and the change to always include `stateDiff` and `vmTrace` (nullable) in responses.

Sequence Diagram(s)

mermaid
sequenceDiagram
participant Client
participant RPC as "RPC Method (V1/V2)"
participant Resolver as "Tipset Resolver"
participant Tracer as "Trace Executor"
participant DB as "DB / State Viewer"
participant Assembler as "Trace Assembler"

Client->>RPC: EthTraceReplayBlockTransactions request
RPC->>Resolver: resolve tipset (V1 or V2)
Resolver-->>RPC: tipset
RPC->>Tracer: execute traces for tipset
Tracer-->>RPC: raw trace results
RPC->>DB: resolve tx hashes & fetch state snapshots
DB-->>RPC: tx hashes / state
RPC->>Assembler: build envs, capture vm_trace/state_diff, assemble results
Assembler-->>Client: Vec

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

feat: enable V2 API support for basic Eth and Filecoin RPC methods #6171 — related modifications to Eth trace replay and V2 API support for trace endpoints.
fix(rpc): register RPC methods for different versions into different modules #6219 — related RPC-versioning changes that add V2 method variants and registration.

Suggested reviewers

hanabi1224
sudo-shashank
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 accurately describes the main change: adding V2 API support for EthTraceReplayBlockTransactions, which is the primary focus of all code modifications.
Linked Issues check	✅ Passed	The pull request successfully implements the EthTraceReplayBlockTransactions V2 endpoint as required by issue `#6308`, with a refactor and fixes included.
Out of Scope Changes check	✅ Passed	All changes are directly related to implementing the V2 API endpoint: adding the V2 variant, refactoring shared logic, updating types, and adjusting serialization behavior for Lotus compatibility.

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

✨ Finishing touches

📝 Generate docstrings

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

codecov · 2026-01-20T09:46:43Z

Codecov Report

❌ Patch coverage is 70.17544% with 17 lines in your changes missing coverage. Please review.
✅ Project coverage is 58.73%. Comparing base (1546c7c) to head (3f9cb65).
⚠️ Report is 3 commits behind head on main.

Files with missing lines	Patch %	Lines
src/rpc/methods/eth.rs	70.17%	10 Missing and 7 partials ⚠️

Additional details and impacted files

Files with missing lines	Coverage Δ
src/rpc/methods/eth/types.rs	`66.06% <ø> (ø)`
src/rpc/mod.rs	`24.47% <ø> (ø)`
src/rpc/methods/eth.rs	`67.67% <70.17%> (+0.01%)`	⬆️

... and 9 files 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 1546c7c...3f9cb65. Read the comment docs.

🚀 New features to boost your workflow:

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

LesnyRumcajs · 2026-01-20T16:18:10Z

src/rpc/methods/eth.rs


-        let state = StateTree::new_from_root(ctx.store_owned(), &state_root)?;
+pub enum EthTraceReplayBlockTransactionsV2 {}
+impl RpcMethod<2> for EthTraceReplayBlockTransactionsV2 {


description?

I didn't notice this earlier that some of the other API's also doesn't have a Description, I will create an issue for this so we can add in all API's.

@coderabbitai create a issue for the adding Description to all the API's available in the forest.

🧩 Analysis chain

@akaladarshi I'll create a GitHub issue to track adding DESCRIPTION fields to all RPC methods in Forest.

🏁 Script executed:

#!/bin/bash # Create a GitHub issue for adding DESCRIPTION to all RPC methods gh issue create \ --repo ChainSafe/forest \ --title "Add DESCRIPTION to all RPC methods" \ --body "## Background Many RPC method implementations in Forest are missing the \`DESCRIPTION\` constant, which should provide documentation about what each method does. ## Task Add the \`DESCRIPTION\` field to all RPC method implementations throughout the codebase. This will improve API documentation and help users understand what each method does. ## Example \`\`\`rust impl RpcMethod<2> for EthTraceReplayBlockTransactions { const NAME: &'static str = \"Filecoin.EthTraceReplayBlockTransactions\"; const NAME_ALIAS: Option<&'static str> = Some(\"trace_replayBlockTransactions\"); const DESCRIPTION: Option<&'static str> = Some( \"Replays all transactions in a block returning the requested traces for each transaction.\", ); // ... } \`\`\` ## Context Related PR: `#6444` Related comment: https://github.com/ChainSafe/forest/pull/6444#discussion_r2709084181 cc: `@akaladarshi`" \ --assignee akaladarshi

Length of output: 47

@akaladarshi I've created issue #6460 to track adding DESCRIPTION fields to all RPC methods in Forest. The issue has been assigned to you and includes the context from this PR discussion.

LesnyRumcajs · 2026-01-20T16:21:45Z

src/rpc/methods/eth.rs

+        ctx: Ctx<impl Blockstore + Send + Sync + 'static>,
+        (block_param, trace_types): Self::Params,
+    ) -> Result<Self::Ok, ServerError> {
+        if trace_types.as_slice() != ["trace"] {


is there a point in using anyhow here? Seems to me it'd be easier to define a new method on ServerError, e.g., ServerError::unsupported_params. It'd be cheaper.

I guess we can use the ServerError::invalid_params("only 'trace' is supported", None)

…snapshot tests

LesnyRumcajs · 2026-01-21T09:46:02Z

src/rpc/methods/eth/types.rs

 #[serde(rename_all = "camelCase")]
 pub struct EthReplayBlockTransactionTrace {
    pub output: EthBytes,
-    #[serde(skip_serializing_if = "Option::is_none")]


so this was incorrect?

what's the struct in Lotus?

Here is the lotus struct for this, and yeah I saw in the lotus snapshot response that the fields are set to null.

What's the Lotus snapshot response?

Lotus returns something like this:

"lotus_response": { "Ok": [ { "output": "0x0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000600000000000000000000000000000000000000000000000000000000000000000", "stateDiff": null, "trace": [ { "action": { "callType": "call", "from": "0xff00000000000000000000000000000000021cc9", "gas": "0xbdf9c", "input": "0x868e10c40000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000600000000000000000000000000000000000000000000000000000000000000000", "to": "0x0f96b5f075e13c3a552c1481a1ae00f9c042d58b", "value": "0x917bd023e0703660" }, "result": { "gasUsed": "0x12d48f", "output": "0x0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000600000000000000000000000000000000000000000000000000000000000000000" }, "subtraces": 0, "traceAddress": [], "type": "call" } ], "transactionHash": "0x77b925676c49edbc6096d6b67002202a11f8c0160cbba1fe40f4162cb734e598", "vmTrace": null },

Ok, cool, makes sense.

…PI (#6444)

akaladarshi force-pushed the akaladarshi/replay-block-tx-v2 branch from 62d9e13 to 1b2504a Compare January 20, 2026 08:59

akaladarshi marked this pull request as ready for review January 20, 2026 08:59

akaladarshi requested a review from a team as a code owner January 20, 2026 08:59

akaladarshi requested review from LesnyRumcajs and hanabi1224 and removed request for a team January 20, 2026 08:59

akaladarshi added the RPC requires calibnet RPC checks to run on CI label Jan 20, 2026

LesnyRumcajs reviewed Jan 20, 2026

View reviewed changes

akaladarshi added 4 commits January 21, 2026 00:38

Add EthTraceReplayBlockTransactionsV2 API support

10b6635

add api snapshot test

222b07b

fix eth replay block transaction response descrepancy and update the …

4386854

…snapshot tests

address comments

505c6f5

akaladarshi force-pushed the akaladarshi/replay-block-tx-v2 branch from 6cbc78a to 505c6f5 Compare January 20, 2026 19:08

update changelog

0741774

LesnyRumcajs reviewed Jan 21, 2026

View reviewed changes

coderabbitai bot mentioned this pull request Jan 22, 2026

Add DESCRIPTION to all RPC methods #6460

Open

Merge branch 'main' into akaladarshi/replay-block-tx-v2

3f9cb65

LesnyRumcajs approved these changes Jan 22, 2026

View reviewed changes

LesnyRumcajs added this pull request to the merge queue Jan 22, 2026

github-merge-queue bot pushed a commit that referenced this pull request Jan 22, 2026

feat(rpc): Add support for the EthTraceReplayBlockTransactions V2 A…

09333d7

…PI (#6444)

github-merge-queue bot removed this pull request from the merge queue due to failed status checks Jan 22, 2026

akaladarshi added this pull request to the merge queue Jan 22, 2026

Merged via the queue into main with commit 3061897 Jan 22, 2026
44 checks passed

akaladarshi deleted the akaladarshi/replay-block-tx-v2 branch January 22, 2026 19:33

sudo-shashank pushed a commit that referenced this pull request Jan 23, 2026

feat(rpc): Add support for the EthTraceReplayBlockTransactions V2 A…

b2df58c

…PI (#6444)

coderabbitai bot mentioned this pull request Feb 5, 2026

fix: forge script bug #6541

Merged

6 tasks

coderabbitai bot mentioned this pull request Feb 19, 2026

feat: Implement Forest.EthTraceCall #6412

Merged

4 tasks

This was referenced Mar 10, 2026

feat(api): Implement debug_traceTransaction API #6685

Draft

refactor: prepare for the changes in debug trace transaction #6731

Open

Conversation

akaladarshi commented Jan 19, 2026 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary of changes

Reference issue to close (if applicable)

Other information and links

Change checklist

Summary by CodeRabbit

Uh oh!

coderabbitai bot commented Jan 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Sequence Diagram(s)

Estimated code review effort

Possibly related PRs

Suggested reviewers

Uh oh!

codecov bot commented Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

akaladarshi Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

coderabbitai bot Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

akaladarshi commented Jan 19, 2026 •

edited by coderabbitai bot

Loading

coderabbitai bot commented Jan 19, 2026 •

edited

Loading

codecov bot commented Jan 20, 2026 •

edited

Loading

akaladarshi Jan 20, 2026 •

edited

Loading