JSON-RPC API
Pre-bedrock (current version)
Optimism shares the same JSON-RPC API (opens new window) as Ethereum. Some custom methods have been introduced to simplify certain Optimism specific interactions.
# Custom JSON-RPC Methods
# eth_getBlockRange
Like eth_getBlockByNumber
but accepts a range of block numbers instead of just a single block.
Parameters
QUANTITY|TAG
- integer of the starting block number for the range, or the string"earliest"
,"latest"
or"pending"
, as in the default block parameter (opens new window).QUANTITY|TAG
- integer of the ending block number for the range, or the string"earliest"
,"latest"
or"pending"
, as in the default block parameter (opens new window).BOOLEAN
- Iftrue
it returns the full transaction objects, iffalse
only the hashes of the transactions.
Returns
An array of block
objects.
See eth_getBlockByHash
(opens new window) for the structure of a block
object.
Example
// Request
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getBlockRange","params":["0x1", "0x2", false],"id":1}' <node url>
// Result
{
"jsonrpc":"2.0",
"id":1,
"result":[
{
"difficulty":"0x2",
"extraData":"0xd98301090a846765746889676f312e31352e3133856c696e75780000000000009c3827892825f0825a7e329b6913b84c9e4f89168350aff0939e0e6609629f2e7f07f2aeb62acbf4b16a739cab68866f4880ea406583a4b28a59d4f55dc2314e00",
"gasLimit":"0xe4e1c0",
"gasUsed":"0x3183d",
"hash":"0xbee7192e575af30420cae0c7776304ac196077ee72b048970549e4f08e875453",
"logsBloom":"0x00000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000400000000000100000000000000200000000002000000000000001000000000000000000004000000000000000000000000000040000400000100400000000000000100000000000000000000000000000020000000000000000000000000000000000000000000000001000000000000000000000100000000000000000000000000000000000000000000000000000000000000088000000080000000000010000000000000000000000000000800008000120000000000000000000000000000000002000",
"miner":"0x0000000000000000000000000000000000000000",
"mixHash":"0x0000000000000000000000000000000000000000000000000000000000000000",
"nonce":"0x0000000000000000",
"number":"0x1",
"parentHash":"0x7ca38a1916c42007829c55e69d3e9a73265554b586a499015373241b8a3fa48b",
"receiptsRoot":"0xf4c97b1186b690ad3318f907c0cdaf46f4598f27f711a5609064b2690a767287",
"sha3Uncles":"0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
"size":"0x30c",
"stateRoot":"0xd3ac40854cd2ac17d8effeae6065cea990b04be714f7061544973feeb2f1c95f",
"timestamp":"0x618d8837",
"totalDifficulty":"0x3",
"transactions":["0x5e77a04531c7c107af1882d76cbff9486d0a9aa53701c30888509d4f5f2b003a"],
"transactionsRoot":"0x19f5efd0d94386e72fcb3f296f1cb2936d017c37487982f76f09c591129f561f",
"uncles":[]
},
{
"difficulty":"0x2",
"extraData":"0xd98301090a846765746889676f312e31352e3133856c696e757800000000000064a82cb66c7810b9619e7f14ab65c769a828b1616974987c530684eb3870b65e5b2400c1b61c6d340beef8c8e99127ac0de50e479d21f0833a5e2910fe64b41801",
"gasLimit":"0xe4e1c0",
"gasUsed":"0x1c60d",
"hash":"0x45fd6ce41bb8ebb2bccdaa92dd1619e287704cb07722039901a7eba63dea1d13",
"logsBloom":"0x00080000000200000000000000000008000000000000000000000100008000000000000000000000000000000000000000000000000000000000400000000000100000000000000000000000020000000000000000000000000000000000004000000000000000000000000000000000400000000400000000000000100000000000000000000000000000020000000000000000000000000000000000000000100000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000008400000000000000000010000000000000000020000000020000000000000000000000000000000000000000000002000",
"miner":"0x0000000000000000000000000000000000000000",
"mixHash":"0x0000000000000000000000000000000000000000000000000000000000000000",
"nonce":"0x0000000000000000",
"number":"0x2",
"parentHash":"0xbee7192e575af30420cae0c7776304ac196077ee72b048970549e4f08e875453",
"receiptsRoot":"0x2057c8fb79c0f294062c1436aa56741134dc46d228a4f874929f8b791a7007a4",
"sha3Uncles":"0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
"size":"0x30c",
"stateRoot":"0x87026f3a614318ae24bcef6bc8f7564479afbbbe2b1fb189bc133a5de5a2b0f8",
"timestamp":"0x618d8837",
"totalDifficulty":"0x5",
"transactions":["0xaf6ed8a6864d44989adc47c84f6fe0aeb1819817505c42cde6cbbcd5e14dd317"],
"transactionsRoot":"0xa39c4d0d2397f8fcb1683ba833d4ab935cd2f4c5ca6f56a7d9a45b9904ea1c69",
"uncles":[]
}
]
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
# rollup_getInfo
Returns useful L2-specific information about the current node.
Parameters
None
Returns
Object
mode
:STRING
-"sequencer"
or"verifier"
depending on the node's mode of operationsyncing
:BOOLEAN
-true
if the node is currently syncing,false
otherwiseethContext
:OBJECT
blockNumber
:QUANTITY
- Block number of the latest known L1 blocktimestamp
:QUANTITY
- Timestamp of the latest known L1 block
rollupContext
:OBJECT
queueIndex
:QUANTITY
- Index within the CTC of the last L1 to L2 message ingestedindex
:QUANTITY
- Index of the last L2 tx processedverifiedIndex
:QUANTITY
- Index of the last tx that was ingested from a batch that was posted to L1
Example
// Request
curl -X POST --data '{"jsonrpc":"2.0","method":"rollup_getInfo","params":[],"id":1}' <node url>
// Result
{
"jsonrpc":"2.0",
"id":1,
"result":{
"mode":"verifier",
"syncing":false,
"ethContext":{
"blockNumber":13679735,
"timestamp":1637791660
},
"rollupContext":{
"index":430948,
"queueIndex":12481,
"verifiedIndex":0
}
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# rollup_gasPrices
Returns the L1 and L2 gas prices that are being used by the Sequencer to calculate fees.
Parameters
None
Returns
Object
l1GasPrice
:QUANTITY
- L1 gas price in wei that the Sequencer will use to estimate the L1 portion of fees (calldata costs).l2GasPrice
:QUANTITY
- L2 gas price in wei that the Sequencer will use to estimate the L2 portion of fees (execution costs).
Example
// Request
curl -X POST --data '{"jsonrpc":"2.0","method":"rollup_gasPrices","params":[],"id":1}' <node url>
// Result
{
"jsonrpc":"2.0",
"id":1,
"result":{
"l1GasPrice":"0x237aa50984",
"l2GasPrice":"0xf4240"
}
}
2
3
4
5
6
7
8
9
10
11
12
# Unsupported JSON-RPC methods
# eth_getAccounts
This method is used to retrieve a list of addresses owned by a user.
Optimism nodes do not expose internal wallets for security reasons and therefore block the eth_getAccounts
method.
You should use external wallet software as an alternative.
# eth_sendTransaction
Optimism nodes also block the eth_sendTransaction
method for the same reasons as eth_getAccounts
.
You should use external wallet software as an alternative.
Please note that this is not the same as the eth_sendRawTransaction
method, which accepts a signed transaction as an input.
eth_sendRawTransaction
is supported by Optimism.
Bedrock (coming Q1 2023)
There are several bedrock components with an RPC API:
# Rollup node (op-node)
Rollup node (opens new window) refers to the component in the protocol specifications. The Optimism implementation is called op-node.
The op-node
component implements several RPC methods:
# optimism_outputAtBlock
Get the output root at a specific block. This method is documented in the specifications (opens new window).
curl -X POST -H "Content-Type: application/json" --data \
'{"jsonrpc":"2.0","method":"optimism_outputAtBlock","params":["latest"],"id":1}' \
http://localhost:9545
2
3
Sample output:
{
"jsonrpc":"2.0",
"id":1,
"result":[
"0x0000000000000000000000000000000000000000000000000000000000000000",
"0xabe711e34c1387c8c56d0def8ce77e454d6a0bfd26cef2396626202238442421"
]
}
2
3
4
5
6
7
8
# optimism_syncStatus
Get the synchronization status.
curl -X POST -H "Content-Type: application/json" --data \
'{"jsonrpc":"2.0","method":"optimism_syncStatus","params":[],"id":1}' \
http://localhost:9545
2
3
Sample output:
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"current_l1": {
"hash": "0x5adcfcbd1c2fcf9e06bfdaa8414a4586f84e11f487396abca940299eb0ed2da5",
"number": 7569281,
"parentHash": "0xfd022ca8a8c4e0f3bfd67081c18551840ea0717cc01d9a94601e1e41e92616d3",
"timestamp": 1662862860
},
"head_l1": {
"hash": "0x5c12fde5ea79aefe4b52c0c8cc0e0eb33a2ccb423cb3cd9c9132e18ad42e89b6",
"number": 8042823,
"parentHash": "0x74818f8ecaa932431bf9523e929dcfa11ab382c752529d8271a24810884a2551",
"timestamp": 1669735356
},
"safe_l1": {
"hash": "0x0000000000000000000000000000000000000000000000000000000000000000",
"number": 0,
"parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
"timestamp": 0
},
"finalized_l1": {
"hash": "0x0000000000000000000000000000000000000000000000000000000000000000",
"number": 0,
"parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
"timestamp": 0
},
"unsafe_l2": {
"hash": "0x1cad05886ec0e2cda728674e00eadcbb9245ff34c0bfd86c866673a615c1c43a",
"number": 1752,
"parentHash": "0x0115dbbd26aaf9563d7e3cad65bad41926d94b2643ccb080f71e394c2c3d62a3",
"timestamp": 1662861300,
"l1origin": {
"hash": "0x43fe1601041056e9a2a5dabaa20715518ae0058abf67a69f5ebdd53b1f6ff02f",
"number": 7569162
},
"sequenceNumber": 0
},
"safe_l2": {
"hash": "0x1cad05886ec0e2cda728674e00eadcbb9245ff34c0bfd86c866673a615c1c43a",
"number": 1752,
"parentHash": "0x0115dbbd26aaf9563d7e3cad65bad41926d94b2643ccb080f71e394c2c3d62a3",
"timestamp": 1662861300,
"l1origin": {
"hash": "0x43fe1601041056e9a2a5dabaa20715518ae0058abf67a69f5ebdd53b1f6ff02f",
"number": 7569162
},
"sequenceNumber": 0
},
"finalized_l2": {
"hash": "0x6758307d692d4f2f6650acd3762674749a0c1cc2530b9b481845d0f8ee1bd456",
"number": 0,
"parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
"timestamp": 1662857796,
"l1origin": {
"hash": "0xb0bbb79a00fb8485185b1bedfac386812d662e1cddba77b67a26e1ed9ba8f0ec",
"number": 7568910
},
"sequenceNumber": 0
}
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
# optimism_rollupConfig
Get the rollup configuration parameters.
curl -X POST -H "Content-Type: application/json" --data \
'{"jsonrpc":"2.0","method":"optimism_rollupConfig","params":[],"id":1}' \
http://localhost:9545
2
3
Sample output:
{
"jsonrpc":"2.0",
"id":1,
"result":{
"genesis":{
"l1":{
"hash":"0xb0bbb79a00fb8485185b1bedfac386812d662e1cddba77b67a26e1ed9ba8f0ec",
"number":7568910
},
"l2":{
"hash":"0x6758307d692d4f2f6650acd3762674749a0c1cc2530b9b481845d0f8ee1bd456",
"number":0
},
"l2_time":1662857796
},
"block_time":2,
"max_sequencer_drift":120,
"seq_window_size":120,
"channel_timeout":30,
"l1_chain_id":5,
"l2_chain_id":28528,
"p2p_sequencer_address":"0x59dc8e68a80833cc8a9592d532fed42374c8b5dc",
"fee_recipient_address":"0xdffc6a1c238ff9504b055ad7efeee0148f2d62bd",
"batch_inbox_address":"0xfeb2acb903f95fb5f5497157c0727a7d16e3fd16",
"batch_sender_address":"0x4ff79526ea1d492a3db2aa210d7318ff13f2012c",
"deposit_contract_address":"0xa581ca3353db73115c4625ffc7adf5db379434a8"
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
# optimism_version
Get the software version.
curl -X POST -H "Content-Type: application/json" \
'--data '{"jsonrpc":"2.0","method":"optimism_version","params":[],"id":1}' \
http://localhost:9545
2
3
Sample output:
{
"jsonrpc":"2.0",
"id":1,
"result":"v0.0.0-"
}
2
3
4
5
# Peer to peer synchronization
Optionally, the rollup node can provide peer to peer synchronization (opens new window) to provide pending L2 blocks to other rollup nodes.
# Execution engine (op-geth)
Execution engine (opens new window) refers to the component in the protocol specifications. The Optimism implementation is called op-geth.
The execution engine's RPC interface is identical to the upstream Geth RPC interface (opens new window). This includes the ability to provide snap sync (opens new window) functionality to other execution engines.
The responses are nearly identical too, except we also include the L1 gas usage and price information.
# Daisy chain
The daisy chain is a proxy that distributes requests either to the execution engine (if related to post-Bedrock blocks), or the legacy geth (if related to blocks prior to bedrock). It accepts the interface used by L1 execution engines (opens new window).
# Legacy geth
The legacy geth provides information about the blockchain prior to Bedrock.
It implements the read-only methods of the interface used by L1 execution engines (opens new window).
It does not implement eth_sendTransaction
and eth_sendRawTransaction
, because they don't make sense in a read-only copy.