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 hashoutputRoot(string): The output root hashblockRef(L2BlockInfo): Reference to the L2 blockwithdrawalStorageRoot(string): The withdrawal storage rootstateRoot(string): The state rootsyncStatus(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 rollupblockTime(number): The block time of the L2 in secondsmaxSequencerDrift(number): Maximum sequencer drift in secondsseqWindowSize(number): The sequencer window sizechannelTimeout(number): Number of L1 blocks between channel open/closegraniteChannelTimeout(number): Channel timeout after Granite hardforkl1ChainId(number): The L1 chain IDl2ChainId(number): The L2 chain IDbatchInboxAddress(string): L1 address where batches are sentdepositContractAddress(string): L1 address for depositsl1SystemConfigAddress(string): L1 address for system configprotocolVersionsAddress(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, withhashandnumberfields.safeHead: The corresponding L2 safe head, withhashandnumberfields.
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 atcurrent_l1_finalized(BlockInfo): The current L1 finalized block (legacy/deprecated)head_l1(BlockInfo): The L1 head block referencesafe_l1(BlockInfo): The L1 safe head block referencefinalized_l1(BlockInfo): The finalized L1 block referenceunsafe_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 referencelocal_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, withhashandnumberfields. Every L1 block strictly below this cursor has been fully processed. Consumers checking an L1 scopeXmust wait forcurrent_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 containsoutput,output_root, and the SafeDB-backedrequired_l1block.safe_timestamp: The safe L2 head timestamp, as a JSON integer.
data contains:
super: The version 1 preimage, containingchainsand a hexadecimaltimestamp. Each chain entry containsChainIDas a decimal string andOutputas 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’srequired_l1.
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
-32000with a message containingl1 at safe head not found. - History before the available range returns
-32000with a message containingl1 at safe head history unavailable. Waiting for more derivation does not restore that missing historical range. - A disabled database returns
-32000with a message containingsafe head database not enabledwhen a non-genesis historical lookup is required. - If history changes repeatedly while the output is read, the request returns
-32000withsafe head history changed during query; retry. - Database and engine read failures return RPC errors rather than an unverified root.
l1AtSafeHead@<blockNumber>. They differ from the bare not found message returned by optimism_safeHeadAtL1Block.