create-fhevm-example 1.4.3 → 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/package.json

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