Using Solo with EVM Tools

Point your existing Ethereum tooling (Hardhat, ethers.js, Foundry, and MetaMask) at a local Hiero network via the Hiero JSON-RPC relay. This document covers enabling the relay, creating and configuring a Hardhat project, deploying a Solidity contract, using Foundry, and configuring wallets.

Overview

Hiero is EVM-compatible. The Hiero JSON-RPC relay exposes a standard Ethereum JSON-RPC interface on your local Solo network, letting you use familiar EVM tools without modification.

This guide walks you through:

  • Launching a Solo network with the JSON-RPC relay enabled.
  • Retrieving ECDSA accounts for EVM tooling.
  • Creating and configuring a Hardhat project against the relay.
  • Deploying and interacting with a Solidity contract.
  • Deploying, calling and testing the same contract with Foundry (forge and cast).
  • Verifying transactions via the Explorer and Mirror Node.
  • Configuring ethers.js and MetaMask.

Prerequisites

Before proceeding, ensure you have completed the following:

  • System Readiness - your local environment meets all hardware and software requirements, including Docker and Solo.
  • Quickstart - you are comfortable running Solo deployments.

You will also need:


Step 1: Launch a Solo Network with the JSON-RPC Relay

The easiest way to start a Solo network with the relay pre-configured is via one-shot single deploy, which provisions the consensus node, mirror node, Hiero Mirror Node Explorer, and the Hiero JSON-RPC relay in a single step:

npx @hiero-ledger/solo one-shot single deploy

This command:

  • Creates a local Kind Kubernetes cluster.
  • Deploys a Hiero consensus node, mirror node, and Hiero Mirror Node Explorer.
  • Deploys the Hiero JSON-RPC relay and exposes it at http://localhost:37546 (Solo 0.63+).
  • Generates three groups of pre-funded accounts, including ECDSA (EVM-compatible) accounts.

Relay endpoint summary (Solo 0.63 and later):

PropertyValue
RPC URLhttp://localhost:37546
Chain ID298
Currency symbolHBAR

If you are using Solo 0.62 or earlier, the relay is at http://localhost:7546.

Adding the Relay to an Existing Deployment

If you already have a running Solo network without the relay, see Step 10: Deploy JSON-RPC Relay in the Step-by-Step Manual Deployment guide for full instructions, then return here once your relay is running on http://localhost:37546 (Solo 0.63+) or http://localhost:7546 (Solo 0.62 and earlier).

To remove the relay when you no longer need it, see Cleanup Step 1: Destroy JSON-RPC Relay in the same guide.


Step 2: Retrieve Your ECDSA Account and Private Key

one-shot single deploy creates ECDSA alias accounts, which are required for EVM tooling such as Hardhat, ethers.js, Foundry, and MetaMask. These accounts and their private keys are saved to a cache directory on completion.

Note: ED25519 accounts are not compatible with Hardhat, ethers.js, Foundry, or MetaMask when used via the JSON-RPC interface. Always use the ECDSA keys from accounts.json for EVM tooling.

  • To find your deployment name, run solo one-shot show deployment (see Capture your deployment name).

  • Then open the accounts file at:

    ~/.solo/one-shot-<deployment-name>/accounts.json
    
  • Open that file to retrieve your ECDSA keys and EVM address. Each account entry contains:

    • An ECDSA private key - 64 hex characters with a 0x prefix (e.g. 0x105d0050...).
    • An ECDSA public key - the corresponding public key.
    • An EVM address - derived from the public key (e.g. 0x70d379d473e2005bb054f50a1d9322f45acb215a). In Hiero terminology, this means the account has an EVM address aliased from its ECDSA public key.
    0x105d0050185ccb907fba04dd92d8de9e32c18305e097ab41dadda21489a211524
    0x2e1d968b041d84dd120a5860cee60cd83f9374ef527ca86996317ada3d0d03e7
    ...
    
  • Export the private key for one account as an environment variable - never hardcode private keys in source files:

export SOLO_EVM_PRIVATE_KEY="0x105d0050185ccb907fba04dd92d8de9e32c18305e097ab41dadda21489a211524"
$env:SOLO_EVM_PRIVATE_KEY = '0x105d0050185ccb907fba04dd92d8de9e32c18305e097ab41dadda21489a211524'

Step 3: Create and Configure a Hardhat Project

A ready-to-run Hardhat project is provided in the Solo repository. Skip to Step 4 after cloning:

git clone https://github.com/hiero-ledger/solo.git
cd solo/examples/hardhat-with-solo/hardhat-example
npm install

Option B: Create a New Hardhat Project from Scratch

If you want to integrate Solo into your own project:

mkdir solo-hardhat && cd solo-hardhat
npm init -y
npm install --save-dev hardhat @nomicfoundation/hardhat-toolbox
npx hardhat init

When prompted, choose TypeScript project or JavaScript project based on your preference.

Install dependencies:

npm install

Configure Hardhat to Connect to the Solo Relay

Create or update hardhat.config.ts to point at the Solo JSON-RPC relay. The chainId of 298 is required - Hardhat will reject transactions if it does not match the network:

import { defineConfig } from "hardhat/config";
import hardhatToolboxMochaEthers from "@nomicfoundation/hardhat-toolbox-mocha-ethers";

const config = defineConfig({
  plugins: [hardhatToolboxMochaEthers],
  solidity: "0.8.28",
  networks: {
    my_solo_deployment: {
      type: "http",
      url: "http://127.0.0.1:37546",
      chainId: 298,
      // Load from environment - never commit private keys to source control
      accounts: process.env.SOLO_EVM_PRIVATE_KEY
        ? [process.env.SOLO_EVM_PRIVATE_KEY]
        : [],
    },
  },
});

export default config;

Important: This is the Hardhat v3 config format used by the bundled example (Hardhat 3.x). Each network needs an explicit type: "http", and chainId: 298 must be set - without type/chainId, Hardhat v3 fails with HHE40000: No network with chain id "298" found when connecting to the relay. The network key (my_solo_deployment) must match the --network flag you pass to Hardhat commands.


Step 4: Deploy and Interact with a Solidity Contract

The Sample Contract

If using the pre-built Solo example, contracts/SimpleStorage.sol is included. For a new project, create contracts/SimpleStorage.sol:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.19;

contract SimpleStorage {
    uint256 private value;

    event ValueChanged(
        uint256 indexed oldValue,
        uint256 indexed newValue,
        address indexed changer
    );

    constructor(uint256 initial) {
        value = initial;
    }

    function get() external view returns (uint256) {
        return value;
    }

    function set(uint256 newValue) external {
        uint256 old = value;
        value = newValue;
        emit ValueChanged(old, newValue, msg.sender);
    }
}

Compile the Contract

npx hardhat compile

Expected output:

Compiled 1 Solidity file successfully (evm target: paris).

Run the Tests

npx hardhat test --network my_solo_deployment

For the pre-built example, the test suite covers three scenarios:

  SimpleStorage
    ✔ deploys with initial value
    ✔ updates value and emits ValueChanged event
    ✔ allows other accounts to set value

  3 passing (12s)

Deploy via a Script

To deploy SimpleStorage to your Solo network using a deploy script:

npx hardhat run scripts/deploy.ts --network my_solo_deployment

A minimal scripts/deploy.ts looks like:

Hardhat v3: The bundled example pins Hardhat 3.x, which removed the ethers named export from the hardhat module. Obtain ethers from the network connection with const { ethers } = await network.connect() instead of import { ethers } from "hardhat".

import { network } from "hardhat";

async function main() {
  const { ethers } = await network.connect();
  const SimpleStorage = await ethers.getContractFactory("SimpleStorage");
  const contract = await SimpleStorage.deploy(42);
  await contract.waitForDeployment();

  console.log("SimpleStorage deployed to:", await contract.getAddress());
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});

Step 5: Send a Transaction with ethers.js

To submit a transaction directly from a script using ethers.js via Hardhat:

import { network } from "hardhat";

async function main() {
  const { ethers } = await network.connect();
  const [sender] = await ethers.getSigners();
  console.log("Sender:", sender.address);

  const balance = await ethers.provider.getBalance(sender.address);
  console.log("Balance:", ethers.formatEther(balance), "HBAR");

  const tx = await sender.sendTransaction({
    to: sender.address,
    value: 10_000_000_000n,
  });

  await tx.wait();
  console.log("Transaction confirmed. Hash:", tx.hash);
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});

Run it with:

npx hardhat run scripts/send-tx.ts --network my_solo_deployment

Step 6: Use Foundry (forge and cast)

Foundry works with the Solo relay as well: forge create and cast send submit transactions to the network, and forge test runs your tests against a fork of it.

Version requirements: Foundry 1.8 or later, and Hiero JSON-RPC relay 0.80.0 or later (Solo 0.94.0 and later deploy relay 0.80.1). Foundry 1.8 sends EIP-1898 block parameters that older relay versions do not support.

Option A: Use the Pre-Built Solo Example

A ready-to-run Foundry project is provided in the Solo repository. It reuses the SimpleStorage contract from Step 4:

git clone https://github.com/hiero-ledger/solo.git
cd solo/examples/foundry-with-solo

With a Solo network running, task test installs forge-std, deploys SimpleStorage with forge create, updates it with cast send, and runs forge test. To deploy the network as well, run task (see Running the Full Example Automatically).

Option B: Configure Your Own Foundry Project

Point Foundry at the Solo relay in foundry.toml:

[profile.default]
src = "contracts"
out = "out"
libs = ["lib"]
evm_version = "cancun"

# Default RPC endpoint for forge and cast; forge test forks it.
eth_rpc_url = "http://localhost:37546"

# Solo networks are ephemeral and block numbers restart on every redeploy,
# so do not reuse cached fork state.
no_storage_caching = true

Install forge-std for the test helpers. Add --no-git when the project lives inside another Git repository and you do not want a submodule:

forge install foundry-rs/forge-std

Deploy a Contract with forge create

forge build
forge create contracts/SimpleStorage.sol:SimpleStorage \
  --rpc-url http://localhost:37546 \
  --private-key "$SOLO_EVM_PRIVATE_KEY" \
  --broadcast \
  --constructor-args 42

--constructor-args takes every remaining argument, so keep it last. The output includes a Deployed to: line with the contract address. Save it for the next commands:

export SIMPLE_STORAGE_ADDRESS="0xYOUR_CONTRACT_ADDRESS"

Interact with the Contract Using cast

cast call "$SIMPLE_STORAGE_ADDRESS" "get()(uint256)" --rpc-url http://localhost:37546

cast send "$SIMPLE_STORAGE_ADDRESS" "set(uint256)" 7 \
  --rpc-url http://localhost:37546 \
  --private-key "$SOLO_EVM_PRIVATE_KEY"

cast call "$SIMPLE_STORAGE_ADDRESS" "get()(uint256)" --rpc-url http://localhost:37546

The first cast call returns 42 and the second returns 7.

Run forge test Against Solo

Because eth_rpc_url is set, forge test forks the Solo network: tests run in a local EVM that loads accounts, code and storage from the relay on demand. Contracts the tests create and the state changes they make stay in the fork and never reach the Solo network. Use forge create or cast send to change the network itself.

SIMPLE_STORAGE_VALUE=7 forge test -vvv

The example’s test/SimpleStorage.t.sol checks that the fork reports chain ID 298, runs the same three scenarios as the Hardhat tests, and reads the SimpleStorage contract deployed above (from the exported SIMPLE_STORAGE_ADDRESS) through the fork.

Note: forge script is not covered. It has known limitations on Hedera when it broadcasts multiple transactions; use forge create and cast send to change network state.


Step 7: Verify Transactions

Confirm your transactions reached consensus using any of the following:

Hiero Mirror Node Explorer

http://localhost:38080/localnet/dashboard

Note: If you are using Solo 0.62 or earlier, the Explorer is at http://localhost:8080/localnet/dashboard.

Search by account address, transaction hash, or contract address to view transaction details and receipts.

Hiero Mirror Node REST API

http://localhost:38081/api/v1/transactions?limit=5

Returns the five most recent transactions in JSON format. Useful for scripted verification.

Note: localhost:5551 (the legacy Mirror Node REST API direct endpoint) is being phased out. Use localhost:38081 (Solo 0.63+) or localhost:8081 (Solo 0.62 and earlier) to ensure compatibility with all endpoints.

Hiero JSON RPC Relay (eth_getTransactionReceipt)

curl -X POST http://localhost:37546 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_getTransactionReceipt","params":["0xYOUR_TX_HASH"],"id":1}'

Step 8: Configure MetaMask

To connect MetaMask to your local Solo network:

  1. Open MetaMask and go to Settings → Networks → Add a network → Add a network manually.

  2. Enter the following values:

    FieldValue
    Network nameSolo Local
    New RPC URLhttp://localhost:37546
    Chain ID298
    Currency symbolHBAR

    Note: If you are using Solo 0.62 or earlier, use http://localhost:7546 for the RPC URL.

  3. Click Save and switch to the Solo Local network.

  4. Import an account using an ECDSA private key from accounts.json:

    • Click the account icon → Import account.
    • Paste the private key (with 0x prefix).
    • Click Import.

Your MetaMask wallet is now connected to the local Solo network and funded with the pre-allocated HBAR balance.


Step 9: Tear Down the Network

When finished, destroy the Solo deployment and all associated containers:

npx @hiero-ledger/solo one-shot single destroy

If you added the relay manually to an existing deployment:

solo relay node destroy --deployment "${SOLO_DEPLOYMENT}"

Reference: Running the Full Example Automatically

The hardhat-with-solo example includes a Taskfile.yml that automates all steps - deploy network, install dependencies, compile, and test - in a single command:

cd solo/examples/hardhat-with-solo
task

To tear everything down:

task destroy

This is useful for CI pipelines. See the Solo deployment with Hardhat Example for full details.

The foundry-with-solo example does the same for Foundry - deploy the network, install forge-std, deploy and update SimpleStorage with forge create and cast send, then run forge test:

cd solo/examples/foundry-with-solo
task

Tear it down with task destroy. See the Solo deployment with Foundry Example for full details.


Troubleshooting

SymptomLikely CauseFix
connection refused on port 37546Relay not runningRun one-shot single deploy or solo relay node add
invalid sender or signature errorUsing ED25519 key instead of ECDSAUse ECDSA keys from accounts.json
Hardhat chainId mismatch errorMissing or wrong chainId in configSet chainId: 298 in hardhat.config.ts
MetaMask shows wrong networkChain ID mismatchEnsure Chain ID is 298 in MetaMask network settings
INSUFFICIENT_TX_FEE on transactionAccount not fundedUse a pre-funded ECDSA account from accounts.json
Hardhat test timeoutNetwork not fully startedWait for one-shot to fully complete before running tests
forge test reports chain ID 31337 instead of 298forge test is not forking the relaySet eth_rpc_url in foundry.toml or pass --fork-url http://localhost:37546
forge test fails while fetching state from the relayFoundry 1.8+ against a relay older than 0.80.0Upgrade to Solo 0.94.0 or later (relay 0.80.1)
forge create fails with contract was not deployed, but the contract existsThe deployment includes a block node: the mirror node then returns no created_contract_ids, so the relay receipt has no contractAddress (hiero-mirror-node#14473)Deploy without a block node (ONE_SHOT_WITH_BLOCK_NODE=false)
Port 37546 already in useAnother process is using the portRun lsof -i :37546 and stop the conflicting process

Further Reading