From 9bdfff71e14324b01a6f185aa45bb02fe1d2040d Mon Sep 17 00:00:00 2001 From: Einar Rasmussen Date: Fri, 30 Oct 2026 19:36:21 -0500 Subject: [PATCH 1/3] kona-node,safedb,op-acceptance-tests: validate persistence and proof consumers Validate SafeDB history across restart and resync, Cannon execution-step proofs through game resolution, and dispute-monitor proof consumers. Run op-geth resync coverage sequentially before normal acceptance tests for both consensus clients, and document the historical RPC contract. --- .circleci/continue/main.yml | 14 + .../node-operators/kona-node/rpc/rollup.mdx | 266 +++++++++++++----- .../tests/proofs/cannon_kona/setup_test.go | 1 + .../tests/proofs/cannon_kona/step_test.go | 18 +- .../safedb_proof_consumers/consumers_test.go | 96 +++++++ .../safeheaddb_clsync/safeheaddb_test.go | 2 + .../safeheaddb_elsync/safeheaddb_test.go | 13 +- rust/kona/crates/node/safedb/README.md | 13 + 8 files changed, 324 insertions(+), 99 deletions(-) create mode 100644 op-acceptance-tests/tests/safedb_proof_consumers/consumers_test.go diff --git a/.circleci/continue/main.yml b/.circleci/continue/main.yml index 1495c561e10..d4959f2d223 100644 --- a/.circleci/continue/main.yml +++ b/.circleci/continue/main.yml @@ -2233,6 +2233,20 @@ jobs: # does not need a separate `go mod download`. - go-restore-cache: namespace: op-acceptance-tests + - run: + name: Run SafeDB resync tests with op-geth + command: | + if [ "${CIRCLE_NODE_INDEX:-0}" != "0" ]; then + exit 0 + fi + mkdir -p op-acceptance-tests/logs/safedb-op-geth op-acceptance-tests/results + DEVSTACK_L2EL_KIND=op-geth LOG_LEVEL=info gotestsum \ + --format testname \ + --jsonfile op-acceptance-tests/logs/safedb-op-geth/raw_go_events.log \ + --junitfile op-acceptance-tests/results/safedb-op-geth.xml \ + -- -count=1 -p=1 -parallel=1 -timeout=10m \ + ./op-acceptance-tests/tests/safeheaddb_elsync \ + ./op-acceptance-tests/tests/safeheaddb_clsync # Run the acceptance tests (if the devnet is running) - run: name: Run acceptance tests diff --git a/docs/public-docs/node-operators/kona-node/rpc/rollup.mdx b/docs/public-docs/node-operators/kona-node/rpc/rollup.mdx index 59becec189c..a568ae84079 100644 --- a/docs/public-docs/node-operators/kona-node/rpc/rollup.mdx +++ b/docs/public-docs/node-operators/kona-node/rpc/rollup.mdx @@ -120,6 +120,137 @@ Returns the output root at a specific block number, including the L2 block refer } ``` +## `optimism_rollupConfig` + +Returns the rollup configuration parameters that define the rollup chain's behavior and properties. + +| Client | Method invocation | +| ------ | ---------------------------------------------- | +| RPC | `{"method": "optimism_rollupConfig", "params": []}` | + +### Returns + +`RollupConfig` - An object containing the complete rollup configuration: +- `genesis` (`ChainGenesis`): The genesis state of the rollup +- `blockTime` (`number`): The block time of the L2 in seconds +- `maxSequencerDrift` (`number`): Maximum sequencer drift in seconds +- `seqWindowSize` (`number`): The sequencer window size +- `channelTimeout` (`number`): Number of L1 blocks between channel open/close +- `graniteChannelTimeout` (`number`): Channel timeout after Granite hardfork +- `l1ChainId` (`number`): The L1 chain ID +- `l2ChainId` (`number`): The L2 chain ID +- `batchInboxAddress` (`string`): L1 address where batches are sent +- `depositContractAddress` (`string`): L1 address for deposits +- `l1SystemConfigAddress` (`string`): L1 address for system config +- `protocolVersionsAddress` (`string`): L1 address for protocol versions +- Additional configuration fields for hardforks, fees, and interoperability + +### Example + +```js +// > {"jsonrpc":"2.0","id":1,"method":"optimism_rollupConfig","params":[]} +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "genesis": { + "l1": { + "hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", + "number": 18000000 + }, + "l2": { + "hash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890", + "number": 0, + "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000", + "timestamp": 1699000000, + "l1Origin": { + "hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", + "number": 18000000 + }, + "sequenceNumber": 0 + }, + "l2Time": 1699000000, + "systemConfig": { + "batcherAddr": "0x1234567890123456789012345678901234567890", + "overhead": "0x00000000000000000000000000000000000000000000000000000000000000bc", + "scalar": "0x00000000000000000000000000000000000000000000000000000000000f4240", + "gasLimit": 30000000 + } + }, + "blockTime": 2, + "maxSequencerDrift": 600, + "seqWindowSize": 3600, + "channelTimeout": 300, + "graniteChannelTimeout": 50, + "l1ChainId": 1, + "l2ChainId": 10, + "batchInboxAddress": "0xff00000000000000000000000000000000000010", + "depositContractAddress": "0xbEb5Fc579115071764c7423A4f12eDde41f106Ed", + "l1SystemConfigAddress": "0x229047fed2591dbec1eF1118d64F7aF3dB9EB290", + "protocolVersionsAddress": "0x8062AbC286f5e7D9428a0Ccb9AbD71e50d93b935", + "superchainConfigAddress": "0x95703e0982140D16f8ebA6d158FccEde42f04a4C", + "blobs_data": 1710374400, + "interopMessageExpiryWindow": 3600, + "chainOpConfig": { + "canyon_denominator": 250, + "canyon_elasticity": 6 + } + } +} +``` + +## `optimism_safeHeadAtL1Block` + +Returns the most recent recorded L2 safe head whose derivation source L1 block is at or before the requested L1 block. Enable persistence with `--safedb.path` or `KONA_NODE_SAFEDB_PATH`. + +### Parameters + +- `l1BlockNumber` (`string`): An L1 block number encoded as a hexadecimal quantity, such as `"0x64"`. Block tags are not supported. + +### Returns + +An object containing: + +- `l1Block`: The recorded derivation source L1 block, with `hash` and `number` fields. +- `safeHead`: The corresponding L2 safe head, with `hash` and `number` fields. + +Both block numbers in the response are JSON integers. The recorded L1 block can precede the requested block because records are sparse. A request above the recorded tip returns the latest record; it does not establish that derivation has processed the requested L1 block. + +### Errors + +| Condition | Code | Message | +| --- | --- | --- | +| No record exists at or before the requested L1 block | `-32000` | `not found` | +| SafeDB is disabled | `-32000` | Contains `safe head database not enabled` | +| Invalid parameter encoding | `-32602` | Invalid parameters | + +A disabled database is distinct from an enabled database with no matching record. Database read failures also return an RPC error; callers must not interpret a failed lookup as proof of historical safety. + +### Example + +```json +{"id":1,"jsonrpc":"2.0","method":"optimism_safeHeadAtL1Block","params":["0x64"]} +``` + +An illustrative response: + +```json +{ + "id": 1, + "jsonrpc": "2.0", + "result": { + "l1Block": { + "hash": "0x1111111111111111111111111111111111111111111111111111111111111111", + "number": 98 + }, + "safeHead": { + "hash": "0x2222222222222222222222222222222222222222222222222222222222222222", + "number": 42 + } + } +} +``` + ## `optimism_syncStatus` Returns the current synchronization status of the rollup node, including information about L1 and L2 block states. @@ -217,104 +348,91 @@ Returns the current synchronization status of the rollup node, including informa } ``` -## `optimism_rollupConfig` +## `optimism_version` -Returns the rollup configuration parameters that define the rollup chain's behavior and properties. +Returns the software version of the Kona rollup node. -| Client | Method invocation | -| ------ | ---------------------------------------------- | -| RPC | `{"method": "optimism_rollupConfig", "params": []}` | +| Client | Method invocation | +| ------ | ---------------------------------------- | +| RPC | `{"method": "optimism_version", "params": []}` | ### Returns -`RollupConfig` - An object containing the complete rollup configuration: -- `genesis` (`ChainGenesis`): The genesis state of the rollup -- `blockTime` (`number`): The block time of the L2 in seconds -- `maxSequencerDrift` (`number`): Maximum sequencer drift in seconds -- `seqWindowSize` (`number`): The sequencer window size -- `channelTimeout` (`number`): Number of L1 blocks between channel open/close -- `graniteChannelTimeout` (`number`): Channel timeout after Granite hardfork -- `l1ChainId` (`number`): The L1 chain ID -- `l2ChainId` (`number`): The L2 chain ID -- `batchInboxAddress` (`string`): L1 address where batches are sent -- `depositContractAddress` (`string`): L1 address for deposits -- `l1SystemConfigAddress` (`string`): L1 address for system config -- `protocolVersionsAddress` (`string`): L1 address for protocol versions -- Additional configuration fields for hardforks, fees, and interoperability +`string` - The version string of the Kona software (e.g., "0.1.0") ### Example ```js -// > {"jsonrpc":"2.0","id":1,"method":"optimism_rollupConfig","params":[]} +// > {"jsonrpc":"2.0","id":1,"method":"optimism_version","params":[]} { "jsonrpc": "2.0", "id": 1, - "result": { - "genesis": { - "l1": { - "hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", - "number": 18000000 - }, - "l2": { - "hash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890", - "number": 0, - "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000", - "timestamp": 1699000000, - "l1Origin": { - "hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", - "number": 18000000 - }, - "sequenceNumber": 0 - }, - "l2Time": 1699000000, - "systemConfig": { - "batcherAddr": "0x1234567890123456789012345678901234567890", - "overhead": "0x00000000000000000000000000000000000000000000000000000000000000bc", - "scalar": "0x00000000000000000000000000000000000000000000000000000000000f4240", - "gasLimit": 30000000 - } - }, - "blockTime": 2, - "maxSequencerDrift": 600, - "seqWindowSize": 3600, - "channelTimeout": 300, - "graniteChannelTimeout": 50, - "l1ChainId": 1, - "l2ChainId": 10, - "batchInboxAddress": "0xff00000000000000000000000000000000000010", - "depositContractAddress": "0xbEb5Fc579115071764c7423A4f12eDde41f106Ed", - "l1SystemConfigAddress": "0x229047fed2591dbec1eF1118d64F7aF3dB9EB290", - "protocolVersionsAddress": "0x8062AbC286f5e7D9428a0Ccb9AbD71e50d93b935", - "superchainConfigAddress": "0x95703e0982140D16f8ebA6d158FccEde42f04a4C", - "blobs_data": 1710374400, - "interopMessageExpiryWindow": 3600, - "chainOpConfig": { - "canyon_denominator": 250, - "canyon_elasticity": 6 - } - } + "result": "0.1.0" } ``` -## `optimism_version` +## `superroot_atTimestamp` -Returns the software version of the Kona rollup node. +Returns a pre-interop, single-chain super root and its L1 derivation requirements. This method uses the `superroot` namespace rather than the `optimism` namespace. SafeDB must be enabled and contain the relevant history for a non-genesis block that is locally safe. -| Client | Method invocation | -| ------ | ---------------------------------------- | -| RPC | `{"method": "optimism_version", "params": []}` | +### Parameters + +- `timestamp` (`string`): An L2 timestamp encoded as a hexadecimal quantity. The rollup configuration maps the timestamp to an L2 block number. ### Returns -`string` - The version string of the Kona software (e.g., "0.1.0") +The response reports derivation progress even when the requested block is not yet locally safe: + +- `chain_ids`: The single chain ID, encoded as a decimal string. +- `current_l1`: The derivation cursor, with `hash` and `number` fields. Every L1 block strictly below this cursor has been fully processed. Consumers checking an L1 scope `X` must wait for `current_l1.number > X`. +- `finalized_timestamp`: The finalized L2 head timestamp, as a JSON integer. +- `local_safe_timestamp`: The locally safe L2 head timestamp, as a JSON integer. +- `optimistic_at_timestamp`: A map keyed by decimal chain ID. Once the requested block is locally safe, its entry contains `output`, `output_root`, and the SafeDB-backed `required_l1` block. +- `safe_timestamp`: The safe L2 head timestamp, as a JSON integer. + +When the block is locally safe, `data` contains: + +- `super`: The version 1 preimage, containing `chains` and a hexadecimal `timestamp`. Each chain entry contains `ChainID` as a decimal string and `Output` as an output-root hash. +- `super_root`: The super-root hash. +- `verified_required_l1`: The SafeDB-backed L1 block required to derive the output. For the single-chain response, it equals that chain's `required_l1`. + +The `output` preimage contains `blockHash`, `messagePasserStorageRoot`, and `stateRoot`. L1 block references contain a hash and a JSON integer block number. Genesis has a zero L1 requirement. + +When the requested block is above local-safe, `optimistic_at_timestamp` is empty and `data` is omitted. Consumers must wait for a response containing the requested output rather than treating a progress-only response as a verified super root. + +### Errors + +- A timestamp before L2 genesis returns `-32602`. +- History not yet recorded returns `-32000` with a message containing `l1 at safe head not found`. +- History before the available range returns `-32000` with a message containing `l1 at safe head history unavailable`. Waiting for more derivation does not restore that missing historical range. +- A disabled database returns `-32000` with a message containing `safe head database not enabled` when a non-genesis historical lookup is required. +- If history changes repeatedly while the output is read, the request returns `-32000` with `safe head history changed during query; retry`. +- Database and engine read failures return RPC errors rather than an unverified root. + +SafeDB lookup messages for this method include the operation prefix `l1AtSafeHead@`. They differ from the bare `not found` message returned by `optimism_safeHeadAtL1Block`. ### Example -```js -// > {"jsonrpc":"2.0","id":1,"method":"optimism_version","params":[]} +```json +{"id":1,"jsonrpc":"2.0","method":"superroot_atTimestamp","params":["0x6553f100"]} +``` + +An illustrative progress-only response when the requested block is not yet locally safe: + +```json { - "jsonrpc": "2.0", "id": 1, - "result": "0.1.0" + "jsonrpc": "2.0", + "result": { + "chain_ids": ["901"], + "current_l1": { + "hash": "0x1111111111111111111111111111111111111111111111111111111111111111", + "number": 100 + }, + "finalized_timestamp": 1699999900, + "local_safe_timestamp": 1699999998, + "optimistic_at_timestamp": {}, + "safe_timestamp": 1699999998 + } } ``` diff --git a/op-acceptance-tests/tests/proofs/cannon_kona/setup_test.go b/op-acceptance-tests/tests/proofs/cannon_kona/setup_test.go index b84663e040f..10893ceeab6 100644 --- a/op-acceptance-tests/tests/proofs/cannon_kona/setup_test.go +++ b/op-acceptance-tests/tests/proofs/cannon_kona/setup_test.go @@ -11,6 +11,7 @@ func cannonOpts() []presets.Option { return []presets.Option{ presets.WithGameTypeAdded(gameTypes.CannonKonaGameType), presets.WithDeployerOptions(sysgo.WithJovianAtGenesis), + presets.WithTimeTravelEnabled(), presets.WithGlobalL2CLOption(sysgo.L2CLOptionFn(func(p devtest.T, _ sysgo.ComponentTarget, cfg *sysgo.L2CLConfig) { cfg.SafeDBPath = p.TempDir() })), diff --git a/op-acceptance-tests/tests/proofs/cannon_kona/step_test.go b/op-acceptance-tests/tests/proofs/cannon_kona/step_test.go index bf49e843ac3..f3a6ed5bdc3 100644 --- a/op-acceptance-tests/tests/proofs/cannon_kona/step_test.go +++ b/op-acceptance-tests/tests/proofs/cannon_kona/step_test.go @@ -2,10 +2,11 @@ package cannon_kona import ( "testing" + "time" + gameTypes "github.com/ethereum-optimism/optimism/op-challenger/game/types" "github.com/ethereum-optimism/optimism/op-devstack/devtest" "github.com/ethereum-optimism/optimism/op-devstack/dsl/proofs" - "github.com/ethereum-optimism/optimism/op-devstack/sysgo" "github.com/ethereum-optimism/optimism/op-service/eth" safety "github.com/ethereum-optimism/optimism/op-service/eth/safety" @@ -13,19 +14,6 @@ import ( func TestExecuteStep_CannonKona(gt *testing.T) { t := devtest.ParallelT(gt) - // Example error with kona-node: - // - // assertions.go:387: ERROR[03-31|10:33:38.442] - // assertions.go:387: Error Trace: /optimism/op-devstack/dsl/proofs/game_helper.go:263 - // assertions.go:387: /optimism/op-devstack/dsl/proofs/game_helper.go:196 - // assertions.go:387: /optimism/op-devstack/dsl/proofs/fault_dispute_game.go:124 - // assertions.go:387: /optimism/op-acceptance-tests/tests/proofs/cannon/step_test.go:40 - // assertions.go:387: /.local/share/mise/installs/go/1.24.13/src/runtime/asm_arm64.s:1223 - // assertions.go:387: Error: Received unexpected error: - // assertions.go:387: failed to get safe head at L1 block 0xe926b953777546729b2607011590354a6a42dc35e36b7ea68c9dd4b470261541:6: not found - // assertions.go:387: Test: TestExecuteStep_CannonKona - // assertions.go:387: Messages: Failed to get honest root claim - sysgo.SkipOnKonaNode(t, "not supported") sys := newSystem(t) l1User := sys.FunderL1.NewFundedEOA(eth.ThousandEther) @@ -39,4 +27,6 @@ func TestExecuteStep_CannonKona(gt *testing.T) { claim = game.DisputeToStep(l1User, claim, 1000) // Skip down to max depth game.LogGameData() claim.WaitForCountered() + sys.AdvanceTime(game.MaxClockDuration() + time.Second) + game.WaitForGameStatus(gameTypes.GameStatusDefenderWon) } diff --git a/op-acceptance-tests/tests/safedb_proof_consumers/consumers_test.go b/op-acceptance-tests/tests/safedb_proof_consumers/consumers_test.go new file mode 100644 index 00000000000..b6438daaa3c --- /dev/null +++ b/op-acceptance-tests/tests/safedb_proof_consumers/consumers_test.go @@ -0,0 +1,96 @@ +package safedb_proof_consumers + +import ( + "testing" + + gameTypes "github.com/ethereum-optimism/optimism/op-challenger/game/types" + "github.com/ethereum-optimism/optimism/op-core/devfeatures" + "github.com/ethereum-optimism/optimism/op-devstack/devtest" + "github.com/ethereum-optimism/optimism/op-devstack/dsl" + "github.com/ethereum-optimism/optimism/op-devstack/dsl/disputemon" + "github.com/ethereum-optimism/optimism/op-devstack/dsl/proofs" + "github.com/ethereum-optimism/optimism/op-devstack/presets" + "github.com/ethereum-optimism/optimism/op-devstack/sysgo" + "github.com/ethereum-optimism/optimism/op-service/eth" + "github.com/ethereum/go-ethereum/common" + + safety "github.com/ethereum-optimism/optimism/op-service/eth/safety" +) + +func TestProposerPublishesSuperRoot(gt *testing.T) { + t := devtest.ParallelT(gt) + system := presets.NewMinimal(t, + presets.WithDeployerOptions( + sysgo.WithJovianAtGenesis, + sysgo.WithDevFeatureEnabled(devfeatures.OptimismPortalInteropFlag), + sysgo.WithDevFeatureEnabled(devfeatures.SuperRootGamesMigrationFlag), + ), + ) + + game := system.DisputeGameFactory().WaitForGame() + game.VerifyGameType(gameTypes.SuperPermissionedGameType) + dsl.NewOpNodeSuperRoots(system.L2CL).AssertSuperRootAtTimestamp(game.L2SequenceNumber(), game.RootClaimValue()) +} + +func TestDisputeMonitorClassifiesOutputRoots(gt *testing.T) { + for _, testCase := range []struct { + name string + + agreedRoots int + disagreedRoots int + gameOptions []proofs.GameOpt + }{ + {name: "valid", agreedRoots: 1}, + {name: "invalid", disagreedRoots: 1, gameOptions: []proofs.GameOpt{proofs.WithRootClaim(common.HexToHash("0xdead"))}}, + } { + gt.Run(testCase.name, func(gt *testing.T) { + t := devtest.ParallelT(gt) + system := newOutputRootSystem(t) + proposer := system.FunderL1.NewFundedEOA(eth.OneEther) + gameOptions := append([]proofs.GameOpt{proofs.WithL2SequenceNumber(3)}, testCase.gameOptions...) + game := system.DisputeGameFactory().StartCannonKonaGame(proposer, gameOptions...) + game.WaitForGameStatus(gameTypes.GameStatusInProgress) + + monitor := system.StartDisputeMon() + monitor.VerifyState( + disputemon.GameCount(gameTypes.CannonKonaGameType, 1), + disputemon.FailedGames(0), + disputemon.AgreedRoots(testCase.agreedRoots), + disputemon.DisagreedRoots(testCase.disagreedRoots), + ) + }) + } +} + +func TestDisputeMonitorRejectsOutputRootNotSafeAtGameL1Head(gt *testing.T) { + t := devtest.ParallelT(gt) + system := newOutputRootSystem(t) + proposer := system.FunderL1.NewFundedEOA(eth.OneEther) + system.L2CL.Reached(safety.LocalSafe, 3, 30) + system.L2Batcher.Stop() + system.L2CL.Advanced(safety.LocalUnsafe, 3, 30) + blockNumber := system.L2CL.HeadBlockRef(safety.LocalUnsafe).Number + + game := system.DisputeGameFactory().StartCannonKonaGame(proposer, + proofs.WithL2SequenceNumber(blockNumber), + proofs.WithFutureProposal(), + ) + system.L2Batcher.Start() + system.L2CL.Reached(safety.LocalSafe, blockNumber, 30) + + monitor := system.StartDisputeMon() + monitor.VerifyState( + disputemon.GameCount(gameTypes.CannonKonaGameType, 1), + disputemon.FailedGames(0), + disputemon.AgreedRoots(0), + disputemon.DisagreedRoots(1), + disputemon.InvalidProposalObserved(game), + ) +} + +func newOutputRootSystem(t devtest.T) *presets.Minimal { + return presets.NewMinimalNoFaultProofs(t, + presets.WithDeployerOptions(sysgo.WithJovianAtGenesis), + presets.WithGameTypeAdded(gameTypes.CannonKonaGameType), + ) +} diff --git a/op-acceptance-tests/tests/safeheaddb_clsync/safeheaddb_test.go b/op-acceptance-tests/tests/safeheaddb_clsync/safeheaddb_test.go index 66f034d5e60..fac25ef3268 100644 --- a/op-acceptance-tests/tests/safeheaddb_clsync/safeheaddb_test.go +++ b/op-acceptance-tests/tests/safeheaddb_clsync/safeheaddb_test.go @@ -27,6 +27,7 @@ func TestPreserveDatabaseOnCLResync(gt *testing.T) { // assertions.go:387: sysgo.SkipOnOpReth(t, "not supported (peering issue)") sys := presets.NewSingleChainMultiNode(t, + presets.WithDeployerOptions(sysgo.WithJovianAtGenesis), presets.WithGlobalL2CLOption(sysgo.L2CLOptionFn(func(p devtest.T, _ sysgo.ComponentTarget, cfg *sysgo.L2CLConfig) { cfg.SequencerSyncMode = sync.CLSync cfg.VerifierSyncMode = sync.CLSync @@ -52,6 +53,7 @@ func TestPreserveDatabaseOnCLResync(gt *testing.T) { sys.L2ELB.Start() sys.L2CLB.Start() + sys.L2ELB.WaitForOnline() sys.L2ELB.PeerWith(sys.L2EL) sys.L2CLB.InSync(sys.L2CL, safety.LocalSafe, 30) diff --git a/op-acceptance-tests/tests/safeheaddb_elsync/safeheaddb_test.go b/op-acceptance-tests/tests/safeheaddb_elsync/safeheaddb_test.go index 9aa4a2114d2..9fb062347d1 100644 --- a/op-acceptance-tests/tests/safeheaddb_elsync/safeheaddb_test.go +++ b/op-acceptance-tests/tests/safeheaddb_elsync/safeheaddb_test.go @@ -17,6 +17,7 @@ func newSingleChainMultiNodeELSync(t devtest.T) *presets.SingleChainMultiNode { // uses a 4x CrossSafe budget (see singlechain_from_runtime.go), which is // what this test needs. return presets.NewSingleChainMultiNode(t, + presets.WithDeployerOptions(sysgo.WithJovianAtGenesis), presets.WithGlobalL2CLOption(sysgo.L2CLOptionFn(func(p devtest.T, _ sysgo.ComponentTarget, cfg *sysgo.L2CLConfig) { cfg.VerifierSyncMode = sync.ELSync cfg.SafeDBPath = p.TempDir() @@ -74,16 +75,6 @@ func TestTruncateDatabaseOnELResync(gt *testing.T) { func TestNotTruncateDatabaseOnRestartWithExistingDatabase(gt *testing.T) { t := devtest.ParallelT(gt) - // Example error with kona-node: - // - // assertions.go:387: ERROR[03-31|10:35:59.154] - // assertions.go:387: Error Trace: /Users/josh/repos/optimism/op-devstack/dsl/safedb.go:22 - // assertions.go:387: /Users/josh/repos/optimism/op-devstack/dsl/l2_cl.go:432 - // assertions.go:387: /Users/josh/repos/optimism/op-acceptance-tests/tests/safeheaddb_elsync/safeheaddb_test.go:74 - // assertions.go:387: Error: Expected value not to be nil. - // assertions.go:387: Test: TestNotTruncateDatabaseOnRestartWithExistingDatabase - // assertions.go:387: Messages: no safe head data available at L1 block 4 - sysgo.SkipOnKonaNode(t, "not supported") sys := newSingleChainMultiNodeELSync(t) dsl.CheckAll(t, @@ -95,7 +86,7 @@ func TestNotTruncateDatabaseOnRestartWithExistingDatabase(gt *testing.T) { preRestartSafeBlock := sys.L2CLB.SafeHeadDBFloor() sys.L2CLB.VerifySafeHeadDatabaseMatches(sys.L2CL, dsl.WithMinRequiredL2Block(preRestartSafeBlock)) - // Restart the verifier op-node, but not the EL so the existing chain data is not deleted. + // Keep the EL's chain data while restarting the verifier CL. sys.L2CLB.Stop() sys.L2CL.Advanced(safety.LocalSafe, 3, 30) diff --git a/rust/kona/crates/node/safedb/README.md b/rust/kona/crates/node/safedb/README.md index 3639948bd13..2e9b27ac88f 100644 --- a/rust/kona/crates/node/safedb/README.md +++ b/rust/kona/crates/node/safedb/README.md @@ -19,6 +19,19 @@ missed. See [`SafeDb::safe_head_updated`]. The layout carries no compatibility guarantee with any other implementation and is free to change. +## RPC error contract + +The node's `optimism_safeHeadAtL1Block` and pre-interop `superroot_atTimestamp` handlers +translate `SafeDB` failures into JSON-RPC errors with code `-32000`. A missing L1 lookup +record has the bare message `not found`. The reverse lookup used by `superroot_atTimestamp` +distinguishes `l1 at safe head not found` (not recorded yet) from +`l1 at safe head history unavailable` (before the available history), with an operation +prefix of `l1AtSafeHead@`. A disabled database has a message containing +`safe head database not enabled`, prefixed with the attempted operation. These conditions +remain distinct so clients can identify unavailable historical coverage without treating a +disabled database as an empty one. Other storage failures return an error with operation +context rather than a successful historical answer. + The crate exposes: - [`SafeDb`] — the database trait. From 301c29c0916132d5c9c5a0db31316bc1730fb65d Mon Sep 17 00:00:00 2001 From: Einar Rasmussen Date: Sun, 1 Nov 2026 13:03:22 -0600 Subject: [PATCH 2/3] ci,op-acceptance-tests,docs: harden op-geth SafeDB resync step and tidy consumer tests The op-geth SafeDB resync step now runs after the sharded suite so a resync failure cannot skip shard 0's share of it, restricts itself to the two cases that SkipOnOpReth, and fails when any of them skips or does not pass. The cannon_kona preset relies on the runtime's default SafeDB path, the dispute-monitor classification test drops a wait on a status new games already have, and the CL-sync resync comment describes CL sync rather than EL sync. The safeHeadAtL1Block and superroot_atTimestamp docs gain the invocation table and example style used by the other methods on the page. Co-Authored-By: Claude Fable 5.1 --- .circleci/continue/main.yml | 46 +++++++++++++------ .../node-operators/kona-node/rpc/rollup.mdx | 30 ++++++------ .../tests/proofs/cannon_kona/setup_test.go | 3 -- .../safedb_proof_consumers/consumers_test.go | 3 +- .../safeheaddb_clsync/safeheaddb_test.go | 4 +- 5 files changed, 50 insertions(+), 36 deletions(-) diff --git a/.circleci/continue/main.yml b/.circleci/continue/main.yml index d4959f2d223..446ab1198cd 100644 --- a/.circleci/continue/main.yml +++ b/.circleci/continue/main.yml @@ -2233,20 +2233,6 @@ jobs: # does not need a separate `go mod download`. - go-restore-cache: namespace: op-acceptance-tests - - run: - name: Run SafeDB resync tests with op-geth - command: | - if [ "${CIRCLE_NODE_INDEX:-0}" != "0" ]; then - exit 0 - fi - mkdir -p op-acceptance-tests/logs/safedb-op-geth op-acceptance-tests/results - DEVSTACK_L2EL_KIND=op-geth LOG_LEVEL=info gotestsum \ - --format testname \ - --jsonfile op-acceptance-tests/logs/safedb-op-geth/raw_go_events.log \ - --junitfile op-acceptance-tests/results/safedb-op-geth.xml \ - -- -count=1 -p=1 -parallel=1 -timeout=10m \ - ./op-acceptance-tests/tests/safeheaddb_elsync \ - ./op-acceptance-tests/tests/safeheaddb_clsync # Run the acceptance tests (if the devnet is running) - run: name: Run acceptance tests @@ -2270,6 +2256,38 @@ jobs: LOG_DIR=$(ls -td -- logs/* | head -1) cat "$LOG_DIR"/failed/*.log || true when: on_fail + # The two resync cases below SkipOnOpReth, so the op-reth run above never + # exercises them. They run here with op-geth, after the sharded suite so a + # resync failure cannot skip shard 0's share of it, and the step fails on + # any skip: buildL2Genesis skips op-geth on Karst chains, which would + # otherwise turn a fork-default change into silent loss of coverage. + - run: + name: Run SafeDB resync tests with op-geth + command: | + if [ "${CIRCLE_NODE_INDEX:-0}" != "0" ]; then + exit 0 + fi + RESYNC_TESTS="TestTruncateDatabaseOnELResync TestPreserveDatabaseOnCLResync" + EVENTS_FILE=op-acceptance-tests/logs/safedb-op-geth/raw_go_events.log + mkdir -p "$(dirname "$EVENTS_FILE")" op-acceptance-tests/results + DEVSTACK_L2EL_KIND=op-geth LOG_LEVEL=info gotestsum \ + --format testname \ + --jsonfile "$EVENTS_FILE" \ + --junitfile op-acceptance-tests/results/safedb-op-geth.xml \ + -- -count=1 -p=1 -parallel=1 -timeout=10m \ + -run "^($(echo "$RESYNC_TESTS" | tr ' ' '|'))$" \ + ./op-acceptance-tests/tests/safeheaddb_elsync \ + ./op-acceptance-tests/tests/safeheaddb_clsync + if grep -q '"Action":"skip","Package":"[^"]*","Test":"' "$EVENTS_FILE"; then + echo "SafeDB resync tests were skipped under op-geth" >&2 + exit 1 + fi + for test_name in $RESYNC_TESTS; do + if ! grep -q "\"Action\":\"pass\",\"Package\":\"[^\"]*\",\"Test\":\"$test_name\"" "$EVENTS_FILE"; then + echo "SafeDB resync test $test_name did not pass under op-geth" >&2 + exit 1 + fi + done # Save the module cache for future runs - go-save-cache: namespace: op-acceptance-tests diff --git a/docs/public-docs/node-operators/kona-node/rpc/rollup.mdx b/docs/public-docs/node-operators/kona-node/rpc/rollup.mdx index a568ae84079..9c7a3b3e654 100644 --- a/docs/public-docs/node-operators/kona-node/rpc/rollup.mdx +++ b/docs/public-docs/node-operators/kona-node/rpc/rollup.mdx @@ -203,6 +203,10 @@ Returns the rollup configuration parameters that define the rollup chain's behav Returns the most recent recorded L2 safe head whose derivation source L1 block is at or before the requested L1 block. Enable persistence with `--safedb.path` or `KONA_NODE_SAFEDB_PATH`. +| Client | Method invocation | +| ------ | ------------------------------------------------------------------ | +| RPC | `{"method": "optimism_safeHeadAtL1Block", "params": [l1BlockNumber]}` | + ### Parameters - `l1BlockNumber` (`string`): An L1 block number encoded as a hexadecimal quantity, such as `"0x64"`. Block tags are not supported. @@ -228,16 +232,11 @@ A disabled database is distinct from an enabled database with no matching record ### Example -```json -{"id":1,"jsonrpc":"2.0","method":"optimism_safeHeadAtL1Block","params":["0x64"]} -``` - -An illustrative response: - -```json +```js +// > {"jsonrpc":"2.0","id":1,"method":"optimism_safeHeadAtL1Block","params":["0x64"]} { - "id": 1, "jsonrpc": "2.0", + "id": 1, "result": { "l1Block": { "hash": "0x1111111111111111111111111111111111111111111111111111111111111111", @@ -375,6 +374,10 @@ Returns the software version of the Kona rollup node. Returns a pre-interop, single-chain super root and its L1 derivation requirements. This method uses the `superroot` namespace rather than the `optimism` namespace. SafeDB must be enabled and contain the relevant history for a non-genesis block that is locally safe. +| Client | Method invocation | +| ------ | ---------------------------------------------------------- | +| RPC | `{"method": "superroot_atTimestamp", "params": [timestamp]}` | + ### Parameters - `timestamp` (`string`): An L2 timestamp encoded as a hexadecimal quantity. The rollup configuration maps the timestamp to an L2 block number. @@ -413,16 +416,13 @@ SafeDB lookup messages for this method include the operation prefix `l1AtSafeHea ### Example -```json -{"id":1,"jsonrpc":"2.0","method":"superroot_atTimestamp","params":["0x6553f100"]} -``` - -An illustrative progress-only response when the requested block is not yet locally safe: +A progress-only response, returned while the requested block is not yet locally safe: -```json +```js +// > {"jsonrpc":"2.0","id":1,"method":"superroot_atTimestamp","params":["0x6553f100"]} { - "id": 1, "jsonrpc": "2.0", + "id": 1, "result": { "chain_ids": ["901"], "current_l1": { diff --git a/op-acceptance-tests/tests/proofs/cannon_kona/setup_test.go b/op-acceptance-tests/tests/proofs/cannon_kona/setup_test.go index 10893ceeab6..d049d5aecce 100644 --- a/op-acceptance-tests/tests/proofs/cannon_kona/setup_test.go +++ b/op-acceptance-tests/tests/proofs/cannon_kona/setup_test.go @@ -12,9 +12,6 @@ func cannonOpts() []presets.Option { presets.WithGameTypeAdded(gameTypes.CannonKonaGameType), presets.WithDeployerOptions(sysgo.WithJovianAtGenesis), presets.WithTimeTravelEnabled(), - presets.WithGlobalL2CLOption(sysgo.L2CLOptionFn(func(p devtest.T, _ sysgo.ComponentTarget, cfg *sysgo.L2CLConfig) { - cfg.SafeDBPath = p.TempDir() - })), } } diff --git a/op-acceptance-tests/tests/safedb_proof_consumers/consumers_test.go b/op-acceptance-tests/tests/safedb_proof_consumers/consumers_test.go index b6438daaa3c..cc8639db0c2 100644 --- a/op-acceptance-tests/tests/safedb_proof_consumers/consumers_test.go +++ b/op-acceptance-tests/tests/safedb_proof_consumers/consumers_test.go @@ -48,8 +48,7 @@ func TestDisputeMonitorClassifiesOutputRoots(gt *testing.T) { system := newOutputRootSystem(t) proposer := system.FunderL1.NewFundedEOA(eth.OneEther) gameOptions := append([]proofs.GameOpt{proofs.WithL2SequenceNumber(3)}, testCase.gameOptions...) - game := system.DisputeGameFactory().StartCannonKonaGame(proposer, gameOptions...) - game.WaitForGameStatus(gameTypes.GameStatusInProgress) + system.DisputeGameFactory().StartCannonKonaGame(proposer, gameOptions...) monitor := system.StartDisputeMon() monitor.VerifyState( diff --git a/op-acceptance-tests/tests/safeheaddb_clsync/safeheaddb_test.go b/op-acceptance-tests/tests/safeheaddb_clsync/safeheaddb_test.go index fac25ef3268..4a1598254ef 100644 --- a/op-acceptance-tests/tests/safeheaddb_clsync/safeheaddb_test.go +++ b/op-acceptance-tests/tests/safeheaddb_clsync/safeheaddb_test.go @@ -44,8 +44,8 @@ func TestPreserveDatabaseOnCLResync(gt *testing.T) { sys.L2CLB.VerifySafeHeadDatabaseMatches(sys.L2CL) // Stop the verifier node. Since the sysgo EL uses in-memory storage this also wipes its database. - // With the EL reset to genesis, when the CL restarts it will use EL sync to resync the chain rather than - // deriving it from L1. + // With the EL reset to genesis, the restarted CL stays in CL sync mode and re-derives the chain from L1, + // so unlike the EL sync case it must not truncate its safe head database. sys.L2ELB.Stop() sys.L2CLB.Stop() From 511ce62447ecc1b0ace986f8a22dae6c38816808 Mon Sep 17 00:00:00 2001 From: Einar Rasmussen Date: Sun, 1 Nov 2026 14:20:37 -0600 Subject: [PATCH 3/3] ci,op-acceptance-tests: run SafeDB op-geth resync tests in dedicated jobs The two resync cases SkipOnOpReth and ran as an extra step on shard 0 of each sharded acceptance job, which shard-tests.sh cannot balance. Move the step into a safedb-resync-test justfile recipe and run it in its own single-node op-node and kona-node jobs, both required by ci-gate. Co-Authored-By: Claude Fable 5.1 --- .circleci/continue/main.yml | 89 +++++++++++++++++++++++------------- op-acceptance-tests/justfile | 64 ++++++++++++++++++++++++++ 2 files changed, 120 insertions(+), 33 deletions(-) diff --git a/.circleci/continue/main.yml b/.circleci/continue/main.yml index 446ab1198cd..2627c1f2e10 100644 --- a/.circleci/continue/main.yml +++ b/.circleci/continue/main.yml @@ -2178,6 +2178,12 @@ jobs: leaves the justfile default in place" type: string default: "" + just_recipe: + description: "op-acceptance-tests justfile recipe to run: the sharded suite, + or the op-geth-only SafeDB resync cases that the op-reth suite skips" + type: enum + enum: [acceptance-test, safedb-resync-test] + default: acceptance-test docker: - image: <> resource_class: <> @@ -2242,7 +2248,7 @@ jobs: if [ -n "<>" ]; then export ACCEPTANCE_TEST_JOBS="<>" fi - LOG_LEVEL=info just acceptance-test + LOG_LEVEL=info just <> - run: name: Print results (summary) working_directory: op-acceptance-tests @@ -2256,38 +2262,6 @@ jobs: LOG_DIR=$(ls -td -- logs/* | head -1) cat "$LOG_DIR"/failed/*.log || true when: on_fail - # The two resync cases below SkipOnOpReth, so the op-reth run above never - # exercises them. They run here with op-geth, after the sharded suite so a - # resync failure cannot skip shard 0's share of it, and the step fails on - # any skip: buildL2Genesis skips op-geth on Karst chains, which would - # otherwise turn a fork-default change into silent loss of coverage. - - run: - name: Run SafeDB resync tests with op-geth - command: | - if [ "${CIRCLE_NODE_INDEX:-0}" != "0" ]; then - exit 0 - fi - RESYNC_TESTS="TestTruncateDatabaseOnELResync TestPreserveDatabaseOnCLResync" - EVENTS_FILE=op-acceptance-tests/logs/safedb-op-geth/raw_go_events.log - mkdir -p "$(dirname "$EVENTS_FILE")" op-acceptance-tests/results - DEVSTACK_L2EL_KIND=op-geth LOG_LEVEL=info gotestsum \ - --format testname \ - --jsonfile "$EVENTS_FILE" \ - --junitfile op-acceptance-tests/results/safedb-op-geth.xml \ - -- -count=1 -p=1 -parallel=1 -timeout=10m \ - -run "^($(echo "$RESYNC_TESTS" | tr ' ' '|'))$" \ - ./op-acceptance-tests/tests/safeheaddb_elsync \ - ./op-acceptance-tests/tests/safeheaddb_clsync - if grep -q '"Action":"skip","Package":"[^"]*","Test":"' "$EVENTS_FILE"; then - echo "SafeDB resync tests were skipped under op-geth" >&2 - exit 1 - fi - for test_name in $RESYNC_TESTS; do - if ! grep -q "\"Action\":\"pass\",\"Package\":\"[^\"]*\",\"Test\":\"$test_name\"" "$EVENTS_FILE"; then - echo "SafeDB resync test $test_name did not pass under op-geth" >&2 - exit 1 - fi - done # Save the module cache for future runs - go-save-cache: namespace: op-acceptance-tests @@ -2903,6 +2877,53 @@ workflows: - prep-go-modules # for the gitignored superchain-configs.zip op-acceptance-tests //go:embeds - prep-superchain + # SafeDB resync - op-node/op-geth and kona/op-geth. The two resync cases + # SkipOnOpReth, so the sharded op-reth jobs above never exercise them. They + # run one at a time, so a single node is enough and the sharded jobs stay + # balanced. + - op-acceptance-tests: + name: safedb-resync-opn-op-geth-<> + image: <> + matrix: + parameters: + l1_fork: *acceptance_l1_forks + l2_el_kind: op-geth + just_recipe: safedb-resync-test + resource_class: xlarge.gen2 + context: + - circleci-repo-readonly-authenticated-github-token + - slack + - discord + requires: + - contracts-bedrock-build + - cannon-prestate + - rust-binaries-for-sysgo + - go-binaries-for-sysgo + - prep-go-modules + # for the gitignored superchain-configs.zip op-acceptance-tests //go:embeds + - prep-superchain + - op-acceptance-tests: + name: safedb-resync-kona-op-geth-<> + image: <> + matrix: + parameters: + l1_fork: *acceptance_l1_forks + l2_cl_kind: kona-node + l2_el_kind: op-geth + just_recipe: safedb-resync-test + resource_class: xlarge.gen2 + context: + - circleci-repo-readonly-authenticated-github-token + - slack + - discord + requires: + - contracts-bedrock-build + - cannon-prestate + - rust-binaries-for-sysgo + - go-binaries-for-sysgo + - prep-go-modules + # for the gitignored superchain-configs.zip op-acceptance-tests //go:embeds + - prep-superchain # Gate job - single stable job used as GitHub required status check for develop. # Uses terminal requires so it always runs (even when deps fail), giving the # merge queue an immediate failure signal instead of a timeout. @@ -2919,6 +2940,8 @@ workflows: - go-actions-tests: terminal - memory-all-opn-op-reth-fusaka: terminal - memory-all-kona-op-reth-fusaka: terminal + - safedb-resync-opn-op-geth-fusaka: terminal + - safedb-resync-kona-op-geth-fusaka: terminal - kona-build-sp1-elfs: terminal # Go test/lint jobs previously fanned in via the bedrock-go-tests helper. - cannon-go-lint-and-test: terminal diff --git a/op-acceptance-tests/justfile b/op-acceptance-tests/justfile index e048d226f27..eb778cce3b5 100644 --- a/op-acceptance-tests/justfile +++ b/op-acceptance-tests/justfile @@ -165,5 +165,69 @@ acceptance-test: cp "$LOG_DIR/all.log" "$LOG_DIR/summary.log" exit "$TEST_STATUS" +# Run the SafeDB resync cases that SkipOnOpReth, with op-geth forced on +safedb-resync-test: + #!/usr/bin/env bash + set -euo pipefail + export DEVSTACK_L2EL_KIND=op-geth + echo -e "DEVNET: in-memory (op-geth SafeDB resync)\n" + + LOG_LEVEL="$(echo "${LOG_LEVEL:-info}" | grep -E '^(debug|info|warn|error)$' || echo 'info')" + TEST_TIMEOUT="${ACCEPTANCE_TEST_TIMEOUT:-10m}" + echo "LOG_LEVEL: $LOG_LEVEL" + echo "PACKAGE TIMEOUT: $TEST_TIMEOUT" + + cd {{REPO_ROOT}} + if ! command -v gotestsum >/dev/null; then + echo "error: gotestsum is required for acceptance-test runs." >&2 + exit 1 + fi + + RESYNC_TESTS=(TestTruncateDatabaseOnELResync TestPreserveDatabaseOnCLResync) + RESYNC_PACKAGES=( + ./op-acceptance-tests/tests/safeheaddb_clsync + ./op-acceptance-tests/tests/safeheaddb_elsync + ) + RUN_FLAG="-run=^($(IFS='|'; echo "${RESYNC_TESTS[*]}"))$" + + LOG_ROOT="{{REPO_ROOT}}/op-acceptance-tests/logs" + RESULTS_DIR="{{REPO_ROOT}}/op-acceptance-tests/results" + LOG_DIR="$LOG_ROOT/safedb-resync-$(date -u +%Y%m%d-%H%M%S)" + EVENTS_FILE="$LOG_DIR/raw_go_events.log" + mkdir -p "$LOG_DIR/failed" "$RESULTS_DIR" + + set +e + LOG_LEVEL="${LOG_LEVEL}" {{REPO_ROOT}}/ops/scripts/gotestsum-split.sh \ + --format testname \ + --junitfile "$RESULTS_DIR/safedb-resync.xml" \ + --jsonfile "$EVENTS_FILE" \ + -- \ + -count=1 \ + -p 1 \ + -parallel 1 \ + -timeout "${TEST_TIMEOUT}" \ + "$RUN_FLAG" \ + "${RESYNC_PACKAGES[@]}" \ + 2>&1 | tee "$LOG_DIR/all.log" + TEST_STATUS=${PIPESTATUS[0]} + set -e + + cp "$LOG_DIR/all.log" "$LOG_DIR/summary.log" + if [ "$TEST_STATUS" -ne 0 ]; then + exit "$TEST_STATUS" + fi + # buildL2Genesis skips op-geth on Karst chains, which would otherwise turn a + # fork-default change into silent loss of coverage. + if grep -q '"Action":"skip","Package":"[^"]*","Test":"' "$EVENTS_FILE"; then + echo "SafeDB resync tests were skipped under op-geth" >&2 + exit 1 + fi + for test_name in "${RESYNC_TESTS[@]}"; do + if ! grep -q "\"Action\":\"pass\",\"Package\":\"[^\"]*\",\"Test\":\"$test_name\"" "$EVENTS_FILE"; then + echo "SafeDB resync test $test_name did not pass under op-geth" >&2 + exit 1 + fi + done + clean: rm -rf tests/interop/loadtest/artifacts