Skip to content
Merged
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
Original file line number Diff line number Diff line change
@@ -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
}
2 changes: 2 additions & 0 deletions op-devstack/sysgo/l2_cl.go
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 5 additions & 1 deletion op-devstack/sysgo/l2_cl_kona_config.go
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand All @@ -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)
}
Expand Down
28 changes: 23 additions & 5 deletions op-devstack/sysgo/l2_cl_kona_config_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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))
})
Expand All @@ -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))
}
})
Expand All @@ -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) {
Expand All @@ -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))
})
}
Expand All @@ -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))
Expand Down Expand Up @@ -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()
Expand Down Expand Up @@ -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))
})
}
}
}
5 changes: 5 additions & 0 deletions op-devstack/sysgo/mixed_runtime.go
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down Expand Up @@ -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:
Expand All @@ -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
}),
}),
},
Expand Down
1 change: 1 addition & 0 deletions op-devstack/sysgo/singlechain_build.go
Original file line number Diff line number Diff line change
Expand Up @@ -389,6 +389,7 @@ func startL2CLNode(
SequencerEnabled: cfg.IsSequencer,
SequencerStopped: startCfg.SequencerStopped,
SequencerConfDepth: 2,
VerifierConfDepth: cfg.VerifierL1Confs,
},
Rollup: *l2Net.rollupCfg,
DependencySet: startCfg.DependencySet,
Expand Down
6 changes: 6 additions & 0 deletions rust/kona/bin/node/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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:
Expand Down
6 changes: 6 additions & 0 deletions rust/kona/bin/node/src/commands/node/command.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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<PathBuf>,
/// 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,
Expand All @@ -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(),
Expand Down Expand Up @@ -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
Expand Down
25 changes: 25 additions & 0 deletions rust/kona/bin/node/src/commands/node/tests.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand Down
Loading
Loading