Anything you can do, you can do on Hedera: Introducing the JSON-RPC Relay
May 18, 2022
by Atul Mahamuni
Senior Vice President of Product at Swirlds Labs

The launch of Hedera Smart Contracts 2.0 (HSCS) in February 2022 came with subsequent rapid adoption by application developers and usage by retail users. The most prominent is Stader Labs’ staking application that locks HBAR in a smart contract and rewards stakers with an HBARX coupon, redeemable for 1 HBAR at a later date — within a few short days, thousands of retail users staked over $50M USD worth of HBAR through the HashPack Wallet.

HSCS 2.0 offers significant advantages, including optimizations of the Besu EVM for the Hedera network. In addition, Hedera core contributors have integrated the Hedera Token Service (HTS) into HSCS, enabling application developers to combine the full programmability offered by EVM-based smart contracts with native fungible tokens and NFTs configured and minted using the fast, efficient, and low-cost HTS.

Now it’s time to turn the focus on bringing even greater usability for developers building Smart Contract applications on Hedera. The most ubiquitous EVM-based libraries, tools, and workflows across web3 ecosystems are based on the JSON-RPC specification. Existing Hedera application developers desire streamlined ways to build and deploy smart contracts on Hedera, while new entrants migrating from alternative EVM-based networks want to use the same tools and services with which they’re most familiar — however, today, the Hedera mainnet does not understand the Ethereum transaction body natively.

What is the JSON-RPC Relay?

To address this challenge and make building EVM-based smart contracts on Hedera even more accessible, a series of technical measures have been proposed via HIPs (HIP-410 & HIP-415); these HIPs enable the creation of HIP-482, which is the JSON-RPC Relay that supports JSON-RPC API calls (transactions & queries). The JSON-RPC Relay makes it easy for existing libraries, development tools, and wallets to work effortlessly on Hedera.

The combination of HIP-410 / 415 enables the JSON-RPC Relay and furnishes three crucial functional requirements:

  • Exchange of transactions and queries between RPC native DLTs e.g. Ethereum and Hedera.

  • Encapsulation of requests in Hedera and Ethereum body structures.

  • Providing logical equivalence to Ethereum Blocks on Hedera.

This enables the support of wallets, such as Metamask, libraries, such as ethers.js and web3.js, and developer tools, such as Truffle and Hardhat.

How does the JSON-RPC Relay work?

The primary purpose of the JSON-RPC Relay is to provide applications and tools seamless access to the Hedera network while masking implementation complexities and preventing reductions in performance, security, or scalability.

The relay sends transactions to the Hedera mainnet for consensus using the Hedera SDK and sends queries to the mirror node REST API. This is further explained in the paragraphs below, which introduce two HIPs to make this possible: HIP-410 and HIP-415. Additionally, HIP-482 offers the full list of JSON-RPC APIs supported by this relay.

Flowchart final transparent updated

HIP-410: Wrapping Ethereum transaction bytes in a Hedera transaction

HIP-410 creates a mechanism so that the JSON-RPC Relay can wrap the Ethereum transaction body in a Hedera API (HAPI) call and submit it to the Hedera mainnet. The Hedera mainnet then unwraps this transaction and interprets its payload to call a method in the smart contract.

HIP-415: Introduction of blocks

Ethereum's JSON-RPC APIs are tightly bound to the blocks that Ethereum's mining process produces. Hedera offers leaderless consensus and does not use single-leader block production; therefore, it has no need to group fairly ordered transactions into blocks. HIP-415 proposes an introduction of deterministic groupings as part of the protocol and exposed as blocks through relevant JSON-RPC and REST APIs. This makes it so that transactions on Hedera can be interpreted as a chain of blocks.

Consensus nodes vs mirror nodes

Hedera’s architecture has a logical separation of consensus functionality, via Hedera consensus nodes, from the maintenance of the ledger (i.e. the history of transactions), via Hedera mirror nodes. Hence, the JSON-RPC relay sends transactions to the Hedera mainnet and sends queries to the mirror node REST API.

The mirror node software is being upgraded to support queries for the results of smart contract transactions, as well as querying for logs and events emitted by smart contracts. In the future, enhancements to this capability include debugging support, ensuring users can query the mirror nodes about the state of a smart contract at any point in history, as well as re-execute the smart contract against that state.