diff --git a/op-acceptance-tests/tests/derivation/confirmations/confirmations_test.go b/op-acceptance-tests/tests/derivation/confirmations/confirmations_test.go new file mode 100644 index 00000000000..0e1b6f34206 --- /dev/null +++ b/op-acceptance-tests/tests/derivation/confirmations/confirmations_test.go @@ -0,0 +1,164 @@ +package confirmations + +import ( + "context" + "fmt" + "testing" + "time" + + "github.com/ethereum-optimism/optimism/op-devstack/devtest" + "github.com/ethereum-optimism/optimism/op-devstack/dsl" + "github.com/ethereum-optimism/optimism/op-devstack/presets" + "github.com/ethereum-optimism/optimism/op-devstack/sysgo" + "github.com/ethereum-optimism/optimism/op-e2e/e2eutils/wait" + "github.com/ethereum-optimism/optimism/op-service/eth" + "github.com/ethereum-optimism/optimism/op-service/log" + "github.com/ethereum-optimism/optimism/op-service/testlog" + "github.com/ethereum/go-ethereum/common" + "github.com/stretchr/testify/require" +) + +// capturedTest sends both in-process Go logs and the Kona subprocess logs to the +// same capture, so a brief reset cannot escape between sync-status samples. +type capturedTest struct { + devtest.T + logger log.Logger +} + +func (t capturedTest) Logger() log.Logger { return t.logger } + +func TestVerifierConfirmationsProtectDerivationFromShallowL1Reorg(gt *testing.T) { + sysgo.SkipOnKonaNode(devtest.SerialT(gt), "pins op-node and kona-node explicitly; covered by the op-node variant") + for _, confirmations := range []uint64{0, 4} { + gt.Run(fmt.Sprintf("confirmations_%d", confirmations), func(gt *testing.T) { + testShallowL1Reorg(gt, confirmations) + }) + } +} + +func testShallowL1Reorg(gt *testing.T, confirmations uint64) { + logger, logs := testlog.CaptureLogger(gt, log.LevelInfo) + t := capturedTest{T: devtest.SerialT(gt), logger: logger} + runtime := sysgo.NewMixedSingleChainRuntime(t, sysgo.MixedSingleChainPresetConfig{ + NodeSpecs: []sysgo.MixedSingleChainNodeSpec{ + {ELKey: "sequencer-el", CLKey: "sequencer-cl", ELKind: sysgo.MixedL2ELOpGeth, CLKind: sysgo.MixedL2CLOpNode, IsSequencer: true}, + {ELKey: "go-el", CLKey: "go-cl", ELKind: sysgo.MixedL2ELOpGeth, CLKind: sysgo.MixedL2CLOpNode, VerifierL1Confs: confirmations}, + {ELKey: "kona-el", CLKey: "kona-cl", ELKind: sysgo.MixedL2ELOpGeth, CLKind: sysgo.MixedL2CLKona, VerifierL1Confs: confirmations}, + }, + WithTestSequencer: true, + // Keep all manually produced empty blocks within one sequencing window. + DeployerOptions: []sysgo.DeployerOption{sysgo.WithSequencingWindow(12)}, + }) + sys := presets.NewMixedSingleChainFrontends(t, runtime) + verifiers := sys.Nodes[1:] + for _, verifier := range verifiers { + awaitStatus(t, verifier.CL, "a non-genesis safe head before the reorg", func(s *eth.SyncStatus) bool { + return s.SafeL2.Number >= 12 + }) + } + + sys.L2Batcher.Stop() + sys.L1CL.Stop() + // Drain the final batch input past the delayed verifiers. The replaced tip + // then carries no data needed to derive their existing safe heads. + for range confirmations + 2 { + sys.TestSequencer.SequenceBlock(t, sys.L1Network.ChainID(), common.Hash{}) + } + oldTip := sys.L1EL.BlockRefByLabel(eth.Unsafe) + confirmed := sys.L1EL.BlockRefByNumber(oldTip.Number - confirmations) + before := make([]eth.L2BlockRef, len(verifiers)) + for i, verifier := range verifiers { + s := awaitStatus(t, verifier.CL, "derivation at the configured confirmation distance", func(s *eth.SyncStatus) bool { + return s.HeadL1.Hash == oldTip.Hash && s.CurrentL1.ID() == confirmed.ID() + }) + before[i] = s.SafeL2 + } + logs.Clear() + + sys.TestSequencer.SequenceBlock(t, sys.L1Network.ChainID(), oldTip.ParentHash) + replacement := sys.L1EL.BlockRefByLabel(eth.Unsafe) + t.Require().Equal(oldTip.Number, replacement.Number, "the L1 replacement must be at the old tip's height") + t.Require().NotEqual(oldTip.Hash, replacement.Hash, "the test must replace the old L1 block") + t.Require().Equal(oldTip.ParentHash, replacement.ParentHash, "only the L1 tip should be replaced") + for _, verifier := range verifiers { + awaitStatus(t, verifier.CL, "observation of the replacement L1 head", func(s *eth.SyncStatus) bool { + return s.HeadL1.Hash == replacement.Hash + }) + } + + // A zero-confirmation verifier detects replacement of its consumed block + // when reading the replacement's child. Delayed verifiers instead consume + // the canonical replacement once it has the requested confirmations. + for range max(confirmations, 1) { + sys.TestSequencer.SequenceBlock(t, sys.L1Network.ChainID(), common.Hash{}) + tip := sys.L1EL.BlockRefByLabel(eth.Unsafe) + confirmed = sys.L1EL.BlockRefByNumber(tip.Number - confirmations) + for _, verifier := range verifiers { + awaitStatus(t, verifier.CL, "derivation of the canonical L1 block at the confirmation boundary", func(s *eth.SyncStatus) bool { + return s.HeadL1.Hash == tip.Hash && s.CurrentL1.ID() == confirmed.ID() + }) + } + } + if confirmations > 0 { + t.Require().Equal(replacement.ID(), confirmed.ID(), "the replacement must eventually become eligible for derivation") + } + for i, verifier := range verifiers { + awaitStatus(t, verifier.CL, "the same safe chain after the shallow L1 reorg", func(s *eth.SyncStatus) bool { + return s.SafeL2 == before[i] + }) + } + + if confirmations == 0 { + ctx, cancel := context.WithTimeout(t.Ctx(), 120*time.Second) + defer cancel() + err := wait.For(ctx, 100*time.Millisecond, func() (bool, error) { + goResets, konaResets := resetCounts(logs) + t.Logger().Info("Waiting for both clients to detect the consumed L1 tip replacement", "go_resets", goResets, "kona_resets", konaResets) + return goResets > 0 && konaResets > 0, nil + }) + t.Require().NoError(err, "both zero-confirmation verifiers must report their derivation reset") + } + goResets, konaResets := resetCounts(logs) + t.Logger().Info("Compared derivation resets after shallow L1 reorg", "confirmations", confirmations, "go_resets", goResets, "kona_resets", konaResets) + if confirmations == 0 { + t.Require().Positive(goResets, "Go must reset after consuming the replaced tip at zero confirmations") + t.Require().Positive(konaResets, "Kona must reset after consuming the replaced tip at zero confirmations") + } else { + t.Require().Zero(goResets, "Go must avoid a derivation reset for a reorg within its confirmation distance") + t.Require().Zero(konaResets, "Kona must avoid a derivation reset for a reorg within its confirmation distance") + } +} + +func resetCounts(logs *testlog.CapturingHandler) (goResets, konaResets int) { + goResets = len(logs.FindLogs( + testlog.NewMessageFilter("Deriver system is resetting"), + testlog.NewAttributesFilter("component", "l2cl-go-cl"), + )) + konaResets = len(logs.FindLogs( + testlog.NewMessageContainsFilter("Derivation pipeline is being reset"), + testlog.NewAttributesFilter("component", "kona-node"), + )) + return +} + +// awaitStatus keeps the scenario-specific predicate here while using the shared +// bounded wait primitive. RPC failures are logged and retried without calling +// FailNow from an asynchronous Eventually callback. +func awaitStatus(t devtest.T, node *dsl.L2CLNode, expectation string, accept func(*eth.SyncStatus) bool) *eth.SyncStatus { + t.Helper() + ctx, cancel := context.WithTimeout(t.Ctx(), 120*time.Second) + defer cancel() + var last *eth.SyncStatus + err := wait.For(ctx, 100*time.Millisecond, func() (bool, error) { + s, err := node.Escape().RollupAPI().SyncStatus(ctx) + if err != nil { + t.Logger().Warn("Waiting for rollup sync status", "node", node, "expectation", expectation, "err", err) + return false, nil + } + last = s + t.Logger().Info("Waiting for derivation state", "node", node, "expectation", expectation, "head_l1", s.HeadL1, "current_l1", s.CurrentL1, "safe_l2", s.SafeL2) + return accept(s), nil + }) + require.NoError(t, err, "%s did not reach %s; last status: %+v", node, expectation, last) + return last +} diff --git a/op-devstack/sysgo/l2_cl.go b/op-devstack/sysgo/l2_cl.go index d08122b3ce6..6b766fbb935 100644 --- a/op-devstack/sysgo/l2_cl.go +++ b/op-devstack/sysgo/l2_cl.go @@ -20,6 +20,8 @@ type L2CLConfig struct { // SyncMode for op-node, if this is a verifier. As above, this does not select // a native sync mode in Kona. VerifierSyncMode nodeSync.Mode + // VerifierL1Confs delays L1 input to derivation, independently of sequencing. + VerifierL1Confs uint64 // SafeDBPath is the path to the safe DB to use. Disabled if empty. SafeDBPath string diff --git a/op-devstack/sysgo/l2_cl_kona_config.go b/op-devstack/sysgo/l2_cl_kona_config.go index 215ea91148c..ecf1f1a54a1 100644 --- a/op-devstack/sysgo/l2_cl_kona_config.go +++ b/op-devstack/sysgo/l2_cl_kona_config.go @@ -47,6 +47,7 @@ func resolveKonaL2CLConfig(t devtest.T, key string, chainID eth.ChainID, isSeque unsupported.SequencerSyncMode = baseCfg.SequencerSyncMode unsupported.VerifierSyncMode = baseCfg.VerifierSyncMode unsupported.SafeDBPath = "" + unsupported.VerifierL1Confs = 0 unsupported.NoDiscovery = baseCfg.NoDiscovery unsupported.FollowSource = "" if isSequencer { @@ -64,7 +65,10 @@ func resolveKonaL2CLConfig(t devtest.T, key string, chainID eth.ChainID, isSeque } func konaL2CLEnv(cfg *L2CLConfig, sequencerStopped bool) []string { - extraEnv := []string{fmt.Sprintf("KONA_NODE_P2P_NO_DISCOVERY=%t", cfg.NoDiscovery)} + extraEnv := []string{ + fmt.Sprintf("KONA_NODE_P2P_NO_DISCOVERY=%t", cfg.NoDiscovery), + fmt.Sprintf("KONA_NODE_VERIFIER_L1_CONFS=%d", cfg.VerifierL1Confs), + } if cfg.SafeDBPath != "" { extraEnv = append(extraEnv, "KONA_NODE_SAFEDB_PATH="+cfg.SafeDBPath) } diff --git a/op-devstack/sysgo/l2_cl_kona_config_test.go b/op-devstack/sysgo/l2_cl_kona_config_test.go index 3b417b769e4..d70dc2b7690 100644 --- a/op-devstack/sysgo/l2_cl_kona_config_test.go +++ b/op-devstack/sysgo/l2_cl_kona_config_test.go @@ -29,6 +29,7 @@ func TestKonaL2CLEnvSupportedOptions(t *testing.T) { } require.Equal(t, []string{ "KONA_NODE_P2P_NO_DISCOVERY=false", + "KONA_NODE_VERIFIER_L1_CONFS=0", "KONA_NODE_SAFEDB_PATH=/tmp/safe-head.db", }, konaL2CLEnv(resolveKonaL2CLConfig(dt, "node", chainID, isSequencer, "", opts), false)) }) @@ -41,13 +42,13 @@ func TestKonaL2CLEnvDiscovery(t *testing.T) { t.Setenv("KONA_NODE_P2P_NO_DISCOVERY", ambient) dt := devtest.SerialT(t) chainID := eth.ChainIDFromUInt64(901) - require.Equal(t, []string{"KONA_NODE_P2P_NO_DISCOVERY=" + ambient}, + require.Equal(t, []string{"KONA_NODE_P2P_NO_DISCOVERY=" + ambient, "KONA_NODE_VERIFIER_L1_CONFS=0"}, konaL2CLEnv(resolveKonaL2CLConfig(dt, "node", chainID, false, "", nil), false)) for _, noDiscovery := range []bool{false, true} { opts := []L2CLOption{L2CLOptionFn(func(_ devtest.T, _ ComponentTarget, cfg *L2CLConfig) { cfg.NoDiscovery = noDiscovery })} - require.Equal(t, []string{fmt.Sprintf("KONA_NODE_P2P_NO_DISCOVERY=%t", noDiscovery)}, + require.Equal(t, []string{fmt.Sprintf("KONA_NODE_P2P_NO_DISCOVERY=%t", noDiscovery), "KONA_NODE_VERIFIER_L1_CONFS=0"}, konaL2CLEnv(resolveKonaL2CLConfig(dt, "node", chainID, false, "", opts), false)) } }) @@ -60,11 +61,13 @@ func TestKonaL2CLEnvFollowSource(t *testing.T) { chainID := eth.ChainIDFromUInt64(901) require.Equal(t, []string{ "KONA_NODE_P2P_NO_DISCOVERY=true", + "KONA_NODE_VERIFIER_L1_CONFS=0", "KONA_NODE_L2_FOLLOW_SOURCE=http://initial:8545", }, konaL2CLEnv(resolveKonaL2CLConfig(dt, "node", chainID, false, "http://initial:8545", nil), false)) // Apply callbacks in order, with the same initial follow source as op-node. require.Equal(t, []string{ "KONA_NODE_P2P_NO_DISCOVERY=true", + "KONA_NODE_VERIFIER_L1_CONFS=0", "KONA_NODE_L2_FOLLOW_SOURCE=http://last:8545", }, konaL2CLEnv(resolveKonaL2CLConfig(dt, "node", chainID, false, "http://initial:8545", []L2CLOption{ L2CLOptionFn(func(_ devtest.T, _ ComponentTarget, config *L2CLConfig) { @@ -91,7 +94,7 @@ func TestKonaL2CLEnvAcceptsSyncModeCompatibilityInputs(t *testing.T) { })} // Neither compatibility mode emits a flag pretending to select a // native mode: Kona always drives EL sync through Engine API responses. - require.Equal(t, []string{"KONA_NODE_P2P_NO_DISCOVERY=true"}, + require.Equal(t, []string{"KONA_NODE_P2P_NO_DISCOVERY=true", "KONA_NODE_VERIFIER_L1_CONFS=0"}, konaL2CLEnv(resolveKonaL2CLConfig(devtest.SerialT(t), "node", eth.ChainIDFromUInt64(901), isSequencer, "", opts), false)) }) } @@ -106,6 +109,7 @@ func TestKonaL2CLEnvConductor(t *testing.T) { })} require.Equal(t, []string{ "KONA_NODE_P2P_NO_DISCOVERY=true", + "KONA_NODE_VERIFIER_L1_CONFS=0", "KONA_NODE_CONDUCTOR_RPC=http://conductor:8547", "KONA_NODE_CONDUCTOR_RPC_TIMEOUT=7", }, konaL2CLEnv(resolveKonaL2CLConfig(devtest.SerialT(t), "node", eth.ChainIDFromUInt64(901), true, "", opts), false)) @@ -162,8 +166,8 @@ func TestKonaL2CLEnvSequencerStopped(t *testing.T) { name string stopped bool }{ - {environment: []string{"KONA_NODE_P2P_NO_DISCOVERY=false"}, name: "running"}, - {environment: []string{"KONA_NODE_P2P_NO_DISCOVERY=false", "KONA_NODE_SEQUENCER_STOPPED=true"}, name: "stopped", stopped: true}, + {environment: []string{"KONA_NODE_P2P_NO_DISCOVERY=false", "KONA_NODE_VERIFIER_L1_CONFS=0"}, name: "running"}, + {environment: []string{"KONA_NODE_P2P_NO_DISCOVERY=false", "KONA_NODE_VERIFIER_L1_CONFS=0", "KONA_NODE_SEQUENCER_STOPPED=true"}, name: "stopped", stopped: true}, } { t.Run(testCase.name, func(t *testing.T) { cfg := DefaultL2CLConfig() @@ -198,3 +202,17 @@ func TestResolveKonaL2CLConfigSafeDBOptions(t *testing.T) { }) } } + +func TestKonaL2CLEnvVerifierL1Confs(t *testing.T) { + for _, isSequencer := range []bool{false, true} { + for _, confirmations := range []uint64{0, 4} { + t.Run(fmt.Sprintf("sequencer=%t/confs=%d", isSequencer, confirmations), func(t *testing.T) { + opts := []L2CLOption{L2CLOptionFn(func(_ devtest.T, _ ComponentTarget, cfg *L2CLConfig) { + cfg.VerifierL1Confs = confirmations + })} + cfg := resolveKonaL2CLConfig(devtest.SerialT(t), "node", eth.ChainIDFromUInt64(901), isSequencer, "", opts) + require.Contains(t, konaL2CLEnv(cfg, false), fmt.Sprintf("KONA_NODE_VERIFIER_L1_CONFS=%d", confirmations)) + }) + } + } +} diff --git a/op-devstack/sysgo/mixed_runtime.go b/op-devstack/sysgo/mixed_runtime.go index dc2f981c015..bdb6e8b0df6 100644 --- a/op-devstack/sysgo/mixed_runtime.go +++ b/op-devstack/sysgo/mixed_runtime.go @@ -184,6 +184,9 @@ type MixedSingleChainNodeSpec struct { // EnableSafeDB gives this node's CL a safe head database in a fresh temp dir, so it records // the L2 safe head reached as of each L1 block and serves it over optimism_safeHeadAtL1Block. EnableSafeDB bool + // VerifierL1Confs is the L1 confirmation distance used by derivation in either CL. + // It does not change the sequencer's L1 origin selection distance. + VerifierL1Confs uint64 } type MixedSingleChainPresetConfig struct { @@ -285,6 +288,7 @@ func NewMixedSingleChainRuntime(t devtest.T, cfg MixedSingleChainPresetConfig) * DependencySet: depSet, L2CLOptions: []L2CLOption{L2CLOptionFn(func(_ devtest.T, _ ComponentTarget, cfg *L2CLConfig) { cfg.SafeDBPath = safeDBPath + cfg.VerifierL1Confs = spec.VerifierL1Confs })}, }) case MixedL2CLKona: @@ -303,6 +307,7 @@ func NewMixedSingleChainRuntime(t devtest.T, cfg MixedSingleChainPresetConfig) * L2CLConfig: resolveKonaL2CLConfig(t, spec.CLKey, l2Net.ChainID(), spec.IsSequencer, "", []L2CLOption{ L2CLOptionFn(func(_ devtest.T, _ ComponentTarget, cfg *L2CLConfig) { cfg.SafeDBPath = safeDBPath + cfg.VerifierL1Confs = spec.VerifierL1Confs }), }), }, diff --git a/op-devstack/sysgo/singlechain_build.go b/op-devstack/sysgo/singlechain_build.go index edeae471f95..a0c777a418d 100644 --- a/op-devstack/sysgo/singlechain_build.go +++ b/op-devstack/sysgo/singlechain_build.go @@ -389,6 +389,7 @@ func startL2CLNode( SequencerEnabled: cfg.IsSequencer, SequencerStopped: startCfg.SequencerStopped, SequencerConfDepth: 2, + VerifierConfDepth: cfg.VerifierL1Confs, }, Rollup: *l2Net.rollupCfg, DependencySet: startCfg.DependencySet, diff --git a/rust/kona/bin/node/README.md b/rust/kona/bin/node/README.md index ddcb67e124e..79aafb7246e 100644 --- a/rust/kona/bin/node/README.md +++ b/rust/kona/bin/node/README.md @@ -80,6 +80,7 @@ Many configuration options can be set via environment variables: - `KONA_NODE_L1_ETH_RPC` - L1 execution client RPC URL - `KONA_NODE_L1_TRUST_RPC` - Whether to trust the L1 RPC without verification (default: false) - `KONA_NODE_L1_BEACON` - L1 beacon API URL +- `KONA_NODE_VERIFIER_L1_CONFS` - L1 confirmation depth before deriving L2 data (default: 0) - `KONA_NODE_L2_ENGINE_RPC` - L2 engine API URL - `KONA_NODE_L2_TRUST_RPC` - Whether to trust the L2 RPC without verification (default: true) - `KONA_NODE_L2_ENGINE_AUTH` - Path to L2 engine JWT secret file @@ -97,6 +98,11 @@ export RUST_LOG="kona_node=info,kona_derive=debug" kona-node node --port 5060 ``` +Use `--verifier.l1-confs 4` (or `KONA_NODE_VERIFIER_L1_CONFS=4`) to keep derivation +four blocks behind the observed L1 head. This applies in validator and sequencer modes; +the sequencer's selection of L1 origins is configured separately. The default of zero +derives through the L1 tip, matching op-node's default. + ### Help and Documentation Use the `--help` flag to see all available options and subcommands: diff --git a/rust/kona/bin/node/src/commands/node/command.rs b/rust/kona/bin/node/src/commands/node/command.rs index eac6935ab64..f06b2ff7675 100644 --- a/rust/kona/bin/node/src/commands/node/command.rs +++ b/rust/kona/bin/node/src/commands/node/command.rs @@ -122,6 +122,10 @@ pub struct NodeCommand { /// by `optimism_safeHeadAtL1Block`. Nothing is recorded when unset. #[arg(long = "safedb.path", env = "KONA_NODE_SAFEDB_PATH")] pub safedb_path: Option, + /// Number of L1 blocks to keep behind the L1 head before deriving L2 data. + /// Reorgs are supported, but may be slow to recover from. + #[arg(long = "verifier.l1-confs", env = "KONA_NODE_VERIFIER_L1_CONFS", default_value_t = 0)] + pub verifier_l1_confs: u64, /// P2P CLI arguments. #[command(flatten)] pub p2p_flags: P2PArgs, @@ -143,6 +147,7 @@ impl Default for NodeCommand { l1_config_file: None, interop_dependency_set: None, safedb_path: None, + verifier_l1_confs: 0, node_mode: NodeMode::Validator, p2p_flags: P2PArgs::default(), rpc_flags: RpcArgs::default(), @@ -341,6 +346,7 @@ impl NodeCommand { .with_derivation_delegate_config(derivation_delegate_config) .with_dependency_set(dependency_set) .with_safe_db(safe_db) + .with_verifier_l1_confs(self.verifier_l1_confs) .build() .start() .await diff --git a/rust/kona/bin/node/src/commands/node/tests.rs b/rust/kona/bin/node/src/commands/node/tests.rs index 766c342f3df..0cfb440c62b 100644 --- a/rust/kona/bin/node/src/commands/node/tests.rs +++ b/rust/kona/bin/node/src/commands/node/tests.rs @@ -32,6 +32,31 @@ fn test_node_cli_defaults() { let args = NodeCommand::parse_from(std::iter::once(&"node").chain(default_flags().iter()).copied()); assert_eq!(args.node_mode, NodeMode::Validator); + assert_eq!(args.verifier_l1_confs, 0); + assert_eq!(NodeCommand::default().verifier_l1_confs, 0); +} + +#[test] +fn verifier_confirmation_depth_is_available_in_both_node_modes() { + for mode in ["Validator", "Sequencer"] { + let args = NodeCommand::parse_from( + std::iter::once("node").chain(default_flags().iter().copied()).chain([ + "--mode", + mode, + "--verifier.l1-confs", + "4", + ]), + ); + assert_eq!(args.verifier_l1_confs, 4); + } +} + +#[test] +fn verifier_confirmation_depth_has_the_expected_environment_variable() { + use clap::CommandFactory; + let command = NodeCommand::command(); + let arg = command.get_arguments().find(|arg| arg.get_id() == "verifier_l1_confs").unwrap(); + assert_eq!(arg.get_env().unwrap(), "KONA_NODE_VERIFIER_L1_CONFS"); } #[test] diff --git a/rust/kona/crates/node/service/src/service/builder.rs b/rust/kona/crates/node/service/src/service/builder.rs index 1e21fddd85c..8400aec1f6f 100644 --- a/rust/kona/crates/node/service/src/service/builder.rs +++ b/rust/kona/crates/node/service/src/service/builder.rs @@ -80,6 +80,8 @@ pub struct RollupNodeBuilder { pub dependency_set: Option>, /// Records the safe head reached as of each L1 block when configured. pub safe_db: Option>, + /// Number of L1 confirmations required before deriving L2 blocks. + pub verifier_l1_confs: u64, } impl RollupNodeBuilder { @@ -105,6 +107,7 @@ impl RollupNodeBuilder { derivation_delegate_config: None, dependency_set: None, safe_db: None, + verifier_l1_confs: 0, } } @@ -122,6 +125,11 @@ impl RollupNodeBuilder { Self { safe_db, ..self } } + /// Sets the L1 confirmation depth for derivation in both node modes. + pub fn with_verifier_l1_confs(self, verifier_l1_confs: u64) -> Self { + Self { verifier_l1_confs, ..self } + } + /// Sets the [`EngineConfig`] on the [`RollupNodeBuilder`]. pub fn with_engine_config(self, engine_config: EngineConfig) -> Self { Self { engine_config, ..self } @@ -213,6 +221,7 @@ impl RollupNodeBuilder { derivation_delegate_provider, dependency_set: self.dependency_set, safe_db: self.safe_db, + verifier_l1_confs: self.verifier_l1_confs, } } } diff --git a/rust/kona/crates/node/service/src/service/node/rollup.rs b/rust/kona/crates/node/service/src/service/node/rollup.rs index c1cc99e61fa..d1b5fb0a12e 100644 --- a/rust/kona/crates/node/service/src/service/node/rollup.rs +++ b/rust/kona/crates/node/service/src/service/node/rollup.rs @@ -117,6 +117,8 @@ pub struct RollupNode { pub(crate) dependency_set: Option>, /// Records the safe head reached as of each L1 block. Disabled unless configured. pub(crate) safe_db: Option>, + /// L1 confirmation depth for online derivation, independent of sequencing. + pub(crate) verifier_l1_confs: u64, } /// A RollupNode-level derivation actor wrapper. @@ -219,13 +221,17 @@ impl RollupNode { ) } - async fn create_pipeline(&self) -> Result { + async fn create_pipeline( + &self, + l1_head: watch::Receiver>, + ) -> Result { // Create the caching L1/L2 EL providers for derivation. let l1_derivation_provider = AlloyChainProvider::new_with_trust( self.l1_config.engine_provider.clone(), DERIVATION_PROVIDER_CACHE_SIZE, self.l1_config.trust_rpc, - ); + ) + .with_confirmation_depth(self.verifier_l1_confs, l1_head); let l2_derivation_provider = BufferedAlloyL2ChainProvider::new( self.l2_block_buffer.clone(), AlloyL2ChainProvider::new_with_trust( @@ -283,6 +289,7 @@ impl RollupNode { engine_actor_request_tx: mpsc::Sender, derivation_actor_request_rx: mpsc::Receiver, derivation_origin_tx: watch::Sender>, + l1_head: watch::Receiver>, ) -> Result { if let Some(provider) = self.derivation_delegate_provider.clone() { // L1 Provider for sanity checking Derivation Delegation @@ -299,7 +306,7 @@ impl RollupNode { )))) } else { let pipeline = self - .create_pipeline() + .create_pipeline(l1_head) .await .map_err(|error| format!("Failed to initialize L1 blob provider: {error}"))?; let l1_block_zero = self.l1_block_zero().await?; @@ -614,6 +621,7 @@ impl RollupNode { engine_actor_request_tx.clone(), derivation_actor_request_rx, derivation_origin_tx, + l1_head_updates_rx.clone(), ) .await?; diff --git a/rust/kona/crates/protocol/derive/src/stages/traversal/polling.rs b/rust/kona/crates/protocol/derive/src/stages/traversal/polling.rs index d043cec0756..c88a307019d 100644 --- a/rust/kona/crates/protocol/derive/src/stages/traversal/polling.rs +++ b/rust/kona/crates/protocol/derive/src/stages/traversal/polling.rs @@ -147,8 +147,11 @@ impl Stage for PollingTraversal { l1_origin: BlockNumHash, system_config: SystemConfig, ) -> PipelineResult<()> { - let block_info = - self.data_source.block_info_by_number(l1_origin.number).await.map_err(Into::into)?; + let block_info = self + .data_source + .block_info_by_number_for_reset(l1_origin.number) + .await + .map_err(Into::into)?; self.update_origin(block_info); self.system_config = system_config; Ok(()) diff --git a/rust/kona/crates/protocol/derive/src/traits/providers.rs b/rust/kona/crates/protocol/derive/src/traits/providers.rs index 50eb15b62d6..37cd9f3ae3e 100644 --- a/rust/kona/crates/protocol/derive/src/traits/providers.rs +++ b/rust/kona/crates/protocol/derive/src/traits/providers.rs @@ -22,6 +22,20 @@ pub trait ChainProvider { /// source. async fn block_info_by_number(&mut self, number: u64) -> Result; + /// Resolves a reset base against the canonical chain without delaying for confirmations. + /// The reset base has already been selected; this lookup preserves canonical-by-number + /// resolution even if the supplied base hash was reorged out. Providers without a live + /// confirmation-depth policy use the ordinary lookup. + async fn block_info_by_number_for_reset( + &mut self, + number: u64, + ) -> Result + where + Self: Send, + { + self.block_info_by_number(number).await + } + /// Returns all receipts in the block with the given hash, or an error if the block does not /// exist in the data source. async fn receipts_by_hash(&mut self, hash: B256) -> Result, Self::Error>; diff --git a/rust/kona/crates/providers/providers-alloy/Cargo.toml b/rust/kona/crates/providers/providers-alloy/Cargo.toml index 907101fa217..27b510f4786 100644 --- a/rust/kona/crates/providers/providers-alloy/Cargo.toml +++ b/rust/kona/crates/providers/providers-alloy/Cargo.toml @@ -51,6 +51,7 @@ thiserror.workspace = true async-trait.workspace = true tower.workspace = true http-body-util.workspace = true +tokio = { workspace = true, features = ["sync"] } c-kzg.workspace = true tracing.workspace = true diff --git a/rust/kona/crates/providers/providers-alloy/src/chain_provider.rs b/rust/kona/crates/providers/providers-alloy/src/chain_provider.rs index 615b396ec6c..7367cbfcdec 100644 --- a/rust/kona/crates/providers/providers-alloy/src/chain_provider.rs +++ b/rust/kona/crates/providers/providers-alloy/src/chain_provider.rs @@ -24,6 +24,30 @@ use std::{ }, vec::Vec, }; +use tokio::sync::watch; + +/// Limits online derivation's forward traversal to sufficiently confirmed L1 blocks. +#[derive(Debug, Clone)] +struct ConfirmationDepth { + depth: u64, + head: watch::Receiver>, +} + +impl ConfirmationDepth { + fn allows(&self, number: u64) -> bool { + let head = *self.head.borrow(); + let Some(head) = head.filter(|head| *head != BlockInfo::default()) else { + // Like op-node, do not restrict startup before the first L1 head signal. + return true; + }; + // Always expose L1 genesis, and avoid accepting future blocks through integer overflow. + number == 0 || + self.depth == 0 || + number + .checked_add(self.depth) + .is_some_and(|confirmed_at| confirmed_at <= head.number) + } +} /// The [`AlloyChainProvider`] is a concrete implementation of the [`ChainProvider`] trait, /// providing data over Ethereum JSON-RPC using an alloy provider as the backend. @@ -33,6 +57,8 @@ pub struct AlloyChainProvider { pub inner: RootProvider, /// Whether to trust the RPC without verification. pub trust_rpc: bool, + /// Optional confirmation policy for online derivation's forward traversal only. + confirmation_depth: Option, /// `header_by_hash` LRU cache. header_by_hash_cache: LruCache, /// `receipts_by_hash_cache` LRU cache. @@ -63,6 +89,7 @@ impl AlloyChainProvider { Self { inner, trust_rpc, + confirmation_depth: None, header_by_hash_cache: LruCache::new(NonZeroUsize::new(cache_size).unwrap()), receipts_by_hash_cache: LruCache::new(NonZeroUsize::new(cache_size).unwrap()), raw_receipts_supported: Arc::new(AtomicBool::new(true)), @@ -78,6 +105,19 @@ impl AlloyChainProvider { Self::new(inner, cache_size) } + /// Hides L1 blocks with fewer than `depth` confirmations from forward traversal. + /// + /// Reset and hash-based lookups are unaffected. Configure only the online derivation provider, + /// so unsafe-head recovery and sequencing keep their own L1 views. + pub fn with_confirmation_depth( + mut self, + depth: u64, + head: watch::Receiver>, + ) -> Self { + self.confirmation_depth = Some(ConfirmationDepth { depth, head }); + self + } + /// Returns the latest L2 block number. pub async fn latest_block_number(&mut self) -> Result> { kona_macros::inc!(gauge, Metrics::CHAIN_PROVIDER_RPC_CALLS, "method" => "block_number"); @@ -458,6 +498,17 @@ impl ChainProvider for AlloyChainProvider { } async fn block_info_by_number(&mut self, number: u64) -> Result { + if self.confirmation_depth.as_ref().is_some_and(|depth| !depth.allows(number)) { + // A number-based not-found is temporary: traversal waits for more confirmations. + return Err(AlloyChainProviderError::BlockNotFound(number.into())); + } + self.block_info_by_number_for_reset(number).await + } + + async fn block_info_by_number_for_reset( + &mut self, + number: u64, + ) -> Result { kona_macros::inc!(gauge, Metrics::CHAIN_PROVIDER_RPC_CALLS, "method" => "block_by_number"); let block = self @@ -596,6 +647,149 @@ mod tests { AlloyChainProvider::new(RootProvider::new(RpcClient::mocked(asserter)), 8) } + fn observed_head(number: u64) -> BlockInfo { + BlockInfo { number, hash: B256::repeat_byte(0xaa), ..Default::default() } + } + + #[test] + fn confirmation_depth_boundaries() { + let (_head_tx, head_rx) = watch::channel(Some(observed_head(10))); + let policy = ConfirmationDepth { depth: 4, head: head_rx }; + assert!(policy.allows(0), "L1 genesis remains visible"); + assert!(policy.allows(6), "the exact confirmation boundary is visible"); + assert!(!policy.allows(7)); + assert!(!policy.allows(10)); + assert!(!policy.allows(u64::MAX), "addition must not overflow to an allowed height"); + } + + #[test] + fn confirmation_depth_unknown_head_and_zero_depth() { + let (head_tx, head_rx) = watch::channel(None); + let policy = ConfirmationDepth { depth: 4, head: head_rx.clone() }; + assert!(policy.allows(100), "op-node bypasses the limit before its first head signal"); + head_tx.send_replace(Some(BlockInfo::default())); + assert!(policy.allows(100), "an empty head matches op-node's zero block reference"); + head_tx.send_replace(Some(observed_head(10))); + assert!(!policy.allows(100)); + let no_delay = ConfirmationDepth { depth: 0, head: head_rx }; + assert!(no_delay.allows(u64::MAX), "zero depth ignores the observed L1 head"); + } + + #[tokio::test] + async fn confirmation_depth_tracks_head_regression_and_clones() { + let asserter = Asserter::new(); + let block = rpc_block(B256::ZERO, Vec::new(), alloy_consensus::EMPTY_ROOT_HASH); + asserter.push_success(&Some(block.clone())); + asserter.push_success(&Some(block)); + let (head_tx, head_rx) = watch::channel(Some(observed_head(10))); + let mut provider = mocked_provider(asserter.clone()).with_confirmation_depth(4, head_rx); + let mut cloned = provider.clone(); + provider.block_info_by_number(6).await.unwrap(); + head_tx.send_replace(Some(observed_head(9))); + let error = cloned.block_info_by_number(6).await.unwrap_err(); + assert!(matches!(PipelineErrorKind::from(error), PipelineErrorKind::Temporary(_))); + assert_eq!(asserter.read_q().len(), 1, "withheld blocks must not reach the RPC"); + head_tx.send_replace(Some(observed_head(10))); + cloned.block_info_by_number(6).await.unwrap(); + assert!(asserter.read_q().is_empty()); + } + + #[tokio::test] + async fn confirmation_depth_leaves_hash_reads_unrestricted() { + let asserter = Asserter::new(); + let block = rpc_block(B256::ZERO, Vec::new(), alloy_consensus::EMPTY_ROOT_HASH); + asserter.push_success(&Some(block)); + let (_head_tx, head_rx) = watch::channel(Some(observed_head(10))); + let mut provider = mocked_provider(asserter.clone()).with_confirmation_depth(4, head_rx); + provider.header_by_hash(B256::repeat_byte(0xbb)).await.unwrap(); + assert!(asserter.read_q().is_empty()); + } + + #[tokio::test] + async fn confirmation_depth_does_not_block_reset_within_the_window() { + use kona_derive::{OriginAdvancer, OriginProvider, PollingTraversal, Stage}; + use kona_genesis::{RollupConfig, SystemConfig}; + + let asserter = Asserter::new(); + let block: EthereumBlock = RpcBlock::new( + RpcHeader::new(Header { number: 1, ..Default::default() }), + BlockTransactions::Hashes(Vec::new()), + ); + asserter.push_success(&Some(block.clone())); + let (_head_tx, head_rx) = watch::channel(Some(observed_head(2))); + let provider = mocked_provider(asserter.clone()).with_confirmation_depth(4, head_rx); + let mut traversal = PollingTraversal::new(provider, Arc::new(RollupConfig::default())); + // Reset re-resolves the canonical block by number, even when its old hash is stale. + traversal + .reset(alloy_eips::BlockNumHash::new(1, B256::ZERO), SystemConfig::default()) + .await + .unwrap(); + assert_eq!(traversal.origin().unwrap().hash, block.header.hash); + assert!(matches!(traversal.advance_origin().await, Err(PipelineErrorKind::Temporary(_)))); + assert!(asserter.read_q().is_empty()); + } + + /// A one-block tip replacement is invisible to delayed traversal. At zero depth, consuming + /// the old tip and then its replacement's child produces the ordinary reorg reset. + #[tokio::test] + async fn confirmation_depth_shields_traversal_from_shallow_reorg() { + use kona_derive::{OriginAdvancer, OriginProvider, PollingTraversal}; + use kona_genesis::RollupConfig; + + let parent = BlockInfo { number: 13, hash: B256::repeat_byte(0x13), ..Default::default() }; + let make_block = |number, parent_hash, timestamp| -> EthereumBlock { + RpcBlock::new( + RpcHeader::new(Header { number, parent_hash, timestamp, ..Default::default() }), + BlockTransactions::Hashes(Vec::new()), + ) + }; + let old_tip = make_block(14, parent.hash, 14); + let replacement = make_block(14, parent.hash, 15); + let child = make_block(15, replacement.header.hash, 16); + let receipt = + ReceiptEnvelope::Legacy(ReceiptWithBloom::new(Receipt::default(), Bloom::ZERO)); + let raw_receipts = vec![Bytes::from(receipt.encoded_2718())]; + + for depth in [0, 1] { + let asserter = Asserter::new(); + let (head_tx, head_rx) = watch::channel(Some(observed_head(14))); + if depth == 0 { + asserter.push_success(&Some(old_tip.clone())); + asserter.push_success(&raw_receipts); + asserter.push_success(&Some(child.clone())); + } else { + asserter.push_success(&Some(replacement.clone())); + asserter.push_success(&raw_receipts); + } + let provider = + mocked_provider(asserter.clone()).with_confirmation_depth(depth, head_rx); + let mut traversal = PollingTraversal::new(provider, Arc::new(RollupConfig::default())); + traversal.block = Some(parent); + if depth == 0 { + traversal.advance_origin().await.unwrap(); + assert_eq!(traversal.origin().unwrap().hash, old_tip.header.hash); + } else { + assert!(matches!( + traversal.advance_origin().await, + Err(PipelineErrorKind::Temporary(_)) + )); + assert_eq!(traversal.origin(), Some(parent)); + } + head_tx.send_replace(Some(observed_head(15))); + let result = traversal.advance_origin().await; + if depth == 0 { + assert!(matches!( + result, + Err(PipelineErrorKind::Reset(ResetError::ReorgDetected(..))) + )); + } else { + result.unwrap(); + assert_eq!(traversal.origin().unwrap().hash, replacement.header.hash); + } + assert!(asserter.read_q().is_empty()); + } + } + #[test] fn test_from_alloy_chain_provider_error() { // Transport errors are transient — retry makes sense.