Skip to content

hardhat: fix docs according to expected kusama launch #563

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 8 commits into from
May 9, 2025
Merged

hardhat: fix docs according to expected kusama launch #563

Changes from 2 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
c80519f
hardhat: fix docs according to expected kusama launch
BigTava Apr 15, 2025
53de2db
fix: title
BigTava Apr 15, 2025
e63161a
feat: proposes hardhat.config and hardhat.md
BigTava Apr 21, 2025
2c028f8
fix: rename polkadotTestnest to westendHub
BigTava Apr 22, 2025
1d6e1f3
fix: replaces `npx hardhat node` with `npx hardhat node-polkavm`
BigTava Apr 23, 2025
f3be48a
docs: small changes in "Use Hardhat with Polkadot"
BigTava May 5, 2025
29d122d
docs: minor fixes
BigTava May 8, 2025
37ad3e8
Merge remote-tracking branch 'upstream/staging-ah-smart-contracts' in…
BigTava May 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 38 additions & 38 deletions develop/smart-contracts/dev-environments/hardhat.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: Use Hardhat with Asset Hub
description: Learn how to create, compile, test, and deploy smart contracts on Asset Hub using Hardhat, a powerful development environment for blockchain developers.
title: Use Hardhat with Polkadot Hub
description: Learn how to create, compile, test, and deploy smart contracts on Polkadot Hub using Hardhat, a powerful development environment for blockchain developers.
---

# Hardhat
Expand Down Expand Up @@ -51,10 +51,10 @@ Before getting started, ensure you have:
npm install --save-dev hardhat @nomicfoundation/hardhat-toolbox
```

To interact with Asset Hub, Hardhat requires the [`hardhat-resolc`](https://www.npmjs.com/package/hardhat-resolc){target=\_blank} plugin to compile contracts to PolkaVM bytecode and the [`hardhat-revive-node`](https://www.npmjs.com/package/hardhat-revive-node){target=\_blank} plugin to spawn a local node compatible with PolkaVM.
To interact with Polkadot Hub, Hardhat requires a plugin to compile contracts to PolkaVM bytecode and the and to spawn a local node compatible with PolkaVM.

```bash
npm install --save-dev hardhat-resolc hardhat-revive-node
npm install --save-dev @parity/hardhat-polkadot
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What's the reason for this update? I checked https://www.npmjs.com/ and there is no package named @parity/hardhat-polkadot, so If we move on with this change the instruction would not work

Copy link
Author

@BigTava BigTava Apr 21, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We are releasing an umbrella package to 1) simplify onboarding 2) simplify adding more packages/features without the user having to install them

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What do you think about this move?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, having only one package will be much better for devs, I fully agree with that. However, I was suggesting that we need to implement this change only after the package has been deployed and we confirm that the command npm install @parity/hardhat-polkadot actually works

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Absolutely. This PR should only be merged after the package is available

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ah okay, I'd put this PR as a draft PR then, and it will get unblock once that package is available :)

```

4. Create a Hardhat project:
Expand All @@ -80,9 +80,9 @@ Before getting started, ensure you have:

## Compiling Your Contract

The `hardhat-resolc` plugin will compile your Solidity contracts for Solidity versions `0.8.0` and higher to be PolkaVM compatible. When compiling your contract using the `hardhat-resolc` plugin, there are two ways to configure your compilation process:
The plugin will compile your Solidity contracts for Solidity versions `0.8.0` and higher to be PolkaVM compatible. When compiling your contract, there are two ways to configure your compilation process:

- **Remix compiler** - uses the Remix online compiler backend for simplicity and ease of use
- **Npm compiler** - uses library [@parity/revive](https://www.npmjs.com/package/@parity/revive){target=\_blank} for simplicity and ease of use
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can the @parity/revive be integrated into the hardhat workflow? Otherwise I think this would be misleading

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh just saw that you can do:

resolc: {
    compilerSource: 'npm',
    settings: {},
  },

Would it be possible to add a complete example of how to use npm, then, so users can compare the binary and the npm library

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can the @parity/revive be integrated into the hardhat workflow

@parity/revive is already integrated right? Users don't have to install it.

Would it be possible to add a complete example of how to use npm

Is npm.config.ts enough? I am proposing we add full project examples and not just the hardhat.config.ts? What do you think? In addition to this, do you think users will use binary configuration? What if they don't even add this "resolc" key to config? We just compile the thing if the package is imported and if someone wants to debug the compiler they can configure the "resolc" with the binary. Looking forward to your feedback

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We do have some full project examples available here - https://github.com/polkadot-developers/polkavm-hardhat-examples

From my experience, the binary configuration was quite complex from a developer experience standpoint. I had to download the binary, switch the solc version on my machine to a compatible one, and then check out and compile a matching version of the Polkadot SDK to generate a compatible substrate-node and eth-rpc-adapter.

Now that there's an npm-based option, I think we should emphasize using that as much as possible.

That said, for this guide—which serves as a starting point for developers—I suggest we explain both approaches. We can highlight the npm.config.ts setup (https://github.com/paritytech/hardhat-polkadot/blob/main/examples/npm.config.ts) and pull that file directly from the Hardhat repo to avoid duplication. After covering the npm path, we can still include the binary configuration for projects that might require customizing the resolc binary, as you mentioned.

@BigTava, what do you think?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We do have some full project examples available here

Nice! Where will you feature these? I think it is key we have an examples folder too in our repo. They will also be part of our e2e test suite. Maybe you could just link to our folder so we reduce maintenance overhead.

what do you think

I think we shouldn't frame 2 options. We just mention there is a more advanced option to compile the contracts. The user shouldn't even need to configure the compiler. It just needs to import the package and it uses the npm as default. For now, let's keep as is and rename Remix -> Npm. But, if you agree, we would reduce the step "Compiling Your Contract" to just step 2 and 3 and briefly mention the binary configuration.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice! Where will you feature these? I think it is key we have an examples folder too in our repo. They will also be part of our e2e test suite. Maybe you could just link to our folder so we reduce maintenance overhead.

I believe that for tutorials, we should keep them in the repository I shared previously since it would be easier to update those projects as the tutorial requires if we need to adjust something in the documentation. However, if you all add some projects and examples in the Hardhat Revive repository, we can also add references so that people can check different use cases as soon as those projects are pinned to a specific tag or release, ensuring that the documentation does not break even if the project gets updated.

I think we shouldn't frame 2 options. We just mention there is a more advanced option to compile the contracts. The user shouldn't even need to configure the compiler. It just needs to import the package and it uses the npm as default. For now, let's keep as is and rename Remix -> Npm. But, if you agree, we would reduce the step "Compiling Your Contract" to just step 2 and 3 and briefly mention the binary configuration.

I like this, yeah I agree!

- **Binary compiler** - uses the resolc binary directly for more control and configuration options
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- **Binary compiler** - uses the resolc binary directly for more control and configuration options
- **Binary compiler** - uses your local `resolc` binary directly for more control and configuration options

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks!


To compile your project, follow these instructions:
Expand All @@ -109,7 +109,7 @@ To compile your project, follow these instructions:
--8<-- 'code/develop/smart-contracts/dev-environments/hardhat/hardhat.config.js:65:66'
```

For the binary configuration, replace `INSERT_PATH_TO_RESOLC_COMPILER` with the proper path to the binary. For more information about its installation, check the [installation](https://github.com/paritytech/revive?tab=readme-ov-file#installation){target=\_blank} section of the `pallet-revive`.
For the binary configuration, check the [installation](https://github.com/paritytech/revive?tab=readme-ov-file#installation){target=\_blank} section of the `pallet-revive`.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wouldn't remove "replace INSERT_PATH_TO_RESOLC_COMPILER with the proper path to the binary. For more information about its installation,". This aims to add clarity for those who have no experience with the plugin, so if we take this out, it would be harder to grasp. Would you agree @BigTava ?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agree, thanks

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you please roll back this change?


2. Compile the contract with Hardhat:

Expand All @@ -127,32 +127,6 @@ To compile your project, follow these instructions:

## Testing Your Contract

When testing your contract, be aware that [`@nomicfoundation/hardhat-toolbox/network-helpers`](https://hardhat.org/hardhat-network-helpers/docs/overview){target=\_blank} is not fully compatible with Asset Hub's available RPCs. Specifically, Hardhat-only helpers like `time` and `loadFixture` may not work due to missing RPC calls in the node. For more details, refer to the [Compatibility](https://github.com/paritytech/hardhat-revive/tree/main/packages/hardhat-revive-node#compatibility){target=\_blank} section in the `hardhat-revive` docs.

You should avoid using helpers like `time` and `loadFixture` when writing tests. For example, for the `Lock.sol` contract, you can replace the default test file under `tests/Lock.js` with the following logic:

```javascript title="Lock.js"
--8<-- "code/develop/smart-contracts/dev-environments/hardhat/lock-test.js"
```

To run your test, execute the following command:

```bash
npx hardhat test
```

## Deploying with a Local Node

Before deploying to a live network, you can deploy your contract to a local node using the [`hardhat-revive-node`](https://www.npmjs.com/package/hardhat-revive-node){target=\_blank} plugin and Ignition modules:

!!! warning "Contract Size Limitation in Testing Environment"

When testing or deploying large contracts in Hardhat's local environment, you may encounter this error:

`Error: the initcode size of this transaction is too large`

This limitation is established by Hardhat based on Ethereum's default contract size limits. While Hardhat can disable this limitation, technical constraints currently prevent it from being applied to the PolkaVM test environment.

1. First, ensure you have compiled a Substrate node and the ETH RPC adapter from the Polkadot SDK. Checkout the [compatible commit](https://github.com/paritytech/polkadot-sdk/commit/c29e72a8628835e34deb6aa7db9a78a2e4eabcee){target=\_blank} from the SDK and build the node and the ETH-RPC from source:

```bash
Expand Down Expand Up @@ -203,7 +177,33 @@ Before deploying to a live network, you can deploy your contract to a local node
adapterBinaryPath: '/home/username/polkadot-sdk/target/release/eth-rpc',
```

3. Modify the Ignition modules, considering that the value of the pallet revive `block.timestamp` is returned in seconds. Check this [PR](https://github.com/paritytech/polkadot-sdk/pull/7792/files){target=\_blank} for more information. For example, for the default `ignition/modules/Lock.js` file, the needed modification should be:
When testing your contract, be aware that [`@nomicfoundation/hardhat-toolbox/network-helpers`](https://hardhat.org/hardhat-network-helpers/docs/overview){target=\_blank} is not fully compatible with Asset Hub's available RPCs. Specifically, Hardhat-only helpers like `time` and `loadFixture` may not work due to missing RPC calls in the node. For more details, refer to the [Compatibility](https://github.com/paritytech/hardhat-polkadot#compatibility){target=\_blank} section docs.

You should avoid using helpers like `time` and `loadFixture` when writing tests. For example, for the `Lock.sol` contract, you can replace the default test file under `tests/Lock.js` with the following logic:

```javascript title="Lock.js"
--8<-- "code/develop/smart-contracts/dev-environments/hardhat/lock-test.js"
```

To run your test, execute the following command:

```bash
npx hardhat test
```

## Deploying with a Local Node

Before deploying to a live network, you can deploy your contract to a local node using the [`hardhat-revive-node`](https://www.npmjs.com/package/hardhat-revive-node){target=\_blank} plugin and Ignition modules:

!!! warning "Contract Size Limitation in Testing Environment"

When testing or deploying large contracts in Hardhat's local environment, you may encounter this error:

`Error: the initcode size of this transaction is too large`

This limitation is established by Hardhat based on Ethereum's default contract size limits. While Hardhat can disable this limitation, technical constraints currently prevent it from being applied to the PolkaVM test environment.

1. Modify the Ignition modules, considering that the value of the pallet revive `block.timestamp` is returned in seconds. Check this [PR](https://github.com/paritytech/polkadot-sdk/pull/7792/files){target=\_blank} for more information. For example, for the default `ignition/modules/Lock.js` file, the needed modification should be:

```diff
- const JAN_1ST_2030 = 1893456000;
Expand All @@ -216,15 +216,15 @@ Before deploying to a live network, you can deploy your contract to a local node
--8<-- 'code/develop/smart-contracts/dev-environments/hardhat/lock-ignition.js'
```

4. Start a local node:
2. Start a local node:

```bash
npx hardhat node-polkavm
```

This command will start a local PolkaVM node powered by the `hardhat-revive-node` plugin.

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

```bash
npx hardhat ignition deploy ./ignition/modules/INSERT_IGNITION_MODULE_NAME.js --network localNode
Expand Down Expand Up @@ -263,7 +263,7 @@ After testing your contract locally, you can deploy it to a live network. This g
--8<-- 'code/develop/smart-contracts/dev-environments/hardhat/hardhat.config.js:66:66'
```

5. Update your Hardhat configuration file with network settings for the Asset Hub network you want to target:
5. Update your Hardhat configuration file with network settings for the Polkadot Hub network you want to target:

=== "Remix Configuration"

Expand Down Expand Up @@ -303,7 +303,7 @@ For example, for the default `Lock.sol` contract, you can use the following file
Run your interaction script:

```bash
npx hardhat run scripts/interact.js --network westendAssetHub
npx hardhat run scripts/interact.js --network polkadotHub
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps this should be westendHub, in any case, this also requires updating the hardhat.config.js code snippet

Copy link
Author

@BigTava BigTava Apr 21, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We want to avoid using anything but polkadot, to reduce friction. polkadotHub is already a stretch for technical audiences. What is your opinion on this?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Mmm, I do understand your point, and I think @0xLucca worked in a PR to emphasize the usage of Polkadot Hub here - https://github.com/polkadot-developers/polkadot-docs/pull/572/files

But in this case, how would we differentiate if a user is trying to interact with Westend Asset Hub or polkadot asset hub? That's why I thought about using Westend Hub, as it'd be changed here

Copy link
Author

@BigTava BigTava Apr 21, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Exactly, the PR 572 is good. You're right, what about just calling it here in the docs polkadotTestnet? IMO, it would help developers associate westend as a testnet of Polkadot. In the end, I am just trying to minimize the different names we use, which cause real pain in developer onboarding. Polkadot is known for being quite confusing. The change starts here

Copy link
Collaborator

@nhussein11 nhussein11 Apr 21, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Totally, I agree with that point. I'm just a bit concerned about Paseo, because if, at some point, Paseo is also upgraded to support polkavm, the word polkadotTestnet would not be enough to cover both, westend and paseo. What do you think?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point. I will confirm that point. IMO developers only care, if testnet 1 is better than testnet 2 for some reason. If not, they just care it is a testnet

```

## Where to Go Next
Expand Down