Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
83 changes: 83 additions & 0 deletions docs/glamsterdam-client-compatibility.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,83 @@
# Glamsterdam client compatibility

The geth v1.17.10 update corrects the JSON name of the block access list hash
from `balHash` to `blockAccessListHash`. Without that field, decoding a
Glamsterdam header and calling `Header.Hash()` computes a different hash from
the canonical block hash reported by Ethereum.

`baseChain.GetBlockHashByNumber` returns that decoded header's hash. Wallet
coordination uses it in `SHA256(wallet public-key hash || safe-block hash)`,
where the safe block is 32 blocks before the coordination block. The seed
controls the operator shuffle that selects the leader and the heartbeat
choice. A fleet using one old hash rule can agree internally while using an
incorrect canonical hash; mixing the old and corrected rules can produce
different leaders and action checklists for the same wallet and window.

## Release coordination

This dependency update changes a shared coordination rule for post-fork
headers. It must be included in a coordinated client release:

- Every operator must run the corrected client before mainnet activation of
the header fields that change the coordination hash.
- Sepolia already carries these fields. An ungated rolling release there
mixes the old and corrected hash rules immediately. Its release plan needs
a coordinated fleet transition or a compatible activation gate, with a
rehearsal that verifies the same seed, leader, and heartbeat choice across
the fleet.
- Before release, the coordinated corrected fleet must also complete an
actual heartbeat and deposit-sweep signing and live execution rehearsal.
Agreement on the computed leader alone does not satisfy this gate. This
patch does not claim that this release rehearsal has been completed.
- Before release, compare the corrected client's computed hashes with the
canonical hashes returned by the actual RPC providers operators use,
across shared post-fork block numbers. Include more than the saved fixture
and confirm that every provider serves `blockAccessListHash` and
`slotNumber` consistently.
- A successful client build, a passing unit test, or unchanged contract
interfaces does not establish mixed-version coordination compatibility.

This patch chooses no cutover block and performs no deployment. It does not
add an application activation gate; release owners must resolve the
transition before deploying it on an already forked network. The header
hash correction itself requires no smart-contract upgrade.

## Transactions across activation

Generated contract `ForceMining` replacement callbacks still preserve an
original nonzero `GasLimit`. Raising the replacement fee therefore does not
refresh that gas limit after repricing. The geth update does not fix this
behavior.

As an interim release gate, release owners must rehearse and document a
bounded, coordinated drain of pending calls and calls estimated before the
fork:

1. Choose a bounded submission pause and resumption plan for affected
Ethereum calls. Inventory outstanding transactions by sender and nonce,
and drain or reconcile them across the activation boundary.
2. Do not use pre-fork gas estimates for post-fork inclusion. Estimate new
submissions against the active post-fork rules and current business state.
3. Before retrying unresolved work, check its receipt, the account's confirmed
and pending nonces, and current contract/business state. Distinguish mined,
still-pending, replaced, and dropped transactions; a missing receipt alone
does not establish that the original call is safe to repeat.
4. Only after that reconciliation, obtain a fresh estimate and choose a
nonce-appropriate retry for work that is still needed. Do not blindly
rebroadcast work that may remain pending or may already have succeeded.
Resume affected submissions under the bounded plan once these checks and
post-fork estimation are in place.

This runbook is a release prerequisite, not an implemented transaction-drain
mechanism. This patch performs no live action and chooses no fork date or
activation block.

## Regression coverage

`TestGetBlockHashByNumber_Glamsterdam` serves a real public Sepolia header
through an in-process JSON-RPC server and calls the production method. It
compares the result with the canonical hash saved in the original response.
The test fails with geth v1.17.3 and passes with the corrected decoder.

The fixture and its provenance are in
`pkg/chain/ethereum/testdata/sepolia-glamsterdam-header-12084523.*`.
44 changes: 23 additions & 21 deletions go.mod
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ require (
github.com/btcsuite/btcd/btcutil v1.1.5
github.com/btcsuite/btcd/chaincfg/chainhash v1.1.0
github.com/checksum0/go-electrum v0.0.0-20220912200153-b862ac442cf9
github.com/ethereum/go-ethereum v1.17.3
github.com/ethereum/go-ethereum v1.17.10
github.com/ferranbt/fastssz v0.1.4
github.com/go-test/deep v1.0.8
github.com/google/gofuzz v1.2.0
Expand All @@ -70,11 +70,11 @@ require (
github.com/spf13/pflag v1.0.6
github.com/spf13/viper v1.12.0
go.uber.org/zap v1.27.0
golang.org/x/crypto v0.47.0
golang.org/x/crypto v0.55.0
golang.org/x/exp v0.0.0-20250106191152-7588d65b2ba8
golang.org/x/sync v0.19.0
golang.org/x/term v0.39.0
google.golang.org/protobuf v1.36.11
golang.org/x/sync v0.22.0
golang.org/x/term v0.45.0
google.golang.org/protobuf v1.36.12
google.golang.org/protobuf/dev v0.0.0-00010101000000-000000000000
)

Expand All @@ -86,15 +86,16 @@ require (
github.com/davecgh/go-spew v1.1.1 // indirect
github.com/decred/dcrd/crypto/blake256 v1.0.1 // indirect
github.com/emicklei/dot v1.6.2 // indirect
github.com/ethereum/c-kzg-4844/v2 v2.1.6 // indirect
github.com/ethereum/c-kzg-4844/v2 v2.1.8 // indirect
github.com/fjl/jsonw v0.1.0 // indirect
github.com/gballet/go-libpcsclite v0.0.0-20191108122812-4678299bea08 // indirect
github.com/go-task/slim-sprig/v3 v3.0.0 // indirect
github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
github.com/pion/datachannel v1.5.10 // indirect
github.com/pion/dtls/v2 v2.2.12 // indirect
github.com/pion/ice/v2 v2.3.37 // indirect
github.com/pion/interceptor v0.1.37 // indirect
github.com/pion/logging v0.2.2 // indirect
github.com/pion/logging v0.2.4 // indirect
github.com/pion/mdns v0.0.12 // indirect
github.com/pion/randutil v0.1.0 // indirect
github.com/pion/rtcp v1.2.15 // indirect
Expand All @@ -108,10 +109,11 @@ require (
github.com/pion/turn/v2 v2.1.6 // indirect
github.com/pion/webrtc/v3 v3.3.5 // indirect
github.com/pmezard/go-difflib v1.0.0 // indirect
github.com/stretchr/objx v0.5.2 // indirect
github.com/stretchr/testify v1.11.1 // indirect
github.com/stretchr/objx v0.5.3 // indirect
github.com/stretchr/testify v1.12.1 // indirect
github.com/wlynxg/anet v0.0.5 // indirect
golang.org/x/telemetry v0.0.0-20251203150158-8fff8a5912fc // indirect
go.yaml.in/yaml/v3 v3.0.5 // indirect
golang.org/x/telemetry v0.0.0-20260811182544-a038080d80e5 // indirect
)

require (
Expand All @@ -137,7 +139,7 @@ require (
github.com/flynn/noise v1.1.0 // indirect
github.com/francoispqt/gojay v1.2.13 // indirect
github.com/fsnotify/fsnotify v1.6.0 // indirect
github.com/go-logr/logr v1.4.3 // indirect
github.com/go-logr/logr v1.4.4 // indirect
github.com/go-logr/stdr v1.2.2 // indirect
github.com/go-ole/go-ole v1.3.0 // indirect
github.com/godbus/dbus/v5 v5.1.0 // indirect
Expand All @@ -162,7 +164,7 @@ require (
github.com/jbenet/go-temp-err-catcher v0.1.0 // indirect
github.com/kkdai/bstream v0.0.0-20161212061736-f391b8402d23 // indirect
github.com/klauspost/compress v1.17.11 // indirect
github.com/klauspost/cpuid/v2 v2.2.9 // indirect
github.com/klauspost/cpuid/v2 v2.3.0 // indirect
github.com/koron/go-ssdp v0.0.4 // indirect
github.com/libp2p/go-buffer-pool v0.1.0 // indirect
github.com/libp2p/go-cidranger v1.1.0 // indirect
Expand Down Expand Up @@ -229,19 +231,19 @@ require (
github.com/whyrusleeping/go-keyspace v0.0.0-20160322163242-5b898ac5add1 // indirect
go.opencensus.io v0.24.0 // indirect
go.opentelemetry.io/auto/sdk v1.2.1 // indirect
go.opentelemetry.io/otel v1.41.0 // indirect
go.opentelemetry.io/otel/metric v1.41.0 // indirect
go.opentelemetry.io/otel/trace v1.41.0 // indirect
go.opentelemetry.io/otel v1.46.0 // indirect
go.opentelemetry.io/otel/metric v1.46.0 // indirect
go.opentelemetry.io/otel/trace v1.46.0 // indirect
go.uber.org/dig v1.18.0 // indirect
go.uber.org/fx v1.23.0 // indirect
go.uber.org/mock v0.5.0 // indirect
go.uber.org/multierr v1.11.0 // indirect
golang.org/x/mod v0.31.0 // indirect
golang.org/x/net v0.49.0 // indirect
golang.org/x/sys v0.40.0 // indirect
golang.org/x/text v0.33.0 // indirect
golang.org/x/time v0.9.0
golang.org/x/tools v0.40.0
golang.org/x/mod v0.39.0 // indirect
golang.org/x/net v0.58.0 // indirect
golang.org/x/sys v0.47.0 // indirect
golang.org/x/text v0.41.0 // indirect
golang.org/x/time v0.14.0
golang.org/x/tools v0.49.0
gonum.org/v1/gonum v0.15.1 // indirect
gopkg.in/ini.v1 v1.67.0 // indirect
gopkg.in/yaml.v2 v2.4.0 // indirect
Expand Down
Loading
Loading