create-fhevm-example 1.4.5 → 1.4.7

package/dist/scripts/commands/add-mode.js

@@ -58,7 +58,7 @@ const utils_1 = require("../shared/utils");
 function detectHardhatProject(targetDir) {
     const packageJsonPath = path.join(targetDir, "package.json");
     const hardhatConfigTs = path.join(targetDir, "hardhat.config.ts");
-    const hardhatConfigJs = path.join(targetDir, "hardhat.config");
+    const hardhatConfigJs = path.join(targetDir, "hardhat.config.js");
     if (!fs.existsSync(packageJsonPath)) {
         return false;
     }
@@ -106,7 +106,7 @@ function updateHardhatConfig(targetDir) {
             ? configPathJs
             : null;
     if (!actualPath) {
-        throw new Error("hardhat.config.ts or hardhat.config.js not found");
+        throw new Error(utils_1.ERROR_MESSAGES.CONFIG_NOT_FOUND);
     }
     let content = fs.readFileSync(actualPath, "utf-8");
     if (content.includes("@fhevm/hardhat-plugin")) {
@@ -139,12 +139,12 @@ function updateHardhatConfig(targetDir) {
 function addExampleFiles(exampleName, targetDir) {
     const example = config_1.EXAMPLES[exampleName];
     if (!example) {
-        throw new Error(`Unknown example: ${exampleName}`);
+        throw new Error(utils_1.ERROR_MESSAGES.UNKNOWN_EXAMPLE(exampleName));
     }
     const rootDir = (0, utils_1.getRootDir)();
     const contractName = (0, utils_1.getContractName)(example.contract);
     if (!contractName) {
-        throw new Error("Could not extract contract name");
+        throw new Error(utils_1.ERROR_MESSAGES.CONTRACT_NAME_FAILED);
     }
     const contractSource = path.join(rootDir, example.contract);
     const testSource = path.join(rootDir, example.test);
@@ -154,15 +154,9 @@ function addExampleFiles(exampleName, targetDir) {
     if (!fs.existsSync(contractsDir)) {
         fs.mkdirSync(contractsDir, { recursive: true });
     }
-    if (fs.existsSync(contractDest)) {
-        // File exists - will be handled by caller with prompts
-        fs.copyFileSync(contractSource, contractDest);
-        p.log.success(`Overwritten: ${contractName}.sol`);
-    }
-    else {
-        fs.copyFileSync(contractSource, contractDest);
-        p.log.success(`Added: ${contractName}.sol`);
-    }
+    const isContractOverwrite = fs.existsSync(contractDest);
+    fs.copyFileSync(contractSource, contractDest);
+    p.log.success(`${isContractOverwrite ? "Overwritten" : "Added"}: ${contractName}.sol`);
     // Handle test file
     const testFileName = path.basename(example.test);
     const testDest = path.join(targetDir, "test", testFileName);
@@ -170,14 +164,9 @@ function addExampleFiles(exampleName, targetDir) {
     if (!fs.existsSync(testDir)) {
         fs.mkdirSync(testDir, { recursive: true });
     }
-    if (fs.existsSync(testDest)) {
-        fs.copyFileSync(testSource, testDest);
-        p.log.success(`Overwritten: ${testFileName}`);
-    }
-    else {
-        fs.copyFileSync(testSource, testDest);
-        p.log.success(`Added: ${testFileName}`);
-    }
+    const isTestOverwrite = fs.existsSync(testDest);
+    fs.copyFileSync(testSource, testDest);
+    p.log.success(`${isTestOverwrite ? "Overwritten" : "Added"}: ${testFileName}`);
     // Handle contract dependencies
     if (example.dependencies) {
         p.log.message("");

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) {
@@ -162,4 +233,7 @@ async function main() {
         p.outro(picocolors_1.default.green("✅ All checks passed! You are ready to develop. 🚀"));
     }
 }
-main().catch(console.error);
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

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/commands/generate-docs.js

@@ -187,5 +187,8 @@ async function main() {
 }
 const isMainModule = process.argv[1]?.includes("generate-docs");
 if (isMainModule) {
-    main().catch(console.error);
+    main().catch((err) => {
+        console.error(err);
+        process.exit(1);
+    });
 }

package/dist/scripts/index.js

@@ -56,6 +56,17 @@ const builders_1 = require("./shared/builders");
 const ui_1 = require("./shared/ui");
 const add_mode_1 = require("./commands/add-mode");
 const generate_docs_1 = require("./commands/generate-docs");
+// =============================================================================
+// INTERACTIVE MODE
+// =============================================================================
+/** Helper to check if user cancelled and show message */
+function checkCancel(value) {
+    if (p.isCancel(value)) {
+        p.cancel("Operation cancelled.");
+        return true;
+    }
+    return false;
+}
 /** Prompts user to select mode and returns project configuration */
 async function getProjectConfig() {
     // Build options - docs only available in local dev mode
@@ -83,22 +94,16 @@ async function getProjectConfig() {
         message: "What would you like to create?",
         options,
     });
-    if (p.isCancel(mode)) {
-        p.cancel("Operation cancelled.");
+    if (checkCancel(mode))
         return null;
-    }
     let name;
     if (mode === "single") {
         const category = await (0, ui_1.promptSelectCategory)();
-        if (p.isCancel(category)) {
-            p.cancel("Operation cancelled.");
+        if (checkCancel(category))
             return null;
-        }
         const example = await (0, ui_1.promptSelectExampleFromCategory)(category);
-        if (p.isCancel(example)) {
-            p.cancel("Operation cancelled.");
+        if (checkCancel(example))
             return null;
-        }
         name = example;
     }
     else if (mode === "docs") {
@@ -108,10 +113,8 @@ async function getProjectConfig() {
     }
     else {
         const category = await (0, ui_1.promptSelectCategoryProject)();
-        if (p.isCancel(category)) {
-            p.cancel("Operation cancelled.");
+        if (checkCancel(category))
             return null;
-        }
         name = category;
     }
     const projectName = await p.text({
@@ -119,27 +122,21 @@ async function getProjectConfig() {
         placeholder: `my-${name}-project`,
         defaultValue: `my-${name}-project`,
     });
-    if (p.isCancel(projectName)) {
-        p.cancel("Operation cancelled.");
+    if (checkCancel(projectName))
         return null;
-    }
     const outputDir = await p.text({
         message: "Output directory:",
         placeholder: `./${projectName}`,
         defaultValue: `./${projectName}`,
     });
-    if (p.isCancel(outputDir)) {
-        p.cancel("Operation cancelled.");
+    if (checkCancel(outputDir))
         return null;
-    }
     const shouldInstall = await p.confirm({
         message: "Install dependencies and run tests?",
         initialValue: false,
     });
-    if (p.isCancel(shouldInstall)) {
-        p.cancel("Operation cancelled.");
+    if (checkCancel(shouldInstall))
         return null;
-    }
     return {
         mode: mode,
         name,
@@ -205,12 +202,22 @@ async function runInteractiveMode() {
 }
 function parseArgs(args) {
     const parsed = {};
+    // Short flag mappings
+    const shortFlags = {
+        "-e": "example",
+        "-c": "category",
+        "-o": "output",
+        "-a": "add",
+        "-i": "install",
+        "-h": "help",
+    };
     for (let i = 0; i < args.length; i++) {
         const arg = args[i];
+        // Handle long flags (--example, --category, etc.)
         if (arg.startsWith("--")) {
             const key = arg.slice(2);
             const nextArg = args[i + 1];
-            if (nextArg && !nextArg.startsWith("--")) {
+            if (nextArg && !nextArg.startsWith("-")) {
                 parsed[key] = nextArg;
                 i++;
             }
@@ -218,8 +225,20 @@ function parseArgs(args) {
                 parsed[key] = true;
             }
         }
-        else if (arg === "-h") {
-            parsed["help"] = true;
+        // Handle short flags (-e, -c, -o, -a, -i, -h)
+        else if (arg.startsWith("-") && shortFlags[arg]) {
+            const key = shortFlags[arg];
+            const nextArg = args[i + 1];
+            // Flags that take values: -e, -c, -o
+            if (["example", "category", "output"].includes(key) &&
+                nextArg &&
+                !nextArg.startsWith("-")) {
+                parsed[key] = nextArg;
+                i++;
+            }
+            else {
+                parsed[key] = true;
+            }
         }
     }
     return parsed;

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

@@ -1 +1 @@
-{"version":3,"file":"builders.d.ts","sourceRoot":"","sources":["../../../scripts/shared/builders.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA6DH;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,GAChB,IAAI,CAkDN;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,GAChB,IAAI,CAwEN;AAMD;;GAEG;AACH,wBAAsB,sBAAsB,CAC1C,YAAY,EAAE,MAAM,EAAE,EACtB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAuEf"}
+{"version":3,"file":"builders.d.ts","sourceRoot":"","sources":["../../../scripts/shared/builders.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAiEH;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,GAChB,IAAI,CAkDN;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,GAChB,IAAI,CAwEN;AAMD;;GAEG;AACH,wBAAsB,sBAAsB,CAC1C,YAAY,EAAE,MAAM,EAAE,EACtB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CA6Df"}

package/dist/scripts/shared/builders.js

@@ -69,7 +69,8 @@ function copyDependencies(dependencies, outputDir) {
     }
 }
 /**
- * Initializes git repository (optional, fails silently)
+ * Initializes git repository (optional, logs warning if skipped)
+ * @returns true if git init succeeded, false otherwise
  */
 function initGitRepo(outputDir) {
     try {
@@ -77,9 +78,11 @@ function initGitRepo(outputDir) {
             cwd: outputDir,
             stdio: "ignore",
         });
+        return true;
     }
     catch {
-        // Git init is optional
+        utils_1.log.dim("   ⚠️ Git initialization skipped (git not available)");
+        return false;
     }
 }
 // =============================================================================
@@ -208,18 +211,9 @@ async function createLocalTestProject(exampleNames, outputDir) {
             Object.assign(allNpmDeps, example.npmDependencies);
         }
     }
-    // 3. Copy dependencies
-    for (const depPath of allContractDeps) {
-        const depFullPath = path.join(rootDir, depPath);
-        if (fs.existsSync(depFullPath)) {
-            const relativePath = depPath.replace(/^contracts\//, "");
-            const depDestPath = path.join(outputDir, "contracts", relativePath);
-            const depDestDir = path.dirname(depDestPath);
-            if (!fs.existsSync(depDestDir)) {
-                fs.mkdirSync(depDestDir, { recursive: true });
-            }
-            fs.copyFileSync(depFullPath, depDestPath);
-        }
+    // 3. Copy dependencies (reuse helper function)
+    if (allContractDeps.size > 0) {
+        copyDependencies(Array.from(allContractDeps), outputDir);
     }
     // 4. Finalize project
     (0, generators_1.updateProjectPackageJson)(outputDir, "fhevm-test-project", `Testing ${exampleNames.length} examples`, Object.keys(allNpmDeps).length > 0 ? allNpmDeps : undefined);

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

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../scripts/shared/config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,MAAM,WAAW,aAAa;IAC5B,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,uCAAuC;IACvC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,4BAA4B;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,8CAA8C;IAC9C,UAAU,EAAE,MAAM,CAAC;IACnB,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,cAAc;IAC7B,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,SAAS,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAClD;AAMD,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CA6RlD,CAAC;AAMF,eAAO,MAAM,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAoJrD,CAAC;AAMF;;GAEG;AACH,wBAAgB,eAAe,IAAI,MAAM,EAAE,CAE1C;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,EAAE,CAE3C;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAElE;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAEpE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE3D"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../scripts/shared/config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,MAAM,WAAW,aAAa;IAC5B,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,uCAAuC;IACvC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,4BAA4B;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,8CAA8C;IAC9C,UAAU,EAAE,MAAM,CAAC;IACnB,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,cAAc;IAC7B,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,SAAS,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAClD;AAMD,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CA+SlD,CAAC;AAMF,eAAO,MAAM,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAiKrD,CAAC;AAMF;;GAEG;AACH,wBAAgB,eAAe,IAAI,MAAM,EAAE,CAE1C;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,EAAE,CAE3C;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAElE;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAEpE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE3D"}

package/dist/scripts/shared/config.js

@@ -144,36 +144,52 @@ exports.EXAMPLES = {
         docsOutput: "docs/basic/fhe-operations/fhe-if-then-else.md",
         title: "FHE If Then Else"
     },
+    "control-flow": {
+        contract: "contracts/concepts/antipatterns/ControlFlow.sol",
+        test: "test/concepts/antipatterns/ControlFlow.ts",
+        description: "Control flow anti-patterns in FHE development. Demonstrates common mistakes when using conditional logic and loops with encrypted values.",
+        category: "Concepts - Antipatterns",
+        docsOutput: "docs/concepts/antipatterns/control-flow.md",
+        title: "Control Flow"
+    },
+    "operations-gas-noise": {
+        contract: "contracts/concepts/antipatterns/OperationsGasNoise.sol",
+        test: "test/concepts/antipatterns/OperationsGasNoise.ts",
+        description: "Operations, gas, and noise anti-patterns in FHE development. Demonstrates performance issues, side-channel leaks, and inefficient encrypted computation patterns.",
+        category: "Concepts - Antipatterns",
+        docsOutput: "docs/concepts/antipatterns/operations-gas-noise.md",
+        title: "Operations Gas Noise"
+    },
+    "permissions": {
+        contract: "contracts/concepts/antipatterns/Permissions.sol",
+        test: "test/concepts/antipatterns/Permissions.ts",
+        description: "Permission management anti-patterns in FHE development. Demonstrates common mistakes with allowThis, allow, and permission propagation across transfers and contracts.",
+        category: "Concepts - Antipatterns",
+        docsOutput: "docs/concepts/antipatterns/permissions.md",
+        title: "Permissions"
+    },
     "fhe-access-control": {
-        contract: "contracts/concepts/FHEAccessControl.sol",
-        test: "test/concepts/FHEAccessControl.ts",
+        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",
-        docsOutput: "docs/concepts/fhe-access-control.md",
+        category: "Concepts - Core",
+        docsOutput: "docs/concepts/core/fhe-access-control.md",
         title: "FHE Access Control"
     },
-    "fhe-anti-patterns": {
-        contract: "contracts/concepts/FHEAntiPatterns.sol",
-        test: "test/concepts/FHEAntiPatterns.ts",
-        description: "Comprehensive guide to FHE anti-patterns and their solutions. Covers 9 critical mistakes: using if/else on encrypted values, incorrect permission patterns, require() statements that leak info, unbounded loops, noise accumulation, and deprecated APIs. Each pattern shows both ❌ WRONG and ✅ CORRECT implementations.",
-        category: "Concepts",
-        docsOutput: "docs/concepts/fhe-anti-patterns.md",
-        title: "FHE Anti Patterns"
-    },
     "fhe-handles": {
-        contract: "contracts/concepts/FHEHandles.sol",
-        test: "test/concepts/FHEHandles.ts",
+        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",
-        docsOutput: "docs/concepts/fhe-handles.md",
+        category: "Concepts - Core",
+        docsOutput: "docs/concepts/core/fhe-handles.md",
         title: "FHE Handles"
     },
     "fhe-input-proof": {
-        contract: "contracts/concepts/FHEInputProof.sol",
-        test: "test/concepts/FHEInputProof.ts",
+        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",
-        docsOutput: "docs/concepts/fhe-input-proof.md",
+        category: "Concepts - Core",
+        docsOutput: "docs/concepts/core/fhe-input-proof.md",
         title: "FHE Input Proof"
     },
     "encrypted-lottery": {
@@ -277,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",
@@ -323,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",
@@ -361,29 +352,42 @@ 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/FHEAntiPatterns.sol",
-                test: "test/concepts/FHEAntiPatterns.ts",
+                sol: "contracts/concepts/core/FHEHandles.sol",
+                test: "test/concepts/core/FHEHandles.ts",
+            },
+            {
+                sol: "contracts/concepts/core/FHEInputProof.sol",
+                test: "test/concepts/core/FHEInputProof.ts",
+            }
+        ],
+    },
+    conceptsantipatterns: {
+        name: "Concepts - Antipatterns",
+        contracts: [
+            {
+                sol: "contracts/concepts/antipatterns/ControlFlow.sol",
+                test: "test/concepts/antipatterns/ControlFlow.ts",
             },
             {
-                sol: "contracts/concepts/FHEHandles.sol",
-                test: "test/concepts/FHEHandles.ts",
+                sol: "contracts/concepts/antipatterns/OperationsGasNoise.sol",
+                test: "test/concepts/antipatterns/OperationsGasNoise.ts",
             },
             {
-                sol: "contracts/concepts/FHEInputProof.sol",
-                test: "test/concepts/FHEInputProof.ts",
+                sol: "contracts/concepts/antipatterns/Permissions.sol",
+                test: "test/concepts/antipatterns/Permissions.ts",
             }
         ],
     },
     gaming: {
-        name: "Gaming Examples",
+        name: "Gaming",
         contracts: [
             {
                 sol: "contracts/gaming/EncryptedLottery.sol",
@@ -399,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

@@ -108,18 +108,19 @@ exports.FHEVM_DEPENDENCIES = {
         "@fhevm/solidity": "^0.9.1",
     },
     devDependencies: {
-        "@fhevm/hardhat-plugin": "^0.3.0-1",
-        "@zama-fhe/relayer-sdk": "^0.3.0-5",
+        "@fhevm/hardhat-plugin": "^0.3.0-3",
+        "@zama-fhe/relayer-sdk": "^0.3.0-6",
     },
 };
 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";