Optimism Documentation

op-geth is the execution client for the OP Stack, based on Go Ethereum (Geth). It provides the execution layer with Ethereum-equivalent functionality plus OP Stack-specific enhancements for L2 gas accounting and receipts.

Overview

The op-geth execution client implements the standard Ethereum JSON-RPC API with minimal modifications. This means you can use familiar Ethereum tools and libraries with OP Stack chains.

The execution engine’s RPC interface is identical to the upstream Geth RPC interface. The key difference is that transaction receipts include additional L1 gas usage and pricing information specific to L2 operations.

Key Differences from Ethereum

While op-geth maintains compatibility with Ethereum’s JSON-RPC API, there are important differences:

Transaction Receipts

Transaction receipts in op-geth include additional L1 data fee information:

l1GasUsed: Amount of L1 gas used for L1 data availability
l1GasPrice: L1 gas price at the time of transaction execution
l1Fee: Total L1 data fee charged (in wei)
l1FeeScalar: Scalar value used in L1 fee calculation

This additional information helps you understand the full cost of L2 transactions, which include both L2 execution costs and L1 data availability costs.

Gas Price Calculation

For L2 gas prices, use the standard eth_gasPrice method. For L1 gas prices and fee estimation, use the GasPriceOracle predeployed contract or the Optimism SDK.

Standard JSON-RPC Methods

op-geth supports all standard Ethereum JSON-RPC methods. Below are commonly used methods with examples.

eth_blockNumber

Returns the number of the most recent block.

curl
cast

curl -X POST -H "Content-Type: application/json" --data \
  '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \
  http://localhost:8545

cast block-number --rpc-url http://localhost:8545

Sample success output:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x4b7"
}

eth_getBalance

Returns the balance of the account at the given address.

curl
cast

curl -X POST -H "Content-Type: application/json" --data \
  '{"jsonrpc":"2.0","method":"eth_getBalance","params":["0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb","latest"],"id":1}' \
  http://localhost:8545

cast balance 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb --rpc-url http://localhost:8545

Sample success output:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x0234c8a3397aab58"
}

eth_getTransactionByHash

Returns information about a transaction by transaction hash.

curl
cast

curl -X POST -H "Content-Type: application/json" --data \
  '{"jsonrpc":"2.0","method":"eth_getTransactionByHash","params":["0x88df016429689c079f3b2f6ad39fa052532c56795b733da78a91ebe6a713944b"],"id":1}' \
  http://localhost:8545

cast tx 0x88df016429689c079f3b2f6ad39fa052532c56795b733da78a91ebe6a713944b --rpc-url http://localhost:8545

Sample success output:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "blockHash": "0x1d59ff54b1eb26b013ce3cb5fc9dab3705b415a67127a003c3e61eb445bb8df2",
    "blockNumber": "0x5daf3b",
    "from": "0xa7d9ddbe1f17865597fbd27ec712455208b6b76d",
    "gas": "0xc350",
    "gasPrice": "0x4a817c800",
    "hash": "0x88df016429689c079f3b2f6ad39fa052532c56795b733da78a91ebe6a713944b",
    "input": "0x68656c6c6f21",
    "nonce": "0x15",
    "to": "0xf02c1c8e6114b1dbe8937a39260b5b0a374432bb",
    "transactionIndex": "0x41",
    "value": "0xf3dbb76162000",
    "type": "0x0",
    "chainId": "0xa4b1",
    "v": "0x1546d71",
    "r": "0x8a8eafb3cf4c5c4c5c5e5c5e5c5e5c5e5c5e5c5e5c5e5c5e5c5e5c5e5c5e5c5e",
    "s": "0x8a8eafb3cf4c5c4c5c5e5c5e5c5e5c5e5c5e5c5e5c5e5c5e5c5e5c5e5c5e5c5e"
  }
}

eth_getTransactionReceipt

Returns the receipt of a transaction by transaction hash. This method includes OP Stack-specific L1 fee fields.

curl
cast

curl -X POST -H "Content-Type: application/json" --data \
  '{"jsonrpc":"2.0","method":"eth_getTransactionReceipt","params":["0x88df016429689c079f3b2f6ad39fa052532c56795b733da78a91ebe6a713944b"],"id":1}' \
  http://localhost:8545

cast receipt 0x88df016429689c079f3b2f6ad39fa052532c56795b733da78a91ebe6a713944b --rpc-url http://localhost:8545

Sample success output:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "blockHash": "0x1d59ff54b1eb26b013ce3cb5fc9dab3705b415a67127a003c3e61eb445bb8df2",
    "blockNumber": "0x5daf3b",
    "contractAddress": null,
    "cumulativeGasUsed": "0x33bc",
    "effectiveGasPrice": "0x4a817c800",
    "from": "0xa7d9ddbe1f17865597fbd27ec712455208b6b76d",
    "gasUsed": "0x4dc",
    "logs": [],
    "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
    "status": "0x1",
    "to": "0xf02c1c8e6114b1dbe8937a39260b5b0a374432bb",
    "transactionHash": "0x88df016429689c079f3b2f6ad39fa052532c56795b733da78a91ebe6a713944b",
    "transactionIndex": "0x41",
    "type": "0x0",
    "l1GasUsed": "0x5e0",
    "l1GasPrice": "0x3b9aca00",
    "l1Fee": "0x16a3f5b9c0",
    "l1FeeScalar": "1.0"
  }
}

Notice the additional fields at the end of the receipt: l1GasUsed, l1GasPrice, l1Fee, and l1FeeScalar. These fields are specific to OP Stack chains and provide information about L1 data availability costs.

eth_call

Executes a new message call immediately without creating a transaction on the blockchain.

curl
cast

curl -X POST -H "Content-Type: application/json" --data \
  '{"jsonrpc":"2.0","method":"eth_call","params":[{"to":"0x420000000000000000000000000000000000000F","data":"0x519b4bd3"},"latest"],"id":1}' \
  http://localhost:8545

cast call 0x420000000000000000000000000000000000000F "l1BaseFee()" --rpc-url http://localhost:8545

Sample success output:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x00000000000000000000000000000000000000000000000000000003b9aca00"
}

eth_estimateGas

Generates and returns an estimate of gas needed for a transaction to complete.

curl
cast

curl -X POST -H "Content-Type: application/json" --data \
  '{"jsonrpc":"2.0","method":"eth_estimateGas","params":[{"from":"0x8D97689C9818892B700e27F316cc3E41e17fBeb9","to":"0xd3CdA913deB6f67967B99D67aCDFa1712C293601","value":"0xde0b6b3a7640000"}],"id":1}' \
  http://localhost:8545

cast estimate 0xd3CdA913deB6f67967B99D67aCDFa1712C293601 --value 1ether --from 0x8D97689C9818892B700e27F316cc3E41e17fBeb9 --rpc-url http://localhost:8545

Sample success output:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x5208"
}

eth_estimateGas only estimates L2 execution gas. To calculate the total transaction cost including L1 data fees, use the Optimism SDK or query the GasPriceOracle predeployed contract.

eth_sendRawTransaction

Submits a signed transaction to the network.

curl
cast

curl -X POST -H "Content-Type: application/json" --data \
  '{"jsonrpc":"2.0","method":"eth_sendRawTransaction","params":["0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675"],"id":1}' \
  http://localhost:8545

cast publish 0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675 --rpc-url http://localhost:8545

Sample success output:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331"
}

eth_getBlockByNumber

Returns information about a block by block number.

curl
cast

curl -X POST -H "Content-Type: application/json" --data \
  '{"jsonrpc":"2.0","method":"eth_getBlockByNumber","params":["0x1b4",true],"id":1}' \
  http://localhost:8545

cast block 0x1b4 --rpc-url http://localhost:8545

Sample success output:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "difficulty": "0x0",
    "extraData": "0x",
    "gasLimit": "0x1c9c380",
    "gasUsed": "0x5208",
    "hash": "0x1d59ff54b1eb26b013ce3cb5fc9dab3705b415a67127a003c3e61eb445bb8df2",
    "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
    "miner": "0x4200000000000000000000000000000000000011",
    "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "nonce": "0x0000000000000000",
    "number": "0x1b4",
    "parentHash": "0x9b83c12c69edb74f6c8dd5d052765c1adf940e320bd1291696e6fa07829eee71",
    "receiptsRoot": "0x056b23fbba480696b65fe5a59b8f2148a1299103c4f57df839233af2cf4ca2d2",
    "sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
    "size": "0x27f",
    "stateRoot": "0xd5855eb08b3387c0af375e9cdb6acfc05eb8f519e419b874b6ff2ffda7ed1dff",
    "timestamp": "0x54e34e8e",
    "totalDifficulty": "0x0",
    "transactions": [],
    "transactionsRoot": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421",
    "uncles": []
  }
}

eth_getLogs

Returns an array of all logs matching a given filter object.

curl
cast

curl -X POST -H "Content-Type: application/json" --data \
  '{"jsonrpc":"2.0","method":"eth_getLogs","params":[{"fromBlock":"0x1","toBlock":"0x2","address":"0x8320fe7702b96808f7bbc0d4a888ed1468216cfd"}],"id":1}' \
  http://localhost:8545

cast logs --from-block 1 --to-block 2 --address 0x8320fe7702b96808f7bbc0d4a888ed1468216cfd --rpc-url http://localhost:8545

Sample success output:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [{
    "address": "0x8320fe7702b96808f7bbc0d4a888ed1468216cfd",
    "topics": [
      "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
      "0x00000000000000000000000000000000000000000000000000000000000000fe",
      "0x000000000000000000000000a94f5374fce5edbc8e2a8697c15331677e6ebf0b"
    ],
    "data": "0x0000000000000000000000000000000000000000000000000000000000000001",
    "blockNumber": "0x1",
    "transactionHash": "0xab059a62e22e230fe0f56d8555340a29b2e9532360368f810595453f6fdd213b",
    "transactionIndex": "0x0",
    "blockHash": "0x8243343df08b9751f5ca0c5f8c9c0460d8a9b6351066fae0acbd4d3e776de8bb",
    "logIndex": "0x0",
    "removed": false
  }]
}

eth_chainId

Returns the currently configured chain ID, used for signing replay-protected transactions.

curl
cast

curl -X POST -H "Content-Type: application/json" --data \
  '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}' \
  http://localhost:8545

cast chain-id --rpc-url http://localhost:8545

Sample success output:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0xa"
}

Gas Price Methods

eth_gasPrice

Returns the current gas price in wei for L2 execution.

curl
cast

curl -X POST -H "Content-Type: application/json" --data \
  '{"jsonrpc":"2.0","method":"eth_gasPrice","params":[],"id":1}' \
  http://localhost:8545

cast gas-price --rpc-url http://localhost:8545

Sample success output:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x4a817c800"
}

This only returns the L2 gas price. For comprehensive transaction cost estimation including L1 data fees, use the GasPriceOracle predeployed contract or the Optimism SDK.

eth_maxPriorityFeePerGas

Returns the current maximum priority fee per gas (EIP-1559).

curl
cast

curl -X POST -H "Content-Type: application/json" --data \
  '{"jsonrpc":"2.0","method":"eth_maxPriorityFeePerGas","params":[],"id":1}' \
  http://localhost:8545

cast --priority-gas-price --rpc-url http://localhost:8545

Sample success output:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x3b9aca00"
}

Account and State Methods

eth_getCode

Returns code at a given address.

curl
cast

curl -X POST -H "Content-Type: application/json" --data \
  '{"jsonrpc":"2.0","method":"eth_getCode","params":["0x420000000000000000000000000000000000000F","latest"],"id":1}' \
  http://localhost:8545

cast code 0x420000000000000000000000000000000000000F --rpc-url http://localhost:8545

Sample success output:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x608060405234801561001057600080fd5b50600436106100365760003560e01c806354fd4d501461003b578063..."
}

eth_getStorageAt

Returns the value from a storage position at a given address.

curl
cast

curl -X POST -H "Content-Type: application/json" --data \
  '{"jsonrpc":"2.0","method":"eth_getStorageAt","params":["0x420000000000000000000000000000000000000F","0x0","latest"],"id":1}' \
  http://localhost:8545

cast storage 0x420000000000000000000000000000000000000F 0x0 --rpc-url http://localhost:8545

Sample success output:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x0000000000000000000000000000000000000000000000000000000000000001"
}

eth_getTransactionCount

Returns the number of transactions sent from an address (the nonce).

curl
cast

curl -X POST -H "Content-Type: application/json" --data \
  '{"jsonrpc":"2.0","method":"eth_getTransactionCount","params":["0x8D97689C9818892B700e27F316cc3E41e17fBeb9","latest"],"id":1}' \
  http://localhost:8545

cast nonce 0x8D97689C9818892B700e27F316cc3E41e17fBeb9 --rpc-url http://localhost:8545

Sample success output:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x1a"
}

Debug and Trace Methods

op-geth supports the same debug and trace methods as upstream Geth, allowing detailed transaction analysis and debugging.

Debug and trace methods can be resource-intensive. Most public RPC providers disable these methods. You’ll need to run your own node with --http.api debug,trace to access them.

debug_traceTransaction

Returns the trace of a transaction, showing all internal calls and state changes.

curl
cast

curl -X POST -H "Content-Type: application/json" --data \
  '{"jsonrpc":"2.0","method":"debug_traceTransaction","params":["0x88df016429689c079f3b2f6ad39fa052532c56795b733da78a91ebe6a713944b"],"id":1}' \
  http://localhost:8545

cast run 0x88df016429689c079f3b2f6ad39fa052532c56795b733da78a91ebe6a713944b --rpc-url http://localhost:8545 --trace

debug_traceCall

Traces a call without executing it on-chain.

curl

curl -X POST -H "Content-Type: application/json" --data \
  '{"jsonrpc":"2.0","method":"debug_traceCall","params":[{"to":"0x420000000000000000000000000000000000000F","data":"0x519b4bd3"},"latest"],"id":1}' \
  http://localhost:8545

WebSocket Support

op-geth supports WebSocket connections for real-time event subscriptions using the eth_subscribe method. Creates a subscription for specific events.

// Connect to WebSocket
const ws = new WebSocket('ws://localhost:8546');

// Subscribe to new block headers
ws.send(JSON.stringify({
  "jsonrpc": "2.0",
  "method": "eth_subscribe",
  "params": ["newHeads"],
  "id": 1
}));

// Subscribe to logs
ws.send(JSON.stringify({
  "jsonrpc": "2.0",
  "method": "eth_subscribe",
  "params": [
    "logs",
    {
      "address": "0x8320fe7702b96808f7bbc0d4a888ed1468216cfd",
      "topics": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"]
    }
  ],
  "id": 2
}));

eth_unsubscribe

Cancels an active subscription.

ws.send(JSON.stringify({
  "jsonrpc": "2.0",
  "method": "eth_unsubscribe",
  "params": ["0x9cef478923ff08bf67fde6c64013158d"],
  "id": 1
}));

Additional Resources

For a complete list of all supported JSON-RPC methods, refer to:

Running a Node with RPC Access

To run your own op-geth node with full RPC access:

op-geth \
  --http \
  --http.addr 0.0.0.0 \
  --http.port 8545 \
  --http.api eth,net,web3,debug,trace \
  --ws \
  --ws.addr 0.0.0.0 \
  --ws.port 8546 \
  --ws.api eth,net,web3 \
  ... # additional flags

Be cautious when exposing RPC endpoints publicly. Use authentication, rate limiting, and firewall rules to prevent abuse. Debug and trace APIs should only be enabled for trusted clients.

Getting Started

Guides

Tutorials

Reference

op-geth JSON-RPC API

Overview

Key Differences from Ethereum

Transaction Receipts

Gas Price Calculation

Standard JSON-RPC Methods

eth_blockNumber

eth_getBalance

eth_getTransactionByHash

eth_getTransactionReceipt

eth_call

eth_estimateGas

eth_sendRawTransaction

eth_getBlockByNumber

eth_getLogs

eth_chainId

Gas Price Methods

eth_gasPrice

eth_maxPriorityFeePerGas

Account and State Methods

eth_getCode

eth_getStorageAt

eth_getTransactionCount

Debug and Trace Methods

debug_traceTransaction

debug_traceCall

WebSocket Support

eth_unsubscribe

Additional Resources

Running a Node with RPC Access

Getting Started

Guides

Tutorials

Reference

​Overview

​Key Differences from Ethereum

​Transaction Receipts

​Gas Price Calculation

​Standard JSON-RPC Methods

​eth_blockNumber

​eth_getBalance

​eth_getTransactionByHash

​eth_getTransactionReceipt

​eth_call

​eth_estimateGas

​eth_sendRawTransaction

​eth_getBlockByNumber

​eth_getLogs

​eth_chainId

​Gas Price Methods

​eth_gasPrice

​eth_maxPriorityFeePerGas

​Account and State Methods

​eth_getCode

​eth_getStorageAt

​eth_getTransactionCount

​Debug and Trace Methods

​debug_traceTransaction

​debug_traceCall

​WebSocket Support

​eth_subscribe

​eth_unsubscribe

​Additional Resources

​Running a Node with RPC Access

Overview

Key Differences from Ethereum

Transaction Receipts

Gas Price Calculation

Standard JSON-RPC Methods

eth_blockNumber

eth_getBalance

eth_getTransactionByHash

eth_getTransactionReceipt

eth_call

eth_estimateGas

eth_sendRawTransaction

eth_getBlockByNumber

eth_getLogs

eth_chainId

Gas Price Methods

eth_gasPrice

eth_maxPriorityFeePerGas

Account and State Methods

eth_getCode

eth_getStorageAt

eth_getTransactionCount

Debug and Trace Methods

debug_traceTransaction

debug_traceCall

WebSocket Support

eth_subscribe

eth_unsubscribe

Additional Resources

Running a Node with RPC Access