Skip to content
Closed
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
57 changes: 56 additions & 1 deletion .circleci/continue/main.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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: <<parameters.image>>
resource_class: <<parameters.resource_class>>
Expand Down Expand Up @@ -2242,7 +2248,7 @@ jobs:
if [ -n "<<parameters.acceptance_test_jobs>>" ]; then
export ACCEPTANCE_TEST_JOBS="<<parameters.acceptance_test_jobs>>"
fi
LOG_LEVEL=info just acceptance-test
LOG_LEVEL=info just <<parameters.just_recipe>>
- run:
name: Print results (summary)
working_directory: op-acceptance-tests
Expand Down Expand Up @@ -2871,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-<<matrix.l1_fork>>
image: <<pipeline.parameters.c-rust_base_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-<<matrix.l1_fork>>
image: <<pipeline.parameters.c-rust_base_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.
Expand All @@ -2887,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
Expand Down
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`

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
}
}
```
Loading
Loading