create-fhevm-example 1.4.2 → 1.4.4

package/contracts/gaming/EncryptedLottery.sol

@@ -13,23 +13,11 @@ import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 /**
  * @notice Encrypted Lottery with private ticket numbers - fair and verifiable!
  *
- * @dev Demonstrates FHE random selection and encrypted matching:
- *      - Players purchase tickets with encrypted numbers
- *      - Winning number generated using block randomness + FHE
- *      - Winners identified via FHE.eq without revealing ticket numbers
- *      - Only winner's ticket revealed at end
- *
- * Flow:
- * 1. Lottery created with ticket price and duration
- * 2. Players buy tickets with encrypted numbers
- * 3. Owner draws winning number at end
- * 4. Winners can claim prizes
- *
- * ⚠️ IMPORTANT: Block randomness is predictable - use VRF in production!
+ * @dev Flow: buyTicket() → startDrawing() → checkAndClaim() → revealWinner()
+ *      ⚡ Gas: Loop in checkAndClaim can be expensive with many tickets!
+ *      ⚠️ Block randomness is predictable - use VRF in production!
  */
 contract EncryptedLottery is ZamaEthereumConfig {
-    // ==================== TYPES ====================
-
     enum LotteryState {
         Open, // Accepting tickets
         Drawing, // Drawing in progress
@@ -41,9 +29,6 @@ contract EncryptedLottery is ZamaEthereumConfig {
         euint64 number;
     }
 
-    // ==================== STATE ====================
-
-    /// Lottery owner
     address public owner;
 
     /// Current lottery state
@@ -73,9 +58,7 @@ contract EncryptedLottery is ZamaEthereumConfig {
     /// Lottery round number
     uint256 public roundNumber;
 
-    // ==================== EVENTS ====================
-
-    /// @notice Emitted when a ticket is purchased
+    /// Emitted when a ticket is purchased
     /// @param buyer Address of ticket buyer
     /// @param ticketIndex Index of the ticket
     event TicketPurchased(address indexed buyer, uint256 indexed ticketIndex);
@@ -94,18 +77,11 @@ contract EncryptedLottery is ZamaEthereumConfig {
     /// @param rollover Amount rolled to next round
     event NoWinner(uint256 indexed roundNumber, uint256 rollover);
 
-    // ==================== MODIFIERS ====================
-
     modifier onlyOwner() {
         require(msg.sender == owner, "Only owner");
         _;
     }
 
-    // ==================== CONSTRUCTOR ====================
-
-    /// @notice Creates a new encrypted lottery
-    /// @param _ticketPrice Price per ticket in wei
-    /// @param _duration Duration in seconds
     constructor(uint256 _ticketPrice, uint256 _duration) {
         require(_ticketPrice > 0, "Ticket price must be > 0");
         require(_duration > 0, "Duration must be > 0");
@@ -117,9 +93,7 @@ contract EncryptedLottery is ZamaEthereumConfig {
         roundNumber = 1;
     }
 
-    // ==================== TICKET PURCHASE ====================
-
-    /// @notice Purchase a lottery ticket with an encrypted number
+    /// @notice Purchase a lottery ticket with encrypted number
     /// @param encryptedNumber Your encrypted ticket number
     /// @param inputProof Proof validating the encrypted input
     function buyTicket(
@@ -130,7 +104,7 @@ contract EncryptedLottery is ZamaEthereumConfig {
         require(block.timestamp < endTime, "Lottery ended");
         require(msg.value >= ticketPrice, "Insufficient payment");
 
-        // 🔐 Convert external encrypted input
+        // Convert and store encrypted ticket number
         euint64 ticketNumber = FHE.fromExternal(encryptedNumber, inputProof);
 
         // ✅ Grant contract permission
@@ -146,8 +120,6 @@ contract EncryptedLottery is ZamaEthereumConfig {
         emit TicketPurchased(msg.sender, ticketIndex);
     }
 
-    // ==================== DRAWING ====================
-
     /// @notice Start the drawing process
     /// @dev Only owner can call after lottery ends
     function startDrawing() external onlyOwner {
@@ -261,9 +233,6 @@ contract EncryptedLottery is ZamaEthereumConfig {
         // prizePool carries over if no winner
     }
 
-    // ==================== VIEW FUNCTIONS ====================
-
-    /// @notice Get total number of tickets sold
     function getTicketCount() external view returns (uint256) {
         return _tickets.length;
     }

package/contracts/gaming/EncryptedPoker.sol

@@ -13,23 +13,11 @@ import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 /**
  * @notice Encrypted Poker - Texas Hold'em with hidden hole cards!
  *
- * @dev Demonstrates multi-player FHE game mechanics:
- *      - Each player's hole cards remain encrypted until showdown
- *      - Hand strength computed via FHE without revealing cards
- *      - Winner determined by encrypted comparison
- *      - Only winning hand revealed, loser's cards stay private
- *
- * Simplified rules for demo:
- * - 2 players (heads-up)
- * - Cards encoded as 1-13 (Ace=1, King=13)
- * - Hand strength = card1 + card2 (simplified for demo)
- * - Higher total wins
- *
- * ⚠️ IMPORTANT: Production poker would need proper hand rankings!
+ * @dev Flow: joinGame() → bet()/fold() → showdown() → revealWinner()
+ *      Hand strength = card1 + card2 (simplified for demo)
+ *      ⚠️ Production needs proper hand rankings (flush, straight, etc.)
  */
 contract EncryptedPoker is ZamaEthereumConfig {
-    // ==================== TYPES ====================
-
     enum GameState {
         WaitingForPlayers, // Waiting for 2 players
         CardsDealt, // Both players have cards
@@ -47,8 +35,6 @@ contract EncryptedPoker is ZamaEthereumConfig {
         bool folded;
     }
 
-    // ==================== STATE ====================
-
     /// Game state
     GameState public state;
 
@@ -70,8 +56,6 @@ contract EncryptedPoker is ZamaEthereumConfig {
     /// Encrypted comparison result (true if player 0 wins)
     ebool private _player0Wins;
 
-    // ==================== EVENTS ====================
-
     /// @notice Emitted when a player joins
     /// @param player Address of joining player
     /// @param seat Seat number (0 or 1)
@@ -97,8 +81,6 @@ contract EncryptedPoker is ZamaEthereumConfig {
     /// @param pot Total pot won
     event GameWon(address indexed winner, uint256 pot);
 
-    // ==================== CONSTRUCTOR ====================
-
     /// @notice Creates a new poker game
     /// @param _minBet Minimum bet amount in wei
     constructor(uint256 _minBet) {
@@ -108,8 +90,6 @@ contract EncryptedPoker is ZamaEthereumConfig {
         state = GameState.WaitingForPlayers;
     }
 
-    // ==================== JOIN GAME ====================
-
     /// @notice Join the game with encrypted hole cards
     /// @param encCard1 First encrypted card (1-13)
     /// @param encCard2 Second encrypted card (1-13)
@@ -173,8 +153,6 @@ contract EncryptedPoker is ZamaEthereumConfig {
         emit PlayerJoined(msg.sender, seat);
     }
 
-    // ==================== BETTING ====================
-
     /// @notice Place a bet
     function bet() external payable {
         require(
@@ -220,8 +198,6 @@ contract EncryptedPoker is ZamaEthereumConfig {
         emit GameWon(winner, winnings);
     }
 
-    // ==================== SHOWDOWN ====================
-
     /// @notice Initiate showdown - compare hands using FHE
     function showdown() external {
         require(
@@ -276,8 +252,6 @@ contract EncryptedPoker is ZamaEthereumConfig {
         emit GameWon(winner, winnings);
     }
 
-    // ==================== RESET ====================
-
     /// @notice Reset for a new game
     function resetGame() external {
         require(state == GameState.Finished, "Game not finished");
@@ -290,8 +264,6 @@ contract EncryptedPoker is ZamaEthereumConfig {
         gameId++;
     }
 
-    // ==================== VIEW FUNCTIONS ====================
-
     /// @notice Get game info
     function getGameInfo()
         external
@@ -327,8 +299,6 @@ contract EncryptedPoker is ZamaEthereumConfig {
         return (_players[seat].card1, _players[seat].card2);
     }
 
-    // ==================== INTERNAL ====================
-
     function _getSeat(address player) internal view returns (uint8) {
         if (_players[0].addr == player) return 0;
         if (_players[1].addr == player) return 1;

package/contracts/gaming/RockPaperScissors.sol

@@ -1,39 +1,23 @@
 // SPDX-License-Identifier: BSD-3-Clause-Clear
 pragma solidity ^0.8.24;
 
-import {
-    FHE,
-    euint8,
-    ebool,
-    externalEuint8
-} from "@fhevm/solidity/lib/FHE.sol";
+import {FHE, euint8, ebool, externalEuint8} from "@fhevm/solidity/lib/FHE.sol";
 import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 
 /**
- * @notice Rock-Paper-Scissors game with encrypted moves - fair play guaranteed!
- *
- * @dev Demonstrates FHE commit-reveal pattern without trusted third party:
- *      - Players submit encrypted moves (0=Rock, 1=Paper, 2=Scissors)
- *      - FHE comparison determines winner without revealing moves
- *      - Loser's move revealed only after game concludes
- *
- * Move encoding: 0 = Rock, 1 = Paper, 2 = Scissors
- * Win logic: (move1 - move2 + 3) % 3 → 1 = player1 wins, 2 = player2 wins
- *
- * ⚠️ IMPORTANT: Uses FHE.rem for modulo - computationally expensive but secure
+ * @notice Rock-Paper-Scissors game with encrypted moves - fair play guaranteed using FHE!
+
+ * @dev Commit-reveal pattern without trusted third party.
+ *      Move encoding: 0=Rock, 1=Paper, 2=Scissors
+ *      ⚡ Gas: FHE.rem() is computationally expensive (~300k gas)
  */
 contract RockPaperScissors is ZamaEthereumConfig {
-    // ==================== TYPES ====================
-
     enum GameState {
         WaitingForPlayers, // 0 or 1 player joined
-        BothMoved,         // Both players submitted moves
-        Revealed           // Winner determined and revealed
+        BothMoved, // Both players submitted moves
+        Revealed // Winner determined and revealed
     }
 
-    // ==================== STATE ====================
-
-    /// Player 1 address
     address public player1;
 
     /// Player 2 address
@@ -52,9 +36,7 @@ contract RockPaperScissors is ZamaEthereumConfig {
     /// Game ID for tracking multiple games
     uint256 public gameId;
 
-    // ==================== EVENTS ====================
-
-    /// @notice Emitted when a player joins
+    /// Emitted when a player joins
     /// @param player Address of joining player
     /// @param playerNumber 1 or 2
     event PlayerJoined(address indexed player, uint8 playerNumber);
@@ -67,34 +49,29 @@ contract RockPaperScissors is ZamaEthereumConfig {
     /// @param gameId Current game ID
     event GameResult(address indexed winner, uint256 indexed gameId);
 
-    // ==================== CONSTRUCTOR ====================
-
-    /// @notice Creates a new Rock-Paper-Scissors game
     constructor() {
         gameId = 1;
         state = GameState.WaitingForPlayers;
     }
 
-    // ==================== PLAY FUNCTIONS ====================
-
     /// @notice Submit an encrypted move to play
     /// @dev Move must be 0 (Rock), 1 (Paper), or 2 (Scissors)
-    /// @param encryptedMove Encrypted move value (0-2)
     /// @param inputProof Proof validating the encrypted input
     function play(
         externalEuint8 encryptedMove,
         bytes calldata inputProof
     ) external {
-        require(state == GameState.WaitingForPlayers, "Game not accepting moves");
+        require(
+            state == GameState.WaitingForPlayers,
+            "Game not accepting moves"
+        );
         require(
             msg.sender != player1 && msg.sender != player2,
             "Already in this game"
         );
 
-        // 🔐 Convert external encrypted input to internal euint8
+        // Convert and validate encrypted move
         euint8 move = FHE.fromExternal(encryptedMove, inputProof);
-
-        // ✅ Grant contract permission to operate on this value
         FHE.allowThis(move);
 
         if (player1 == address(0)) {
@@ -117,31 +94,25 @@ contract RockPaperScissors is ZamaEthereumConfig {
     function determineWinner() external {
         require(state == GameState.BothMoved, "Not ready to determine winner");
 
-        // 🎯 Winner calculation using FHE
-        // Formula: (move1 - move2 + 3) % 3
-        // Result: 0 = tie, 1 = player1 wins, 2 = player2 wins
-
-        // Convert moves to computation: add 3 to avoid negative numbers
-        // move1 + 3 - move2 = (move1 - move2 + 3)
-        euint8 diff = FHE.add(FHE.add(_move1, FHE.asEuint8(3)), FHE.neg(_move2));
+        // Winner calculation: (move1 - move2 + 3) % 3
+        // 0=tie, 1=player1 wins, 2=player2 wins
+        euint8 diff = FHE.add(
+            FHE.add(_move1, FHE.asEuint8(3)),
+            FHE.neg(_move2)
+        );
 
-        // Modulo 3 to get result (0, 1, or 2)
+        // 🎲 Why rem? Modulo keeps result in 0-2 range (tie/p1 wins/p2 wins)
+        // ⚡ rem is expensive (~300k gas) - consider alternatives for production
         euint8 result = FHE.rem(diff, 3);
 
-        // 🔍 Check outcomes
+        // Compare results to determine outcome
         ebool isTie = FHE.eq(result, FHE.asEuint8(0));
         ebool player1Wins = FHE.eq(result, FHE.asEuint8(1));
 
-        // 📊 Encode winner as address bits (simplified for demo)
-        // In production, use public decryption pattern
-
-        // Make result publicly decryptable
+        // 🌐 Why makePubliclyDecryptable? Anyone can decrypt result with KMS proof
         FHE.allowThis(result);
         FHE.makePubliclyDecryptable(result);
 
-        // Store encrypted result for later reveal
-        // For this demo, we'll use select to pick winner
-
         state = GameState.Revealed;
 
         emit GameResult(address(0), gameId); // Placeholder - real winner after decryption
@@ -157,7 +128,10 @@ contract RockPaperScissors is ZamaEthereumConfig {
         require(state == GameState.Revealed, "Game not ready for reveal");
 
         // Build ciphertext list for verification
-        euint8 diff = FHE.add(FHE.add(_move1, FHE.asEuint8(3)), FHE.neg(_move2));
+        euint8 diff = FHE.add(
+            FHE.add(_move1, FHE.asEuint8(3)),
+            FHE.neg(_move2)
+        );
         euint8 result = FHE.rem(diff, 3);
 
         bytes32[] memory cts = new bytes32[](1);
@@ -193,16 +167,17 @@ contract RockPaperScissors is ZamaEthereumConfig {
         gameId++;
     }
 
-    // ==================== VIEW FUNCTIONS ====================
-
-    /// @notice Get current game state
-    function getGameState() external view returns (
-        address p1,
-        address p2,
-        GameState currentState,
-        address currentWinner,
-        uint256 currentGameId
-    ) {
+    function getGameState()
+        external
+        view
+        returns (
+            address p1,
+            address p2,
+            GameState currentState,
+            address currentWinner,
+            uint256 currentGameId
+        )
+    {
         return (player1, player2, state, winner, gameId);
     }
 

package/contracts/openzeppelin/VestingWallet.sol

@@ -12,19 +12,17 @@ import {
 } from "@openzeppelin/confidential-contracts/interfaces/IERC7984.sol";
 
 /**
- * @notice Linear vesting wallet for ERC7984 tokens - amounts stay encrypted!
- *
- * @dev Timeline: |--START--|---VESTING---|--END--|
- *                 0%        linear        100%
- *
- * All vesting calculations are performed on encrypted values using FHE operations.
+ * @notice Linear vesting wallet for ERC7984 tokens with fully encrypted amounts and schedules.
+
+ * @dev Timeline: |--START--|---VESTING---|--END--| (0% → linear → 100%)
+ *      All vesting calculations performed on encrypted values using FHE.
+ *      ⚡ Gas: FHE.div/mul operations are expensive (~200k gas each)
  */
 contract VestingWalletExample is
     Ownable,
     ReentrancyGuardTransient,
     ZamaEthereumConfig
 {
-    // 🔐 Track released amounts per token (encrypted)
     mapping(address token => euint128) private _tokenReleased;
     uint64 private _start;
     uint64 private _duration;
@@ -50,8 +48,6 @@ contract VestingWalletExample is
         _duration = durationSeconds;
     }
 
-    // ==================== VIEW FUNCTIONS ====================
-
     function start() public view virtual returns (uint64) {
         return _start;
     }
@@ -77,9 +73,7 @@ contract VestingWalletExample is
         euint128 vestedAmount_ = vestedAmount(token, uint48(block.timestamp));
         euint128 releasedAmount = released(token);
 
-        // 🔀 FHE.select: encrypted if-else
-        // If vested >= released: return (vested - released)
-        // Else: return 0
+        // Encrypted comparison: if vested >= released → return difference, else 0
         ebool canRelease = FHE.ge(vestedAmount_, releasedAmount);
         return
             FHE.select(
@@ -89,11 +83,10 @@ contract VestingWalletExample is
             );
     }
 
-    /// @notice Release vested tokens to beneficiary
     function release(address token) public virtual nonReentrant {
         euint64 amount = releasable(token);
 
-        // Transfer encrypted amount to owner
+        // Transfer encrypted amount using allowTransient (cheaper!)
         FHE.allowTransient(amount, token);
         euint64 amountSent = IERC7984(token).confidentialTransfer(
             owner(),
@@ -122,8 +115,6 @@ contract VestingWalletExample is
         return _vestingSchedule(totalAllocation, timestamp);
     }
 
-    // ==================== INTERNAL ====================
-
     /// @dev Linear vesting: (total * elapsed) / duration
     function _vestingSchedule(
         euint128 totalAllocation,
@@ -136,7 +127,7 @@ contract VestingWalletExample is
             // After end: 100% vested
             return totalAllocation;
         } else {
-            // During vesting: linear unlock
+            // ⚡ Gas warning: FHE.mul + FHE.div cost ~400k gas combined!
             return
                 FHE.div(
                     FHE.mul(totalAllocation, (timestamp - start())),

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,CAuDvD;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;
@@ -140,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
  */
@@ -151,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`;
@@ -194,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",
@@ -224,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/package.json

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