create-fhevm-example 1.4.6 → 1.4.7

package/dist/scripts/commands/doctor.js

@@ -127,12 +127,83 @@ async function checkConfigIntegrity() {
         };
     }
 }
+async function checkSubmoduleStatus() {
+    const SUBMODULE_PATH = "fhevm-hardhat-template";
+    const SUBMODULE_URL = "https://github.com/zama-ai/fhevm-hardhat-template";
+    try {
+        // 1. Get local commit hash
+        const localStatus = (0, child_process_1.execSync)(`git submodule status ${SUBMODULE_PATH}`, {
+            stdio: "pipe",
+            encoding: "utf-8",
+        }).trim();
+        // git submodule status output: " 3e01a81bfca5f0857cba55a099e98863efc79bcb fhevm-hardhat-template (v0.2.0-2-g3e01a81)"
+        const localHash = localStatus.split(" ").filter((s) => s.length > 0)[0];
+        if (!localHash || localHash.length < 40) {
+            return {
+                name: "Submodule status",
+                status: "fail",
+                message: "Not initialized",
+                details: [
+                    `Run ${picocolors_1.default.bold("git submodule update --init")} to initialize.`,
+                ],
+            };
+        }
+        // 2. Get remote commit hash
+        // We use a timeout to not hang doctor script if internet is slow/down
+        const remoteInfo = (0, child_process_1.execSync)(`git ls-remote ${SUBMODULE_URL} HEAD`, {
+            stdio: "pipe",
+            encoding: "utf-8",
+            timeout: 5000, // 5 seconds timeout
+        }).trim();
+        const remoteHash = remoteInfo.split("\t")[0];
+        if (!remoteHash || remoteHash.length < 40) {
+            return {
+                name: "Submodule status",
+                status: "warn",
+                message: "Connection error",
+                details: ["Could not fetch remote status from GitHub."],
+            };
+        }
+        if (localHash === remoteHash) {
+            return {
+                name: "Submodule status",
+                status: "success",
+                message: "Up to date",
+            };
+        }
+        else {
+            return {
+                name: "Submodule status",
+                status: "warn",
+                message: "Update available",
+                details: [
+                    `Local:  ${picocolors_1.default.dim(localHash.slice(0, 7))}`,
+                    `Remote: ${picocolors_1.default.dim(remoteHash.slice(0, 7))}`,
+                    `Run ${picocolors_1.default.bold("git submodule update --remote --merge")} to update.`,
+                ],
+            };
+        }
+    }
+    catch (e) {
+        return {
+            name: "Submodule status",
+            status: "warn",
+            message: "Check skipped",
+            details: ["Git error or no internet connection."],
+        };
+    }
+}
 // =============================================================================
 // Main
 // =============================================================================
 async function main() {
     p.intro(picocolors_1.default.cyan("🩺 FHEVM Doctor"));
-    const checks = [checkNodeVersion(), checkGit(), checkConfigIntegrity()];
+    const checks = [
+        checkNodeVersion(),
+        checkGit(),
+        checkConfigIntegrity(),
+        checkSubmoduleStatus(),
+    ];
     const results = await Promise.all(checks);
     let hasFailure = false;
     for (const result of results) {

package/dist/scripts/commands/generate-config.js

@@ -191,7 +191,18 @@ function generateCategoriesConfig(contracts) {
         }
         categoryMap[contract.category].push(contract);
     }
-    const categoryEntries = Object.entries(categoryMap).map(([category, items]) => {
+    const sortedEntries = Object.entries(categoryMap).sort(([catA], [catB]) => {
+        const idxA = utils_1.CATEGORY_ORDER.indexOf(catA);
+        const idxB = utils_1.CATEGORY_ORDER.indexOf(catB);
+        if (idxA !== -1 && idxB !== -1)
+            return idxA - idxB;
+        if (idxA !== -1)
+            return -1;
+        if (idxB !== -1)
+            return 1;
+        return catA.localeCompare(catB);
+    });
+    const categoryEntries = sortedEntries.map(([category, items]) => {
         const categoryKey = category
             .toLowerCase()
             .replace(/\s+/g, "")
@@ -203,7 +214,7 @@ function generateCategoriesConfig(contracts) {
       }`)
             .join(",\n");
         return `  ${categoryKey}: {
-    name: "${category} Examples",
+    name: "${category}",
     contracts: [
 ${contracts}
     ],

package/dist/scripts/shared/config.js

@@ -144,30 +144,6 @@ exports.EXAMPLES = {
         docsOutput: "docs/basic/fhe-operations/fhe-if-then-else.md",
         title: "FHE If Then Else"
     },
-    "fhe-access-control": {
-        contract: "contracts/concepts/FHEAccessControl.sol",
-        test: "test/concepts/FHEAccessControl.ts",
-        description: "Master class for FHE permission patterns and access control. Explains the three permission types: allow() for permanent access, allowThis() for contract operations, and allowTransient() for temporary cross-contract calls. Includes correct and incorrect usage examples to prevent common decryption failures.",
-        category: "Concepts",
-        docsOutput: "docs/concepts/fhe-access-control.md",
-        title: "FHE Access Control"
-    },
-    "fhe-handles": {
-        contract: "contracts/concepts/FHEHandles.sol",
-        test: "test/concepts/FHEHandles.ts",
-        description: "Deep dive into FHE handles: what they are and how they work. Explains that handles are uint256 pointers to encrypted data, demonstrates three creation methods (fromExternal, asEuint, operations), and emphasizes immutability - every operation creates a NEW handle. Includes gas cost comparisons for different operations.",
-        category: "Concepts",
-        docsOutput: "docs/concepts/fhe-handles.md",
-        title: "FHE Handles"
-    },
-    "fhe-input-proof": {
-        contract: "contracts/concepts/FHEInputProof.sol",
-        test: "test/concepts/FHEInputProof.ts",
-        description: "Input proof validation and batching strategies in FHEVM. Explains why proofs are essential (prevent garbage data, wrong types, and replay attacks) and demonstrates the gas-efficient batching pattern where one proof validates multiple encrypted inputs, saving ~50k gas per additional value.",
-        category: "Concepts",
-        docsOutput: "docs/concepts/fhe-input-proof.md",
-        title: "FHE Input Proof"
-    },
     "control-flow": {
         contract: "contracts/concepts/antipatterns/ControlFlow.sol",
         test: "test/concepts/antipatterns/ControlFlow.ts",
@@ -192,6 +168,30 @@ exports.EXAMPLES = {
         docsOutput: "docs/concepts/antipatterns/permissions.md",
         title: "Permissions"
     },
+    "fhe-access-control": {
+        contract: "contracts/concepts/core/FHEAccessControl.sol",
+        test: "test/concepts/core/FHEAccessControl.ts",
+        description: "Master class for FHE permission patterns and access control. Explains the three permission types: allow() for permanent access, allowThis() for contract operations, and allowTransient() for temporary cross-contract calls. Includes correct and incorrect usage examples to prevent common decryption failures.",
+        category: "Concepts - Core",
+        docsOutput: "docs/concepts/core/fhe-access-control.md",
+        title: "FHE Access Control"
+    },
+    "fhe-handles": {
+        contract: "contracts/concepts/core/FHEHandles.sol",
+        test: "test/concepts/core/FHEHandles.ts",
+        description: "Deep dive into FHE handles: what they are and how they work. Explains that handles are uint256 pointers to encrypted data, demonstrates three creation methods (fromExternal, asEuint, operations), and emphasizes immutability - every operation creates a NEW handle. Includes gas cost comparisons for different operations.",
+        category: "Concepts - Core",
+        docsOutput: "docs/concepts/core/fhe-handles.md",
+        title: "FHE Handles"
+    },
+    "fhe-input-proof": {
+        contract: "contracts/concepts/core/FHEInputProof.sol",
+        test: "test/concepts/core/FHEInputProof.ts",
+        description: "Input proof validation and batching strategies in FHEVM. Explains why proofs are essential (prevent garbage data, wrong types, and replay attacks) and demonstrates the gas-efficient batching pattern where one proof validates multiple encrypted inputs, saving ~50k gas per additional value.",
+        category: "Concepts - Core",
+        docsOutput: "docs/concepts/core/fhe-input-proof.md",
+        title: "FHE Input Proof"
+    },
     "encrypted-lottery": {
         contract: "contracts/gaming/EncryptedLottery.sol",
         test: "test/gaming/EncryptedLottery.ts",
@@ -293,33 +293,25 @@ exports.EXAMPLES = {
 // Category Configurations
 // =============================================================================
 exports.CATEGORIES = {
-    advanced: {
-        name: "Advanced Examples",
+    basicencryption: {
+        name: "Basic - Encryption",
         contracts: [
             {
-                sol: "contracts/advanced/BlindAuction.sol",
-                test: "test/advanced/BlindAuction.ts",
-            },
-            {
-                sol: "contracts/advanced/EncryptedEscrow.sol",
-                test: "test/advanced/EncryptedEscrow.ts",
-            },
-            {
-                sol: "contracts/advanced/HiddenVoting.sol",
-                test: "test/advanced/HiddenVoting.ts",
+                sol: "contracts/basic/encryption/EncryptMultipleValues.sol",
+                test: "test/basic/encryption/EncryptMultipleValues.ts",
             },
             {
-                sol: "contracts/advanced/PrivateKYC.sol",
-                test: "test/advanced/PrivateKYC.ts",
+                sol: "contracts/basic/encryption/EncryptSingleValue.sol",
+                test: "test/basic/encryption/EncryptSingleValue.ts",
             },
             {
-                sol: "contracts/advanced/PrivatePayroll.sol",
-                test: "test/advanced/PrivatePayroll.ts",
+                sol: "contracts/basic/encryption/FHECounter.sol",
+                test: "test/basic/encryption/FHECounter.ts",
             }
         ],
     },
     basicdecryption: {
-        name: "Basic - Decryption Examples",
+        name: "Basic - Decryption",
         contracts: [
             {
                 sol: "contracts/basic/decryption/PublicDecryptMultipleValues.sol",
@@ -339,25 +331,8 @@ exports.CATEGORIES = {
             }
         ],
     },
-    basicencryption: {
-        name: "Basic - Encryption Examples",
-        contracts: [
-            {
-                sol: "contracts/basic/encryption/EncryptMultipleValues.sol",
-                test: "test/basic/encryption/EncryptMultipleValues.ts",
-            },
-            {
-                sol: "contracts/basic/encryption/EncryptSingleValue.sol",
-                test: "test/basic/encryption/EncryptSingleValue.ts",
-            },
-            {
-                sol: "contracts/basic/encryption/FHECounter.sol",
-                test: "test/basic/encryption/FHECounter.ts",
-            }
-        ],
-    },
     basicfheoperations: {
-        name: "Basic - FHE Operations Examples",
+        name: "Basic - FHE Operations",
         contracts: [
             {
                 sol: "contracts/basic/fhe-operations/FHEAdd.sol",
@@ -377,25 +352,25 @@ exports.CATEGORIES = {
             }
         ],
     },
-    concepts: {
-        name: "Concepts Examples",
+    conceptscore: {
+        name: "Concepts - Core",
         contracts: [
             {
-                sol: "contracts/concepts/FHEAccessControl.sol",
-                test: "test/concepts/FHEAccessControl.ts",
+                sol: "contracts/concepts/core/FHEAccessControl.sol",
+                test: "test/concepts/core/FHEAccessControl.ts",
             },
             {
-                sol: "contracts/concepts/FHEHandles.sol",
-                test: "test/concepts/FHEHandles.ts",
+                sol: "contracts/concepts/core/FHEHandles.sol",
+                test: "test/concepts/core/FHEHandles.ts",
             },
             {
-                sol: "contracts/concepts/FHEInputProof.sol",
-                test: "test/concepts/FHEInputProof.ts",
+                sol: "contracts/concepts/core/FHEInputProof.sol",
+                test: "test/concepts/core/FHEInputProof.ts",
             }
         ],
     },
     conceptsantipatterns: {
-        name: "Concepts - Antipatterns Examples",
+        name: "Concepts - Antipatterns",
         contracts: [
             {
                 sol: "contracts/concepts/antipatterns/ControlFlow.sol",
@@ -412,7 +387,7 @@ exports.CATEGORIES = {
         ],
     },
     gaming: {
-        name: "Gaming Examples",
+        name: "Gaming",
         contracts: [
             {
                 sol: "contracts/gaming/EncryptedLottery.sol",
@@ -428,8 +403,33 @@ exports.CATEGORIES = {
             }
         ],
     },
+    advanced: {
+        name: "Advanced",
+        contracts: [
+            {
+                sol: "contracts/advanced/BlindAuction.sol",
+                test: "test/advanced/BlindAuction.ts",
+            },
+            {
+                sol: "contracts/advanced/EncryptedEscrow.sol",
+                test: "test/advanced/EncryptedEscrow.ts",
+            },
+            {
+                sol: "contracts/advanced/HiddenVoting.sol",
+                test: "test/advanced/HiddenVoting.ts",
+            },
+            {
+                sol: "contracts/advanced/PrivateKYC.sol",
+                test: "test/advanced/PrivateKYC.ts",
+            },
+            {
+                sol: "contracts/advanced/PrivatePayroll.sol",
+                test: "test/advanced/PrivatePayroll.ts",
+            }
+        ],
+    },
     openzeppelin: {
-        name: "Openzeppelin Examples",
+        name: "Openzeppelin",
         contracts: [
             {
                 sol: "contracts/openzeppelin/ERC7984.sol",

package/dist/scripts/shared/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../scripts/shared/utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAWH,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,UAAU,CAAC;AAEhD,eAAO,MAAM,aAAa,iBAAO,CAAC;AAElC,qDAAqD;AACrD,eAAO,MAAM,iBAAiB,2BAA2B,CAAC;AAE1D,gDAAgD;AAChD,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAEzC,mDAAmD;AACnD,eAAO,MAAM,YAAY,UAQxB,CAAC;AAEF,wFAAwF;AACxF,eAAO,MAAM,iBAAiB,2QAyB7B,CAAC;AAEF,4CAA4C;AAC5C,eAAO,MAAM,kBAAkB;;;;;;;;;CAS9B,CAAC;AAEF,eAAO,MAAM,cAAc,UAQ1B,CAAC;AAEF,eAAO,MAAM,kBAAkB,yPAS9B,CAAC;AAEF,eAAO,MAAM,cAAc;;;4BAGD,MAAM;6BACL,MAAM;uBACZ,MAAM;;;;CAI1B,CAAC;AAMF,eAAO,MAAM,GAAG;mBACC,MAAM;iBACR,MAAM;gBACP,MAAM;eACP,MAAM;mBACF,MAAM;CACtB,CAAC;AAEF;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,SAAI,GAAG,KAAK,CAI/D;AAMD,sDAAsD;AACtD,wBAAgB,UAAU,IAAI,MAAM,CAUnC;AAED,uCAAuC;AACvC,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED,oEAAoE;AACpE,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,WAAW,GAAE,MAAM,EAAiB,GACnC,IAAI,CAoBN;AAMD,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAM/C;AAED,wBAAgB,yBAAyB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAKhE;AAED,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAK7D;AAED,wBAAgB,eAAe,CAAC,qBAAqB,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAqB5E;AAMD,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAIlD;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAInD;AAED,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAIhE"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../scripts/shared/utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAWH,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,UAAU,CAAC;AAEhD,eAAO,MAAM,aAAa,iBAAO,CAAC;AAElC,qDAAqD;AACrD,eAAO,MAAM,iBAAiB,2BAA2B,CAAC;AAE1D,gDAAgD;AAChD,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAEzC,mDAAmD;AACnD,eAAO,MAAM,YAAY,UAQxB,CAAC;AAEF,wFAAwF;AACxF,eAAO,MAAM,iBAAiB,2QAyB7B,CAAC;AAEF,4CAA4C;AAC5C,eAAO,MAAM,kBAAkB;;;;;;;;;CAS9B,CAAC;AAEF,eAAO,MAAM,cAAc,UAS1B,CAAC;AAEF,eAAO,MAAM,kBAAkB,yPAS9B,CAAC;AAEF,eAAO,MAAM,cAAc;;;4BAGD,MAAM;6BACL,MAAM;uBACZ,MAAM;;;;CAI1B,CAAC;AAMF,eAAO,MAAM,GAAG;mBACC,MAAM;iBACR,MAAM;gBACP,MAAM;eACP,MAAM;mBACF,MAAM;CACtB,CAAC;AAEF;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,SAAI,GAAG,KAAK,CAI/D;AAMD,sDAAsD;AACtD,wBAAgB,UAAU,IAAI,MAAM,CAUnC;AAED,uCAAuC;AACvC,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED,oEAAoE;AACpE,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,WAAW,GAAE,MAAM,EAAiB,GACnC,IAAI,CAoBN;AAMD,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAM/C;AAED,wBAAgB,yBAAyB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAKhE;AAED,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAK7D;AAED,wBAAgB,eAAe,CAAC,qBAAqB,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAqB5E;AAMD,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAIlD;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAInD;AAED,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAIhE"}

package/dist/scripts/shared/utils.js

@@ -116,10 +116,11 @@ exports.CATEGORY_ORDER = [
     "Basic - Encryption",
     "Basic - Decryption",
     "Basic - FHE Operations",
-    "Concepts",
+    "Concepts - Core",
+    "Concepts - Antipatterns",
     "Gaming",
-    "Openzeppelin",
     "Advanced",
+    "Openzeppelin",
 ];
 exports.TEST_TYPES_CONTENT = `import type { HardhatEthersSigner } from "@nomicfoundation/hardhat-ethers/signers";
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-fhevm-example",
-  "version": "1.4.6",
+  "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/FHEAntiPatterns.ts

@@ -1,112 +0,0 @@
-import { HardhatEthersSigner } from "@nomicfoundation/hardhat-ethers/signers";
-import { expect } from "chai";
-import { ethers } from "hardhat";
-import * as hre from "hardhat";
-
-import { FHEAntiPatterns, FHEAntiPatterns__factory } from "../types";
-import type { Signers } from "./types";
-
-async function deployFixture() {
-  const factory = (await ethers.getContractFactory(
-    "FHEAntiPatterns"
-  )) as FHEAntiPatterns__factory;
-  const contract = (await factory.deploy()) as FHEAntiPatterns;
-  const contractAddress = await contract.getAddress();
-  return { contract, contractAddress };
-}
-
-/**
- * @notice Tests for FHE anti-patterns
- * Demonstrates correct patterns for common FHE mistakes
- */
-describe("FHEAntiPatterns", function () {
-  let contract: FHEAntiPatterns;
-  let contractAddress: string;
-  let signers: Signers;
-
-  before(async function () {
-    if (!hre.fhevm.isMock) {
-      console.warn(`This hardhat test suite cannot run on Sepolia Testnet`);
-      this.skip();
-    }
-    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("Initialization", function () {
-    it("should initialize with encrypted balance and threshold", async function () {
-      const fhevm = hre.fhevm;
-      const balance = 100;
-      const threshold = 50;
-
-      const input = await fhevm
-        .createEncryptedInput(contractAddress, signers.alice.address)
-        .add32(balance)
-        .add32(threshold)
-        .encrypt();
-
-      await contract
-        .connect(signers.alice)
-        .initialize(input.handles[0], input.handles[1], input.inputProof);
-
-      // Contract should now have encrypted values
-      // We can't directly verify values without decryption, but tx should succeed
-    });
-  });
-
-  describe("Correct Conditional Pattern", function () {
-    it("should handle conditional logic with FHE.select", async function () {
-      const fhevm = hre.fhevm;
-
-      // Initialize with balance=100, threshold=50
-      const input = await fhevm
-        .createEncryptedInput(contractAddress, signers.alice.address)
-        .add32(100) // balance
-        .add32(50) // threshold
-        .encrypt();
-
-      await contract
-        .connect(signers.alice)
-        .initialize(input.handles[0], input.handles[1], input.inputProof);
-
-      // Execute correct conditional - should not revert
-      await expect(contract.connect(signers.alice).correctConditional()).to.not
-        .be.reverted;
-    });
-  });
-
-  describe("Correct Computation Pattern", function () {
-    it("should compute with proper permission grants", async function () {
-      const fhevm = hre.fhevm;
-
-      const input = await fhevm
-        .createEncryptedInput(contractAddress, signers.alice.address)
-        .add32(50) // balance
-        .add32(25) // threshold
-        .encrypt();
-
-      await contract
-        .connect(signers.alice)
-        .initialize(input.handles[0], input.handles[1], input.inputProof);
-
-      // correctCompute grants proper permissions
-      await expect(contract.connect(signers.alice).correctCompute()).to.not.be
-        .reverted;
-    });
-  });
-
-  describe("Rules Reference", function () {
-    it("should return the key rules summary", async function () {
-      const rules = await contract.getRules();
-      expect(rules).to.include("FHE.select");
-      expect(rules).to.include("FHE.allowThis");
-      expect(rules).to.include("require/revert");
-    });
-  });
-});