Configuring Hardhat with Hiero Local Node: A Step-by-Step Guide

Developers building smart contracts on Hedera often use the Hedera JSON-RPC Relay to enable Ethereum tools like Hardhat. In this post, we'll walk through how to set up Hardhat to work with the Hiero Local Node, allowing for local deployment, debugging, and testing of smart contracts without using testnet resources.

Not sure whether to use the Hiero Local Node, Hashio, or a custom relay setup? Read this blog post comparing the different options.

Prerequisites

• Basic understanding of smart contracts.

• Basic understanding of Node.js and JavaScript.

• Basic understanding of Hardhat Ethereum Development Tool and Ethers.

• ECDSA account from the Hedera Portal.

---

Video Tutorial

You can either watch the video tutorial or follow the step-by-step tutorial below.

---

Step 1: Set Up the Hiero Local Node

Hedera provides a local node configuration that includes a mirror node, a consensus node, and the JSON-RPC relay. You can run it via npm.

Clone, install, and run the node:

git clone https://github.com/hiero-ledger/hiero-local-node.git
cd hiero-local-node
npm install
npm run start

Once all the containers have started, the Hiero Local Node is up and running. This includes a Consensus Node, Mirror Node and explorer, JSON RPC Relay, Block Node, Grafana UI, and Prometheus UI.

This command will also generate accounts on startup, which we will use later in our hardhat.config.js.

Auto-generated accounts for Hiero Local Node

Step 2: Create a Hardhat Project

If you don’t already have a Hardhat project, create one:

mkdir tutorial-local-hardhat
cd tutorial-local-hardhat
npx hardhat init

Make sure to select "Create a JavaScript project" and accept the default values. Hardhat will configure your project correctly and install the required dependencies like hardhat and @nomicfoundation/hardhat-toolbox (This includes plugins for Ethers, Waffle, Chai, and more).

Console logs for "npx hardhat init"

Step 3: Configure "hardhat.config.js"

Update your config to include the Hiero Local Node as a custom network:

require("@nomicfoundation/hardhat-toolbox");

module.exports = {
  solidity: {
    version: "0.8.28",
  },
  paths: {
    sources: "./contracts",
    tests: "./test",
    cache: "./cache",
    artifacts: "./artifacts",
  },
  defaultNetwork: "local",
  networks: {
    local: {
      url: 'http://localhost:7546',
      accounts: [
        "0x105d050185ccb907fba04dd92d8de9e32c18305e097ab41dadda21489a211524",
        "0x2e1d968b041d84dd120a5860cee60cd83f9374ef527ca86996317ada3d0d03e7"
      ],
      chainId: 298,
    }
  },
};

🔍 Key Highlights

• Network config: local

  • url: 'http://localhost:7546': ➤ This is the Hedera JSON-RPC Relay endpoint provided by the local node (via Docker). It enables Ethereum-compatible tools like Hardhat and Ethers.js to interact with the Hedera network.

  • accounts: ➤ Two predefined ECDSA private keys provided by the Hiero Local Node. ➤ These accounts are already funded, and can be used immediately to deploy and interact with smart contracts.

  • chainId: 298: ➤ This is the chain ID used by the Hiero Local Node to distinguish it from mainnet (295) or testnet (296).

• Set paths:

  • ./contracts: Where your smart contracts are located.

  • ./tests: Directory for writing and running Hardhat tests.

  • ./cache & ./artifacts: Manage build outputs and compilation caching to speed up repeated runs.

• Default network: "local"

  • Automatically uses the local Hedera environment for all tasks like compiling, deploying, testing, and scripting.

Further Learning & Next Steps

Want to take your local development setup even further? Here are some excellent tutorials to help you dive deeper into smart contract development on Hedera using Hardhat and Ethers.js:

1. How to Mint and Burn an ERC-721 Token (Part 1) Learn how to create a basic ERC-721 NFT, mint it, and burn it on Hedera.

2. Access Control, Token URI, Pause & Transfer (Part 2) Extend your NFT with features like pausing, setting token URIs, and restricting minting to specific roles.

3. Upgrade Your NFT with UUPS Proxies (Part 3) Learn how to add upgradability to your smart contracts using OpenZeppelin’s UUPS proxy pattern on Hedera.

4. How to Set Up a Hedera Local Node A hands-on guide to spinning up a local Hedera test environment with a built-in JSON-RPC Relay. Perfect for fast, zero-cost smart contract development and testing.

Writer: Michiel, Developer Relations Engineer

GitHub | LinkedIn

Editor: Krystal, Technical Writer

GitHub | X