Skip to content
262 changes: 190 additions & 72 deletions docs/public-docs/node-operators/kona-node/rpc/rollup.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -120,6 +120,136 @@ 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`
Comment thread
einar-oplabs marked this conversation as resolved.
Resolved

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.

### 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

```js
// > {"jsonrpc":"2.0","id":1,"method":"optimism_safeHeadAtL1Block","params":["0x64"]}
{
"jsonrpc": "2.0",
"id": 1,
"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.
Expand Down Expand Up @@ -217,104 +347,92 @@ 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": []}` |
| 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.

### 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@<blockNumber>`. They differ from the bare `not found` message returned by `optimism_safeHeadAtL1Block`.

### Example

A progress-only response, returned while the requested block is not yet locally safe:

```js
// > {"jsonrpc":"2.0","id":1,"method":"optimism_version","params":[]}
// > {"jsonrpc":"2.0","id":1,"method":"superroot_atTimestamp","params":["0x6553f100"]}
{
"jsonrpc": "2.0",
"id": 1,
"result": "0.1.0"
"result": {
"chain_ids": ["901"],
"current_l1": {
"hash": "0x1111111111111111111111111111111111111111111111111111111111111111",
"number": 100
},
"finalized_timestamp": 1699999900,
"local_safe_timestamp": 1699999998,
"optimistic_at_timestamp": {},
"safe_timestamp": 1699999998
}
}
```
Original file line number Diff line number Diff line change
Expand Up @@ -11,9 +11,7 @@ func cannonOpts() []presets.Option {
return []presets.Option{
presets.WithGameTypeAdded(gameTypes.CannonKonaGameType),
presets.WithDeployerOptions(sysgo.WithJovianAtGenesis),
presets.WithGlobalL2CLOption(sysgo.L2CLOptionFn(func(p devtest.T, _ sysgo.ComponentTarget, cfg *sysgo.L2CLConfig) {
cfg.SafeDBPath = p.TempDir()
})),
presets.WithTimeTravelEnabled(),
}
}

Expand Down
18 changes: 4 additions & 14 deletions op-acceptance-tests/tests/proofs/cannon_kona/step_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -2,30 +2,18 @@ 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"
)

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)
Expand All @@ -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)
}
Loading
Loading