Quai Hardhat Integration

Quai Network is a hierarchy of EVM-compatible chains secured by a single pool of proof-of-work. Transactions execute on zone chains like Cyprus-1, which run an EVM derived from go-ethereum — so contracts written for Ethereum compile and run on Quai without modification. Hardhat handles compilation, local testing, and deployment scripting exactly as it does on any EVM chain.

Two things differ from Ethereum. First, Quai nodes expose a quai_ JSON-RPC namespace instead of eth_, so deployment scripts use the quais SDK — a maintained fork of Ethers v6 with a near-identical API — rather than stock Ethers. Second, Quai's address space is sharded: an address prefix determines which zone it lives on, and contract deployment automatically grinds addresses to land in your target zone (CREATE handles this for you; CREATE2 salts must resolve to a valid zone address).

The dominant-strategies/hardhat-example repository wires all of this together — network config, environment handling, and quais-based deploy scripts for both vanilla Solidity and cross-chain SolidityX projects.

The fastest path is the maintained example repo. The steps below show what it configures, so you can also adapt an existing Hardhat project.

1. 1

   Clone the example and install

   The repo contains a Solidity/ project for standard contracts and a SolidityX/ project for cross-chain contracts.

   git clone https://github.com/dominant-strategies/hardhat-example.git
   cd hardhat-example/Solidity
   npm install

2. 2

   Configure your environment

   Set the RPC endpoint, chain ID, and a deployer private key in the shared .env file. Use chain ID 9 for mainnet or 15000 for the Orchard testnet — testnet QUAI is free from the faucet at orchard.faucet.quai.network.

   RPC_URL="https://rpc.quai.network"
   CHAIN_ID="9"
   CYPRUS1_PK="0x..." # deployer key for the Cyprus-1 zone

3. 3

   Point hardhat.config.js at a zone

   Each Quai zone is configured as a Hardhat network. Cyprus-1 is the primary zone live on mainnet today; the hierarchy is built to expand to nine zones across the Cyprus, Paxos, and Hydra regions.

   require("@nomicfoundation/hardhat-toolbox");
   require("@quai/hardhat-deploy-metadata");
   const dotenv = require("dotenv");
   dotenv.config({ path: "../.env" });
   
   module.exports = {
     defaultNetwork: "cyprus1",
     networks: {
       cyprus1: {
         url: process.env.RPC_URL,
         accounts: [process.env.CYPRUS1_PK],
         chainId: Number(process.env.CHAIN_ID),
       },
     },
     solidity: {
       version: "0.8.20",
       settings: {
         optimizer: { enabled: true, runs: 1000 },
       },
     },
   };

4. 4

   Deploy with a quais script

   Deploy scripts construct a provider and wallet from your Hardhat network config using quais instead of Ethers — the API is nearly identical.

   npx hardhat run scripts/deployERC20.js --network cyprus1

5. 5

   Verify on Quaiscan

   The @quai/hardhat-deploy-metadata plugin pushes contract metadata to IPFS at deploy time, which Quaiscan uses for source verification at quaiscan.io/contract-verification.

• Token launches

  ERC-20 and ERC-721 contracts deploy unchanged. The example repo ships both as ready-to-deploy templates with quais deployment scripts.

• Protocol testing

  Run your unit and integration suites against the in-process Hardhat network before deploying — standard EVM semantics mean tests behave the same.

• Cross-chain contracts with SolidityX

  The quai-hardhat-plugin adds the SolidityX compiler, enabling QRC-20X and QRC-721X contracts that move trustlessly between zones.

• CI/CD pipelines

  Hardhat tasks script cleanly into CI: compile and test on every commit, deploy to Orchard testnet on merge, promote to mainnet on release.

A complete Hardhat deploy script using the quais SDK. If you've written an Ethers v6 deploy script, this is the same shape — provider, wallet, contract factory.

const quais = require("quais");
const ERC20 = require("../artifacts/contracts/ERC20.sol/ERC20.json");

async function main() {
  // Provider + wallet from the Hardhat network config
  const provider = new quais.JsonRpcProvider(hre.network.config.url, undefined, {
    usePathing: true,
  });
  const wallet = new quais.Wallet(hre.network.config.accounts[0], provider);

  // Deploy exactly as you would with Ethers v6
  const factory = new quais.ContractFactory(ERC20.abi, ERC20.bytecode, wallet);
  const token = await factory.deploy("MyToken", "MTK", quais.parseQuai("1000000"));

  await token.waitForDeployment();
  console.log("ERC-20 deployed to:", await token.getAddress());
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});