Skip to content

Add an update-geth skill for go-ethereum version bumps #24278

Open

Description

@sebastianst

After the cutover (#20266, #24176) go.mod requires upstream go-ethereum directly, and Dependabot no longer proposes its version bumps. Every bump is then a deliberate change that someone has to drive. This issue proposes an update-geth skill for it, like update-reth for the Rust side.

Why a skill

A go-ethereum bump that compiles can still change behaviour. The cutover found several such changes, and none of them was a compile error:

  • The rpc client started to treat "error": null in a successful response as an error (rpc: client treats a response with "error": null as an error since v1.17.4 ethereum/go-ethereum#36150).
  • golang/snappy, a transitive dependency, started to reject a length preamble that kona's snap crate still accepted, which is a gossip difference between op-node and kona-node.
  • params.ChainConfig and BlobScheduleConfig lost keys, so a config file that op-node accepted before fails its strict decode.
  • The blob pool stopped accepting sidecars without cell proofs, and block building for Prague started to require the EIP-7002 and EIP-7251 contracts in genesis.

Consensus: fork configs and blob schedules

The one check that every bump needs. Derivation computes the L1 blob base fee and writes it into the L1 attributes deposit (l1_block_info.go). The value comes from go-ethereum: eip4844.CalcBlobFee with an L1 chain config that, for mainnet, Sepolia and Hoodi, is go-ethereum's built-in one. A bump therefore changes consensus when it changes any of:

  • a fork time or a blob-schedule entry in params.MainnetChainConfig, SepoliaChainConfig or HoodiChainConfig, e.g. a newly scheduled L1 fork or BPO;
  • the default blob configs (params.DefaultBlobSchedule and the per-fork BlobConfig values);
  • how eip4844.CalcBlobFee picks the blob config for a header, or its fee formula.

The skill diffs these between the old and the new version and stops on any difference. Each one is then compared with kona, which takes the same values from alloy (variant.rs): op-node and kona-node must use the same schedule for every L1 timestamp, and an op-node release that learns of an L1 fork has to ship before that fork activates.

The cutover ran this check with the program below, run once per version and diffed. Between op-geth v1.101702.4-rc.2 and go-ethereum v1.17.10 the fees are equal at every fork boundary of the three networks; upstream adds Sepolia's Amsterdam time, which keeps the BPO2 blob parameters.

Dump program
// Prints everything derivation takes from go-ethereum for the L1 blob base fee, so that
// the output can be diffed between two go-ethereum versions.
package main

import (
	"encoding/json"
	"fmt"
	"math"
	"math/big"
	"reflect"
	"sort"
	"strings"

	"github.com/ethereum/go-ethereum/consensus/misc/eip4844"
	"github.com/ethereum/go-ethereum/core/types"
	"github.com/ethereum/go-ethereum/params"
)

func main() {
	cfgs := []struct {
		name string
		cfg  *params.ChainConfig
	}{
		{"mainnet", params.MainnetChainConfig},
		{"sepolia", params.SepoliaChainConfig},
		{"hoodi", params.HoodiChainConfig},
	}
	excess := []uint64{0, 1, 393216, 786432, 3_000_000, 10_000_000, 50_000_000, 120_000_000, 300_000_000, 1_000_000_000}
	for _, c := range cfgs {
		fmt.Printf("== %s\n", c.name)
		// Fork times, by field name, through reflection so that fields of only one version show up.
		v := reflect.ValueOf(*c.cfg)
		times := map[uint64]bool{}
		var lines []string
		for i := 0; i < v.NumField(); i++ {
			name := v.Type().Field(i).Name
			if !strings.HasSuffix(name, "Time") {
				continue
			}
			f := v.Field(i)
			if f.Kind() != reflect.Ptr || f.IsNil() {
				lines = append(lines, fmt.Sprintf("time %s nil", name))
				continue
			}
			t := f.Elem().Uint()
			lines = append(lines, fmt.Sprintf("time %s %d", name, t))
			times[t] = true
		}
		sort.Strings(lines)
		fmt.Println(strings.Join(lines, "\n"))
		bs, _ := json.Marshal(c.cfg.BlobScheduleConfig)
		fmt.Printf("blobSchedule %s\n", bs)

		var ts []uint64
		for t := range times {
			ts = append(ts, t)
			if t > 0 {
				ts = append(ts, t-1)
			}
		}
		ts = append(ts, 1_800_000_000, 2_000_000_000, math.MaxUint64/2)
		sort.Slice(ts, func(i, j int) bool { return ts[i] < ts[j] })
		for _, t := range ts {
			if c.cfg.CancunTime == nil || t < *c.cfg.CancunTime {
				continue
			}
			var fees []string
			for _, e := range excess {
				e := e
				h := &types.Header{Number: big.NewInt(100_000_000), Time: t, ExcessBlobGas: &e}
				fees = append(fees, eip4844.CalcBlobFee(c.cfg, h).String())
			}
			fmt.Printf("fee t=%d %s\n", t, strings.Join(fees, ","))
		}
	}
	ds, _ := json.Marshal(params.DefaultBlobSchedule)
	fmt.Printf("== default\nblobSchedule %s\n", ds)
}

What the skill covers

  • Choose the target release and read its release notes and the upstream diff of the packages the monorepo imports.
  • Bump go.mod, tidy, and fix the API changes.
  • Review the changes in behaviour. The "go-ethereum version bumps" section that go.mod!: build against upstream go-ethereum v1.17.10 #24176 adds to docs/ai/opgeth-decoupling.md is the start of the checklist: gas accounting, intrinsic and floor gas, the blob schedule, new L1 forks. To add:
    • rpc client and server behaviour;
    • added or removed ChainConfig and blob-schedule keys in the JSON form, for both the L1 config file that op-node reads and the L2 chain-config codec in op-core/params;
    • Engine API versions and header fields of a new L1 fork;
    • transitive dependencies that change with the bump and touch a wire format (snappy, KZG, libp2p), with the matching Rust crate bumped in the same PR.
  • The golden vectors in op-core must not change.
  • Write a BREAKING CHANGE entry for every change an operator or a Go importer can observe.
  • Check the downstream Go modules that import the monorepo.

To decide

  • Does the bump also get a reviewer agent and a risk guide, like reth-update-reviewer and docs/ai/reth-update-review.md? The Go side has far less code that shadows upstream than the op-reth forks, so one skill with a checklist may be enough.
  • Which checklist items can become tests? A test that fails when go-ethereum's ChainConfig gains a fork field that the op-core/params decoder does not check is better than a step in a skill.

The first use is the bump to the release that contains ethereum/go-ethereum#36151.

🤖 Co-created with Claude Fable 5.2

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions