create-fhevm-example 1.3.1 → 1.4.0

package/fhevm-hardhat-template/package.json

@@ -0,0 +1,104 @@
+{
+  "name": "fhevm-hardhat-template",
+  "description": "Hardhat-based template for developing FHEVM Solidity smart contracts",
+  "version": "0.3.0-3",
+  "engines": {
+    "node": ">=20",
+    "npm": ">=7.0.0"
+  },
+  "license": "BSD-3-Clause-Clear",
+  "homepage": "https://github.com/zama-ai/fhevm-hardhat-template/README.md",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zama-ai/fhevm-hardhat-template.git"
+  },
+  "keywords": [
+    "fhevm",
+    "zama",
+    "eth",
+    "ethereum",
+    "dapps",
+    "wallet",
+    "web3",
+    "typescript",
+    "hardhat"
+  ],
+  "dependencies": {
+    "encrypted-types": "^0.0.4",
+    "@fhevm/solidity": "^0.9.1"
+  },
+  "devDependencies": {
+    "@fhevm/hardhat-plugin": "^0.3.0-3",
+    "@nomicfoundation/hardhat-chai-matchers": "^2.1.0",
+    "@nomicfoundation/hardhat-ethers": "^3.1.0",
+    "@nomicfoundation/hardhat-network-helpers": "^1.1.0",
+    "@nomicfoundation/hardhat-verify": "^2.1.0",
+    "@typechain/ethers-v6": "^0.5.1",
+    "@typechain/hardhat": "^9.1.0",
+    "@types/chai": "^4.3.20",
+    "@types/mocha": "^10.0.10",
+    "@types/node": "^20.19.8",
+    "@typescript-eslint/eslint-plugin": "^8.37.0",
+    "@typescript-eslint/parser": "^8.37.0",
+    "@zama-fhe/relayer-sdk": "^0.3.0-6",
+    "chai": "^4.5.0",
+    "chai-as-promised": "^8.0.1",
+    "cross-env": "^7.0.3",
+    "eslint": "^8.57.1",
+    "eslint-config-prettier": "^9.1.0",
+    "ethers": "^6.15.0",
+    "hardhat": "^2.26.0",
+    "hardhat-deploy": "^0.11.45",
+    "hardhat-gas-reporter": "^2.3.0",
+    "mocha": "^11.7.1",
+    "prettier": "^3.6.2",
+    "prettier-plugin-solidity": "^2.1.0",
+    "rimraf": "^6.0.1",
+    "solhint": "^6.0.0",
+    "solidity-coverage": "^0.8.16",
+    "ts-generator": "^0.1.1",
+    "ts-node": "^10.9.2",
+    "typechain": "^8.3.2",
+    "typescript": "^5.8.3"
+  },
+  "files": [
+    "contracts"
+  ],
+  "scripts": {
+    "clean": "rimraf ./fhevmTemp ./artifacts ./cache ./coverage ./types ./coverage.json ./dist && npm run typechain",
+    "compile": "cross-env TS_NODE_TRANSPILE_ONLY=true hardhat compile",
+    "coverage": "cross-env SOLIDITY_COVERAGE=true hardhat coverage --solcoverjs ./.solcover.js --temp artifacts --testfiles \"test/**/*.ts\" && npm run typechain",
+    "lint": "npm run lint:sol && npm run lint:ts && npm run prettier:check",
+    "lint:sol": "solhint --max-warnings 0 \"contracts/**/*.sol\"",
+    "lint:ts": "eslint --ignore-path ./.eslintignore --ext .js,.ts .",
+    "postcompile": "npm run typechain",
+    "prettier:check": "prettier --check \"**/*.{js,json,md,sol,ts,yml}\"",
+    "prettier:write": "prettier --write \"**/*.{js,json,md,sol,ts,yml}\"",
+    "test": "hardhat test",
+    "test:sepolia": "hardhat test --network sepolia",
+    "build:ts": "tsc --project tsconfig.json",
+    "typechain": "cross-env TS_NODE_TRANSPILE_ONLY=true hardhat typechain",
+    "chain": "hardhat node --network hardhat --no-deploy",
+    "deploy:localhost": "hardhat deploy --network localhost",
+    "deploy:sepolia": "hardhat deploy --network sepolia",
+    "verify:sepolia": "hardhat verify --network sepolia"
+  },
+  "overrides": {
+    "ws@>=7.0.0 <7.5.10": ">=7.5.10",
+    "axios@>=1.3.2 <=1.7.3": ">=1.7.4",
+    "elliptic@>=4.0.0 <=6.5.6": ">=6.5.7",
+    "elliptic@>=2.0.0 <=6.5.6": ">=6.5.7",
+    "elliptic@>=5.2.1 <=6.5.6": ">=6.5.7",
+    "micromatch@<4.0.8": ">=4.0.8",
+    "elliptic@<6.6.0": ">=6.6.0",
+    "elliptic@<6.5.6": ">=6.5.6",
+    "undici@>=6.0.0 <6.21.1": ">=6.21.1 <7.0.0",
+    "undici@>=4.5.0 <5.28.5": ">=5.28.5 <6.0.0",
+    "elliptic@<=6.6.0": ">=6.6.1",
+    "tar-fs@>=2.0.0 <2.1.2": ">=2.1.2",
+    "axios@>=1.0.0 <1.8.2": ">=1.8.2",
+    "axios@<0.29.1": ">=0.29.1",
+    "cookie@<0.7.0": ">=0.7.0",
+    "minimatch": "^3.1.2"
+  }
+}

package/fhevm-hardhat-template/tasks/FHECounter.ts

@@ -0,0 +1,184 @@
+import { FhevmType } from "@fhevm/hardhat-plugin";
+import { task } from "hardhat/config";
+import type { TaskArguments } from "hardhat/types";
+
+/**
+ * Tutorial: Deploy and Interact Locally (--network localhost)
+ * ===========================================================
+ *
+ * 1. From a separate terminal window:
+ *
+ *   npx hardhat node
+ *
+ * 2. Deploy the FHECounter contract
+ *
+ *   npx hardhat --network localhost deploy
+ *
+ * 3. Interact with the FHECounter contract
+ *
+ *   npx hardhat --network localhost task:decrypt-count
+ *   npx hardhat --network localhost task:increment --value 2
+ *   npx hardhat --network localhost task:decrement --value 1
+ *   npx hardhat --network localhost task:decrypt-count
+ *
+ *
+ * Tutorial: Deploy and Interact on Sepolia (--network sepolia)
+ * ===========================================================
+ *
+ * 1. Deploy the FHECounter contract
+ *
+ *   npx hardhat --network sepolia deploy
+ *
+ * 2. Interact with the FHECounter contract
+ *
+ *   npx hardhat --network sepolia task:decrypt-count
+ *   npx hardhat --network sepolia task:increment --value 2
+ *   npx hardhat --network sepolia task:decrement --value 1
+ *   npx hardhat --network sepolia task:decrypt-count
+ *
+ */
+
+/**
+ * Example:
+ *   - npx hardhat --network localhost task:address
+ *   - npx hardhat --network sepolia task:address
+ */
+task("task:address", "Prints the FHECounter address").setAction(async function (_taskArguments: TaskArguments, hre) {
+  const { deployments } = hre;
+
+  const fheCounter = await deployments.get("FHECounter");
+
+  console.log("FHECounter address is " + fheCounter.address);
+});
+
+/**
+ * Example:
+ *   - npx hardhat --network localhost task:decrypt-count
+ *   - npx hardhat --network sepolia task:decrypt-count
+ */
+task("task:decrypt-count", "Calls the getCount() function of Counter Contract")
+  .addOptionalParam("address", "Optionally specify the Counter contract address")
+  .setAction(async function (taskArguments: TaskArguments, hre) {
+    const { ethers, deployments, fhevm } = hre;
+
+    await fhevm.initializeCLIApi();
+
+    const FHECounterDeployement = taskArguments.address
+      ? { address: taskArguments.address }
+      : await deployments.get("FHECounter");
+    console.log(`FHECounter: ${FHECounterDeployement.address}`);
+
+    const signers = await ethers.getSigners();
+
+    const fheCounterContract = await ethers.getContractAt("FHECounter", FHECounterDeployement.address);
+
+    const encryptedCount = await fheCounterContract.getCount();
+    if (encryptedCount === ethers.ZeroHash) {
+      console.log(`encrypted count: ${encryptedCount}`);
+      console.log("clear count    : 0");
+      return;
+    }
+
+    const clearCount = await fhevm.userDecryptEuint(
+      FhevmType.euint32,
+      encryptedCount,
+      FHECounterDeployement.address,
+      signers[0],
+    );
+    console.log(`Encrypted count: ${encryptedCount}`);
+    console.log(`Clear count    : ${clearCount}`);
+  });
+
+/**
+ * Example:
+ *   - npx hardhat --network localhost task:increment --value 1
+ *   - npx hardhat --network sepolia task:increment --value 1
+ */
+task("task:increment", "Calls the increment() function of FHECounter Contract")
+  .addOptionalParam("address", "Optionally specify the FHECounter contract address")
+  .addParam("value", "The increment value")
+  .setAction(async function (taskArguments: TaskArguments, hre) {
+    const { ethers, deployments, fhevm } = hre;
+
+    const value = parseInt(taskArguments.value);
+    if (!Number.isInteger(value)) {
+      throw new Error(`Argument --value is not an integer`);
+    }
+
+    await fhevm.initializeCLIApi();
+
+    const FHECounterDeployement = taskArguments.address
+      ? { address: taskArguments.address }
+      : await deployments.get("FHECounter");
+    console.log(`FHECounter: ${FHECounterDeployement.address}`);
+
+    const signers = await ethers.getSigners();
+
+    const fheCounterContract = await ethers.getContractAt("FHECounter", FHECounterDeployement.address);
+
+    // Encrypt the value passed as argument
+    const encryptedValue = await fhevm
+      .createEncryptedInput(FHECounterDeployement.address, signers[0].address)
+      .add32(value)
+      .encrypt();
+
+    const tx = await fheCounterContract
+      .connect(signers[0])
+      .increment(encryptedValue.handles[0], encryptedValue.inputProof);
+    console.log(`Wait for tx:${tx.hash}...`);
+
+    const receipt = await tx.wait();
+    console.log(`tx:${tx.hash} status=${receipt?.status}`);
+
+    const newEncryptedCount = await fheCounterContract.getCount();
+    console.log("Encrypted count after increment:", newEncryptedCount);
+
+    console.log(`FHECounter increment(${value}) succeeded!`);
+  });
+
+/**
+ * Example:
+ *   - npx hardhat --network localhost task:decrement --value 1
+ *   - npx hardhat --network sepolia task:decrement --value 1
+ */
+task("task:decrement", "Calls the decrement() function of FHECounter Contract")
+  .addOptionalParam("address", "Optionally specify the FHECounter contract address")
+  .addParam("value", "The decrement value")
+  .setAction(async function (taskArguments: TaskArguments, hre) {
+    const { ethers, deployments, fhevm } = hre;
+
+    const value = parseInt(taskArguments.value);
+    if (!Number.isInteger(value)) {
+      throw new Error(`Argument --value is not an integer`);
+    }
+
+    await fhevm.initializeCLIApi();
+
+    const FHECounterDeployement = taskArguments.address
+      ? { address: taskArguments.address }
+      : await deployments.get("FHECounter");
+    console.log(`FHECounter: ${FHECounterDeployement.address}`);
+
+    const signers = await ethers.getSigners();
+
+    const fheCounterContract = await ethers.getContractAt("FHECounter", FHECounterDeployement.address);
+
+    // Encrypt the value passed as argument
+    const encryptedValue = await fhevm
+      .createEncryptedInput(FHECounterDeployement.address, signers[0].address)
+      .add32(value)
+      .encrypt();
+
+    const tx = await fheCounterContract
+      .connect(signers[0])
+      .decrement(encryptedValue.handles[0], encryptedValue.inputProof);
+    console.log(`Wait for tx:${tx.hash}...`);
+
+    const receipt = await tx.wait();
+    console.log(`tx:${tx.hash} status=${receipt?.status}`);
+
+    const newEncryptedCount = await fheCounterContract.getCount();
+    console.log("Encrypted count after decrement:", newEncryptedCount);
+
+    console.log(`FHECounter decrement(${value}) succeeded!`);
+  });

package/fhevm-hardhat-template/tasks/accounts.ts

@@ -0,0 +1,9 @@
+import { task } from "hardhat/config";
+
+task("accounts", "Prints the list of accounts", async (_taskArgs, hre) => {
+  const accounts = await hre.ethers.getSigners();
+
+  for (const account of accounts) {
+    console.log(`${account.address}`);
+  }
+});

package/fhevm-hardhat-template/test/FHECounter.ts

@@ -0,0 +1,104 @@
+import { HardhatEthersSigner } from "@nomicfoundation/hardhat-ethers/signers";
+import { ethers, fhevm } from "hardhat";
+import { FHECounter, FHECounter__factory } from "../types";
+import { expect } from "chai";
+import { FhevmType } from "@fhevm/hardhat-plugin";
+
+type Signers = {
+  deployer: HardhatEthersSigner;
+  alice: HardhatEthersSigner;
+  bob: HardhatEthersSigner;
+};
+
+async function deployFixture() {
+  const factory = (await ethers.getContractFactory("FHECounter")) as FHECounter__factory;
+  const fheCounterContract = (await factory.deploy()) as FHECounter;
+  const fheCounterContractAddress = await fheCounterContract.getAddress();
+
+  return { fheCounterContract, fheCounterContractAddress };
+}
+
+describe("FHECounter", function () {
+  let signers: Signers;
+  let fheCounterContract: FHECounter;
+  let fheCounterContractAddress: string;
+
+  before(async function () {
+    const ethSigners: HardhatEthersSigner[] = await ethers.getSigners();
+    signers = { deployer: ethSigners[0], alice: ethSigners[1], bob: ethSigners[2] };
+  });
+
+  beforeEach(async function () {
+    // Check whether the tests are running against an FHEVM mock environment
+    if (!fhevm.isMock) {
+      console.warn(`This hardhat test suite cannot run on Sepolia Testnet`);
+      this.skip();
+    }
+
+    ({ fheCounterContract, fheCounterContractAddress } = await deployFixture());
+  });
+
+  it("encrypted count should be uninitialized after deployment", async function () {
+    const encryptedCount = await fheCounterContract.getCount();
+    // Expect initial count to be bytes32(0) after deployment,
+    // (meaning the encrypted count value is uninitialized)
+    expect(encryptedCount).to.eq(ethers.ZeroHash);
+  });
+
+  it("increment the counter by 1", async function () {
+    const encryptedCountBeforeInc = await fheCounterContract.getCount();
+    expect(encryptedCountBeforeInc).to.eq(ethers.ZeroHash);
+    const clearCountBeforeInc = 0;
+
+    // Encrypt constant 1 as a euint32
+    const clearOne = 1;
+    const encryptedOne = await fhevm
+      .createEncryptedInput(fheCounterContractAddress, signers.alice.address)
+      .add32(clearOne)
+      .encrypt();
+
+    const tx = await fheCounterContract
+      .connect(signers.alice)
+      .increment(encryptedOne.handles[0], encryptedOne.inputProof);
+    await tx.wait();
+
+    const encryptedCountAfterInc = await fheCounterContract.getCount();
+    const clearCountAfterInc = await fhevm.userDecryptEuint(
+      FhevmType.euint32,
+      encryptedCountAfterInc,
+      fheCounterContractAddress,
+      signers.alice,
+    );
+
+    expect(clearCountAfterInc).to.eq(clearCountBeforeInc + clearOne);
+  });
+
+  it("decrement the counter by 1", async function () {
+    // Encrypt constant 1 as a euint32
+    const clearOne = 1;
+    const encryptedOne = await fhevm
+      .createEncryptedInput(fheCounterContractAddress, signers.alice.address)
+      .add32(clearOne)
+      .encrypt();
+
+    // First increment by 1, count becomes 1
+    let tx = await fheCounterContract
+      .connect(signers.alice)
+      .increment(encryptedOne.handles[0], encryptedOne.inputProof);
+    await tx.wait();
+
+    // Then decrement by 1, count goes back to 0
+    tx = await fheCounterContract.connect(signers.alice).decrement(encryptedOne.handles[0], encryptedOne.inputProof);
+    await tx.wait();
+
+    const encryptedCountAfterDec = await fheCounterContract.getCount();
+    const clearCountAfterInc = await fhevm.userDecryptEuint(
+      FhevmType.euint32,
+      encryptedCountAfterDec,
+      fheCounterContractAddress,
+      signers.alice,
+    );
+
+    expect(clearCountAfterInc).to.eq(0);
+  });
+});

package/fhevm-hardhat-template/test/FHECounterSepolia.ts

@@ -0,0 +1,104 @@
+import { HardhatEthersSigner } from "@nomicfoundation/hardhat-ethers/signers";
+import { ethers, fhevm, deployments } from "hardhat";
+import { FHECounter } from "../types";
+import { expect } from "chai";
+import { FhevmType } from "@fhevm/hardhat-plugin";
+
+type Signers = {
+  alice: HardhatEthersSigner;
+};
+
+describe("FHECounterSepolia", function () {
+  let signers: Signers;
+  let fheCounterContract: FHECounter;
+  let fheCounterContractAddress: string;
+  let step: number;
+  let steps: number;
+
+  function progress(message: string) {
+    console.log(`${++step}/${steps} ${message}`);
+  }
+
+  before(async function () {
+    if (fhevm.isMock) {
+      console.warn(`This hardhat test suite can only run on Sepolia Testnet`);
+      this.skip();
+    }
+
+    try {
+      const FHECounterDeployement = await deployments.get("FHECounter");
+      fheCounterContractAddress = FHECounterDeployement.address;
+      fheCounterContract = await ethers.getContractAt("FHECounter", FHECounterDeployement.address);
+    } catch (e) {
+      (e as Error).message += ". Call 'npx hardhat deploy --network sepolia'";
+      throw e;
+    }
+
+    const ethSigners: HardhatEthersSigner[] = await ethers.getSigners();
+    signers = { alice: ethSigners[0] };
+  });
+
+  beforeEach(async () => {
+    step = 0;
+    steps = 0;
+  });
+
+  it("increment the counter by 1", async function () {
+    steps = 10;
+
+    this.timeout(4 * 40000);
+
+    progress("Encrypting '0'...");
+    const encryptedZero = await fhevm
+      .createEncryptedInput(fheCounterContractAddress, signers.alice.address)
+      .add32(0)
+      .encrypt();
+
+    progress(
+      `Call increment(0) FHECounter=${fheCounterContractAddress} handle=${ethers.hexlify(encryptedZero.handles[0])} signer=${signers.alice.address}...`,
+    );
+    let tx = await fheCounterContract
+      .connect(signers.alice)
+      .increment(encryptedZero.handles[0], encryptedZero.inputProof);
+    await tx.wait();
+
+    progress(`Call FHECounter.getCount()...`);
+    const encryptedCountBeforeInc = await fheCounterContract.getCount();
+    expect(encryptedCountBeforeInc).to.not.eq(ethers.ZeroHash);
+
+    progress(`Decrypting FHECounter.getCount()=${encryptedCountBeforeInc}...`);
+    const clearCountBeforeInc = await fhevm.userDecryptEuint(
+      FhevmType.euint32,
+      encryptedCountBeforeInc,
+      fheCounterContractAddress,
+      signers.alice,
+    );
+    progress(`Clear FHECounter.getCount()=${clearCountBeforeInc}`);
+
+    progress(`Encrypting '1'...`);
+    const encryptedOne = await fhevm
+      .createEncryptedInput(fheCounterContractAddress, signers.alice.address)
+      .add32(1)
+      .encrypt();
+
+    progress(
+      `Call increment(1) FHECounter=${fheCounterContractAddress} handle=${ethers.hexlify(encryptedOne.handles[0])} signer=${signers.alice.address}...`,
+    );
+    tx = await fheCounterContract.connect(signers.alice).increment(encryptedOne.handles[0], encryptedOne.inputProof);
+    await tx.wait();
+
+    progress(`Call FHECounter.getCount()...`);
+    const encryptedCountAfterInc = await fheCounterContract.getCount();
+
+    progress(`Decrypting FHECounter.getCount()=${encryptedCountAfterInc}...`);
+    const clearCountAfterInc = await fhevm.userDecryptEuint(
+      FhevmType.euint32,
+      encryptedCountAfterInc,
+      fheCounterContractAddress,
+      signers.alice,
+    );
+    progress(`Clear FHECounter.getCount()=${clearCountAfterInc}`);
+
+    expect(clearCountAfterInc - clearCountBeforeInc).to.eq(1);
+  });
+});

package/fhevm-hardhat-template/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "declaration": true,
+    "declarationMap": true,
+    "outDir": "dist",
+    "emitDecoratorMetadata": true,
+    "esModuleInterop": true,
+    "experimentalDecorators": true,
+    "forceConsistentCasingInFileNames": true,
+    "lib": ["es2022"], // get error cause (ErrorOptions)
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "noImplicitAny": true,
+    "removeComments": true,
+    "resolveJsonModule": true,
+    "sourceMap": true,
+    "strict": true,
+    "target": "es2022" // get error cause (ErrorOptions)
+  },
+  "exclude": ["node_modules"],
+  "files": ["./hardhat.config.ts"],
+  "include": ["src/**/*", "tasks/**/*", "test/**/*", "deploy/**/*", "types/"]
+}

package/package.json

@@ -1,28 +1,31 @@
 {
   "name": "create-fhevm-example",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "Create FHEVM example projects with a single command - A comprehensive toolkit for building privacy-preserving smart contracts",
   "bin": {
     "create-fhevm-example": "./dist/scripts/index.js"
   },
   "main": "./dist/scripts/index.js",
   "files": [
-    "dist"
+    "dist",
+    "contracts",
+    "test",
+    "fhevm-hardhat-template"
   ],
   "scripts": {
     "build": "tsc",
     "create": "LOCAL_DEV=1 npx ts-node scripts/index.ts",
     "create:example": "npx ts-node scripts/index.ts --example",
     "create:category": "npx ts-node scripts/index.ts --category",
-    "create:docs": "npx ts-node scripts/generate-docs.ts",
-    "test:all": "npx ts-node scripts/maintenance.ts test-all",
-    "generate:config": "npx ts-node scripts/generate-config.ts",
-    "doctor": "npx ts-node scripts/doctor.ts",
-    "help:create": "npx ts-node scripts/index.ts --help",
-    "help:docs": "npx ts-node scripts/generate-docs.ts --help",
-    "help:test": "npx ts-node scripts/maintenance.ts test-all --help",
+    "create:docs": "npx ts-node scripts/commands/generate-docs.ts",
+    "test:all": "npx ts-node scripts/commands/maintenance.ts test-all",
+    "generate:config": "npx ts-node scripts/commands/generate-config.ts",
+    "doctor": "npx ts-node scripts/commands/doctor.ts",
+    "help:create": "LOCAL_DEV=1 npx ts-node scripts/index.ts --help",
+    "help:docs": "npx ts-node scripts/commands/generate-docs.ts --help",
+    "help:test": "npx ts-node scripts/commands/maintenance.ts test-all --help",
 
-    "postinstall": "git submodule update --init --recursive",
+    "prepare": "git submodule update --init --recursive || true",
     "prepublishOnly": "npm run build",
     "prepack": "mv README.md GITHUB_README.md && cp NPM_README.md README.md",
     "postpack": "mv GITHUB_README.md README.md"