Skip to main content
Hardhat talks to Hedera through the Hiero JSON-RPC Relay, which translates Ethereum JSON-RPC calls into Hedera transactions. Once you point Hardhat at a relay endpoint, the workflow is the same as any other EVM chain: npx hardhat build, deploy scripts, ethers.js, and tests all behave normally. This page covers what is Hedera-specific. For a full local walkthrough, the Solo team maintains an end-to-end Hardhat guide.

Using Solo with EVM tools

Deploy a local Solo network, generate funded ECDSA accounts, configure hardhat.config.ts, deploy a contract, and connect MetaMask.

​
Pick a relay endpoint

Solo’s relay port changed in version 0.63; deployments on 0.62 and earlier use 7546. Solo also forwards to the next free port if 37546 is taken, so confirm the assignment printed at the end of your deploy. See Local Development for the current endpoint list, and the JSON-RPC relay page for third-party and self-hosted options.
Hashio is intended for development and testing. For production, use a commercial-grade relay or host your own Hiero JSON-RPC Relay.

​
Use ECDSA keys

Hedera supports both ED25519 and ECDSA (secp256k1) keys, but only ECDSA keys work over the JSON-RPC relay. An ED25519 account has no EVM address that Hardhat or ethers.js can sign for, so deployments from one fail.
  • Local network: Solo writes pre-funded ECDSA accounts to the createdAccounts array in ~/.solo/one-shot-<deployment-name>/accounts.json. Each entry includes the private key (0x plus 64 hex characters), its public key, and the derived EVM address.
  • Testnet and mainnet: create an ECDSA account in the Hedera Portal and use its HEX Encoded Private Key, not the DER-encoded one.
Read Addresses for how Hedera account IDs and EVM addresses relate.

​
Configure the network

Hardhat 3 requires type and chainId on HTTP networks. Without both, connecting to the relay fails with HHE40000: No network with chain id "298" found. Define one network entry per target rather than swapping the URL, since chainId has to move with it:
hardhat.config.ts
The network key is what you pass to --network, so npx hardhat run scripts/deploy.ts --network hederaLocal targets the local relay. Store the private key with Hardhat’s keystore rather than committing it:
  • compile → build: npx hardhat compile is now npx hardhat build.
  • project init: npx hardhat init is now npx hardhat --init.
  • keystore commands: the keystore plugin (npx hardhat keystore set ...) is new in v3.
  • Solidity tests: v3 runs Foundry-compatible Solidity tests alongside TypeScript integration tests.
  • Network management: v3 tasks can open and manage multiple network connections at once.
See the Hardhat documentation for the full migration guide.

​
Hedera-specific gotchas

  • Gas price units. The relay returns msg.value and gasPrice with 18 decimals, while native Hedera APIs use 8 decimals for HBAR. See HBAR decimal places.
  • Foundry and Hardhat print “ETH”. Tooling hardcodes the label. The currency being spent is HBAR.
  • Contract verification. Sourcify supports mainnet (295) and testnet (296). It does not support a local network, so verification has to wait until you deploy to a public network.
  • Token association. Transferring an HTS token to an account requires that account to be associated with the token first. See token association.

​
Further learning

  1. How to Mint and Burn an ERC-721 Token (Part 1)
    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 pausing, token URIs, and role-restricted minting.
  3. Upgrade Your NFT with UUPS Proxies (Part 3)
    Add upgradeability using OpenZeppelin’s UUPS proxy pattern.

Writer: Michiel, DevRel Engineer

GitHub | LinkedIn

Editor: Krystal, Senior DX Engineer

GitHub | X

Editor: Kiran, Developer Advocate

GitHub | LinkedIn