How to Merge Upstream go-ethereum

[tynes]

Updating op-geth with Upstream geth Changes

Pulling upstream geth changes into op-geth is a multistep process - first updating op-geth and then pulling that into the monorepo. The complication is that most of the tests are in the monorepo and we want to see them passing before actually merging the update into op-geth optimism branch.

Prep op-geth PR

Create a new branch from the latest optimism branch in op-geth same as usual for a PR.

Merge in the changes from the new upstream release, e.g:

git remote add upstream "https://github.com/ethereum/go-ethereum.git"
git fetch upstream
git merge "v1.11.5" # Adjust for whatever the latest geth release tag is

Resolve any merge conflicts and create a draft PR.

Update fork.yaml

In the op-geth repo, update the base → hash value in fork.yaml so that https://op-geth.optimism.io/ only shows differences from the new upstream commit. The new hash is the commit hash of the upstream tag that was just merged in.

Include this change as part of the PR to merge changes into op-geth.

Prep Monorepo PR

Create a new branch in the optimism monorepo off the develop branch same as usual for a PR.

Update the version of op-geth used. While you can do this by changing the replace line in ./go.mod to point to your local checkout of op-geth we want to take advantage of CI to run some tests so we’ll temporarily update it to point to the branch we created the PR from in op-geth.

With go mod edit

go mod edit \
  -replace github.com/ethereum/go-ethereum@v1.11.4=github.com/ethereum-optimism/op-geth@<COMMIT>
go mod tidy

Replace <COMMIT> with the commit hash of the latest commit from your op-geth branch. Run this again in the indexer directory to also update op-geth in the indexer module. You can use the branch name instead of the commit hash but only if the branch name doesn’t contain any special characters (like /).

Commit this and create a draft PR. Then review the CI results and fix any issues.

Manually Modifying go.mod

I find it easier to just manually modify go.mod. Find the existing entry for github.com/ethereum/go-ethereum and update the current version with the new version of upstream geth. So upgrading from go-ethereum 1.13.4 to 1.13.5:

- github.com/ethereum/go-ethereum v1.13.4
+ github.com/ethereum/go-ethereum v1.13.5

Then update the replace directive for geth at the bottom of the file:

- replace github.com/ethereum/go-ethereum v1.13.4 => github.com/ethereum-optimism/op-geth v1.101304.2-0.20231114215743-0289fd0504a0
+ replace github.com/ethereum/go-ethereum v1.13.5 => github.com/ethereum-optimism/op-geth <COMMIT>

Replace <COMMIT> with the commit hash of the latest commit from your op-geth branch. Run this again in the indexer directory to also update op-geth in the indexer module. You can use the branch name instead of the commit hash but only if the branch name doesn’t contain any special characters (like /).

Then run go mod tidy

Commit this and create a draft PR. Then review the CI results and fix any issues.

Identify relevant changes to command line flags

If there are any changes to how op-geth must be invoked in our infrastructure, document these in the PR and make devinfra aware of the necessary changes. Be sure that the flag changes are tested in running infrastructure.

Merge op-geth PR

Get the op-geth PR reviewed and merge into the optimism branch.

Update Monorepo PR

Now that the changes are actually merged into op-geth properly, update the go.mod in the monorepo again to point to the latest commit on the optimism branch of op-geth. The best way to do this is to first create a tag in op-geth and then update the monorepo to use that tag:

git tag v1.101308.0-rc.1
git push origin v1.101308.0-rc.1
# head over to Circle CI to approve the docker build

and

go mod edit -replace github.com/ethereum/go-ethereum@v1.13.8=github.com/ethereum-optimism/op-geth@v1.101308.0-rc.1

Then run go mod tidy.

Push that change up (consider amending the previous commit pointing to the branch as we don’t need that in the final history).

Merge Monorepo PR

Finally, get the monorepo reviewed and merge it in. Geth is now updated. 🎉