eth-docs/plugeth-statediff-upgrade-guide.md

Upgrading plugeth-statediff for Ethereum fork

This guide covers the process of updating plugeth-statediff for a new Ethereum fork (e.g., Deneb/Cancun, Pectra, etc.).

See project-dependencies.md for the full dependency graph of all related projects.

Overview

plugeth-statediff is the core state-diffing plugin that extracts Ethereum state changes. It depends on:

• plugeth: The plugin framework (Geth fork)
• plugeth-utils: Shared utilities for plugins

Integration tests additionally depend on:

• stack-orchestrator: For deployment
• fixturenet-eth-stacks: Stack definitions for local test networks
• system-tests: For end-to-end testing
• eth-statediff-compliance: For verification and benchmarking

Update sequence

Phase 1: Update utility tools to target new geth version

These tools depend on geth directly and should be updated first. They can be done in parallel:

1. eth-testing - Update to new geth version
2. eth-iterator-utils - Update to new geth version
3. eth-dump-genblock - Update to new geth version
4. eth-statediff-compliance - Update to new geth version

These updates ensure testing and validation infrastructure is ready before updating the core plugin.

Phase 2: Update core plugin stack

These should be done sequentially in this order:

1. Update plugeth-utils

Start here as it's the base dependency for both plugeth and plugeth-statediff.

• Update to track new geth version
• Test and release first

2. Update plugeth

• Update plugeth-utils reference in go.mod
• Also update plugeth-utils in wrapmain/go.mod
• Rebase or update to target new geth version
• Test and release

3. Update plugeth-statediff

Main plugin update:

Dependencies to update:

• Update plugeth reference
• Update plugeth-utils reference

Code changes:

• Adapt to any geth core/state API changes
• Update state diffing logic if needed

Testing requirements:

• Unit tests must pass
• Integration tests (require stack-orchestrator and system-tests)
• Compliance tests (using eth-statediff-compliance)

Phase 3: Integration testing

Before releasing plugeth-statediff, ensure integration tests pass:

1. Update stack-orchestrator with any needed config changes
2. Update fixturenet-eth-stacks if stack definitions need changes for the new fork
3. Deploy local test network using fixturenet-eth-stacks
4. Update system-tests if needed
5. Run full integration test suite against the fixturenet
6. Run eth-statediff-compliance benchmarks

Known issues and workarounds

Go plugin module name workaround

When updating plugeth, be aware of the Go plugin module naming issue:

• Issue: cerc-io/plugeth-statediff#6
• Fix: d730849b7e

The module name must match exactly between plugin and host for Go's plugin system to work correctly.

Release order

Recommended release order to minimize breaking changes:

1. plugeth-utils - Base dependency, release first
2. plugeth - After plugeth-utils is released and tested
3. eth-testing and other utility tools - Can be released in parallel
4. plugeth-statediff - After plugeth and plugeth-utils are stable
5. Downstream services - After plugeth-statediff is released (see project-dependencies.md for full list)

Post-release updates

After releasing plugeth-statediff, the following projects will need updates:

Immediate dependents:

• eth-statediff-service
• ipld-eth-db-validator

IPLD/StateDB layer:

• ipld-eth-statedb (can use git patch/apply from geth core/state/*)
• ipfs-ethdb

See project-dependencies.md for the complete update sequence for all downstream services. For a concrete example, see the Notion milestone and tasks for the Deneb/Cancun upgrade.

Checklist

Before considering the upgrade complete:

• plugeth-utils updated and released
• plugeth updated (including wrapmain/go.mod) and released
• plugeth-statediff updated with new dependency versions
• Unit tests pass
• fixturenet-plugeth stack successfully builds and deploys with updated versions
• Integration tests pass (using fixturenet-plugeth stack via stack-orchestrator)
• Compliance tests pass (eth-statediff-compliance)
• System tests pass
• Performance benchmarks reviewed
• Release notes prepared
• Downstream services identified for follow-up updates
• Update these docs if needed