JSON-RPC API

Standard Ethereum RPC

Standard Ethereum JSON-RPC methods are supported on Lighter EVM. The following namespaces are available:

eth — standard Ethereum methods (eth_blockNumber, eth_getBalance, eth_sendRawTransaction, etc.)
net — network info (net_version, net_listening, etc.)
web3 — utility methods (web3_clientVersion, web3_sha3)
debug — debug methods (debug_traceTransaction, debug_traceCall, etc.)
trace — trace methods (trace_transaction, trace_block, etc.)

These methods are available on your configured Lighter EVM RPC endpoint.

L1 data fee fields

eth_getTransactionReceipt responses include three additional fields reporting the transaction's L1 data fee:

l1GasUsed — pubdata bytes metered for the transaction.
l1GasPrice — price per pubdata byte, in wei.
l1Fee — l1GasUsed * l1GasPrice, in wei.

Fee-exempt exogenous transactions report their metered bytes in l1GasUsed with l1GasPrice = 0 and l1Fee = 0.

Lighter RPC

Lighter EVM additionally exposes a lighter JSON-RPC namespace with Lighter-specific RPC methods.

`lighter_syncStatus`

Returns the current sync status of the sequencer.

Response:

{
  "headL1":      { "number": 0, "hash": "0x…", "parentHash": "0x…", "timestamp": 0 },
  "safeL1":      { "number": 0, "hash": "0x…", "parentHash": "0x…", "timestamp": 0 },
  "finalizedL1": { "number": 0, "hash": "0x…", "parentHash": "0x…", "timestamp": 0 },
  "unsafeL2":    { "number": 0, "hash": "0x…", "parentHash": "0x…", "timestamp": 0, "parentCoreBlock": 0 },
  "safeL2":      { "number": 0, "hash": "0x…", "parentHash": "0x…", "timestamp": 0, "parentCoreBlock": 0 },
  "finalizedL2": { "number": 0, "hash": "0x…", "parentHash": "0x…", "timestamp": 0, "parentCoreBlock": 0 },
  "latestCommittedBatch": { "batchNumber": 0, "upToL2BlockNumber": 0, "l1CommitBlockNumber": 0 },
  "latestVerifiedBatch":  { "batchNumber": 0, "upToL2BlockNumber": 0, "l1VerificationBlockNumber": 0 },
  "latestExecutedBatch":  { "batchNumber": 0, "upToL2BlockNumber": 0, "l1BatchExecutionBlockNumber": 0 }
}

All fields are nullable — they return null until the sequencer has observed the corresponding state. L2 block references include a parentCoreBlock field indicating the Core block height that the EVM block's state is derived from.

`lighter_getWithdrawalProof`

Returns the Merkle proof and the claim arguments for a withdrawal initiated on Lighter EVM, once the batch containing it has been executed on L1. See L1 and EVM for the full flow.

Parameters:

txHash — hash of the Lighter EVM transaction that emitted the WithdrawalInitiated event.
index — zero-based position of the WithdrawalInitiated event among those emitted by the transaction (0 for a transaction with a single withdrawal).

Response:

{
  "batchNumber": 1287,
  "proof": ["0x…", "0x…"],
  "isLeft": "0x2",
  "l1CallHash": "0x…",
  "root": "0x…",
  "l2Sender": "0x…",
  "to": "0x…",
  "value": "0x2386f26fc10000",
  "msgNonce": "0x1c",
  "data": "0x"
}

Errors:

The method returns a JSON-RPC error with code -32000 and a descriptive message when:

The batch containing the transaction has not yet finalized on L1.
The transaction is unknown to the node, for example because a follower node has not imported its block yet.
index is greater than or equal to the number of WithdrawalInitiated events the transaction emitted.