Hardhat Polkadot

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

1. Create a directory to hold your project files:

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

2. Initialize a new npm project:

   npm init -y

3. Install the Polkadot plugin for Hardhat:

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

4. Install the resolc compiler (required for compiling Solidity to PVM):

   npm install --save-dev @parity/resolc@1.5.0

5. 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.

6. Add the following folder to the .gitignore file if it is not already there:

   echo '/ignition/deployments/' >> .gitignore

7. 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 a broader overview of how Ethereum-native tools differ when used against Polkadot EVM networks, see Differences between Ethereum-native tools and Polkadot EVM networks. For plugin-specific 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:

1. Ensure your local node is running:

   npx hardhat node

2. 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:

1. Fund your deployment account with PAS test tokens from the Polkadot faucet.

2. 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.

3. Verify your private key is set:

   npx hardhat vars get PRIVATE_KEY

4. 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@1.5.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

View tests

Where to Go Next

• Deploy a Basic Contract

  ---

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

  → Get Started

• Deploy an ERC-20

  ---

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

  → Get Started

• Hardhat Documentation

  ---

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

  → Get Started

• Hardhat Polkadot Plugin

  ---

  Explore the full capabilities of the Hardhat Polkadot plugin.

  → Get Started