feat(cli): add reth report command for debug report generation

[meetrick]

Motivation

When users encounter state root mismatch or EVM execution errors during sync, they need to manually collect multiple pieces of information (checksums, logs, block info, version history, etc.) for bug reports. This process is error-prone, time-consuming, and results in inconsistent reports.

This PR addresses issue #18569 and the TODO in the codebase:

// TODO: automate the process outlined below so the user can just send in a debugging package

Solution

Add a new top-level reth report command that automates the collection of all necessary debugging information into a single .tar.gz archive.

Usage

reth report --block <BLOCK_NUMBER> [--checksum] [-y] [--output report.tar.gz]

What it collects

Information	Description
metadata.json	Timestamp, reth version, chain name, data directory
block_info.json	Block number, hash, parent hash, state root, transactions/receipts root
db_stats.json	Latest block number, table statistics (entries, size), optional checksums
version_history.json	Full VersionHistory table dump
logs/	All reth.log* files from the log directory
invalid_block_hooks/	All files from the invalid block hooks directory

Features

• User consent prompt: Privacy notice with confirmation before collecting data (-y to skip)
• GitHub issue link: Generates a pre-filled issue creation URL
• Checksum option: --checksum flag to include database table checksums (takes a long time)
• Flexible output: Custom output path via --output flag

Error guidance

Updated error messages to guide users to run reth report:

• State root mismatch errors (INVALID_STATE_ROOT_ERROR_MESSAGE)
• EVM execution errors (DEBUG_REPORT_SUGGESTION)

Example Output

======================================================================
RETH DEBUG REPORT GENERATOR
======================================================================

This tool will collect the following information:
  • Database table statistics
  • VersionHistory table (client version history)
  • Log files from: /path/to/datadir/logs
  • Invalid block hook outputs from: /path/to/datadir/invalid_block_hooks
  • Block header information for block #12345000

⚠️  PRIVACY NOTICE:
  The generated archive may contain sensitive information about your node.
  Please review the contents before sharing publicly.

Do you want to proceed? [y/N]: y

======================================================================
DEBUG REPORT GENERATED SUCCESSFULLY
======================================================================

Archive saved to: reth_report_20260108_123456.tar.gz

📋 To create a GitHub issue, visit:
https://github.com/paradigmxyz/reth/issues/new?title=State%20Root%20Error%20at%20Block%2012345000&labels=C-bug

⚠️  IMPORTANT:
   • You must be logged into GitHub in your browser
   • The issue will be created under YOUR GitHub account
   • Please attach the generated archive to your issue
   • Review the archive contents before sharing

Documentation

Added CLI documentation for both reth and op-reth:

File	Change
docs/vocs/docs/pages/cli/reth/report.mdx	New command documentation
docs/vocs/docs/pages/cli/op-reth/report.mdx	New command documentation
docs/vocs/sidebar-cli-reth.ts	Added sidebar entry
docs/vocs/sidebar-cli-op-reth.ts	Added sidebar entry

Related

Closes #18569 (MVP implementation without S3 upload - can be added in follow-up PR)

[mediocregopher]

@meetrick thanks for the PR, this is a good first step but I think we had another UX in mind for this case. If you could check out #18569 you can see what we were thinking. If you'd like to implement that I'd be happy to assign it, we don't yet have an S3 bucket set up but once we get an MVP of the implementation that step could be taken care of on our end.

[meetrick]

@mediocregopher Thanks for the feedback! I see the difference now.

My PR focuses on generating a local JSON report specifically for state root errors,
while #18569 aims for a more comprehensive reth report UX.

I’d be happy to work on #18569 instead. Just to confirm a few things:

1. Would you prefer that I close this PR and start fresh, or adapt it in that direction?
2. For an initial MVP, is it fine if the command only creates a local archive, and we add S3 later?
3. Should reth report eventually replace the current error message guidance, or live alongside it?

[mediocregopher]

@meetrick

Would you prefer that I close this PR and start fresh, or adapt it in that direction?

That's up to you, if you think your work in this PR can be adapted then go for it, or start a new one if now.

For an initial MVP, is it fine if the command only creates a local archive, and we add S3 later?

Yes I think that's a good place to start.

Should reth report eventually replace the current error message guidance, or live alongside it?

I think it should replace it, ultimately anything we want to have during state root debugging should be automatically grabbed by the report command.