create-fhevm-example 1.4.2 → 1.4.4

package/contracts/basic/decryption/PublicDecryptMultipleValues.sol

@@ -5,14 +5,12 @@ 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 8-sided die roll game demonstrating public decryption of multiple encrypted values.
  *
- * @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;
 
@@ -68,7 +66,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);
 
@@ -119,13 +118,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 +126,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 +145,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,12 @@ 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 Simple Heads or Tails game demonstrating public, permissionless decryption with FHE.
  *
- * @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;
 
@@ -66,7 +64,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
@@ -113,21 +112,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 +129,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,25 @@ 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 Demonstrates user decryption of multiple encrypted values with different types.
  *
- * @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 +33,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,35 @@ 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 Demonstrates FHE decryption mechanism and highlights the critical permission pattern.
  *
- * @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

@@ -15,39 +15,30 @@ import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 /**
  * @notice Encrypting and handling multiple values in a single transaction efficiently.
  *
- * @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,33 @@ 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 FHE encryption mechanism with single values, including common pitfalls and best practices.
+
  * @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

@@ -6,46 +6,45 @@ 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.
+
+ * @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);

package/contracts/basic/fhe-operations/FHEAdd.sol

@@ -5,21 +5,19 @@ import {FHE, euint8, externalEuint8} from "@fhevm/solidity/lib/FHE.sol";
 import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 
 /**
- * @notice Simple example: adding two encrypted values (a + b)
- *
- * @dev Demonstrates the most basic FHE operation and permission flow.
+ * @notice Simple example demonstrating addition of two encrypted values (a + b)
+
+ * @dev Shows the most basic FHE operation and permission flow.
+ *      ⚡ Gas: FHE.add() costs ~100k gas (coprocessor call)
  */
 contract FHEAdd is ZamaEthereumConfig {
     euint8 private _a;
     euint8 private _b;
     euint8 private _result;
 
-    constructor() {}
-
     /// @notice Set the first operand (encrypted)
     function setA(externalEuint8 inputA, bytes calldata inputProof) external {
         _a = FHE.fromExternal(inputA, inputProof);
-        // Only contract needs permission to use this for computation
         FHE.allowThis(_a);
     }
 
@@ -30,21 +28,17 @@ contract FHEAdd is ZamaEthereumConfig {
     }
 
     /// @notice Compute a + b on encrypted values
-    /// @dev The contract computes on ciphertexts - it never sees actual values!
+    /// @dev Contract operates on ciphertexts - never sees actual values!
     function computeAPlusB() external {
-        // 🔐 Addition on encrypted values
-        // Neither the contract nor anyone else knows what a, b, or result are
+        // 🧮 Homomorphic: operates on encrypted data without decrypting
         _result = FHE.add(_a, _b);
 
-        // 📋 PERMISSION FLOW:
-        // During this function, contract has "ephemeral" permission on _result
-        // When function ends, ephemeral permission is revoked
-        // We need PERMANENT permissions for future access:
-        FHE.allowThis(_result); // Contract can use result later
-        FHE.allow(_result, msg.sender); // Caller can decrypt result
+        // 🔑 Why both? allowThis = contract can use it, allow = user can decrypt
+        FHE.allowThis(_result);
+        FHE.allow(_result, msg.sender);
     }
 
-    /// @notice Returns the encrypted result
+    /// @notice Returns the encrypted result handle
     function result() public view returns (euint8) {
         return _result;
     }

package/contracts/basic/fhe-operations/FHEArithmetic.sol

@@ -5,93 +5,77 @@ import {FHE, euint32, externalEuint32} from "@fhevm/solidity/lib/FHE.sol";
 import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 
 /**
- * @notice Demonstrates all FHE arithmetic operations on encrypted integers
+ * @notice Demonstrates all FHE arithmetic operations: add, sub, mul, div, rem, min, max
  *
- * @dev This contract shows how to perform mathematical operations on encrypted values
- *      without ever revealing the underlying data.
- *
- * Available operations:
- * - FHE.add(a, b)  : Addition
- * - FHE.sub(a, b)  : Subtraction
- * - FHE.mul(a, b)  : Multiplication
- * - FHE.div(a, b)  : Division (integer)
- * - FHE.rem(a, b)  : Remainder (modulo)
- * - FHE.min(a, b)  : Minimum of two values
- * - FHE.max(a, b)  : Maximum of two values
+ * @dev ⚡ Gas costs vary: add/sub (~100k) < mul (~150k) < div/rem (~300k)
+ *      ⚠️ div/rem only work with plaintext divisor (not encrypted!)
  */
 contract FHEArithmetic is ZamaEthereumConfig {
     euint32 private _a;
     euint32 private _b;
     euint32 private _result;
 
-    // solhint-disable-next-line no-empty-blocks
-    constructor() {}
-
-    /// @notice Sets the first operand (encrypted)
     function setA(externalEuint32 inputA, bytes calldata inputProof) external {
         _a = FHE.fromExternal(inputA, inputProof);
         FHE.allowThis(_a);
     }
 
-    /// @notice Sets the second operand (encrypted)
     function setB(externalEuint32 inputB, bytes calldata inputProof) external {
         _b = FHE.fromExternal(inputB, inputProof);
         FHE.allowThis(_b);
     }
 
-    /// @notice Computes encrypted addition: result = a + b
+    /// @notice Encrypted addition: result = a + b
     function computeAdd() external {
         _result = FHE.add(_a, _b);
         _grantPermissions();
     }
 
-    /// @notice Computes encrypted subtraction: result = a - b
-    /// @dev No underflow protection - in production, add range checks
+    /// @notice Encrypted subtraction: result = a - b
+    /// @dev ⚠️ No underflow protection! Wraps around at 0.
     function computeSub() external {
         _result = FHE.sub(_a, _b);
         _grantPermissions();
     }
 
-    /// @notice Computes encrypted multiplication: result = a * b
-    /// @dev No overflow protection - in production, add range checks
+    /// @notice Encrypted multiplication: result = a * b
+    /// @dev ⚠️ No overflow protection! May wrap at type max.
     function computeMul() external {
         _result = FHE.mul(_a, _b);
         _grantPermissions();
     }
 
-    /// @notice Computes encrypted division: result = a / b (scalar)
-    /// @dev Divisor must be a scalar (plaintext) because FHE division by encrypted value is not supported.
+    /// @notice Encrypted division: result = a / divisor
+    /// @dev ❌ WRONG: FHE.div(encryptedA, encryptedB) - not supported!
+    ///      ✅ CORRECT: FHE.div(encryptedA, plaintextB)
     function computeDiv(uint32 divisor) external {
         _result = FHE.div(_a, divisor);
         _grantPermissions();
     }
 
-    /// @notice Computes encrypted remainder: result = a % b (scalar)
-    /// @dev Divisor must be a scalar (plaintext).
+    /// @notice Encrypted remainder: result = a % modulus
+    /// @dev Modulus must be plaintext (same limitation as div)
     function computeRem(uint32 modulus) external {
         _result = FHE.rem(_a, modulus);
         _grantPermissions();
     }
 
-    /// @notice Computes encrypted minimum: result = min(a, b)
+    /// @notice Encrypted minimum: result = min(a, b)
     function computeMin() external {
         _result = FHE.min(_a, _b);
         _grantPermissions();
     }
 
-    /// @notice Computes encrypted maximum: result = max(a, b)
+    /// @notice Encrypted maximum: result = max(a, b)
     function computeMax() external {
         _result = FHE.max(_a, _b);
         _grantPermissions();
     }
 
-    /// @notice Returns the encrypted result
-    /// @dev Caller must have FHE permissions to decrypt
     function getResult() public view returns (euint32) {
         return _result;
     }
 
-    /// @dev Grants FHE permissions to contract and caller for decryption
     function _grantPermissions() internal {
         FHE.allowThis(_result);
         FHE.allow(_result, msg.sender);