create-fhevm-example 1.4.1 → 1.4.3

package/dist/scripts/shared/generators.d.ts

@@ -12,6 +12,18 @@ export declare function cleanupTemplate(outputDir: string): void;
  * Generates a deploy script for a contract
  */
 export declare function generateDeployScript(contractName: string): string;
+/**
+ * Extracts FHE function names used in contract
+ */
+export declare function extractFHEFunctions(contractContent: string): string[];
+/**
+ * Extracts FHE types used in contract (from imports and declarations)
+ */
+export declare function extractFHETypes(contractContent: string): string[];
+/**
+ * Generates FHE API Reference markdown section (collapsible format)
+ */
+export declare function generateFHEApiSection(functions: string[], types: string[]): string;
 /**
  * Generates GitBook-compatible markdown documentation
  */

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

@@ -1 +1 @@
-{"version":3,"file":"generators.d.ts","sourceRoot":"","sources":["../../../scripts/shared/generators.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAWH;;GAEG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAiDvD;AAMD;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAkCjE;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,MAAM,EACnB,eAAe,EAAE,MAAM,EACvB,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,GACnB,MAAM,CA2BR;AAMD;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,WAAW,CAAC,EAAE,MAAM,EACpB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACvC,IAAI,CAiBN;AAMD;;GAEG;AACH,wBAAgB,UAAU,CACxB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,MAAM,CAAC,CA+BjB;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,EAAE,MAAM,GACV,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CA2B/C;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAchE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CA4B1D"}
+{"version":3,"file":"generators.d.ts","sourceRoot":"","sources":["../../../scripts/shared/generators.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAWH;;GAEG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAuDvD;AAMD;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAkCjE;AAgFD;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,eAAe,EAAE,MAAM,GAAG,MAAM,EAAE,CAUrE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,eAAe,EAAE,MAAM,GAAG,MAAM,EAAE,CASjE;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,EAAE,EACnB,KAAK,EAAE,MAAM,EAAE,GACd,MAAM,CAwBR;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,MAAM,EACnB,eAAe,EAAE,MAAM,EACvB,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,GACnB,MAAM,CAgCR;AAMD;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,WAAW,CAAC,EAAE,MAAM,EACpB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACvC,IAAI,CAiBN;AAMD;;GAEG;AACH,wBAAgB,UAAU,CACxB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,MAAM,CAAC,CAgCjB;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,EAAE,MAAM,GACV,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CA4B/C;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAchE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CA4B1D"}

package/dist/scripts/shared/generators.js

@@ -41,6 +41,9 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.cleanupTemplate = cleanupTemplate;
 exports.generateDeployScript = generateDeployScript;
+exports.extractFHEFunctions = extractFHEFunctions;
+exports.extractFHETypes = extractFHETypes;
+exports.generateFHEApiSection = generateFHEApiSection;
 exports.generateGitBookMarkdown = generateGitBookMarkdown;
 exports.updateProjectPackageJson = updateProjectPackageJson;
 exports.runCommand = runCommand;
@@ -93,6 +96,11 @@ function cleanupTemplate(outputDir) {
         fs.unlinkSync(oldTaskFile);
     }
     fs.writeFileSync(path.join(outputDir, "test", "types.ts"), utils_1.TEST_TYPES_CONTENT);
+    // Create .gitignore (npm ignores .gitignore files during publish)
+    const gitignorePath = path.join(outputDir, ".gitignore");
+    if (!fs.existsSync(gitignorePath)) {
+        fs.writeFileSync(gitignorePath, utils_1.GITIGNORE_CONTENT);
+    }
 }
 // =============================================================================
 // Code Generators
@@ -135,6 +143,121 @@ func.id = "deploy_${contractName.toLowerCase()}";
 func.tags = ["${contractName}"];
 `;
 }
+// =============================================================================
+// FHE API Reference (from @fhevm/solidity)
+// =============================================================================
+/** FHE Library Functions with developer-friendly descriptions */
+const FHE_FUNCTION_DESCRIPTIONS = {
+    // Type Conversion & Initialization
+    asEbool: "Encrypts a plaintext boolean into ebool",
+    asEuint8: "Encrypts a plaintext uint8 value into euint8",
+    asEuint16: "Encrypts a plaintext uint16 value into euint16",
+    asEuint32: "Encrypts a plaintext uint32 value into euint32",
+    asEuint64: "Encrypts a plaintext uint64 value into euint64",
+    asEuint128: "Encrypts a plaintext uint128 value into euint128",
+    asEuint256: "Encrypts a plaintext uint256 value into euint256",
+    asEaddress: "Encrypts a plaintext address into eaddress",
+    fromExternal: "Validates and converts external encrypted input using inputProof",
+    isInitialized: "Checks if an encrypted value has been set (handle != 0)",
+    // Arithmetic Operations
+    add: "Homomorphic addition: result = a + b (overflow wraps)",
+    sub: "Homomorphic subtraction: result = a - b (underflow wraps)",
+    mul: "Homomorphic multiplication: result = a * b",
+    div: "Homomorphic division: result = a / b (plaintext divisor only)",
+    rem: "Homomorphic remainder: result = a % b (plaintext divisor only)",
+    neg: "Homomorphic negation (two's complement)",
+    min: "Returns smaller of two encrypted values",
+    max: "Returns larger of two encrypted values",
+    // Comparison Operations (return ebool)
+    eq: "Encrypted equality: returns ebool(a == b)",
+    ne: "Encrypted inequality: returns ebool(a != b)",
+    gt: "Encrypted greater-than: returns ebool(a > b)",
+    lt: "Encrypted less-than: returns ebool(a < b)",
+    ge: "Encrypted greater-or-equal: returns ebool(a >= b)",
+    le: "Encrypted less-or-equal: returns ebool(a <= b)",
+    // Bitwise Operations
+    and: "Homomorphic bitwise AND",
+    or: "Homomorphic bitwise OR",
+    xor: "Homomorphic bitwise XOR",
+    not: "Homomorphic bitwise NOT",
+    shl: "Homomorphic shift left",
+    shr: "Homomorphic shift right",
+    rotl: "Homomorphic rotate left",
+    rotr: "Homomorphic rotate right",
+    // Conditional Logic
+    select: "Encrypted if-then-else: select(cond, a, b) → returns a if true, b if false",
+    // Random Number Generation
+    randEbool: "Generates random encrypted boolean",
+    randEuint8: "Generates random encrypted 8-bit integer",
+    randEuint16: "Generates random encrypted 16-bit integer",
+    randEuint32: "Generates random encrypted 32-bit integer",
+    randEuint64: "Generates random encrypted 64-bit integer",
+    randEuint128: "Generates random encrypted 128-bit integer",
+    randEuint256: "Generates random encrypted 256-bit integer",
+    // Access Control
+    allow: "Grants PERMANENT permission for address to decrypt/use value",
+    allowThis: "Grants contract permission to operate on ciphertext",
+    allowTransient: "Grants TEMPORARY permission (expires at tx end)",
+    isAllowed: "Checks if address has permission to use ciphertext",
+    isSenderAllowed: "Checks if msg.sender has permission",
+    // Decryption
+    makePubliclyDecryptable: "Marks ciphertext for public decryption via relayer",
+    isPubliclyDecryptable: "Checks if ciphertext is publicly decryptable",
+    checkSignatures: "Verifies KMS decryption proof (reverts if invalid)",
+    toBytes32: "Converts encrypted handle to bytes32 for proof arrays",
+    // Utility
+    cleanTransientStorage: "Clears transient permissions (for AA bundled UserOps)",
+};
+/**
+ * Extracts FHE function names used in contract
+ */
+function extractFHEFunctions(contractContent) {
+    const pattern = /FHE\.([a-zA-Z0-9]+)\s*[(<]/g;
+    const matches = new Set();
+    let match;
+    while ((match = pattern.exec(contractContent)) !== null) {
+        if (FHE_FUNCTION_DESCRIPTIONS[match[1]]) {
+            matches.add(match[1]);
+        }
+    }
+    return Array.from(matches).sort();
+}
+/**
+ * Extracts FHE types used in contract (from imports and declarations)
+ */
+function extractFHETypes(contractContent) {
+    const pattern = /\b(ebool|euint(?:8|16|32|64|128|256)|eaddress|externalEbool|externalEuint(?:8|16|32|64|128|256)|externalEaddress)\b/g;
+    const matches = new Set();
+    let match;
+    while ((match = pattern.exec(contractContent)) !== null) {
+        matches.add(match[1]);
+    }
+    return Array.from(matches).sort();
+}
+/**
+ * Generates FHE API Reference markdown section (collapsible format)
+ */
+function generateFHEApiSection(functions, types) {
+    if (functions.length === 0 && types.length === 0)
+        return "";
+    const totalCount = functions.length + types.length;
+    let section = `<details>\n`;
+    section += `<summary>🔐 FHE API Reference (${totalCount} items)</summary>\n\n`;
+    // Types
+    if (types.length > 0) {
+        section += `**Types:** ${types.map((t) => `\`${t}\``).join(" · ")}\n\n`;
+    }
+    // Functions as list
+    if (functions.length > 0) {
+        section += `**Functions:**\n`;
+        for (const f of functions) {
+            section += `- \`FHE.${f}()\` - ${FHE_FUNCTION_DESCRIPTIONS[f]}\n`;
+        }
+        section += `\n`;
+    }
+    section += `</details>\n\n`;
+    return section;
+}
 /**
  * Generates GitBook-compatible markdown documentation
  */
@@ -146,6 +269,10 @@ function generateGitBookMarkdown(description, contractContent, testContent, cont
     markdown += `- \`.ts\` file → \`<your-project-root-dir>/test/\`\n\n`;
     markdown += `This ensures Hardhat can compile and test your contracts as expected.\n`;
     markdown += `{% endhint %}\n\n`;
+    // Extract and add FHE API Reference section
+    const fheFunctions = extractFHEFunctions(contractContent);
+    const fheTypes = extractFHETypes(contractContent);
+    markdown += generateFHEApiSection(fheFunctions, fheTypes);
     markdown += `{% tabs %}\n\n`;
     markdown += `{% tab title="${contractName}.sol" %}\n\n`;
     markdown += `\`\`\`solidity\n`;
@@ -189,7 +316,8 @@ function updateProjectPackageJson(outputDir, projectName, description, npmDepend
  */
 function runCommand(cmd, args, cwd) {
     return new Promise((resolve, reject) => {
-        const child = (0, child_process_1.spawn)(cmd, args, {
+        const fullCommand = [cmd, ...args].join(" ");
+        const child = (0, child_process_1.spawn)(fullCommand, [], {
             cwd,
             shell: true,
             stdio: "pipe",
@@ -219,7 +347,8 @@ function runCommand(cmd, args, cwd) {
 function runCommandWithStatus(cmd, args, cwd) {
     return new Promise((resolve) => {
         let output = "";
-        const proc = (0, child_process_1.spawn)(cmd, args, {
+        const fullCommand = [cmd, ...args].join(" ");
+        const proc = (0, child_process_1.spawn)(fullCommand, [], {
             cwd,
             shell: true,
             stdio: ["ignore", "pipe", "pipe"],

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

@@ -12,6 +12,8 @@ export declare const TEMPLATE_DIR_NAME = "fhevm-hardhat-template";
 export declare const MAX_DESCRIPTION_LENGTH = 80;
 /** Directories to exclude when copying template */
 export declare const EXCLUDE_DIRS: string[];
+/** Gitignore content for scaffolded projects (npm ignores .gitignore during publish) */
+export declare const GITIGNORE_CONTENT = "# fhevm\nfhevmTemp\n\n# directories\n.coverage_artifacts\n.coverage_cache\n.coverage_contracts\nartifacts\nbuild\ncache\ncoverage\ndist\nnode_modules\ntypes\ndeployments\ntmp\n\n# files\n*.env\n*.log\n.DS_Store\n.pnp.*\ncoverage.json\npnpm-lock.yaml\nyarn.lock\n";
 /** FHEVM package versions for --add mode */
 export declare const FHEVM_DEPENDENCIES: {
     dependencies: {

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,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,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"}

package/dist/scripts/shared/utils.js

@@ -42,7 +42,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.log = exports.ERROR_MESSAGES = exports.TEST_TYPES_CONTENT = exports.CATEGORY_ORDER = exports.FHEVM_DEPENDENCIES = exports.EXCLUDE_DIRS = exports.MAX_DESCRIPTION_LENGTH = exports.TEMPLATE_DIR_NAME = exports.CATEGORY_ICON = void 0;
+exports.log = exports.ERROR_MESSAGES = exports.TEST_TYPES_CONTENT = exports.CATEGORY_ORDER = exports.FHEVM_DEPENDENCIES = exports.GITIGNORE_CONTENT = exports.EXCLUDE_DIRS = exports.MAX_DESCRIPTION_LENGTH = exports.TEMPLATE_DIR_NAME = exports.CATEGORY_ICON = void 0;
 exports.handleError = handleError;
 exports.getRootDir = getRootDir;
 exports.getTemplateDir = getTemplateDir;
@@ -74,6 +74,33 @@ exports.EXCLUDE_DIRS = [
     "dist",
     ".git",
 ];
+/** Gitignore content for scaffolded projects (npm ignores .gitignore during publish) */
+exports.GITIGNORE_CONTENT = `# fhevm
+fhevmTemp
+
+# directories
+.coverage_artifacts
+.coverage_cache
+.coverage_contracts
+artifacts
+build
+cache
+coverage
+dist
+node_modules
+types
+deployments
+tmp
+
+# files
+*.env
+*.log
+.DS_Store
+.pnp.*
+coverage.json
+pnpm-lock.yaml
+yarn.lock
+`;
 /** FHEVM package versions for --add mode */
 exports.FHEVM_DEPENDENCIES = {
     dependencies: {

package/package.json

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