chore: prep for Amsterdam fork

[tac0turtle]

Overview

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: c6d21ad7-457d-4275-a839-1e6f642dbd8e

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch marko/reth_2.3

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[claude]

Claude finished @tac0turtle's task in 3m 32s —— View job

---

Code Review

• Gather context (AGENTS.md, changed files)
• Review execution/evm/engine_payload.go (new file)
• Review execution/evm/engine_rpc_client.go (major changes)
• Review execution/evm/execution.go
• Review execution/evm/engine_rpc_tracing.go
• Review test files
• Review documentation changes
• Post final review

---

Summary

This PR adds Amsterdam fork support to ev-node's EVM execution layer: new Engine API methods (forkchoiceUpdatedV4, getPayloadV6, newPayloadV5), a custom EnginePayloadEnvelope to preserve the blockAccessList field that go-ethereum's typed struct doesn't expose, and automatic version negotiation with fallback. The design is solid and the test coverage with fake HTTP servers is excellent. A few issues are worth addressing before merge.

---

Issues

Bug: Missing json:"blobsBundle" tag in EnginePayloadEnvelope

execution/evm/engine_payload.go, lines 26–33 and 71–76

Both the UnmarshalJSON and MarshalJSON inner struct definitions are missing a JSON tag on BlobsBundle:

// Both structs have this:
BlobsBundle *engine.BlobsBundle   // <-- no json tag

• Marshal: Go will emit "BlobsBundle" (capital B). The Engine API spec and the test constant minimalPayloadEnvelopeJSON both use "blobsBundle" (lowercase). Any consumer of MarshalJSON (e.g. logs, tests that round-trip the envelope) will produce a broken JSON blob.
• Unmarshal: Works fine because Go's JSON decoder is case-insensitive on key matching.

Both structs need json:"blobsBundle". Fix this →

---

Code smell: decodeSecret/getAuthToken duplicated in test/test_helpers.go

execution/evm/test/test_helpers.go, lines 206–228

These functions are byte-for-byte copies of decodeSecret and getAuthToken in execution.go. They live in a separate package (package test with //go:build evm) so they can't reference the unexported originals, but consider exposing thin helpers or moving these to a shared internal package to avoid drift. Fix this →

---

ams_update.md should not be checked in at repo root

This file looks like a development scratchpad / design note. It should be removed before merge or moved into the docs/ tree as part of the official documentation. Leaving it at root will confuse developers encountering it later.

---

Notes / Minor Points

engine_rpc_client.go – V5 fallback order probes forward before backward

// When V5 is preferred:
return []enginePayloadVersion{enginePayloadVersionV5, enginePayloadVersionV6, enginePayloadVersionV4}

V6 is tried before V4 when V5 fails, which is an intentional "forward probe" for Amsterdam upgrades. Worth a short comment to distinguish this from a simple backwards-compatibility fallback—otherwise it looks like the ordering might be a mistake.

engine_rpc_client.go – V4 forkchoice implicitly sets payload version to V6

Lines 81–83:

if version == engineForkchoiceVersionV4 {
    e.payloadVersion.Store(uint32(enginePayloadVersionV6))
}

This coupling (V4 forkchoice → V6 payload) is correct per the Amsterdam spec but is easy to miss. A single inline comment linking it to the spec would help.

engine_rpc_client.go – doForkchoiceUpdate double return

if err != nil {
    return err
}
return nil  // equivalent to: return err

Nit: can be collapsed to return err.

engine_payload.go – executionPayloadJSON redundant nil receiver guards

Both executionPayloadParam (line 103) and executionPayloadJSON (line 113) nil-guard on e == nil. Since executionPayloadParam immediately delegates to executionPayloadJSON, one guard is sufficient.

engine_payload.go – rawExecutionPayloadHasField parses the full payload twice

hasAmsterdamFields calls rawExecutionPayloadHasField up to twice (once for slotNumber, once for blockAccessList), each of which does a full json.Unmarshal into a map[string]json.RawMessage. This is called in newPayloadMethod which runs on every NewPayload and in the tracing wrapper. Parsing the full execution payload twice per submit is wasteful for Amsterdam payloads; consider parsing once and checking both keys.

execution_payload_attrs_test.go – minimal coverage

TestBuildPayloadAttributes_AddsSlotNumberCandidate only asserts the value at height 12. A table-driven test covering 0, 1, and an arbitrary height would better document the deriveSlotNumber contract.

engine_rpc_tracing.go – method attribute recorded post-call

The GetForkchoiceUpdatedMethod / GetPayloadMethod reflection via optional interfaces is a clean pattern for reporting the resolved (possibly re-negotiated) version. No issues, just noting this is a good design.

---

Testing

The fakeEngineServer-based unit tests in engine_rpc_client_test.go are thorough:

• Prague/Osaka/Amsterdam static chains ✓
• Live fork-upgrade transition (V4→V5) ✓
• Non-fork error propagation ✓
• Amsterdam blockAccessList round-trip preservation ✓
• slotNumber stripping on V3, inclusion on V4 ✓

Missing: a test for the V5→V6 transition (mid-run Amsterdam upgrade) analogous to TestGetPayload_ForkUpgrade_SwitchesV4ToV5.

[github-actions]

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

Build	Format	Lint	Breaking	Updated (UTC)
✅ passed	⏩ skipped	✅ passed	✅ passed	Jun 11, 2026, 1:15 PM

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://evstack.github.io/docs-preview/pr-3352/
Built to branch main at 2026-06-11 13:17 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 60.71%. Comparing base (29e8542) to head (e7df142).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3352   +/-   ##
=======================================
  Coverage   60.70%   60.71%           
=======================================
  Files         127      127           
  Lines       13781    13781           
=======================================
+ Hits         8366     8367    +1     
+ Misses       4502     4501    -1     
  Partials      913      913           

Flag	Coverage Δ
combined	60.71% <ø> (+<0.01%)	⬆️

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

☔ View full report in Codecov by Harness.
📢 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.