Skip to content

Bump to nitro v3.12.2 - #33

Merged
sduchesneau merged 24 commits into
release/v3.x-fhfrom
bump/nitro-3.12.2
Nov 6, 2026
Merged

sduchesneau merged 24 commits into
release/v3.x-fhfrom
bump/nitro-3.12.2

Conversation

@dfuse-bot

Copy link
Copy Markdown

Merges upstream tag v3.12.2. Files outside our own changes are identical to v3.12.2, and the Firehose delta against upstream is the same 41 files as in v3.12.1-fh3.0.

  • go-ethereum submodule points at 1927c192f0, the head of Bump to the go-ethereum revision of nitro v3.12.2 go-ethereum#75 (go-ethereum revision 30456d24d3 pinned by nitro v3.12.2). The submodule was the only merge conflict.
  • ACTIVATIONS.md statuses refreshed. v3.12.2 adds no ArbOS version, precompile, transaction type or balance reason. One, Nova and Sepolia are all at ArbOS 61, with no upgrade scheduled.
  • Tag to push after merge: v3.12.2-fh3.0, on this PR's merge commit. That is the rule's result (newest tag v3.11.4-fh3.0-1 → upstream version replaced, -N dropped) and matches the planned tag. fh3.0 is unchanged because the block model does not change.

Merge order

  1. Bump to the go-ethereum revision of nitro v3.12.2 go-ethereum#75 first (no tag, this line pins go-ethereum by commit).
  2. Before merging this PR, move the go-ethereum submodule and the commit link in CHANGELOG.sf.md to Pull out Sequencer from ArbInterface and add TxForwarder mode OffchainLabs/nitro#75's merge commit, as done for v3.12.1. If Pull out Sequencer from ArbInterface and add TxForwarder mode OffchainLabs/nitro#75 lands as a fast-forward of release/arbitrum-3.x to 1927c192f0, nothing needs to change. Until Pull out Sequencer from ArbInterface and add TxForwarder mode OffchainLabs/nitro#75 is merged, this PR pins a commit that exists only on the go-ethereum bump branch.

CHANGELOG

## v3.12.2-fh3.0

* Bumped to [3.12.2](https://github.com/OffchainLabs/nitro/releases/tag/v3.12.2).
* Updated `go-ethereum` to [1927c192f0](https://github.com/streamingfast/go-ethereum/commit/1927c192f0fa59a6584fe65d9fe2b0675275b201), which brings the go-ethereum revision pinned by nitro v3.12.2 (freezer fixes only, no Firehose change).

This also renames the ## Unreleased heading above the v3.12.1 entries to ## v3.12.1-fh3.0. The v3.12.1-fh3.0 tag was pushed on the bump branch's "Release v3.12.1-fh3.0" commit (def4eda70), which never reached release/v3.x-fh. For the same reason, git describe on the release branch still reports v3.11.4-fh3.0-1.

Firehose review

Upstream range v3.12.1..v3.12.2 (13 non-merge commits): sequencer panic recovery for delayed messages, a transaction-feed demo client and feed round markers, changelog files, the bals freezer table marked optional in gethhook, and the go-ethereum pin. The go-ethereum range 5eee8f546e..30456d24d3 only touches core/rawdb.

  1. Serial, in-order tracing: checked, none found. Nothing in the range changes block execution. The new recover() in Sequencer.sequenceDelayedMessage only runs on a sequencer. A traced sequencer that panics mid-block would retry with the tracer still holding the open block, but Firehose readers do not sequence.
  2. Block emitted only after acceptance: checked, none found. No new post-execution check and no header field.
  3. Activations: no new ArbOS version (MaxArbosVersionSupported stays 61) and no fork-gated change. See ACTIVATIONS.md.
  4. Unmapped upstream fields: checked, none found. core/types is unchanged in go-ethereum and no Arbitrum type changed in nitro.
  5. Transactions without a real hash: checked, none found.

Test Execution Summary

Build Status

  • go-ethereum go build ./...: PASSED
  • nitro make build-node-deps then go build ./...: PASSED
  • nitro go vet ./arbos/... ./execution/... ./precompiles/... ./gethhook/... ./arbnode/...: PASSED
  • Docker: docker build --target nitro-node -f Dockerfile ., then docker build -f Dockerfile.sf --build-arg NITRO_BASE_IMAGE=<that image> .: PASSED. The image runs nitro --version and lists the --execution.vmtrace.* flags. It bundles fireeth v2.24.1.

Unit Tests

Package Status Notes
go-ethereum go test ./core/... ./eth/... PASSED 35 packages with tests, including eth/tracers and eth/tracers/internal/tracetest/firehose
nitro go test ./execution/gethexec/... ./gethhook/... ./arbos/... PASSED 15 packages, including the new sequencer panic recovery tests

Integration Tests

  • Status: NOT RUN. Nitro system_tests were not run, because Firehose code lives in go-ethereum and nitro's Firehose diff is build and release files only.

Battlefield Tests

  • Status: RUN, with reviewable value diffs that predate this bump. No transaction trace failure.
  • Setup: battlefield-ethereum 879ea9a, fireeth v2.24.1, plain geth built from Bump to the go-ethereum revision of nitro v3.12.2 go-ethereum#75 (no nitro binary).
    • GETH_BINARY=<geth> ./scripts/run_firehose_geth_dev.sh 3.0 prague, then pnpm test:fh3.0:geth-dev: 72 passing, 11 failing, 21 pending.
    • GETH_BINARY=<geth> ./scripts/run_firehose_geth_dev.sh 3.0 (cancun), then pnpm test:fh3.0:geth-dev: 71 passing, 9 failing, 24 pending (a subset of the same diffs).
    • Baseline: the same prague run with a geth built from d3459f8e99, the go-ethereum commit in v3.12.1-fh3.0. It gives the same 11 failures, and the diff output is byte-for-byte identical. This merge changes no Battlefield output.
  • Failures (all present before this bump):
    1. Calls, "Delegate to empty contract", and Deploys, the five create2 cases: root call gasConsumed, transaction gasUsed and the matching REASON_GAS_REFUND value are 2,500 higher than in the canonical geth-dev snapshot (plus the derived gasLimit of one nested call). The trace shape is identical. Value diff, root cause not investigated (2,500 is the difference between a cold and a warm account access).
    2. Logs, "Single", "All indexed", "All mixed", "Multi", and Storages, "Set long string & array": some keccakPreimages entries are missing compared with the canonical snapshot (hashed log arguments, and hash-of-hash entries that explain no changed slot). Expected: since v3.11.4-fh3.0, this fork keeps only preimages that explain a changed storage slot.
  • pnpm test:fh2.3:arbitrum-geth-dev, the Arbitrum target the runbook names, no longer runs. It expects Firehose block version 3, and this fork emits version 5 since v3.12.1-fh3.0. The previous bump PR reported 0 failures for test:fh3.0:geth-dev; that run's setup is unknown, so the gap is unexplained.
  • Fork coverage: the geth dev network is a plain Ethereum dev chain, not an Arbitrum one. ArbOS transaction types, Stylus, retryables and the ArbOS 60/61 paths (tip collection, transaction filtering) have no Battlefield coverage. test:fh3.0:nitro-dev has no snapshots.

Open questions

  1. Submodule pin. This PR pins the go-ethereum bump branch head (1927c192f0) because Pull out Sequencer from ArbInterface and add TxForwarder mode OffchainLabs/nitro#75 is not merged yet. Conservative choice: keep that pin and repoint it to Pull out Sequencer from ArbInterface and add TxForwarder mode OffchainLabs/nitro#75's merge commit before merging, as in the merge order above.
  2. Battlefield for Arbitrum. The fh2.3:arbitrum-geth-dev snapshots are obsolete since the switch to block version 5, and fh3.0:geth-dev has 11 standing diffs on this line (identical before and after this bump). Conservative choice: report them as pre-existing and change no snapshots. Someone should decide whether to record fh3.0/v5/arbitrum-geth-dev overrides.

joshuacolvin0 and others added 23 commits September 25, 2026 15:42
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
A panic inside SequenceDelayedMessage escaped StartSequencing and
killed the sequencing thread. The delayed turn now recovers the
panic, logs it with a backtrace, and throttles delayed sequencing
for one minute, leaving regular turns unaffected.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
The panic can only originate inside SequenceDelayedMessage, before the
named result is assigned, so it is already nil in the deferred function.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
backport 3.12: fix for head truncation below a diverged tail group
…ort-3.12

Recover from panics while sequencing delayed messages (backport OffchainLabs#1005)
Add cmd/transaction-feed-client, a single-file Go executable that connects
to the transaction feed WebSocket, decodes each JSON message, and prints a
summary line per transaction. It depends only on the standard library and
github.com/coder/websocket so the file can be copied into any Go module.

The client takes the feed address and an optional Bearer token as flags,
supports wss:// through the default TLS stack, disables the 32 KiB read
limit so large transactions are not rejected, and reconnects after a
disconnect.

Wire the binary into `make build` and add the changelog entry.

Closes NIT-5612
Feed consumers that wait for every transaction of a PGA round before
acting could only infer that a round had ended when the first message of
the next round arrived, which wasted the next round's bidding window.

Bump the feed to version 2. Every message now starts with an envelope of
version, kind, timestamp_ms, and pga_round. The transaction payload is
unchanged under kind "Transaction". The new kind "RoundEnd" carries
block_number and marks the end of a group of transactions whose order
was decided together. Consumers should ignore kinds they don't know, so
this change is forward-compatible.

A PGA round with one transaction produces:

    {"version":2,"kind":"Transaction","timestamp_ms":1759795200000,
     "pga_round":3,"transaction":{"block_number":1234,"tx_index":1,
     "raw_tx":"0x02f8...","tx_hash":"0xab...","receipt":{...}}}
    {"version":2,"kind":"RoundEnd","timestamp_ms":1759795200012,
     "pga_round":3,"block_number":1234}

Under FIFO ordering, and for resequenced and delayed-message blocks,
pga_round is omitted and a single RoundEnd follows the block's
transactions.

The demo client dispatches on kind and still accepts version 1 messages,
to ease migration. Existing consumers must handle version 2 and the new
kind before the sequencer upgrades.

Closes NIT-5927
Feed consumers that wait for every transaction of a PGA round before
acting could only infer that a round had ended when the first message of
the next round arrived, which wasted the next round's bidding window.

Bump the feed to version 2. Every message now starts with an envelope of
version, kind, timestamp_ms, and pga_round. The transaction payload is
unchanged under kind "Transaction". The new kind "PGARoundEnd" carries
block_number and marks the end of a PGA round. Consumers should ignore
kinds they don't know, so this change is forward-compatible.

A PGA round with one transaction produces:

    {"version":2,"kind":"Transaction","timestamp_ms":1759795200000,
     "pga_round":3,"transaction":{"block_number":1234,"tx_index":1,
     "raw_tx":"0x02f8...","tx_hash":"0xab...","receipt":{...}}}
    {"version":2,"kind":"PGARoundEnd","timestamp_ms":1759795200012,
     "pga_round":3,"block_number":1234}

The PGA orderer sends it through the feed broadcaster the sequencer hands
it, from recordRoundEnd and before the wait for the next round, so empty
rounds are signalled too. FIFO ordering, delayed-message blocks, and
resequenced blocks have no rounds and send nothing new.

The demo client dispatches on kind and still accepts version 1 messages,
to ease migration. Existing consumers must handle version 2 and the new
kind before the sequencer upgrades.

Closes NIT-5927
…065-transaction-feed-client

Backport transaction-feed client example
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Nitro never builds block access lists, so repair can reset a bals table
that lags after a 3.11.x run instead of truncating the chain to it.
…ort-3.12

Keep recent blocks when returning to 3.12.x after 3.11.x (backport OffchainLabs#1110)

@sduchesneau sduchesneau left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@sduchesneau
sduchesneau merged commit 42d5b4f into release/v3.x-fh Nov 6, 2026
3 of 5 checks passed
@sduchesneau
sduchesneau deleted the bump/nitro-3.12.2 branch November 6, 2026 21:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

9 participants