Skip to main content
The optimism API provides methods for interacting with Kona’s rollup state and configuration.

optimism_outputAtBlock

Returns the output root at a specific block number, including the L2 block reference, withdrawal storage root, state root, and sync status.

Parameters

  • blockNumber (BlockNumberOrTag): The block number to get the output for. Can be a number, “latest”, “earliest”, “pending”, “safe”, or “finalized”.

Returns

OutputResponse - An object containing:
  • version (string): The output version hash
  • outputRoot (string): The output root hash
  • blockRef (L2BlockInfo): Reference to the L2 block
  • withdrawalStorageRoot (string): The withdrawal storage root
  • stateRoot (string): The state root
  • syncStatus (SyncStatus): The current sync status of the node

Example

optimism_rollupConfig

Returns the rollup configuration parameters that define the rollup chain’s behavior and properties.

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

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

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

optimism_syncStatus

Returns the current synchronization status of the rollup node, including information about L1 and L2 block states.

Returns

SyncStatus - An object containing detailed sync information:
  • current_l1 (BlockInfo): The current L1 block that derivation is idled at
  • current_l1_finalized (BlockInfo): The current L1 finalized block (legacy/deprecated)
  • head_l1 (BlockInfo): The L1 head block reference
  • safe_l1 (BlockInfo): The L1 safe head block reference
  • finalized_l1 (BlockInfo): The finalized L1 block reference
  • unsafe_l2 (L2BlockInfo): The unsafe L2 block reference (absolute tip)
  • safe_l2 (L2BlockInfo): The safe L2 block reference (derived from L1)
  • finalized_l2 (L2BlockInfo): The finalized L2 block reference
  • local_safe_l2 (L2BlockInfo): Local safe L2 block derived from L1, not yet cross-verified

Example

optimism_version

Returns the software version of the Kona rollup node.

Returns

string - The version string of the Kona software (e.g., “0.1.0”)

Example

superroot_atTimestamp

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.

Parameters

  • timestamp (string): An L2 timestamp encoded as a hexadecimal quantity. The rollup configuration maps the timestamp to an L2 block number.

Returns

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: