create-fhevm-example 1.4.3 → 1.4.5

package/contracts/advanced/PrivatePayroll.sol

@@ -10,26 +10,16 @@ import {
 import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 
 /**
- * @notice Private Payroll system - salaries stay encrypted, only employees see their own!
+ * @notice Confidential payroll system with encrypted salaries.
+ *         Employers can add employees with encrypted salary amounts. Each employee
+ *         can decrypt only their own salary - other salaries remain hidden.
+ *         Demonstrates selective decryption permissions where different users
+ *         see different encrypted values. Perfect for privacy-preserving HR systems.
  *
- * @dev Demonstrates confidential enterprise use case:
- *      - Employee salaries stored encrypted
- *      - Bulk payments without revealing individual amounts
- *      - Each employee can decrypt only their own salary
- *      - Total payroll visible to employer for budgeting
- *
- * Flow:
- * 1. Employer adds employees with encrypted salaries
- * 2. Employer funds the contract
- * 3. Employer calls payAll() to process all salaries
- * 4. Employees can view (decrypt) their own salary
- *
- * ⚠️ IMPORTANT: Uses cumulative encrypted sum for total payroll tracking
+ * @dev Flow: addEmployee() → fund() → processPayment()
+ *      Each employee can decrypt only their own salary.
  */
 contract PrivatePayroll is ZamaEthereumConfig {
-    // ==================== STATE ====================
-
-    /// Contract owner (employer)
     address public employer;
 
     /// List of employee addresses
@@ -50,9 +40,7 @@ contract PrivatePayroll is ZamaEthereumConfig {
     /// Payment period in seconds (default: 30 days)
     uint256 public paymentPeriod;
 
-    // ==================== EVENTS ====================
-
-    /// @notice Emitted when a new employee is added
+    /// Emitted when a new employee is added
     /// @param employee Address of the employee
     event EmployeeAdded(address indexed employee);
 
@@ -73,8 +61,6 @@ contract PrivatePayroll is ZamaEthereumConfig {
     /// @param amount Amount funded
     event ContractFunded(uint256 amount);
 
-    // ==================== MODIFIERS ====================
-
     modifier onlyEmployer() {
         require(msg.sender == employer, "Only employer");
         _;
@@ -85,10 +71,6 @@ contract PrivatePayroll is ZamaEthereumConfig {
         _;
     }
 
-    // ==================== CONSTRUCTOR ====================
-
-    /// @notice Creates a new private payroll contract
-    /// @param _paymentPeriod Time between payments in seconds
     constructor(uint256 _paymentPeriod) {
         employer = msg.sender;
         paymentPeriod = _paymentPeriod > 0 ? _paymentPeriod : 30 days;
@@ -96,8 +78,6 @@ contract PrivatePayroll is ZamaEthereumConfig {
         FHE.allowThis(_totalSalaries);
     }
 
-    // ==================== EMPLOYEE MANAGEMENT ====================
-
     /// @notice Add a new employee with encrypted salary
     /// @param employee Address of the employee
     /// @param encryptedSalary Encrypted salary amount
@@ -190,8 +170,6 @@ contract PrivatePayroll is ZamaEthereumConfig {
         emit EmployeeRemoved(employee);
     }
 
-    // ==================== PAYMENTS ====================
-
     /// @notice Fund the contract for payroll
     function fund() external payable onlyEmployer {
         require(msg.value > 0, "Must send funds");
@@ -231,9 +209,7 @@ contract PrivatePayroll is ZamaEthereumConfig {
         emit PaymentProcessed(employee, block.timestamp);
     }
 
-    // ==================== VIEW FUNCTIONS ====================
-
-    /// @notice Get encrypted salary handle for an employee
+    /// @notice Get encrypted salary handle for employee
     /// @dev Only callable by the employee themselves
     function getMySalary() external view onlyEmployee returns (euint64) {
         return _salaries[msg.sender];
@@ -276,8 +252,6 @@ contract PrivatePayroll is ZamaEthereumConfig {
         return (employees.length, address(this).balance, paymentPeriod);
     }
 
-    // ==================== RECEIVE ====================
-
     /// @notice Accept ETH deposits
     receive() external payable {
         emit ContractFunded(msg.value);

package/contracts/basic/decryption/PublicDecryptMultipleValues.sol

@@ -5,14 +5,16 @@ import {FHE, euint8} from "@fhevm/solidity/lib/FHE.sol";
 import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 
 /**
- * @notice Implements a simple 8-sided Die Roll game demonstrating public, permissionless decryption
+ * @notice Highest die roll game with public decryption of multiple values.
+ *         Two players roll encrypted 8-sided dice, results are made publicly
+ *         decryptable. Demonstrates handling multiple encrypted values in
+ *         checkSignatures() where ORDER MATTERS - the cts[] array must match
+ *         the order of values in the ABI-encoded result.
  *
- * @dev Uses FHE.makePubliclyDecryptable feature to allow anyone to decrypt the game results.
- *      Inherits from ZamaEthereumConfig to access FHE functions like FHE.randEuint8() and FHE.checkSignatures().
+ * @dev Uses FHE.randEuint8() + FHE.makePubliclyDecryptable() for both dice rolls.
+ *      ⚠️ Order matters in cts[] array for checkSignatures!
  */
 contract HighestDieRoll is ZamaEthereumConfig {
-    constructor() {}
-
     // Simple counter to assign a unique ID to each new game.
     uint256 private counter = 0;
 
@@ -31,7 +33,8 @@ contract HighestDieRoll is ZamaEthereumConfig {
     // Mapping to store all game states, accessible by a unique game ID.
     mapping(uint256 gameId => Game game) public games;
 
-    /// @notice Emitted when a new game is started, providing the encrypted handle required for decryption
+    /// @notice Emitted when a new game is started,
+    ///         providing the encrypted handle required for decryption
     /// @param gameId The unique identifier for the game
     /// @param playerA The address of playerA
     /// @param playerB The address of playerB
@@ -68,7 +71,8 @@ contract HighestDieRoll is ZamaEthereumConfig {
             revealed: false
         });
 
-        // We make the results publicly decryptable.
+        // 🌐 Both values marked for public decryption
+        // Anyone can decrypt with valid KMS proof
         FHE.makePubliclyDecryptable(playerAEncryptedDieRoll);
         FHE.makePubliclyDecryptable(playerBEncryptedDieRoll);
 
@@ -98,7 +102,8 @@ contract HighestDieRoll is ZamaEthereumConfig {
         return games[gameId].playerBEncryptedDieRoll;
     }
 
-    /// @notice Returns the address of the game winner. If the game is finalized, the function returns `address(0)`
+    /// @notice Returns the address of the game winner.
+    ///         If the game is finalized, the function returns `address(0)`
     /// @notice if the game is a draw.
     function getWinner(uint256 gameId) public view returns (address) {
         require(games[gameId].revealed, "Game winner not yet revealed");
@@ -110,8 +115,8 @@ contract HighestDieRoll is ZamaEthereumConfig {
         return games[gameId].revealed;
     }
 
-    /// @notice Verifies the provided (decryption proof, ABI-encoded clear values) pair against the stored ciphertext,
-    /// @notice and then stores the winner of the game.
+    /// @notice Verifies the provided (decryption proof, ABI-encoded clear values)
+    ///         pair against the stored ciphertext, and then stores the winner of the game.
     function recordAndVerifyWinner(
         uint256 gameId,
         bytes memory abiEncodedClearGameResult,
@@ -119,13 +124,7 @@ contract HighestDieRoll is ZamaEthereumConfig {
     ) public {
         require(!games[gameId].revealed, "Game already revealed");
 
-        // 1. FHE Verification: Build the list of ciphertexts (handles) and verify the proof.
-        //    The verification checks that 'abiEncodedClearGameResult' is the true decryption
-        //    of the '(playerAEncryptedDieRoll, playerBEncryptedDieRoll)' handle pair using
-        //    the provided 'decryptionProof'.
-
-        // Creating the list of handles in the right order! In this case the order does not matter since the proof
-        // only involves 1 single handle.
+        // Verify KMS proof - ORDER MATTERS!
         bytes32[] memory cts = new bytes32[](2);
         cts[0] = FHE.toBytes32(games[gameId].playerAEncryptedDieRoll);
         cts[1] = FHE.toBytes32(games[gameId].playerBEncryptedDieRoll);
@@ -133,9 +132,8 @@ contract HighestDieRoll is ZamaEthereumConfig {
         // This FHE call reverts the transaction if the decryption proof is invalid.
         FHE.checkSignatures(cts, abiEncodedClearGameResult, decryptionProof);
 
-        // 2. Decode the clear result and determine the winner's address.
-        //    In this very specific case, the function argument `abiEncodedClearGameResult` could have been replaced by two
-        //    `uint8` instead of an abi-encoded uint8 pair. In this case, we should have to compute abi.encode on-chain
+        // Decode both decrypted die rolls
+        // Note: Using abi.decode here, but could also accept two uint8 parameters
         (
             uint8 decodedClearPlayerADieRoll,
             uint8 decodedClearPlayerBDieRoll
@@ -153,7 +151,7 @@ contract HighestDieRoll is ZamaEthereumConfig {
                     : address(0)
             );
 
-        // 3. Store the revealed flag
+        // Store game result
         games[gameId].revealed = true;
         games[gameId].winner = winner;
     }

package/contracts/basic/decryption/PublicDecryptSingleValue.sol

@@ -5,14 +5,16 @@ import {FHE, ebool} from "@fhevm/solidity/lib/FHE.sol";
 import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 
 /**
- * @notice Implements a simple Heads or Tails game demonstrating public, permissionless decryption
+ * @notice Heads or Tails game with public, permissionless decryption.
+ *         Demonstrates makePubliclyDecryptable() which allows ANYONE to decrypt
+ *         the result (not just allowed users). Perfect for public game results,
+ *         lottery winners, or voting tallies. Uses FHE.randEbool() for fair
+ *         randomness and KMS-verified decryption proofs.
  *
- * @dev Uses FHE.makePubliclyDecryptable feature to allow anyone to decrypt the game results.
- *      Inherits from ZamaEthereumConfig to access FHE functions like FHE.randEbool() and FHE.checkSignatures().
+ * @dev Uses FHE.randEbool() for random result + FHE.makePubliclyDecryptable() for revealing.
+ *      Anyone can decrypt results with valid KMS proof.
  */
 contract HeadsOrTails is ZamaEthereumConfig {
-    constructor() {}
-
     /// Simple counter to assign a unique ID to each new game.
     uint256 private counter = 0;
 
@@ -29,7 +31,8 @@ contract HeadsOrTails is ZamaEthereumConfig {
     // Mapping to store all game states, accessible by a unique game ID.
     mapping(uint256 gameId => Game game) public games;
 
-    /// @notice Emitted when a new game is started, providing the encrypted handle required for decryption
+    /// @notice Emitted when a new game is started,
+    ///         providing the encrypted handle required for decryption
     /// @param gameId The unique identifier for the game
     /// @param headsPlayer The address choosing Heads
     /// @param tailsPlayer The address choosing Tails
@@ -66,7 +69,8 @@ contract HeadsOrTails is ZamaEthereumConfig {
             winner: address(0)
         });
 
-        // We make the result publicly decryptable.
+        // 🌐 Why makePubliclyDecryptable? Allows ANYONE to decrypt (not just allowed users)
+        // Use case: Public game results, lottery winners, voting tallies
         FHE.makePubliclyDecryptable(headsOrTailsResult);
 
         // You can catch the event to get the gameId and the encryptedHasHeadsWon handle
@@ -98,10 +102,11 @@ contract HeadsOrTails is ZamaEthereumConfig {
         return games[gameId].winner;
     }
 
-    /// @notice Verifies the provided (decryption proof, ABI-encoded clear value) pair against the stored ciphertext,
-    /// @notice and then stores the winner of the game.
+    /// @notice Verifies the provided (decryption proof, ABI-encoded clear value)
+    ///         pair against the stored ciphertext, and then stores the winner of the game.
     /// @dev gameId: The ID of the game to settle.
-    ///      abiEncodedClearGameResult: The ABI-encoded clear value (bool) associated to the `decryptionProof`.
+    ///      abiEncodedClearGameResult: The ABI-encoded clear value (bool)
+    ///                                 associated to the `decryptionProof`.
     ///      decryptionProof: The proof that validates the decryption.
     function recordAndVerifyWinner(
         uint256 gameId,
@@ -113,21 +118,15 @@ contract HeadsOrTails is ZamaEthereumConfig {
             "Game winner already revealed"
         );
 
-        // 1. FHE Verification: Build the list of ciphertexts (handles) and verify the proof.
-        //    The verification checks that 'abiEncodedClearGameResult' is the true decryption
-        //    of the 'encryptedHasHeadsWon' handle using the provided 'decryptionProof'.
-
-        // Creating the list of handles in the right order! In this case the order does not matter since the proof
-        // only involves 1 single handle.
+        // Verify KMS decryption proof
         bytes32[] memory cts = new bytes32[](1);
         cts[0] = FHE.toBytes32(games[gameId].encryptedHasHeadsWon);
 
         // This FHE call reverts the transaction if the decryption proof is invalid.
         FHE.checkSignatures(cts, abiEncodedClearGameResult, decryptionProof);
 
-        // 2. Decode the clear result and determine the winner's address.
-        //    In this very specific case, the function argument `abiEncodedClearGameResult` could have been a simple
-        //    `bool` instead of an abi-encoded bool. In this case, we should have compute abi.encode on-chain
+        // Decode the decrypted result to determine winner
+        // Note: Using abi.decode here, but could also accept plain bool parameter
         bool decodedClearGameResult = abi.decode(
             abiEncodedClearGameResult,
             (bool)
@@ -136,7 +135,7 @@ contract HeadsOrTails is ZamaEthereumConfig {
             ? games[gameId].headsPlayer
             : games[gameId].tailsPlayer;
 
-        // 3. Store the winner
+        // Store the winner
         games[gameId].winner = winner;
     }
 }

package/contracts/basic/decryption/UserDecryptMultipleValues.sol

@@ -5,33 +5,29 @@ import {FHE, ebool, euint32, euint64} from "@fhevm/solidity/lib/FHE.sol";
 import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 
 /**
- * @notice Demonstrates user decryption of multiple encrypted values
+ * @notice Decrypting multiple encrypted values of different types for a user.
+ *         Shows how to handle ebool, euint32, and euint64 in one contract.
+ *         Each value requires individual permission grants - there's no batching
+ *         for permissions (unlike input proofs). Demonstrates the pattern of
+ *         granting allowThis() for each value separately.
  *
- * @dev Shows how to create encrypted values from plaintext and grant permissions
- *      for multiple values of different types (ebool, euint32, euint64).
+ * @dev Each value needs separate permission grants (no batching).
+ *      ⚠️ Cannot batch permission grants - must call allow() for each value!
  */
 contract UserDecryptMultipleValues is ZamaEthereumConfig {
-    // 🔐 Multiple encrypted values of different types
     ebool private _encryptedBool;
     euint32 private _encryptedUint32;
     euint64 private _encryptedUint64;
 
-    constructor() {}
-
-    /// @notice Initialize multiple encrypted values from plaintext
-    /// @dev Uses FHE.asEuintX() to create encrypted constants from plaintext
-    ///      (The plaintext IS visible on-chain, but result is encrypted)
+    /// @notice Initialize multiple values from plaintext
+    /// @dev FHE.asEuintX() creates encrypted constants from plaintext
     function initialize(bool a, uint32 b, uint64 c) external {
-        // Create encrypted values from plaintext constants
-        // FHE.asEbool(a) encrypts a boolean value
+        // Create encrypted values from plaintext
         _encryptedBool = FHE.xor(FHE.asEbool(a), FHE.asEbool(false));
-
-        // FHE.asEuint32(b) + 1 creates an encrypted (b + 1)
         _encryptedUint32 = FHE.add(FHE.asEuint32(b), FHE.asEuint32(1));
         _encryptedUint64 = FHE.add(FHE.asEuint64(c), FHE.asEuint64(1));
 
-        // ⚠️ CRITICAL: Grant permissions for EACH value separately
-        // You cannot batch permission grants!
+        // ⚠️ Why separate? No batching for permissions - each needs individual allow()
         FHE.allowThis(_encryptedBool);
         FHE.allowThis(_encryptedUint32);
         FHE.allowThis(_encryptedUint64);
@@ -41,20 +37,14 @@ contract UserDecryptMultipleValues is ZamaEthereumConfig {
         FHE.allow(_encryptedUint64, msg.sender);
     }
 
-    /// @notice Returns the encrypted boolean value
-    /// @dev Client decrypts with: fhevm.userDecrypt(FhevmType.ebool, handle, ...)
     function encryptedBool() public view returns (ebool) {
         return _encryptedBool;
     }
 
-    /// @notice Returns the encrypted uint32 value
-    /// @dev Client decrypts with: fhevm.userDecrypt(FhevmType.euint32, handle, ...)
     function encryptedUint32() public view returns (euint32) {
         return _encryptedUint32;
     }
 
-    /// @notice Returns the encrypted uint64 value
-    /// @dev Client decrypts with: fhevm.userDecrypt(FhevmType.euint64, handle, ...)
     function encryptedUint64() public view returns (euint64) {
         return _encryptedUint64;
     }

package/contracts/basic/decryption/UserDecryptSingleValue.sol

@@ -5,54 +5,39 @@ import {FHE, euint32} from "@fhevm/solidity/lib/FHE.sol";
 import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 
 /**
- * @notice Demonstrates the FHE decryption mechanism and highlights common pitfalls
+ * @notice User-controlled decryption with proper permission management.
+ *         Demonstrates the critical two-step permission pattern: allowThis()
+ *         grants the contract permission to store/compute, while allow() grants
+ *         the user permission to decrypt. Missing either step causes decryption
+ *         to fail. Includes examples of both correct and incorrect patterns.
  *
- * @dev This trivial example shows correct vs incorrect permission granting patterns.
- *      Emphasizes that BOTH FHE.allowThis() and FHE.allow(user) are required for user decryption.
+ * @dev Shows CORRECT vs INCORRECT permission granting.
+ *      ⚠️ Both allowThis + allow required for user decryption!
  */
 contract UserDecryptSingleValue is ZamaEthereumConfig {
     euint32 private _trivialEuint32;
 
-    // solhint-disable-next-line no-empty-blocks
-    constructor() {}
-
-    /// @notice Initialize with a trivial formula (value + 1)
-    /// @dev Demonstrates correct permission granting
+    /// @notice ✅ CORRECT: Proper permission pattern
     function initializeUint32(uint32 value) external {
-        // Compute a trivial FHE formula _trivialEuint32 = value + 1
         _trivialEuint32 = FHE.add(FHE.asEuint32(value), FHE.asEuint32(1));
 
-        // Grant FHE permissions to:
-        // ✅ The contract caller (`msg.sender`): allows them to decrypt `_trivialEuint32`.
-        // ✅ The contract itself (`address(this)`): allows it to operate on `_trivialEuint32` and
-        //    also enables the caller to perform user decryption.
-        //
-        // Note: If you forget to call `FHE.allowThis(_trivialEuint32)`, the user will NOT be able
-        //       to user decrypt the value! Both the contract and the caller must have FHE permissions
-        //       for user decryption to succeed.
+        // 🔑 Why both needed?
+        // - allowThis: Contract authorizes releasing the value
+        // - allow: User can request decryption
         FHE.allowThis(_trivialEuint32);
         FHE.allow(_trivialEuint32, msg.sender);
     }
 
-    /// @notice Demonstrate INCORRECT permission granting (Anti-pattern)
-    /// @dev Missing FHE.allowThis() causes user decryption to fail
+    /// @notice ❌ WRONG: Missing allowThis causes decryption to FAIL!
+    /// @dev Common mistake - user gets permission but decryption still fails
     function initializeUint32Wrong(uint32 value) external {
-        // Compute a trivial FHE formula _trivialEuint32 = value + 1
         _trivialEuint32 = FHE.add(FHE.asEuint32(value), FHE.asEuint32(1));
 
-        // ❌ Common FHE permission mistake:
-        // ================================================================
-        // We grant FHE permissions to the contract caller (`msg.sender`),
-        // expecting they will be able to user decrypt the encrypted value later.
-        //
-        // However, this will fail! 💥
-        // The contract itself (`address(this)`) also needs FHE permissions to allow user decryption.
-        // Without granting the contract access using `FHE.allowThis(...)`,
-        // the user decryption attempt by the user will not succeed.
+        // ❌ Missing allowThis → user can't decrypt!
+        // Why? Decryption needs contract authorization to release
         FHE.allow(_trivialEuint32, msg.sender);
     }
 
-    /// @notice Returns the encrypted uint32 value
     function encryptedUint32() public view returns (euint32) {
         return _trivialEuint32;
     }

package/contracts/basic/encryption/EncryptMultipleValues.sol

@@ -13,41 +13,35 @@ import {
 import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 
 /**
- * @notice Encrypting and handling multiple values in a single transaction efficiently.
+ * @notice Efficient handling of multiple encrypted values in one transaction.
+ *         Demonstrates batched input validation where a single proof covers
+ *         multiple encrypted values (ebool, euint32, eaddress), saving ~50k gas
+ *         per additional value compared to separate proofs.
  *
- * @dev Supported encrypted types:
- *   - euint8/16/32/64/128/256: encrypted integers
- *   - ebool: encrypted boolean
- *   - eaddress: encrypted address
- *   - ebytes64/128/256: encrypted bytes
+ * @dev Demonstrates batched input (ONE proof for multiple values).
+ *      ⚡ Gas: Batching saves ~50k gas vs separate proofs!
  */
 contract EncryptMultipleValues is ZamaEthereumConfig {
-    // 🔐 Three different encrypted types stored together
-    ebool private _encryptedEbool; // e.g., vote, permission flag
-    euint32 private _encryptedEuint32; // e.g., amount, balance
-    eaddress private _encryptedEaddress; // e.g., hidden recipient
+    ebool private _encryptedEbool;
+    euint32 private _encryptedEuint32;
+    eaddress private _encryptedEaddress;
 
-    constructor() {}
-
-    /// @notice Store multiple encrypted values from a single batched input
-    /// @dev Client-side batching example:
-    ///   const input = await fhevm.createEncryptedInput(contractAddr, userAddr)
-    ///     .addBool(true).add32(123).addAddress(addr).encrypt();
-    ///   // This creates ONE proof for ALL values - more gas efficient!
+    /// @notice Store multiple encrypted values from single batched input
+    /// @dev Client creates ONE proof for ALL values using createEncryptedInput().
+    ///      Much cheaper than separate encrypt() calls!
     function initialize(
         externalEbool inputEbool,
         externalEuint32 inputEuint32,
         externalEaddress inputEaddress,
-        bytes calldata inputProof // Single proof covers all values
+        bytes calldata inputProof // Single proof covers all!
     ) external {
-        // Convert each external input to internal handle
+        // 💡 Why one proof? Client batches all values before encrypt()
+        // Saves ~50k gas per additional value!
         _encryptedEbool = FHE.fromExternal(inputEbool, inputProof);
         _encryptedEuint32 = FHE.fromExternal(inputEuint32, inputProof);
         _encryptedEaddress = FHE.fromExternal(inputEaddress, inputProof);
 
-        // ⚠️ IMPORTANT: Each value needs its own permission grants!
-        // You cannot batch permission grants
-
+        // 🔐 Each value needs own permissions (no batching here)
         FHE.allowThis(_encryptedEbool);
         FHE.allow(_encryptedEbool, msg.sender);
 

package/contracts/basic/encryption/EncryptSingleValue.sol

@@ -5,39 +5,37 @@ import {FHE, externalEuint32, euint32} from "@fhevm/solidity/lib/FHE.sol";
 import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 
 /**
- * @notice FHE encryption mechanism with single values, including common pitfalls and best practices for developers.
- *
+ * @notice Single value encryption with proof validation.
+ *         Shows how to receive encrypted data from users, validate proofs,
+ *         and grant proper permissions. Includes examples of common mistakes
+ *         and the correct permission pattern (allowThis + allow).
+
  * @dev Shows the complete flow: receiving encrypted input from user, validating proof,
  *      storing the encrypted value, and granting permissions for decryption.
  */
 contract EncryptSingleValue is ZamaEthereumConfig {
-    // 🔐 Stored encrypted - only authorized users can decrypt
     euint32 private _encryptedEuint32;
 
-    constructor() {}
-
     /// @notice Store an encrypted value submitted by the user
-    /// @dev inputEuint32: Encrypted value (created client-side with fhevm.createEncryptedInput())
-    ///      inputProof: Zero-knowledge proof that the encryption is valid
+    /// @dev inputProof ensures: value encrypted for THIS contract + THIS user.
+    ///      Prevents replay attacks from other contracts/users.
     function initialize(
         externalEuint32 inputEuint32,
         bytes calldata inputProof
     ) external {
-        // Convert external input to internal handle
-        // 📋 The proof ensures:
-        //    - Value was encrypted for THIS contract address
-        //    - Value was encrypted by THIS user (msg.sender)
-        //    - Prevents replay attacks from other contracts/users
+        // 🔐 Why proof?
+        // Prevents: replay attacks, wrong contract, invalid ciphertext
         _encryptedEuint32 = FHE.fromExternal(inputEuint32, inputProof);
 
-        // ⚠️ CRITICAL: Grant permissions for future decryption
-        // Without BOTH of these, user decryption will fail!
-        FHE.allowThis(_encryptedEuint32); // Contract can operate on it
-        FHE.allow(_encryptedEuint32, msg.sender); // User can decrypt it
+        // 🔑 Why both?
+        // - allowThis: Contract can store/compute with it
+        // - allow(user): User can decrypt it
+        FHE.allowThis(_encryptedEuint32);
+        FHE.allow(_encryptedEuint32, msg.sender);
     }
 
     /// @notice Returns the encrypted handle (not the actual value!)
-    /// @dev To decrypt, use fhevm.userDecryptEuint() on the client side
+    /// @dev To decrypt, use fhevm.userDecryptEuint32() on client side
     function encryptedUint32() public view returns (euint32) {
         return _encryptedEuint32;
     }

package/contracts/basic/encryption/FHECounter.sol

@@ -5,47 +5,49 @@ import {FHE, euint32, externalEuint32} from "@fhevm/solidity/lib/FHE.sol";
 import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 
 /**
- * @notice Confidential counter implementation using FHEVM, compared with a standard counter to highlight encryption benefits.
- *
- * @dev Demonstrates basic FHE operations: encryption, computation, and permission management.
- *      Shows how to work with encrypted values without ever revealing the underlying data.
+ * @notice Confidential counter with encrypted increment/decrement operations.
+ *         Demonstrates the complete FHE workflow: encryption, computation,
+ *         and permission management. The counter value remains private,
+ *         only accessible through decryption by authorized users.
+
+ * @dev Demonstrates basic FHE workflow: fromExternal() → compute → allow permissions.
+ *      All arithmetic happens on encrypted values without revealing the count.
  */
 contract FHECounter is ZamaEthereumConfig {
-    // 🔐 The count is always encrypted - no one can see the actual value
     euint32 private _count;
 
-    /// @notice Returns the encrypted count handle (not the actual value!)
     function getCount() external view returns (euint32) {
         return _count;
     }
 
-    /// @notice Increments the counter by an encrypted value
+    /// @notice Increments counter by encrypted amount
+    /// @dev Why allowThis + allow? Contract needs permission to store,
+    ///      user needs permission to decrypt. Both required!
     function increment(
         externalEuint32 inputEuint32,
         bytes calldata inputProof
     ) external {
-        // Convert external encrypted input to internal handle
-        // The proof is verified automatically
+        // 🔐 Why proof? Ensures valid ciphertext encrypted for THIS contract
         euint32 encryptedValue = FHE.fromExternal(inputEuint32, inputProof);
 
-        // Add encrypted values - computation happens on ciphertexts
-        // Neither the contract nor anyone else sees the actual numbers
+        // 🧮 Homomorphic add: works on encrypted data
         _count = FHE.add(_count, encryptedValue);
 
-        // ⚠️ CRITICAL: Both permissions required for user decryption!
-        FHE.allowThis(_count); // Contract can continue using this value
-        FHE.allow(_count, msg.sender); // Caller can decrypt it
+        // 🔑 Both needed: allowThis = contract stores, allow = user decrypts
+        FHE.allowThis(_count);
+        FHE.allow(_count, msg.sender);
     }
 
-    /// @notice Decrements the counter by an encrypted value
+    /// @notice Decrements counter by encrypted amount
+    /// @dev ⚠️ No underflow protection! FHE.sub wraps around at 0.
+    ///      ❌ WRONG: Checking result < 0 reveals information
+    ///      ✅ CORRECT: Use application-level balance tracking or FHE.select()
     function decrement(
         externalEuint32 inputEuint32,
         bytes calldata inputProof
     ) external {
         euint32 encryptedValue = FHE.fromExternal(inputEuint32, inputProof);
 
-        // Subtract encrypted values
-        // ⚠️ No underflow protection here - add checks in production!
         _count = FHE.sub(_count, encryptedValue);
 
         FHE.allowThis(_count);