Home

JSON RPC Interface (Query Interface)

4 min read

In the OP Stack, the Execution Layer (primarily op-geth) serves as the interface for both network coordination (via the Engine API) and user-facing interactions. The system exposes an extensive JSON-RPC interface to support blockchain data queries, transaction submissions, and deep debugging.

1. Standard Ethereum JSON-RPC Support

While the Engine API is registered under the engine namespace for Consensus Layer (CL) coordination, the software acts as a full Ethereum node backend. It is designed to expose standard namespaces like eth_, debug_, and net_ by interacting with the core blockchain logic:

  • API Registration: The node infrastructure allows for the registration of various API services, including the ConsensusAPI and simulatedBeaconAPI (under the dev namespace).
  • Transport Flexibility: The underlying node.New configuration supports standard network transports, including P2P, HTTP, and WebSocket interfaces.

2. Serving Blockchain Data Queries

The protocol fulfills queries such as eth_getBlockByNumber or eth_getBalance by accessing its internal BlockChain and StateDB.

  • Retrieval Logic: For example, the getBodiesByRange internal method demonstrates how the system fetches ranges of blocks using GetBlockByNumber.
  • State Access: To serve balance or nonce queries, the Execution Layer (EL) utilizes the StateReader interface to retrieve StateAccount data from the Merkle Patricia or Verkle trie.
  • Data Serialization: The state package includes methods like Dump and IterativeDump to serialize the entire state or specific account data into JSON-formatted objects for RPC responses.

3. Transaction Submission (eth_sendRawTransaction)

When a user submits a transaction via JSON-RPC, the protocol processes it through a defined lifecycle:

  • The TxPool: Transactions are accepted into the TxPool, which manages pending and executable transactions.
  • Simulated Submission: Tests within the sources show the SendTx method being used to sign and submit transactions into the pool.
  • Miner Inclusion: The Miner background worker continuously monitors the txpool, pulling transactions sorted by price and nonce to build upcoming blocks.

4. Execution Traces and Debugging

The OP Stack provides granular debugging information through its EVM Tracer architecture:

  • Tracer Hooks: The EVM Config supports a Tracer containing hooks for specific events. These hooks trigger at the protocol level during the interpreter’s run loop.
  • Capture Points: Traces are generated by capturing data at key points:
    • OnOpcode: Logs the program counter, opcode, and gas cost for every step of execution.
    • OnEnter / OnExit: Records details when entering or exiting a call frame.
    • OnFault: Captures errors during execution for troubleshooting.
  • Stateless Witnesses: Starting with specialized endpoints like engine_newPayloadWithWitness, the protocol can return stateless witnesses (RLP-encoded proofs) that allow for the verification of state transitions without a local database.

5. Flow Example: A Transaction Trace Query

  1. Request: A user calls a debug RPC method (e.g., debug_traceTransaction) via HTTP or WebSocket.
  2. Initialization: The EL initializes an EVM instance with a Config that includes Tracer hooks.
  3. Execution: The Interpreter runs the code. At each step, it checks the Tracer. If active, it calls OnOpcode to log the current state (stack, memory, gas).
  4. Completion: Once the code finishes or faults, the OnExit hook captures the return data and final gas usage.
  5. Response: The collected trace is bundled into a JSON response and returned to the user.

Relationship between the Consensus and Execution Layer

1. The Engine API: Internal Protocol Coordination

The Consensus Layer (CL) uses the Engine API (registered under the engine namespace) to drive the Execution Layer (EL) through deterministic state transitions.

  • State Control: This interface is used to tell the EL which block is the current “head,” which is “safe,” and which is “finalized” via engine_forkchoiceUpdated.
  • Block Production & Validation: The CL uses this API to trigger block building (engine_getPayload) and to hand over new blocks for local re-execution and verification (engine_newPayload).
  • Authentication: Unlike public endpoints, the engine namespace is authenticated, meaning only the authorized consensus client (like the op-node) can access these methods to modify the chain state.

2. Standard JSON-RPC: Public Data and Interaction

Concurrently, the Execution Layer acts as a standard Ethereum node, exposing the common eth_, debug_, net_, and web3_ namespaces for the broader ecosystem.

  • Serving Queries: These public endpoints allow wallets, block explorers, and dApps to query blockchain data, such as retrieving account balances (eth_getBalance) or fetching historical block data (eth_getBlockByNumber).
  • Accepting Transactions: This is the primary entry point for new user activity. When a user sends a transaction via eth_sendRawTransaction, it enters the EL’s TxPool.
  • Observability: The debug_ and trace_ namespaces utilize internal EVM tracers to provide granular execution logs for troubleshooting and auditing.

Graph View

Backlinks