create-fhevm-example 1.4.8 → 1.5.0

package/contracts/advanced/BlindAuction.sol

@@ -10,15 +10,12 @@ import {
 import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 
 /**
- * @notice Blind auction where bids remain encrypted until the end.
- *         Bidders submit encrypted amounts. The contract finds the highest bid
- *         using FHE.gt and FHE.select without ever decrypting losing bids.
- *         Only the winning bid amount is revealed after the auction closes.
- *         Losing bids remain private forever, ensuring true bid confidentiality.
+ * @notice Blind auction where bids remain fully encrypted until the end.
+ *         Uses FHE.gt/select to find the winner without decrypting losing bids.
+ *         Only the winning amount is revealed after the auction closes.
 
  * @dev Flow: bid() → endAuction() → revealWinner()
  *      Uses FHE.gt/select to find winner without revealing losing bids.
- *      Losing bids remain encrypted forever!
  */
 contract BlindAuction is ZamaEthereumConfig {
     enum AuctionState {

package/contracts/advanced/EncryptedEscrow.sol

@@ -10,14 +10,11 @@ import {
 import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 
 /**
- * @notice Confidential escrow service with hidden transaction amounts.
- *         Buyer and seller agree on encrypted escrow amount. Funds are held
- *         securely until conditions are met. Amount remains hidden from public
- *         view until release or refund. Includes arbiter for dispute resolution.
- *         Perfect for high-value transactions requiring privacy.
+ * @notice Confidential escrow service with hidden transaction amounts and arbiters.
+ *         Secures funds with encrypted amounts. Details remain hidden until
+ *         release or refund, supporting multi-party dispute resolution.
  *
  * @dev Flow: createEscrow() → fundEscrow() → release()/requestRefund()/raiseDispute()
- *      Multi-party agreement with arbiter for disputes.
  */
 contract EncryptedEscrow is ZamaEthereumConfig {
     enum EscrowState {

package/contracts/advanced/HiddenVoting.sol

@@ -5,11 +5,9 @@ import {FHE, euint64, ebool, externalEuint8} from "@fhevm/solidity/lib/FHE.sol";
 import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 
 /**
- * @notice Private voting system with homomorphic vote tallying.
- *         Voters submit encrypted ballots (Yes/No). Votes are tallied using
- *         homomorphic addition WITHOUT decrypting individual ballots. Only the
- *         final tally is revealed - individual votes remain private forever.
- *         Perfect for DAO governance, elections, or any scenario requiring ballot secrecy.
+ * @notice Private voting system with homomorphic vote tallying (Yes/No).
+ *         Ballots are added without decryption. Only final totals are revealed,
+ *         ensuring individual vote secrecy forever.
  *
  * @dev Flow: vote() → closeVoting() → revealResults()
  *      ⚡ Gas: Each vote costs ~200k gas (FHE.add + FHE.select operations)
@@ -118,6 +116,7 @@ contract HiddenVoting is ZamaEthereumConfig {
         );
         _noVotes = FHE.add(_noVotes, noIncrement);
 
+        FHE.allowThis(_yesVotes);
         FHE.allowThis(_noVotes);
 
         hasVoted[msg.sender] = true;

package/contracts/advanced/PrivateKYC.sol

@@ -12,16 +12,11 @@ import {
 import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 
 /**
- * @notice Privacy-preserving identity verification using predicate proofs.
- *         Users submit encrypted personal data (age, country, credit score).
- *         Contract can verify predicates like "Is user 18+?" or "Good credit?"
- *         without learning the actual values. Returns encrypted booleans that
- *         prove compliance without revealing sensitive information. Revolutionary
- *         for KYC/AML compliance while preserving user privacy.
+ * @notice Privacy-preserving KYC using encrypted predicate proofs (e.g., 18+ check).
+ *         Users submit encrypted data. The contract verifies compliance without
+ *         learning actual values, returning encrypted booleans.
  *
  * @dev Flow: submitKYC() → verifyAge18()/verifyGoodCredit()/etc.
- *      Returns encrypted booleans: "Is 18+?", "Good credit?" without revealing actual values.
- *      ⚠️ Production KYC needs trusted attesters!
  */
 contract PrivateKYC is ZamaEthereumConfig {
     struct Identity {

package/contracts/advanced/PrivatePayroll.sol

@@ -10,11 +10,9 @@ import {
 import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 
 /**
- * @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.
+ * @notice Confidential payroll system with encrypted salaries and selective access.
+ *         Employers manage employees with hidden salaries. Only the owner and the
+ *         respective employee can access specific salary data.
  *
  * @dev Flow: addEmployee() → fund() → processPayment()
  *      Each employee can decrypt only their own salary.

package/contracts/basic/decryption/PublicDecryptMultipleValues.sol

@@ -5,14 +5,11 @@ import {FHE, euint8} from "@fhevm/solidity/lib/FHE.sol";
 import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 
 /**
- * @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.
+ * @notice Dice game demonstrating public decryption of multiple encrypted values.
+ *         Shows how to use checkSignatures() with multiple values, highlighting
+ *         that the order in cts[] must match the ABI-encoded results.
  *
- * @dev Uses FHE.randEuint8() + FHE.makePubliclyDecryptable() for both dice rolls.
- *      ⚠️ Order matters in cts[] array for checkSignatures!
+ * @dev Uses FHE.randEuint8() and FHE.makePubliclyDecryptable().
  */
 contract HighestDieRoll is ZamaEthereumConfig {
     // Simple counter to assign a unique ID to each new game.

package/contracts/basic/decryption/PublicDecryptSingleValue.sol

@@ -6,13 +6,10 @@ import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 
 /**
  * @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.
+ *         Demonstrates FHE.makePubliclyDecryptable(), allowing any user to
+ *         decrypt results like game outcomes or voting tallies using KMS proofs.
  *
- * @dev Uses FHE.randEbool() for random result + FHE.makePubliclyDecryptable() for revealing.
- *      Anyone can decrypt results with valid KMS proof.
+ * @dev Uses FHE.randEbool() and FHE.makePubliclyDecryptable().
  */
 contract HeadsOrTails is ZamaEthereumConfig {
     /// Simple counter to assign a unique ID to each new game.

package/contracts/basic/decryption/UserDecryptMultipleValues.sol

@@ -5,14 +5,11 @@ import {FHE, ebool, euint32, euint64} from "@fhevm/solidity/lib/FHE.sol";
 import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 
 /**
- * @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.
+ * @notice Decrypting multiple encrypted values (ebool, euint32, euint64) for a user.
+ *         Highlights that each value requires individual permission grants,
+ *         as there is no batching for FHE.allow() or FHE.allowThis().
  *
- * @dev Each value needs separate permission grants (no batching).
- *      ⚠️ Cannot batch permission grants - must call allow() for each value!
+ * @dev Individual permissions are required for each encrypted value.
  */
 contract UserDecryptMultipleValues is ZamaEthereumConfig {
     ebool private _encryptedBool;

package/contracts/basic/decryption/UserDecryptSingleValue.sol

@@ -5,14 +5,11 @@ import {FHE, euint32} from "@fhevm/solidity/lib/FHE.sol";
 import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 
 /**
- * @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.
+ * @notice User-controlled decryption with mandatory two-step permissions.
+ *         Demonstrates the pattern: allowThis() for contract storage/computation
+ *         and allow() for user decryption, illustrating correct vs incorrect usage.
  *
- * @dev Shows CORRECT vs INCORRECT permission granting.
- *      ⚠️ Both allowThis + allow required for user decryption!
+ * @dev Both allowThis and allow are required for successful user decryption.
  */
 contract UserDecryptSingleValue is ZamaEthereumConfig {
     euint32 private _trivialEuint32;

package/contracts/basic/encryption/EncryptMultipleValues.sol

@@ -13,13 +13,11 @@ import {
 import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 
 /**
- * @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.
+ * @notice Efficient handling of multiple encrypted values via batched inputs.
+ *         Uses a single proof for multiple values (ebool, euint32, eaddress),
+ *         saving significant gas compared to separate proofs.
  *
- * @dev Demonstrates batched input (ONE proof for multiple values).
- *      ⚡ Gas: Batching saves ~50k gas vs separate proofs!
+ * @dev Batching saves ~50k gas per additional value.
  */
 contract EncryptMultipleValues is ZamaEthereumConfig {
     ebool private _encryptedEbool;

package/contracts/basic/encryption/FHECounter.sol

@@ -6,12 +6,10 @@ import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 
 /**
  * @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.
+ *         Demonstrates the FHE workflow: encryption, computation, and permission
+ *         management while keeping the counter value private.
 
- * @dev Demonstrates basic FHE workflow: fromExternal() → compute → allow permissions.
- *      All arithmetic happens on encrypted values without revealing the count.
+ * @dev Workflow: fromExternal (validation) → arithmetic → permissions.
  */
 contract FHECounter is ZamaEthereumConfig {
     euint32 private _count;

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

@@ -6,13 +6,10 @@ import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 
 /**
  * @notice Introduction to homomorphic addition on encrypted values.
- *         Demonstrates the most fundamental FHE operation: adding two encrypted
- *         numbers without decrypting them. Shows the complete flow from receiving
- *         encrypted inputs, performing the addition, and granting permissions
- *         for both contract storage and user decryption.
+ *         Demonstrates adding two encrypted numbers without decryption, including
+ *         input handling, addition, and permission management.
 
- * @dev Shows the most basic FHE operation and permission flow.
- *      ⚡ Gas: FHE.add() costs ~100k gas (coprocessor call)
+ * @dev Shows the basic FHE operation and permission flow (FHE.add ~100k gas).
  */
 contract FHEAdd is ZamaEthereumConfig {
     euint8 private _a;

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

@@ -5,14 +5,11 @@ import {FHE, euint32, externalEuint32} from "@fhevm/solidity/lib/FHE.sol";
 import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 
 /**
- * @notice Complete suite of FHE arithmetic operations on encrypted values.
- *         Covers all basic math: addition, subtraction, multiplication, division,
- *         remainder (modulo), minimum, and maximum. Includes gas cost comparisons
- *         and important limitations (e.g., division/remainder only work with
- *         plaintext divisors, not encrypted divisors).
+ * @notice FHE arithmetic (add, sub, mul, div, rem, min, max) on encrypted values.
+ *         Includes gas cost comparisons and key limitations, such as plaintext
+ *         divisors for division and remainder operations.
  *
- * @dev ⚡ Gas costs vary: add/sub (~100k) < mul (~150k) < div/rem (~300k)
- *      ⚠️ div/rem only work with plaintext divisor (not encrypted!)
+ * @dev div/rem only work with plaintext divisors (not encrypted).
  */
 contract FHEArithmetic is ZamaEthereumConfig {
     euint32 private _a;

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

@@ -10,15 +10,11 @@ import {
 import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 
 /**
- * @notice Complete guide to encrypted comparisons and conditional selection.
- *         Covers all comparison operators (eq, ne, gt, lt, ge, le) that return
- *         encrypted booleans (ebool), and demonstrates FHE.select for branching
- *         without information leakage. Critical for implementing logic like
- *         "find maximum" or "check threshold" without revealing values.
+ * @notice Encrypted comparisons (eq, ne, gt, lt, ge, le) and conditional selection.
+ *         Demonstrates FHE.select for branching without information leakage,
+ *         essential for "find maximum" or threshold logic.
  *
- * @dev Results are encrypted booleans (ebool) - comparisons reveal nothing!
- *      ⚡ Gas: Comparisons ~100k, select ~120k
- *      ❌ WRONG: if (FHE.gt(a,b)) → decrypts! ✅ CORRECT: FHE.select()
+ * @dev Comparisons return ebool; select avoids revealing values during branching.
  */
 contract FHEComparison is ZamaEthereumConfig {
     euint32 private _a;

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

@@ -5,14 +5,11 @@ import {FHE, ebool, euint8, externalEuint8} from "@fhevm/solidity/lib/FHE.sol";
 import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 
 /**
- * @notice Conditional logic without information leakage using FHE.select.
- *         Demonstrates how to implement if-then-else logic on encrypted values
- *         (computing max of two numbers). Using regular if/else would decrypt
- *         and leak which branch was taken. FHE.select evaluates BOTH branches
- *         and picks one based on the encrypted condition, preserving privacy.
+ * @notice Conditional logic using FHE.select for privacy-preserving branching.
+ *         Demonstrates if-then-else logic on encrypted values. Unlike regular
+ *         if/else, FHE.select avoids information leakage by evaluating both branches.
  *
- * @dev ❌ Can't use if/else (leaks info!) ✅ Use FHE.select instead
- *      ⚡ Gas: ~120k for select operation
+ * @dev Evaluates both branches using encrypted conditions (FHE.select ~120k gas).
  */
 contract FHEIfThenElse is ZamaEthereumConfig {
     euint8 private _a;

package/contracts/concepts/antipatterns/ControlFlow.sol

@@ -11,12 +11,10 @@ import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 
 /**
  * @notice Control flow anti-patterns in FHE development.
- *         Demonstrates common mistakes when using conditional logic
- *         and loops with encrypted values.
+ *         Demonstrates mistakes with conditional logic and loops on encrypted
+ *         values, providing correct vs incorrect implementations.
  *
- * @dev Covers 3 critical patterns: if/else branching, require statements,
- *      and encrypted loop iterations.
- *      Each shows ❌ WRONG and ✅ CORRECT implementations.
+ * @dev Covers if/else branching, require statements, and encrypted loops.
  */
 contract FHEControlFlowAntiPatterns is ZamaEthereumConfig {
     euint32 private _secretBalance;

package/contracts/concepts/antipatterns/OperationsGasNoise.sol

@@ -11,11 +11,10 @@ import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 
 /**
  * @notice Operations, gas, and noise anti-patterns in FHE development.
- *         Demonstrates performance issues, side-channel leaks, and
- *         inefficient encrypted computation patterns.
+ *         Covers performance issues, side-channel leaks, noise accumulation,
+ *         and inefficient encrypted computation patterns.
  *
- * @dev Covers 4 patterns: gas/timing side channels, noise accumulation,
- *      deprecated APIs, and type mismatches.
+ * @dev Explores timing side channels, noise, deprecated APIs, and type mismatches.
  */
 contract FHEOperationsGasNoiseAntiPatterns is ZamaEthereumConfig {
     euint32 private _secretValue;
@@ -117,16 +116,16 @@ contract FHEOperationsGasNoiseAntiPatterns is ZamaEthereumConfig {
     // ═══════════════════════════════════════════════════════════════════════
 
     /**
-     * ❌ WRONG: Using old TFHE.decrypt() pattern
+     * ❌ WRONG: Using old FHE.decrypt() pattern
      * @dev Deprecated in FHEVM v0.9+
      */
     function wrongDeprecatedAPI() external pure returns (string memory) {
         // ❌ OLD (v0.8 and earlier):
-        // TFHE.decrypt() - went through Zama Oracle
+        // FHE.decrypt() - went through Zama Oracle
         //
         // This pattern is deprecated and no longer supported
 
-        return "Don't use TFHE.decrypt() - it's deprecated";
+        return "Don't use FHE.decrypt() - it's deprecated";
     }
 
     /**

package/contracts/concepts/antipatterns/Permissions.sol

@@ -6,12 +6,10 @@ import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 
 /**
  * @notice Permission management anti-patterns in FHE development.
- *         Demonstrates common mistakes with allowThis, allow, and
- *         permission propagation across transfers and contracts.
+ *         Covers mistakes with allowThis, allow, and permission propagation
+ *         across transfers and cross-contract calls.
  *
- * @dev Covers 6 critical patterns: missing allowThis, missing allow(user),
- *      view functions without permissions, unauthenticated re-encryption,
- *      transfer permission issues, and cross-contract delegation.
+ * @dev Explores missing permissions, view function failures, and delegation issues.
  */
 contract FHEPermissionsAntiPatterns is ZamaEthereumConfig {
     euint32 private _secretValue;

package/contracts/concepts/core/FHEAccessControl.sol

@@ -5,11 +5,9 @@ import {FHE, euint32, externalEuint32} from "@fhevm/solidity/lib/FHE.sol";
 import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 
 /**
- * @notice Master class for FHE permission patterns and access control.
- *         Explains the three permission types: allow() for permanent access,
- *         allowThis() for contract operations, and allowTransient() for
- *         temporary cross-contract calls. Includes correct and incorrect
- *         usage examples to prevent common decryption failures.
+ * @notice FHE permission patterns: allow() permanent, allowThis() contract,
+ *         and allowTransient() temporary access. Demonstrates usage to
+ *         prevent common decryption failures.
 
  * @dev allow() = permanent, allowThis() = contract permission,
  *      allowTransient() = expires at TX end