diff --git a/.ai/categories/smart-contracts.md b/.ai/categories/smart-contracts.md
index 5412f63f8..99bdb153d 100644
--- a/.ai/categories/smart-contracts.md
+++ b/.ai/categories/smart-contracts.md
@@ -8967,6 +8967,1273 @@ 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
+
+-   <span class="badge external">External</span> __Hardhat Documentation__
+
+    ---
+
+    Explore official Hardhat documentation for advanced troubleshooting.
+
+    [:octicons-arrow-right-24: Visit Docs](https://hardhat.org/docs){target=\_blank}
+
+</div>
+
+
+---
+
+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:
+
+<div class="grid cards" markdown>
+
+-   <span class="badge guide">Guide</span> __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)
+
+-   <span class="badge guide">Guide</span> __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)
+
+-   <span class="badge guide">Guide</span> __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)
+
+-   <span class="badge external">External</span> __Hardhat Documentation__
+
+    ---
+
+    Explore official Hardhat documentation for advanced troubleshooting.
+
+    [:octicons-arrow-right-24: Visit Docs](https://hardhat.org/docs){target=\_blank}
+
+</div>
+
+
 ---
 
 Page Title: Use Hardhat with Polkadot Hub
diff --git a/.ai/categories/tooling.md b/.ai/categories/tooling.md
index 7b85f85c4..d7eb5d50d 100644
--- a/.ai/categories/tooling.md
+++ b/.ai/categories/tooling.md
@@ -10977,6 +10977,1273 @@ 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
+
+-   <span class="badge external">External</span> __Hardhat Documentation__
+
+    ---
+
+    Explore official Hardhat documentation for advanced troubleshooting.
+
+    [:octicons-arrow-right-24: Visit Docs](https://hardhat.org/docs){target=\_blank}
+
+</div>
+
+
+---
+
+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:
+
+<div class="grid cards" markdown>
+
+-   <span class="badge guide">Guide</span> __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)
+
+-   <span class="badge guide">Guide</span> __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)
+
+-   <span class="badge guide">Guide</span> __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)
+
+-   <span class="badge external">External</span> __Hardhat Documentation__
+
+    ---
+
+    Explore official Hardhat documentation for advanced troubleshooting.
+
+    [:octicons-arrow-right-24: Visit Docs](https://hardhat.org/docs){target=\_blank}
+
+</div>
+
+
 ---
 
 Page Title: Use Hardhat with 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
+
+-   <span class="badge external">External</span> __Hardhat Documentation__
+
+    ---
+
+    Explore official Hardhat documentation for advanced troubleshooting.
+
+    [:octicons-arrow-right-24: Visit Docs](https://hardhat.org/docs){target=\_blank}
+
+</div>
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:
+
+<div class="grid cards" markdown>
+
+-   <span class="badge guide">Guide</span> __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)
+
+-   <span class="badge guide">Guide</span> __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)
+
+-   <span class="badge guide">Guide</span> __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)
+
+-   <span class="badge external">External</span> __Hardhat Documentation__
+
+    ---
+
+    Explore official Hardhat documentation for advanced troubleshooting.
+
+    [:octicons-arrow-right-24: Visit Docs](https://hardhat.org/docs){target=\_blank}
+
+</div>
diff --git a/.ai/site-index.json b/.ai/site-index.json
index 6fe83e689..52fdbaa12 100644
--- a/.ai/site-index.json
+++ b/.ai/site-index.json
@@ -7406,24 +7406,353 @@
     "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": "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.txt b/llms.txt
index 6b479c954..d5173aadd 100644
--- a/llms.txt
+++ b/llms.txt
@@ -61,7 +61,9 @@ Docs: Smart Contracts
 - [Deploy an NFT to Polkadot Hub with Hardhat](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/smart-contracts-cookbook-smart-contracts-deploy-nft-hardhat.md): Learn how to deploy an ERC-721 NFT contract to Polkadot Hub with Hardhat, a comprehenive development environment with built-in deployment capabilities.
 - [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): Overview of Hardhat, a powerful development environment for creating, compiling, testing, and deploying smart contracts on Polkadot Hub.
+- [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.
 - [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.
@@ -179,7 +181,9 @@ Docs: Tooling
 - [XCM Tools](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/reference-tools-xcm-tools.md): Explore essential XCM tools across Polkadot, crafted to enhance cross-chain functionality and integration within the ecosystem.
 - [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): Overview of Hardhat, a powerful development environment for creating, compiling, testing, and deploying smart contracts on Polkadot Hub.
+- [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.
 - [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.
@@ -237,7 +241,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.
diff --git a/smart-contracts/dev-environments/hardhat/.nav.yml b/smart-contracts/dev-environments/hardhat/.nav.yml
index d47646582..b3326ea47 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
+ - '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..c026a0d43
--- /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 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
+
+-   <span class="badge external">External</span> __Hardhat Documentation__
+
+    ---
+
+    Explore official Hardhat documentation for advanced troubleshooting.
+
+    [:octicons-arrow-right-24: Visit Docs](https://hardhat.org/docs){target=\_blank}
+
+</div>
\ 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 30404ce4c..000000000
--- a/smart-contracts/dev-environments/hardhat/troubleshooting.md
+++ /dev/null
@@ -1 +0,0 @@
-TODO
\ No newline at end of file
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