Skip to content

docs: add v0.4.0 upgrade guide#220

Merged
tac0turtle merged 5 commits intomainfrom
jgimeno/retract-v03x-upgrade-doc
Apr 17, 2026
Merged

docs: add v0.4.0 upgrade guide#220
tac0turtle merged 5 commits intomainfrom
jgimeno/retract-v03x-upgrade-doc

Conversation

@randygrok
Copy link
Copy Markdown
Contributor

@randygrok randygrok commented Apr 15, 2026

Description

Add upgrade guide for v0.4.0, covering all changes since v0.3.0: reth v2.0.0 upgrade, ev-deployer CLI, ev-dev local chain, transaction sponsor service, granular tracing with EV_TRACE_LEVEL, EIP-2718 decode fix, and txpool fallback restricted to dev mode. The existing v0.3.0 upgrade guide is left as-is.

Summary by CodeRabbit

  • Documentation
    • Added comprehensive v0.4.0 upgrade guide with detailed migration steps, chainspec references, and examples; removed the v0.3.0 upgrade guide.
  • New Features
    • Added an ev-deployer CLI and finer-grained tracing instrumentation.
  • Changed
    • Upgraded to Reth v2.0.0; default Storage V2 for new nodes; build system migrated from Makefile to just.
  • Bug Fixes
    • Fixed Engine API payload decoding; restricted txpool fallback behavior to dev mode; added related test coverage.

@randygrok randygrok requested a review from a team as a code owner April 15, 2026 08:02
@coderabbitai
Copy link
Copy Markdown

coderabbitai bot commented Apr 15, 2026

Warning

Rate limit exceeded

@tac0turtle has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 59 minutes and 8 seconds before requesting another review.

Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 59 minutes and 8 seconds.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: c2ef2d65-1ab0-4ebe-88c2-61873dc59a2e

📥 Commits

Reviewing files that changed from the base of the PR and between 109c69f and b4ba074.

📒 Files selected for processing (2)
  • CHANGELOG.md
  • docs/UPGRADE-v0.4.0.md
📝 Walkthrough

Walkthrough

Adds a new upgrade guide docs/UPGRADE-v0.4.0.md, updates the changelog with v0.4.0 notes, and removes the previous docs/UPGRADE-v0.3.0.md; changes document Reth v2.0.0 migration, config/behavior adjustments, payload decode fix, and build-tool migration to just.

Changes

Cohort / File(s) Summary
New Upgrade Guide
docs/UPGRADE-v0.4.0.md
Adds a comprehensive v0.4.0 upgrade guide detailing unchanged/changed behaviors, Reth v2.0.0 migration (Storage V2 default), Storage V1 compatibility, txpool fallback restricted to --dev, EIP-2718 payload decode fix, chainspec field references, examples, and operational notes (make→just).
Changelog Update
CHANGELOG.md
Updates Unreleased section: adds ev-deployer CLI, tracing spans, reorders EV_TRACE_LEVEL, notes Reth v2.0.0 upgrade details (revm/alloy versions), txpool fallback restriction, payload decode fix, and build migration to Justfile.
Removed Old Guide
docs/UPGRADE-v0.3.0.md
Deletes the v0.3.0 upgrade document and its historical migration instructions and examples.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Poem

🐇 I hopped through changelogs late at night,
Wrote a guide to make migrations light,
With Reth and storage set anew,
A carrot of docs to guide your view,
✨🐾

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Description check ⚠️ Warning The description is missing critical template sections including Type of Change checkbox, Related Issues, Checklist items, Testing details, and Additional Notes. Complete the PR description by filling out all required template sections: select appropriate Type of Change option(s), link any related issues, check off relevant checklist items, describe testing performed, and add any additional context needed.
✅ Passed checks (2 passed)
Check name Status Explanation
Title check ✅ Passed The title directly matches the main changeset: it introduces a new v0.4.0 upgrade guide documentation file.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

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

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch jgimeno/retract-v03x-upgrade-doc

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

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

@claude
Copy link
Copy Markdown

claude bot commented Apr 15, 2026

Claude finished @randygrok's task —— View job


PR Review Complete

I've completed a thorough review of this PR that adds a v0.4.0 upgrade guide. Overall, this is well-structured documentation that effectively consolidates migration information. Here's my detailed feedback:

Todo List:

  • Read repository guidelines (CLAUDE.md)
  • Review CHANGELOG.md changes
  • Review new upgrade guide (docs/UPGRADE-v0.4.0.md)
  • Check for security concerns
  • Analyze previous reviewer feedback
  • Provide comprehensive review feedback

Review Summary

✅ Strengths:

  • Clear Structure: Well-organized upgrade guide with logical sections and proper hierarchical flow
  • Version Clarity: Correctly addresses the v0.3.0 beta situation and provides clear upgrade paths
  • Comprehensive Coverage: Includes all major changes from Reth v2.0.0 upgrade, Storage V2, build system migration, and various fixes
  • Practical Information: Provides actionable upgrade steps with specific examples and configuration details
  • Good Documentation Practices: Uses proper markdown formatting, includes complete chainspec examples, and references related documentation

📝 Areas for Improvement:

Code Quality & Best Practices

  • Documentation Organization: The guide effectively consolidates information that was previously scattered, addressing reviewer feedback about streamlining from changelog-style content
  • Technical Accuracy: All technical details appear correct based on the changelog and codebase structure
  • Maintainability: Good use of tables for configuration references and clear section organization

Security Concerns ⚠️

CRITICAL: Missing security guidance for sensitive configuration:

  • The SPONSOR_PRIVATE_KEY environment variable mentioned in the transaction sponsor service section lacks security warnings
  • Recommendation: Add prominent security notes about:
    • Never committing private keys to version control
    • Using secure secret management systems
    • Proper key rotation practices
    • Avoiding logging sensitive values

Documentation Quality

  • Reference Links: Good use of internal documentation links (lines 43, 47, 120-123)
  • Version Handling: Properly addresses the v0.3.0 beta situation (lines 5, 10)
  • Examples: Complete chainspec example is helpful for operators

Previous Reviewer Feedback Analysis

The PR has addressed most previous reviewer concerns:

  • tac0turtle's feedback: Successfully separated migration guide from changelog content
  • Version clarity: Added proper v0.3.0 beta context
  • Content focus: Streamlined to focus on actual migration steps rather than feature announcements
  • Approval received: Latest review shows approval from tac0turtle

Performance Considerations

  • Documentation-only changes have no runtime performance impact
  • Well-structured content should improve operator experience during upgrades

Test Coverage

  • As a documentation PR, traditional test coverage doesn't apply
  • However, the guide includes practical examples and references that can be validated by operators

Specific Recommendations

  1. Security Enhancement (High Priority):

    ### Transaction Sponsor Service
    
    + ⚠️ **Security Warning**: The `SPONSOR_PRIVATE_KEY` environment variable contains sensitive cryptographic material. Never commit private keys to version control, use secure secret management systems, and implement proper key rotation practices.
    
    **Configuration (environment variables):**
  2. Minor Documentation Improvements:

    • Consider adding a "Migration Checklist" section for operators to track their upgrade progress
    • The Storage V2 migration notes could benefit from estimated resync times or data size considerations
  3. Cross-Reference Validation:

    • Verify that all referenced documentation files exist and contain the expected content
    • Consider adding version numbers to the "Related Documentation" section for clarity

Final Assessment

This PR successfully creates a comprehensive upgrade guide that addresses real operational needs. The documentation is well-structured, technically accurate, and addresses previous reviewer feedback effectively. The only significant concern is the missing security guidance for sensitive configuration values.

Recommendation: Approve with the security enhancement implemented. The upgrade guide will significantly help operators navigate the v0.4.0 transition safely and efficiently.


Copy link
Copy Markdown

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🧹 Nitpick comments (1)
docs/UPGRADE-v0.4.0.md (1)

94-105: Add secret-handling guidance for SPONSOR_PRIVATE_KEY.

The configuration table exposes a high-risk secret variable but does not state operational handling requirements (no plaintext commits/logging, prefer secret manager). A short warning would reduce accidental key leakage risk.

🔐 Suggested addition
 ### Transaction Sponsor Service
@@
 **Configuration (environment variables):**
+
+> Security note: `SPONSOR_PRIVATE_KEY` is sensitive. Store it in a secret manager (or equivalent),
+> never commit it to git, and avoid printing it in logs.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/UPGRADE-v0.4.0.md` around lines 94 - 105, Add a short, prominent warning
under the configuration table about the SPONSOR_PRIVATE_KEY variable: state that
it is a high-risk secret, must never be committed to source control or printed
to logs, and recommend using a secrets manager (or env injection via CI/CD),
restricted IAM, and regular rotation; update the table row for
SPONSOR_PRIVATE_KEY (in the docs/UPGRADE-v0.4.0.md section) to reference this
guidance and ensure the note mentions avoiding plaintext storage and disabling
debug/stack traces that might leak it.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/UPGRADE-v0.4.0.md`:
- Line 3: Replace any references that imply a stable v0.3.0 release with the
beta tag and clarify wording: update the header sentence that currently says
"since v0.3.0" (and the occurrences around lines 139–144) to explicitly state
"since v0.3.0‑beta" or "since v0.3.0 (beta)", and rephrase any sentences that
suggest a stable v0.3.0 was shipped so they clearly indicate the prior release
was a beta (e.g., change "v0.3.0" -> "v0.3.0-beta" and add "beta release"
wording where necessary).

---

Nitpick comments:
In `@docs/UPGRADE-v0.4.0.md`:
- Around line 94-105: Add a short, prominent warning under the configuration
table about the SPONSOR_PRIVATE_KEY variable: state that it is a high-risk
secret, must never be committed to source control or printed to logs, and
recommend using a secrets manager (or env injection via CI/CD), restricted IAM,
and regular rotation; update the table row for SPONSOR_PRIVATE_KEY (in the
docs/UPGRADE-v0.4.0.md section) to reference this guidance and ensure the note
mentions avoiding plaintext storage and disabling debug/stack traces that might
leak it.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 57f475ef-e030-439d-9339-b19abaf6a319

📥 Commits

Reviewing files that changed from the base of the PR and between d0bc639 and 4c1ead3.

📒 Files selected for processing (1)
  • docs/UPGRADE-v0.4.0.md

Comment thread docs/UPGRADE-v0.4.0.md Outdated
Copy link
Copy Markdown
Contributor

@tac0turtle tac0turtle left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this seems more like a changelog and a migration guide, can you split the two. move things to changelog and then slim this down to only migration

Split changelog content from migration guide per review feedback.
Move new features and bug fixes to CHANGELOG.md, slim the upgrade
guide to config-only migration steps. Remove v0.3.0 upgrade guide
as v0.4.0 now covers upgrades from all previous versions.
Comment thread docs/UPGRADE-v0.4.0.md

See [EIP-1559 Configuration](eip1559-configuration.md) for tuning recommendations.

## Upgrading from v0.1.x
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

can we point people to other upgrade guides to avoid mentioning everything every time

Comment thread docs/UPGRADE-v0.4.0.md Outdated

This guide covers the configuration changes required to upgrade ev-reth to v0.4.0. For a full list of changes, see the [CHANGELOG](../CHANGELOG.md).

## Upgrading from v0.3.0
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

v0.3.0 was never released lets treat it as such and just do upgrade from 0.2.x to 0.4.x

@tac0turtle tac0turtle enabled auto-merge (squash) April 17, 2026 13:36
@tac0turtle tac0turtle merged commit 2cd9dc2 into main Apr 17, 2026
17 checks passed
@tac0turtle tac0turtle deleted the jgimeno/retract-v03x-upgrade-doc branch April 17, 2026 13:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants