In blockchain, reading data efficiently and effectively is crucial. JSON-RPC is a stateless, lightweight remote procedure call (RPC) protocol that allows for the execution of commands and retrieval of data from blockchain nodes. This guide explains the fundamentals of using JSON-RPC to interact with blockchain data, offering insights into its structure, workflow, and practical application.

Understanding JSON-RPC

Blockchain data is decentralized and immutable, consisting of various elements such as blocks, transactions, and smart contracts. Each block contains a list of transactions, representing a transfer of value or a smart contract execution. Accessing and interpreting this data is essential for developing decentralized applications (dApps), examining protocol activity, and conducting blockchain analytics.

What is JSON-RPC?

JSON-RPC, short for JavaScript Object Notation - Remote Procedure Call, is a protocol used to perform remote procedure calls. Encoded in JSON, it facilitates asynchronous communication between a client and a server, allowing the client to request information or actions from the server. A key feature of JSON-RPC is its stateless nature, meaning each request from the client must contain all the necessary information for the server to process it. This simplicity and stateless design make JSON-RPC an ideal choice for numerous applications, particularly for blockchain interactions.

How JSON-RPC Works

JSON-RPC operates through a series of requests and responses. The client sends a JSON-RPC request to the server, specifying the method to be executed and any necessary parameters. The server processes the request, executes the specified method, and returns a JSON-RPC response containing the result or an error message.

JSON-RPC Workflow

To interact with a blockchain node, you typically use a JSON-RPC interface. This interface can be accessed using various tools and libraries that facilitate sending JSON-RPC requests and receiving responses. Examples of tools and libraries for JSON-RPC  JavaScript libraries such as `ethers.js`, and full-fledged blockchain clients like Erigon and Reth, which facilitate access to blockchain nodes.

A typical workflow of JSON-RPC when fetching blockchain data can be summarized in three steps:

  1. Send Request: The client sends a JSON-RPC request to the blockchain node.

  2. Process Request: The node processes the request and performs the specified method.

  3. Return Response: The node sends back a JSON-RPC response containing the result or an error message.

Common JSON-RPC Methods

Some of the common methods used in JSON-RPC to interact with blockchain nodes include:

eth_blockNumber: This is used to retrieve the number of the most recent block.

eth_getBlockByNumber: It fetches a block based on its number.

eth_getTransactionByHash: Retrieves a transaction using its hash.

Leveraging GoldRush for Enhanced Data Retrieval

GoldRush offers a unified API that simplifies the process of retrieving blockchain data. While JSON-RPC requires crafting specific requests for each type of data, GoldRush abstracts this complexity, providing a more user-friendly and streamlined user experience. The unified API allows developers to access data across multiple blockchain networks using consistent and simplified endpoints.

Fetching Blockchain Data Using GoldRush

To fetch blockchain data using GoldRush, you typically make RESTful HTTP requests. The API endpoints are designed to be intuitive and easy to use, reducing the need for detailed knowledge of JSON-RPC methods and parameters. For example, fetching a transaction by its hash from the GoldRush API using typescript might look something like this:

JavaScript
import { CovalentClient } from "@covalenthq/client-sdk";

const ApiServices = async () => {
const client = new CovalentClient("Your-API-Key");
const resp = await client.TransactionService.getTransaction("eth-mainnet", "0x55a8333b5d56dc9caf64585a44db86e47dc112195450f71cb7a325bf8d5bd92f", {"quoteCurrency": "usd", "withSafe"; true});
console.log(resp.data);
}

The response will include the transaction and other relevant details in a format that is easier to parse and work with compared to raw JSON-RPC responses.

json
{
  "updated_at": "2024-07-17T17:45:40.980210485Z",
  "chain_id": 1,
  "chain_name": "eth-mainnet",
  "items": [
    {
      "block_signed_at": "2024-07-16T11:53:59Z",
      "block_height": 20318900,
      "block_hash": "0x1031511b7bd770a99b68484d15ff75e082b738465dd75379badfbfa6e7b0bbc3",
      "tx_hash": "0x55a8333b5d56dc9caf64585a44db86e47dc112195450f71cb7a325bf8d5bd92f",
      "tx_offset": 164,
      "successful": true,
      "miner_address": "0x4838b106fce9647bdf1e7877bf73ce8b0bad5f97",
      "from_address": "0x4838b106fce9647bdf1e7877bf73ce8b0bad5f97",
      "from_address_label": null,
      "to_address": "0x27c229fe370c1195c45ff1953e96acd741aa48c0",
      "to_address_label": null,
      "value": "36709716526572934",
      "value_quote": 126.470008330923,
      "pretty_value_quote": "$126.47",
      "gas_metadata": {
        "contract_decimals": 18,
        "contract_name": "Ether",
        "contract_ticker_symbol": "ETH",
        "contract_address": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
        "supports_erc": [],
        "logo_url": "https://www.datocms-assets.com/86369/1669653891-eth.svg"
      },
      "gas_offered": 22420,
      "gas_spent": 22420,
      "gas_price": 7960754367,
      "fees_paid": "178480112908140",
      "gas_quote": 0.614888468290325,
      "pretty_gas_quote": "$0.61",
      "gas_quote_rate": 3445.13715433829,
      "explorers": [
        {
          "label": null,
          "url": "https://etherscan.io/tx/0x55a8333b5d56dc9caf64585a44db86e47dc112195450f71cb7a325bf8d5bd92f"
        }
      ],
      "log_events": [
        {
          "block_signed_at": "2024-07-16T11:53:59Z",
          "block_height": 20318900,
          "tx_offset": 164,
          "log_offset": 471,
          "tx_hash": "0x55a8333b5d56dc9caf64585a44db86e47dc112195450f71cb7a325bf8d5bd92f",
          "raw_log_topics": [
            "0x830d2d700a97af574b186c80d40429385d24241565b08a7c559ba283a964d9b1",
            "0x00000000000000000000000027c229fe370c1195c45ff1953e96acd741aa48c0"
          ],
          "sender_contract_decimals": null,
          "sender_name": null,
          "sender_contract_ticker_symbol": null,
          "sender_address": "0x27c229fe370c1195c45ff1953e96acd741aa48c0",
          "sender_address_label": null,
          "sender_logo_url": "https://logos.covalenthq.com/tokens/1/0x27c229fe370c1195c45ff1953e96acd741aa48c0.png",
          "supports_erc": null,
          "sender_factory_address": null,
          "raw_log_data": "0x00000000000000000000000000000000000000000000000000826b4aed5f2586",
          "decoded": {
            "name": "ReceiveETH",
            "signature": "ReceiveETH(indexed address split, uint256 amount)",
            "params": [
              {
                "name": "split",
                "type": "address",
                "indexed": true,
                "decoded": true,
                "value": "0x27c229fe370c1195c45ff1953e96acd741aa48c0"
              },
              {
                "name": "amount",
                "type": "uint256",
                "indexed": false,
                "decoded": true,
                "value": "36709716526572934"
              }
            ]
          }
        }
      ]
    }
  ],
  "pagination": null
}

Conclusion

JSON-RPC is a robust and essential protocol for interacting with blockchain nodes, providing the means to read and manipulate blockchain data effectively. Understanding its workflow, methods, and formats allows developers to leverage its full potential in their projects. However, tools like GoldRush's unified API offer a more streamlined and user-friendly alternative for data retrieval, enabling developers to focus on building innovative applications without getting bogged down in the complexities of direct node interaction.