Hardhat¶

Hardhat Polkadot¶

Introduction¶

Hardhat is a flexible development environment for building, testing, and deploying smart contracts on Polkadot. Its task runner and plugin system support organizing contract code, running tests, managing deployments, and adding custom tooling. This page demonstrates how to set up a Hardhat project for Polkadot Hub.

Prerequisites¶

Before setting up Hardhat, make sure the following are installed:

Node.js (Hardhat requires an LTS Node version, even major numbers like 18.x, 20.x, or 22.x)
A package manager like npm, pnpm, or yarn

Initialize a Hardhat Project¶

Create a directory to hold your project files:
```
mkdir hardhat-example
cd hardhat-example
```
Initialize a Hardhat project:
npmpnpmyarn
This single command sets up your project, installs Hardhat (and optionally the Toolbox), and intializes the project:
npx hardhat@^2.27.0 init
This single command sets up your project, installs Hardhat (and optionally the Toolbox), and intializes the project:
pnpm dlx hardhat@^2.27.0 init
These commands manually set up your project, install Hardhat (and optionally the Toolbox), and initializes the project:
# Initialize a new Node.js project yarn init -y # Install Hardhat and the Hardhat Toolbox locally yarn add --dev hardhat@^2.27.0 @nomicfoundation/hardhat-toolbox # Initialize a Hardhat project npx hardhat init
You will be prompted to select certain configurations for your project. To quickly create a working setup, you can accept the default answers, which will create a JavaScript project, initialize it in the current directory, add a .gitignore, and install all dependencies.

After completing the setup, your Hardhat project will be fully initialized with all necessary files and dependencies. You'll see the following core components in your project:

contracts: Stores your Solidity smart contracts.
ignition: Contains deployment modules for safely deploying your contracts to various networks.
test: Contains test files that validate contract functionality.
hardhat.config.js | .ts: Defines your project's settings, including networks, compiler options, and plugins.

Configure Hardhat for Polkadot Hub¶

To use Hardhat with Polkadot Hub, define the network configuration in your hardhat.config.ts file:

Polkadot TestNet

hardhat.config.ts

import type { HardhatUserConfig } from 'hardhat/config';
import '@nomicfoundation/hardhat-toolbox';

// If you want to use a variable for your private key
import { vars } from 'hardhat/config';

const config: HardhatUserConfig = {
  solidity: '0.8.28',
  networks: {
    polkadotTestnet: {
      url: 'https://services.polkadothub-rpc.com/testnet',
      chainId: 420420417,
      accounts: [vars.get('PRIVATE_KEY')],
    },
  },
};

export default config;

Tip

To define a configuration variable for your private key, run:

npx hardhat vars set PRIVATE_KEY

Hardhat will prompt you to enter your private key and store it so it can be referenced in your configuration file.

Where to Go Next¶

Guide Deploy a Basic Contract

Ready to start using Hardhat? Learn how to compile, test, and deploy a basic contract.

Get Started
Guide Deploy an ERC-20

Walk through deploying a fully-functional ERC-20 to Polkadot Hub using Hardhat.

Get Started
Guide Deploy an NFT

Walk through deploying an NFT to Polkadot Hub using Hardhat.

Get Started
Guide Create a DApp

Learn step-by-step how to build a fully functional dApp that interacts with a smart contract deployed via Hardhat.

Get Started

Introduction¶

Hardhat is a flexible development environment for building, testing, and deploying smart contracts. With the @parity/hardhat-polkadot plugin, you can compile Solidity contracts to PVM bytecode and deploy them to Polkadot Hub. This page demonstrates how to set up a Hardhat project for PVM development.

Prerequisites¶

Before setting up Hardhat, make sure the following are installed:

Node.js version 22.5+ and npm version 10.9.0+ to avoid issues with the Polkadot plugin
A package manager like npm, pnpm, or yarn

Initialize a Hardhat Project¶

Create a directory to hold your project files:

mkdir hardhat-pvm-example
cd hardhat-pvm-example

Initialize a new npm project:
```
npm init -y
```

Install the Polkadot plugin for Hardhat:

npm install --save-dev @parity/hardhat-polkadot@0.2.7

Install the resolc compiler (required for compiling Solidity to PVM):
```
npm install --save-dev @parity/resolc@0.2.0
```
Initialize a Hardhat project:
```
npx hardhat-polkadot init
```
Follow the project creation wizard. Your project will be created with three main folders:
- contracts: Stores your Solidity smart contracts.
- ignition: Contains deployment modules for safely deploying your contracts to various networks.
- test: Contains test files that validate contract functionality.
Add the following folder to the .gitignore file if it is not already there:
```
echo '/ignition/deployments/' >> .gitignore
```
Complete the setup by installing all dependencies:
```
npm install
```

Compile Your Contract¶

The plugin will compile your Solidity contracts (version 0.8.0 and higher) to PVM bytecode using the resolc compiler:

npx hardhat compile

After successful compilation, you'll see the artifacts generated in the artifacts directory:

ls artifacts/contracts/*.sol/

You should see JSON files containing the contract ABIs and bytecodes for the contracts you compiled.

Test Your Contract Locally¶

Hardhat provides a local testing environment through the hardhat-polkadot plugin, which spins up a local Substrate node with an ETH-RPC adapter.

Start a Local Node¶

To obtain the dev-node and eth-rpc binaries, check this release and download the binaries for your platform, then update the paths in your config.

Note

You might need to give executable permissions to the binaries:

chmod +x /path/to/your/binary

In macOS environments, binaries are sometimes quarantined. To remove this, run:

xattr -d com.apple.quarantine /path/to/your/binary

Once you have set up the binaries, start your local testing node:

npx hardhat node

This command launches a local node with the ETH-RPC adapter. By default, the Substrate node runs on localhost:8000, and the ETH-RPC adapter on localhost:8545.

The output will be something like this:

npx hardhat node
Starting server at 127.0.0.1:8000 ../bin/substrate-node --rpc-port=8000 --dev Starting the Eth RPC Adapter at 127.0.0.1:8545 ../bin/eth-rpc --node-rpc-url=ws://localhost:8000 --dev 2025-05-29 13:00:32 Running in --dev mode, RPC CORS has been disabled. 2025-05-29 13:00:32 Running in --dev mode, RPC CORS has been disabled. 2025-05-29 13:00:32 🌐 Connecting to node at: ws://localhost:8000 ... 2025-05-29 13:00:32 Substrate Node 2025-05-29 13:00:32 ✌️ version 3.0.0-dev-f73c228b7a1 2025-05-29 13:00:32 ❤️ by Parity Technologies <admin@parity.io>, 2017-2025 2025-05-29 13:00:32 📋 Chain specification: Development 2025-05-29 13:00:32 🏷 Node name: electric-activity-4221 2025-05-29 13:00:32 👤 Role: AUTHORITY 2025-05-29 13:00:32 💾 Database: RocksDb at /var/folders/f4/7rdt2m9d7j361dm453cpggbm0000gn/T/substrateOaoecu/chains/dev/db/full 2025-05-29 13:00:36 [0] 💸 generated 1 npos voters, 1 from validators and 0 nominators ...

Run Tests¶

To run your contract tests:

npx hardhat test

Compatibility Note

Be aware that @nomicfoundation/hardhat-toolbox/network-helpers is not fully compatible with Polkadot Hub's available RPCs. Specifically, helpers like time and loadFixture may not work due to missing RPC calls in the node. For more details, refer to the Compatibility section in the hardhat-polkadot documentation.

Deploy to Local Node¶

Before deploying to a live network, you can deploy your contract to a local node using Ignition modules:

Ensure your local node is running:
```
npx hardhat node
```

In a new terminal window, deploy the contract using Ignition:

npx hardhat ignition deploy ./ignition/modules/MyToken.js --network localNode

Tip

The ignition.requiredConfirmations: 1 setting in your config ensures that deployment doesn't hang on local nodes that only produce blocks when transactions are submitted.

Deploy to Polkadot Hub TestNet¶

After testing locally, you can deploy to the Polkadot Hub TestNet:

Fund your deployment account with PAS test tokens from the Polkadot faucet.
Set your private key as a configuration variable:
```
npx hardhat vars set PRIVATE_KEY
```
Warning

Never reveal your private key. Anyone with access to it can control your wallet and steal your funds. Store it securely and never share it publicly or commit it to version control systems.
Verify your private key is set:
```
npx hardhat vars get PRIVATE_KEY
```

Deploy your contract:

npx hardhat ignition deploy ./ignition/modules/MyToken.js --network polkadotTestnet

Common Issues¶

Compilation fails with resolc errors: Ensure you have @parity/resolc@0.2.0 installed and the version is specified in your hardhat.config.js
Deployment hangs on local node: You might need to set ignition.requiredConfirmations: 1 in your config file
Binary permission issues: Run chmod +x /path/to/your/binary and on macOS, use xattr -d com.apple.quarantine /path/to/your/binary

Where to Go Next¶

Guide Deploy a Basic Contract

Ready to start using Hardhat with PVM? Learn how to compile, test, and deploy a basic contract.

Get Started
Guide Deploy an ERC-20

Walk through deploying a fully-functional ERC-20 to Polkadot Hub using Hardhat.

Get Started
External Hardhat Documentation

Learn more about Hardhat's advanced features and best practices.

Get Started
External Hardhat Polkadot Plugin

Explore the full capabilities of the Hardhat Polkadot plugin.

Get Started

Last update: January 27, 2026
| Created: January 14, 2026