create-fhevm-example 1.4.4 → 1.4.5

package/contracts/advanced/BlindAuction.sol

@@ -10,7 +10,11 @@ import {
 import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 
 /**
- * @notice Blind Auction with encrypted bids - only the winning price is revealed after bidding ends
+ * @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.
 
  * @dev Flow: bid() → endAuction() → revealWinner()
  *      Uses FHE.gt/select to find winner without revealing losing bids.

package/contracts/advanced/EncryptedEscrow.sol

@@ -10,7 +10,11 @@ import {
 import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 
 /**
- * @notice Encrypted Escrow service - amounts hidden until release!
+ * @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.
  *
  * @dev Flow: createEscrow() → fundEscrow() → release()/requestRefund()/raiseDispute()
  *      Multi-party agreement with arbiter for disputes.

package/contracts/advanced/HiddenVoting.sol

@@ -5,7 +5,11 @@ import {FHE, euint64, ebool, externalEuint8} from "@fhevm/solidity/lib/FHE.sol";
 import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 
 /**
- * @notice Hidden Voting with encrypted ballots and homomorphic tallying - individual votes stay private forever!
+ * @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.
  *
  * @dev Flow: vote() → closeVoting() → revealResults()
  *      ⚡ Gas: Each vote costs ~200k gas (FHE.add + FHE.select operations)

package/contracts/advanced/PrivateKYC.sol

@@ -12,7 +12,12 @@ import {
 import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 
 /**
- * @notice Private KYC - verify identity without revealing personal data!
+ * @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.
  *
  * @dev Flow: submitKYC() → verifyAge18()/verifyGoodCredit()/etc.
  *      Returns encrypted booleans: "Is 18+?", "Good credit?" without revealing actual values.

package/contracts/advanced/PrivatePayroll.sol

@@ -10,7 +10,11 @@ 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 Flow: addEmployee() → fund() → processPayment()
  *      Each employee can decrypt only their own salary.

package/contracts/basic/decryption/PublicDecryptMultipleValues.sol

@@ -5,7 +5,11 @@ import {FHE, euint8} from "@fhevm/solidity/lib/FHE.sol";
 import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 
 /**
- * @notice 8-sided die roll game demonstrating public decryption of multiple encrypted values.
+ * @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.randEuint8() + FHE.makePubliclyDecryptable() for both dice rolls.
  *      ⚠️ Order matters in cts[] array for checkSignatures!
@@ -29,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
@@ -97,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");
@@ -109,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,

package/contracts/basic/decryption/PublicDecryptSingleValue.sol

@@ -5,7 +5,11 @@ import {FHE, ebool} from "@fhevm/solidity/lib/FHE.sol";
 import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 
 /**
- * @notice Simple Heads or Tails game demonstrating public, permissionless decryption with FHE.
+ * @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.randEbool() for random result + FHE.makePubliclyDecryptable() for revealing.
  *      Anyone can decrypt results with valid KMS proof.
@@ -27,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
@@ -97,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,

package/contracts/basic/decryption/UserDecryptMultipleValues.sol

@@ -5,7 +5,11 @@ 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 with different types.
+ * @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 Each value needs separate permission grants (no batching).
  *      ⚠️ Cannot batch permission grants - must call allow() for each value!

package/contracts/basic/decryption/UserDecryptSingleValue.sol

@@ -5,7 +5,11 @@ import {FHE, euint32} from "@fhevm/solidity/lib/FHE.sol";
 import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 
 /**
- * @notice Demonstrates FHE decryption mechanism and highlights the critical permission pattern.
+ * @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 Shows CORRECT vs INCORRECT permission granting.
  *      ⚠️ Both allowThis + allow required for user decryption!

package/contracts/basic/encryption/EncryptMultipleValues.sol

@@ -13,7 +13,10 @@ 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 Demonstrates batched input (ONE proof for multiple values).
  *      ⚡ Gas: Batching saves ~50k gas vs separate proofs!

package/contracts/basic/encryption/EncryptSingleValue.sol

@@ -5,7 +5,10 @@ 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.
+ * @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.
@@ -20,7 +23,8 @@ contract EncryptSingleValue is ZamaEthereumConfig {
         externalEuint32 inputEuint32,
         bytes calldata inputProof
     ) external {
-        // 🔐 Why proof? Prevents: replay attacks, wrong contract, invalid ciphertext
+        // 🔐 Why proof?
+        // Prevents: replay attacks, wrong contract, invalid ciphertext
         _encryptedEuint32 = FHE.fromExternal(inputEuint32, inputProof);
 
         // 🔑 Why both?

package/contracts/basic/encryption/FHECounter.sol

@@ -5,7 +5,10 @@ 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.
+ * @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.

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

@@ -5,7 +5,11 @@ import {FHE, euint8, externalEuint8} from "@fhevm/solidity/lib/FHE.sol";
 import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 
 /**
- * @notice Simple example demonstrating addition of two encrypted values (a + b)
+ * @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.
 
  * @dev Shows the most basic FHE operation and permission flow.
  *      ⚡ Gas: FHE.add() costs ~100k gas (coprocessor call)

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

@@ -5,7 +5,11 @@ import {FHE, euint32, externalEuint32} from "@fhevm/solidity/lib/FHE.sol";
 import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 
 /**
- * @notice Demonstrates all FHE arithmetic operations: add, sub, mul, div, rem, min, max
+ * @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).
  *
  * @dev ⚡ Gas costs vary: add/sub (~100k) < mul (~150k) < div/rem (~300k)
  *      ⚠️ div/rem only work with plaintext divisor (not encrypted!)

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

@@ -10,7 +10,11 @@ import {
 import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 
 /**
- * @notice Demonstrates all FHE comparison operations: eq, ne, gt, lt, ge, le, select
+ * @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.
  *
  * @dev Results are encrypted booleans (ebool) - comparisons reveal nothing!
  *      ⚡ Gas: Comparisons ~100k, select ~120k

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

@@ -5,7 +5,11 @@ import {FHE, ebool, euint8, externalEuint8} from "@fhevm/solidity/lib/FHE.sol";
 import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 
 /**
- * @notice Demonstrates conditional logic: max(a, b) using encrypted comparison
+ * @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.
  *
  * @dev ❌ Can't use if/else (leaks info!) ✅ Use FHE.select instead
  *      ⚡ Gas: ~120k for select operation

package/contracts/concepts/FHEAccessControl.sol

@@ -5,9 +5,14 @@ import {FHE, euint32, externalEuint32} from "@fhevm/solidity/lib/FHE.sol";
 import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 
 /**
- * @notice Critical access control patterns in FHEVM: FHE.allow, FHE.allowThis, FHE.allowTransient with common mistakes.
-
- * @dev allow() = permanent, allowThis() = contract permission, allowTransient() = expires at TX end
+ * @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.
+
+ * @dev allow() = permanent, allowThis() = contract permission,
+ *      allowTransient() = expires at TX end
  *      Both allowThis + allow required for user decryption!
  */
 contract FHEAccessControl is ZamaEthereumConfig {

package/contracts/concepts/FHEAntiPatterns.sol

@@ -10,7 +10,11 @@ import {
 import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 
 /**
- * @notice Common FHE mistakes and correct alternatives: branching, permissions, require, loops, noise, deprecated APIs.
+ * @notice Comprehensive guide to FHE anti-patterns and their solutions.
+ *         Covers 9 critical mistakes: using if/else on encrypted values,
+ *         incorrect permission patterns, require() statements that leak info,
+ *         unbounded loops, noise accumulation, and deprecated APIs.
+ *         Each pattern shows both ❌ WRONG and ✅ CORRECT implementations.
  *
  * @dev Covers 9 critical anti-patterns with ❌ WRONG and ✅ CORRECT examples.
  *      This is an educational contract - study each pattern before building production code!

package/contracts/concepts/FHEHandles.sol

@@ -5,7 +5,11 @@ import {FHE, euint32, externalEuint32} from "@fhevm/solidity/lib/FHE.sol";
 import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 
 /**
- * @notice Understanding FHE handles: creation, computation, and immut ability.
+ * @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. Operations create NEW handles (immutable).
  *      ⚡ Gas: asEuint32 ~20k, fromExternal ~50k, add/sub ~100k

package/contracts/concepts/FHEInputProof.sol

@@ -11,7 +11,11 @@ import {
 import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 
 /**
- * @notice Explains input proof validation in FHEVM: why proofs matter and how to batch inputs efficiently.
+ * @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 Proofs ensure: valid ciphertext + correct range + proof of knowledge.
  *      ⚡ Gas: Batching multiple values in ONE proof saves ~50k gas vs separate proofs!

package/contracts/gaming/EncryptedLottery.sol

@@ -11,7 +11,11 @@ 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 Flow: buyTicket() → startDrawing() → checkAndClaim() → revealWinner()
  *      ⚡ Gas: Loop in checkAndClaim can be expensive with many tickets!

package/contracts/gaming/EncryptedPoker.sol

@@ -11,7 +11,11 @@ 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 Flow: joinGame() → bet()/fold() → showdown() → revealWinner()
  *      Hand strength = card1 + card2 (simplified for demo)

package/contracts/gaming/RockPaperScissors.sol

@@ -5,7 +5,11 @@ 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 using FHE!
+ * @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

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.
  */

package/contracts/openzeppelin/VestingWallet.sol

@@ -12,7 +12,12 @@ import {
 } from "@openzeppelin/confidential-contracts/interfaces/IERC7984.sol";
 
 /**
- * @notice Linear vesting wallet for ERC7984 tokens with fully encrypted amounts and schedules.
+ * @notice Time-locked vesting wallet with fully encrypted token amounts.
+ *         Implements linear vesting for ERC7984 confidential tokens. Vesting
+ *         schedule, amounts, and release calculations all happen on encrypted
+ *         values using FHE operations. Beneficiary can release vested tokens
+ *         over time without revealing the total allocation or vesting progress
+ *         to observers.
 
  * @dev Timeline: |--START--|---VESTING---|--END--| (0% → linear → 100%)
  *      All vesting calculations performed on encrypted values using FHE.

package/dist/scripts/commands/generate-config.js

@@ -56,9 +56,24 @@ const OUTPUT_FILE = path.join(ROOT_DIR, "scripts/shared/config.ts");
 // =============================================================================
 function extractNotice(contractPath) {
     const content = fs.readFileSync(contractPath, "utf-8");
-    const noticeRegex = /\/\*\*[\s\S]*?@notice\s+([^\n*]+)[\s\S]*?\*\/[\s\S]*?contract\s+\w+/;
+    // Match @notice and capture everything until @dev or end of comment block
+    const noticeRegex = /\/\*\*[\s\S]*?@notice\s+([\s\S]*?)(?:@dev|@param|\*\/)/;
     const match = content.match(noticeRegex);
-    return match && match[1] ? match[1].trim() : null;
+    if (!match || !match[1]) {
+        return null;
+    }
+    // Clean up the extracted text:
+    // 1. Remove leading asterisks and whitespace from each line
+    // 2. Join lines with space
+    // 3. Collapse multiple spaces
+    const cleaned = match[1]
+        .split("\n")
+        .map((line) => line.replace(/^\s*\*\s?/, "").trim())
+        .filter((line) => line.length > 0)
+        .join(" ")
+        .replace(/\s+/g, " ")
+        .trim();
+    return cleaned || null;
 }
 function readExistingConfig() {
     try {
@@ -160,7 +175,7 @@ function generateExamplesConfig(contracts) {
     contract: "${c.contractPath}",
     test: "${c.testPath}",${npmDepsField}${depsField}
     description:
-      "${c.description}",
+      "${c.description.replace(/"/g, '\\"')}",
     category: "${c.category}",
     docsOutput: "${c.docsOutput}",
     title: "${c.title}"

package/dist/scripts/shared/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../scripts/shared/config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,MAAM,WAAW,aAAa;IAC5B,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,uCAAuC;IACvC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,4BAA4B;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,8CAA8C;IAC9C,UAAU,EAAE,MAAM,CAAC;IACnB,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,cAAc;IAC7B,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,SAAS,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAClD;AAMD,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CA+QlD,CAAC;AAMF,eAAO,MAAM,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAoJrD,CAAC;AAMF;;GAEG;AACH,wBAAgB,eAAe,IAAI,MAAM,EAAE,CAE1C;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,EAAE,CAE3C;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAElE;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAEpE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE3D"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../scripts/shared/config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,MAAM,WAAW,aAAa;IAC5B,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,uCAAuC;IACvC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,4BAA4B;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,8CAA8C;IAC9C,UAAU,EAAE,MAAM,CAAC;IACnB,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,cAAc;IAC7B,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,SAAS,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAClD;AAMD,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CA6RlD,CAAC;AAMF,eAAO,MAAM,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAoJrD,CAAC;AAMF;;GAEG;AACH,wBAAgB,eAAe,IAAI,MAAM,EAAE,CAE1C;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,EAAE,CAE3C;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAElE;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAEpE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE3D"}

package/dist/scripts/shared/config.js

@@ -19,253 +19,259 @@ exports.EXAMPLES = {
     "blind-auction": {
         contract: "contracts/advanced/BlindAuction.sol",
         test: "test/advanced/BlindAuction.ts",
-        description: "Blind Auction with encrypted bids - only the winning price is revealed",
+        description: "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.",
         category: "Advanced",
         docsOutput: "docs/advanced/blind-auction.md",
-        title: "Blind Auction",
+        title: "Blind Auction"
     },
     "encrypted-escrow": {
         contract: "contracts/advanced/EncryptedEscrow.sol",
         test: "test/advanced/EncryptedEscrow.ts",
-        description: "Encrypted Escrow service - amounts hidden until release!",
+        description: "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.",
         category: "Advanced",
         docsOutput: "docs/advanced/encrypted-escrow.md",
-        title: "Encrypted Escrow",
+        title: "Encrypted Escrow"
     },
     "hidden-voting": {
         contract: "contracts/advanced/HiddenVoting.sol",
         test: "test/advanced/HiddenVoting.ts",
-        description: "Hidden Voting with encrypted ballots and homomorphic tallying",
+        description: "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.",
         category: "Advanced",
         docsOutput: "docs/advanced/hidden-voting.md",
-        title: "Hidden Voting",
+        title: "Hidden Voting"
     },
     "private-kyc": {
         contract: "contracts/advanced/PrivateKYC.sol",
         test: "test/advanced/PrivateKYC.ts",
-        description: "Private KYC - verify identity without revealing personal data!",
+        description: "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.",
         category: "Advanced",
         docsOutput: "docs/advanced/private-kyc.md",
-        title: "Private KYC",
+        title: "Private KYC"
     },
     "private-payroll": {
         contract: "contracts/advanced/PrivatePayroll.sol",
         test: "test/advanced/PrivatePayroll.ts",
-        description: "Private Payroll system - salaries stay encrypted, only employees see their own!",
+        description: "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.",
         category: "Advanced",
         docsOutput: "docs/advanced/private-payroll.md",
-        title: "Private Payroll",
+        title: "Private Payroll"
     },
     "public-decrypt-multiple-values": {
         contract: "contracts/basic/decryption/PublicDecryptMultipleValues.sol",
         test: "test/basic/decryption/PublicDecryptMultipleValues.ts",
-        description: "Implements a simple 8-sided Die Roll game demonstrating public, permissionless decryption",
+        description: "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.",
         category: "Basic - Decryption",
         docsOutput: "docs/basic/decryption/public-decrypt-multiple-values.md",
-        title: "Public Decrypt Multiple Values",
+        title: "Public Decrypt Multiple Values"
     },
     "public-decrypt-single-value": {
         contract: "contracts/basic/decryption/PublicDecryptSingleValue.sol",
         test: "test/basic/decryption/PublicDecryptSingleValue.ts",
-        description: "Implements a simple Heads or Tails game demonstrating public, permissionless decryption",
+        description: "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.",
         category: "Basic - Decryption",
         docsOutput: "docs/basic/decryption/public-decrypt-single-value.md",
-        title: "Public Decrypt Single Value",
+        title: "Public Decrypt Single Value"
     },
     "user-decrypt-multiple-values": {
         contract: "contracts/basic/decryption/UserDecryptMultipleValues.sol",
         test: "test/basic/decryption/UserDecryptMultipleValues.ts",
-        description: "Demonstrates user decryption of multiple encrypted values",
+        description: "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.",
         category: "Basic - Decryption",
         docsOutput: "docs/basic/decryption/user-decrypt-multiple-values.md",
-        title: "User Decrypt Multiple Values",
+        title: "User Decrypt Multiple Values"
     },
     "user-decrypt-single-value": {
         contract: "contracts/basic/decryption/UserDecryptSingleValue.sol",
         test: "test/basic/decryption/UserDecryptSingleValue.ts",
-        description: "Demonstrates the FHE decryption mechanism and highlights common pitfalls",
+        description: "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.",
         category: "Basic - Decryption",
         docsOutput: "docs/basic/decryption/user-decrypt-single-value.md",
-        title: "User Decrypt Single Value",
+        title: "User Decrypt Single Value"
     },
     "encrypt-multiple-values": {
         contract: "contracts/basic/encryption/EncryptMultipleValues.sol",
         test: "test/basic/encryption/EncryptMultipleValues.ts",
-        description: "Encrypting and handling multiple values in a single transaction efficiently.",
+        description: "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.",
         category: "Basic - Encryption",
         docsOutput: "docs/basic/encryption/encrypt-multiple-values.md",
-        title: "Encrypt Multiple Values",
+        title: "Encrypt Multiple Values"
     },
     "encrypt-single-value": {
         contract: "contracts/basic/encryption/EncryptSingleValue.sol",
         test: "test/basic/encryption/EncryptSingleValue.ts",
-        description: "FHE encryption mechanism with single values, including common pitfalls and best practices for developers.",
+        description: "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).",
         category: "Basic - Encryption",
         docsOutput: "docs/basic/encryption/encrypt-single-value.md",
-        title: "Encrypt Single Value",
+        title: "Encrypt Single Value"
     },
     "fhe-counter": {
         contract: "contracts/basic/encryption/FHECounter.sol",
         test: "test/basic/encryption/FHECounter.ts",
-        description: "Confidential counter implementation using FHEVM, compared with a standard counter to highlight encryption benefits.",
+        description: "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.",
         category: "Basic - Encryption",
         docsOutput: "docs/basic/encryption/fhe-counter.md",
-        title: "FHE Counter",
+        title: "FHE Counter"
     },
     "fhe-add": {
         contract: "contracts/basic/fhe-operations/FHEAdd.sol",
         test: "test/basic/fhe-operations/FHEAdd.ts",
-        description: "Simple example: adding two encrypted values (a + b)",
+        description: "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.",
         category: "Basic - FHE Operations",
         docsOutput: "docs/basic/fhe-operations/fhe-add.md",
-        title: "FHE Add",
+        title: "FHE Add"
     },
     "fhe-arithmetic": {
         contract: "contracts/basic/fhe-operations/FHEArithmetic.sol",
         test: "test/basic/fhe-operations/FHEArithmetic.ts",
-        description: "Demonstrates all FHE arithmetic operations on encrypted integers",
+        description: "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).",
         category: "Basic - FHE Operations",
         docsOutput: "docs/basic/fhe-operations/fhe-arithmetic.md",
-        title: "FHE Arithmetic",
+        title: "FHE Arithmetic"
     },
     "fhe-comparison": {
         contract: "contracts/basic/fhe-operations/FHEComparison.sol",
         test: "test/basic/fhe-operations/FHEComparison.ts",
-        description: "Demonstrates all FHE comparison operations on encrypted integers",
+        description: "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.",
         category: "Basic - FHE Operations",
         docsOutput: "docs/basic/fhe-operations/fhe-comparison.md",
-        title: "FHE Comparison",
+        title: "FHE Comparison"
     },
     "fhe-if-then-else": {
         contract: "contracts/basic/fhe-operations/FHEIfThenElse.sol",
         test: "test/basic/fhe-operations/FHEIfThenElse.ts",
-        description: "Demonstrates conditional logic: max(a, b) using encrypted comparison",
+        description: "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.",
         category: "Basic - FHE Operations",
         docsOutput: "docs/basic/fhe-operations/fhe-if-then-else.md",
-        title: "FHE If Then Else",
+        title: "FHE If Then Else"
     },
     "fhe-access-control": {
         contract: "contracts/concepts/FHEAccessControl.sol",
         test: "test/concepts/FHEAccessControl.ts",
-        description: "Critical access control patterns in FHEVM: FHE.allow, FHE.allowThis, FHE.allowTransient. Includes common mistakes and correct implementations.",
+        description: "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.",
         category: "Concepts",
         docsOutput: "docs/concepts/fhe-access-control.md",
-        title: "FHE Access Control",
+        title: "FHE Access Control"
     },
     "fhe-anti-patterns": {
         contract: "contracts/concepts/FHEAntiPatterns.sol",
         test: "test/concepts/FHEAntiPatterns.ts",
-        description: "Common FHE mistakes and their correct alternatives. Covers: branching, permissions, require/revert, re-encryption, loops, noise, and deprecated APIs.",
+        description: "Comprehensive guide to FHE anti-patterns and their solutions. Covers 9 critical mistakes: using if/else on encrypted values, incorrect permission patterns, require() statements that leak info, unbounded loops, noise accumulation, and deprecated APIs. Each pattern shows both ❌ WRONG and ✅ CORRECT implementations.",
         category: "Concepts",
         docsOutput: "docs/concepts/fhe-anti-patterns.md",
-        title: "FHE Anti Patterns",
+        title: "FHE Anti Patterns"
     },
     "fhe-handles": {
         contract: "contracts/concepts/FHEHandles.sol",
         test: "test/concepts/FHEHandles.ts",
-        description: "Understanding FHE handles: creation, computation, immutability, and symbolic execution in mock mode.",
+        description: "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.",
         category: "Concepts",
         docsOutput: "docs/concepts/fhe-handles.md",
-        title: "FHE Handles",
+        title: "FHE Handles"
     },
     "fhe-input-proof": {
         contract: "contracts/concepts/FHEInputProof.sol",
         test: "test/concepts/FHEInputProof.ts",
-        description: "Explains input proof validation in FHEVM: what proofs are, why they are needed, and how to use them correctly with single and batched inputs.",
+        description: "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.",
         category: "Concepts",
         docsOutput: "docs/concepts/fhe-input-proof.md",
-        title: "FHE Input Proof",
+        title: "FHE Input Proof"
     },
     "encrypted-lottery": {
         contract: "contracts/gaming/EncryptedLottery.sol",
         test: "test/gaming/EncryptedLottery.ts",
-        description: "Encrypted Lottery with private ticket numbers - fair and verifiable!",
+        description: "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.",
         category: "Gaming",
         docsOutput: "docs/gaming/encrypted-lottery.md",
-        title: "Encrypted Lottery",
+        title: "Encrypted Lottery"
     },
     "encrypted-poker": {
         contract: "contracts/gaming/EncryptedPoker.sol",
         test: "test/gaming/EncryptedPoker.ts",
-        description: "Encrypted Poker - Texas Hold'em with hidden hole cards!",
+        description: "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.",
         category: "Gaming",
         docsOutput: "docs/gaming/encrypted-poker.md",
-        title: "Encrypted Poker",
+        title: "Encrypted Poker"
     },
     "rock-paper-scissors": {
         contract: "contracts/gaming/RockPaperScissors.sol",
         test: "test/gaming/RockPaperScissors.ts",
-        description: "Rock-Paper-Scissors game with encrypted moves - fair play guaranteed!",
+        description: "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.",
         category: "Gaming",
         docsOutput: "docs/gaming/rock-paper-scissors.md",
-        title: "Rock Paper Scissors",
+        title: "Rock Paper Scissors"
     },
-    erc7984: {
+    "erc7984": {
         contract: "contracts/openzeppelin/ERC7984.sol",
         test: "test/openzeppelin/ERC7984.ts",
         npmDependencies: {
             "@openzeppelin/contracts": "^5.4.0",
-            "@openzeppelin/confidential-contracts": "^0.3.0",
+            "@openzeppelin/confidential-contracts": "^0.3.0"
         },
-        description: "Confidential token using OpenZeppelin's ERC7984 standard",
+        description: "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.",
         category: "Openzeppelin",
         docsOutput: "docs/openzeppelin/erc7984.md",
-        title: "ERC7984",
+        title: "ERC7984"
     },
     "erc7984-erc20-wrapper": {
         contract: "contracts/openzeppelin/ERC7984ERC20Wrapper.sol",
         test: "test/openzeppelin/ERC7984ERC20Wrapper.ts",
         npmDependencies: {
             "@openzeppelin/contracts": "^5.4.0",
-            "@openzeppelin/confidential-contracts": "^0.3.0",
+            "@openzeppelin/confidential-contracts": "^0.3.0"
         },
-        dependencies: ["contracts/openzeppelin/mocks/ERC20Mock.sol"],
-        description: "Wraps ERC20 tokens into confidential ERC7984 tokens",
+        dependencies: [
+            "contracts/openzeppelin/mocks/ERC20Mock.sol"
+        ],
+        description: "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.",
         category: "Openzeppelin",
         docsOutput: "docs/openzeppelin/erc7984-erc20-wrapper.md",
-        title: "ERC7984 ERC20 Wrapper",
+        title: "ERC7984 ERC20 Wrapper"
     },
     "swap-erc7984-to-erc20": {
         contract: "contracts/openzeppelin/SwapERC7984ToERC20.sol",
         test: "test/openzeppelin/SwapERC7984ToERC20.ts",
         npmDependencies: {
             "@openzeppelin/contracts": "^5.4.0",
-            "@openzeppelin/confidential-contracts": "^0.3.0",
+            "@openzeppelin/confidential-contracts": "^0.3.0"
         },
         dependencies: [
             "contracts/openzeppelin/mocks/ERC20Mock.sol",
-            "contracts/openzeppelin/ERC7984.sol",
+            "contracts/openzeppelin/ERC7984.sol"
         ],
-        description: "Swap confidential ERC7984 tokens to regular ERC20 tokens",
+        description: "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.",
         category: "Openzeppelin",
         docsOutput: "docs/openzeppelin/swap-erc7984-to-erc20.md",
-        title: "Swap ERC7984 To ERC20",
+        title: "Swap ERC7984 To ERC20"
     },
     "swap-erc7984-to-erc7984": {
         contract: "contracts/openzeppelin/SwapERC7984ToERC7984.sol",
         test: "test/openzeppelin/SwapERC7984ToERC7984.ts",
         npmDependencies: {
-            "@openzeppelin/confidential-contracts": "^0.3.0",
+            "@openzeppelin/confidential-contracts": "^0.3.0"
         },
-        dependencies: ["contracts/openzeppelin/ERC7984.sol"],
-        description: "Fully confidential swap between two ERC7984 tokens",
+        dependencies: [
+            "contracts/openzeppelin/ERC7984.sol"
+        ],
+        description: "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.",
         category: "Openzeppelin",
         docsOutput: "docs/openzeppelin/swap-erc7984-to-erc7984.md",
-        title: "Swap ERC7984 To ERC7984",
+        title: "Swap ERC7984 To ERC7984"
     },
     "vesting-wallet": {
         contract: "contracts/openzeppelin/VestingWallet.sol",
         test: "test/openzeppelin/VestingWallet.ts",
         npmDependencies: {
             "@openzeppelin/contracts": "^5.4.0",
-            "@openzeppelin/confidential-contracts": "^0.3.0",
+            "@openzeppelin/confidential-contracts": "^0.3.0"
         },
-        dependencies: ["contracts/openzeppelin/ERC7984.sol"],
-        description: "Linear vesting wallet for ERC7984 tokens - amounts stay encrypted!",
+        dependencies: [
+            "contracts/openzeppelin/ERC7984.sol"
+        ],
+        description: "Time-locked vesting wallet with fully encrypted token amounts. Implements linear vesting for ERC7984 confidential tokens. Vesting schedule, amounts, and release calculations all happen on encrypted values using FHE operations. Beneficiary can release vested tokens over time without revealing the total allocation or vesting progress to observers.",
         category: "Openzeppelin",
         docsOutput: "docs/openzeppelin/vesting-wallet.md",
-        title: "Vesting Wallet",
-    },
+        title: "Vesting Wallet"
+    }
 };
 // =============================================================================
 // Category Configurations
@@ -293,7 +299,7 @@ exports.CATEGORIES = {
             {
                 sol: "contracts/advanced/PrivatePayroll.sol",
                 test: "test/advanced/PrivatePayroll.ts",
-            },
+            }
         ],
     },
     basicdecryption: {
@@ -314,7 +320,7 @@ exports.CATEGORIES = {
             {
                 sol: "contracts/basic/decryption/UserDecryptSingleValue.sol",
                 test: "test/basic/decryption/UserDecryptSingleValue.ts",
-            },
+            }
         ],
     },
     basicencryption: {
@@ -331,7 +337,7 @@ exports.CATEGORIES = {
             {
                 sol: "contracts/basic/encryption/FHECounter.sol",
                 test: "test/basic/encryption/FHECounter.ts",
-            },
+            }
         ],
     },
     basicfheoperations: {
@@ -352,7 +358,7 @@ exports.CATEGORIES = {
             {
                 sol: "contracts/basic/fhe-operations/FHEIfThenElse.sol",
                 test: "test/basic/fhe-operations/FHEIfThenElse.ts",
-            },
+            }
         ],
     },
     concepts: {
@@ -373,7 +379,7 @@ exports.CATEGORIES = {
             {
                 sol: "contracts/concepts/FHEInputProof.sol",
                 test: "test/concepts/FHEInputProof.ts",
-            },
+            }
         ],
     },
     gaming: {
@@ -390,7 +396,7 @@ exports.CATEGORIES = {
             {
                 sol: "contracts/gaming/RockPaperScissors.sol",
                 test: "test/gaming/RockPaperScissors.ts",
-            },
+            }
         ],
     },
     openzeppelin: {
@@ -415,9 +421,9 @@ exports.CATEGORIES = {
             {
                 sol: "contracts/openzeppelin/VestingWallet.sol",
                 test: "test/openzeppelin/VestingWallet.ts",
-            },
+            }
         ],
-    },
+    }
 };
 // =============================================================================
 // Helper Functions

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-fhevm-example",
-  "version": "1.4.4",
+  "version": "1.4.5",
   "description": "Create FHEVM example projects with a single command - A comprehensive toolkit for building privacy-preserving smart contracts",
   "bin": {
     "create-fhevm-example": "./dist/scripts/index.js"