create-fhevm-example 1.4.5 → 1.4.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-fhevm-example",
-  "version": "1.4.5",
+  "version": "1.4.7",
   "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"

package/test/concepts/antipatterns/ControlFlow.ts

@@ -0,0 +1,125 @@
+import {
+  FhevmType,
+  HardhatFhevmRuntimeEnvironment,
+} from "@fhevm/hardhat-plugin";
+import { HardhatEthersSigner } from "@nomicfoundation/hardhat-ethers/signers";
+import { expect } from "chai";
+import { ethers } from "hardhat";
+import * as hre from "hardhat";
+
+import {
+  FHEControlFlowAntiPatterns,
+  FHEControlFlowAntiPatterns__factory,
+} from "../types";
+import type { Signers } from "./types";
+
+async function deployFixture() {
+  const factory = (await ethers.getContractFactory(
+    "FHEControlFlowAntiPatterns"
+  )) as FHEControlFlowAntiPatterns__factory;
+  const contract = (await factory.deploy()) as FHEControlFlowAntiPatterns;
+  const contractAddress = await contract.getAddress();
+  return { contract, contractAddress };
+}
+
+/**
+ * @notice Tests for FHE control flow anti-patterns
+ * Demonstrates wrong and correct patterns for conditional logic and loops
+ */
+describe("FHEControlFlowAntiPatterns", function () {
+  let contract: FHEControlFlowAntiPatterns;
+  let contractAddress: string;
+  let signers: Signers;
+
+  before(async function () {
+    if (!hre.fhevm.isMock) {
+      throw new Error(`This hardhat test suite cannot run on Sepolia Testnet`);
+    }
+    const ethSigners: HardhatEthersSigner[] = await ethers.getSigners();
+    signers = { owner: ethSigners[0], alice: ethSigners[1] };
+  });
+
+  beforeEach(async function () {
+    const deployment = await deployFixture();
+    contractAddress = deployment.contractAddress;
+    contract = deployment.contract;
+
+    // Initialize contract with test values
+    const fhevm: HardhatFhevmRuntimeEnvironment = hre.fhevm;
+
+    // Create encrypted input for balance only (threshold is fixed at 100)
+    const input = await fhevm
+      .createEncryptedInput(contractAddress, signers.alice.address)
+      .add32(50) // balance
+      .encrypt();
+
+    await contract
+      .connect(signers.alice)
+      .initialize(input.handles[0], input.inputProof);
+  });
+
+  describe("Pattern 1: If/Else Branching", function () {
+    it("should execute correctConditional without leaking information", async function () {
+      const fhevm: HardhatFhevmRuntimeEnvironment = hre.fhevm;
+
+      await contract.connect(signers.alice).correctConditional();
+
+      const encrypted = await contract.getBalance();
+      const decrypted = await fhevm.userDecryptEuint(
+        FhevmType.euint32,
+        encrypted,
+        contractAddress,
+        signers.alice
+      );
+
+      // Balance (50) is not above threshold (100), so no penalty applied
+      expect(decrypted).to.equal(50);
+    });
+
+    it("wrongBranching should return placeholder value", async function () {
+      const result = await contract.wrongBranching.staticCall();
+      expect(result).to.equal(0);
+    });
+  });
+
+  describe("Pattern 2: Require/Revert", function () {
+    it("should return encrypted boolean for validation", async function () {
+      const fhevm: HardhatFhevmRuntimeEnvironment = hre.fhevm;
+
+      // Execute validation (stores result)
+      await contract.connect(signers.alice).correctValidation();
+
+      // Get result via getter
+      const encrypted = await contract.getValidationResult();
+      const decrypted = await fhevm.userDecryptEbool(
+        encrypted,
+        contractAddress,
+        signers.alice
+      );
+
+      // Balance (50) < 100, so should be false
+      expect(decrypted).to.equal(false);
+    });
+
+    it("wrongRequire should return explanation string", async function () {
+      const result = await contract.wrongRequire();
+      expect(result).to.include("doesn't work with encrypted values");
+    });
+  });
+
+  describe("Pattern 3: Encrypted Loop Iterations", function () {
+    it("should use fixed iterations with FHE.select", async function () {
+      const fhevm: HardhatFhevmRuntimeEnvironment = hre.fhevm;
+
+      await contract.connect(signers.alice).correctFixedIterations();
+
+      // Result should count up to min(balance, MAX_ITERATIONS)
+      // Balance is 50, MAX_ITERATIONS is 5, so result should be 5
+    });
+
+    it("wrongEncryptedLoop should return explanation string", async function () {
+      const result = await contract.wrongEncryptedLoop();
+      expect(result).to.include("Loop iterations leak");
+    });
+  });
+});

package/test/concepts/antipatterns/OperationsGasNoise.ts

@@ -0,0 +1,187 @@
+import {
+  FhevmType,
+  HardhatFhevmRuntimeEnvironment,
+} from "@fhevm/hardhat-plugin";
+import { HardhatEthersSigner } from "@nomicfoundation/hardhat-ethers/signers";
+import { expect } from "chai";
+import { ethers } from "hardhat";
+import * as hre from "hardhat";
+
+import {
+  FHEOperationsGasNoiseAntiPatterns,
+  FHEOperationsGasNoiseAntiPatterns__factory,
+} from "../types";
+import type { Signers } from "./types";
+
+async function deployFixture() {
+  const factory = (await ethers.getContractFactory(
+    "FHEOperationsGasNoiseAntiPatterns"
+  )) as FHEOperationsGasNoiseAntiPatterns__factory;
+  const contract =
+    (await factory.deploy()) as FHEOperationsGasNoiseAntiPatterns;
+  const contractAddress = await contract.getAddress();
+  return { contract, contractAddress };
+}
+
+/**
+ * @notice Tests for FHE operations, gas, and noise anti-patterns
+ * Demonstrates performance issues and optimization techniques
+ */
+describe("FHEOperationsGasNoiseAntiPatterns", function () {
+  let contract: FHEOperationsGasNoiseAntiPatterns;
+  let contractAddress: string;
+  let signers: Signers;
+
+  before(async function () {
+    if (!hre.fhevm.isMock) {
+      throw new Error(`This hardhat test suite cannot run on Sepolia Testnet`);
+    }
+    const ethSigners: HardhatEthersSigner[] = await ethers.getSigners();
+    signers = { owner: ethSigners[0], alice: ethSigners[1] };
+  });
+
+  beforeEach(async function () {
+    const deployment = await deployFixture();
+    contractAddress = deployment.contractAddress;
+    contract = deployment.contract;
+  });
+
+  describe("Pattern 1: Gas/Timing Side Channel", function () {
+    const testValue = 50;
+
+    it("wrongGasLeak should store value", async function () {
+      const fhevm: HardhatFhevmRuntimeEnvironment = hre.fhevm;
+
+      const input = await fhevm
+        .createEncryptedInput(contractAddress, signers.alice.address)
+        .add32(testValue)
+        .encrypt();
+
+      await contract
+        .connect(signers.alice)
+        .wrongGasLeak(input.handles[0], input.inputProof);
+
+      // Value should be stored (but without permission to decrypt)
+    });
+
+    it("correctConstantTime should use constant gas", async function () {
+      const fhevm: HardhatFhevmRuntimeEnvironment = hre.fhevm;
+
+      const input = await fhevm
+        .createEncryptedInput(contractAddress, signers.alice.address)
+        .add32(testValue)
+        .encrypt();
+
+      await contract
+        .connect(signers.alice)
+        .correctConstantTime(input.handles[0], input.inputProof);
+
+      const encrypted = await contract.getValue();
+      const decrypted = await fhevm.userDecryptEuint(
+        FhevmType.euint32,
+        encrypted,
+        contractAddress,
+        signers.alice
+      );
+
+      expect(decrypted).to.equal(testValue * 2);
+    });
+  });
+
+  describe("Pattern 2: Noise Accumulation", function () {
+    const testValue = 2;
+
+    it("wrongNoiseAccumulation should chain many operations", async function () {
+      const fhevm: HardhatFhevmRuntimeEnvironment = hre.fhevm;
+
+      const input = await fhevm
+        .createEncryptedInput(contractAddress, signers.alice.address)
+        .add32(testValue)
+        .encrypt();
+
+      await contract
+        .connect(signers.alice)
+        .wrongNoiseAccumulation(input.handles[0], input.inputProof);
+
+      // Result stored but may have accumulated noise
+    });
+
+    it("correctMinimizeOperations should use single operation", async function () {
+      const fhevm: HardhatFhevmRuntimeEnvironment = hre.fhevm;
+
+      const input = await fhevm
+        .createEncryptedInput(contractAddress, signers.alice.address)
+        .add32(testValue)
+        .encrypt();
+
+      await contract
+        .connect(signers.alice)
+        .correctMinimizeOperations(input.handles[0], input.inputProof);
+
+      const encrypted = await contract.getValue();
+      const decrypted = await fhevm.userDecryptEuint(
+        FhevmType.euint32,
+        encrypted,
+        contractAddress,
+        signers.alice
+      );
+
+      // 2 * 32 = 64
+      expect(decrypted).to.equal(64);
+    });
+  });
+
+  describe("Pattern 3: Deprecated APIs", function () {
+    it("wrongDeprecatedAPI should return warning string", async function () {
+      const result = await contract.wrongDeprecatedAPI();
+      expect(result).to.include("deprecated");
+    });
+
+    it("correctModernAPI should return guidance string", async function () {
+      const result = await contract.correctModernAPI();
+      expect(result).to.include("FHE.makePubliclyDecryptable");
+    });
+  });
+
+  describe("Pattern 4: Type Mismatch", function () {
+    const testValue = 100;
+
+    it("wrongOversizedType should use euint256 unnecessarily", async function () {
+      const fhevm: HardhatFhevmRuntimeEnvironment = hre.fhevm;
+
+      const input = await fhevm
+        .createEncryptedInput(contractAddress, signers.alice.address)
+        .add32(testValue)
+        .encrypt();
+
+      await contract
+        .connect(signers.alice)
+        .wrongOversizedType(input.handles[0], input.inputProof);
+
+      // Value stored but with wasteful type conversion
+    });
+
+    it("correctRightSizedType should use euint32", async function () {
+      const fhevm: HardhatFhevmRuntimeEnvironment = hre.fhevm;
+
+      const input = await fhevm
+        .createEncryptedInput(contractAddress, signers.alice.address)
+        .add32(testValue)
+        .encrypt();
+
+      await contract
+        .connect(signers.alice)
+        .correctRightSizedType(input.handles[0], input.inputProof);
+
+      const encrypted = await contract.getValue();
+      const decrypted = await fhevm.userDecryptEuint(
+        FhevmType.euint32,
+        encrypted,
+        contractAddress,
+        signers.alice
+      );
+
+      expect(decrypted).to.equal(testValue * 2);
+    });
+  });
+});

package/test/concepts/antipatterns/Permissions.ts

@@ -0,0 +1,327 @@
+import {
+  FhevmType,
+  HardhatFhevmRuntimeEnvironment,
+} from "@fhevm/hardhat-plugin";
+import { HardhatEthersSigner } from "@nomicfoundation/hardhat-ethers/signers";
+import { expect } from "chai";
+import { ethers } from "hardhat";
+import * as hre from "hardhat";
+
+import {
+  FHEPermissionsAntiPatterns,
+  FHEPermissionsAntiPatterns__factory,
+} from "../types";
+import type { Signers } from "./types";
+
+async function deployFixture() {
+  const factory = (await ethers.getContractFactory(
+    "FHEPermissionsAntiPatterns"
+  )) as FHEPermissionsAntiPatterns__factory;
+  const contract = (await factory.deploy()) as FHEPermissionsAntiPatterns;
+  const contractAddress = await contract.getAddress();
+  return { contract, contractAddress };
+}
+
+/**
+ * @notice Tests for FHE permission anti-patterns
+ * Demonstrates wrong and correct permission handling patterns
+ */
+describe("FHEPermissionsAntiPatterns", function () {
+  let contract: FHEPermissionsAntiPatterns;
+  let contractAddress: string;
+  let signers: Signers;
+  let bob: HardhatEthersSigner;
+
+  before(async function () {
+    if (!hre.fhevm.isMock) {
+      throw new Error(`This hardhat test suite cannot run on Sepolia Testnet`);
+    }
+    const ethSigners: HardhatEthersSigner[] = await ethers.getSigners();
+    signers = { owner: ethSigners[0], alice: ethSigners[1] };
+    bob = ethSigners[2];
+  });
+
+  beforeEach(async function () {
+    const deployment = await deployFixture();
+    contractAddress = deployment.contractAddress;
+    contract = deployment.contract;
+  });
+
+  describe("Pattern 1: Missing allowThis", function () {
+    const testValue = 42;
+
+    it("should FAIL without allowThis", async function () {
+      const fhevm: HardhatFhevmRuntimeEnvironment = hre.fhevm;
+
+      const input = await fhevm
+        .createEncryptedInput(contractAddress, signers.alice.address)
+        .add32(testValue)
+        .encrypt();
+
+      await contract
+        .connect(signers.alice)
+        .wrongMissingAllowThis(input.handles[0], input.inputProof);
+
+      // Decryption should fail
+      const encrypted = await contract.getValue();
+      await expect(
+        fhevm.userDecryptEuint(
+          FhevmType.euint32,
+          encrypted,
+          contractAddress,
+          signers.alice
+        )
+      ).to.be.rejected;
+    });
+
+    it("should succeed with allowThis", async function () {
+      const fhevm: HardhatFhevmRuntimeEnvironment = hre.fhevm;
+
+      const input = await fhevm
+        .createEncryptedInput(contractAddress, signers.alice.address)
+        .add32(testValue)
+        .encrypt();
+
+      await contract
+        .connect(signers.alice)
+        .correctWithAllowThis(input.handles[0], input.inputProof);
+
+      const encrypted = await contract.getValue();
+      const decrypted = await fhevm.userDecryptEuint(
+        FhevmType.euint32,
+        encrypted,
+        contractAddress,
+        signers.alice
+      );
+
+      expect(decrypted).to.equal(testValue * 2);
+    });
+  });
+
+  describe("Pattern 2: Missing allow(user)", function () {
+    const testValue = 100;
+
+    it("should FAIL without user allow", async function () {
+      const fhevm: HardhatFhevmRuntimeEnvironment = hre.fhevm;
+
+      const input = await fhevm
+        .createEncryptedInput(contractAddress, signers.alice.address)
+        .add32(testValue)
+        .encrypt();
+
+      await contract
+        .connect(signers.alice)
+        .wrongMissingUserAllow(input.handles[0], input.inputProof);
+
+      const encrypted = await contract.getValue();
+      await expect(
+        fhevm.userDecryptEuint(
+          FhevmType.euint32,
+          encrypted,
+          contractAddress,
+          signers.alice
+        )
+      ).to.be.rejected;
+    });
+
+    it("should succeed with user allow", async function () {
+      const fhevm: HardhatFhevmRuntimeEnvironment = hre.fhevm;
+
+      const input = await fhevm
+        .createEncryptedInput(contractAddress, signers.alice.address)
+        .add32(testValue)
+        .encrypt();
+
+      await contract
+        .connect(signers.alice)
+        .correctWithUserAllow(input.handles[0], input.inputProof);
+
+      const encrypted = await contract.getValue();
+      const decrypted = await fhevm.userDecryptEuint(
+        FhevmType.euint32,
+        encrypted,
+        contractAddress,
+        signers.alice
+      );
+
+      expect(decrypted).to.equal(testValue);
+    });
+  });
+
+  describe("Pattern 3: View Function Without Permissions", function () {
+    const testValue = 200;
+
+    it("should FAIL when stored without permission", async function () {
+      const fhevm: HardhatFhevmRuntimeEnvironment = hre.fhevm;
+
+      const input = await fhevm
+        .createEncryptedInput(contractAddress, signers.alice.address)
+        .add32(testValue)
+        .encrypt();
+
+      await contract
+        .connect(signers.alice)
+        .wrongStoreWithoutPermission(input.handles[0], input.inputProof);
+
+      const encrypted = await contract.getValue();
+      await expect(
+        fhevm.userDecryptEuint(
+          FhevmType.euint32,
+          encrypted,
+          contractAddress,
+          signers.alice
+        )
+      ).to.be.rejected;
+    });
+
+    it("should succeed when stored with permission", async function () {
+      const fhevm: HardhatFhevmRuntimeEnvironment = hre.fhevm;
+
+      const input = await fhevm
+        .createEncryptedInput(contractAddress, signers.alice.address)
+        .add32(testValue)
+        .encrypt();
+
+      await contract
+        .connect(signers.alice)
+        .correctStoreWithPermission(input.handles[0], input.inputProof);
+
+      const encrypted = await contract.getValue();
+      const decrypted = await fhevm.userDecryptEuint(
+        FhevmType.euint32,
+        encrypted,
+        contractAddress,
+        signers.alice
+      );
+
+      expect(decrypted).to.equal(testValue);
+    });
+  });
+
+  describe("Pattern 4: Unauthenticated Re-encryption", function () {
+    it("wrongReencryptWithoutAuth should return empty bytes", async function () {
+      const dummyPublicKey =
+        "0x0000000000000000000000000000000000000000000000000000000000000000";
+      const result = await contract.wrongReencryptWithoutAuth(dummyPublicKey);
+      expect(result).to.equal("0x");
+    });
+
+    it("correctReencryptWithAuth should return encrypted handle", async function () {
+      const fhevm: HardhatFhevmRuntimeEnvironment = hre.fhevm;
+
+      const input = await fhevm
+        .createEncryptedInput(contractAddress, signers.alice.address)
+        .add32(123)
+        .encrypt();
+
+      await contract
+        .connect(signers.alice)
+        .correctWithUserAllow(input.handles[0], input.inputProof);
+
+      const encrypted = await contract.correctReencryptWithAuth();
+      expect(encrypted).to.not.equal(0);
+    });
+  });
+
+  describe("Pattern 5: Transfer Without Permission", function () {
+    const initialBalance = 1000;
+    const transferAmount = 100;
+
+    beforeEach(async function () {
+      const fhevm: HardhatFhevmRuntimeEnvironment = hre.fhevm;
+
+      // Initialize Alice's balance
+      const input = await fhevm
+        .createEncryptedInput(contractAddress, signers.alice.address)
+        .add32(initialBalance)
+        .encrypt();
+
+      await contract
+        .connect(signers.alice)
+        .initializeBalance(input.handles[0], input.inputProof);
+    });
+
+    it("should FAIL recipient decryption without permission", async function () {
+      const fhevm: HardhatFhevmRuntimeEnvironment = hre.fhevm;
+
+      const input = await fhevm
+        .createEncryptedInput(contractAddress, signers.alice.address)
+        .add32(transferAmount)
+        .encrypt();
+
+      await contract
+        .connect(signers.alice)
+        .wrongTransferWithoutPermission(
+          bob.address,
+          input.handles[0],
+          input.inputProof
+        );
+
+      // Bob cannot decrypt his balance
+      const encrypted = await contract.getBalance(bob.address);
+      await expect(
+        fhevm.userDecryptEuint(
+          FhevmType.euint32,
+          encrypted,
+          contractAddress,
+          bob
+        )
+      ).to.be.rejected;
+    });
+
+    it("should succeed with permission propagation", async function () {
+      const fhevm: HardhatFhevmRuntimeEnvironment = hre.fhevm;
+
+      const input = await fhevm
+        .createEncryptedInput(contractAddress, signers.alice.address)
+        .add32(transferAmount)
+        .encrypt();
+
+      await contract
+        .connect(signers.alice)
+        .correctTransferWithPermission(
+          bob.address,
+          input.handles[0],
+          input.inputProof
+        );
+
+      // Bob can decrypt his balance
+      const encrypted = await contract.getBalance(bob.address);
+      const decrypted = await fhevm.userDecryptEuint(
+        FhevmType.euint32,
+        encrypted,
+        contractAddress,
+        bob
+      );
+
+      expect(decrypted).to.equal(transferAmount);
+    });
+  });
+
+  describe("Pattern 6: Cross-Contract Permission", function () {
+    beforeEach(async function () {
+      // Initialize _secretValue so the contract has permission on it
+      const fhevm: HardhatFhevmRuntimeEnvironment = hre.fhevm;
+      const input = await fhevm
+        .createEncryptedInput(contractAddress, signers.alice.address)
+        .add32(42)
+        .encrypt();
+
+      await contract
+        .connect(signers.alice)
+        .correctWithAllowThis(input.handles[0], input.inputProof);
+    });
+
+    it("wrongCrossContractCall should call without permission", async function () {
+      const dummyAddress = "0x0000000000000000000000000000000000000001";
+      // This will fail but we're just testing it doesn't revert
+      await contract.wrongCrossContractCall(dummyAddress);
+    });
+
+    it("correctCrossContractCall should grant allowTransient", async function () {
+      const dummyAddress = "0x0000000000000000000000000000000000000001";
+      // This should succeed - contract has permission on _secretValue
+      await contract.correctCrossContractCall(dummyAddress);
+    });
+  });
+});