HardHat

This guide walks you through setting up a complete local Ethereum development environment for Substreams development using HardHat. You'll deploy a sample Counter contract, generate transactions, and stream the events using Substreams.

Estimated time: 15-20 minutes

What You'll Build

• Local Ethereum node (Geth in dev mode)

• Firehose integration for block streaming

• Counter smart contract with events

• Substreams module to extract contract events

• Complete Docker Compose orchestration

Prerequisites

Ensure you have the following installed:

• Docker 20.10+ with Docker Compose v2.0+

• Node.js 18+ with npm or yarn

• Substreams CLI v1.7.0+ (installation guide)

• Rust with wasm32-unknown-unknown target

• curl for testing endpoints

Architecture Overview

The local environment consists of:

• Geth (port 8545/8546) - Ethereum node in dev mode with 1-second block time

• Substreams (port 9000) - Substreams Tier1 service providing gRPC streaming

• Docker network - Connecting all services

┌─────────────────┐    ┌─────────────────────┐    ┌─────────────────┐
│   Your App      │    │     Substreams      │    │     HardHat     │
│                 │    │                     │    │                 │
│ ┌─────────────┐ │    │ ┌─────────────────┐ │    │ ┌─────────────┐ │
│ │ Substreams  │─┼────┼►│   Substreams    │ │    │ │   Deploy    │ │
│ │    CLI      │ │    │ │   (port 9000)   │ │    │ │  Contracts  │ │
│ └─────────────┘ │    │ └─────────────────┘ │    │ └─────────────┘ │
└─────────────────┘    │          │          │    └─────────────────┘
                       │ ┌─────────────────┐ │
                       │ │      Geth       │ │
                       │ │   (port 8545)   │ │
                       │ └─────────────────┘ │
                       └─────────────────────┘

Setup Instructions

1. Create Project Directory

mkdir substreams-ethereum-local
cd substreams-ethereum-local

2. Create Docker Compose Configuration

Create a docker-compose.yml file:

services:
  ethereum-node:
    image: ghcr.io/streamingfast/go-ethereum:geth-v1.16.7-fh3.0
    container_name: ethereum-dev-node
    entrypoint: ["/app/fireeth"]
    command:
      - start
      - reader-node,relayer,merger,firehose,substreams-tier1,substreams-tier2
      - --config-file=
      - --log-format=text
      - --log-to-file=false
      - --data-dir=/data
      - --advertise-block-id-encoding=hex
      - --advertise-chain-name=local-ethereum
      - --common-first-streamable-block=0
      - --reader-node-path=geth
      - --reader-node-arguments=--dev --dev.period=1 --vmtrace=firehose --http --http.addr=0.0.0.0 --http.port=8545 --http.api=eth,net,web3,debug,txpool --datadir=/data/geth
      - --firehose-grpc-listen-addr=:8089
      - --substreams-tier1-grpc-listen-addr=:9000
      - --substreams-tier1-block-type=sf.ethereum.type.v2.Block
    ports:
      - "8545:8545"
      - "8546:8546"
      - "8089:8089"
      - "9000:9000"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8545", "-X", "POST", "-H", "Content-Type: application/json", "-d", '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}']
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s
    volumes:
      - ethereum_data:/data
    networks:
      - ethereum_network

  fund-address:
    image: ghcr.io/streamingfast/go-ethereum:geth-v1.16.7-fh3.0
    volumes:
      - ethereum_data:/data
    entrypoint: ["geth"]
    command:
      - attach
      - --datadir=/data/geth
      - '--exec=[
        "0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266",
        "0x70997970c51812dc3a010c7d01b50e0d17dc79c8",
        "0x3c44cdddb6a900fa2b585dd299e03d12fa4293bc",
        "0x90f79bf6eb2c4f870365e785982e1f101e93b906",
        "0x15d34aaf54267db7d7c367839aaf71a00a2c6a65",
        "0x9965507d1a55bcc2695c58ba16fb37d819b0a4dc",
        "0x976ea74026e726554db657fa54763abd0c3a0aa9",
        "0x14dc79964da2c08b23698b3d3cc7ca32193d9955",
        "0x23618e81e3f5cdf7f54c3d65f7fbc0abf5b21e8f",
        "0xa0ee7a142d267c1f36714e4a8f75612f20a79720"
        ].forEach(to =>
        eth.sendTransaction({from: eth.accounts[0], to, value: web3.toWei(10000, "ether")})
        );'
    restart: on-failure
    deploy:
      restart_policy:
        condition: on-failure
        delay: 2s

volumes:
  ethereum_data:

networks:
  ethereum_network:
    driver: bridge

3. Start the Environment

docker compose up -d

To restart everything from scratch, use docker compose down --volumes to remove all data and start fresh.

Validation Commands

1. Check Docker Services

Verify all containers are running and healthy:

docker compose ps

Expected output:

NAME                   COMMAND                  SERVICE           STATUS              PORTS
ethereum-dev-node      "/app/fireeth start …"   ethereum-node     Up (healthy)        0.0.0.0:8089->8089/tcp, 0.0.0.0:8545->8545/tcp, 0.0.0.0:8546->8546/tcp, 0.0.0.0:9000->9000/tcp
fund-address           "geth attach --datad…"   fund-address      Exited (0)

2. Test Substreams Connectivity

Test Substreams Tier1 gRPC connectivity:

substreams run -e localhost:9000 --plaintext [email protected] -o clock -s -1

Expected output:

Writing clock information only (no data)
----------- BLOCK #24 (6c3dbc20ae11cb856bed9789f7845359e98de71b830f0d9599d0061ed4e962d2) age=1.959195s ---------------
...

If all validation commands succeed, your environment is ready!

Deploy Counter Contract with HardHat

1. Initialize HardHat Project

This guide mostly follows HardHat's setup tutorial in a streamlined way.

npx hardhat --init

Follow the interactive prompts:

• First choose Hardhat 3 Beta (recommended for new projects)

• Second use . as the relative path

• Third choose A TypeScript Hardhat project using Node Test Runner and Viem

• Fourth choose Yes when requested to install dependencies

2. Configure HardHat

Update hardhat.config.ts to add the local network:

export default defineConfig({
  ...,
  networks: {
    local: {
      type: "http",
      chainType: "l1",
      chainId: 1337,
      url: "http://localhost:8545",
    },
    ...
  },
});

3. Counter Contract

HardHat created a contract for us! You can view the contract at contracts/Counter.sol:

// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.28;

contract Counter {
  uint public x;

  event Increment(uint by);

  function inc() public {
    x++;
    emit Increment(1);
  }

  function incBy(uint by) public {
    require(by > 0, "incBy: increment should be positive");
    x += by;
    emit Increment(by);
  }
}

4. Deploy the Contract

HardHat created a deployment script at ignition/modules/Counter.ts. Deploy the contract:

npx hardhat ignition deploy ignition/modules/Counter.ts --network=local

Example output:

...
Deployed Addresses

CounterModule#Counter - <CONTRACT_ADDRESS>

5. Verify Deployment

npx hardhat console --network local

In the console:

const { viem } = await network.connect();
let counter = await viem.getContractAt("Counter", "<CONTRACT_ADDRESS>");
await counter.write.incBy([2n]);
await counter.read.x(); // Should return current counter value

Create Substreams Module

1. Initialize Substreams Project

substreams init

Follow the interactive prompts:

• Chosen protocol: EVM

• Chosen generator: evm-events-calls

• Please enter the project name: counter

• Please select the chain: Ethereum Mainnet (or the chain you are targeting)

• Please enter the contract address: <CONTRACT_ADDRESS> (use your deployed address)

• How do you want to provide the JSON ABI?: JSON in a local file

• Input the full path of the JSON ABI: ./artifacts/contracts/Counter.sol/Counter.json

• Please enter the contract initial block number: 0

• Choose a short name for the contract: counter

• What do you want to track for this contract?: Both events and calls

• Is this contract a factory: No

• Add another contract?: No

• In which directory do you want to download the project?: ./substreams

• How would you like to consume the Substreams?: To Postgres (or choose any other one)

The IDL file at ./artifacts/contracts/Counter.sol/Counter.json was automatically generated by Hardhat during the build process. We reference this file when initializing the Substreams module.

This will generate the basic Substreams module structure with the necessary configuration for tracking your Counter program.

2. Build and Test Substreams

cd substreams
substreams build
substreams run -e localhost:9000 --plaintext counter-v0.1.0.spkg

Look for the deployment block as it's the one that will contain some actual data. You can scan a specific range using -s <DEPLOYMENT_BLOCK> -t +10 to scan 10 blocks starting from the deployment block.

You can also leave the substreams run running and open another terminal to run execute the Verify Deployment commands to see data being process live.

You should see the Increment events from your contract deployment!

Cleanup

Congratulations! You've completed the tutorial and have a working local HardHat development environment for Substreams.

When you're done, you can clean up the Docker environment with:

docker compose down --volumes

This will stop all containers and remove all data, allowing you to start fresh if needed.

Troubleshooting

For common issues with Docker Compose, RPC connectivity, Substreams, and platform-specific problems, see the Local Development Troubleshooting Guide.

Next Steps

Now that you have a working local environment:

1. Try Other Platforms - Explore Foundry or Solana local development

2. Advanced Substreams - Learn about modules, manifests, and data transformations

3. Consuming Substreams - Connect to databases or streaming platforms

4. Production Deployment - Move to production endpoints

Additional Resources

• HardHat Documentation

• Substreams Ethereum Reference

• Substreams CLI Reference

• Creating Protobuf Schemas