Skip to content

rust: tag upstream mirrors and extend reth bump-review guidance - #22477

Merged
sebastianst merged 7 commits into
developfrom
seb/upstream-mirror-tags
Sep 18, 2026
Merged

sebastianst merged 7 commits into
developfrom
seb/upstream-mirror-tags

Conversation

@sebastianst

@sebastianst sebastianst commented Aug 18, 2026 •

Copy link
Copy Markdown
Member

Several op-crates carry code that mirrors upstream reth, revm or alloy — ports, verbatim
copies, overridden defaults, re-declared surfaces and forwarding wrappers. Nothing marked
them, so an upstream change that should force a matching edit here produces no diff and no
compile error, and the divergence is only found by someone reading both sides. Two recent
bugs came in exactly this way.

Tags. Each site gets UPSTREAM-MIRROR(<kind>): <crate>@<version> `<symbol>` , recording the
version the mirror was last verified against. Kinds are port, copy, override, set and
delegate. Inventory after this change: 56 mirrors, 50 current, 6 frozen.

Tooling. rust/scripts/upstream-mirrors.py (just mirrors, just mirrors stale) lists every
tag and flags any whose recorded version has fallen behind the pin. just check-upstream-mirrors
runs the checker's contract tests and fails closed on malformed tags, unknown crates, ambiguous
resolved versions, versions ahead of the pin and split reth pins; it runs in the required
rust-fmt job and in just lint. Staleness is reported, never gated (see the guide for why).

Guides. docs/ai/reth-upstream-mirrors.md covers the grammar, the kinds, and which repo to
diff a reth mirror against. docs/ai/reth-update-review.md, rust/UPDATING-RETH.md, the
update-reth skill and the reth-update-reviewer agent gain matching bump-review guidance:
the stale-mirror worklist, inspecting every tag change relative to the merge base (an advanced
tag is evidence to review, not proof of re-verification), triaging a fork's cherry-picks on each
bump, the upstream preconditions OP breaks (deposits skip validate_env, …), and upstream
derive macros that expand to consensus-facing decoders with no body in our tree.

The FPVM EthPrecompiles::run caller is included even though it delegates output conversion:
the remaining copied input/error/gas path still needs upstream review. The guide also clarifies
that a backport merged on upstream main must survive until the selected release actually
contains it.

No behaviour changes — comments, docs, one script and one CI command-line.

Verification: all 32 checker tests pass. The checker discovers the FPVM caller as current;
a simulated dependency bump makes it stale and includes it in the stale-only worklist.

Includes the fixes from #22641 (checker fail-closed + tests + CI wiring, corrected inventory).

Follow-up

The tags describe the duplication; they do not reduce it. #22478 tracks the reduction work:
delegating where a seam already exists, deleting outright duplicates, and asking upstream for
abstractions where none exists today.

🤖 Co-created with Claude Opus 5, GPT-5.6, Claude Fable 5.1, and GPT-6

https://claude.ai/code/session_01Ss5Vsih1Jhvd4eWB9UJoi8

@sebastianst sebastianst left a comment

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

🤖 GPT-5.6 says: Review verdict: changes needed.

The original diff had three blocking classes of issues:

  • the checker failed open on malformed or ambiguous metadata and was not executed by required Rust CI;
  • the stale/tag-advance and fork-cherry-pick workflows could declare an unverified bump reviewed;
  • multiple mirror tags were missing, attached to the wrong owner, or prescribed the wrong re-verification.

The complete fixes, checker regression tests, CI wiring, and corrected inventory are in #22641, stacked on this PR. Please land that fix into this branch before merging #22477.

@opgitgovernance

Copy link
Copy Markdown
Contributor

This pr has been automatically marked as stale and will be closed in 5 days if no updates

@opgitgovernance opgitgovernance added the S-stale Status: Will be closed unless there is activity label Sep 5, 2026
@sebastianst sebastianst reopened this Sep 10, 2026
@sebastianst sebastianst removed the S-stale Status: Will be closed unless there is activity label Sep 10, 2026
@wiz-0f98cca50a

wiz-0f98cca50a Bot commented Sep 10, 2026 •

Copy link
Copy Markdown

Wiz Scan Summary

Scanner Findings
Vulnerability Finding Vulnerabilities -
Data Finding Sensitive Data -
Secret Finding Secrets -
IaC Misconfiguration IaC Misconfigurations -
SAST Finding SAST Findings 1 Low
Software Management Finding Software Management Findings -
Total 1 Low

View scan details in Wiz

To detect these findings earlier in the dev lifecycle, try the Wiz Code extension for VS Code, JetBrains, or Visual Studio.

@joshklop joshklop left a comment

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.

Requesting changes for three gaps in the mirror inventory/update workflow. Details are inline.

Comment thread rust/kona/bin/client/src/fpvm_evm/tx.rs Resolved
Comment thread rust/op-reth/crates/payload/src/lib.rs Resolved
Comment thread rust/UPDATING-RETH.md Resolved
@sebastianst

Copy link
Copy Markdown
Member Author

🤖 Claude Fable 5.1 says: Addressed all three inline comments in 8808ccf (see the thread replies). Inventory is now 56 mirrors: 50 current, 6 frozen; checker tests and --check pass. #22495 has the commit merged in with both new tags advanced to its pins (revm-context-interface 42.0.0 is byte-identical to 41.0.0 for the Transaction trait, and into_execution_data is unchanged between aef8d3e and 0fbe428).

@sebastianst
sebastianst removed this pull request from stack #22889 September 18, 2026 08:51
@sebastianst
sebastianst force-pushed the seb/upstream-mirror-tags branch from 8808ccf to 2c69a15 Compare September 18, 2026 08:57
sebastianst and others added 7 commits September 18, 2026 12:50
Several op-crates carry code that mirrors upstream reth, revm or alloy —
ports, verbatim copies, overridden defaults, and re-declared surfaces. Nothing
marked them, so an upstream change that should force a matching edit here
produces no diff and no compile error, and the divergence is only found by
someone reading both sides.

Tag each site with `UPSTREAM-MIRROR(<kind>): <crate>@<version> <symbol>`,
recording the version the mirror was last verified against, and add
`rust/scripts/upstream-mirrors.py` (`just mirrors`) to list them and flag any
whose recorded version has fallen behind the pin. `--check` fails on a
malformed tag. The guide in `docs/ai/reth-upstream-mirrors.md` covers the
grammar, the kinds, and which repo to diff a `reth` mirror against.

Also extends the bump-review guidance in `docs/ai/reth-update-review.md` and
`rust/UPDATING-RETH.md`, including triaging the fork's cherry-picks on each
bump: drop the ones that landed upstream, replay the ones that did not.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
`clippy::doc_markdown` rejects the unbackticked item path in each tag, so the
tags as written fail the lint. Backtick the symbol in all 24 tags, and teach
the parser to accept it — the tag grammar and `upstream-mirrors.py` have to
change together, or every tag reads as malformed and `--check` fails instead.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Derived impls from alloy-consensus, alloy-rlp and reth-codecs-derive expand
to consensus-facing decoders with no body in our tree, so a changed
expansion produces no diff. Name the class in the silent-override taxonomy
and point at the canonical-decoding test that pins the accepted input set.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ss5Vsih1Jhvd4eWB9UJoi8
Only doc-comment lines can carry a tag; a plain comment, string literal or
`#[doc]` attribute naming the token was reported as malformed and failed
required CI. A tag-shaped line inside a fenced doc example no longer becomes
a phantom mirror. `port` tags keep the ordered version check, so a version
ahead of the pin is still an error; only staleness is reported as frozen.
`--check` fails when it finds no tags at all. Malformed notes name the two
common causes (prose reflowed onto the tag line, a `reth-*` member crate
named for the git-pinned family), and `just mirrors stale --json` works.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ss5Vsih1Jhvd4eWB9UJoi8
Delegating output conversion does not remove the provider dispatch copy. Keep that boundary on the handler bump worklist and clarify that maintenance backports remain necessary until the selected release contains them.
Tag `alloy_op_evm::OpTx`'s `Transaction` impl as a delegate of
`revm_context_interface::Transaction`: it forwards the required getters to
`OpTransaction<TxEnv>` and inherits every defaulted method, so the inner
type's deposit override of `effective_gas_price` did not apply to `OpTx`.
Forward that method too, in both this impl and its FPVM copy. This is
behaviour-identical for the deposit envs built here (no priority fee, so
both paths return the gas price) and closes the seam for any other caller.

Tag `From<OpBuiltPayload<N>> for OpExecData` as the copy of
`EthBuiltPayload::into_execution_data`, the second execution-data path
next to `block_to_payload`, so upstream changes to sidecar propagation
reach the worklist.

Use `perl -pi -e` for the pin edits in UPDATING-RETH so they work with BSD
sed as well.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ss5Vsih1Jhvd4eWB9UJoi8
@sebastianst
sebastianst force-pushed the seb/upstream-mirror-tags branch from 2c69a15 to bea4449 Compare September 18, 2026 10:51
@sebastianst
sebastianst added this pull request to the merge queue Sep 18, 2026
Merged via the queue into develop with commit 1e5b69c Sep 18, 2026
131 checks passed
@sebastianst
sebastianst deleted the seb/upstream-mirror-tags branch September 18, 2026 11:58
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.

3 participants