From 3f5a769db5f3ad7d654a5328841bdf5c4b57feb3 Mon Sep 17 00:00:00 2001 From: nhussein11 Date: Tue, 11 Nov 2025 10:02:59 -0300 Subject: [PATCH 1/6] Add troubleshooting guide for Hardhat on Polkadot Hub --- .../hardhat/troubleshooting.md | 702 +++++++++++++++++- 1 file changed, 701 insertions(+), 1 deletion(-) diff --git a/smart-contracts/dev-environments/hardhat/troubleshooting.md b/smart-contracts/dev-environments/hardhat/troubleshooting.md index 30404ce4c..34f7a0350 100644 --- a/smart-contracts/dev-environments/hardhat/troubleshooting.md +++ b/smart-contracts/dev-environments/hardhat/troubleshooting.md @@ -1 +1,701 @@ -TODO \ No newline at end of file +--- +title: Troubleshooting Hardhat on Polkadot Hub +description: Solutions to common issues when developing, compiling, deploying, and testing smart contracts using Hardhat on Polkadot Hub. +categories: Smart Contracts, Tooling +--- + +# Troubleshooting Hardhat + +## Overview + +This guide provides solutions to common issues you may encounter when using Hardhat with Polkadot Hub. If you're experiencing problems with installation, compilation, deployment, testing, or contract interaction, you'll likely find the solution here. + +## Installation Issues + +### Node.js Version Incompatibility + +**Problem**: Hardhat fails to install or run with version-related errors. + +**Solutions**: + +1. **Check Node.js version**: + - Ensure you have an LTS version of Node.js installed (18.x, 20.x, or 22.x) + - Check your current version with `node --version` + - Download the appropriate LTS version from [nodejs.org](https://nodejs.org/) + +2. **Use nvm for version management**: + - Install nvm (Node Version Manager) to easily switch between Node versions + - Run `nvm install --lts` to install the latest LTS version + - Run `nvm use --lts` to switch to it + +### Hardhat Installation Fails + +**Problem**: npm fails to install Hardhat or its dependencies. + +**Solutions**: + +1. **Clear npm cache**: + ```bash + npm cache clean --force + ``` + +2. **Delete node_modules and package-lock.json**: + ```bash + rm -rf node_modules package-lock.json + npm install + ``` + +3. **Check npm version**: + - Ensure you have npm 7.x or higher + - Update npm with `npm install -g npm@latest` + +4. **Install with specific version**: + ```bash + npm install --save-dev hardhat@^2.26.0 + ``` + +### Hardhat Toolbox Plugin Issues + +**Problem**: Hardhat Toolbox fails to install or causes conflicts. + +**Solutions**: + +1. **Install Hardhat Toolbox separately**: + ```bash + npm install --save-dev @nomicfoundation/hardhat-toolbox + ``` + +2. **Check for peer dependency conflicts**: + - Review the error messages for conflicting package versions + - Try using `npm install --legacy-peer-deps` if conflicts persist + +## Compilation Issues + +### Contract Won't Compile + +**Problem**: Your contract fails to compile or shows errors in the terminal. + +**Solutions**: + +1. **Check Solidity version compatibility**: + - Ensure your contract's pragma statement matches the compiler version in `hardhat.config.js` + - Example: If your contract uses `pragma solidity ^0.8.0;`, set `solidity: "0.8.28"` or compatible version + +2. **Verify imports**: + - Ensure all imported contracts are in the correct paths + - For OpenZeppelin contracts, make sure they're installed: `npm install @openzeppelin/contracts` + +3. **Clear artifacts and cache**: + ```bash + npx hardhat clean + npx hardhat compile + ``` + +4. **Check for syntax errors**: + - Carefully read error messages in the terminal + - Common issues include missing semicolons, incorrect function visibility, or type mismatches + +### Compilation Artifacts Missing + +**Problem**: The artifacts folder is empty or missing expected files. + +**Solutions**: + +1. **Ensure compilation completed successfully**: + - Check the terminal output for any error messages + - Look for "Compiled X Solidity files successfully" message + +2. **Verify contract file location**: + - Contracts must be in the `contracts` directory or subdirectories + - File must have .sol extension + +3. **Check hardhat.config.js settings**: + - Ensure the paths configuration is correct + - Default artifacts location is `./artifacts` + +### Compiler Version Errors + +**Problem**: Errors related to Solidity compiler version or features. + +**Solutions**: + +1. **Match pragma version with config**: + ```javascript + module.exports = { + solidity: { + version: "0.8.28", + settings: { + optimizer: { + enabled: true, + runs: 200 + } + } + } + }; + ``` + +2. **Use multiple compiler versions** (if needed): + ```javascript + module.exports = { + solidity: { + compilers: [ + { version: "0.8.28" }, + { version: "0.8.20" } + ] + } + }; + ``` + +## Testing Issues + +### Tests Fail to Run + +**Problem**: Tests don't execute or Hardhat throws errors when running tests. + +**Solutions**: + +1. **Verify test file location**: + - Test files must be in the `test` directory + - Files should end with `.js` or `.test.js` + +2. **Check test framework imports**: + ```javascript + const { expect } = require("chai"); + const { ethers } = require("hardhat"); + ``` + +3. **Ensure Hardhat Toolbox is installed**: + ```bash + npm install --save-dev @nomicfoundation/hardhat-toolbox + ``` + +4. **Run tests with verbose output**: + ```bash + npx hardhat test --verbose + ``` + +### Local Test Network Issues + +**Problem**: `npx hardhat node` fails to start or becomes unresponsive. + +**Solutions**: + +1. **Check if port 8545 is already in use**: + - Kill any process using port 8545 + - On Linux/Mac: `lsof -ti:8545 | xargs kill -9` + - On Windows: `netstat -ano | findstr :8545`, then kill the process with the appropriate process ID. + +2. **Specify a different port**: + ```bash + npx hardhat node --port 8546 + ``` + +3. **Reset the node**: + - Stop the node (Ctrl+C) + - Start it again with a fresh state + +### Test Assertions Failing + +**Problem**: Tests run but fail with assertion errors. + +**Solutions**: + +1. **Check account balances**: + - Ensure test accounts have sufficient ETH + - Hardhat node provides test accounts with 10,000 ETH each + +2. **Wait for transaction confirmations**: + ```javascript + const tx = await contract.someFunction(); + await tx.wait(); // Wait for transaction to be mined + ``` + +3. **Verify contract state**: + - Use console.log to debug values + - Check if contract was properly deployed in beforeEach hooks + +4. **Review timing issues**: + - Add appropriate waits between transactions + - Use `await ethers.provider.send("evm_mine")` to mine blocks manually + +## Network Configuration Issues + +### Cannot Connect to Local Development Node + +**Problem**: Hardhat cannot connect to the local development node. + +**Solutions**: + +1. **Verify the node is running**: + - Ensure your local development node is started + - Check the [Local Development Node](/smart-contracts/dev-environments/local-dev-node/) guide + +2. **Check network configuration**: + ```javascript + module.exports = { + networks: { + polkadotTestNet: { + url: "http://localhost:8545", + chainId: 420420420, + accounts: [PRIVATE_KEY] + } + } + }; + ``` + +3. **Verify URL and port**: + - Ensure the URL matches your local node's RPC endpoint + - Default is usually `http://localhost:8545` + +4. **Check firewall settings**: + - Ensure your firewall allows connections to localhost:8545 + +### Private Key Configuration Issues + +**Problem**: Hardhat cannot access or use the configured private key. + +**Solutions**: + +1. **Verify private key is set**: + ```bash + npx hardhat vars get PRIVATE_KEY + ``` + +2. **Set private key correctly**: + ```bash + npx hardhat vars set PRIVATE_KEY "0x..." + ``` + - Ensure the key starts with "0x" + - Do not include quotes within the actual key value + +3. **Check key format in config**: + ```javascript + const { vars } = require("hardhat/config"); + const PRIVATE_KEY = vars.get("PRIVATE_KEY"); + + module.exports = { + networks: { + polkadotTestNet: { + accounts: [PRIVATE_KEY] // Should be an array + } + } + }; + ``` + +4. **Alternative: Use mnemonic**: + ```javascript + accounts: { + mnemonic: "test test test test test test test test test test test junk" + } + ``` + +### Wrong Network Selected + +**Problem**: Deployment or transactions go to the wrong network. + +**Solutions**: + +1. **Specify network explicitly**: + ```bash + npx hardhat run scripts/deploy.js --network polkadotTestNet + ``` + +2. **Verify network in config**: + - Check that the network name matches what you're using in commands + - Ensure chainId matches the target network + +3. **Check default network**: + ```javascript + module.exports = { + defaultNetwork: "polkadotTestNet", + networks: { + // network configs + } + }; + ``` + +## Deployment Issues + +### Insufficient Funds Error + +**Problem**: Deployment fails with "insufficient funds" error. + +**Solutions**: + +1. **Check account balance**: + - Verify you have enough test tokens in your account + - For local development node, accounts should be pre-funded + +2. **Get test tokens**: + - Visit the [Polkadot faucet](/smart-contracts/faucet/){target=\_blank} for test networks + - Wait a few minutes for faucet transactions to complete + +3. **Verify account address**: + - Ensure the private key corresponds to the account you think you're using + - Check the account balance matches expectations + +### Ignition Deployment Fails + +**Problem**: Deployment using Hardhat Ignition fails or throws errors. + +**Solutions**: + +1. **Check Ignition module syntax**: + ```javascript + const { buildModule } = require("@nomicfoundation/hardhat-ignition/modules"); + + module.exports = buildModule("LockModule", (m) => { + const unlockTime = m.getParameter("unlockTime"); + const lock = m.contract("Lock", [unlockTime]); + return { lock }; + }); + ``` + +2. **Verify constructor parameters**: + - Ensure all required constructor parameters are provided + - Check parameter types match the contract's constructor + +3. **Clear previous deployments**: + ```bash + rm -rf ignition/deployments/ + ``` + +4. **Use deployment script alternative**: + - Create a manual deployment script in the `scripts` folder if Ignition continues to fail + +### Deployment Script Errors + +**Problem**: Custom deployment scripts fail to execute. + +**Solutions**: + +1. **Check script imports**: + ```javascript + const hre = require("hardhat"); + // or + const { ethers } = require("hardhat"); + ``` + +2. **Verify contract factory**: + ```javascript + const Contract = await ethers.getContractFactory("ContractName"); + const contract = await Contract.deploy(/* constructor args */); + await contract.deployed(); + ``` + +3. **Add error handling**: + ```javascript + try { + // deployment code + } catch (error) { + console.error("Deployment failed:", error); + process.exit(1); + } + ``` + +4. **Check gas settings**: + ```javascript + const contract = await Contract.deploy({ + gasLimit: 5000000 + }); + ``` + +### Contract Deployment Timeout + +**Problem**: Deployment hangs or times out. + +**Solutions**: + +1. **Increase timeout in config**: + ```javascript + module.exports = { + networks: { + polkadotTestNet: { + timeout: 60000 // 60 seconds + } + } + }; + ``` + +2. **Check network connection**: + - Verify the RPC endpoint is responsive + - Test with a simple read operation first + +3. **Reduce contract complexity**: + - Large contracts may take longer to deploy + - Consider splitting into multiple contracts + +## Contract Interaction Issues + +### Cannot Connect to Deployed Contract + +**Problem**: Scripts fail to interact with a deployed contract. + +**Solutions**: + +1. **Verify contract address**: + - Ensure you're using the correct deployed contract address + - Check the deployment output or Ignition deployment files + +2. **Check contract ABI**: + ```javascript + const Contract = await ethers.getContractFactory("ContractName"); + const contract = Contract.attach(contractAddress); + ``` + +3. **Verify network connection**: + - Ensure you're connected to the same network where the contract was deployed + - Use the `--network` flag when running scripts + +### Transaction Reverts + +**Problem**: Transactions revert when calling contract functions. + +**Solutions**: + +1. **Check function requirements**: + - Verify all require() conditions in the contract are satisfied + - Ensure you're meeting any access control requirements + +2. **Add debugging**: + ```javascript + try { + const tx = await contract.someFunction(); + const receipt = await tx.wait(); + console.log("Transaction successful:", receipt); + } catch (error) { + console.error("Transaction failed:", error.message); + } + ``` + +3. **Check gas limits**: + ```javascript + const tx = await contract.someFunction({ + gasLimit: 500000 + }); + ``` + +4. **Verify function parameters**: + - Ensure parameter types match the function signature + - Check for correct number of parameters + +### Read Functions Not Returning Values + +**Problem**: View/pure functions don't return expected values. + +**Solutions**: + +1. **Use call() for read-only functions**: + ```javascript + const value = await contract.someViewFunction(); + console.log("Returned value:", value); + ``` + +2. **Check contract state**: + - Verify the contract has been properly initialized + - Ensure any required state changes have been completed + +3. **Handle BigNumber returns**: + ```javascript + const value = await contract.someFunction(); + console.log("Value:", value.toString()); + ``` + +### Write Functions Not Updating State + +**Problem**: State-changing functions execute but don't update state. + +**Solutions**: + +1. **Wait for transaction confirmation**: + ```javascript + const tx = await contract.someFunction(); + await tx.wait(); // Wait for the transaction to be mined + const newState = await contract.getState(); + ``` + +2. **Check transaction receipt**: + ```javascript + const tx = await contract.someFunction(); + const receipt = await tx.wait(); + console.log("Transaction status:", receipt.status); + ``` + +3. **Verify transaction success**: + - Check that receipt.status === 1 (success) + - Review any events emitted by the transaction + +4. **Check for reverts**: + - Look for revert reasons in the error message + - Verify contract logic and access controls + +## Performance and Configuration Issues + +### Compilation is Slow + +**Problem**: Contract compilation takes a long time. + +**Solutions**: + +1. **Enable compiler cache**: + - Hardhat caches compilation results by default + - Ensure the cache folder is not ignored in .gitignore + +2. **Optimize compiler settings**: + ```javascript + module.exports = { + solidity: { + version: "0.8.28", + settings: { + optimizer: { + enabled: true, + runs: 200 + } + } + } + }; + ``` + +3. **Compile specific contracts**: + ```bash + npx hardhat compile --force + ``` + +### Hardhat Console Issues + +**Problem**: Cannot start Hardhat console or console commands fail. + +**Solutions**: + +1. **Start console with correct network**: + ```bash + npx hardhat console --network polkadotTestNet + ``` + +2. **Check console imports**: + ```javascript + // In console + const Contract = await ethers.getContractFactory("ContractName"); + ``` + +3. **Verify network connection**: + - Ensure the target network is accessible + - Check network configuration in hardhat.config.js + +### Plugin Configuration Issues + +**Problem**: Hardhat plugins not working correctly. + +**Solutions**: + +1. **Verify plugin installation**: + ```bash + npm list @nomicfoundation/hardhat-toolbox + ``` + +2. **Check plugin import in config**: + ```javascript + require("@nomicfoundation/hardhat-toolbox"); + ``` + +3. **Update plugins to latest versions**: + ```bash + npm update @nomicfoundation/hardhat-toolbox + ``` + +4. **Check for plugin conflicts**: + - Review package.json for version conflicts + - Try removing and reinstalling conflicting plugins + +## Environment Variable Issues + +### Cannot Access Environment Variables + +**Problem**: Scripts cannot read environment variables. + +**Solutions**: + +1. **Use Hardhat vars correctly**: + ```bash + npx hardhat vars set VARIABLE_NAME "value" + npx hardhat vars get VARIABLE_NAME + ``` + +2. **Alternative: Use dotenv**: + ```bash + npm install dotenv + ``` + ```javascript + require('dotenv').config(); + const value = process.env.VARIABLE_NAME; + ``` + +3. **Check variable access in config**: + ```javascript + const { vars } = require("hardhat/config"); + const value = vars.get("VARIABLE_NAME"); + ``` + +### Private Key Security Warnings + +**Problem**: Concerns about private key security. + +**Solutions**: + +1. **Never commit private keys**: + - Add `.env` to .gitignore if using dotenv + - Hardhat vars are stored locally and not in git + +2. **Use test accounts for development**: + - Use the pre-funded accounts from `npx hardhat node` + - Never use real private keys for testing + +3. **Verify .gitignore includes**: + ``` + node_modules + .env + coverage + cache + artifacts + ignition/deployments/ + ``` + +## Where to Go Next + +Continue improving your Hardhat workflow with these resources: + +
+ +- Guide __Get Started with Hardhat__ + + --- + + Return to the basics and review the Hardhat setup process. + + [:octicons-arrow-right-24: Get Started](/smart-contracts/dev-environments/hardhat/get-started) + +- Guide __Compile and Test Smart Contracts__ + + --- + + Learn how to compile and test your smart contracts using Hardhat. + + [:octicons-arrow-right-24: Get Started](/smart-contracts/dev-environments/hardhat/compile-and-test) + +- Guide __Deploy Smart Contracts__ + + --- + + Learn how to deploy and interact with smart contracts using Hardhat. + + [:octicons-arrow-right-24: Get Started](/smart-contracts/dev-environments/hardhat/deploy-a-contract) + +- External __Hardhat Documentation__ + + --- + + Explore official Hardhat documentation for advanced troubleshooting. + + [:octicons-arrow-right-24: Visit Docs](https://hardhat.org/docs){target=\_blank} + +
\ No newline at end of file From 0b52915e963f783535756a2d6a911260b2e1c4d6 Mon Sep 17 00:00:00 2001 From: nhussein11 Date: Tue, 11 Nov 2025 10:03:04 -0300 Subject: [PATCH 2/6] Remove 'Verify a Contract' section and its corresponding documentation from Hardhat navigation. --- smart-contracts/dev-environments/hardhat/.nav.yml | 1 - smart-contracts/dev-environments/hardhat/verify-a-contract.md | 1 - 2 files changed, 2 deletions(-) delete mode 100644 smart-contracts/dev-environments/hardhat/verify-a-contract.md diff --git a/smart-contracts/dev-environments/hardhat/.nav.yml b/smart-contracts/dev-environments/hardhat/.nav.yml index d47646582..aa1cef6da 100644 --- a/smart-contracts/dev-environments/hardhat/.nav.yml +++ b/smart-contracts/dev-environments/hardhat/.nav.yml @@ -3,5 +3,4 @@ nav: - 'Install and Config': install-and-config.md - 'Compile and Test': compile-and-test.md - 'Deploy a Contract': deploy-a-contract.md - - 'Verify a Contract': verify-a-contract.md - 'Troubleshooting': troubleshooting.md diff --git a/smart-contracts/dev-environments/hardhat/verify-a-contract.md b/smart-contracts/dev-environments/hardhat/verify-a-contract.md deleted file mode 100644 index 30404ce4c..000000000 --- a/smart-contracts/dev-environments/hardhat/verify-a-contract.md +++ /dev/null @@ -1 +0,0 @@ -TODO \ No newline at end of file From 0ba7529ad53278b227c5693f4b2944ac3dfeafa3 Mon Sep 17 00:00:00 2001 From: nhussein11 Date: Tue, 11 Nov 2025 10:04:29 -0300 Subject: [PATCH 3/6] fix: llms --- .ai/categories/smart-contracts.md | 705 ++++++++++++++++++ .ai/categories/tooling.md | 705 ++++++++++++++++++ ...ev-environments-hardhat-troubleshooting.md | 699 ++++++++++++++++- .ai/site-index.json | 195 ++++- llms-full.jsonl | 35 + llms.txt | 3 +- 6 files changed, 2331 insertions(+), 11 deletions(-) diff --git a/.ai/categories/smart-contracts.md b/.ai/categories/smart-contracts.md index 65cacb7c7..d38467093 100644 --- a/.ai/categories/smart-contracts.md +++ b/.ai/categories/smart-contracts.md @@ -15262,6 +15262,711 @@ You now know the weight system, how it affects transaction fee computation, and - [Web3 Foundation Research](https://research.web3.foundation/Polkadot/overview/token-economics#relay-chain-transaction-fees-and-per-block-transaction-limits){target=\_blank} +--- + +Page Title: Troubleshooting Hardhat on Polkadot Hub + +- Source (raw): https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/smart-contracts-dev-environments-hardhat-troubleshooting.md +- Canonical (HTML): https://docs.polkadot.com/smart-contracts/dev-environments/hardhat/troubleshooting/ +- Summary: Solutions to common issues when developing, compiling, deploying, and testing smart contracts using Hardhat on Polkadot Hub. + +# Troubleshooting Hardhat + +## Overview + +This guide provides solutions to common issues you may encounter when using Hardhat with Polkadot Hub. If you're experiencing problems with installation, compilation, deployment, testing, or contract interaction, you'll likely find the solution here. + +## Installation Issues + +### Node.js Version Incompatibility + +**Problem**: Hardhat fails to install or run with version-related errors. + +**Solutions**: + +1. **Check Node.js version**: + - Ensure you have an LTS version of Node.js installed (18.x, 20.x, or 22.x) + - Check your current version with `node --version` + - Download the appropriate LTS version from [nodejs.org](https://nodejs.org/) + +2. **Use nvm for version management**: + - Install nvm (Node Version Manager) to easily switch between Node versions + - Run `nvm install --lts` to install the latest LTS version + - Run `nvm use --lts` to switch to it + +### Hardhat Installation Fails + +**Problem**: npm fails to install Hardhat or its dependencies. + +**Solutions**: + +1. **Clear npm cache**: + ```bash + npm cache clean --force + ``` + +2. **Delete node_modules and package-lock.json**: + ```bash + rm -rf node_modules package-lock.json + npm install + ``` + +3. **Check npm version**: + - Ensure you have npm 7.x or higher + - Update npm with `npm install -g npm@latest` + +4. **Install with specific version**: + ```bash + npm install --save-dev hardhat@^2.26.0 + ``` + +### Hardhat Toolbox Plugin Issues + +**Problem**: Hardhat Toolbox fails to install or causes conflicts. + +**Solutions**: + +1. **Install Hardhat Toolbox separately**: + ```bash + npm install --save-dev @nomicfoundation/hardhat-toolbox + ``` + +2. **Check for peer dependency conflicts**: + - Review the error messages for conflicting package versions + - Try using `npm install --legacy-peer-deps` if conflicts persist + +## Compilation Issues + +### Contract Won't Compile + +**Problem**: Your contract fails to compile or shows errors in the terminal. + +**Solutions**: + +1. **Check Solidity version compatibility**: + - Ensure your contract's pragma statement matches the compiler version in `hardhat.config.js` + - Example: If your contract uses `pragma solidity ^0.8.0;`, set `solidity: "0.8.28"` or compatible version + +2. **Verify imports**: + - Ensure all imported contracts are in the correct paths + - For OpenZeppelin contracts, make sure they're installed: `npm install @openzeppelin/contracts` + +3. **Clear artifacts and cache**: + ```bash + npx hardhat clean + npx hardhat compile + ``` + +4. **Check for syntax errors**: + - Carefully read error messages in the terminal + - Common issues include missing semicolons, incorrect function visibility, or type mismatches + +### Compilation Artifacts Missing + +**Problem**: The artifacts folder is empty or missing expected files. + +**Solutions**: + +1. **Ensure compilation completed successfully**: + - Check the terminal output for any error messages + - Look for "Compiled X Solidity files successfully" message + +2. **Verify contract file location**: + - Contracts must be in the `contracts` directory or subdirectories + - File must have .sol extension + +3. **Check hardhat.config.js settings**: + - Ensure the paths configuration is correct + - Default artifacts location is `./artifacts` + +### Compiler Version Errors + +**Problem**: Errors related to Solidity compiler version or features. + +**Solutions**: + +1. **Match pragma version with config**: + ```javascript + module.exports = { + solidity: { + version: "0.8.28", + settings: { + optimizer: { + enabled: true, + runs: 200 + } + } + } + }; + ``` + +2. **Use multiple compiler versions** (if needed): + ```javascript + module.exports = { + solidity: { + compilers: [ + { version: "0.8.28" }, + { version: "0.8.20" } + ] + } + }; + ``` + +## Testing Issues + +### Tests Fail to Run + +**Problem**: Tests don't execute or Hardhat throws errors when running tests. + +**Solutions**: + +1. **Verify test file location**: + - Test files must be in the `test` directory + - Files should end with `.js` or `.test.js` + +2. **Check test framework imports**: + ```javascript + const { expect } = require("chai"); + const { ethers } = require("hardhat"); + ``` + +3. **Ensure Hardhat Toolbox is installed**: + ```bash + npm install --save-dev @nomicfoundation/hardhat-toolbox + ``` + +4. **Run tests with verbose output**: + ```bash + npx hardhat test --verbose + ``` + +### Local Test Network Issues + +**Problem**: `npx hardhat node` fails to start or becomes unresponsive. + +**Solutions**: + +1. **Check if port 8545 is already in use**: + - Kill any process using port 8545 + - On Linux/Mac: `lsof -ti:8545 | xargs kill -9` + - On Windows: `netstat -ano | findstr :8545`, then kill the process with the appropriate process ID. + +2. **Specify a different port**: + ```bash + npx hardhat node --port 8546 + ``` + +3. **Reset the node**: + - Stop the node (Ctrl+C) + - Start it again with a fresh state + +### Test Assertions Failing + +**Problem**: Tests run but fail with assertion errors. + +**Solutions**: + +1. **Check account balances**: + - Ensure test accounts have sufficient ETH + - Hardhat node provides test accounts with 10,000 ETH each + +2. **Wait for transaction confirmations**: + ```javascript + const tx = await contract.someFunction(); + await tx.wait(); // Wait for transaction to be mined + ``` + +3. **Verify contract state**: + - Use console.log to debug values + - Check if contract was properly deployed in beforeEach hooks + +4. **Review timing issues**: + - Add appropriate waits between transactions + - Use `await ethers.provider.send("evm_mine")` to mine blocks manually + +## Network Configuration Issues + +### Cannot Connect to Local Development Node + +**Problem**: Hardhat cannot connect to the local development node. + +**Solutions**: + +1. **Verify the node is running**: + - Ensure your local development node is started + - Check the [Local Development Node](/smart-contracts/dev-environments/local-dev-node/) guide + +2. **Check network configuration**: + ```javascript + module.exports = { + networks: { + polkadotTestNet: { + url: "http://localhost:8545", + chainId: 420420420, + accounts: [PRIVATE_KEY] + } + } + }; + ``` + +3. **Verify URL and port**: + - Ensure the URL matches your local node's RPC endpoint + - Default is usually `http://localhost:8545` + +4. **Check firewall settings**: + - Ensure your firewall allows connections to localhost:8545 + +### Private Key Configuration Issues + +**Problem**: Hardhat cannot access or use the configured private key. + +**Solutions**: + +1. **Verify private key is set**: + ```bash + npx hardhat vars get PRIVATE_KEY + ``` + +2. **Set private key correctly**: + ```bash + npx hardhat vars set PRIVATE_KEY "0x..." + ``` + - Ensure the key starts with "0x" + - Do not include quotes within the actual key value + +3. **Check key format in config**: + ```javascript + const { vars } = require("hardhat/config"); + const PRIVATE_KEY = vars.get("PRIVATE_KEY"); + + module.exports = { + networks: { + polkadotTestNet: { + accounts: [PRIVATE_KEY] // Should be an array + } + } + }; + ``` + +4. **Alternative: Use mnemonic**: + ```javascript + accounts: { + mnemonic: "test test test test test test test test test test test junk" + } + ``` + +### Wrong Network Selected + +**Problem**: Deployment or transactions go to the wrong network. + +**Solutions**: + +1. **Specify network explicitly**: + ```bash + npx hardhat run scripts/deploy.js --network polkadotTestNet + ``` + +2. **Verify network in config**: + - Check that the network name matches what you're using in commands + - Ensure chainId matches the target network + +3. **Check default network**: + ```javascript + module.exports = { + defaultNetwork: "polkadotTestNet", + networks: { + // network configs + } + }; + ``` + +## Deployment Issues + +### Insufficient Funds Error + +**Problem**: Deployment fails with "insufficient funds" error. + +**Solutions**: + +1. **Check account balance**: + - Verify you have enough test tokens in your account + - For local development node, accounts should be pre-funded + +2. **Get test tokens**: + - Visit the [Polkadot faucet](/smart-contracts/faucet/){target=\_blank} for test networks + - Wait a few minutes for faucet transactions to complete + +3. **Verify account address**: + - Ensure the private key corresponds to the account you think you're using + - Check the account balance matches expectations + +### Ignition Deployment Fails + +**Problem**: Deployment using Hardhat Ignition fails or throws errors. + +**Solutions**: + +1. **Check Ignition module syntax**: + ```javascript + const { buildModule } = require("@nomicfoundation/hardhat-ignition/modules"); + + module.exports = buildModule("LockModule", (m) => { + const unlockTime = m.getParameter("unlockTime"); + const lock = m.contract("Lock", [unlockTime]); + return { lock }; + }); + ``` + +2. **Verify constructor parameters**: + - Ensure all required constructor parameters are provided + - Check parameter types match the contract's constructor + +3. **Clear previous deployments**: + ```bash + rm -rf ignition/deployments/ + ``` + +4. **Use deployment script alternative**: + - Create a manual deployment script in the `scripts` folder if Ignition continues to fail + +### Deployment Script Errors + +**Problem**: Custom deployment scripts fail to execute. + +**Solutions**: + +1. **Check script imports**: + ```javascript + const hre = require("hardhat"); + // or + const { ethers } = require("hardhat"); + ``` + +2. **Verify contract factory**: + ```javascript + const Contract = await ethers.getContractFactory("ContractName"); + const contract = await Contract.deploy(/* constructor args */); + await contract.deployed(); + ``` + +3. **Add error handling**: + ```javascript + try { + // deployment code + } catch (error) { + console.error("Deployment failed:", error); + process.exit(1); + } + ``` + +4. **Check gas settings**: + ```javascript + const contract = await Contract.deploy({ + gasLimit: 5000000 + }); + ``` + +### Contract Deployment Timeout + +**Problem**: Deployment hangs or times out. + +**Solutions**: + +1. **Increase timeout in config**: + ```javascript + module.exports = { + networks: { + polkadotTestNet: { + timeout: 60000 // 60 seconds + } + } + }; + ``` + +2. **Check network connection**: + - Verify the RPC endpoint is responsive + - Test with a simple read operation first + +3. **Reduce contract complexity**: + - Large contracts may take longer to deploy + - Consider splitting into multiple contracts + +## Contract Interaction Issues + +### Cannot Connect to Deployed Contract + +**Problem**: Scripts fail to interact with a deployed contract. + +**Solutions**: + +1. **Verify contract address**: + - Ensure you're using the correct deployed contract address + - Check the deployment output or Ignition deployment files + +2. **Check contract ABI**: + ```javascript + const Contract = await ethers.getContractFactory("ContractName"); + const contract = Contract.attach(contractAddress); + ``` + +3. **Verify network connection**: + - Ensure you're connected to the same network where the contract was deployed + - Use the `--network` flag when running scripts + +### Transaction Reverts + +**Problem**: Transactions revert when calling contract functions. + +**Solutions**: + +1. **Check function requirements**: + - Verify all require() conditions in the contract are satisfied + - Ensure you're meeting any access control requirements + +2. **Add debugging**: + ```javascript + try { + const tx = await contract.someFunction(); + const receipt = await tx.wait(); + console.log("Transaction successful:", receipt); + } catch (error) { + console.error("Transaction failed:", error.message); + } + ``` + +3. **Check gas limits**: + ```javascript + const tx = await contract.someFunction({ + gasLimit: 500000 + }); + ``` + +4. **Verify function parameters**: + - Ensure parameter types match the function signature + - Check for correct number of parameters + +### Read Functions Not Returning Values + +**Problem**: View/pure functions don't return expected values. + +**Solutions**: + +1. **Use call() for read-only functions**: + ```javascript + const value = await contract.someViewFunction(); + console.log("Returned value:", value); + ``` + +2. **Check contract state**: + - Verify the contract has been properly initialized + - Ensure any required state changes have been completed + +3. **Handle BigNumber returns**: + ```javascript + const value = await contract.someFunction(); + console.log("Value:", value.toString()); + ``` + +### Write Functions Not Updating State + +**Problem**: State-changing functions execute but don't update state. + +**Solutions**: + +1. **Wait for transaction confirmation**: + ```javascript + const tx = await contract.someFunction(); + await tx.wait(); // Wait for the transaction to be mined + const newState = await contract.getState(); + ``` + +2. **Check transaction receipt**: + ```javascript + const tx = await contract.someFunction(); + const receipt = await tx.wait(); + console.log("Transaction status:", receipt.status); + ``` + +3. **Verify transaction success**: + - Check that receipt.status === 1 (success) + - Review any events emitted by the transaction + +4. **Check for reverts**: + - Look for revert reasons in the error message + - Verify contract logic and access controls + +## Performance and Configuration Issues + +### Compilation is Slow + +**Problem**: Contract compilation takes a long time. + +**Solutions**: + +1. **Enable compiler cache**: + - Hardhat caches compilation results by default + - Ensure the cache folder is not ignored in .gitignore + +2. **Optimize compiler settings**: + ```javascript + module.exports = { + solidity: { + version: "0.8.28", + settings: { + optimizer: { + enabled: true, + runs: 200 + } + } + } + }; + ``` + +3. **Compile specific contracts**: + ```bash + npx hardhat compile --force + ``` + +### Hardhat Console Issues + +**Problem**: Cannot start Hardhat console or console commands fail. + +**Solutions**: + +1. **Start console with correct network**: + ```bash + npx hardhat console --network polkadotTestNet + ``` + +2. **Check console imports**: + ```javascript + // In console + const Contract = await ethers.getContractFactory("ContractName"); + ``` + +3. **Verify network connection**: + - Ensure the target network is accessible + - Check network configuration in hardhat.config.js + +### Plugin Configuration Issues + +**Problem**: Hardhat plugins not working correctly. + +**Solutions**: + +1. **Verify plugin installation**: + ```bash + npm list @nomicfoundation/hardhat-toolbox + ``` + +2. **Check plugin import in config**: + ```javascript + require("@nomicfoundation/hardhat-toolbox"); + ``` + +3. **Update plugins to latest versions**: + ```bash + npm update @nomicfoundation/hardhat-toolbox + ``` + +4. **Check for plugin conflicts**: + - Review package.json for version conflicts + - Try removing and reinstalling conflicting plugins + +## Environment Variable Issues + +### Cannot Access Environment Variables + +**Problem**: Scripts cannot read environment variables. + +**Solutions**: + +1. **Use Hardhat vars correctly**: + ```bash + npx hardhat vars set VARIABLE_NAME "value" + npx hardhat vars get VARIABLE_NAME + ``` + +2. **Alternative: Use dotenv**: + ```bash + npm install dotenv + ``` + ```javascript + require('dotenv').config(); + const value = process.env.VARIABLE_NAME; + ``` + +3. **Check variable access in config**: + ```javascript + const { vars } = require("hardhat/config"); + const value = vars.get("VARIABLE_NAME"); + ``` + +### Private Key Security Warnings + +**Problem**: Concerns about private key security. + +**Solutions**: + +1. **Never commit private keys**: + - Add `.env` to .gitignore if using dotenv + - Hardhat vars are stored locally and not in git + +2. **Use test accounts for development**: + - Use the pre-funded accounts from `npx hardhat node` + - Never use real private keys for testing + +3. **Verify .gitignore includes**: + ``` + node_modules + .env + coverage + cache + artifacts + ignition/deployments/ + ``` + +## Where to Go Next + +Continue improving your Hardhat workflow with these resources: + +
+ +- Guide __Get Started with Hardhat__ + + --- + + Return to the basics and review the Hardhat setup process. + + [:octicons-arrow-right-24: Get Started](/smart-contracts/dev-environments/hardhat/get-started) + +- Guide __Compile and Test Smart Contracts__ + + --- + + Learn how to compile and test your smart contracts using Hardhat. + + [:octicons-arrow-right-24: Get Started](/smart-contracts/dev-environments/hardhat/compile-and-test) + +- Guide __Deploy Smart Contracts__ + + --- + + Learn how to deploy and interact with smart contracts using Hardhat. + + [:octicons-arrow-right-24: Get Started](/smart-contracts/dev-environments/hardhat/deploy-a-contract) + +- External __Hardhat Documentation__ + + --- + + Explore official Hardhat documentation for advanced troubleshooting. + + [:octicons-arrow-right-24: Visit Docs](https://hardhat.org/docs){target=\_blank} + +
+ + --- Page Title: Use Hardhat with Polkadot Hub diff --git a/.ai/categories/tooling.md b/.ai/categories/tooling.md index 23ea85110..2a6fc0135 100644 --- a/.ai/categories/tooling.md +++ b/.ai/categories/tooling.md @@ -21294,6 +21294,711 @@ You now know the weight system, how it affects transaction fee computation, and - [Web3 Foundation Research](https://research.web3.foundation/Polkadot/overview/token-economics#relay-chain-transaction-fees-and-per-block-transaction-limits){target=\_blank} +--- + +Page Title: Troubleshooting Hardhat on Polkadot Hub + +- Source (raw): https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/smart-contracts-dev-environments-hardhat-troubleshooting.md +- Canonical (HTML): https://docs.polkadot.com/smart-contracts/dev-environments/hardhat/troubleshooting/ +- Summary: Solutions to common issues when developing, compiling, deploying, and testing smart contracts using Hardhat on Polkadot Hub. + +# Troubleshooting Hardhat + +## Overview + +This guide provides solutions to common issues you may encounter when using Hardhat with Polkadot Hub. If you're experiencing problems with installation, compilation, deployment, testing, or contract interaction, you'll likely find the solution here. + +## Installation Issues + +### Node.js Version Incompatibility + +**Problem**: Hardhat fails to install or run with version-related errors. + +**Solutions**: + +1. **Check Node.js version**: + - Ensure you have an LTS version of Node.js installed (18.x, 20.x, or 22.x) + - Check your current version with `node --version` + - Download the appropriate LTS version from [nodejs.org](https://nodejs.org/) + +2. **Use nvm for version management**: + - Install nvm (Node Version Manager) to easily switch between Node versions + - Run `nvm install --lts` to install the latest LTS version + - Run `nvm use --lts` to switch to it + +### Hardhat Installation Fails + +**Problem**: npm fails to install Hardhat or its dependencies. + +**Solutions**: + +1. **Clear npm cache**: + ```bash + npm cache clean --force + ``` + +2. **Delete node_modules and package-lock.json**: + ```bash + rm -rf node_modules package-lock.json + npm install + ``` + +3. **Check npm version**: + - Ensure you have npm 7.x or higher + - Update npm with `npm install -g npm@latest` + +4. **Install with specific version**: + ```bash + npm install --save-dev hardhat@^2.26.0 + ``` + +### Hardhat Toolbox Plugin Issues + +**Problem**: Hardhat Toolbox fails to install or causes conflicts. + +**Solutions**: + +1. **Install Hardhat Toolbox separately**: + ```bash + npm install --save-dev @nomicfoundation/hardhat-toolbox + ``` + +2. **Check for peer dependency conflicts**: + - Review the error messages for conflicting package versions + - Try using `npm install --legacy-peer-deps` if conflicts persist + +## Compilation Issues + +### Contract Won't Compile + +**Problem**: Your contract fails to compile or shows errors in the terminal. + +**Solutions**: + +1. **Check Solidity version compatibility**: + - Ensure your contract's pragma statement matches the compiler version in `hardhat.config.js` + - Example: If your contract uses `pragma solidity ^0.8.0;`, set `solidity: "0.8.28"` or compatible version + +2. **Verify imports**: + - Ensure all imported contracts are in the correct paths + - For OpenZeppelin contracts, make sure they're installed: `npm install @openzeppelin/contracts` + +3. **Clear artifacts and cache**: + ```bash + npx hardhat clean + npx hardhat compile + ``` + +4. **Check for syntax errors**: + - Carefully read error messages in the terminal + - Common issues include missing semicolons, incorrect function visibility, or type mismatches + +### Compilation Artifacts Missing + +**Problem**: The artifacts folder is empty or missing expected files. + +**Solutions**: + +1. **Ensure compilation completed successfully**: + - Check the terminal output for any error messages + - Look for "Compiled X Solidity files successfully" message + +2. **Verify contract file location**: + - Contracts must be in the `contracts` directory or subdirectories + - File must have .sol extension + +3. **Check hardhat.config.js settings**: + - Ensure the paths configuration is correct + - Default artifacts location is `./artifacts` + +### Compiler Version Errors + +**Problem**: Errors related to Solidity compiler version or features. + +**Solutions**: + +1. **Match pragma version with config**: + ```javascript + module.exports = { + solidity: { + version: "0.8.28", + settings: { + optimizer: { + enabled: true, + runs: 200 + } + } + } + }; + ``` + +2. **Use multiple compiler versions** (if needed): + ```javascript + module.exports = { + solidity: { + compilers: [ + { version: "0.8.28" }, + { version: "0.8.20" } + ] + } + }; + ``` + +## Testing Issues + +### Tests Fail to Run + +**Problem**: Tests don't execute or Hardhat throws errors when running tests. + +**Solutions**: + +1. **Verify test file location**: + - Test files must be in the `test` directory + - Files should end with `.js` or `.test.js` + +2. **Check test framework imports**: + ```javascript + const { expect } = require("chai"); + const { ethers } = require("hardhat"); + ``` + +3. **Ensure Hardhat Toolbox is installed**: + ```bash + npm install --save-dev @nomicfoundation/hardhat-toolbox + ``` + +4. **Run tests with verbose output**: + ```bash + npx hardhat test --verbose + ``` + +### Local Test Network Issues + +**Problem**: `npx hardhat node` fails to start or becomes unresponsive. + +**Solutions**: + +1. **Check if port 8545 is already in use**: + - Kill any process using port 8545 + - On Linux/Mac: `lsof -ti:8545 | xargs kill -9` + - On Windows: `netstat -ano | findstr :8545`, then kill the process with the appropriate process ID. + +2. **Specify a different port**: + ```bash + npx hardhat node --port 8546 + ``` + +3. **Reset the node**: + - Stop the node (Ctrl+C) + - Start it again with a fresh state + +### Test Assertions Failing + +**Problem**: Tests run but fail with assertion errors. + +**Solutions**: + +1. **Check account balances**: + - Ensure test accounts have sufficient ETH + - Hardhat node provides test accounts with 10,000 ETH each + +2. **Wait for transaction confirmations**: + ```javascript + const tx = await contract.someFunction(); + await tx.wait(); // Wait for transaction to be mined + ``` + +3. **Verify contract state**: + - Use console.log to debug values + - Check if contract was properly deployed in beforeEach hooks + +4. **Review timing issues**: + - Add appropriate waits between transactions + - Use `await ethers.provider.send("evm_mine")` to mine blocks manually + +## Network Configuration Issues + +### Cannot Connect to Local Development Node + +**Problem**: Hardhat cannot connect to the local development node. + +**Solutions**: + +1. **Verify the node is running**: + - Ensure your local development node is started + - Check the [Local Development Node](/smart-contracts/dev-environments/local-dev-node/) guide + +2. **Check network configuration**: + ```javascript + module.exports = { + networks: { + polkadotTestNet: { + url: "http://localhost:8545", + chainId: 420420420, + accounts: [PRIVATE_KEY] + } + } + }; + ``` + +3. **Verify URL and port**: + - Ensure the URL matches your local node's RPC endpoint + - Default is usually `http://localhost:8545` + +4. **Check firewall settings**: + - Ensure your firewall allows connections to localhost:8545 + +### Private Key Configuration Issues + +**Problem**: Hardhat cannot access or use the configured private key. + +**Solutions**: + +1. **Verify private key is set**: + ```bash + npx hardhat vars get PRIVATE_KEY + ``` + +2. **Set private key correctly**: + ```bash + npx hardhat vars set PRIVATE_KEY "0x..." + ``` + - Ensure the key starts with "0x" + - Do not include quotes within the actual key value + +3. **Check key format in config**: + ```javascript + const { vars } = require("hardhat/config"); + const PRIVATE_KEY = vars.get("PRIVATE_KEY"); + + module.exports = { + networks: { + polkadotTestNet: { + accounts: [PRIVATE_KEY] // Should be an array + } + } + }; + ``` + +4. **Alternative: Use mnemonic**: + ```javascript + accounts: { + mnemonic: "test test test test test test test test test test test junk" + } + ``` + +### Wrong Network Selected + +**Problem**: Deployment or transactions go to the wrong network. + +**Solutions**: + +1. **Specify network explicitly**: + ```bash + npx hardhat run scripts/deploy.js --network polkadotTestNet + ``` + +2. **Verify network in config**: + - Check that the network name matches what you're using in commands + - Ensure chainId matches the target network + +3. **Check default network**: + ```javascript + module.exports = { + defaultNetwork: "polkadotTestNet", + networks: { + // network configs + } + }; + ``` + +## Deployment Issues + +### Insufficient Funds Error + +**Problem**: Deployment fails with "insufficient funds" error. + +**Solutions**: + +1. **Check account balance**: + - Verify you have enough test tokens in your account + - For local development node, accounts should be pre-funded + +2. **Get test tokens**: + - Visit the [Polkadot faucet](/smart-contracts/faucet/){target=\_blank} for test networks + - Wait a few minutes for faucet transactions to complete + +3. **Verify account address**: + - Ensure the private key corresponds to the account you think you're using + - Check the account balance matches expectations + +### Ignition Deployment Fails + +**Problem**: Deployment using Hardhat Ignition fails or throws errors. + +**Solutions**: + +1. **Check Ignition module syntax**: + ```javascript + const { buildModule } = require("@nomicfoundation/hardhat-ignition/modules"); + + module.exports = buildModule("LockModule", (m) => { + const unlockTime = m.getParameter("unlockTime"); + const lock = m.contract("Lock", [unlockTime]); + return { lock }; + }); + ``` + +2. **Verify constructor parameters**: + - Ensure all required constructor parameters are provided + - Check parameter types match the contract's constructor + +3. **Clear previous deployments**: + ```bash + rm -rf ignition/deployments/ + ``` + +4. **Use deployment script alternative**: + - Create a manual deployment script in the `scripts` folder if Ignition continues to fail + +### Deployment Script Errors + +**Problem**: Custom deployment scripts fail to execute. + +**Solutions**: + +1. **Check script imports**: + ```javascript + const hre = require("hardhat"); + // or + const { ethers } = require("hardhat"); + ``` + +2. **Verify contract factory**: + ```javascript + const Contract = await ethers.getContractFactory("ContractName"); + const contract = await Contract.deploy(/* constructor args */); + await contract.deployed(); + ``` + +3. **Add error handling**: + ```javascript + try { + // deployment code + } catch (error) { + console.error("Deployment failed:", error); + process.exit(1); + } + ``` + +4. **Check gas settings**: + ```javascript + const contract = await Contract.deploy({ + gasLimit: 5000000 + }); + ``` + +### Contract Deployment Timeout + +**Problem**: Deployment hangs or times out. + +**Solutions**: + +1. **Increase timeout in config**: + ```javascript + module.exports = { + networks: { + polkadotTestNet: { + timeout: 60000 // 60 seconds + } + } + }; + ``` + +2. **Check network connection**: + - Verify the RPC endpoint is responsive + - Test with a simple read operation first + +3. **Reduce contract complexity**: + - Large contracts may take longer to deploy + - Consider splitting into multiple contracts + +## Contract Interaction Issues + +### Cannot Connect to Deployed Contract + +**Problem**: Scripts fail to interact with a deployed contract. + +**Solutions**: + +1. **Verify contract address**: + - Ensure you're using the correct deployed contract address + - Check the deployment output or Ignition deployment files + +2. **Check contract ABI**: + ```javascript + const Contract = await ethers.getContractFactory("ContractName"); + const contract = Contract.attach(contractAddress); + ``` + +3. **Verify network connection**: + - Ensure you're connected to the same network where the contract was deployed + - Use the `--network` flag when running scripts + +### Transaction Reverts + +**Problem**: Transactions revert when calling contract functions. + +**Solutions**: + +1. **Check function requirements**: + - Verify all require() conditions in the contract are satisfied + - Ensure you're meeting any access control requirements + +2. **Add debugging**: + ```javascript + try { + const tx = await contract.someFunction(); + const receipt = await tx.wait(); + console.log("Transaction successful:", receipt); + } catch (error) { + console.error("Transaction failed:", error.message); + } + ``` + +3. **Check gas limits**: + ```javascript + const tx = await contract.someFunction({ + gasLimit: 500000 + }); + ``` + +4. **Verify function parameters**: + - Ensure parameter types match the function signature + - Check for correct number of parameters + +### Read Functions Not Returning Values + +**Problem**: View/pure functions don't return expected values. + +**Solutions**: + +1. **Use call() for read-only functions**: + ```javascript + const value = await contract.someViewFunction(); + console.log("Returned value:", value); + ``` + +2. **Check contract state**: + - Verify the contract has been properly initialized + - Ensure any required state changes have been completed + +3. **Handle BigNumber returns**: + ```javascript + const value = await contract.someFunction(); + console.log("Value:", value.toString()); + ``` + +### Write Functions Not Updating State + +**Problem**: State-changing functions execute but don't update state. + +**Solutions**: + +1. **Wait for transaction confirmation**: + ```javascript + const tx = await contract.someFunction(); + await tx.wait(); // Wait for the transaction to be mined + const newState = await contract.getState(); + ``` + +2. **Check transaction receipt**: + ```javascript + const tx = await contract.someFunction(); + const receipt = await tx.wait(); + console.log("Transaction status:", receipt.status); + ``` + +3. **Verify transaction success**: + - Check that receipt.status === 1 (success) + - Review any events emitted by the transaction + +4. **Check for reverts**: + - Look for revert reasons in the error message + - Verify contract logic and access controls + +## Performance and Configuration Issues + +### Compilation is Slow + +**Problem**: Contract compilation takes a long time. + +**Solutions**: + +1. **Enable compiler cache**: + - Hardhat caches compilation results by default + - Ensure the cache folder is not ignored in .gitignore + +2. **Optimize compiler settings**: + ```javascript + module.exports = { + solidity: { + version: "0.8.28", + settings: { + optimizer: { + enabled: true, + runs: 200 + } + } + } + }; + ``` + +3. **Compile specific contracts**: + ```bash + npx hardhat compile --force + ``` + +### Hardhat Console Issues + +**Problem**: Cannot start Hardhat console or console commands fail. + +**Solutions**: + +1. **Start console with correct network**: + ```bash + npx hardhat console --network polkadotTestNet + ``` + +2. **Check console imports**: + ```javascript + // In console + const Contract = await ethers.getContractFactory("ContractName"); + ``` + +3. **Verify network connection**: + - Ensure the target network is accessible + - Check network configuration in hardhat.config.js + +### Plugin Configuration Issues + +**Problem**: Hardhat plugins not working correctly. + +**Solutions**: + +1. **Verify plugin installation**: + ```bash + npm list @nomicfoundation/hardhat-toolbox + ``` + +2. **Check plugin import in config**: + ```javascript + require("@nomicfoundation/hardhat-toolbox"); + ``` + +3. **Update plugins to latest versions**: + ```bash + npm update @nomicfoundation/hardhat-toolbox + ``` + +4. **Check for plugin conflicts**: + - Review package.json for version conflicts + - Try removing and reinstalling conflicting plugins + +## Environment Variable Issues + +### Cannot Access Environment Variables + +**Problem**: Scripts cannot read environment variables. + +**Solutions**: + +1. **Use Hardhat vars correctly**: + ```bash + npx hardhat vars set VARIABLE_NAME "value" + npx hardhat vars get VARIABLE_NAME + ``` + +2. **Alternative: Use dotenv**: + ```bash + npm install dotenv + ``` + ```javascript + require('dotenv').config(); + const value = process.env.VARIABLE_NAME; + ``` + +3. **Check variable access in config**: + ```javascript + const { vars } = require("hardhat/config"); + const value = vars.get("VARIABLE_NAME"); + ``` + +### Private Key Security Warnings + +**Problem**: Concerns about private key security. + +**Solutions**: + +1. **Never commit private keys**: + - Add `.env` to .gitignore if using dotenv + - Hardhat vars are stored locally and not in git + +2. **Use test accounts for development**: + - Use the pre-funded accounts from `npx hardhat node` + - Never use real private keys for testing + +3. **Verify .gitignore includes**: + ``` + node_modules + .env + coverage + cache + artifacts + ignition/deployments/ + ``` + +## Where to Go Next + +Continue improving your Hardhat workflow with these resources: + +
+ +- Guide __Get Started with Hardhat__ + + --- + + Return to the basics and review the Hardhat setup process. + + [:octicons-arrow-right-24: Get Started](/smart-contracts/dev-environments/hardhat/get-started) + +- Guide __Compile and Test Smart Contracts__ + + --- + + Learn how to compile and test your smart contracts using Hardhat. + + [:octicons-arrow-right-24: Get Started](/smart-contracts/dev-environments/hardhat/compile-and-test) + +- Guide __Deploy Smart Contracts__ + + --- + + Learn how to deploy and interact with smart contracts using Hardhat. + + [:octicons-arrow-right-24: Get Started](/smart-contracts/dev-environments/hardhat/deploy-a-contract) + +- External __Hardhat Documentation__ + + --- + + Explore official Hardhat documentation for advanced troubleshooting. + + [:octicons-arrow-right-24: Visit Docs](https://hardhat.org/docs){target=\_blank} + +
+ + --- Page Title: Use Hardhat with Polkadot Hub diff --git a/.ai/pages/smart-contracts-dev-environments-hardhat-troubleshooting.md b/.ai/pages/smart-contracts-dev-environments-hardhat-troubleshooting.md index 7d4e13cdb..91f90c807 100644 --- a/.ai/pages/smart-contracts-dev-environments-hardhat-troubleshooting.md +++ b/.ai/pages/smart-contracts-dev-environments-hardhat-troubleshooting.md @@ -1,5 +1,702 @@ --- +title: Troubleshooting Hardhat on Polkadot Hub +description: Solutions to common issues when developing, compiling, deploying, and testing smart contracts using Hardhat on Polkadot Hub. +categories: Smart Contracts, Tooling url: https://docs.polkadot.com/smart-contracts/dev-environments/hardhat/troubleshooting/ --- -TODO +# Troubleshooting Hardhat + +## Overview + +This guide provides solutions to common issues you may encounter when using Hardhat with Polkadot Hub. If you're experiencing problems with installation, compilation, deployment, testing, or contract interaction, you'll likely find the solution here. + +## Installation Issues + +### Node.js Version Incompatibility + +**Problem**: Hardhat fails to install or run with version-related errors. + +**Solutions**: + +1. **Check Node.js version**: + - Ensure you have an LTS version of Node.js installed (18.x, 20.x, or 22.x) + - Check your current version with `node --version` + - Download the appropriate LTS version from [nodejs.org](https://nodejs.org/) + +2. **Use nvm for version management**: + - Install nvm (Node Version Manager) to easily switch between Node versions + - Run `nvm install --lts` to install the latest LTS version + - Run `nvm use --lts` to switch to it + +### Hardhat Installation Fails + +**Problem**: npm fails to install Hardhat or its dependencies. + +**Solutions**: + +1. **Clear npm cache**: + ```bash + npm cache clean --force + ``` + +2. **Delete node_modules and package-lock.json**: + ```bash + rm -rf node_modules package-lock.json + npm install + ``` + +3. **Check npm version**: + - Ensure you have npm 7.x or higher + - Update npm with `npm install -g npm@latest` + +4. **Install with specific version**: + ```bash + npm install --save-dev hardhat@^2.26.0 + ``` + +### Hardhat Toolbox Plugin Issues + +**Problem**: Hardhat Toolbox fails to install or causes conflicts. + +**Solutions**: + +1. **Install Hardhat Toolbox separately**: + ```bash + npm install --save-dev @nomicfoundation/hardhat-toolbox + ``` + +2. **Check for peer dependency conflicts**: + - Review the error messages for conflicting package versions + - Try using `npm install --legacy-peer-deps` if conflicts persist + +## Compilation Issues + +### Contract Won't Compile + +**Problem**: Your contract fails to compile or shows errors in the terminal. + +**Solutions**: + +1. **Check Solidity version compatibility**: + - Ensure your contract's pragma statement matches the compiler version in `hardhat.config.js` + - Example: If your contract uses `pragma solidity ^0.8.0;`, set `solidity: "0.8.28"` or compatible version + +2. **Verify imports**: + - Ensure all imported contracts are in the correct paths + - For OpenZeppelin contracts, make sure they're installed: `npm install @openzeppelin/contracts` + +3. **Clear artifacts and cache**: + ```bash + npx hardhat clean + npx hardhat compile + ``` + +4. **Check for syntax errors**: + - Carefully read error messages in the terminal + - Common issues include missing semicolons, incorrect function visibility, or type mismatches + +### Compilation Artifacts Missing + +**Problem**: The artifacts folder is empty or missing expected files. + +**Solutions**: + +1. **Ensure compilation completed successfully**: + - Check the terminal output for any error messages + - Look for "Compiled X Solidity files successfully" message + +2. **Verify contract file location**: + - Contracts must be in the `contracts` directory or subdirectories + - File must have .sol extension + +3. **Check hardhat.config.js settings**: + - Ensure the paths configuration is correct + - Default artifacts location is `./artifacts` + +### Compiler Version Errors + +**Problem**: Errors related to Solidity compiler version or features. + +**Solutions**: + +1. **Match pragma version with config**: + ```javascript + module.exports = { + solidity: { + version: "0.8.28", + settings: { + optimizer: { + enabled: true, + runs: 200 + } + } + } + }; + ``` + +2. **Use multiple compiler versions** (if needed): + ```javascript + module.exports = { + solidity: { + compilers: [ + { version: "0.8.28" }, + { version: "0.8.20" } + ] + } + }; + ``` + +## Testing Issues + +### Tests Fail to Run + +**Problem**: Tests don't execute or Hardhat throws errors when running tests. + +**Solutions**: + +1. **Verify test file location**: + - Test files must be in the `test` directory + - Files should end with `.js` or `.test.js` + +2. **Check test framework imports**: + ```javascript + const { expect } = require("chai"); + const { ethers } = require("hardhat"); + ``` + +3. **Ensure Hardhat Toolbox is installed**: + ```bash + npm install --save-dev @nomicfoundation/hardhat-toolbox + ``` + +4. **Run tests with verbose output**: + ```bash + npx hardhat test --verbose + ``` + +### Local Test Network Issues + +**Problem**: `npx hardhat node` fails to start or becomes unresponsive. + +**Solutions**: + +1. **Check if port 8545 is already in use**: + - Kill any process using port 8545 + - On Linux/Mac: `lsof -ti:8545 | xargs kill -9` + - On Windows: `netstat -ano | findstr :8545`, then kill the process with the appropriate process ID. + +2. **Specify a different port**: + ```bash + npx hardhat node --port 8546 + ``` + +3. **Reset the node**: + - Stop the node (Ctrl+C) + - Start it again with a fresh state + +### Test Assertions Failing + +**Problem**: Tests run but fail with assertion errors. + +**Solutions**: + +1. **Check account balances**: + - Ensure test accounts have sufficient ETH + - Hardhat node provides test accounts with 10,000 ETH each + +2. **Wait for transaction confirmations**: + ```javascript + const tx = await contract.someFunction(); + await tx.wait(); // Wait for transaction to be mined + ``` + +3. **Verify contract state**: + - Use console.log to debug values + - Check if contract was properly deployed in beforeEach hooks + +4. **Review timing issues**: + - Add appropriate waits between transactions + - Use `await ethers.provider.send("evm_mine")` to mine blocks manually + +## Network Configuration Issues + +### Cannot Connect to Local Development Node + +**Problem**: Hardhat cannot connect to the local development node. + +**Solutions**: + +1. **Verify the node is running**: + - Ensure your local development node is started + - Check the [Local Development Node](/smart-contracts/dev-environments/local-dev-node/) guide + +2. **Check network configuration**: + ```javascript + module.exports = { + networks: { + polkadotTestNet: { + url: "http://localhost:8545", + chainId: 420420420, + accounts: [PRIVATE_KEY] + } + } + }; + ``` + +3. **Verify URL and port**: + - Ensure the URL matches your local node's RPC endpoint + - Default is usually `http://localhost:8545` + +4. **Check firewall settings**: + - Ensure your firewall allows connections to localhost:8545 + +### Private Key Configuration Issues + +**Problem**: Hardhat cannot access or use the configured private key. + +**Solutions**: + +1. **Verify private key is set**: + ```bash + npx hardhat vars get PRIVATE_KEY + ``` + +2. **Set private key correctly**: + ```bash + npx hardhat vars set PRIVATE_KEY "0x..." + ``` + - Ensure the key starts with "0x" + - Do not include quotes within the actual key value + +3. **Check key format in config**: + ```javascript + const { vars } = require("hardhat/config"); + const PRIVATE_KEY = vars.get("PRIVATE_KEY"); + + module.exports = { + networks: { + polkadotTestNet: { + accounts: [PRIVATE_KEY] // Should be an array + } + } + }; + ``` + +4. **Alternative: Use mnemonic**: + ```javascript + accounts: { + mnemonic: "test test test test test test test test test test test junk" + } + ``` + +### Wrong Network Selected + +**Problem**: Deployment or transactions go to the wrong network. + +**Solutions**: + +1. **Specify network explicitly**: + ```bash + npx hardhat run scripts/deploy.js --network polkadotTestNet + ``` + +2. **Verify network in config**: + - Check that the network name matches what you're using in commands + - Ensure chainId matches the target network + +3. **Check default network**: + ```javascript + module.exports = { + defaultNetwork: "polkadotTestNet", + networks: { + // network configs + } + }; + ``` + +## Deployment Issues + +### Insufficient Funds Error + +**Problem**: Deployment fails with "insufficient funds" error. + +**Solutions**: + +1. **Check account balance**: + - Verify you have enough test tokens in your account + - For local development node, accounts should be pre-funded + +2. **Get test tokens**: + - Visit the [Polkadot faucet](/smart-contracts/faucet/){target=\_blank} for test networks + - Wait a few minutes for faucet transactions to complete + +3. **Verify account address**: + - Ensure the private key corresponds to the account you think you're using + - Check the account balance matches expectations + +### Ignition Deployment Fails + +**Problem**: Deployment using Hardhat Ignition fails or throws errors. + +**Solutions**: + +1. **Check Ignition module syntax**: + ```javascript + const { buildModule } = require("@nomicfoundation/hardhat-ignition/modules"); + + module.exports = buildModule("LockModule", (m) => { + const unlockTime = m.getParameter("unlockTime"); + const lock = m.contract("Lock", [unlockTime]); + return { lock }; + }); + ``` + +2. **Verify constructor parameters**: + - Ensure all required constructor parameters are provided + - Check parameter types match the contract's constructor + +3. **Clear previous deployments**: + ```bash + rm -rf ignition/deployments/ + ``` + +4. **Use deployment script alternative**: + - Create a manual deployment script in the `scripts` folder if Ignition continues to fail + +### Deployment Script Errors + +**Problem**: Custom deployment scripts fail to execute. + +**Solutions**: + +1. **Check script imports**: + ```javascript + const hre = require("hardhat"); + // or + const { ethers } = require("hardhat"); + ``` + +2. **Verify contract factory**: + ```javascript + const Contract = await ethers.getContractFactory("ContractName"); + const contract = await Contract.deploy(/* constructor args */); + await contract.deployed(); + ``` + +3. **Add error handling**: + ```javascript + try { + // deployment code + } catch (error) { + console.error("Deployment failed:", error); + process.exit(1); + } + ``` + +4. **Check gas settings**: + ```javascript + const contract = await Contract.deploy({ + gasLimit: 5000000 + }); + ``` + +### Contract Deployment Timeout + +**Problem**: Deployment hangs or times out. + +**Solutions**: + +1. **Increase timeout in config**: + ```javascript + module.exports = { + networks: { + polkadotTestNet: { + timeout: 60000 // 60 seconds + } + } + }; + ``` + +2. **Check network connection**: + - Verify the RPC endpoint is responsive + - Test with a simple read operation first + +3. **Reduce contract complexity**: + - Large contracts may take longer to deploy + - Consider splitting into multiple contracts + +## Contract Interaction Issues + +### Cannot Connect to Deployed Contract + +**Problem**: Scripts fail to interact with a deployed contract. + +**Solutions**: + +1. **Verify contract address**: + - Ensure you're using the correct deployed contract address + - Check the deployment output or Ignition deployment files + +2. **Check contract ABI**: + ```javascript + const Contract = await ethers.getContractFactory("ContractName"); + const contract = Contract.attach(contractAddress); + ``` + +3. **Verify network connection**: + - Ensure you're connected to the same network where the contract was deployed + - Use the `--network` flag when running scripts + +### Transaction Reverts + +**Problem**: Transactions revert when calling contract functions. + +**Solutions**: + +1. **Check function requirements**: + - Verify all require() conditions in the contract are satisfied + - Ensure you're meeting any access control requirements + +2. **Add debugging**: + ```javascript + try { + const tx = await contract.someFunction(); + const receipt = await tx.wait(); + console.log("Transaction successful:", receipt); + } catch (error) { + console.error("Transaction failed:", error.message); + } + ``` + +3. **Check gas limits**: + ```javascript + const tx = await contract.someFunction({ + gasLimit: 500000 + }); + ``` + +4. **Verify function parameters**: + - Ensure parameter types match the function signature + - Check for correct number of parameters + +### Read Functions Not Returning Values + +**Problem**: View/pure functions don't return expected values. + +**Solutions**: + +1. **Use call() for read-only functions**: + ```javascript + const value = await contract.someViewFunction(); + console.log("Returned value:", value); + ``` + +2. **Check contract state**: + - Verify the contract has been properly initialized + - Ensure any required state changes have been completed + +3. **Handle BigNumber returns**: + ```javascript + const value = await contract.someFunction(); + console.log("Value:", value.toString()); + ``` + +### Write Functions Not Updating State + +**Problem**: State-changing functions execute but don't update state. + +**Solutions**: + +1. **Wait for transaction confirmation**: + ```javascript + const tx = await contract.someFunction(); + await tx.wait(); // Wait for the transaction to be mined + const newState = await contract.getState(); + ``` + +2. **Check transaction receipt**: + ```javascript + const tx = await contract.someFunction(); + const receipt = await tx.wait(); + console.log("Transaction status:", receipt.status); + ``` + +3. **Verify transaction success**: + - Check that receipt.status === 1 (success) + - Review any events emitted by the transaction + +4. **Check for reverts**: + - Look for revert reasons in the error message + - Verify contract logic and access controls + +## Performance and Configuration Issues + +### Compilation is Slow + +**Problem**: Contract compilation takes a long time. + +**Solutions**: + +1. **Enable compiler cache**: + - Hardhat caches compilation results by default + - Ensure the cache folder is not ignored in .gitignore + +2. **Optimize compiler settings**: + ```javascript + module.exports = { + solidity: { + version: "0.8.28", + settings: { + optimizer: { + enabled: true, + runs: 200 + } + } + } + }; + ``` + +3. **Compile specific contracts**: + ```bash + npx hardhat compile --force + ``` + +### Hardhat Console Issues + +**Problem**: Cannot start Hardhat console or console commands fail. + +**Solutions**: + +1. **Start console with correct network**: + ```bash + npx hardhat console --network polkadotTestNet + ``` + +2. **Check console imports**: + ```javascript + // In console + const Contract = await ethers.getContractFactory("ContractName"); + ``` + +3. **Verify network connection**: + - Ensure the target network is accessible + - Check network configuration in hardhat.config.js + +### Plugin Configuration Issues + +**Problem**: Hardhat plugins not working correctly. + +**Solutions**: + +1. **Verify plugin installation**: + ```bash + npm list @nomicfoundation/hardhat-toolbox + ``` + +2. **Check plugin import in config**: + ```javascript + require("@nomicfoundation/hardhat-toolbox"); + ``` + +3. **Update plugins to latest versions**: + ```bash + npm update @nomicfoundation/hardhat-toolbox + ``` + +4. **Check for plugin conflicts**: + - Review package.json for version conflicts + - Try removing and reinstalling conflicting plugins + +## Environment Variable Issues + +### Cannot Access Environment Variables + +**Problem**: Scripts cannot read environment variables. + +**Solutions**: + +1. **Use Hardhat vars correctly**: + ```bash + npx hardhat vars set VARIABLE_NAME "value" + npx hardhat vars get VARIABLE_NAME + ``` + +2. **Alternative: Use dotenv**: + ```bash + npm install dotenv + ``` + ```javascript + require('dotenv').config(); + const value = process.env.VARIABLE_NAME; + ``` + +3. **Check variable access in config**: + ```javascript + const { vars } = require("hardhat/config"); + const value = vars.get("VARIABLE_NAME"); + ``` + +### Private Key Security Warnings + +**Problem**: Concerns about private key security. + +**Solutions**: + +1. **Never commit private keys**: + - Add `.env` to .gitignore if using dotenv + - Hardhat vars are stored locally and not in git + +2. **Use test accounts for development**: + - Use the pre-funded accounts from `npx hardhat node` + - Never use real private keys for testing + +3. **Verify .gitignore includes**: + ``` + node_modules + .env + coverage + cache + artifacts + ignition/deployments/ + ``` + +## Where to Go Next + +Continue improving your Hardhat workflow with these resources: + +
+ +- Guide __Get Started with Hardhat__ + + --- + + Return to the basics and review the Hardhat setup process. + + [:octicons-arrow-right-24: Get Started](/smart-contracts/dev-environments/hardhat/get-started) + +- Guide __Compile and Test Smart Contracts__ + + --- + + Learn how to compile and test your smart contracts using Hardhat. + + [:octicons-arrow-right-24: Get Started](/smart-contracts/dev-environments/hardhat/compile-and-test) + +- Guide __Deploy Smart Contracts__ + + --- + + Learn how to deploy and interact with smart contracts using Hardhat. + + [:octicons-arrow-right-24: Get Started](/smart-contracts/dev-environments/hardhat/deploy-a-contract) + +- External __Hardhat Documentation__ + + --- + + Explore official Hardhat documentation for advanced troubleshooting. + + [:octicons-arrow-right-24: Visit Docs](https://hardhat.org/docs){target=\_blank} + +
diff --git a/.ai/site-index.json b/.ai/site-index.json index ac7cb0c85..f704e0ae6 100644 --- a/.ai/site-index.json +++ b/.ai/site-index.json @@ -11734,22 +11734,199 @@ }, { "id": "smart-contracts-dev-environments-hardhat-troubleshooting", - "title": "smart-contracts-dev-environments-hardhat-troubleshooting", + "title": "Troubleshooting Hardhat on Polkadot Hub", "slug": "smart-contracts-dev-environments-hardhat-troubleshooting", "categories": [ - "Uncategorized" + "Smart Contracts", + "Tooling" ], "raw_md_url": "https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/smart-contracts-dev-environments-hardhat-troubleshooting.md", "html_url": "https://docs.polkadot.com/smart-contracts/dev-environments/hardhat/troubleshooting/", - "preview": "TODO", - "outline": [], + "preview": "This guide provides solutions to common issues you may encounter when using Hardhat with Polkadot Hub. If you're experiencing problems with installation, compilation, deployment, testing, or contract interaction, you'll likely find the solution here.", + "outline": [ + { + "depth": 2, + "title": "Overview", + "anchor": "overview" + }, + { + "depth": 2, + "title": "Installation Issues", + "anchor": "installation-issues" + }, + { + "depth": 3, + "title": "Node.js Version Incompatibility", + "anchor": "nodejs-version-incompatibility" + }, + { + "depth": 3, + "title": "Hardhat Installation Fails", + "anchor": "hardhat-installation-fails" + }, + { + "depth": 3, + "title": "Hardhat Toolbox Plugin Issues", + "anchor": "hardhat-toolbox-plugin-issues" + }, + { + "depth": 2, + "title": "Compilation Issues", + "anchor": "compilation-issues" + }, + { + "depth": 3, + "title": "Contract Won't Compile", + "anchor": "contract-wont-compile" + }, + { + "depth": 3, + "title": "Compilation Artifacts Missing", + "anchor": "compilation-artifacts-missing" + }, + { + "depth": 3, + "title": "Compiler Version Errors", + "anchor": "compiler-version-errors" + }, + { + "depth": 2, + "title": "Testing Issues", + "anchor": "testing-issues" + }, + { + "depth": 3, + "title": "Tests Fail to Run", + "anchor": "tests-fail-to-run" + }, + { + "depth": 3, + "title": "Local Test Network Issues", + "anchor": "local-test-network-issues" + }, + { + "depth": 3, + "title": "Test Assertions Failing", + "anchor": "test-assertions-failing" + }, + { + "depth": 2, + "title": "Network Configuration Issues", + "anchor": "network-configuration-issues" + }, + { + "depth": 3, + "title": "Cannot Connect to Local Development Node", + "anchor": "cannot-connect-to-local-development-node" + }, + { + "depth": 3, + "title": "Private Key Configuration Issues", + "anchor": "private-key-configuration-issues" + }, + { + "depth": 3, + "title": "Wrong Network Selected", + "anchor": "wrong-network-selected" + }, + { + "depth": 2, + "title": "Deployment Issues", + "anchor": "deployment-issues" + }, + { + "depth": 3, + "title": "Insufficient Funds Error", + "anchor": "insufficient-funds-error" + }, + { + "depth": 3, + "title": "Ignition Deployment Fails", + "anchor": "ignition-deployment-fails" + }, + { + "depth": 3, + "title": "Deployment Script Errors", + "anchor": "deployment-script-errors" + }, + { + "depth": 3, + "title": "Contract Deployment Timeout", + "anchor": "contract-deployment-timeout" + }, + { + "depth": 2, + "title": "Contract Interaction Issues", + "anchor": "contract-interaction-issues" + }, + { + "depth": 3, + "title": "Cannot Connect to Deployed Contract", + "anchor": "cannot-connect-to-deployed-contract" + }, + { + "depth": 3, + "title": "Transaction Reverts", + "anchor": "transaction-reverts" + }, + { + "depth": 3, + "title": "Read Functions Not Returning Values", + "anchor": "read-functions-not-returning-values" + }, + { + "depth": 3, + "title": "Write Functions Not Updating State", + "anchor": "write-functions-not-updating-state" + }, + { + "depth": 2, + "title": "Performance and Configuration Issues", + "anchor": "performance-and-configuration-issues" + }, + { + "depth": 3, + "title": "Compilation is Slow", + "anchor": "compilation-is-slow" + }, + { + "depth": 3, + "title": "Hardhat Console Issues", + "anchor": "hardhat-console-issues" + }, + { + "depth": 3, + "title": "Plugin Configuration Issues", + "anchor": "plugin-configuration-issues" + }, + { + "depth": 2, + "title": "Environment Variable Issues", + "anchor": "environment-variable-issues" + }, + { + "depth": 3, + "title": "Cannot Access Environment Variables", + "anchor": "cannot-access-environment-variables" + }, + { + "depth": 3, + "title": "Private Key Security Warnings", + "anchor": "private-key-security-warnings" + }, + { + "depth": 2, + "title": "Where to Go Next", + "anchor": "where-to-go-next" + } + ], "stats": { - "chars": 5, - "words": 1, - "headings": 0, - "estimated_token_count_total": 0 + "chars": 17815, + "words": 2093, + "headings": 35, + "estimated_token_count_total": 4175 }, - "hash": "sha256:56ba36249ea8216ad513b13df3de6c0e490ba214897674d30331f1c7e7edbef3", + "hash": "sha256:9baf24d263b7d0678f834b5b4a08567d5bb88ffb05973b67e5099e0cf3290e0c", "token_estimator": "heuristic-v1" }, { diff --git a/llms-full.jsonl b/llms-full.jsonl index 1f5ab24b0..f45c3d890 100644 --- a/llms-full.jsonl +++ b/llms-full.jsonl @@ -1458,6 +1458,41 @@ {"page_id": "smart-contracts-dev-environments-hardhat-get-started", "page_title": "Use Hardhat with Polkadot Hub", "index": 8, "depth": 2, "title": "Interacting with Your Contract", "anchor": "interacting-with-your-contract", "start_char": 14963, "end_char": 16763, "estimated_token_count": 426, "token_estimator": "heuristic-v1", "text": "## Interacting with Your Contract\n\nOnce deployed, you can create a script to interact with your contract. To do so, create a file called `scripts/interact.js` and add some logic to interact with the contract.\n\nFor example, for the default `MyToken.sol` contract, you can use the following file that connects to the contract at its address and retrieves the `unlockTime`, which represents when funds can be withdrawn. The script converts this timestamp into a readable date and logs it. It then checks the contract's balance and displays it. Finally, it attempts to call the withdrawal function on the contract, but it catches and logs the error message if the withdrawal is not yet allowed (e.g., before `unlockTime`).\n\n```javascript title=\"interact.js\"\nconst hre = require('hardhat');\n\nasync function main() {\n // Get the contract factory\n const MyToken = await hre.ethers.getContractFactory('MyToken');\n\n // Replace with your deployed contract address\n const contractAddress = 'INSERT_CONTRACT_ADDRESS';\n\n // Attach to existing contract\n const token = await MyToken.attach(contractAddress);\n\n // Get signers\n const [deployer] = await hre.ethers.getSigners();\n\n // Read contract state\n const name = await token.name();\n const symbol = await token.symbol();\n const totalSupply = await token.totalSupply();\n const balance = await token.balanceOf(deployer.address);\n\n console.log(`Token: ${name} (${symbol})`);\n console.log(\n `Total Supply: ${hre.ethers.formatUnits(totalSupply, 18)} tokens`,\n );\n console.log(\n `Deployer Balance: ${hre.ethers.formatUnits(balance, 18)} tokens`,\n );\n}\n\nmain().catch((error) => {\n console.error(error);\n process.exitCode = 1;\n});\n\n```\n\nRun your interaction script:\n\n```bash\nnpx hardhat run scripts/interact.js --network polkadotHubTestnet\n```"} {"page_id": "smart-contracts-dev-environments-hardhat-get-started", "page_title": "Use Hardhat with Polkadot Hub", "index": 9, "depth": 2, "title": "Upgrading the Plugin", "anchor": "upgrading-the-plugin", "start_char": 16763, "end_char": 17423, "estimated_token_count": 176, "token_estimator": "heuristic-v1", "text": "## Upgrading the Plugin\n\nIf you already have a Hardhat Polkadot project and want to upgrade to a newer version of the plugin, to avoid errors (for example, `Cannot find module 'run-container'`), you can clean your dependencies by running the following commands:\n\n```bash\nrm -rf node_modules package-lock.json\n```\n\nAfter that, you can upgrade the plugin to the latest version by running the following commands:\n\n```bash\nnpm install --save-dev @parity/hardhat-polkadot@latest\nnpm install\n```\n\nConsider using [Node.js](https://nodejs.org/){target=\\_blank} 22.18+ and [npm](https://www.npmjs.com/){target=\\_blank} version 10.9.0+ to avoid issues with the plugin."} {"page_id": "smart-contracts-dev-environments-hardhat-get-started", "page_title": "Use Hardhat with Polkadot Hub", "index": 10, "depth": 2, "title": "Where to Go Next", "anchor": "where-to-go-next", "start_char": 17423, "end_char": 18514, "estimated_token_count": 253, "token_estimator": "heuristic-v1", "text": "## Where to Go Next\n\nHardhat provides a powerful environment for developing, testing, and deploying smart contracts on Polkadot Hub. Its plugin architecture allows seamless integration with PolkaVM through the `hardhat-resolc` and `hardhat-revive-node` plugins.\n\nExplore more about smart contracts through these resources:\n\n
\n\n- Guide __Get Started with Smart Contracts__\n\n ---\n\n Learn how to get started with smart contracts\n\n [:octicons-arrow-right-24: Get Started](/smart-contracts/get-started/)\n\n- External __Hardhat Documentation__\n\n ---\n\n Learn more about Hardhat's advanced features and best practices.\n\n [:octicons-arrow-right-24: Get Started](https://hardhat.org/docs){target=\\_blank}\n\n- External __OpenZeppelin Contracts__\n\n ---\n\n Test your skills by deploying contracts with prebuilt templates.\n\n [:octicons-arrow-right-24: Get Started](https://www.openzeppelin.com/solidity-contracts){target=\\_blank}\n\n
"} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting", "page_title": "Troubleshooting Hardhat on Polkadot Hub", "index": 0, "depth": 2, "title": "Overview", "anchor": "overview", "start_char": 27, "end_char": 292, "estimated_token_count": 48, "token_estimator": "heuristic-v1", "text": "## Overview\n\nThis guide provides solutions to common issues you may encounter when using Hardhat with Polkadot Hub. If you're experiencing problems with installation, compilation, deployment, testing, or contract interaction, you'll likely find the solution here."} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting", "page_title": "Troubleshooting Hardhat on Polkadot Hub", "index": 1, "depth": 2, "title": "Installation Issues", "anchor": "installation-issues", "start_char": 292, "end_char": 316, "estimated_token_count": 4, "token_estimator": "heuristic-v1", "text": "## Installation Issues"} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting", "page_title": "Troubleshooting Hardhat on Polkadot Hub", "index": 2, "depth": 3, "title": "Node.js Version Incompatibility", "anchor": "nodejs-version-incompatibility", "start_char": 316, "end_char": 918, "estimated_token_count": 158, "token_estimator": "heuristic-v1", "text": "### Node.js Version Incompatibility\n\n**Problem**: Hardhat fails to install or run with version-related errors.\n\n**Solutions**:\n\n1. **Check Node.js version**:\n - Ensure you have an LTS version of Node.js installed (18.x, 20.x, or 22.x)\n - Check your current version with `node --version`\n - Download the appropriate LTS version from [nodejs.org](https://nodejs.org/)\n\n2. **Use nvm for version management**:\n - Install nvm (Node Version Manager) to easily switch between Node versions\n - Run `nvm install --lts` to install the latest LTS version\n - Run `nvm use --lts` to switch to it"} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting", "page_title": "Troubleshooting Hardhat on Polkadot Hub", "index": 3, "depth": 3, "title": "Hardhat Installation Fails", "anchor": "hardhat-installation-fails", "start_char": 918, "end_char": 1451, "estimated_token_count": 149, "token_estimator": "heuristic-v1", "text": "### Hardhat Installation Fails\n\n**Problem**: npm fails to install Hardhat or its dependencies.\n\n**Solutions**:\n\n1. **Clear npm cache**:\n ```bash\n npm cache clean --force\n ```\n\n2. **Delete node_modules and package-lock.json**:\n ```bash\n rm -rf node_modules package-lock.json\n npm install\n ```\n\n3. **Check npm version**:\n - Ensure you have npm 7.x or higher\n - Update npm with `npm install -g npm@latest`\n\n4. **Install with specific version**:\n ```bash\n npm install --save-dev hardhat@^2.26.0\n ```"} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting", "page_title": "Troubleshooting Hardhat on Polkadot Hub", "index": 4, "depth": 3, "title": "Hardhat Toolbox Plugin Issues", "anchor": "hardhat-toolbox-plugin-issues", "start_char": 1451, "end_char": 1874, "estimated_token_count": 97, "token_estimator": "heuristic-v1", "text": "### Hardhat Toolbox Plugin Issues\n\n**Problem**: Hardhat Toolbox fails to install or causes conflicts.\n\n**Solutions**:\n\n1. **Install Hardhat Toolbox separately**:\n ```bash\n npm install --save-dev @nomicfoundation/hardhat-toolbox\n ```\n\n2. **Check for peer dependency conflicts**:\n - Review the error messages for conflicting package versions\n - Try using `npm install --legacy-peer-deps` if conflicts persist"} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting", "page_title": "Troubleshooting Hardhat on Polkadot Hub", "index": 5, "depth": 2, "title": "Compilation Issues", "anchor": "compilation-issues", "start_char": 1874, "end_char": 1897, "estimated_token_count": 4, "token_estimator": "heuristic-v1", "text": "## Compilation Issues"} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting", "page_title": "Troubleshooting Hardhat on Polkadot Hub", "index": 6, "depth": 3, "title": "Contract Won't Compile", "anchor": "contract-wont-compile", "start_char": 1897, "end_char": 2744, "estimated_token_count": 193, "token_estimator": "heuristic-v1", "text": "### Contract Won't Compile\n\n**Problem**: Your contract fails to compile or shows errors in the terminal.\n\n**Solutions**:\n\n1. **Check Solidity version compatibility**:\n - Ensure your contract's pragma statement matches the compiler version in `hardhat.config.js`\n - Example: If your contract uses `pragma solidity ^0.8.0;`, set `solidity: \"0.8.28\"` or compatible version\n\n2. **Verify imports**:\n - Ensure all imported contracts are in the correct paths\n - For OpenZeppelin contracts, make sure they're installed: `npm install @openzeppelin/contracts`\n\n3. **Clear artifacts and cache**:\n ```bash\n npx hardhat clean\n npx hardhat compile\n ```\n\n4. **Check for syntax errors**:\n - Carefully read error messages in the terminal\n - Common issues include missing semicolons, incorrect function visibility, or type mismatches"} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting", "page_title": "Troubleshooting Hardhat on Polkadot Hub", "index": 7, "depth": 3, "title": "Compilation Artifacts Missing", "anchor": "compilation-artifacts-missing", "start_char": 2744, "end_char": 3322, "estimated_token_count": 120, "token_estimator": "heuristic-v1", "text": "### Compilation Artifacts Missing\n\n**Problem**: The artifacts folder is empty or missing expected files.\n\n**Solutions**:\n\n1. **Ensure compilation completed successfully**:\n - Check the terminal output for any error messages\n - Look for \"Compiled X Solidity files successfully\" message\n\n2. **Verify contract file location**:\n - Contracts must be in the `contracts` directory or subdirectories\n - File must have .sol extension\n\n3. **Check hardhat.config.js settings**:\n - Ensure the paths configuration is correct\n - Default artifacts location is `./artifacts`"} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting", "page_title": "Troubleshooting Hardhat on Polkadot Hub", "index": 8, "depth": 3, "title": "Compiler Version Errors", "anchor": "compiler-version-errors", "start_char": 3322, "end_char": 3933, "estimated_token_count": 142, "token_estimator": "heuristic-v1", "text": "### Compiler Version Errors\n\n**Problem**: Errors related to Solidity compiler version or features.\n\n**Solutions**:\n\n1. **Match pragma version with config**:\n ```javascript\n module.exports = {\n solidity: {\n version: \"0.8.28\",\n settings: {\n optimizer: {\n enabled: true,\n runs: 200\n }\n }\n }\n };\n ```\n\n2. **Use multiple compiler versions** (if needed):\n ```javascript\n module.exports = {\n solidity: {\n compilers: [\n { version: \"0.8.28\" },\n { version: \"0.8.20\" }\n ]\n }\n };\n ```"} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting", "page_title": "Troubleshooting Hardhat on Polkadot Hub", "index": 9, "depth": 2, "title": "Testing Issues", "anchor": "testing-issues", "start_char": 3933, "end_char": 3952, "estimated_token_count": 4, "token_estimator": "heuristic-v1", "text": "## Testing Issues"} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting", "page_title": "Troubleshooting Hardhat on Polkadot Hub", "index": 10, "depth": 3, "title": "Tests Fail to Run", "anchor": "tests-fail-to-run", "start_char": 3952, "end_char": 4564, "estimated_token_count": 169, "token_estimator": "heuristic-v1", "text": "### Tests Fail to Run\n\n**Problem**: Tests don't execute or Hardhat throws errors when running tests.\n\n**Solutions**:\n\n1. **Verify test file location**:\n - Test files must be in the `test` directory\n - Files should end with `.js` or `.test.js`\n\n2. **Check test framework imports**:\n ```javascript\n const { expect } = require(\"chai\");\n const { ethers } = require(\"hardhat\");\n ```\n\n3. **Ensure Hardhat Toolbox is installed**:\n ```bash\n npm install --save-dev @nomicfoundation/hardhat-toolbox\n ```\n\n4. **Run tests with verbose output**:\n ```bash\n npx hardhat test --verbose\n ```"} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting", "page_title": "Troubleshooting Hardhat on Polkadot Hub", "index": 11, "depth": 3, "title": "Local Test Network Issues", "anchor": "local-test-network-issues", "start_char": 4564, "end_char": 5106, "estimated_token_count": 147, "token_estimator": "heuristic-v1", "text": "### Local Test Network Issues\n\n**Problem**: `npx hardhat node` fails to start or becomes unresponsive.\n\n**Solutions**:\n\n1. **Check if port 8545 is already in use**:\n - Kill any process using port 8545\n - On Linux/Mac: `lsof -ti:8545 | xargs kill -9`\n - On Windows: `netstat -ano | findstr :8545`, then kill the process with the appropriate process ID.\n\n2. **Specify a different port**:\n ```bash\n npx hardhat node --port 8546\n ```\n\n3. **Reset the node**:\n - Stop the node (Ctrl+C)\n - Start it again with a fresh state"} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting", "page_title": "Troubleshooting Hardhat on Polkadot Hub", "index": 12, "depth": 3, "title": "Test Assertions Failing", "anchor": "test-assertions-failing", "start_char": 5106, "end_char": 5811, "estimated_token_count": 161, "token_estimator": "heuristic-v1", "text": "### Test Assertions Failing\n\n**Problem**: Tests run but fail with assertion errors.\n\n**Solutions**:\n\n1. **Check account balances**:\n - Ensure test accounts have sufficient ETH\n - Hardhat node provides test accounts with 10,000 ETH each\n\n2. **Wait for transaction confirmations**:\n ```javascript\n const tx = await contract.someFunction();\n await tx.wait(); // Wait for transaction to be mined\n ```\n\n3. **Verify contract state**:\n - Use console.log to debug values\n - Check if contract was properly deployed in beforeEach hooks\n\n4. **Review timing issues**:\n - Add appropriate waits between transactions\n - Use `await ethers.provider.send(\"evm_mine\")` to mine blocks manually"} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting", "page_title": "Troubleshooting Hardhat on Polkadot Hub", "index": 13, "depth": 2, "title": "Network Configuration Issues", "anchor": "network-configuration-issues", "start_char": 5811, "end_char": 5844, "estimated_token_count": 5, "token_estimator": "heuristic-v1", "text": "## Network Configuration Issues"} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting", "page_title": "Troubleshooting Hardhat on Polkadot Hub", "index": 14, "depth": 3, "title": "Cannot Connect to Local Development Node", "anchor": "cannot-connect-to-local-development-node", "start_char": 5844, "end_char": 6655, "estimated_token_count": 185, "token_estimator": "heuristic-v1", "text": "### Cannot Connect to Local Development Node\n\n**Problem**: Hardhat cannot connect to the local development node.\n\n**Solutions**:\n\n1. **Verify the node is running**:\n - Ensure your local development node is started\n - Check the [Local Development Node](/smart-contracts/dev-environments/local-dev-node/) guide\n\n2. **Check network configuration**:\n ```javascript\n module.exports = {\n networks: {\n polkadotTestNet: {\n url: \"http://localhost:8545\",\n chainId: 420420420,\n accounts: [PRIVATE_KEY]\n }\n }\n };\n ```\n\n3. **Verify URL and port**:\n - Ensure the URL matches your local node's RPC endpoint\n - Default is usually `http://localhost:8545`\n\n4. **Check firewall settings**:\n - Ensure your firewall allows connections to localhost:8545"} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting", "page_title": "Troubleshooting Hardhat on Polkadot Hub", "index": 15, "depth": 3, "title": "Private Key Configuration Issues", "anchor": "private-key-configuration-issues", "start_char": 6655, "end_char": 7540, "estimated_token_count": 210, "token_estimator": "heuristic-v1", "text": "### Private Key Configuration Issues\n\n**Problem**: Hardhat cannot access or use the configured private key.\n\n**Solutions**:\n\n1. **Verify private key is set**:\n ```bash\n npx hardhat vars get PRIVATE_KEY\n ```\n\n2. **Set private key correctly**:\n ```bash\n npx hardhat vars set PRIVATE_KEY \"0x...\"\n ```\n - Ensure the key starts with \"0x\"\n - Do not include quotes within the actual key value\n\n3. **Check key format in config**:\n ```javascript\n const { vars } = require(\"hardhat/config\");\n const PRIVATE_KEY = vars.get(\"PRIVATE_KEY\");\n \n module.exports = {\n networks: {\n polkadotTestNet: {\n accounts: [PRIVATE_KEY] // Should be an array\n }\n }\n };\n ```\n\n4. **Alternative: Use mnemonic**:\n ```javascript\n accounts: {\n mnemonic: \"test test test test test test test test test test test junk\"\n }\n ```"} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting", "page_title": "Troubleshooting Hardhat on Polkadot Hub", "index": 16, "depth": 3, "title": "Wrong Network Selected", "anchor": "wrong-network-selected", "start_char": 7540, "end_char": 8105, "estimated_token_count": 126, "token_estimator": "heuristic-v1", "text": "### Wrong Network Selected\n\n**Problem**: Deployment or transactions go to the wrong network.\n\n**Solutions**:\n\n1. **Specify network explicitly**:\n ```bash\n npx hardhat run scripts/deploy.js --network polkadotTestNet\n ```\n\n2. **Verify network in config**:\n - Check that the network name matches what you're using in commands\n - Ensure chainId matches the target network\n\n3. **Check default network**:\n ```javascript\n module.exports = {\n defaultNetwork: \"polkadotTestNet\",\n networks: {\n // network configs\n }\n };\n ```"} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting", "page_title": "Troubleshooting Hardhat on Polkadot Hub", "index": 17, "depth": 2, "title": "Deployment Issues", "anchor": "deployment-issues", "start_char": 8105, "end_char": 8127, "estimated_token_count": 4, "token_estimator": "heuristic-v1", "text": "## Deployment Issues"} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting", "page_title": "Troubleshooting Hardhat on Polkadot Hub", "index": 18, "depth": 3, "title": "Insufficient Funds Error", "anchor": "insufficient-funds-error", "start_char": 8127, "end_char": 8733, "estimated_token_count": 136, "token_estimator": "heuristic-v1", "text": "### Insufficient Funds Error\n\n**Problem**: Deployment fails with \"insufficient funds\" error.\n\n**Solutions**:\n\n1. **Check account balance**:\n - Verify you have enough test tokens in your account\n - For local development node, accounts should be pre-funded\n\n2. **Get test tokens**:\n - Visit the [Polkadot faucet](/smart-contracts/faucet/){target=\\_blank} for test networks\n - Wait a few minutes for faucet transactions to complete\n\n3. **Verify account address**:\n - Ensure the private key corresponds to the account you think you're using\n - Check the account balance matches expectations"} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting", "page_title": "Troubleshooting Hardhat on Polkadot Hub", "index": 19, "depth": 3, "title": "Ignition Deployment Fails", "anchor": "ignition-deployment-fails", "start_char": 8733, "end_char": 9586, "estimated_token_count": 196, "token_estimator": "heuristic-v1", "text": "### Ignition Deployment Fails\n\n**Problem**: Deployment using Hardhat Ignition fails or throws errors.\n\n**Solutions**:\n\n1. **Check Ignition module syntax**:\n ```javascript\n const { buildModule } = require(\"@nomicfoundation/hardhat-ignition/modules\");\n \n module.exports = buildModule(\"LockModule\", (m) => {\n const unlockTime = m.getParameter(\"unlockTime\");\n const lock = m.contract(\"Lock\", [unlockTime]);\n return { lock };\n });\n ```\n\n2. **Verify constructor parameters**:\n - Ensure all required constructor parameters are provided\n - Check parameter types match the contract's constructor\n\n3. **Clear previous deployments**:\n ```bash\n rm -rf ignition/deployments/\n ```\n\n4. **Use deployment script alternative**:\n - Create a manual deployment script in the `scripts` folder if Ignition continues to fail"} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting", "page_title": "Troubleshooting Hardhat on Polkadot Hub", "index": 20, "depth": 3, "title": "Deployment Script Errors", "anchor": "deployment-script-errors", "start_char": 9586, "end_char": 10383, "estimated_token_count": 202, "token_estimator": "heuristic-v1", "text": "### Deployment Script Errors\n\n**Problem**: Custom deployment scripts fail to execute.\n\n**Solutions**:\n\n1. **Check script imports**:\n ```javascript\n const hre = require(\"hardhat\");\n // or\n const { ethers } = require(\"hardhat\");\n ```\n\n2. **Verify contract factory**:\n ```javascript\n const Contract = await ethers.getContractFactory(\"ContractName\");\n const contract = await Contract.deploy(/* constructor args */);\n await contract.deployed();\n ```\n\n3. **Add error handling**:\n ```javascript\n try {\n // deployment code\n } catch (error) {\n console.error(\"Deployment failed:\", error);\n process.exit(1);\n }\n ```\n\n4. **Check gas settings**:\n ```javascript\n const contract = await Contract.deploy({\n gasLimit: 5000000\n });\n ```"} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting", "page_title": "Troubleshooting Hardhat on Polkadot Hub", "index": 21, "depth": 3, "title": "Contract Deployment Timeout", "anchor": "contract-deployment-timeout", "start_char": 10383, "end_char": 10928, "estimated_token_count": 113, "token_estimator": "heuristic-v1", "text": "### Contract Deployment Timeout\n\n**Problem**: Deployment hangs or times out.\n\n**Solutions**:\n\n1. **Increase timeout in config**:\n ```javascript\n module.exports = {\n networks: {\n polkadotTestNet: {\n timeout: 60000 // 60 seconds\n }\n }\n };\n ```\n\n2. **Check network connection**:\n - Verify the RPC endpoint is responsive\n - Test with a simple read operation first\n\n3. **Reduce contract complexity**:\n - Large contracts may take longer to deploy\n - Consider splitting into multiple contracts"} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting", "page_title": "Troubleshooting Hardhat on Polkadot Hub", "index": 22, "depth": 2, "title": "Contract Interaction Issues", "anchor": "contract-interaction-issues", "start_char": 10928, "end_char": 10960, "estimated_token_count": 5, "token_estimator": "heuristic-v1", "text": "## Contract Interaction Issues"} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting", "page_title": "Troubleshooting Hardhat on Polkadot Hub", "index": 23, "depth": 3, "title": "Cannot Connect to Deployed Contract", "anchor": "cannot-connect-to-deployed-contract", "start_char": 10960, "end_char": 11590, "estimated_token_count": 136, "token_estimator": "heuristic-v1", "text": "### Cannot Connect to Deployed Contract\n\n**Problem**: Scripts fail to interact with a deployed contract.\n\n**Solutions**:\n\n1. **Verify contract address**:\n - Ensure you're using the correct deployed contract address\n - Check the deployment output or Ignition deployment files\n\n2. **Check contract ABI**:\n ```javascript\n const Contract = await ethers.getContractFactory(\"ContractName\");\n const contract = Contract.attach(contractAddress);\n ```\n\n3. **Verify network connection**:\n - Ensure you're connected to the same network where the contract was deployed\n - Use the `--network` flag when running scripts"} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting", "page_title": "Troubleshooting Hardhat on Polkadot Hub", "index": 24, "depth": 3, "title": "Transaction Reverts", "anchor": "transaction-reverts", "start_char": 11590, "end_char": 12418, "estimated_token_count": 186, "token_estimator": "heuristic-v1", "text": "### Transaction Reverts\n\n**Problem**: Transactions revert when calling contract functions.\n\n**Solutions**:\n\n1. **Check function requirements**:\n - Verify all require() conditions in the contract are satisfied\n - Ensure you're meeting any access control requirements\n\n2. **Add debugging**:\n ```javascript\n try {\n const tx = await contract.someFunction();\n const receipt = await tx.wait();\n console.log(\"Transaction successful:\", receipt);\n } catch (error) {\n console.error(\"Transaction failed:\", error.message);\n }\n ```\n\n3. **Check gas limits**:\n ```javascript\n const tx = await contract.someFunction({\n gasLimit: 500000\n });\n ```\n\n4. **Verify function parameters**:\n - Ensure parameter types match the function signature\n - Check for correct number of parameters"} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting", "page_title": "Troubleshooting Hardhat on Polkadot Hub", "index": 25, "depth": 3, "title": "Read Functions Not Returning Values", "anchor": "read-functions-not-returning-values", "start_char": 12418, "end_char": 13005, "estimated_token_count": 147, "token_estimator": "heuristic-v1", "text": "### Read Functions Not Returning Values\n\n**Problem**: View/pure functions don't return expected values.\n\n**Solutions**:\n\n1. **Use call() for read-only functions**:\n ```javascript\n const value = await contract.someViewFunction();\n console.log(\"Returned value:\", value);\n ```\n\n2. **Check contract state**:\n - Verify the contract has been properly initialized\n - Ensure any required state changes have been completed\n\n3. **Handle BigNumber returns**:\n ```javascript\n const value = await contract.someFunction();\n console.log(\"Value:\", value.toString());\n ```"} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting", "page_title": "Troubleshooting Hardhat on Polkadot Hub", "index": 26, "depth": 3, "title": "Write Functions Not Updating State", "anchor": "write-functions-not-updating-state", "start_char": 13005, "end_char": 13817, "estimated_token_count": 195, "token_estimator": "heuristic-v1", "text": "### Write Functions Not Updating State\n\n**Problem**: State-changing functions execute but don't update state.\n\n**Solutions**:\n\n1. **Wait for transaction confirmation**:\n ```javascript\n const tx = await contract.someFunction();\n await tx.wait(); // Wait for the transaction to be mined\n const newState = await contract.getState();\n ```\n\n2. **Check transaction receipt**:\n ```javascript\n const tx = await contract.someFunction();\n const receipt = await tx.wait();\n console.log(\"Transaction status:\", receipt.status);\n ```\n\n3. **Verify transaction success**:\n - Check that receipt.status === 1 (success)\n - Review any events emitted by the transaction\n\n4. **Check for reverts**:\n - Look for revert reasons in the error message\n - Verify contract logic and access controls"} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting", "page_title": "Troubleshooting Hardhat on Polkadot Hub", "index": 27, "depth": 2, "title": "Performance and Configuration Issues", "anchor": "performance-and-configuration-issues", "start_char": 13817, "end_char": 13858, "estimated_token_count": 6, "token_estimator": "heuristic-v1", "text": "## Performance and Configuration Issues"} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting", "page_title": "Troubleshooting Hardhat on Polkadot Hub", "index": 28, "depth": 3, "title": "Compilation is Slow", "anchor": "compilation-is-slow", "start_char": 13858, "end_char": 14442, "estimated_token_count": 129, "token_estimator": "heuristic-v1", "text": "### Compilation is Slow\n\n**Problem**: Contract compilation takes a long time.\n\n**Solutions**:\n\n1. **Enable compiler cache**:\n - Hardhat caches compilation results by default\n - Ensure the cache folder is not ignored in .gitignore\n\n2. **Optimize compiler settings**:\n ```javascript\n module.exports = {\n solidity: {\n version: \"0.8.28\",\n settings: {\n optimizer: {\n enabled: true,\n runs: 200\n }\n }\n }\n };\n ```\n\n3. **Compile specific contracts**:\n ```bash\n npx hardhat compile --force\n ```"} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting", "page_title": "Troubleshooting Hardhat on Polkadot Hub", "index": 29, "depth": 3, "title": "Hardhat Console Issues", "anchor": "hardhat-console-issues", "start_char": 14442, "end_char": 14950, "estimated_token_count": 114, "token_estimator": "heuristic-v1", "text": "### Hardhat Console Issues\n\n**Problem**: Cannot start Hardhat console or console commands fail.\n\n**Solutions**:\n\n1. **Start console with correct network**:\n ```bash\n npx hardhat console --network polkadotTestNet\n ```\n\n2. **Check console imports**:\n ```javascript\n // In console\n const Contract = await ethers.getContractFactory(\"ContractName\");\n ```\n\n3. **Verify network connection**:\n - Ensure the target network is accessible\n - Check network configuration in hardhat.config.js"} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting", "page_title": "Troubleshooting Hardhat on Polkadot Hub", "index": 30, "depth": 3, "title": "Plugin Configuration Issues", "anchor": "plugin-configuration-issues", "start_char": 14950, "end_char": 15519, "estimated_token_count": 133, "token_estimator": "heuristic-v1", "text": "### Plugin Configuration Issues\n\n**Problem**: Hardhat plugins not working correctly.\n\n**Solutions**:\n\n1. **Verify plugin installation**:\n ```bash\n npm list @nomicfoundation/hardhat-toolbox\n ```\n\n2. **Check plugin import in config**:\n ```javascript\n require(\"@nomicfoundation/hardhat-toolbox\");\n ```\n\n3. **Update plugins to latest versions**:\n ```bash\n npm update @nomicfoundation/hardhat-toolbox\n ```\n\n4. **Check for plugin conflicts**:\n - Review package.json for version conflicts\n - Try removing and reinstalling conflicting plugins"} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting", "page_title": "Troubleshooting Hardhat on Polkadot Hub", "index": 31, "depth": 2, "title": "Environment Variable Issues", "anchor": "environment-variable-issues", "start_char": 15519, "end_char": 15551, "estimated_token_count": 5, "token_estimator": "heuristic-v1", "text": "## Environment Variable Issues"} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting", "page_title": "Troubleshooting Hardhat on Polkadot Hub", "index": 32, "depth": 3, "title": "Cannot Access Environment Variables", "anchor": "cannot-access-environment-variables", "start_char": 15551, "end_char": 16146, "estimated_token_count": 149, "token_estimator": "heuristic-v1", "text": "### Cannot Access Environment Variables\n\n**Problem**: Scripts cannot read environment variables.\n\n**Solutions**:\n\n1. **Use Hardhat vars correctly**:\n ```bash\n npx hardhat vars set VARIABLE_NAME \"value\"\n npx hardhat vars get VARIABLE_NAME\n ```\n\n2. **Alternative: Use dotenv**:\n ```bash\n npm install dotenv\n ```\n ```javascript\n require('dotenv').config();\n const value = process.env.VARIABLE_NAME;\n ```\n\n3. **Check variable access in config**:\n ```javascript\n const { vars } = require(\"hardhat/config\");\n const value = vars.get(\"VARIABLE_NAME\");\n ```"} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting", "page_title": "Troubleshooting Hardhat on Polkadot Hub", "index": 33, "depth": 3, "title": "Private Key Security Warnings", "anchor": "private-key-security-warnings", "start_char": 16146, "end_char": 16671, "estimated_token_count": 118, "token_estimator": "heuristic-v1", "text": "### Private Key Security Warnings\n\n**Problem**: Concerns about private key security.\n\n**Solutions**:\n\n1. **Never commit private keys**:\n - Add `.env` to .gitignore if using dotenv\n - Hardhat vars are stored locally and not in git\n\n2. **Use test accounts for development**:\n - Use the pre-funded accounts from `npx hardhat node`\n - Never use real private keys for testing\n\n3. **Verify .gitignore includes**:\n ```\n node_modules\n .env\n coverage\n cache\n artifacts\n ignition/deployments/\n ```"} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting", "page_title": "Troubleshooting Hardhat on Polkadot Hub", "index": 34, "depth": 2, "title": "Where to Go Next", "anchor": "where-to-go-next", "start_char": 16671, "end_char": 17815, "estimated_token_count": 279, "token_estimator": "heuristic-v1", "text": "## Where to Go Next\n\nContinue improving your Hardhat workflow with these resources:\n\n
\n\n- Guide __Get Started with Hardhat__\n\n ---\n\n Return to the basics and review the Hardhat setup process.\n\n [:octicons-arrow-right-24: Get Started](/smart-contracts/dev-environments/hardhat/get-started)\n\n- Guide __Compile and Test Smart Contracts__\n\n ---\n\n Learn how to compile and test your smart contracts using Hardhat.\n\n [:octicons-arrow-right-24: Get Started](/smart-contracts/dev-environments/hardhat/compile-and-test)\n\n- Guide __Deploy Smart Contracts__\n\n ---\n\n Learn how to deploy and interact with smart contracts using Hardhat.\n\n [:octicons-arrow-right-24: Get Started](/smart-contracts/dev-environments/hardhat/deploy-a-contract)\n\n- External __Hardhat Documentation__\n\n ---\n\n Explore official Hardhat documentation for advanced troubleshooting.\n\n [:octicons-arrow-right-24: Visit Docs](https://hardhat.org/docs){target=\\_blank}\n\n
"} {"page_id": "smart-contracts-dev-environments-local-dev-node", "page_title": "Local Development Node", "index": 0, "depth": 2, "title": "Introduction", "anchor": "introduction", "start_char": 196, "end_char": 699, "estimated_token_count": 97, "token_estimator": "heuristic-v1", "text": "## Introduction\n\nA local development node provides an isolated blockchain environment where you can deploy, test, and debug smart contracts without incurring network fees or waiting for block confirmations. This guide demonstrates how to set up a local Polkadot SDK-based node with smart contract capabilities.\n\nBy the end of this guide, you'll have:\n\n- A running node with smart contract support.\n- An ETH-RPC adapter for Ethereum-compatible tooling integration accessible at `http://localhost:8545`."} {"page_id": "smart-contracts-dev-environments-local-dev-node", "page_title": "Local Development Node", "index": 1, "depth": 2, "title": "Prerequisites", "anchor": "prerequisites", "start_char": 699, "end_char": 1032, "estimated_token_count": 78, "token_estimator": "heuristic-v1", "text": "## Prerequisites\n\nBefore getting started, ensure you have done the following:\n\n- Completed the [Install Polkadot SDK Dependencies](/parachains/install-polkadot-sdk/){target=\\_blank} guide and successfully installed [Rust](https://www.rust-lang.org/){target=\\_blank} and the required packages to set up your development environment."} {"page_id": "smart-contracts-dev-environments-local-dev-node", "page_title": "Local Development Node", "index": 2, "depth": 2, "title": "Install the Revive Dev Node and ETH-RPC Adapter", "anchor": "install-the-revive-dev-node-and-eth-rpc-adapter", "start_char": 1032, "end_char": 2565, "estimated_token_count": 343, "token_estimator": "heuristic-v1", "text": "## Install the Revive Dev Node and ETH-RPC Adapter\n\nThe Polkadot SDK repository contains both the [Revive Dev node](https://github.com/paritytech/polkadot-sdk/tree/8e2b6f742a38bb13688e12abacded0aab2dbbb23/substrate/frame/revive/dev-node){target=\\_blank} implementation and the [ETH-RPC adapter](https://github.com/paritytech/polkadot-sdk/tree/8e2b6f742a38bb13688e12abacded0aab2dbbb23/substrate/frame/revive/rpc){target=\\_blank} required for Ethereum compatibility. Start by cloning the repository and navigating to the project directory:\n\n```bash\ngit clone https://github.com/paritytech/polkadot-sdk.git\ncd polkadot-sdk\ngit checkout 8e2b6f742a38bb13688e12abacded0aab2dbbb23\n```\n\nNext, you need to compile the two essential components for your development environment. The Substrate node provides the core blockchain runtime with smart contract support, while the ETH-RPC adapter enables Ethereum JSON-RPC compatibility for existing tooling:\n\n```bash\ncargo build -p revive-dev-node --bin revive-dev-node --release\ncargo build -p pallet-revive-eth-rpc --bin eth-rpc --release\n```\n\nThe compilation process may take some time depending on your system specifications, potentially up to 30 minutes. Release builds are optimized for performance but take longer to compile than debug builds. After successful compilation, you can verify the binaries are available in the `target/release` directory:\n\n- **Revive Dev node path**: `polkadot-sdk/target/release/revive-dev-node`\n- **ETH-RPC adapter path**: `polkadot-sdk/target/release/eth-rpc`"} diff --git a/llms.txt b/llms.txt index f20ee9e34..2f5b42ab4 100644 --- a/llms.txt +++ b/llms.txt @@ -91,6 +91,7 @@ Docs: Smart Contracts - [Deploy an NFT to Polkadot Hub with Remix](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/smart-contracts-cookbook-smart-contracts-deploy-nft-remix.md): Learn how to deploy an ERC-721 NFT contract to Polkadot Hub using Remix, a browser-based IDE for quick prototyping and learning. - [Smart Contracts Cookbook Index](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/smart-contracts-cookbook.md): Explore our full collection of tutorials and guides to learn step-by-step how to build, deploy, and work with smart contracts on Polkadot. - [Use Hardhat with Polkadot Hub](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/smart-contracts-dev-environments-hardhat-get-started.md): Learn how to create, compile, test, and deploy smart contracts on Polkadot Hub using Hardhat, a powerful development environment for blockchain developers. +- [Troubleshooting Hardhat on Polkadot Hub](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/smart-contracts-dev-environments-hardhat-troubleshooting.md): Solutions to common issues when developing, compiling, deploying, and testing smart contracts using Hardhat on Polkadot Hub. - [Local Development Node](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/smart-contracts-dev-environments-local-dev-node.md): Follow this step-by-step guide to install a Revive Dev node and ETH-RPC adapter for smart contract development in a local environment. - [Use the Polkadot Remix IDE](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/smart-contracts-dev-environments-remix-get-started.md): Explore the smart contract development and deployment process on Asset Hub using Remix IDE, a visual IDE for blockchain developers. - [Block Explorers](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/smart-contracts-explorers.md): Access PolkaVM explorers like Subscan, BlockScout, and Routescan to track transactions, analyze contracts, and view on-chain data from smart contracts. @@ -244,6 +245,7 @@ Docs: Tooling - [Zero to Hero Smart Contract DApp](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/smart-contracts-cookbook-dapps-zero-to-hero.md): Learn how to build a decentralized application on Polkadot Hub using Viem and Next.js by creating a simple dApp that interacts with a smart contract. - [Deploying Uniswap V2 on Polkadot](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/smart-contracts-cookbook-eth-dapps-uniswap-v2.md): Learn how to deploy and test Uniswap V2 on Polkadot Hub using Hardhat, bringing AMM-based token swaps to the Polkadot ecosystem. - [Use Hardhat with Polkadot Hub](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/smart-contracts-dev-environments-hardhat-get-started.md): Learn how to create, compile, test, and deploy smart contracts on Polkadot Hub using Hardhat, a powerful development environment for blockchain developers. +- [Troubleshooting Hardhat on Polkadot Hub](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/smart-contracts-dev-environments-hardhat-troubleshooting.md): Solutions to common issues when developing, compiling, deploying, and testing smart contracts using Hardhat on Polkadot Hub. - [Use the Polkadot Remix IDE](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/smart-contracts-dev-environments-remix-get-started.md): Explore the smart contract development and deployment process on Asset Hub using Remix IDE, a visual IDE for blockchain developers. - [Block Explorers](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/smart-contracts-explorers.md): Access PolkaVM explorers like Subscan, BlockScout, and Routescan to track transactions, analyze contracts, and view on-chain data from smart contracts. - [Wallets for Polkadot Hub](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/smart-contracts-integrations-wallets.md): Comprehensive guide to connecting and managing wallets for Polkadot Hub, covering step-by-step instructions for interacting with the ecosystem. @@ -367,7 +369,6 @@ Docs: Uncategorized - [smart-contracts-dev-environments-hardhat-compile-and-test](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/smart-contracts-dev-environments-hardhat-compile-and-test.md): No description available. - [smart-contracts-dev-environments-hardhat-deploy-a-contract](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/smart-contracts-dev-environments-hardhat-deploy-a-contract.md): No description available. - [smart-contracts-dev-environments-hardhat-install-and-config](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/smart-contracts-dev-environments-hardhat-install-and-config.md): No description available. -- [smart-contracts-dev-environments-hardhat-troubleshooting](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/smart-contracts-dev-environments-hardhat-troubleshooting.md): No description available. - [smart-contracts-dev-environments-hardhat-verify-a-contract](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/smart-contracts-dev-environments-hardhat-verify-a-contract.md): No description available. - [smart-contracts-dev-environments-remix-deploy-a-contract](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/smart-contracts-dev-environments-remix-deploy-a-contract.md): No description available. - [smart-contracts-dev-environments-remix-troubleshooting](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/smart-contracts-dev-environments-remix-troubleshooting.md): No description available. From 712962c26b9806396a8610262e1fa4b06fdc9f7f Mon Sep 17 00:00:00 2001 From: DAWN KELLY Date: Tue, 18 Nov 2025 15:10:02 -0500 Subject: [PATCH 4/6] update URL and formatting for "FAQ" format --- .../dev-environments/hardhat/.nav.yml | 2 +- .../hardhat/troubleshooting-faq.md | 558 ++++++++++++++ .../hardhat/troubleshooting.md | 701 ------------------ 3 files changed, 559 insertions(+), 702 deletions(-) create mode 100644 smart-contracts/dev-environments/hardhat/troubleshooting-faq.md delete mode 100644 smart-contracts/dev-environments/hardhat/troubleshooting.md diff --git a/smart-contracts/dev-environments/hardhat/.nav.yml b/smart-contracts/dev-environments/hardhat/.nav.yml index aa1cef6da..b3326ea47 100644 --- a/smart-contracts/dev-environments/hardhat/.nav.yml +++ b/smart-contracts/dev-environments/hardhat/.nav.yml @@ -3,4 +3,4 @@ nav: - 'Install and Config': install-and-config.md - 'Compile and Test': compile-and-test.md - 'Deploy a Contract': deploy-a-contract.md - - 'Troubleshooting': troubleshooting.md + - 'Troubleshooting': troubleshooting-faq.md diff --git a/smart-contracts/dev-environments/hardhat/troubleshooting-faq.md b/smart-contracts/dev-environments/hardhat/troubleshooting-faq.md new file mode 100644 index 000000000..fc8b0757e --- /dev/null +++ b/smart-contracts/dev-environments/hardhat/troubleshooting-faq.md @@ -0,0 +1,558 @@ +--- +title: Troubleshooting Hardhat +description: Common issues related to developing, compiling, and deploying smart contracts using Hardhat on Polkadot Hub paired with troubleshooting suggestions. +categories: Smart Contracts, Tooling +--- + +# Hardhat Troubleshooting + +This guide provides solutions to common issues you may encounter when using Hardhat with Polkadot Hub. If you're experiencing problems with installation, compilation, deployment, testing, or contract interaction, you'll likely find the solution here. + +## Hardhat fails to install or run with version-related errors + +- **Check Node.js version**: + - Ensure you have an LTS version of Node.js installed (18.x, 20.x, or 22.x). + - Check your current version with `node --version`. + - Download the appropriate LTS version from [nodejs.org](https://nodejs.org/). + +- **Use nvm for version management**: + - Install nvm (Node Version Manager) to easily switch between Node versions. + - Run `nvm install --lts` to install the latest LTS version. + - Run `nvm use --lts` to switch to it. + +## Install of Hardhat or its dependencies via npm fails + +- **Clear npm cache**: + ```bash + npm cache clean --force + ``` + +- **Delete node_modules and package-lock.json**: + ```bash + rm -rf node_modules package-lock.json + npm install + ``` + +- **Check npm version**: + - Ensure you have npm 7.x or higher + - Update npm with `npm install -g npm@latest` + +- **Install with specific version**: + ```bash + npm install --save-dev hardhat@^2.26.0 + ``` + +## Hardhat Toolbox fails to install or causes conflicts + +- **Install Hardhat Toolbox separately**: + ```bash + npm install --save-dev @nomicfoundation/hardhat-toolbox + ``` + +- **Check for peer dependency conflicts**: + - Review the error messages for conflicting package versions. + - Try using `npm install --legacy-peer-deps` if conflicts persist. + +## Your contract fails to compile or shows errors in the terminal + +- **Check Solidity version compatibility**: + - Ensure your contract's pragma statement matches the compiler version in `hardhat.config.js`. + - Example: If your contract uses `pragma solidity ^0.8.0;`, set `solidity: "0.8.28"` or compatible version. + +- **Verify imports**: + - Ensure all imported contracts are in the correct paths. + - For OpenZeppelin contracts, make sure dependencies are installed using the command: + ```bash + `npm install @openzeppelin/contracts` + ``` + +- **Clear artifacts and cache**: + ```bash + npx hardhat clean + npx hardhat compile + ``` + +- **Check for syntax errors**: + - Carefully read error messages in the terminal. + - Check for common syntax errors, such as missing semicolons, incorrect function visibility, or type mismatches. + +## The artifacts folder is empty or missing expected files + +- **Ensure compilation completed successfully**: + - Check the terminal output for any error messages. + - Look for "Compiled X Solidity files successfully" message. + +- **Verify contract file location**: + - Contracts must be in the `contracts` directory or subdirectories. + - File must have `.sol` extension. + +- **Check `hardhat.config.js` settings**: + - Ensure the paths configuration is correct. + - Default artifacts location is `./artifacts`. + +## Errors related to Solidity compiler version or features + +- **Match pragma version with config**: + ```javascript + module.exports = { + solidity: { + version: "0.8.28", + settings: { + optimizer: { + enabled: true, + runs: 200 + } + } + } + }; + ``` + +- **Use multiple compiler versions** (if needed): + ```javascript + module.exports = { + solidity: { + compilers: [ + { version: "0.8.28" }, + { version: "0.8.20" } + ] + } + }; + ``` + +## Tests don't execute or Hardhat throws errors when running tests + +- **Verify test file location**: + - Test files must be in the `test` directory. + - Files should end with `.js` or `.test.js`. + +- **Check test framework imports**: + ```javascript + const { expect } = require("chai"); + const { ethers } = require("hardhat"); + ``` + +- **Ensure Hardhat Toolbox is installed**: + ```bash + npm install --save-dev @nomicfoundation/hardhat-toolbox + ``` + +- **Run tests with verbose output**: + ```bash + npx hardhat test --verbose + ``` + +## The `npx hardhat node` fails to start or becomes unresponsive + +1. **Check if port 8545 is already in use**: + - Kill any process using port 8545 as follows: + - On Linux/Mac: `lsof -ti:8545 | xargs kill -9` + - On Windows: `netstat -ano | findstr :8545`, then kill the process with the appropriate process ID. + +2. **Specify a different port**: + ```bash + npx hardhat node --port 8546 + ``` + +3. **Reset the node**: + - Stop the node (Ctrl+C). + - Start it again with a fresh state. + +## Tests run but fail with assertion errors + +- **Check account balances**: + - Ensure test accounts have sufficient ETH. + - Hardhat node provides test accounts with 10,000 ETH each. + +- **Wait for transaction confirmations**: + ```javascript + const tx = await contract.someFunction(); + await tx.wait(); // Wait for transaction to be mined + ``` + +- **Verify contract state**: + - Use `console.log` to debug values. + - Check if contract was properly deployed in `beforeEach` hooks. + +- **Review timing issues**: + - Add appropriate waits between transactions. + - Use `await ethers.provider.send("evm_mine")` to mine blocks manually. + +## Hardhat cannot connect to the local development node + +1. **Verify the node is running**: + - Ensure your local development node is started. + - Check the [Local Development Node](/smart-contracts/dev-environments/local-dev-node/) guide. + +2. **Check network configuration**: + ```javascript + module.exports = { + networks: { + polkadotTestNet: { + url: "http://localhost:8545", + chainId: 420420420, + accounts: [PRIVATE_KEY] + } + } + }; + ``` + +3. **Verify URL and port**: + - Ensure the URL matches your local node's RPC endpoint. + - Default is usually `http://localhost:8545`. + +4. **Check firewall settings**: + - Ensure your firewall allows connections to `localhost:8545`. + +## Hardhat cannot access or use the configured private key + +- **Verify private key is set**: + ```bash + npx hardhat vars get PRIVATE_KEY + ``` + +- **Set private key correctly**: + ```bash + npx hardhat vars set PRIVATE_KEY "0x..." + ``` + - Ensure the key starts with "0x". + - Do not include quotes within the actual key value. + +- **Check key format in config**: + ```javascript + const { vars } = require("hardhat/config"); + const PRIVATE_KEY = vars.get("PRIVATE_KEY"); + + module.exports = { + networks: { + polkadotTestNet: { + accounts: [PRIVATE_KEY] // Should be an array + } + } + }; + ``` + +- **Alternative: Use mnemonic**: + ```javascript + accounts: { + mnemonic: "test test test test test test test test test test test junk" + } + ``` + +## Deployment or transactions go to the wrong network + +- **Specify network explicitly**: + ```bash + npx hardhat run scripts/deploy.js --network polkadotTestNet + ``` + +- **Verify network in config**: + - Check that the network name matches what you're using in commands + - Ensure chainId matches the target network + +- **Check default network**: + ```javascript + module.exports = { + defaultNetwork: "polkadotTestNet", + networks: { + // network configs + } + }; + ``` + +## Deployment fails with "insufficient funds" error + +- **Check account balance**: + - Verify you have enough test tokens in your account. + - For local development node, accounts should be pre-funded. + +- **Get test tokens**: + - Visit the [Polkadot faucet](/smart-contracts/faucet/){target=\_blank} for test networks. + - Wait a few minutes for faucet transactions to complete. + +- **Verify account address**: + - Ensure the private key corresponds to the account you think you're using. + - Check the account balance matches expectations. + +## Deployment using Hardhat Ignition fails or throws errors + +- **Check ignition module syntax**: + ```javascript + const { buildModule } = require("@nomicfoundation/hardhat-ignition/modules"); + + module.exports = buildModule("LockModule", (m) => { + const unlockTime = m.getParameter("unlockTime"); + const lock = m.contract("Lock", [unlockTime]); + return { lock }; + }); + ``` + +- **Verify constructor parameters**: + - Ensure all required constructor parameters are provided. + - Check parameter types match the contract's constructor. + +- **Clear previous deployments**: + ```bash + rm -rf ignition/deployments/ + ``` + +- **Use deployment script alternative**: + - Create a manual deployment script in the `scripts` folder if Ignition continues to fail. + +## Custom deployment scripts fail to execute + +- **Check script imports**: + ```javascript + const hre = require("hardhat"); + // or + const { ethers } = require("hardhat"); + ``` + +- **Verify contract factory**: + ```javascript + const Contract = await ethers.getContractFactory("ContractName"); + const contract = await Contract.deploy(/* constructor args */); + await contract.deployed(); + ``` + +- **Add error handling**: + ```javascript + try { + // deployment code + } catch (error) { + console.error("Deployment failed:", error); + process.exit(1); + } + ``` + +- **Check gas settings**: + ```javascript + const contract = await Contract.deploy({ + gasLimit: 5000000 + }); + ``` + +## Contract deployment hangs or times out + +- **Increase timeout in config**: + ```javascript + module.exports = { + networks: { + polkadotTestNet: { + timeout: 60000 // 60 seconds + } + } + }; + ``` + +- **Check network connection**: + - Verify the RPC endpoint is responsive. + - Test with a simple read operation first. + +- **Reduce contract complexity**: + - Large contracts may take longer to deploy. + - Consider splitting into multiple contracts. + +## Scripts fail to interact with a deployed contract + +- **Verify contract address**: + - Ensure you're using the correct deployed contract address. + - Check the deployment output or ignition deployment files. + +- **Check contract ABI**: + ```javascript + const Contract = await ethers.getContractFactory("ContractName"); + const contract = Contract.attach(contractAddress); + ``` + +- **Verify network connection**: + - Ensure you're connected to the same network where the contract was deployed. + - Use the `--network` flag when running scripts. + +## Transactions revert when calling contract functions + +- **Check function requirements**: + - Verify all `require()` conditions in the contract are satisfied. + - Ensure you're meeting any access control requirements. + +- **Add debugging**: + ```javascript + try { + const tx = await contract.someFunction(); + const receipt = await tx.wait(); + console.log("Transaction successful:", receipt); + } catch (error) { + console.error("Transaction failed:", error.message); + } + ``` + +- **Check gas limits**: + ```javascript + const tx = await contract.someFunction({ + gasLimit: 500000 + }); + ``` + +- **Verify function parameters**: + - Ensure parameter types match the function signature. + - Check for correct number of parameters. + +## `View` or `pure` functions don't return expected values + +- **Use `call()` for read-only functions**: + ```javascript + const value = await contract.someViewFunction(); + console.log("Returned value:", value); + ``` + +- **Check contract state**: + - Verify the contract has been properly initialized. + - Ensure any required state changes have been completed. + +- **Handle `BigNumber` returns**: + ```javascript + const value = await contract.someFunction(); + console.log("Value:", value.toString()); + ``` + +## State-changing functions execute but don't update state + +- **Wait for transaction confirmation**: + ```javascript + const tx = await contract.someFunction(); + await tx.wait(); // Wait for the transaction to be mined + const newState = await contract.getState(); + ``` + +- **Check transaction receipt**: + ```javascript + const tx = await contract.someFunction(); + const receipt = await tx.wait(); + console.log("Transaction status:", receipt.status); + ``` + +- **Verify transaction success**: + - Check that `receipt.status === 1` (success). + - Review any events emitted by the transaction. + +- **Check for reverts**: + - Look for revert reasons in the error message. + - Verify contract logic and access controls. + +## Contract compilation takes a long time + +- **Enable compiler cache**: + - Hardhat caches compilation results by default. + - Ensure the cache folder is not ignored in `.gitignore`. + +- **Optimize compiler settings**: + ```javascript + module.exports = { + solidity: { + version: "0.8.28", + settings: { + optimizer: { + enabled: true, + runs: 200 + } + } + } + }; + ``` + +- **Compile specific contracts**: + ```bash + npx hardhat compile --force + ``` + +## Can't start Hardhat console or console commands fail + +- **Start console with correct network**: + ```bash + npx hardhat console --network polkadotTestNet + ``` + +- **Check console imports**: + ```javascript + // In console + const Contract = await ethers.getContractFactory("ContractName"); + ``` + +- **Verify network connection**: + - Ensure the target network is accessible. + - Check network configuration in `hardhat.config.js`. + +## Hardhat plugins not working correctly + +- **Verify plugin installation**: + ```bash + npm list @nomicfoundation/hardhat-toolbox + ``` + +- **Check plugin import in config**: + ```javascript + require("@nomicfoundation/hardhat-toolbox"); + ``` + +- **Update plugins to latest versions**: + ```bash + npm update @nomicfoundation/hardhat-toolbox + ``` + +- **Check for plugin conflicts**: + - Review `package.json` for version conflicts. + - Try removing and reinstalling conflicting plugins. + +## Scripts cannot read environment variables + +- **Use Hardhat vars correctly**: + ```bash + npx hardhat vars set VARIABLE_NAME "value" + npx hardhat vars get VARIABLE_NAME + ``` + +- **Alternative: Use dotenv**: + ```bash + npm install dotenv + ``` + ```javascript + require('dotenv').config(); + const value = process.env.VARIABLE_NAME; + ``` + +- **Check variable access in config**: + ```javascript + const { vars } = require("hardhat/config"); + const value = vars.get("VARIABLE_NAME"); + ``` + +## Concerns about private key security + +- **Never commit private keys**: + - Add `.env` to `.gitignore` if using `dotenv`. + - Hardhat vars are stored locally and not in git. + +- **Use test accounts for development**: + - Use the pre-funded accounts from `npx hardhat node`. + - Never use private keys with real funds for testing. + +- **Verify `.gitignore` includes**: + ``` + node_modules + .env + coverage + cache + artifacts + ignition/deployments/ + ``` + +## Where to Go Next + +- External __Hardhat Documentation__ + + --- + + Explore official Hardhat documentation for advanced troubleshooting. + + [:octicons-arrow-right-24: Visit Docs](https://hardhat.org/docs){target=\_blank} + + \ No newline at end of file diff --git a/smart-contracts/dev-environments/hardhat/troubleshooting.md b/smart-contracts/dev-environments/hardhat/troubleshooting.md deleted file mode 100644 index 34f7a0350..000000000 --- a/smart-contracts/dev-environments/hardhat/troubleshooting.md +++ /dev/null @@ -1,701 +0,0 @@ ---- -title: Troubleshooting Hardhat on Polkadot Hub -description: Solutions to common issues when developing, compiling, deploying, and testing smart contracts using Hardhat on Polkadot Hub. -categories: Smart Contracts, Tooling ---- - -# Troubleshooting Hardhat - -## Overview - -This guide provides solutions to common issues you may encounter when using Hardhat with Polkadot Hub. If you're experiencing problems with installation, compilation, deployment, testing, or contract interaction, you'll likely find the solution here. - -## Installation Issues - -### Node.js Version Incompatibility - -**Problem**: Hardhat fails to install or run with version-related errors. - -**Solutions**: - -1. **Check Node.js version**: - - Ensure you have an LTS version of Node.js installed (18.x, 20.x, or 22.x) - - Check your current version with `node --version` - - Download the appropriate LTS version from [nodejs.org](https://nodejs.org/) - -2. **Use nvm for version management**: - - Install nvm (Node Version Manager) to easily switch between Node versions - - Run `nvm install --lts` to install the latest LTS version - - Run `nvm use --lts` to switch to it - -### Hardhat Installation Fails - -**Problem**: npm fails to install Hardhat or its dependencies. - -**Solutions**: - -1. **Clear npm cache**: - ```bash - npm cache clean --force - ``` - -2. **Delete node_modules and package-lock.json**: - ```bash - rm -rf node_modules package-lock.json - npm install - ``` - -3. **Check npm version**: - - Ensure you have npm 7.x or higher - - Update npm with `npm install -g npm@latest` - -4. **Install with specific version**: - ```bash - npm install --save-dev hardhat@^2.26.0 - ``` - -### Hardhat Toolbox Plugin Issues - -**Problem**: Hardhat Toolbox fails to install or causes conflicts. - -**Solutions**: - -1. **Install Hardhat Toolbox separately**: - ```bash - npm install --save-dev @nomicfoundation/hardhat-toolbox - ``` - -2. **Check for peer dependency conflicts**: - - Review the error messages for conflicting package versions - - Try using `npm install --legacy-peer-deps` if conflicts persist - -## Compilation Issues - -### Contract Won't Compile - -**Problem**: Your contract fails to compile or shows errors in the terminal. - -**Solutions**: - -1. **Check Solidity version compatibility**: - - Ensure your contract's pragma statement matches the compiler version in `hardhat.config.js` - - Example: If your contract uses `pragma solidity ^0.8.0;`, set `solidity: "0.8.28"` or compatible version - -2. **Verify imports**: - - Ensure all imported contracts are in the correct paths - - For OpenZeppelin contracts, make sure they're installed: `npm install @openzeppelin/contracts` - -3. **Clear artifacts and cache**: - ```bash - npx hardhat clean - npx hardhat compile - ``` - -4. **Check for syntax errors**: - - Carefully read error messages in the terminal - - Common issues include missing semicolons, incorrect function visibility, or type mismatches - -### Compilation Artifacts Missing - -**Problem**: The artifacts folder is empty or missing expected files. - -**Solutions**: - -1. **Ensure compilation completed successfully**: - - Check the terminal output for any error messages - - Look for "Compiled X Solidity files successfully" message - -2. **Verify contract file location**: - - Contracts must be in the `contracts` directory or subdirectories - - File must have .sol extension - -3. **Check hardhat.config.js settings**: - - Ensure the paths configuration is correct - - Default artifacts location is `./artifacts` - -### Compiler Version Errors - -**Problem**: Errors related to Solidity compiler version or features. - -**Solutions**: - -1. **Match pragma version with config**: - ```javascript - module.exports = { - solidity: { - version: "0.8.28", - settings: { - optimizer: { - enabled: true, - runs: 200 - } - } - } - }; - ``` - -2. **Use multiple compiler versions** (if needed): - ```javascript - module.exports = { - solidity: { - compilers: [ - { version: "0.8.28" }, - { version: "0.8.20" } - ] - } - }; - ``` - -## Testing Issues - -### Tests Fail to Run - -**Problem**: Tests don't execute or Hardhat throws errors when running tests. - -**Solutions**: - -1. **Verify test file location**: - - Test files must be in the `test` directory - - Files should end with `.js` or `.test.js` - -2. **Check test framework imports**: - ```javascript - const { expect } = require("chai"); - const { ethers } = require("hardhat"); - ``` - -3. **Ensure Hardhat Toolbox is installed**: - ```bash - npm install --save-dev @nomicfoundation/hardhat-toolbox - ``` - -4. **Run tests with verbose output**: - ```bash - npx hardhat test --verbose - ``` - -### Local Test Network Issues - -**Problem**: `npx hardhat node` fails to start or becomes unresponsive. - -**Solutions**: - -1. **Check if port 8545 is already in use**: - - Kill any process using port 8545 - - On Linux/Mac: `lsof -ti:8545 | xargs kill -9` - - On Windows: `netstat -ano | findstr :8545`, then kill the process with the appropriate process ID. - -2. **Specify a different port**: - ```bash - npx hardhat node --port 8546 - ``` - -3. **Reset the node**: - - Stop the node (Ctrl+C) - - Start it again with a fresh state - -### Test Assertions Failing - -**Problem**: Tests run but fail with assertion errors. - -**Solutions**: - -1. **Check account balances**: - - Ensure test accounts have sufficient ETH - - Hardhat node provides test accounts with 10,000 ETH each - -2. **Wait for transaction confirmations**: - ```javascript - const tx = await contract.someFunction(); - await tx.wait(); // Wait for transaction to be mined - ``` - -3. **Verify contract state**: - - Use console.log to debug values - - Check if contract was properly deployed in beforeEach hooks - -4. **Review timing issues**: - - Add appropriate waits between transactions - - Use `await ethers.provider.send("evm_mine")` to mine blocks manually - -## Network Configuration Issues - -### Cannot Connect to Local Development Node - -**Problem**: Hardhat cannot connect to the local development node. - -**Solutions**: - -1. **Verify the node is running**: - - Ensure your local development node is started - - Check the [Local Development Node](/smart-contracts/dev-environments/local-dev-node/) guide - -2. **Check network configuration**: - ```javascript - module.exports = { - networks: { - polkadotTestNet: { - url: "http://localhost:8545", - chainId: 420420420, - accounts: [PRIVATE_KEY] - } - } - }; - ``` - -3. **Verify URL and port**: - - Ensure the URL matches your local node's RPC endpoint - - Default is usually `http://localhost:8545` - -4. **Check firewall settings**: - - Ensure your firewall allows connections to localhost:8545 - -### Private Key Configuration Issues - -**Problem**: Hardhat cannot access or use the configured private key. - -**Solutions**: - -1. **Verify private key is set**: - ```bash - npx hardhat vars get PRIVATE_KEY - ``` - -2. **Set private key correctly**: - ```bash - npx hardhat vars set PRIVATE_KEY "0x..." - ``` - - Ensure the key starts with "0x" - - Do not include quotes within the actual key value - -3. **Check key format in config**: - ```javascript - const { vars } = require("hardhat/config"); - const PRIVATE_KEY = vars.get("PRIVATE_KEY"); - - module.exports = { - networks: { - polkadotTestNet: { - accounts: [PRIVATE_KEY] // Should be an array - } - } - }; - ``` - -4. **Alternative: Use mnemonic**: - ```javascript - accounts: { - mnemonic: "test test test test test test test test test test test junk" - } - ``` - -### Wrong Network Selected - -**Problem**: Deployment or transactions go to the wrong network. - -**Solutions**: - -1. **Specify network explicitly**: - ```bash - npx hardhat run scripts/deploy.js --network polkadotTestNet - ``` - -2. **Verify network in config**: - - Check that the network name matches what you're using in commands - - Ensure chainId matches the target network - -3. **Check default network**: - ```javascript - module.exports = { - defaultNetwork: "polkadotTestNet", - networks: { - // network configs - } - }; - ``` - -## Deployment Issues - -### Insufficient Funds Error - -**Problem**: Deployment fails with "insufficient funds" error. - -**Solutions**: - -1. **Check account balance**: - - Verify you have enough test tokens in your account - - For local development node, accounts should be pre-funded - -2. **Get test tokens**: - - Visit the [Polkadot faucet](/smart-contracts/faucet/){target=\_blank} for test networks - - Wait a few minutes for faucet transactions to complete - -3. **Verify account address**: - - Ensure the private key corresponds to the account you think you're using - - Check the account balance matches expectations - -### Ignition Deployment Fails - -**Problem**: Deployment using Hardhat Ignition fails or throws errors. - -**Solutions**: - -1. **Check Ignition module syntax**: - ```javascript - const { buildModule } = require("@nomicfoundation/hardhat-ignition/modules"); - - module.exports = buildModule("LockModule", (m) => { - const unlockTime = m.getParameter("unlockTime"); - const lock = m.contract("Lock", [unlockTime]); - return { lock }; - }); - ``` - -2. **Verify constructor parameters**: - - Ensure all required constructor parameters are provided - - Check parameter types match the contract's constructor - -3. **Clear previous deployments**: - ```bash - rm -rf ignition/deployments/ - ``` - -4. **Use deployment script alternative**: - - Create a manual deployment script in the `scripts` folder if Ignition continues to fail - -### Deployment Script Errors - -**Problem**: Custom deployment scripts fail to execute. - -**Solutions**: - -1. **Check script imports**: - ```javascript - const hre = require("hardhat"); - // or - const { ethers } = require("hardhat"); - ``` - -2. **Verify contract factory**: - ```javascript - const Contract = await ethers.getContractFactory("ContractName"); - const contract = await Contract.deploy(/* constructor args */); - await contract.deployed(); - ``` - -3. **Add error handling**: - ```javascript - try { - // deployment code - } catch (error) { - console.error("Deployment failed:", error); - process.exit(1); - } - ``` - -4. **Check gas settings**: - ```javascript - const contract = await Contract.deploy({ - gasLimit: 5000000 - }); - ``` - -### Contract Deployment Timeout - -**Problem**: Deployment hangs or times out. - -**Solutions**: - -1. **Increase timeout in config**: - ```javascript - module.exports = { - networks: { - polkadotTestNet: { - timeout: 60000 // 60 seconds - } - } - }; - ``` - -2. **Check network connection**: - - Verify the RPC endpoint is responsive - - Test with a simple read operation first - -3. **Reduce contract complexity**: - - Large contracts may take longer to deploy - - Consider splitting into multiple contracts - -## Contract Interaction Issues - -### Cannot Connect to Deployed Contract - -**Problem**: Scripts fail to interact with a deployed contract. - -**Solutions**: - -1. **Verify contract address**: - - Ensure you're using the correct deployed contract address - - Check the deployment output or Ignition deployment files - -2. **Check contract ABI**: - ```javascript - const Contract = await ethers.getContractFactory("ContractName"); - const contract = Contract.attach(contractAddress); - ``` - -3. **Verify network connection**: - - Ensure you're connected to the same network where the contract was deployed - - Use the `--network` flag when running scripts - -### Transaction Reverts - -**Problem**: Transactions revert when calling contract functions. - -**Solutions**: - -1. **Check function requirements**: - - Verify all require() conditions in the contract are satisfied - - Ensure you're meeting any access control requirements - -2. **Add debugging**: - ```javascript - try { - const tx = await contract.someFunction(); - const receipt = await tx.wait(); - console.log("Transaction successful:", receipt); - } catch (error) { - console.error("Transaction failed:", error.message); - } - ``` - -3. **Check gas limits**: - ```javascript - const tx = await contract.someFunction({ - gasLimit: 500000 - }); - ``` - -4. **Verify function parameters**: - - Ensure parameter types match the function signature - - Check for correct number of parameters - -### Read Functions Not Returning Values - -**Problem**: View/pure functions don't return expected values. - -**Solutions**: - -1. **Use call() for read-only functions**: - ```javascript - const value = await contract.someViewFunction(); - console.log("Returned value:", value); - ``` - -2. **Check contract state**: - - Verify the contract has been properly initialized - - Ensure any required state changes have been completed - -3. **Handle BigNumber returns**: - ```javascript - const value = await contract.someFunction(); - console.log("Value:", value.toString()); - ``` - -### Write Functions Not Updating State - -**Problem**: State-changing functions execute but don't update state. - -**Solutions**: - -1. **Wait for transaction confirmation**: - ```javascript - const tx = await contract.someFunction(); - await tx.wait(); // Wait for the transaction to be mined - const newState = await contract.getState(); - ``` - -2. **Check transaction receipt**: - ```javascript - const tx = await contract.someFunction(); - const receipt = await tx.wait(); - console.log("Transaction status:", receipt.status); - ``` - -3. **Verify transaction success**: - - Check that receipt.status === 1 (success) - - Review any events emitted by the transaction - -4. **Check for reverts**: - - Look for revert reasons in the error message - - Verify contract logic and access controls - -## Performance and Configuration Issues - -### Compilation is Slow - -**Problem**: Contract compilation takes a long time. - -**Solutions**: - -1. **Enable compiler cache**: - - Hardhat caches compilation results by default - - Ensure the cache folder is not ignored in .gitignore - -2. **Optimize compiler settings**: - ```javascript - module.exports = { - solidity: { - version: "0.8.28", - settings: { - optimizer: { - enabled: true, - runs: 200 - } - } - } - }; - ``` - -3. **Compile specific contracts**: - ```bash - npx hardhat compile --force - ``` - -### Hardhat Console Issues - -**Problem**: Cannot start Hardhat console or console commands fail. - -**Solutions**: - -1. **Start console with correct network**: - ```bash - npx hardhat console --network polkadotTestNet - ``` - -2. **Check console imports**: - ```javascript - // In console - const Contract = await ethers.getContractFactory("ContractName"); - ``` - -3. **Verify network connection**: - - Ensure the target network is accessible - - Check network configuration in hardhat.config.js - -### Plugin Configuration Issues - -**Problem**: Hardhat plugins not working correctly. - -**Solutions**: - -1. **Verify plugin installation**: - ```bash - npm list @nomicfoundation/hardhat-toolbox - ``` - -2. **Check plugin import in config**: - ```javascript - require("@nomicfoundation/hardhat-toolbox"); - ``` - -3. **Update plugins to latest versions**: - ```bash - npm update @nomicfoundation/hardhat-toolbox - ``` - -4. **Check for plugin conflicts**: - - Review package.json for version conflicts - - Try removing and reinstalling conflicting plugins - -## Environment Variable Issues - -### Cannot Access Environment Variables - -**Problem**: Scripts cannot read environment variables. - -**Solutions**: - -1. **Use Hardhat vars correctly**: - ```bash - npx hardhat vars set VARIABLE_NAME "value" - npx hardhat vars get VARIABLE_NAME - ``` - -2. **Alternative: Use dotenv**: - ```bash - npm install dotenv - ``` - ```javascript - require('dotenv').config(); - const value = process.env.VARIABLE_NAME; - ``` - -3. **Check variable access in config**: - ```javascript - const { vars } = require("hardhat/config"); - const value = vars.get("VARIABLE_NAME"); - ``` - -### Private Key Security Warnings - -**Problem**: Concerns about private key security. - -**Solutions**: - -1. **Never commit private keys**: - - Add `.env` to .gitignore if using dotenv - - Hardhat vars are stored locally and not in git - -2. **Use test accounts for development**: - - Use the pre-funded accounts from `npx hardhat node` - - Never use real private keys for testing - -3. **Verify .gitignore includes**: - ``` - node_modules - .env - coverage - cache - artifacts - ignition/deployments/ - ``` - -## Where to Go Next - -Continue improving your Hardhat workflow with these resources: - -
- -- Guide __Get Started with Hardhat__ - - --- - - Return to the basics and review the Hardhat setup process. - - [:octicons-arrow-right-24: Get Started](/smart-contracts/dev-environments/hardhat/get-started) - -- Guide __Compile and Test Smart Contracts__ - - --- - - Learn how to compile and test your smart contracts using Hardhat. - - [:octicons-arrow-right-24: Get Started](/smart-contracts/dev-environments/hardhat/compile-and-test) - -- Guide __Deploy Smart Contracts__ - - --- - - Learn how to deploy and interact with smart contracts using Hardhat. - - [:octicons-arrow-right-24: Get Started](/smart-contracts/dev-environments/hardhat/deploy-a-contract) - -- External __Hardhat Documentation__ - - --- - - Explore official Hardhat documentation for advanced troubleshooting. - - [:octicons-arrow-right-24: Visit Docs](https://hardhat.org/docs){target=\_blank} - -
\ No newline at end of file From 47171b63e956684aafc8066e5625f41e193d3c8f Mon Sep 17 00:00:00 2001 From: DAWN KELLY Date: Tue, 18 Nov 2025 15:13:22 -0500 Subject: [PATCH 5/6] grammarly --- .../hardhat/troubleshooting-faq.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/smart-contracts/dev-environments/hardhat/troubleshooting-faq.md b/smart-contracts/dev-environments/hardhat/troubleshooting-faq.md index fc8b0757e..c026a0d43 100644 --- a/smart-contracts/dev-environments/hardhat/troubleshooting-faq.md +++ b/smart-contracts/dev-environments/hardhat/troubleshooting-faq.md @@ -1,6 +1,6 @@ --- title: Troubleshooting Hardhat -description: Common issues related to developing, compiling, and deploying smart contracts using Hardhat on Polkadot Hub paired with troubleshooting suggestions. +description: Common issues related to developing, compiling, and deploying smart contracts using Hardhat on Polkadot Hub, paired with troubleshooting suggestions. categories: Smart Contracts, Tooling --- @@ -16,11 +16,11 @@ This guide provides solutions to common issues you may encounter when using Hard - Download the appropriate LTS version from [nodejs.org](https://nodejs.org/). - **Use nvm for version management**: - - Install nvm (Node Version Manager) to easily switch between Node versions. + - Install nvm (Node Version Manager) to to switch between Node versions easily. - Run `nvm install --lts` to install the latest LTS version. - Run `nvm use --lts` to switch to it. -## Install of Hardhat or its dependencies via npm fails +## Installation of Hardhat or its dependencies via npm fails - **Clear npm cache**: ```bash @@ -57,7 +57,7 @@ This guide provides solutions to common issues you may encounter when using Hard - **Check Solidity version compatibility**: - Ensure your contract's pragma statement matches the compiler version in `hardhat.config.js`. - - Example: If your contract uses `pragma solidity ^0.8.0;`, set `solidity: "0.8.28"` or compatible version. + - Example: If your contract uses `pragma solidity ^0.8.0;`, set `solidity: "0.8.28"` or another compatible version. - **Verify imports**: - Ensure all imported contracts are in the correct paths. @@ -80,7 +80,7 @@ This guide provides solutions to common issues you may encounter when using Hard - **Ensure compilation completed successfully**: - Check the terminal output for any error messages. - - Look for "Compiled X Solidity files successfully" message. + - Look for the "Compiled X Solidity files successfully" message. - **Verify contract file location**: - Contracts must be in the `contracts` directory or subdirectories. @@ -171,7 +171,7 @@ This guide provides solutions to common issues you may encounter when using Hard - **Verify contract state**: - Use `console.log` to debug values. - - Check if contract was properly deployed in `beforeEach` hooks. + - Check if the contract was properly deployed in `beforeEach` hooks. - **Review timing issues**: - Add appropriate waits between transactions. @@ -263,7 +263,7 @@ This guide provides solutions to common issues you may encounter when using Hard - **Check account balance**: - Verify you have enough test tokens in your account. - - For local development node, accounts should be pre-funded. + - For the local development node, accounts should be pre-funded. - **Get test tokens**: - Visit the [Polkadot faucet](/smart-contracts/faucet/){target=\_blank} for test networks. @@ -394,7 +394,7 @@ This guide provides solutions to common issues you may encounter when using Hard - **Verify function parameters**: - Ensure parameter types match the function signature. - - Check for correct number of parameters. + - Check for the correct number of parameters. ## `View` or `pure` functions don't return expected values @@ -435,7 +435,7 @@ This guide provides solutions to common issues you may encounter when using Hard - Review any events emitted by the transaction. - **Check for reverts**: - - Look for revert reasons in the error message. + - Look for any revert reasons in the error message. - Verify contract logic and access controls. ## Contract compilation takes a long time From 576de6ab4e480d401e85cd85c7a5dc915ba3fbcc Mon Sep 17 00:00:00 2001 From: DAWN KELLY Date: Tue, 18 Nov 2025 15:15:45 -0500 Subject: [PATCH 6/6] fresh llms --- .ai/categories/smart-contracts.md | 562 ++++++++++++++++++ .ai/categories/tooling.md | 562 ++++++++++++++++++ ...nvironments-hardhat-troubleshooting-faq.md | 559 +++++++++++++++++ .ai/site-index.json | 152 +++++ llms-full.jsonl | 26 + llms.txt | 4 +- 6 files changed, 1864 insertions(+), 1 deletion(-) create mode 100644 .ai/pages/smart-contracts-dev-environments-hardhat-troubleshooting-faq.md diff --git a/.ai/categories/smart-contracts.md b/.ai/categories/smart-contracts.md index d38467093..140b749cc 100644 --- a/.ai/categories/smart-contracts.md +++ b/.ai/categories/smart-contracts.md @@ -15262,6 +15262,568 @@ You now know the weight system, how it affects transaction fee computation, and - [Web3 Foundation Research](https://research.web3.foundation/Polkadot/overview/token-economics#relay-chain-transaction-fees-and-per-block-transaction-limits){target=\_blank} +--- + +Page Title: Troubleshooting Hardhat + +- Source (raw): https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/smart-contracts-dev-environments-hardhat-troubleshooting-faq.md +- Canonical (HTML): https://docs.polkadot.com/smart-contracts/dev-environments/hardhat/troubleshooting-faq/ +- Summary: Common issues related to developing, compiling, and deploying smart contracts using Hardhat on Polkadot Hub, paired with troubleshooting suggestions. + +# Hardhat Troubleshooting + +This guide provides solutions to common issues you may encounter when using Hardhat with Polkadot Hub. If you're experiencing problems with installation, compilation, deployment, testing, or contract interaction, you'll likely find the solution here. + +## Hardhat fails to install or run with version-related errors + +- **Check Node.js version**: + - Ensure you have an LTS version of Node.js installed (18.x, 20.x, or 22.x). + - Check your current version with `node --version`. + - Download the appropriate LTS version from [nodejs.org](https://nodejs.org/). + +- **Use nvm for version management**: + - Install nvm (Node Version Manager) to to switch between Node versions easily. + - Run `nvm install --lts` to install the latest LTS version. + - Run `nvm use --lts` to switch to it. + +## Installation of Hardhat or its dependencies via npm fails + +- **Clear npm cache**: + ```bash + npm cache clean --force + ``` + +- **Delete node_modules and package-lock.json**: + ```bash + rm -rf node_modules package-lock.json + npm install + ``` + +- **Check npm version**: + - Ensure you have npm 7.x or higher + - Update npm with `npm install -g npm@latest` + +- **Install with specific version**: + ```bash + npm install --save-dev hardhat@^2.26.0 + ``` + +## Hardhat Toolbox fails to install or causes conflicts + +- **Install Hardhat Toolbox separately**: + ```bash + npm install --save-dev @nomicfoundation/hardhat-toolbox + ``` + +- **Check for peer dependency conflicts**: + - Review the error messages for conflicting package versions. + - Try using `npm install --legacy-peer-deps` if conflicts persist. + +## Your contract fails to compile or shows errors in the terminal + +- **Check Solidity version compatibility**: + - Ensure your contract's pragma statement matches the compiler version in `hardhat.config.js`. + - Example: If your contract uses `pragma solidity ^0.8.0;`, set `solidity: "0.8.28"` or another compatible version. + +- **Verify imports**: + - Ensure all imported contracts are in the correct paths. + - For OpenZeppelin contracts, make sure dependencies are installed using the command: + ```bash + `npm install @openzeppelin/contracts` + ``` + +- **Clear artifacts and cache**: + ```bash + npx hardhat clean + npx hardhat compile + ``` + +- **Check for syntax errors**: + - Carefully read error messages in the terminal. + - Check for common syntax errors, such as missing semicolons, incorrect function visibility, or type mismatches. + +## The artifacts folder is empty or missing expected files + +- **Ensure compilation completed successfully**: + - Check the terminal output for any error messages. + - Look for the "Compiled X Solidity files successfully" message. + +- **Verify contract file location**: + - Contracts must be in the `contracts` directory or subdirectories. + - File must have `.sol` extension. + +- **Check `hardhat.config.js` settings**: + - Ensure the paths configuration is correct. + - Default artifacts location is `./artifacts`. + +## Errors related to Solidity compiler version or features + +- **Match pragma version with config**: + ```javascript + module.exports = { + solidity: { + version: "0.8.28", + settings: { + optimizer: { + enabled: true, + runs: 200 + } + } + } + }; + ``` + +- **Use multiple compiler versions** (if needed): + ```javascript + module.exports = { + solidity: { + compilers: [ + { version: "0.8.28" }, + { version: "0.8.20" } + ] + } + }; + ``` + +## Tests don't execute or Hardhat throws errors when running tests + +- **Verify test file location**: + - Test files must be in the `test` directory. + - Files should end with `.js` or `.test.js`. + +- **Check test framework imports**: + ```javascript + const { expect } = require("chai"); + const { ethers } = require("hardhat"); + ``` + +- **Ensure Hardhat Toolbox is installed**: + ```bash + npm install --save-dev @nomicfoundation/hardhat-toolbox + ``` + +- **Run tests with verbose output**: + ```bash + npx hardhat test --verbose + ``` + +## The `npx hardhat node` fails to start or becomes unresponsive + +1. **Check if port 8545 is already in use**: + - Kill any process using port 8545 as follows: + - On Linux/Mac: `lsof -ti:8545 | xargs kill -9` + - On Windows: `netstat -ano | findstr :8545`, then kill the process with the appropriate process ID. + +2. **Specify a different port**: + ```bash + npx hardhat node --port 8546 + ``` + +3. **Reset the node**: + - Stop the node (Ctrl+C). + - Start it again with a fresh state. + +## Tests run but fail with assertion errors + +- **Check account balances**: + - Ensure test accounts have sufficient ETH. + - Hardhat node provides test accounts with 10,000 ETH each. + +- **Wait for transaction confirmations**: + ```javascript + const tx = await contract.someFunction(); + await tx.wait(); // Wait for transaction to be mined + ``` + +- **Verify contract state**: + - Use `console.log` to debug values. + - Check if the contract was properly deployed in `beforeEach` hooks. + +- **Review timing issues**: + - Add appropriate waits between transactions. + - Use `await ethers.provider.send("evm_mine")` to mine blocks manually. + +## Hardhat cannot connect to the local development node + +1. **Verify the node is running**: + - Ensure your local development node is started. + - Check the [Local Development Node](/smart-contracts/dev-environments/local-dev-node/) guide. + +2. **Check network configuration**: + ```javascript + module.exports = { + networks: { + polkadotTestNet: { + url: "http://localhost:8545", + chainId: 420420420, + accounts: [PRIVATE_KEY] + } + } + }; + ``` + +3. **Verify URL and port**: + - Ensure the URL matches your local node's RPC endpoint. + - Default is usually `http://localhost:8545`. + +4. **Check firewall settings**: + - Ensure your firewall allows connections to `localhost:8545`. + +## Hardhat cannot access or use the configured private key + +- **Verify private key is set**: + ```bash + npx hardhat vars get PRIVATE_KEY + ``` + +- **Set private key correctly**: + ```bash + npx hardhat vars set PRIVATE_KEY "0x..." + ``` + - Ensure the key starts with "0x". + - Do not include quotes within the actual key value. + +- **Check key format in config**: + ```javascript + const { vars } = require("hardhat/config"); + const PRIVATE_KEY = vars.get("PRIVATE_KEY"); + + module.exports = { + networks: { + polkadotTestNet: { + accounts: [PRIVATE_KEY] // Should be an array + } + } + }; + ``` + +- **Alternative: Use mnemonic**: + ```javascript + accounts: { + mnemonic: "test test test test test test test test test test test junk" + } + ``` + +## Deployment or transactions go to the wrong network + +- **Specify network explicitly**: + ```bash + npx hardhat run scripts/deploy.js --network polkadotTestNet + ``` + +- **Verify network in config**: + - Check that the network name matches what you're using in commands + - Ensure chainId matches the target network + +- **Check default network**: + ```javascript + module.exports = { + defaultNetwork: "polkadotTestNet", + networks: { + // network configs + } + }; + ``` + +## Deployment fails with "insufficient funds" error + +- **Check account balance**: + - Verify you have enough test tokens in your account. + - For the local development node, accounts should be pre-funded. + +- **Get test tokens**: + - Visit the [Polkadot faucet](/smart-contracts/faucet/){target=\_blank} for test networks. + - Wait a few minutes for faucet transactions to complete. + +- **Verify account address**: + - Ensure the private key corresponds to the account you think you're using. + - Check the account balance matches expectations. + +## Deployment using Hardhat Ignition fails or throws errors + +- **Check ignition module syntax**: + ```javascript + const { buildModule } = require("@nomicfoundation/hardhat-ignition/modules"); + + module.exports = buildModule("LockModule", (m) => { + const unlockTime = m.getParameter("unlockTime"); + const lock = m.contract("Lock", [unlockTime]); + return { lock }; + }); + ``` + +- **Verify constructor parameters**: + - Ensure all required constructor parameters are provided. + - Check parameter types match the contract's constructor. + +- **Clear previous deployments**: + ```bash + rm -rf ignition/deployments/ + ``` + +- **Use deployment script alternative**: + - Create a manual deployment script in the `scripts` folder if Ignition continues to fail. + +## Custom deployment scripts fail to execute + +- **Check script imports**: + ```javascript + const hre = require("hardhat"); + // or + const { ethers } = require("hardhat"); + ``` + +- **Verify contract factory**: + ```javascript + const Contract = await ethers.getContractFactory("ContractName"); + const contract = await Contract.deploy(/* constructor args */); + await contract.deployed(); + ``` + +- **Add error handling**: + ```javascript + try { + // deployment code + } catch (error) { + console.error("Deployment failed:", error); + process.exit(1); + } + ``` + +- **Check gas settings**: + ```javascript + const contract = await Contract.deploy({ + gasLimit: 5000000 + }); + ``` + +## Contract deployment hangs or times out + +- **Increase timeout in config**: + ```javascript + module.exports = { + networks: { + polkadotTestNet: { + timeout: 60000 // 60 seconds + } + } + }; + ``` + +- **Check network connection**: + - Verify the RPC endpoint is responsive. + - Test with a simple read operation first. + +- **Reduce contract complexity**: + - Large contracts may take longer to deploy. + - Consider splitting into multiple contracts. + +## Scripts fail to interact with a deployed contract + +- **Verify contract address**: + - Ensure you're using the correct deployed contract address. + - Check the deployment output or ignition deployment files. + +- **Check contract ABI**: + ```javascript + const Contract = await ethers.getContractFactory("ContractName"); + const contract = Contract.attach(contractAddress); + ``` + +- **Verify network connection**: + - Ensure you're connected to the same network where the contract was deployed. + - Use the `--network` flag when running scripts. + +## Transactions revert when calling contract functions + +- **Check function requirements**: + - Verify all `require()` conditions in the contract are satisfied. + - Ensure you're meeting any access control requirements. + +- **Add debugging**: + ```javascript + try { + const tx = await contract.someFunction(); + const receipt = await tx.wait(); + console.log("Transaction successful:", receipt); + } catch (error) { + console.error("Transaction failed:", error.message); + } + ``` + +- **Check gas limits**: + ```javascript + const tx = await contract.someFunction({ + gasLimit: 500000 + }); + ``` + +- **Verify function parameters**: + - Ensure parameter types match the function signature. + - Check for the correct number of parameters. + +## `View` or `pure` functions don't return expected values + +- **Use `call()` for read-only functions**: + ```javascript + const value = await contract.someViewFunction(); + console.log("Returned value:", value); + ``` + +- **Check contract state**: + - Verify the contract has been properly initialized. + - Ensure any required state changes have been completed. + +- **Handle `BigNumber` returns**: + ```javascript + const value = await contract.someFunction(); + console.log("Value:", value.toString()); + ``` + +## State-changing functions execute but don't update state + +- **Wait for transaction confirmation**: + ```javascript + const tx = await contract.someFunction(); + await tx.wait(); // Wait for the transaction to be mined + const newState = await contract.getState(); + ``` + +- **Check transaction receipt**: + ```javascript + const tx = await contract.someFunction(); + const receipt = await tx.wait(); + console.log("Transaction status:", receipt.status); + ``` + +- **Verify transaction success**: + - Check that `receipt.status === 1` (success). + - Review any events emitted by the transaction. + +- **Check for reverts**: + - Look for any revert reasons in the error message. + - Verify contract logic and access controls. + +## Contract compilation takes a long time + +- **Enable compiler cache**: + - Hardhat caches compilation results by default. + - Ensure the cache folder is not ignored in `.gitignore`. + +- **Optimize compiler settings**: + ```javascript + module.exports = { + solidity: { + version: "0.8.28", + settings: { + optimizer: { + enabled: true, + runs: 200 + } + } + } + }; + ``` + +- **Compile specific contracts**: + ```bash + npx hardhat compile --force + ``` + +## Can't start Hardhat console or console commands fail + +- **Start console with correct network**: + ```bash + npx hardhat console --network polkadotTestNet + ``` + +- **Check console imports**: + ```javascript + // In console + const Contract = await ethers.getContractFactory("ContractName"); + ``` + +- **Verify network connection**: + - Ensure the target network is accessible. + - Check network configuration in `hardhat.config.js`. + +## Hardhat plugins not working correctly + +- **Verify plugin installation**: + ```bash + npm list @nomicfoundation/hardhat-toolbox + ``` + +- **Check plugin import in config**: + ```javascript + require("@nomicfoundation/hardhat-toolbox"); + ``` + +- **Update plugins to latest versions**: + ```bash + npm update @nomicfoundation/hardhat-toolbox + ``` + +- **Check for plugin conflicts**: + - Review `package.json` for version conflicts. + - Try removing and reinstalling conflicting plugins. + +## Scripts cannot read environment variables + +- **Use Hardhat vars correctly**: + ```bash + npx hardhat vars set VARIABLE_NAME "value" + npx hardhat vars get VARIABLE_NAME + ``` + +- **Alternative: Use dotenv**: + ```bash + npm install dotenv + ``` + ```javascript + require('dotenv').config(); + const value = process.env.VARIABLE_NAME; + ``` + +- **Check variable access in config**: + ```javascript + const { vars } = require("hardhat/config"); + const value = vars.get("VARIABLE_NAME"); + ``` + +## Concerns about private key security + +- **Never commit private keys**: + - Add `.env` to `.gitignore` if using `dotenv`. + - Hardhat vars are stored locally and not in git. + +- **Use test accounts for development**: + - Use the pre-funded accounts from `npx hardhat node`. + - Never use private keys with real funds for testing. + +- **Verify `.gitignore` includes**: + ``` + node_modules + .env + coverage + cache + artifacts + ignition/deployments/ + ``` + +## Where to Go Next + +- External __Hardhat Documentation__ + + --- + + Explore official Hardhat documentation for advanced troubleshooting. + + [:octicons-arrow-right-24: Visit Docs](https://hardhat.org/docs){target=\_blank} + + + + --- Page Title: Troubleshooting Hardhat on Polkadot Hub diff --git a/.ai/categories/tooling.md b/.ai/categories/tooling.md index 2a6fc0135..7490c65e5 100644 --- a/.ai/categories/tooling.md +++ b/.ai/categories/tooling.md @@ -21294,6 +21294,568 @@ You now know the weight system, how it affects transaction fee computation, and - [Web3 Foundation Research](https://research.web3.foundation/Polkadot/overview/token-economics#relay-chain-transaction-fees-and-per-block-transaction-limits){target=\_blank} +--- + +Page Title: Troubleshooting Hardhat + +- Source (raw): https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/smart-contracts-dev-environments-hardhat-troubleshooting-faq.md +- Canonical (HTML): https://docs.polkadot.com/smart-contracts/dev-environments/hardhat/troubleshooting-faq/ +- Summary: Common issues related to developing, compiling, and deploying smart contracts using Hardhat on Polkadot Hub, paired with troubleshooting suggestions. + +# Hardhat Troubleshooting + +This guide provides solutions to common issues you may encounter when using Hardhat with Polkadot Hub. If you're experiencing problems with installation, compilation, deployment, testing, or contract interaction, you'll likely find the solution here. + +## Hardhat fails to install or run with version-related errors + +- **Check Node.js version**: + - Ensure you have an LTS version of Node.js installed (18.x, 20.x, or 22.x). + - Check your current version with `node --version`. + - Download the appropriate LTS version from [nodejs.org](https://nodejs.org/). + +- **Use nvm for version management**: + - Install nvm (Node Version Manager) to to switch between Node versions easily. + - Run `nvm install --lts` to install the latest LTS version. + - Run `nvm use --lts` to switch to it. + +## Installation of Hardhat or its dependencies via npm fails + +- **Clear npm cache**: + ```bash + npm cache clean --force + ``` + +- **Delete node_modules and package-lock.json**: + ```bash + rm -rf node_modules package-lock.json + npm install + ``` + +- **Check npm version**: + - Ensure you have npm 7.x or higher + - Update npm with `npm install -g npm@latest` + +- **Install with specific version**: + ```bash + npm install --save-dev hardhat@^2.26.0 + ``` + +## Hardhat Toolbox fails to install or causes conflicts + +- **Install Hardhat Toolbox separately**: + ```bash + npm install --save-dev @nomicfoundation/hardhat-toolbox + ``` + +- **Check for peer dependency conflicts**: + - Review the error messages for conflicting package versions. + - Try using `npm install --legacy-peer-deps` if conflicts persist. + +## Your contract fails to compile or shows errors in the terminal + +- **Check Solidity version compatibility**: + - Ensure your contract's pragma statement matches the compiler version in `hardhat.config.js`. + - Example: If your contract uses `pragma solidity ^0.8.0;`, set `solidity: "0.8.28"` or another compatible version. + +- **Verify imports**: + - Ensure all imported contracts are in the correct paths. + - For OpenZeppelin contracts, make sure dependencies are installed using the command: + ```bash + `npm install @openzeppelin/contracts` + ``` + +- **Clear artifacts and cache**: + ```bash + npx hardhat clean + npx hardhat compile + ``` + +- **Check for syntax errors**: + - Carefully read error messages in the terminal. + - Check for common syntax errors, such as missing semicolons, incorrect function visibility, or type mismatches. + +## The artifacts folder is empty or missing expected files + +- **Ensure compilation completed successfully**: + - Check the terminal output for any error messages. + - Look for the "Compiled X Solidity files successfully" message. + +- **Verify contract file location**: + - Contracts must be in the `contracts` directory or subdirectories. + - File must have `.sol` extension. + +- **Check `hardhat.config.js` settings**: + - Ensure the paths configuration is correct. + - Default artifacts location is `./artifacts`. + +## Errors related to Solidity compiler version or features + +- **Match pragma version with config**: + ```javascript + module.exports = { + solidity: { + version: "0.8.28", + settings: { + optimizer: { + enabled: true, + runs: 200 + } + } + } + }; + ``` + +- **Use multiple compiler versions** (if needed): + ```javascript + module.exports = { + solidity: { + compilers: [ + { version: "0.8.28" }, + { version: "0.8.20" } + ] + } + }; + ``` + +## Tests don't execute or Hardhat throws errors when running tests + +- **Verify test file location**: + - Test files must be in the `test` directory. + - Files should end with `.js` or `.test.js`. + +- **Check test framework imports**: + ```javascript + const { expect } = require("chai"); + const { ethers } = require("hardhat"); + ``` + +- **Ensure Hardhat Toolbox is installed**: + ```bash + npm install --save-dev @nomicfoundation/hardhat-toolbox + ``` + +- **Run tests with verbose output**: + ```bash + npx hardhat test --verbose + ``` + +## The `npx hardhat node` fails to start or becomes unresponsive + +1. **Check if port 8545 is already in use**: + - Kill any process using port 8545 as follows: + - On Linux/Mac: `lsof -ti:8545 | xargs kill -9` + - On Windows: `netstat -ano | findstr :8545`, then kill the process with the appropriate process ID. + +2. **Specify a different port**: + ```bash + npx hardhat node --port 8546 + ``` + +3. **Reset the node**: + - Stop the node (Ctrl+C). + - Start it again with a fresh state. + +## Tests run but fail with assertion errors + +- **Check account balances**: + - Ensure test accounts have sufficient ETH. + - Hardhat node provides test accounts with 10,000 ETH each. + +- **Wait for transaction confirmations**: + ```javascript + const tx = await contract.someFunction(); + await tx.wait(); // Wait for transaction to be mined + ``` + +- **Verify contract state**: + - Use `console.log` to debug values. + - Check if the contract was properly deployed in `beforeEach` hooks. + +- **Review timing issues**: + - Add appropriate waits between transactions. + - Use `await ethers.provider.send("evm_mine")` to mine blocks manually. + +## Hardhat cannot connect to the local development node + +1. **Verify the node is running**: + - Ensure your local development node is started. + - Check the [Local Development Node](/smart-contracts/dev-environments/local-dev-node/) guide. + +2. **Check network configuration**: + ```javascript + module.exports = { + networks: { + polkadotTestNet: { + url: "http://localhost:8545", + chainId: 420420420, + accounts: [PRIVATE_KEY] + } + } + }; + ``` + +3. **Verify URL and port**: + - Ensure the URL matches your local node's RPC endpoint. + - Default is usually `http://localhost:8545`. + +4. **Check firewall settings**: + - Ensure your firewall allows connections to `localhost:8545`. + +## Hardhat cannot access or use the configured private key + +- **Verify private key is set**: + ```bash + npx hardhat vars get PRIVATE_KEY + ``` + +- **Set private key correctly**: + ```bash + npx hardhat vars set PRIVATE_KEY "0x..." + ``` + - Ensure the key starts with "0x". + - Do not include quotes within the actual key value. + +- **Check key format in config**: + ```javascript + const { vars } = require("hardhat/config"); + const PRIVATE_KEY = vars.get("PRIVATE_KEY"); + + module.exports = { + networks: { + polkadotTestNet: { + accounts: [PRIVATE_KEY] // Should be an array + } + } + }; + ``` + +- **Alternative: Use mnemonic**: + ```javascript + accounts: { + mnemonic: "test test test test test test test test test test test junk" + } + ``` + +## Deployment or transactions go to the wrong network + +- **Specify network explicitly**: + ```bash + npx hardhat run scripts/deploy.js --network polkadotTestNet + ``` + +- **Verify network in config**: + - Check that the network name matches what you're using in commands + - Ensure chainId matches the target network + +- **Check default network**: + ```javascript + module.exports = { + defaultNetwork: "polkadotTestNet", + networks: { + // network configs + } + }; + ``` + +## Deployment fails with "insufficient funds" error + +- **Check account balance**: + - Verify you have enough test tokens in your account. + - For the local development node, accounts should be pre-funded. + +- **Get test tokens**: + - Visit the [Polkadot faucet](/smart-contracts/faucet/){target=\_blank} for test networks. + - Wait a few minutes for faucet transactions to complete. + +- **Verify account address**: + - Ensure the private key corresponds to the account you think you're using. + - Check the account balance matches expectations. + +## Deployment using Hardhat Ignition fails or throws errors + +- **Check ignition module syntax**: + ```javascript + const { buildModule } = require("@nomicfoundation/hardhat-ignition/modules"); + + module.exports = buildModule("LockModule", (m) => { + const unlockTime = m.getParameter("unlockTime"); + const lock = m.contract("Lock", [unlockTime]); + return { lock }; + }); + ``` + +- **Verify constructor parameters**: + - Ensure all required constructor parameters are provided. + - Check parameter types match the contract's constructor. + +- **Clear previous deployments**: + ```bash + rm -rf ignition/deployments/ + ``` + +- **Use deployment script alternative**: + - Create a manual deployment script in the `scripts` folder if Ignition continues to fail. + +## Custom deployment scripts fail to execute + +- **Check script imports**: + ```javascript + const hre = require("hardhat"); + // or + const { ethers } = require("hardhat"); + ``` + +- **Verify contract factory**: + ```javascript + const Contract = await ethers.getContractFactory("ContractName"); + const contract = await Contract.deploy(/* constructor args */); + await contract.deployed(); + ``` + +- **Add error handling**: + ```javascript + try { + // deployment code + } catch (error) { + console.error("Deployment failed:", error); + process.exit(1); + } + ``` + +- **Check gas settings**: + ```javascript + const contract = await Contract.deploy({ + gasLimit: 5000000 + }); + ``` + +## Contract deployment hangs or times out + +- **Increase timeout in config**: + ```javascript + module.exports = { + networks: { + polkadotTestNet: { + timeout: 60000 // 60 seconds + } + } + }; + ``` + +- **Check network connection**: + - Verify the RPC endpoint is responsive. + - Test with a simple read operation first. + +- **Reduce contract complexity**: + - Large contracts may take longer to deploy. + - Consider splitting into multiple contracts. + +## Scripts fail to interact with a deployed contract + +- **Verify contract address**: + - Ensure you're using the correct deployed contract address. + - Check the deployment output or ignition deployment files. + +- **Check contract ABI**: + ```javascript + const Contract = await ethers.getContractFactory("ContractName"); + const contract = Contract.attach(contractAddress); + ``` + +- **Verify network connection**: + - Ensure you're connected to the same network where the contract was deployed. + - Use the `--network` flag when running scripts. + +## Transactions revert when calling contract functions + +- **Check function requirements**: + - Verify all `require()` conditions in the contract are satisfied. + - Ensure you're meeting any access control requirements. + +- **Add debugging**: + ```javascript + try { + const tx = await contract.someFunction(); + const receipt = await tx.wait(); + console.log("Transaction successful:", receipt); + } catch (error) { + console.error("Transaction failed:", error.message); + } + ``` + +- **Check gas limits**: + ```javascript + const tx = await contract.someFunction({ + gasLimit: 500000 + }); + ``` + +- **Verify function parameters**: + - Ensure parameter types match the function signature. + - Check for the correct number of parameters. + +## `View` or `pure` functions don't return expected values + +- **Use `call()` for read-only functions**: + ```javascript + const value = await contract.someViewFunction(); + console.log("Returned value:", value); + ``` + +- **Check contract state**: + - Verify the contract has been properly initialized. + - Ensure any required state changes have been completed. + +- **Handle `BigNumber` returns**: + ```javascript + const value = await contract.someFunction(); + console.log("Value:", value.toString()); + ``` + +## State-changing functions execute but don't update state + +- **Wait for transaction confirmation**: + ```javascript + const tx = await contract.someFunction(); + await tx.wait(); // Wait for the transaction to be mined + const newState = await contract.getState(); + ``` + +- **Check transaction receipt**: + ```javascript + const tx = await contract.someFunction(); + const receipt = await tx.wait(); + console.log("Transaction status:", receipt.status); + ``` + +- **Verify transaction success**: + - Check that `receipt.status === 1` (success). + - Review any events emitted by the transaction. + +- **Check for reverts**: + - Look for any revert reasons in the error message. + - Verify contract logic and access controls. + +## Contract compilation takes a long time + +- **Enable compiler cache**: + - Hardhat caches compilation results by default. + - Ensure the cache folder is not ignored in `.gitignore`. + +- **Optimize compiler settings**: + ```javascript + module.exports = { + solidity: { + version: "0.8.28", + settings: { + optimizer: { + enabled: true, + runs: 200 + } + } + } + }; + ``` + +- **Compile specific contracts**: + ```bash + npx hardhat compile --force + ``` + +## Can't start Hardhat console or console commands fail + +- **Start console with correct network**: + ```bash + npx hardhat console --network polkadotTestNet + ``` + +- **Check console imports**: + ```javascript + // In console + const Contract = await ethers.getContractFactory("ContractName"); + ``` + +- **Verify network connection**: + - Ensure the target network is accessible. + - Check network configuration in `hardhat.config.js`. + +## Hardhat plugins not working correctly + +- **Verify plugin installation**: + ```bash + npm list @nomicfoundation/hardhat-toolbox + ``` + +- **Check plugin import in config**: + ```javascript + require("@nomicfoundation/hardhat-toolbox"); + ``` + +- **Update plugins to latest versions**: + ```bash + npm update @nomicfoundation/hardhat-toolbox + ``` + +- **Check for plugin conflicts**: + - Review `package.json` for version conflicts. + - Try removing and reinstalling conflicting plugins. + +## Scripts cannot read environment variables + +- **Use Hardhat vars correctly**: + ```bash + npx hardhat vars set VARIABLE_NAME "value" + npx hardhat vars get VARIABLE_NAME + ``` + +- **Alternative: Use dotenv**: + ```bash + npm install dotenv + ``` + ```javascript + require('dotenv').config(); + const value = process.env.VARIABLE_NAME; + ``` + +- **Check variable access in config**: + ```javascript + const { vars } = require("hardhat/config"); + const value = vars.get("VARIABLE_NAME"); + ``` + +## Concerns about private key security + +- **Never commit private keys**: + - Add `.env` to `.gitignore` if using `dotenv`. + - Hardhat vars are stored locally and not in git. + +- **Use test accounts for development**: + - Use the pre-funded accounts from `npx hardhat node`. + - Never use private keys with real funds for testing. + +- **Verify `.gitignore` includes**: + ``` + node_modules + .env + coverage + cache + artifacts + ignition/deployments/ + ``` + +## Where to Go Next + +- External __Hardhat Documentation__ + + --- + + Explore official Hardhat documentation for advanced troubleshooting. + + [:octicons-arrow-right-24: Visit Docs](https://hardhat.org/docs){target=\_blank} + + + + --- Page Title: Troubleshooting Hardhat on Polkadot Hub diff --git a/.ai/pages/smart-contracts-dev-environments-hardhat-troubleshooting-faq.md b/.ai/pages/smart-contracts-dev-environments-hardhat-troubleshooting-faq.md new file mode 100644 index 000000000..d19c88bc5 --- /dev/null +++ b/.ai/pages/smart-contracts-dev-environments-hardhat-troubleshooting-faq.md @@ -0,0 +1,559 @@ +--- +title: Troubleshooting Hardhat +description: Common issues related to developing, compiling, and deploying smart contracts using Hardhat on Polkadot Hub, paired with troubleshooting suggestions. +categories: Smart Contracts, Tooling +url: https://docs.polkadot.com/smart-contracts/dev-environments/hardhat/troubleshooting-faq/ +--- + +# Hardhat Troubleshooting + +This guide provides solutions to common issues you may encounter when using Hardhat with Polkadot Hub. If you're experiencing problems with installation, compilation, deployment, testing, or contract interaction, you'll likely find the solution here. + +## Hardhat fails to install or run with version-related errors + +- **Check Node.js version**: + - Ensure you have an LTS version of Node.js installed (18.x, 20.x, or 22.x). + - Check your current version with `node --version`. + - Download the appropriate LTS version from [nodejs.org](https://nodejs.org/). + +- **Use nvm for version management**: + - Install nvm (Node Version Manager) to to switch between Node versions easily. + - Run `nvm install --lts` to install the latest LTS version. + - Run `nvm use --lts` to switch to it. + +## Installation of Hardhat or its dependencies via npm fails + +- **Clear npm cache**: + ```bash + npm cache clean --force + ``` + +- **Delete node_modules and package-lock.json**: + ```bash + rm -rf node_modules package-lock.json + npm install + ``` + +- **Check npm version**: + - Ensure you have npm 7.x or higher + - Update npm with `npm install -g npm@latest` + +- **Install with specific version**: + ```bash + npm install --save-dev hardhat@^2.26.0 + ``` + +## Hardhat Toolbox fails to install or causes conflicts + +- **Install Hardhat Toolbox separately**: + ```bash + npm install --save-dev @nomicfoundation/hardhat-toolbox + ``` + +- **Check for peer dependency conflicts**: + - Review the error messages for conflicting package versions. + - Try using `npm install --legacy-peer-deps` if conflicts persist. + +## Your contract fails to compile or shows errors in the terminal + +- **Check Solidity version compatibility**: + - Ensure your contract's pragma statement matches the compiler version in `hardhat.config.js`. + - Example: If your contract uses `pragma solidity ^0.8.0;`, set `solidity: "0.8.28"` or another compatible version. + +- **Verify imports**: + - Ensure all imported contracts are in the correct paths. + - For OpenZeppelin contracts, make sure dependencies are installed using the command: + ```bash + `npm install @openzeppelin/contracts` + ``` + +- **Clear artifacts and cache**: + ```bash + npx hardhat clean + npx hardhat compile + ``` + +- **Check for syntax errors**: + - Carefully read error messages in the terminal. + - Check for common syntax errors, such as missing semicolons, incorrect function visibility, or type mismatches. + +## The artifacts folder is empty or missing expected files + +- **Ensure compilation completed successfully**: + - Check the terminal output for any error messages. + - Look for the "Compiled X Solidity files successfully" message. + +- **Verify contract file location**: + - Contracts must be in the `contracts` directory or subdirectories. + - File must have `.sol` extension. + +- **Check `hardhat.config.js` settings**: + - Ensure the paths configuration is correct. + - Default artifacts location is `./artifacts`. + +## Errors related to Solidity compiler version or features + +- **Match pragma version with config**: + ```javascript + module.exports = { + solidity: { + version: "0.8.28", + settings: { + optimizer: { + enabled: true, + runs: 200 + } + } + } + }; + ``` + +- **Use multiple compiler versions** (if needed): + ```javascript + module.exports = { + solidity: { + compilers: [ + { version: "0.8.28" }, + { version: "0.8.20" } + ] + } + }; + ``` + +## Tests don't execute or Hardhat throws errors when running tests + +- **Verify test file location**: + - Test files must be in the `test` directory. + - Files should end with `.js` or `.test.js`. + +- **Check test framework imports**: + ```javascript + const { expect } = require("chai"); + const { ethers } = require("hardhat"); + ``` + +- **Ensure Hardhat Toolbox is installed**: + ```bash + npm install --save-dev @nomicfoundation/hardhat-toolbox + ``` + +- **Run tests with verbose output**: + ```bash + npx hardhat test --verbose + ``` + +## The `npx hardhat node` fails to start or becomes unresponsive + +1. **Check if port 8545 is already in use**: + - Kill any process using port 8545 as follows: + - On Linux/Mac: `lsof -ti:8545 | xargs kill -9` + - On Windows: `netstat -ano | findstr :8545`, then kill the process with the appropriate process ID. + +2. **Specify a different port**: + ```bash + npx hardhat node --port 8546 + ``` + +3. **Reset the node**: + - Stop the node (Ctrl+C). + - Start it again with a fresh state. + +## Tests run but fail with assertion errors + +- **Check account balances**: + - Ensure test accounts have sufficient ETH. + - Hardhat node provides test accounts with 10,000 ETH each. + +- **Wait for transaction confirmations**: + ```javascript + const tx = await contract.someFunction(); + await tx.wait(); // Wait for transaction to be mined + ``` + +- **Verify contract state**: + - Use `console.log` to debug values. + - Check if the contract was properly deployed in `beforeEach` hooks. + +- **Review timing issues**: + - Add appropriate waits between transactions. + - Use `await ethers.provider.send("evm_mine")` to mine blocks manually. + +## Hardhat cannot connect to the local development node + +1. **Verify the node is running**: + - Ensure your local development node is started. + - Check the [Local Development Node](/smart-contracts/dev-environments/local-dev-node/) guide. + +2. **Check network configuration**: + ```javascript + module.exports = { + networks: { + polkadotTestNet: { + url: "http://localhost:8545", + chainId: 420420420, + accounts: [PRIVATE_KEY] + } + } + }; + ``` + +3. **Verify URL and port**: + - Ensure the URL matches your local node's RPC endpoint. + - Default is usually `http://localhost:8545`. + +4. **Check firewall settings**: + - Ensure your firewall allows connections to `localhost:8545`. + +## Hardhat cannot access or use the configured private key + +- **Verify private key is set**: + ```bash + npx hardhat vars get PRIVATE_KEY + ``` + +- **Set private key correctly**: + ```bash + npx hardhat vars set PRIVATE_KEY "0x..." + ``` + - Ensure the key starts with "0x". + - Do not include quotes within the actual key value. + +- **Check key format in config**: + ```javascript + const { vars } = require("hardhat/config"); + const PRIVATE_KEY = vars.get("PRIVATE_KEY"); + + module.exports = { + networks: { + polkadotTestNet: { + accounts: [PRIVATE_KEY] // Should be an array + } + } + }; + ``` + +- **Alternative: Use mnemonic**: + ```javascript + accounts: { + mnemonic: "test test test test test test test test test test test junk" + } + ``` + +## Deployment or transactions go to the wrong network + +- **Specify network explicitly**: + ```bash + npx hardhat run scripts/deploy.js --network polkadotTestNet + ``` + +- **Verify network in config**: + - Check that the network name matches what you're using in commands + - Ensure chainId matches the target network + +- **Check default network**: + ```javascript + module.exports = { + defaultNetwork: "polkadotTestNet", + networks: { + // network configs + } + }; + ``` + +## Deployment fails with "insufficient funds" error + +- **Check account balance**: + - Verify you have enough test tokens in your account. + - For the local development node, accounts should be pre-funded. + +- **Get test tokens**: + - Visit the [Polkadot faucet](/smart-contracts/faucet/){target=\_blank} for test networks. + - Wait a few minutes for faucet transactions to complete. + +- **Verify account address**: + - Ensure the private key corresponds to the account you think you're using. + - Check the account balance matches expectations. + +## Deployment using Hardhat Ignition fails or throws errors + +- **Check ignition module syntax**: + ```javascript + const { buildModule } = require("@nomicfoundation/hardhat-ignition/modules"); + + module.exports = buildModule("LockModule", (m) => { + const unlockTime = m.getParameter("unlockTime"); + const lock = m.contract("Lock", [unlockTime]); + return { lock }; + }); + ``` + +- **Verify constructor parameters**: + - Ensure all required constructor parameters are provided. + - Check parameter types match the contract's constructor. + +- **Clear previous deployments**: + ```bash + rm -rf ignition/deployments/ + ``` + +- **Use deployment script alternative**: + - Create a manual deployment script in the `scripts` folder if Ignition continues to fail. + +## Custom deployment scripts fail to execute + +- **Check script imports**: + ```javascript + const hre = require("hardhat"); + // or + const { ethers } = require("hardhat"); + ``` + +- **Verify contract factory**: + ```javascript + const Contract = await ethers.getContractFactory("ContractName"); + const contract = await Contract.deploy(/* constructor args */); + await contract.deployed(); + ``` + +- **Add error handling**: + ```javascript + try { + // deployment code + } catch (error) { + console.error("Deployment failed:", error); + process.exit(1); + } + ``` + +- **Check gas settings**: + ```javascript + const contract = await Contract.deploy({ + gasLimit: 5000000 + }); + ``` + +## Contract deployment hangs or times out + +- **Increase timeout in config**: + ```javascript + module.exports = { + networks: { + polkadotTestNet: { + timeout: 60000 // 60 seconds + } + } + }; + ``` + +- **Check network connection**: + - Verify the RPC endpoint is responsive. + - Test with a simple read operation first. + +- **Reduce contract complexity**: + - Large contracts may take longer to deploy. + - Consider splitting into multiple contracts. + +## Scripts fail to interact with a deployed contract + +- **Verify contract address**: + - Ensure you're using the correct deployed contract address. + - Check the deployment output or ignition deployment files. + +- **Check contract ABI**: + ```javascript + const Contract = await ethers.getContractFactory("ContractName"); + const contract = Contract.attach(contractAddress); + ``` + +- **Verify network connection**: + - Ensure you're connected to the same network where the contract was deployed. + - Use the `--network` flag when running scripts. + +## Transactions revert when calling contract functions + +- **Check function requirements**: + - Verify all `require()` conditions in the contract are satisfied. + - Ensure you're meeting any access control requirements. + +- **Add debugging**: + ```javascript + try { + const tx = await contract.someFunction(); + const receipt = await tx.wait(); + console.log("Transaction successful:", receipt); + } catch (error) { + console.error("Transaction failed:", error.message); + } + ``` + +- **Check gas limits**: + ```javascript + const tx = await contract.someFunction({ + gasLimit: 500000 + }); + ``` + +- **Verify function parameters**: + - Ensure parameter types match the function signature. + - Check for the correct number of parameters. + +## `View` or `pure` functions don't return expected values + +- **Use `call()` for read-only functions**: + ```javascript + const value = await contract.someViewFunction(); + console.log("Returned value:", value); + ``` + +- **Check contract state**: + - Verify the contract has been properly initialized. + - Ensure any required state changes have been completed. + +- **Handle `BigNumber` returns**: + ```javascript + const value = await contract.someFunction(); + console.log("Value:", value.toString()); + ``` + +## State-changing functions execute but don't update state + +- **Wait for transaction confirmation**: + ```javascript + const tx = await contract.someFunction(); + await tx.wait(); // Wait for the transaction to be mined + const newState = await contract.getState(); + ``` + +- **Check transaction receipt**: + ```javascript + const tx = await contract.someFunction(); + const receipt = await tx.wait(); + console.log("Transaction status:", receipt.status); + ``` + +- **Verify transaction success**: + - Check that `receipt.status === 1` (success). + - Review any events emitted by the transaction. + +- **Check for reverts**: + - Look for any revert reasons in the error message. + - Verify contract logic and access controls. + +## Contract compilation takes a long time + +- **Enable compiler cache**: + - Hardhat caches compilation results by default. + - Ensure the cache folder is not ignored in `.gitignore`. + +- **Optimize compiler settings**: + ```javascript + module.exports = { + solidity: { + version: "0.8.28", + settings: { + optimizer: { + enabled: true, + runs: 200 + } + } + } + }; + ``` + +- **Compile specific contracts**: + ```bash + npx hardhat compile --force + ``` + +## Can't start Hardhat console or console commands fail + +- **Start console with correct network**: + ```bash + npx hardhat console --network polkadotTestNet + ``` + +- **Check console imports**: + ```javascript + // In console + const Contract = await ethers.getContractFactory("ContractName"); + ``` + +- **Verify network connection**: + - Ensure the target network is accessible. + - Check network configuration in `hardhat.config.js`. + +## Hardhat plugins not working correctly + +- **Verify plugin installation**: + ```bash + npm list @nomicfoundation/hardhat-toolbox + ``` + +- **Check plugin import in config**: + ```javascript + require("@nomicfoundation/hardhat-toolbox"); + ``` + +- **Update plugins to latest versions**: + ```bash + npm update @nomicfoundation/hardhat-toolbox + ``` + +- **Check for plugin conflicts**: + - Review `package.json` for version conflicts. + - Try removing and reinstalling conflicting plugins. + +## Scripts cannot read environment variables + +- **Use Hardhat vars correctly**: + ```bash + npx hardhat vars set VARIABLE_NAME "value" + npx hardhat vars get VARIABLE_NAME + ``` + +- **Alternative: Use dotenv**: + ```bash + npm install dotenv + ``` + ```javascript + require('dotenv').config(); + const value = process.env.VARIABLE_NAME; + ``` + +- **Check variable access in config**: + ```javascript + const { vars } = require("hardhat/config"); + const value = vars.get("VARIABLE_NAME"); + ``` + +## Concerns about private key security + +- **Never commit private keys**: + - Add `.env` to `.gitignore` if using `dotenv`. + - Hardhat vars are stored locally and not in git. + +- **Use test accounts for development**: + - Use the pre-funded accounts from `npx hardhat node`. + - Never use private keys with real funds for testing. + +- **Verify `.gitignore` includes**: + ``` + node_modules + .env + coverage + cache + artifacts + ignition/deployments/ + ``` + +## Where to Go Next + +- External __Hardhat Documentation__ + + --- + + Explore official Hardhat documentation for advanced troubleshooting. + + [:octicons-arrow-right-24: Visit Docs](https://hardhat.org/docs){target=\_blank} + + diff --git a/.ai/site-index.json b/.ai/site-index.json index f704e0ae6..262da72bb 100644 --- a/.ai/site-index.json +++ b/.ai/site-index.json @@ -11732,6 +11732,158 @@ "hash": "sha256:56ba36249ea8216ad513b13df3de6c0e490ba214897674d30331f1c7e7edbef3", "token_estimator": "heuristic-v1" }, + { + "id": "smart-contracts-dev-environments-hardhat-troubleshooting-faq", + "title": "Troubleshooting Hardhat", + "slug": "smart-contracts-dev-environments-hardhat-troubleshooting-faq", + "categories": [ + "Smart Contracts", + "Tooling" + ], + "raw_md_url": "https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/smart-contracts-dev-environments-hardhat-troubleshooting-faq.md", + "html_url": "https://docs.polkadot.com/smart-contracts/dev-environments/hardhat/troubleshooting-faq/", + "preview": "This guide provides solutions to common issues you may encounter when using Hardhat with Polkadot Hub. If you're experiencing problems with installation, compilation, deployment, testing, or contract interaction, you'll likely find the solution here.", + "outline": [ + { + "depth": 2, + "title": "Hardhat fails to install or run with version-related errors", + "anchor": "hardhat-fails-to-install-or-run-with-version-related-errors" + }, + { + "depth": 2, + "title": "Installation of Hardhat or its dependencies via npm fails", + "anchor": "installation-of-hardhat-or-its-dependencies-via-npm-fails" + }, + { + "depth": 2, + "title": "Hardhat Toolbox fails to install or causes conflicts", + "anchor": "hardhat-toolbox-fails-to-install-or-causes-conflicts" + }, + { + "depth": 2, + "title": "Your contract fails to compile or shows errors in the terminal", + "anchor": "your-contract-fails-to-compile-or-shows-errors-in-the-terminal" + }, + { + "depth": 2, + "title": "The artifacts folder is empty or missing expected files", + "anchor": "the-artifacts-folder-is-empty-or-missing-expected-files" + }, + { + "depth": 2, + "title": "Errors related to Solidity compiler version or features", + "anchor": "errors-related-to-solidity-compiler-version-or-features" + }, + { + "depth": 2, + "title": "Tests don't execute or Hardhat throws errors when running tests", + "anchor": "tests-dont-execute-or-hardhat-throws-errors-when-running-tests" + }, + { + "depth": 2, + "title": "The `npx hardhat node` fails to start or becomes unresponsive", + "anchor": "the-npx-hardhat-node-fails-to-start-or-becomes-unresponsive" + }, + { + "depth": 2, + "title": "Tests run but fail with assertion errors", + "anchor": "tests-run-but-fail-with-assertion-errors" + }, + { + "depth": 2, + "title": "Hardhat cannot connect to the local development node", + "anchor": "hardhat-cannot-connect-to-the-local-development-node" + }, + { + "depth": 2, + "title": "Hardhat cannot access or use the configured private key", + "anchor": "hardhat-cannot-access-or-use-the-configured-private-key" + }, + { + "depth": 2, + "title": "Deployment or transactions go to the wrong network", + "anchor": "deployment-or-transactions-go-to-the-wrong-network" + }, + { + "depth": 2, + "title": "Deployment fails with \"insufficient funds\" error", + "anchor": "deployment-fails-with-insufficient-funds-error" + }, + { + "depth": 2, + "title": "Deployment using Hardhat Ignition fails or throws errors", + "anchor": "deployment-using-hardhat-ignition-fails-or-throws-errors" + }, + { + "depth": 2, + "title": "Custom deployment scripts fail to execute", + "anchor": "custom-deployment-scripts-fail-to-execute" + }, + { + "depth": 2, + "title": "Contract deployment hangs or times out", + "anchor": "contract-deployment-hangs-or-times-out" + }, + { + "depth": 2, + "title": "Scripts fail to interact with a deployed contract", + "anchor": "scripts-fail-to-interact-with-a-deployed-contract" + }, + { + "depth": 2, + "title": "Transactions revert when calling contract functions", + "anchor": "transactions-revert-when-calling-contract-functions" + }, + { + "depth": 2, + "title": "`View` or `pure` functions don't return expected values", + "anchor": "view-or-pure-functions-dont-return-expected-values" + }, + { + "depth": 2, + "title": "State-changing functions execute but don't update state", + "anchor": "state-changing-functions-execute-but-dont-update-state" + }, + { + "depth": 2, + "title": "Contract compilation takes a long time", + "anchor": "contract-compilation-takes-a-long-time" + }, + { + "depth": 2, + "title": "Can't start Hardhat console or console commands fail", + "anchor": "cant-start-hardhat-console-or-console-commands-fail" + }, + { + "depth": 2, + "title": "Hardhat plugins not working correctly", + "anchor": "hardhat-plugins-not-working-correctly" + }, + { + "depth": 2, + "title": "Scripts cannot read environment variables", + "anchor": "scripts-cannot-read-environment-variables" + }, + { + "depth": 2, + "title": "Concerns about private key security", + "anchor": "concerns-about-private-key-security" + }, + { + "depth": 2, + "title": "Where to Go Next", + "anchor": "where-to-go-next" + } + ], + "stats": { + "chars": 15409, + "words": 1762, + "headings": 26, + "estimated_token_count_total": 3498 + }, + "hash": "sha256:935754d94993e1e7e8c31e7b7a2839ab553361ba4613b196b11b74e3d021dd26", + "token_estimator": "heuristic-v1" + }, { "id": "smart-contracts-dev-environments-hardhat-troubleshooting", "title": "Troubleshooting Hardhat on Polkadot Hub", diff --git a/llms-full.jsonl b/llms-full.jsonl index f45c3d890..0a0d553d6 100644 --- a/llms-full.jsonl +++ b/llms-full.jsonl @@ -1458,6 +1458,32 @@ {"page_id": "smart-contracts-dev-environments-hardhat-get-started", "page_title": "Use Hardhat with Polkadot Hub", "index": 8, "depth": 2, "title": "Interacting with Your Contract", "anchor": "interacting-with-your-contract", "start_char": 14963, "end_char": 16763, "estimated_token_count": 426, "token_estimator": "heuristic-v1", "text": "## Interacting with Your Contract\n\nOnce deployed, you can create a script to interact with your contract. To do so, create a file called `scripts/interact.js` and add some logic to interact with the contract.\n\nFor example, for the default `MyToken.sol` contract, you can use the following file that connects to the contract at its address and retrieves the `unlockTime`, which represents when funds can be withdrawn. The script converts this timestamp into a readable date and logs it. It then checks the contract's balance and displays it. Finally, it attempts to call the withdrawal function on the contract, but it catches and logs the error message if the withdrawal is not yet allowed (e.g., before `unlockTime`).\n\n```javascript title=\"interact.js\"\nconst hre = require('hardhat');\n\nasync function main() {\n // Get the contract factory\n const MyToken = await hre.ethers.getContractFactory('MyToken');\n\n // Replace with your deployed contract address\n const contractAddress = 'INSERT_CONTRACT_ADDRESS';\n\n // Attach to existing contract\n const token = await MyToken.attach(contractAddress);\n\n // Get signers\n const [deployer] = await hre.ethers.getSigners();\n\n // Read contract state\n const name = await token.name();\n const symbol = await token.symbol();\n const totalSupply = await token.totalSupply();\n const balance = await token.balanceOf(deployer.address);\n\n console.log(`Token: ${name} (${symbol})`);\n console.log(\n `Total Supply: ${hre.ethers.formatUnits(totalSupply, 18)} tokens`,\n );\n console.log(\n `Deployer Balance: ${hre.ethers.formatUnits(balance, 18)} tokens`,\n );\n}\n\nmain().catch((error) => {\n console.error(error);\n process.exitCode = 1;\n});\n\n```\n\nRun your interaction script:\n\n```bash\nnpx hardhat run scripts/interact.js --network polkadotHubTestnet\n```"} {"page_id": "smart-contracts-dev-environments-hardhat-get-started", "page_title": "Use Hardhat with Polkadot Hub", "index": 9, "depth": 2, "title": "Upgrading the Plugin", "anchor": "upgrading-the-plugin", "start_char": 16763, "end_char": 17423, "estimated_token_count": 176, "token_estimator": "heuristic-v1", "text": "## Upgrading the Plugin\n\nIf you already have a Hardhat Polkadot project and want to upgrade to a newer version of the plugin, to avoid errors (for example, `Cannot find module 'run-container'`), you can clean your dependencies by running the following commands:\n\n```bash\nrm -rf node_modules package-lock.json\n```\n\nAfter that, you can upgrade the plugin to the latest version by running the following commands:\n\n```bash\nnpm install --save-dev @parity/hardhat-polkadot@latest\nnpm install\n```\n\nConsider using [Node.js](https://nodejs.org/){target=\\_blank} 22.18+ and [npm](https://www.npmjs.com/){target=\\_blank} version 10.9.0+ to avoid issues with the plugin."} {"page_id": "smart-contracts-dev-environments-hardhat-get-started", "page_title": "Use Hardhat with Polkadot Hub", "index": 10, "depth": 2, "title": "Where to Go Next", "anchor": "where-to-go-next", "start_char": 17423, "end_char": 18514, "estimated_token_count": 253, "token_estimator": "heuristic-v1", "text": "## Where to Go Next\n\nHardhat provides a powerful environment for developing, testing, and deploying smart contracts on Polkadot Hub. Its plugin architecture allows seamless integration with PolkaVM through the `hardhat-resolc` and `hardhat-revive-node` plugins.\n\nExplore more about smart contracts through these resources:\n\n
\n\n- Guide __Get Started with Smart Contracts__\n\n ---\n\n Learn how to get started with smart contracts\n\n [:octicons-arrow-right-24: Get Started](/smart-contracts/get-started/)\n\n- External __Hardhat Documentation__\n\n ---\n\n Learn more about Hardhat's advanced features and best practices.\n\n [:octicons-arrow-right-24: Get Started](https://hardhat.org/docs){target=\\_blank}\n\n- External __OpenZeppelin Contracts__\n\n ---\n\n Test your skills by deploying contracts with prebuilt templates.\n\n [:octicons-arrow-right-24: Get Started](https://www.openzeppelin.com/solidity-contracts){target=\\_blank}\n\n
"} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting-faq", "page_title": "Troubleshooting Hardhat", "index": 0, "depth": 2, "title": "Hardhat fails to install or run with version-related errors", "anchor": "hardhat-fails-to-install-or-run-with-version-related-errors", "start_char": 279, "end_char": 824, "estimated_token_count": 144, "token_estimator": "heuristic-v1", "text": "## Hardhat fails to install or run with version-related errors\n\n- **Check Node.js version**:\n - Ensure you have an LTS version of Node.js installed (18.x, 20.x, or 22.x).\n - Check your current version with `node --version`.\n - Download the appropriate LTS version from [nodejs.org](https://nodejs.org/).\n\n- **Use nvm for version management**:\n - Install nvm (Node Version Manager) to to switch between Node versions easily.\n - Run `nvm install --lts` to install the latest LTS version.\n - Run `nvm use --lts` to switch to it."} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting-faq", "page_title": "Troubleshooting Hardhat", "index": 1, "depth": 2, "title": "Installation of Hardhat or its dependencies via npm fails", "anchor": "installation-of-hardhat-or-its-dependencies-via-npm-fails", "start_char": 824, "end_char": 1303, "estimated_token_count": 129, "token_estimator": "heuristic-v1", "text": "## Installation of Hardhat or its dependencies via npm fails\n\n- **Clear npm cache**:\n ```bash\n npm cache clean --force\n ```\n\n- **Delete node_modules and package-lock.json**:\n ```bash\n rm -rf node_modules package-lock.json\n npm install\n ```\n\n- **Check npm version**:\n - Ensure you have npm 7.x or higher\n - Update npm with `npm install -g npm@latest`\n\n- **Install with specific version**:\n ```bash\n npm install --save-dev hardhat@^2.26.0\n ```"} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting-faq", "page_title": "Troubleshooting Hardhat", "index": 2, "depth": 2, "title": "Hardhat Toolbox fails to install or causes conflicts", "anchor": "hardhat-toolbox-fails-to-install-or-causes-conflicts", "start_char": 1303, "end_char": 1664, "estimated_token_count": 79, "token_estimator": "heuristic-v1", "text": "## Hardhat Toolbox fails to install or causes conflicts\n\n- **Install Hardhat Toolbox separately**:\n ```bash\n npm install --save-dev @nomicfoundation/hardhat-toolbox\n ```\n\n- **Check for peer dependency conflicts**:\n - Review the error messages for conflicting package versions.\n - Try using `npm install --legacy-peer-deps` if conflicts persist."} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting-faq", "page_title": "Troubleshooting Hardhat", "index": 3, "depth": 2, "title": "Your contract fails to compile or shows errors in the terminal", "anchor": "your-contract-fails-to-compile-or-shows-errors-in-the-terminal", "start_char": 1664, "end_char": 2551, "estimated_token_count": 190, "token_estimator": "heuristic-v1", "text": "## Your contract fails to compile or shows errors in the terminal\n\n- **Check Solidity version compatibility**:\n - Ensure your contract's pragma statement matches the compiler version in `hardhat.config.js`.\n - Example: If your contract uses `pragma solidity ^0.8.0;`, set `solidity: \"0.8.28\"` or another compatible version.\n\n- **Verify imports**:\n - Ensure all imported contracts are in the correct paths.\n - For OpenZeppelin contracts, make sure dependencies are installed using the command: \n ```bash\n `npm install @openzeppelin/contracts`\n ```\n\n- **Clear artifacts and cache**:\n ```bash\n npx hardhat clean\n npx hardhat compile\n ```\n\n- **Check for syntax errors**:\n - Carefully read error messages in the terminal.\n - Check for common syntax errors, such as missing semicolons, incorrect function visibility, or type mismatches."} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting-faq", "page_title": "Troubleshooting Hardhat", "index": 4, "depth": 2, "title": "The artifacts folder is empty or missing expected files", "anchor": "the-artifacts-folder-is-empty-or-missing-expected-files", "start_char": 2551, "end_char": 3078, "estimated_token_count": 111, "token_estimator": "heuristic-v1", "text": "## The artifacts folder is empty or missing expected files\n\n- **Ensure compilation completed successfully**:\n - Check the terminal output for any error messages.\n - Look for the \"Compiled X Solidity files successfully\" message.\n\n- **Verify contract file location**:\n - Contracts must be in the `contracts` directory or subdirectories.\n - File must have `.sol` extension.\n\n- **Check `hardhat.config.js` settings**:\n - Ensure the paths configuration is correct.\n - Default artifacts location is `./artifacts`."} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting-faq", "page_title": "Troubleshooting Hardhat", "index": 5, "depth": 2, "title": "Errors related to Solidity compiler version or features", "anchor": "errors-related-to-solidity-compiler-version-or-features", "start_char": 3078, "end_char": 3631, "estimated_token_count": 123, "token_estimator": "heuristic-v1", "text": "## Errors related to Solidity compiler version or features\n\n- **Match pragma version with config**:\n ```javascript\n module.exports = {\n solidity: {\n version: \"0.8.28\",\n settings: {\n optimizer: {\n enabled: true,\n runs: 200\n }\n }\n }\n };\n ```\n\n- **Use multiple compiler versions** (if needed):\n ```javascript\n module.exports = {\n solidity: {\n compilers: [\n { version: \"0.8.28\" },\n { version: \"0.8.20\" }\n ]\n }\n };\n ```"} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting-faq", "page_title": "Troubleshooting Hardhat", "index": 6, "depth": 2, "title": "Tests don't execute or Hardhat throws errors when running tests", "anchor": "tests-dont-execute-or-hardhat-throws-errors-when-running-tests", "start_char": 3631, "end_char": 4191, "estimated_token_count": 149, "token_estimator": "heuristic-v1", "text": "## Tests don't execute or Hardhat throws errors when running tests\n\n- **Verify test file location**:\n - Test files must be in the `test` directory.\n - Files should end with `.js` or `.test.js`.\n\n- **Check test framework imports**:\n ```javascript\n const { expect } = require(\"chai\");\n const { ethers } = require(\"hardhat\");\n ```\n\n- **Ensure Hardhat Toolbox is installed**:\n ```bash\n npm install --save-dev @nomicfoundation/hardhat-toolbox\n ```\n\n- **Run tests with verbose output**:\n ```bash\n npx hardhat test --verbose\n ```"} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting-faq", "page_title": "Troubleshooting Hardhat", "index": 7, "depth": 2, "title": "The `npx hardhat node` fails to start or becomes unresponsive", "anchor": "the-npx-hardhat-node-fails-to-start-or-becomes-unresponsive", "start_char": 4191, "end_char": 4701, "estimated_token_count": 135, "token_estimator": "heuristic-v1", "text": "## The `npx hardhat node` fails to start or becomes unresponsive\n\n1. **Check if port 8545 is already in use**:\n - Kill any process using port 8545 as follows:\n - On Linux/Mac: `lsof -ti:8545 | xargs kill -9`\n - On Windows: `netstat -ano | findstr :8545`, then kill the process with the appropriate process ID.\n\n2. **Specify a different port**:\n ```bash\n npx hardhat node --port 8546\n ```\n\n3. **Reset the node**:\n - Stop the node (Ctrl+C).\n - Start it again with a fresh state."} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting-faq", "page_title": "Troubleshooting Hardhat", "index": 8, "depth": 2, "title": "Tests run but fail with assertion errors", "anchor": "tests-run-but-fail-with-assertion-errors", "start_char": 4701, "end_char": 5360, "estimated_token_count": 151, "token_estimator": "heuristic-v1", "text": "## Tests run but fail with assertion errors\n\n- **Check account balances**:\n - Ensure test accounts have sufficient ETH.\n - Hardhat node provides test accounts with 10,000 ETH each.\n\n- **Wait for transaction confirmations**:\n ```javascript\n const tx = await contract.someFunction();\n await tx.wait(); // Wait for transaction to be mined\n ```\n\n- **Verify contract state**:\n - Use `console.log` to debug values.\n - Check if the contract was properly deployed in `beforeEach` hooks.\n\n- **Review timing issues**:\n - Add appropriate waits between transactions.\n - Use `await ethers.provider.send(\"evm_mine\")` to mine blocks manually."} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting-faq", "page_title": "Troubleshooting Hardhat", "index": 9, "depth": 2, "title": "Hardhat cannot connect to the local development node", "anchor": "hardhat-cannot-connect-to-the-local-development-node", "start_char": 5360, "end_char": 6105, "estimated_token_count": 172, "token_estimator": "heuristic-v1", "text": "## Hardhat cannot connect to the local development node\n\n1. **Verify the node is running**:\n - Ensure your local development node is started.\n - Check the [Local Development Node](/smart-contracts/dev-environments/local-dev-node/) guide.\n\n2. **Check network configuration**:\n ```javascript\n module.exports = {\n networks: {\n polkadotTestNet: {\n url: \"http://localhost:8545\",\n chainId: 420420420,\n accounts: [PRIVATE_KEY]\n }\n }\n };\n ```\n\n3. **Verify URL and port**:\n - Ensure the URL matches your local node's RPC endpoint.\n - Default is usually `http://localhost:8545`.\n\n4. **Check firewall settings**:\n - Ensure your firewall allows connections to `localhost:8545`."} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting-faq", "page_title": "Troubleshooting Hardhat", "index": 10, "depth": 2, "title": "Hardhat cannot access or use the configured private key", "anchor": "hardhat-cannot-access-or-use-the-configured-private-key", "start_char": 6105, "end_char": 6923, "estimated_token_count": 190, "token_estimator": "heuristic-v1", "text": "## Hardhat cannot access or use the configured private key\n\n- **Verify private key is set**:\n ```bash\n npx hardhat vars get PRIVATE_KEY\n ```\n\n- **Set private key correctly**:\n ```bash\n npx hardhat vars set PRIVATE_KEY \"0x...\"\n ```\n - Ensure the key starts with \"0x\".\n - Do not include quotes within the actual key value.\n\n- **Check key format in config**:\n ```javascript\n const { vars } = require(\"hardhat/config\");\n const PRIVATE_KEY = vars.get(\"PRIVATE_KEY\");\n \n module.exports = {\n networks: {\n polkadotTestNet: {\n accounts: [PRIVATE_KEY] // Should be an array\n }\n }\n };\n ```\n\n- **Alternative: Use mnemonic**:\n ```javascript\n accounts: {\n mnemonic: \"test test test test test test test test test test test junk\"\n }\n ```"} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting-faq", "page_title": "Troubleshooting Hardhat", "index": 11, "depth": 2, "title": "Deployment or transactions go to the wrong network", "anchor": "deployment-or-transactions-go-to-the-wrong-network", "start_char": 6923, "end_char": 7430, "estimated_token_count": 106, "token_estimator": "heuristic-v1", "text": "## Deployment or transactions go to the wrong network\n\n- **Specify network explicitly**:\n ```bash\n npx hardhat run scripts/deploy.js --network polkadotTestNet\n ```\n\n- **Verify network in config**:\n - Check that the network name matches what you're using in commands\n - Ensure chainId matches the target network\n\n- **Check default network**:\n ```javascript\n module.exports = {\n defaultNetwork: \"polkadotTestNet\",\n networks: {\n // network configs\n }\n };\n ```"} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting-faq", "page_title": "Troubleshooting Hardhat", "index": 12, "depth": 2, "title": "Deployment fails with \"insufficient funds\" error", "anchor": "deployment-fails-with-insufficient-funds-error", "start_char": 7430, "end_char": 7986, "estimated_token_count": 123, "token_estimator": "heuristic-v1", "text": "## Deployment fails with \"insufficient funds\" error\n\n- **Check account balance**:\n - Verify you have enough test tokens in your account.\n - For the local development node, accounts should be pre-funded.\n\n- **Get test tokens**:\n - Visit the [Polkadot faucet](/smart-contracts/faucet/){target=\\_blank} for test networks.\n - Wait a few minutes for faucet transactions to complete.\n\n- **Verify account address**:\n - Ensure the private key corresponds to the account you think you're using.\n - Check the account balance matches expectations."} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting-faq", "page_title": "Troubleshooting Hardhat", "index": 13, "depth": 2, "title": "Deployment using Hardhat Ignition fails or throws errors", "anchor": "deployment-using-hardhat-ignition-fails-or-throws-errors", "start_char": 7986, "end_char": 8780, "estimated_token_count": 178, "token_estimator": "heuristic-v1", "text": "## Deployment using Hardhat Ignition fails or throws errors\n\n- **Check ignition module syntax**:\n ```javascript\n const { buildModule } = require(\"@nomicfoundation/hardhat-ignition/modules\");\n \n module.exports = buildModule(\"LockModule\", (m) => {\n const unlockTime = m.getParameter(\"unlockTime\");\n const lock = m.contract(\"Lock\", [unlockTime]);\n return { lock };\n });\n ```\n\n- **Verify constructor parameters**:\n - Ensure all required constructor parameters are provided.\n - Check parameter types match the contract's constructor.\n\n- **Clear previous deployments**:\n ```bash\n rm -rf ignition/deployments/\n ```\n\n- **Use deployment script alternative**:\n - Create a manual deployment script in the `scripts` folder if Ignition continues to fail."} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting-faq", "page_title": "Troubleshooting Hardhat", "index": 14, "depth": 2, "title": "Custom deployment scripts fail to execute", "anchor": "custom-deployment-scripts-fail-to-execute", "start_char": 8780, "end_char": 9516, "estimated_token_count": 181, "token_estimator": "heuristic-v1", "text": "## Custom deployment scripts fail to execute\n\n- **Check script imports**:\n ```javascript\n const hre = require(\"hardhat\");\n // or\n const { ethers } = require(\"hardhat\");\n ```\n\n- **Verify contract factory**:\n ```javascript\n const Contract = await ethers.getContractFactory(\"ContractName\");\n const contract = await Contract.deploy(/* constructor args */);\n await contract.deployed();\n ```\n\n- **Add error handling**:\n ```javascript\n try {\n // deployment code\n } catch (error) {\n console.error(\"Deployment failed:\", error);\n process.exit(1);\n }\n ```\n\n- **Check gas settings**:\n ```javascript\n const contract = await Contract.deploy({\n gasLimit: 5000000\n });\n ```"} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting-faq", "page_title": "Troubleshooting Hardhat", "index": 15, "depth": 2, "title": "Contract deployment hangs or times out", "anchor": "contract-deployment-hangs-or-times-out", "start_char": 9516, "end_char": 10011, "estimated_token_count": 98, "token_estimator": "heuristic-v1", "text": "## Contract deployment hangs or times out\n\n- **Increase timeout in config**:\n ```javascript\n module.exports = {\n networks: {\n polkadotTestNet: {\n timeout: 60000 // 60 seconds\n }\n }\n };\n ```\n\n- **Check network connection**:\n - Verify the RPC endpoint is responsive.\n - Test with a simple read operation first.\n\n- **Reduce contract complexity**:\n - Large contracts may take longer to deploy.\n - Consider splitting into multiple contracts."} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting-faq", "page_title": "Troubleshooting Hardhat", "index": 16, "depth": 2, "title": "Scripts fail to interact with a deployed contract", "anchor": "scripts-fail-to-interact-with-a-deployed-contract", "start_char": 10011, "end_char": 10574, "estimated_token_count": 118, "token_estimator": "heuristic-v1", "text": "## Scripts fail to interact with a deployed contract\n\n- **Verify contract address**:\n - Ensure you're using the correct deployed contract address.\n - Check the deployment output or ignition deployment files.\n\n- **Check contract ABI**:\n ```javascript\n const Contract = await ethers.getContractFactory(\"ContractName\");\n const contract = Contract.attach(contractAddress);\n ```\n\n- **Verify network connection**:\n - Ensure you're connected to the same network where the contract was deployed.\n - Use the `--network` flag when running scripts."} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting-faq", "page_title": "Troubleshooting Hardhat", "index": 17, "depth": 2, "title": "Transactions revert when calling contract functions", "anchor": "transactions-revert-when-calling-contract-functions", "start_char": 10574, "end_char": 11356, "estimated_token_count": 173, "token_estimator": "heuristic-v1", "text": "## Transactions revert when calling contract functions\n\n- **Check function requirements**:\n - Verify all `require()` conditions in the contract are satisfied.\n - Ensure you're meeting any access control requirements.\n\n- **Add debugging**:\n ```javascript\n try {\n const tx = await contract.someFunction();\n const receipt = await tx.wait();\n console.log(\"Transaction successful:\", receipt);\n } catch (error) {\n console.error(\"Transaction failed:\", error.message);\n }\n ```\n\n- **Check gas limits**:\n ```javascript\n const tx = await contract.someFunction({\n gasLimit: 500000\n });\n ```\n\n- **Verify function parameters**:\n - Ensure parameter types match the function signature.\n - Check for the correct number of parameters."} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting-faq", "page_title": "Troubleshooting Hardhat", "index": 18, "depth": 2, "title": "`View` or `pure` functions don't return expected values", "anchor": "view-or-pure-functions-dont-return-expected-values", "start_char": 11356, "end_char": 11885, "estimated_token_count": 135, "token_estimator": "heuristic-v1", "text": "## `View` or `pure` functions don't return expected values\n\n- **Use `call()` for read-only functions**:\n ```javascript\n const value = await contract.someViewFunction();\n console.log(\"Returned value:\", value);\n ```\n\n- **Check contract state**:\n - Verify the contract has been properly initialized.\n - Ensure any required state changes have been completed.\n\n- **Handle `BigNumber` returns**:\n ```javascript\n const value = await contract.someFunction();\n console.log(\"Value:\", value.toString());\n ```"} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting-faq", "page_title": "Troubleshooting Hardhat", "index": 19, "depth": 2, "title": "State-changing functions execute but don't update state", "anchor": "state-changing-functions-execute-but-dont-update-state", "start_char": 11885, "end_char": 12636, "estimated_token_count": 179, "token_estimator": "heuristic-v1", "text": "## State-changing functions execute but don't update state\n\n- **Wait for transaction confirmation**:\n ```javascript\n const tx = await contract.someFunction();\n await tx.wait(); // Wait for the transaction to be mined\n const newState = await contract.getState();\n ```\n\n- **Check transaction receipt**:\n ```javascript\n const tx = await contract.someFunction();\n const receipt = await tx.wait();\n console.log(\"Transaction status:\", receipt.status);\n ```\n\n- **Verify transaction success**:\n - Check that `receipt.status === 1` (success).\n - Review any events emitted by the transaction.\n\n- **Check for reverts**:\n - Look for any revert reasons in the error message.\n - Verify contract logic and access controls."} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting-faq", "page_title": "Troubleshooting Hardhat", "index": 20, "depth": 2, "title": "Contract compilation takes a long time", "anchor": "contract-compilation-takes-a-long-time", "start_char": 12636, "end_char": 13169, "estimated_token_count": 113, "token_estimator": "heuristic-v1", "text": "## Contract compilation takes a long time\n\n- **Enable compiler cache**:\n - Hardhat caches compilation results by default.\n - Ensure the cache folder is not ignored in `.gitignore`.\n\n- **Optimize compiler settings**:\n ```javascript\n module.exports = {\n solidity: {\n version: \"0.8.28\",\n settings: {\n optimizer: {\n enabled: true,\n runs: 200\n }\n }\n }\n };\n ```\n\n- **Compile specific contracts**:\n ```bash\n npx hardhat compile --force\n ```"} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting-faq", "page_title": "Troubleshooting Hardhat", "index": 21, "depth": 2, "title": "Can't start Hardhat console or console commands fail", "anchor": "cant-start-hardhat-console-or-console-commands-fail", "start_char": 13169, "end_char": 13622, "estimated_token_count": 100, "token_estimator": "heuristic-v1", "text": "## Can't start Hardhat console or console commands fail\n\n- **Start console with correct network**:\n ```bash\n npx hardhat console --network polkadotTestNet\n ```\n\n- **Check console imports**:\n ```javascript\n // In console\n const Contract = await ethers.getContractFactory(\"ContractName\");\n ```\n\n- **Verify network connection**:\n - Ensure the target network is accessible.\n - Check network configuration in `hardhat.config.js`."} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting-faq", "page_title": "Troubleshooting Hardhat", "index": 22, "depth": 2, "title": "Hardhat plugins not working correctly", "anchor": "hardhat-plugins-not-working-correctly", "start_char": 13622, "end_char": 14131, "estimated_token_count": 116, "token_estimator": "heuristic-v1", "text": "## Hardhat plugins not working correctly\n\n- **Verify plugin installation**:\n ```bash\n npm list @nomicfoundation/hardhat-toolbox\n ```\n\n- **Check plugin import in config**:\n ```javascript\n require(\"@nomicfoundation/hardhat-toolbox\");\n ```\n\n- **Update plugins to latest versions**:\n ```bash\n npm update @nomicfoundation/hardhat-toolbox\n ```\n\n- **Check for plugin conflicts**:\n - Review `package.json` for version conflicts.\n - Try removing and reinstalling conflicting plugins."} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting-faq", "page_title": "Troubleshooting Hardhat", "index": 23, "depth": 2, "title": "Scripts cannot read environment variables", "anchor": "scripts-cannot-read-environment-variables", "start_char": 14131, "end_char": 14655, "estimated_token_count": 128, "token_estimator": "heuristic-v1", "text": "## Scripts cannot read environment variables\n\n- **Use Hardhat vars correctly**:\n ```bash\n npx hardhat vars set VARIABLE_NAME \"value\"\n npx hardhat vars get VARIABLE_NAME\n ```\n\n- **Alternative: Use dotenv**:\n ```bash\n npm install dotenv\n ```\n ```javascript\n require('dotenv').config();\n const value = process.env.VARIABLE_NAME;\n ```\n\n- **Check variable access in config**:\n ```javascript\n const { vars } = require(\"hardhat/config\");\n const value = vars.get(\"VARIABLE_NAME\");\n ```"} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting-faq", "page_title": "Troubleshooting Hardhat", "index": 24, "depth": 2, "title": "Concerns about private key security", "anchor": "concerns-about-private-key-security", "start_char": 14655, "end_char": 15136, "estimated_token_count": 109, "token_estimator": "heuristic-v1", "text": "## Concerns about private key security\n\n- **Never commit private keys**:\n - Add `.env` to `.gitignore` if using `dotenv`.\n - Hardhat vars are stored locally and not in git.\n\n- **Use test accounts for development**:\n - Use the pre-funded accounts from `npx hardhat node`.\n - Never use private keys with real funds for testing.\n\n- **Verify `.gitignore` includes**:\n ```\n node_modules\n .env\n coverage\n cache\n artifacts\n ignition/deployments/\n ```"} +{"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting-faq", "page_title": "Troubleshooting Hardhat", "index": 25, "depth": 2, "title": "Where to Go Next", "anchor": "where-to-go-next", "start_char": 15136, "end_char": 15409, "estimated_token_count": 68, "token_estimator": "heuristic-v1", "text": "## Where to Go Next\n\n- External __Hardhat Documentation__\n\n ---\n\n Explore official Hardhat documentation for advanced troubleshooting.\n\n [:octicons-arrow-right-24: Visit Docs](https://hardhat.org/docs){target=\\_blank}\n\n"} {"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting", "page_title": "Troubleshooting Hardhat on Polkadot Hub", "index": 0, "depth": 2, "title": "Overview", "anchor": "overview", "start_char": 27, "end_char": 292, "estimated_token_count": 48, "token_estimator": "heuristic-v1", "text": "## Overview\n\nThis guide provides solutions to common issues you may encounter when using Hardhat with Polkadot Hub. If you're experiencing problems with installation, compilation, deployment, testing, or contract interaction, you'll likely find the solution here."} {"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting", "page_title": "Troubleshooting Hardhat on Polkadot Hub", "index": 1, "depth": 2, "title": "Installation Issues", "anchor": "installation-issues", "start_char": 292, "end_char": 316, "estimated_token_count": 4, "token_estimator": "heuristic-v1", "text": "## Installation Issues"} {"page_id": "smart-contracts-dev-environments-hardhat-troubleshooting", "page_title": "Troubleshooting Hardhat on Polkadot Hub", "index": 2, "depth": 3, "title": "Node.js Version Incompatibility", "anchor": "nodejs-version-incompatibility", "start_char": 316, "end_char": 918, "estimated_token_count": 158, "token_estimator": "heuristic-v1", "text": "### Node.js Version Incompatibility\n\n**Problem**: Hardhat fails to install or run with version-related errors.\n\n**Solutions**:\n\n1. **Check Node.js version**:\n - Ensure you have an LTS version of Node.js installed (18.x, 20.x, or 22.x)\n - Check your current version with `node --version`\n - Download the appropriate LTS version from [nodejs.org](https://nodejs.org/)\n\n2. **Use nvm for version management**:\n - Install nvm (Node Version Manager) to easily switch between Node versions\n - Run `nvm install --lts` to install the latest LTS version\n - Run `nvm use --lts` to switch to it"} diff --git a/llms.txt b/llms.txt index 2f5b42ab4..e8039fa8b 100644 --- a/llms.txt +++ b/llms.txt @@ -6,7 +6,7 @@ This directory lists URLs for raw Markdown pages that complement the rendered pages on the documentation site. Use these Markdown files to retain semantic context when prompting models while avoiding passing HTML elements. ## Metadata -- Documentation pages: 269 +- Documentation pages: 270 - Categories: 13 ## Docs @@ -91,6 +91,7 @@ Docs: Smart Contracts - [Deploy an NFT to Polkadot Hub with Remix](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/smart-contracts-cookbook-smart-contracts-deploy-nft-remix.md): Learn how to deploy an ERC-721 NFT contract to Polkadot Hub using Remix, a browser-based IDE for quick prototyping and learning. - [Smart Contracts Cookbook Index](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/smart-contracts-cookbook.md): Explore our full collection of tutorials and guides to learn step-by-step how to build, deploy, and work with smart contracts on Polkadot. - [Use Hardhat with Polkadot Hub](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/smart-contracts-dev-environments-hardhat-get-started.md): Learn how to create, compile, test, and deploy smart contracts on Polkadot Hub using Hardhat, a powerful development environment for blockchain developers. +- [Troubleshooting Hardhat](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/smart-contracts-dev-environments-hardhat-troubleshooting-faq.md): Common issues related to developing, compiling, and deploying smart contracts using Hardhat on Polkadot Hub, paired with troubleshooting suggestions. - [Troubleshooting Hardhat on Polkadot Hub](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/smart-contracts-dev-environments-hardhat-troubleshooting.md): Solutions to common issues when developing, compiling, deploying, and testing smart contracts using Hardhat on Polkadot Hub. - [Local Development Node](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/smart-contracts-dev-environments-local-dev-node.md): Follow this step-by-step guide to install a Revive Dev node and ETH-RPC adapter for smart contract development in a local environment. - [Use the Polkadot Remix IDE](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/smart-contracts-dev-environments-remix-get-started.md): Explore the smart contract development and deployment process on Asset Hub using Remix IDE, a visual IDE for blockchain developers. @@ -245,6 +246,7 @@ Docs: Tooling - [Zero to Hero Smart Contract DApp](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/smart-contracts-cookbook-dapps-zero-to-hero.md): Learn how to build a decentralized application on Polkadot Hub using Viem and Next.js by creating a simple dApp that interacts with a smart contract. - [Deploying Uniswap V2 on Polkadot](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/smart-contracts-cookbook-eth-dapps-uniswap-v2.md): Learn how to deploy and test Uniswap V2 on Polkadot Hub using Hardhat, bringing AMM-based token swaps to the Polkadot ecosystem. - [Use Hardhat with Polkadot Hub](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/smart-contracts-dev-environments-hardhat-get-started.md): Learn how to create, compile, test, and deploy smart contracts on Polkadot Hub using Hardhat, a powerful development environment for blockchain developers. +- [Troubleshooting Hardhat](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/smart-contracts-dev-environments-hardhat-troubleshooting-faq.md): Common issues related to developing, compiling, and deploying smart contracts using Hardhat on Polkadot Hub, paired with troubleshooting suggestions. - [Troubleshooting Hardhat on Polkadot Hub](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/smart-contracts-dev-environments-hardhat-troubleshooting.md): Solutions to common issues when developing, compiling, deploying, and testing smart contracts using Hardhat on Polkadot Hub. - [Use the Polkadot Remix IDE](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/smart-contracts-dev-environments-remix-get-started.md): Explore the smart contract development and deployment process on Asset Hub using Remix IDE, a visual IDE for blockchain developers. - [Block Explorers](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/smart-contracts-explorers.md): Access PolkaVM explorers like Subscan, BlockScout, and Routescan to track transactions, analyze contracts, and view on-chain data from smart contracts.