docs: add reth migration docs

[tac0turtle]

Overview

This Pr documents how to do a reth migration, this is in the case of a consensus upgrade or fault of the network

closes #2392

[github-actions]

The latest Buf updates on your PR. Results from workflow CI and Release / buf-check (pull_request).

Build	Format	Lint	Breaking	Updated (UTC)
✅ passed	⏩ skipped	✅ passed	✅ passed	Aug 20, 2025, 8:23 AM

[gemini-code-assist]

Summary of Changes

Hello @tac0turtle, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces comprehensive documentation for performing chain migrations on Evolve EVM-based blockchains. It provides a detailed, step-by-step guide for exporting current chain state, preparing new genesis configurations, initializing new chains, and coordinating with various external services like bridges, block explorers, and exchanges. The new guide aims to assist users in major upgrades, network resets, or transitioning between different chain configurations.

Highlights

• New Migration Guide: A comprehensive guide titled "Evolve EVM Chain Migration Guide" has been added, detailing the process of migrating an EVM chain using reth's dump-genesis and init functions.
• Sidebar Integration: The newly added migration guide is now accessible via the documentation sidebar, integrated under the "Guides" section within the "EVM" category.
• Detailed Migration Steps: The guide provides detailed, step-by-step instructions covering pre-migration planning, coordinating migration block height, stopping nodes, exporting state, preparing new genesis configurations, initializing the new chain, updating node configurations, and starting the new chain.
• External Service Coordination: Crucial sections are included for coordinating chain migrations with external services such as bridges, block explorers, exchanges, DeFi protocols, and wallet providers, outlining specific actions and checklists for each.
• Considerations and Troubleshooting: The documentation also addresses important considerations like data integrity, network consensus, rollback planning, and communication strategies, along with a troubleshooting section for common issues and a migration timeline template.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in issue comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request adds a comprehensive guide for performing a chain migration. The documentation is well-structured and covers the entire process from planning to post-migration validation. I've identified a critical issue where a command in the troubleshooting section contradicts information provided earlier in the guide. I've also found a few areas for improvement, including removing a redundant command and fixing some non-standard markdown formatting for lists. Overall, this is a great addition to the documentation.

[github-actions]

PR Preview Action v1.6.2
Preview removed because the pull request was closed.
2025-08-22 09:11 UTC

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 72.75%. Comparing base (961cb31) to head (74cf397).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2565   +/-   ##
=======================================
  Coverage   72.75%   72.75%           
=======================================
  Files          72       72           
  Lines        7301     7301           
=======================================
  Hits         5312     5312           
  Misses       1566     1566           
  Partials      423      423           

Flag	Coverage Δ
combined	72.75% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

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

[claude]

Claude finished @tac0turtle's task —— View job

---

PR Review: Reth Migration Documentation

Review Tasks

• Read repository guidelines and context
• Review the migration guide documentation
• Check sidebar integration changes
• Analyze technical accuracy and security considerations
• Provide comprehensive feedback

Overall Assessment

This PR adds comprehensive documentation for chain migration using reth, which fills an important gap in the documentation. The guide is well-structured and covers the essential aspects of performing a chain migration. However, there are several critical issues that need to be addressed.

Critical Issues

1. Command Inconsistency in Troubleshooting Section (docs/guides/evm/migration.md:444)

# Current problematic command:
reth dump-genesis --datadir /path/to/datadir --block <HEIGHT> --output genesis-export.json

Issue: This command contradicts the statement on line 76 that reth dump-genesis does not accept a --block flag. This will cause the command to fail and confuse users.

Fix: Remove the --block <HEIGHT> flag:

reth dump-genesis --datadir /path/to/datadir --output genesis-export.json

2. Binary Name Inconsistency (docs/guides/evm/migration.md:93, 108, etc.)

The guide inconsistently uses ev-reth and reth commands. Line 93 uses ev-reth dump-genesis while other sections use reth dump-genesis. This inconsistency could confuse users about which binary to use.

Medium Priority Issues

3. Non-Standard Markdown Formatting (docs/guides/evm/migration.md:82-84, 127-130)

The guide uses unicode bullets (•) with tab indentation instead of standard markdown list syntax. This can cause rendering issues across different markdown viewers.

Current:

	• Sync your Evolve/reth node to the agreed migration height.

Should be:

- Sync your Evolve/reth node to the agreed migration height.

4. Redundant Command (docs/guides/evm/migration.md:142)

There's a redundant cp genesis-export.json genesis-new.json command since the subsequent jq command creates the new file anyway.

Security & Best Practices

Positive Security Aspects:

• ✅ Emphasizes backing up critical configuration directories
• ✅ Warns against deleting the $HOME_DIR/config directory containing node identity
• ✅ Includes comprehensive external service coordination requirements
• ✅ Provides rollback planning guidance
• ✅ Mentions secure distribution of genesis files

Additional Security Recommendations:

• Consider adding checksum verification steps for the exported genesis file
• Add guidance on securing the migration process itself (who has access, audit logging)
• Include verification steps to ensure the exported state matches expected totals

Technical Accuracy

Well-Covered Topics:

• ✅ Proper sequence of stopping nodes before state export
• ✅ Two-option approach for handling migration height (stop vs. rewind)
• ✅ Comprehensive external service coordination
• ✅ Post-migration validation steps
• ✅ Timeline template with realistic milestones

Areas for Improvement:

• The guide could benefit from more specific error handling examples
• Missing guidance on monitoring during the migration process
• Could include more details on validator set coordination

Documentation Quality

Strengths:

• Comprehensive coverage: Covers all major aspects from planning to post-migration
• Clear structure: Well-organized with logical flow
• Practical examples: Includes actual commands and configuration snippets
• Risk awareness: Addresses rollback planning and contingencies
• Stakeholder consideration: Thorough coverage of external service impacts

Minor Improvements:

• Some code blocks could benefit from syntax highlighting specification
• Consider adding a "Prerequisites" verification script
• Timeline estimates could be more specific for different network sizes

Test Coverage Assessment

Since this is documentation-only, traditional test coverage doesn't apply. However, the guide would benefit from:

• Example test commands for validating each step
• Testnet migration walkthrough
• Automated verification scripts for common checks

Performance Considerations

The guide appropriately covers:

• ✅ Disk space requirements (2x current state size)
• ✅ Memory considerations for state export
• ✅ Coordination timing to minimize downtime

Sidebar Integration Review (docs/.vitepress/config.ts)

The sidebar integration is correctly implemented:

• ✅ Added under the EVM section at lines 286-288
• ✅ Follows existing naming conventions
• ✅ Proper indentation and structure

Recommendations

1. Fix the critical command inconsistency in the troubleshooting section
2. Standardize binary naming throughout the document
3. Convert unicode bullets to standard markdown for better compatibility
4. Remove the redundant copy command
5. Consider adding checksum verification steps for enhanced security
6. Add more specific error scenarios with troubleshooting steps

Conclusion

This is a valuable addition to the documentation that addresses an important operational need. The comprehensive coverage and practical approach make it a strong resource. With the critical command inconsistency fixed and the formatting issues addressed, this will be an excellent guide for chain migrations.

The attention to external service coordination and security considerations demonstrates thorough understanding of the operational complexities involved in chain migrations.

Recommendation: Approve after addressing the critical command inconsistency issue.