feat(kona): execute NUT bundles at Karst fork activation

docker-bake.hcl

@@ -346,6 +346,9 @@ target "op-rbuilder" {
 target "kona-node" {
   dockerfile = "kona/docker/apps/kona_app_generic.dockerfile"
   context = "rust"
+  contexts = {
+    nuts-bundles = "op-core/nuts/bundles"
+  }
   args = {
     REPO_LOCATION = "local"
     BIN_TARGET = "kona-node"
@@ -358,6 +361,9 @@ target "kona-node" {
 target "kona-host" {
   dockerfile = "kona/docker/apps/kona_app_generic.dockerfile"
   context = "rust"
+  contexts = {
+    nuts-bundles = "op-core/nuts/bundles"
+  }
   args = {
     REPO_LOCATION = "local"
     BIN_TARGET = "kona-host"
@@ -370,6 +376,9 @@ target "kona-host" {
 target "kona-client" {
   dockerfile = "kona/docker/apps/kona_app_generic.dockerfile"
   context = "rust"
+  contexts = {
+    nuts-bundles = "op-core/nuts/bundles"
+  }
   args = {
     REPO_LOCATION = "local"
     BIN_TARGET = "kona-client"

op-e2e/actions/proofs/karst_fork_test.go

@@ -0,0 +1,94 @@
+package proofs
+
+import (
+	"context"
+	"math/big"
+	"testing"
+
+	"github.com/ethereum-optimism/optimism/op-chain-ops/genesis"
+	"github.com/ethereum-optimism/optimism/op-core/forks"
+	"github.com/ethereum-optimism/optimism/op-core/predeploys"
+	actionsHelpers "github.com/ethereum-optimism/optimism/op-e2e/actions/helpers"
+	"github.com/ethereum-optimism/optimism/op-e2e/actions/proofs/helpers"
+	"github.com/ethereum/go-ethereum/common"
+	"github.com/ethereum/go-ethereum/common/hexutil"
+	"github.com/stretchr/testify/require"
+)
+
+// TestKarstPredeployImplementationsUpgraded verifies that Karst activation
+// replaces the implementation address stored in the EIP-1967 slot of
+// representative predeploy proxies. It is a smoke test that the bundle's
+// upgrade transactions actually rewrote proxy implementation pointers — not
+// a check of what the new implementations do (that's the job of the per-
+// contract test suites).
+//
+// The invariant is Karst-specific: every "Deploy X Implementation" intent in
+// the Karst bundle lands at a fresh address, and L2ProxyAdmin's batch upgrade
+// (bundle intent 31) repoints predeploy proxies to those fresh addresses. A
+// future fork that doesn't upgrade proxies wouldn't satisfy this, which is
+// why the assertion lives in a Karst-specific test rather than in the generic
+// NUT bundle activation test.
+func TestKarstPredeployImplementationsUpgraded(gt *testing.T) {
+	matrix := helpers.NewMatrix[any]()
+	matrix.AddDefaultTestCases(
+		nil,
+		helpers.NewForkMatrix(helpers.Jovian),
+		testKarstPredeployImplementationsUpgraded,
+	)
+	matrix.Run(gt)
+}
+
+func testKarstPredeployImplementationsUpgraded(gt *testing.T, testCfg *helpers.TestCfg[any]) {
+	t := actionsHelpers.NewDefaultTesting(gt)
+
+	offset := uint64(4)
+	testSetup := func(dc *genesis.DeployConfig) {
+		dc.L1PragueTimeOffset = ptr(hexutil.Uint64(0))
+		dc.SetForkTimeOffset(forks.Karst, &offset)
+	}
+	env := helpers.NewL2FaultProofEnv(t, testCfg, helpers.NewTestParams(), helpers.NewBatcherCfg(), testSetup)
+
+	env.Miner.ActEmptyBlock(t)
+	env.Sequencer.ActL1HeadSignal(t)
+	for i := 0; i < int(offset); i++ {
+		env.Sequencer.ActL2EmptyBlock(t)
+	}
+
+	engine := env.Engine
+	actHeader := engine.L2Chain().CurrentHeader()
+	require.Equal(t, forks.Karst,
+		env.Sd.RollupCfg.IsActivationBlock(actHeader.Time-env.Sd.RollupCfg.BlockTime, actHeader.Time),
+		"expected Karst activation block at time %d", actHeader.Time)
+
+	postBlock := actHeader.Number
+	preBlock := new(big.Int).Sub(postBlock, big.NewInt(1))
+
+	ethCl := engine.EthClient()
+
+	// Representative predeploys whose implementation Karst replaces. L1Block and
+	// GasPriceOracle mirror the proxies asserted by earlier fork tests (ecotone,
+	// isthmus); covering them keeps vocabulary consistent across fork tests.
+	proxies := []struct {
+		name string
+		addr common.Address
+	}{
+		{"L1Block", predeploys.L1BlockAddr},
+		{"GasPriceOracle", predeploys.GasPriceOracleAddr},
+	}
+	for _, p := range proxies {
+		preImpl, err := ethCl.StorageAt(context.Background(), p.addr, genesis.ImplementationSlot, preBlock)
+		require.NoError(t, err, "read %s impl slot pre-activation", p.name)
+		postImpl, err := ethCl.StorageAt(context.Background(), p.addr, genesis.ImplementationSlot, postBlock)
+		require.NoError(t, err, "read %s impl slot post-activation", p.name)
+
+		require.NotEqualf(t, preImpl, postImpl,
+			"%s (%s) implementation slot must change across Karst activation", p.name, p.addr)
+
+		// New impl must actually be deployed — guards against an upgrade that
+		// repoints a proxy at an empty address.
+		newImplAddr := common.BytesToAddress(postImpl)
+		code, err := ethCl.CodeAt(context.Background(), newImplAddr, postBlock)
+		require.NoError(t, err, "read code at new %s impl", p.name)
+		require.NotEmptyf(t, code, "new %s impl %s must have code", p.name, newImplAddr)
+	}
+}

op-e2e/actions/proofs/nut_bundle_activation_test.go

@@ -0,0 +1,126 @@
+package proofs
+
+import (
+	"testing"
+
+	"github.com/ethereum-optimism/optimism/op-chain-ops/genesis"
+	"github.com/ethereum-optimism/optimism/op-core/forks"
+	actionsHelpers "github.com/ethereum-optimism/optimism/op-e2e/actions/helpers"
+	"github.com/ethereum-optimism/optimism/op-e2e/actions/proofs/helpers"
+	"github.com/ethereum-optimism/optimism/op-node/rollup/derive"
+	"github.com/ethereum/go-ethereum/common/hexutil"
+	"github.com/ethereum/go-ethereum/core/types"
+	"github.com/stretchr/testify/require"
+)
+
+// TestActivationBlockNUTBundle verifies that, for every fork from Karst onward,
+// the fork's activation block contains exactly the bundle's deposit transactions
+// in order and that every upgrade tx executes successfully.
+//
+// Discovery runs through [forks.From]([forks.Karst]), so any future fork is
+// covered automatically — and required to have a NUT bundle registered with
+// [derive.UpgradeTransactions]. The only per-fork requirement beyond that is
+// that the fork immediately preceding it is registered in [helpers.Hardforks]
+// — a one-line entry needed for any fork-parametrized test in this package.
+func TestActivationBlockNUTBundle(gt *testing.T) {
+	matrix := helpers.NewMatrix[forks.Name]()
+
+	// Resolve Karst's index in forks.All so we can reach the immediately preceding
+	// fork for each entry yielded by forks.From(Karst).
+	karstIdx := -1
+	for i, f := range forks.All {
+		if f == forks.Karst {
+			karstIdx = i
+			break
+		}
+	}
+	require.Greater(gt, karstIdx, 0, "Karst must not be first in forks.All")
+
+	for i, fork := range forks.From(forks.Karst) {
+		_, _, err := derive.UpgradeTransactions(fork)
+		require.NoError(gt, err, "fork %s from Karst onward must have a NUT bundle", fork)
+
+		preFork := forks.All[karstIdx+i-1]
+		preHelper := lookupHardforkHelper(preFork)
+		require.NotNil(gt, preHelper,
+			"no pre-fork helper registered for NUT-bundle fork %s (prior fork: %s); add %s to helpers.Hardforks",
+			fork, preFork, preFork)
+
+		matrix.AddDefaultTestCasesWithName(
+			string(fork),
+			fork,
+			helpers.NewForkMatrix(preHelper),
+			testActivationBlockNUTBundle,
+		)
+	}
+
+	matrix.Run(gt)
+}
+
+func testActivationBlockNUTBundle(gt *testing.T, testCfg *helpers.TestCfg[forks.Name]) {
+	fork := testCfg.Custom
+	t := actionsHelpers.NewDefaultTesting(gt)
+
+	offset := uint64(4)
+	testSetup := func(dc *genesis.DeployConfig) {
+		dc.L1PragueTimeOffset = ptr(hexutil.Uint64(0))
+		dc.SetForkTimeOffset(fork, &offset)
+	}
+	env := helpers.NewL2FaultProofEnv(t, testCfg, helpers.NewTestParams(), helpers.NewBatcherCfg(), testSetup)
+
+	expectedTxs, expectedGas, err := derive.UpgradeTransactions(fork)
+	require.NoError(t, err, "load NUT bundle for %s", fork)
+	require.NotEmpty(t, expectedTxs, "bundle for %s must contain at least one upgrade tx", fork)
+
+	env.Miner.ActEmptyBlock(t)
+	env.Sequencer.ActL1HeadSignal(t)
+	for i := 0; i < int(offset); i++ {
+		env.Sequencer.ActL2EmptyBlock(t)
+	}
+
+	engine := env.Engine
+	actHeader := engine.L2Chain().CurrentHeader()
+	blockTime := env.Sd.RollupCfg.BlockTime
+	require.Equal(t, fork,
+		env.Sd.RollupCfg.IsActivationBlock(actHeader.Time-blockTime, actHeader.Time),
+		"expected activation block for %s at time %d", fork, actHeader.Time)
+
+	actBlock := engine.L2Chain().GetBlockByHash(actHeader.Hash())
+	txs := actBlock.Transactions()
+	// Index 0 is the L1 info deposit; indices 1.. are the NUT upgrade deposits.
+	require.Len(t, txs, 1+len(expectedTxs),
+		"activation block should have 1 L1 info deposit + %d NUT upgrade txs", len(expectedTxs))
+
+	var totalUpgradeGas uint64
+	for i, rawExpected := range expectedTxs {
+		actualBytes, err := txs[1+i].MarshalBinary()
+		require.NoError(t, err)
+		require.Equal(t, []byte(rawExpected), actualBytes, "NUT tx %d byte mismatch", i)
+
+		var expected types.Transaction
+		require.NoError(t, expected.UnmarshalBinary(rawExpected))
+		totalUpgradeGas += expected.Gas()
+	}
+	require.Equal(t, expectedGas, totalUpgradeGas, "total NUT gas must equal bundle total")
+
+	// Every tx in the activation block — the L1 info deposit and all NUT upgrade
+	// deposits — must execute successfully. A reverted upgrade tx would leave the
+	// chain in a broken fork-activation state.
+	receipts := engine.L2Chain().GetReceiptsByHash(actHeader.Hash())
+	require.Len(t, receipts, len(txs), "receipt count must match tx count")
+	for i, r := range receipts {
+		require.Equal(t, types.ReceiptStatusSuccessful, r.Status,
+			"activation-block tx %d reverted", i)
+	}
+}
+
+// lookupHardforkHelper resolves a fork name to its [helpers.Hardfork] entry by
+// scanning [helpers.Hardforks]. Returns nil when the fork isn't registered.
+func lookupHardforkHelper(name forks.Name) *helpers.Hardfork {
+	for _, hf := range helpers.Hardforks {
+		if forks.Name(hf.Name) == name {
+			return hf
+		}
+	}
+	return nil
+}

rust/kona/crates/protocol/derive/src/attributes/stateful.rs

@@ -165,10 +165,14 @@ where
         {
             upgrade_transactions.append(&mut Hardforks::JOVIAN.txs().collect());
         }
+        // Starting with Karst, upgrade transactions carry their own gas budget that is
+        // added to the block gas limit at the fork activation block.
+        let mut upgrade_gas: u64 = 0;
         if self.rollup_cfg.is_karst_active(next_l2_time) &&
             !self.rollup_cfg.is_karst_active(l2_parent.block_info.timestamp)
         {
             upgrade_transactions.append(&mut Hardforks::KARST.txs().collect());
+            upgrade_gas += Hardforks::KARST.upgrade_gas();
         }
         if self.rollup_cfg.is_interop_active(next_l2_time) &&
             !self.rollup_cfg.is_interop_active(l2_parent.block_info.timestamp)
@@ -214,9 +218,11 @@ where
             },
             transactions: Some(txs),
             no_tx_pool: Some(true),
-            gas_limit: Some(u64::from_be_bytes(
-                alloy_primitives::U64::from(sys_config.gas_limit).to_be_bytes(),
-            )),
+            gas_limit: Some(
+                u64::from_be_bytes(
+                    alloy_primitives::U64::from(sys_config.gas_limit).to_be_bytes(),
+                ) + upgrade_gas,
+            ),
             eip_1559_params: sys_config.eip_1559_params(
                 &self.rollup_cfg,
                 l2_parent.block_info.timestamp,

rust/kona/crates/protocol/hardforks/Cargo.toml

@@ -25,10 +25,18 @@ alloy-primitives = { workspace = true, features = ["rlp"] }
 # OP Alloy
 op-alloy-consensus.workspace = true
 
+[build-dependencies]
+anyhow.workspace = true
+serde = { workspace = true, features = ["derive"] }
+serde_json.workspace = true
+
 [dev-dependencies]
 alloy-primitives = { workspace = true, features = ["rand", "arbitrary"] }
+anyhow.workspace = true
 revm.workspace = true
 op-revm.workspace = true
+serde = { workspace = true, features = ["derive"] }
+serde_json.workspace = true
 
 [features]
 default = []

rust/kona/crates/protocol/hardforks/build.rs

@@ -0,0 +1,55 @@
+//! Build script for `kona-hardforks`.
+//!
+//! Reads NUT bundle JSON files from `op-core/nuts/bundles/` and generates Rust source
+//! that constructs [`op_alloy_consensus::NutBundle`] values at runtime without serde.
+//!
+//! The parsing and codegen logic lives in [`build_helpers`] so it can be shared
+//! with integration tests under `tests/`.
+
+use std::{env, fs, path::PathBuf};
+
+use anyhow::{anyhow, Context, Result};
+
+#[path = "build_helpers.rs"]
+mod build_helpers;
+
+use build_helpers::{capitalize, format_bundle, parse_bundle};
+
+/// Read the bundle JSON, generate Rust source, and write it to `out_dir`.
+fn generate(name: &str, json_path: &PathBuf, out_dir: &str) -> Result<()> {
+    let json = fs::read_to_string(json_path)
+        .with_context(|| format!("read {}", json_path.display()))?;
+    let bundle = parse_bundle(&json).with_context(|| format!("parse {}", json_path.display()))?;
+    let code = format_bundle(name, &capitalize(name), &bundle);
+    let out_path = PathBuf::from(out_dir).join(format!("{name}_nut_bundle.rs"));
+    fs::write(&out_path, code).with_context(|| format!("write {}", out_path.display()))?;
+    Ok(())
+}
+
+fn run() -> Result<()> {
+    let out_dir = env::var("OUT_DIR").context("OUT_DIR not set")?;
+    let manifest_dir =
+        PathBuf::from(env::var("CARGO_MANIFEST_DIR").context("CARGO_MANIFEST_DIR not set")?);
+
+    let monorepo_root = manifest_dir
+        .ancestors()
+        .find(|p| p.join("op-core").is_dir())
+        .ok_or_else(|| {
+            anyhow!(
+                "could not find op-core/ in any ancestor of {}",
+                manifest_dir.display()
+            )
+        })?
+        .to_path_buf();
+
+    let karst_bundle = monorepo_root.join("op-core/nuts/bundles/karst_nut_bundle.json");
+    println!("cargo::rerun-if-changed={}", karst_bundle.display());
+
+    generate("karst", &karst_bundle, &out_dir).context("generate karst bundle")
+}
+
+fn main() {
+    if let Err(e) = run() {
+        panic!("{e:?}");
+    }
+}