create-fhevm-example 1.4.3 → 1.4.5

package/contracts/concepts/FHEHandles.sol

@@ -5,24 +5,22 @@ import {FHE, euint32, externalEuint32} from "@fhevm/solidity/lib/FHE.sol";
 import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 
 /**
- * @notice Understanding FHE handles: creation, computation, immutability, and symbolic execution in mock mode.
+ * @notice 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.
  *
- * @dev Handle = uint256 pointer to encrypted data stored by FHE coprocessor.
- *      Types: euint8/16/32/64/128/256, ebool, eaddress, ebytes64/128/256
+ * @dev Handle = uint256 pointer to encrypted data. Operations create NEW handles (immutable).
+ *      ⚡ Gas: asEuint32 ~20k, fromExternal ~50k, add/sub ~100k
  */
 contract FHEHandles is ZamaEthereumConfig {
-    // 🔐 Storage handles - persist across transactions
-    // These are just uint256 pointers, actual ciphertext is off-chain
     euint32 private _storedValue;
     euint32 private _computedValue;
 
     event HandleCreated(string operation, uint256 gasUsed);
     event HandleStored(string description);
 
-    constructor() {}
-
-    // ==================== HANDLE CREATION ====================
-
     /// @notice Pattern 1: Create handle from user's encrypted input
     function createFromExternal(
         externalEuint32 input,
@@ -30,8 +28,7 @@ contract FHEHandles is ZamaEthereumConfig {
     ) external {
         uint256 gasBefore = gasleft();
 
-        // 📥 FHE.fromExternal: converts external handle to internal handle
-        // The proof is verified automatically
+        // fromExternal: validates proof and creates internal handle
         _storedValue = FHE.fromExternal(input, inputProof);
 
         emit HandleCreated("fromExternal", gasBefore - gasleft());
@@ -45,8 +42,7 @@ contract FHEHandles is ZamaEthereumConfig {
     function createFromPlaintext(uint32 plaintextValue) external {
         uint256 gasBefore = gasleft();
 
-        // 📥 FHE.asEuint32: encrypts a public constant
-        // Use for: thresholds, comparison values, zero-initialization
+        // asEuint32: encrypts a public constant (visible on-chain!)
         _storedValue = FHE.asEuint32(plaintextValue);
 
         emit HandleCreated("asEuint32", gasBefore - gasleft());
@@ -55,23 +51,18 @@ contract FHEHandles is ZamaEthereumConfig {
         FHE.allow(_storedValue, msg.sender);
     }
 
-    // ==================== HANDLE COMPUTATION ====================
-
-    /// @notice Key insight: FHE operations create NEW handles
-    /// @dev Original handles are IMMUTABLE - they never change
+    /// @notice ⚠️ Key insight: FHE operations create NEW handles (immutable!)
     function computeNewHandle() external {
         uint256 gasBefore = gasleft();
 
         euint32 constant10 = FHE.asEuint32(10);
 
-        // 🔄 FHE.add creates a BRAND NEW handle
-        // _storedValue handle is UNCHANGED
-        // _computedValue gets the NEW handle
+        // 🔄 Why NEW handle? FHE values are immutable - operations always create new ones
         _computedValue = FHE.add(_storedValue, constant10);
 
         emit HandleCreated("add (new handle)", gasBefore - gasleft());
 
-        // ⚠️ Must grant permissions for the NEW handle!
+        // Must grant permissions for NEW handle
         FHE.allowThis(_computedValue);
         FHE.allow(_computedValue, msg.sender);
 
@@ -94,18 +85,14 @@ contract FHEHandles is ZamaEthereumConfig {
         FHE.allow(_computedValue, msg.sender);
     }
 
-    // ==================== HANDLE IMMUTABILITY ====================
-
-    /// @notice Demonstrates: updating a variable creates NEW handle
+    /// @notice Demonstrates: updating variable creates NEW handle
     function demonstrateImmutability()
         external
         returns (euint32 original, euint32 updated)
     {
-        // 📌 Save reference to current handle
         euint32 originalHandle = _storedValue;
 
-        // 🔄 This creates NEW handle, assigns to _storedValue
-        // originalHandle still points to OLD value!
+        // This creates NEW handle! originalHandle still points to OLD value
         _storedValue = FHE.add(_storedValue, FHE.asEuint32(100));
 
         FHE.allowThis(_storedValue);
@@ -116,8 +103,6 @@ contract FHEHandles is ZamaEthereumConfig {
         return (originalHandle, _storedValue);
     }
 
-    // ==================== GETTERS ====================
-
     function getStoredValue() external view returns (euint32) {
         return _storedValue;
     }

package/contracts/concepts/FHEInputProof.sol

@@ -11,68 +11,50 @@ import {
 import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 
 /**
- * @notice Explains input proof validation in FHEVM: what proofs are, why they are needed, and how to use them correctly with single and batched inputs.
+ * @notice 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.
  *
- * @dev Why proofs? They ensure:
- *      1. Ciphertext is valid (not garbage data)
- *      2. Value is in valid range for the type
- *      3. Sender knows the plaintext (proof of knowledge)
+ * @dev Proofs ensure: valid ciphertext + correct range + proof of knowledge.
+ *      ⚡ Gas: Batching multiple values in ONE proof saves ~50k gas vs separate proofs!
  */
 contract FHEInputProof is ZamaEthereumConfig {
     euint32 private _singleValue;
     euint32 private _valueA;
     euint64 private _valueB;
 
-    constructor() {}
-
-    // ==================== SINGLE INPUT ====================
-
     /// @notice Receive single encrypted value with proof
     function setSingleValue(
         externalEuint32 encryptedInput,
         bytes calldata inputProof
     ) external {
-        // 📥 FHE.fromExternal validates proof automatically
-        // If proof is invalid → transaction reverts
-        // Proof ensures:
-        //   ✓ Valid euint32 ciphertext
-        //   ✓ Encrypted for THIS contract
-        //   ✓ Sender knows the plaintext
+        // 🔐 Why proof needed? Prevents: garbage data, wrong type, replay attacks
         _singleValue = FHE.fromExternal(encryptedInput, inputProof);
 
         FHE.allowThis(_singleValue);
         FHE.allow(_singleValue, msg.sender);
     }
 
-    // ==================== MULTIPLE INPUTS (BATCHED) ====================
-
-    /// @notice Receive multiple encrypted values with SINGLE proof
-    /// @dev Client-side batching is more gas-efficient!
-    ///
-    /// Client code:
-    ///   const input = fhevm.createEncryptedInput(contractAddr, userAddr);
-    ///   input.add32(valueA);  // → handles[0]
-    ///   input.add64(valueB);  // → handles[1]
-    ///   const enc = await input.encrypt();
-    ///   // enc.inputProof covers BOTH values!
+    /// @notice Receive multiple values with SINGLE proof (gas efficient!)
+    /// @dev Client batches: input.add32(a).add64(b).encrypt() → one proof for both!
     function setMultipleValues(
         externalEuint32 inputA,
         externalEuint64 inputB,
-        bytes calldata inputProof // ← Single proof covers both!
+        bytes calldata inputProof // Single proof covers both!
     ) external {
-        // Both validated by same proof
+        // 💡 Same proof validates both - saves ~50k gas!
         _valueA = FHE.fromExternal(inputA, inputProof);
         _valueB = FHE.fromExternal(inputB, inputProof);
 
-        // ⚠️ Each value needs its own permission grants
+        // Each value needs own permissions
         FHE.allowThis(_valueA);
         FHE.allowThis(_valueB);
         FHE.allow(_valueA, msg.sender);
         FHE.allow(_valueB, msg.sender);
     }
 
-    // ==================== COMPUTATION WITH NEW INPUT ====================
-
     /// @notice Add new encrypted input to existing stored value
     function addToValue(
         externalEuint32 addend,
@@ -88,8 +70,6 @@ contract FHEInputProof is ZamaEthereumConfig {
         FHE.allow(_singleValue, msg.sender);
     }
 
-    // ==================== GETTERS ====================
-
     function getSingleValue() external view returns (euint32) {
         return _singleValue;
     }

package/contracts/gaming/EncryptedLottery.sol

@@ -11,25 +11,17 @@ import {
 import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 
 /**
- * @notice Encrypted Lottery with private ticket numbers - fair and verifiable!
+ * @notice Provably fair lottery with encrypted ticket numbers.
+ *         Players buy tickets with encrypted numbers. Winning number is generated
+ *         using FHE randomness. Winner is determined by comparing encrypted values
+ *         without revealing losing tickets. Ensures fairness and privacy - no one
+ *         can see ticket numbers before the draw.
  *
- * @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 +33,6 @@ contract EncryptedLottery is ZamaEthereumConfig {
         euint64 number;
     }
 
-    // ==================== STATE ====================
-
-    /// Lottery owner
     address public owner;
 
     /// Current lottery state
@@ -73,9 +62,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 +81,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 +97,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 +108,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 +124,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 +237,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

@@ -11,25 +11,17 @@ import {
 import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 
 /**
- * @notice Encrypted Poker - Texas Hold'em with hidden hole cards!
+ * @notice On-chain Texas Hold'em poker with encrypted hole cards.
+ *         Two players receive encrypted hole cards that remain hidden throughout
+ *         the game. Hand strength is computed using FHE operations. Winner is
+ *         determined by comparing encrypted hand strengths. Demonstrates complex
+ *         game logic with multiple encrypted states and conditional operations.
  *
- * @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 +39,6 @@ contract EncryptedPoker is ZamaEthereumConfig {
         bool folded;
     }
 
-    // ==================== STATE ====================
-
     /// Game state
     GameState public state;
 
@@ -70,8 +60,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 +85,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 +94,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 +157,6 @@ contract EncryptedPoker is ZamaEthereumConfig {
         emit PlayerJoined(msg.sender, seat);
     }
 
-    // ==================== BETTING ====================
-
     /// @notice Place a bet
     function bet() external payable {
         require(
@@ -220,8 +202,6 @@ contract EncryptedPoker is ZamaEthereumConfig {
         emit GameWon(winner, winnings);
     }
 
-    // ==================== SHOWDOWN ====================
-
     /// @notice Initiate showdown - compare hands using FHE
     function showdown() external {
         require(
@@ -276,8 +256,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 +268,6 @@ contract EncryptedPoker is ZamaEthereumConfig {
         gameId++;
     }
 
-    // ==================== VIEW FUNCTIONS ====================
-
     /// @notice Get game info
     function getGameInfo()
         external
@@ -327,8 +303,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,27 @@
 // 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 Fair Rock-Paper-Scissors game with encrypted moves.
+ *         Players submit encrypted moves (0=Rock, 1=Paper, 2=Scissors) ensuring
+ *         neither player can see the other's choice before committing. Winner is
+ *         determined using FHE operations and revealed publicly. No trusted third
+ *         party needed - cryptography guarantees fairness.
+
+ * @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 +40,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 +53,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 +98,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 +132,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 +171,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/ERC7984.sol

@@ -12,7 +12,12 @@ import {
 } from "@openzeppelin/confidential-contracts/token/ERC7984/ERC7984.sol";
 
 /**
- * @notice Confidential token using OpenZeppelin's ERC7984 standard
+ * @notice Confidential ERC20-compatible token using OpenZeppelin's ERC7984 standard.
+ *         Implements a fully private token where balances and transfer amounts
+ *         are encrypted. Compatible with standard ERC20 interfaces but with FHE
+ *         under the hood. Supports both visible minting (owner knows amount) and
+ *         confidential minting (fully private). Foundation for building private
+ *         DeFi applications.
  *
  * @dev Demonstrates minting and burning with both visible and encrypted amounts.
  *      Shows how to integrate FHE with standard token operations.

package/contracts/openzeppelin/ERC7984ERC20Wrapper.sol

@@ -9,7 +9,11 @@ import {
 } from "@openzeppelin/confidential-contracts/token/ERC7984/extensions/ERC7984ERC20Wrapper.sol";
 
 /**
- * @notice Wraps ERC20 tokens into confidential ERC7984 tokens
+ * @notice Bridge between public ERC20 and confidential ERC7984 tokens.
+ *         Allows users to wrap regular ERC20 tokens into privacy-preserving
+ *         ERC7984 tokens (public → private) and unwrap them back (private → public).
+ *         Wrapping is instant, unwrapping requires decryption proof from KMS.
+ *         Essential for bringing existing tokens into the confidential ecosystem.
  *
  * @dev WRAP: ERC20 → ERC7984 (public → private)
  *      UNWRAP: ERC7984 → ERC20 (private → public, requires decryption)

package/contracts/openzeppelin/SwapERC7984ToERC20.sol

@@ -12,7 +12,11 @@ import {
 import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 
 /**
- * @notice Swap confidential ERC7984 tokens to regular ERC20 tokens
+ * @notice Atomic swap from confidential ERC7984 to public ERC20 tokens.
+ *         Two-step process: (1) Initiate swap with encrypted amount, request
+ *         decryption from KMS. (2) Finalize swap with decryption proof, receive
+ *         ERC20 tokens. Demonstrates the FHEVM v0.9 public decryption flow with
+ *         makePubliclyDecryptable() and checkSignatures() for trustless swaps.
  *
  * @dev Uses FHEVM v0.9 decryption flow:
  *      FHE.makePubliclyDecryptable() + FHE.checkSignatures()

package/contracts/openzeppelin/SwapERC7984ToERC7984.sol

@@ -8,7 +8,11 @@ import {
 import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 
 /**
- * @notice Fully confidential swap between two ERC7984 tokens
+ * @notice Fully private atomic swap between two confidential ERC7984 tokens.
+ *         Both input and output amounts remain encrypted throughout the entire
+ *         swap process. No decryption needed - amounts stay private from start
+ *         to finish. Perfect for confidential DEX operations where trade sizes
+ *         must remain hidden. The ultimate privacy-preserving token exchange.
  *
  * @dev Both input and output amounts remain encrypted throughout the swap.
  */