create-fhevm-example 1.4.3 → 1.4.5

package/contracts/advanced/BlindAuction.sol

@@ -10,33 +10,23 @@ import {
 import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
 
 /**
- * @notice Blind Auction with encrypted bids - only the winning price is revealed
- *
- * @dev Demonstrates advanced FHE patterns:
- *      - Encrypted bid storage and comparison
- *      - FHE.gt() and FHE.select() for finding maximum
- *      - FHE.makePubliclyDecryptable() for revealing results
- *      - FHE.checkSignatures() for proof verification
- *
- * Flow:
- * 1. Owner creates auction with end time and minimum bid
- * 2. Bidders submit encrypted bids (one per address)
- * 3. Owner ends auction → winner computed via FHE.gt/select
- * 4. Anyone can reveal winner after decryption proof is ready
- *
- * ⚠️ IMPORTANT: Losing bids remain encrypted forever!
+ * @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.
+ *      Losing bids remain encrypted forever!
  */
 contract BlindAuction is ZamaEthereumConfig {
-    // ==================== TYPES ====================
-
     enum AuctionState {
         Open, // Accepting bids
         Closed, // Bidding ended, pending reveal
         Revealed // Winner revealed on-chain
     }
 
-    // ==================== STATE ====================
-
     /// Auction owner (deployer)
     address public owner;
 
@@ -70,8 +60,6 @@ contract BlindAuction is ZamaEthereumConfig {
     /// Revealed winning amount (set after reveal)
     uint64 public winningAmount;
 
-    // ==================== EVENTS ====================
-
     /// @notice Emitted when a new bid is placed
     /// @param bidder Address of the bidder
     event BidPlaced(address indexed bidder);
@@ -89,16 +77,12 @@ contract BlindAuction is ZamaEthereumConfig {
     /// @param amount Winning bid amount
     event WinnerRevealed(address indexed winner, uint64 amount);
 
-    // ==================== MODIFIERS ====================
-
     /// @dev Restricts function to owner only
     modifier onlyOwner() {
         require(msg.sender == owner, "Only owner can call");
         _;
     }
 
-    // ==================== CONSTRUCTOR ====================
-
     /// @notice Creates a new blind auction
     /// @param _endTime Unix timestamp when bidding ends
     /// @param _minimumBid Minimum bid amount (plaintext)
@@ -110,11 +94,8 @@ contract BlindAuction is ZamaEthereumConfig {
         auctionState = AuctionState.Open;
     }
 
-    // ==================== BIDDING ====================
-
     /// @notice Submit an encrypted bid to the auction
     /// @dev Each address can only bid once
-    /// @param encryptedBid The encrypted bid amount
     /// @param inputProof Proof validating the encrypted input
     function bid(
         externalEuint64 encryptedBid,
@@ -124,13 +105,11 @@ contract BlindAuction is ZamaEthereumConfig {
         require(block.timestamp < endTime, "Auction has ended");
         require(!hasBid[msg.sender], "Already placed a bid");
 
-        // 🔐 Convert external encrypted input to internal euint64
+        // Convert external encrypted input to internal handle (proof verified)
         euint64 bidAmount = FHE.fromExternal(encryptedBid, inputProof);
-
-        // ✅ Grant contract permission to operate on this value
         FHE.allowThis(bidAmount);
 
-        // 📋 Store the bid
+        // Store bid - amount stays encrypted
         _bids[msg.sender] = bidAmount;
         hasBid[msg.sender] = true;
         bidders.push(msg.sender);
@@ -138,30 +117,24 @@ contract BlindAuction is ZamaEthereumConfig {
         emit BidPlaced(msg.sender);
     }
 
-    // ==================== END AUCTION ====================
-
     /// @notice End the auction and compute the winner
+    /// @dev ⚡ Gas: O(n) loop with FHE.gt/select. ~200k gas per bidder!
     /// @dev Only owner can call after end time
     function endAuction() external onlyOwner {
         require(auctionState == AuctionState.Open, "Auction not open");
         require(block.timestamp >= endTime, "Auction not yet ended");
         require(bidders.length > 0, "No bids placed");
 
-        // 🏆 Find the winning bid using encrypted comparisons
-
-        // Initialize with first bidder
+        // Find winner using encrypted comparisons (no bids revealed!)
         euint64 currentMax = _bids[bidders[0]];
         euint64 currentWinnerIdx = FHE.asEuint64(0);
 
-        // 🔄 Iterate through remaining bidders
         for (uint256 i = 1; i < bidders.length; i++) {
             euint64 candidateBid = _bids[bidders[i]];
 
-            // 🔍 Compare: is candidate > currentMax?
-            // Note: If equal, first bidder wins (no update)
+            // 🔀 Why select? if/else would leak which bid is higher!
+            // Losing bids remain encrypted forever
             ebool isGreater = FHE.gt(candidateBid, currentMax);
-
-            // 🔀 Select the higher bid and its index
             currentMax = FHE.select(isGreater, candidateBid, currentMax);
             currentWinnerIdx = FHE.select(
                 isGreater,
@@ -170,14 +143,12 @@ contract BlindAuction is ZamaEthereumConfig {
             );
         }
 
-        // 📊 Check minimum bid threshold
+        // Check minimum bid (comparison stays encrypted)
         ebool meetsMinimum = FHE.ge(currentMax, FHE.asEuint64(minimumBid));
-
-        // If no one meets minimum, winner stays at index 0 but amount becomes 0
         _winningBid = FHE.select(meetsMinimum, currentMax, FHE.asEuint64(0));
         _winnerIndex = currentWinnerIdx;
 
-        // 🔓 Make results publicly decryptable
+        // Mark for public decryption via KMS relayer
         FHE.allowThis(_winningBid);
         FHE.allowThis(_winnerIndex);
         FHE.makePubliclyDecryptable(_winningBid);
@@ -189,36 +160,32 @@ contract BlindAuction is ZamaEthereumConfig {
     }
 
     /// @notice Reveal the winner with KMS decryption proof
-    /// @dev Anyone can call with valid decryption proof
-    /// @param abiEncodedResults ABI-encoded (uint64 amount, uint64 index)
-    /// @param decryptionProof KMS signature proving decryption
+    /// @dev Anyone can call once relayer provides proof.
+    ///      ⚠️ Order matters! cts[] must match abi.decode() order.
     function revealWinner(
         bytes memory abiEncodedResults,
         bytes memory decryptionProof
     ) external {
         require(auctionState == AuctionState.Closed, "Auction not closed");
 
-        // 🔐 Build ciphertext list for verification
-        // Order MUST match abiEncodedResults encoding order!
+        // Build handle array - order must match abi.decode() below!
         bytes32[] memory cts = new bytes32[](2);
         cts[0] = FHE.toBytes32(_winningBid);
         cts[1] = FHE.toBytes32(_winnerIndex);
 
-        // 🔍 Verify the decryption proof (reverts if invalid)
+        // Verify KMS signatures (reverts if proof invalid)
         FHE.checkSignatures(cts, abiEncodedResults, decryptionProof);
 
-        // 📤 Decode the verified results
+        // Decode verified plaintext results
         (uint64 revealedAmount, uint64 winnerIdx) = abi.decode(
             abiEncodedResults,
             (uint64, uint64)
         );
 
-        // 🏆 Look up winner address
         if (revealedAmount >= minimumBid && winnerIdx < bidders.length) {
             winner = bidders[winnerIdx];
             winningAmount = revealedAmount;
         } else {
-            // No valid winner (all bids below minimum)
             winner = address(0);
             winningAmount = 0;
         }
@@ -228,8 +195,6 @@ contract BlindAuction is ZamaEthereumConfig {
         emit WinnerRevealed(winner, winningAmount);
     }
 
-    // ==================== VIEW FUNCTIONS ====================
-
     /// @notice Get the number of bidders
     function getBidderCount() external view returns (uint256) {
         return bidders.length;

package/contracts/advanced/EncryptedEscrow.sol

@@ -10,26 +10,16 @@ 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 Demonstrates secure escrow with FHE:
- *      - Escrow amounts remain encrypted
- *      - Conditions verified without revealing values
- *      - Multi-party agreement pattern
- *      - Dispute resolution with arbiter
- *
- * Flow:
- * 1. Buyer creates escrow with encrypted amount
- * 2. Buyer deposits funds
- * 3. Seller delivers goods/services
- * 4. Buyer releases funds OR disputes
- * 5. Arbiter resolves disputes if needed
- *
- * ⚠️ IMPORTANT: Amount revealed only on release/refund
+ * @dev Flow: createEscrow() → fundEscrow() → release()/requestRefund()/raiseDispute()
+ *      Multi-party agreement with arbiter for disputes.
  */
 contract EncryptedEscrow is ZamaEthereumConfig {
-    // ==================== TYPES ====================
-
     enum EscrowState {
         Created, // Escrow created, awaiting deposit
         Funded, // Funds deposited
@@ -49,8 +39,6 @@ contract EncryptedEscrow is ZamaEthereumConfig {
         uint256 deadline;
     }
 
-    // ==================== STATE ====================
-
     /// Contract owner
     address public owner;
 
@@ -63,8 +51,6 @@ contract EncryptedEscrow is ZamaEthereumConfig {
     /// Arbiter fee percentage (default 1%)
     uint256 public arbiterFeePercent;
 
-    // ==================== EVENTS ====================
-
     /// @notice Emitted when escrow is created
     /// @param escrowId ID of the escrow
     /// @param buyer Address of buyer
@@ -100,8 +86,6 @@ contract EncryptedEscrow is ZamaEthereumConfig {
     /// @param winner Address favored in resolution
     event DisputeResolved(uint256 indexed escrowId, address indexed winner);
 
-    // ==================== CONSTRUCTOR ====================
-
     /// @notice Creates the escrow contract
     /// @param _arbiterFeePercent Fee percentage for arbiter (0-10)
     constructor(uint256 _arbiterFeePercent) {
@@ -110,8 +94,6 @@ contract EncryptedEscrow is ZamaEthereumConfig {
         arbiterFeePercent = _arbiterFeePercent;
     }
 
-    // ==================== ESCROW CREATION ====================
-
     /// @notice Create a new escrow with encrypted amount
     /// @param seller Address of the seller
     /// @param arbiter Address of dispute arbiter
@@ -172,8 +154,6 @@ contract EncryptedEscrow is ZamaEthereumConfig {
         emit EscrowFunded(escrowId, msg.value);
     }
 
-    // ==================== RELEASE / REFUND ====================
-
     /// @notice Release funds to seller
     /// @dev Only buyer can release after delivery
     /// @param escrowId ID of escrow to release
@@ -211,8 +191,6 @@ contract EncryptedEscrow is ZamaEthereumConfig {
         emit FundsRefunded(escrowId, escrow.buyer);
     }
 
-    // ==================== DISPUTE RESOLUTION ====================
-
     /// @notice Raise a dispute
     /// @param escrowId ID of escrow
     function raiseDispute(uint256 escrowId) external {
@@ -264,8 +242,6 @@ contract EncryptedEscrow is ZamaEthereumConfig {
         emit DisputeResolved(escrowId, winner);
     }
 
-    // ==================== VIEW FUNCTIONS ====================
-
     /// @notice Get escrow details
     function getEscrow(
         uint256 escrowId

package/contracts/advanced/HiddenVoting.sol

@@ -5,33 +5,22 @@ 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
+ * @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 Demonstrates FHE voting patterns:
- *      - Encrypted vote submission (0 = No, 1 = Yes)
- *      - Homomorphic addition for vote tallying
- *      - FHE.makePubliclyDecryptable() for revealing final results
- *      - Privacy: individual votes remain encrypted forever
- *
- * Flow:
- * 1. Owner creates a proposal with voting duration
- * 2. Eligible voters submit encrypted votes (0 or 1)
- * 3. Votes are homomorphically added to running totals
- * 4. After voting ends, owner closes and results become decryptable
- * 5. Anyone can reveal final Yes/No counts with valid proof
+ * @dev Flow: vote() → closeVoting() → revealResults()
+ *      ⚡ Gas: Each vote costs ~200k gas (FHE.add + FHE.select operations)
  */
 contract HiddenVoting is ZamaEthereumConfig {
-    // ==================== TYPES ====================
-
     enum VotingState {
         Active, // Accepting votes
         Closed, // Voting ended, pending reveal
         Revealed // Results revealed on-chain
     }
 
-    // ==================== STATE ====================
-
-    /// Voting owner (deployer)
     address public owner;
 
     /// Current voting state
@@ -59,9 +48,7 @@ contract HiddenVoting is ZamaEthereumConfig {
     uint64 public revealedYesVotes;
     uint64 public revealedNoVotes;
 
-    // ==================== EVENTS ====================
-
-    /// @notice Emitted when a vote is cast
+    /// Emitted when a vote is cast
     /// @param voter Address of the voter
     event VoteCast(address indexed voter);
 
@@ -75,19 +62,11 @@ contract HiddenVoting is ZamaEthereumConfig {
     /// @param noVotes Final No vote count
     event ResultsRevealed(uint64 yesVotes, uint64 noVotes);
 
-    // ==================== MODIFIERS ====================
-
-    /// @dev Restricts function to owner only
     modifier onlyOwner() {
         require(msg.sender == owner, "Only owner can call");
         _;
     }
 
-    // ==================== CONSTRUCTOR ====================
-
-    /// @notice Creates a new voting proposal
-    /// @param _proposal Description of what is being voted on
-    /// @param _durationSeconds How long voting is open
     constructor(string memory _proposal, uint256 _durationSeconds) {
         require(bytes(_proposal).length > 0, "Empty proposal");
         require(_durationSeconds > 0, "Duration must be positive");
@@ -97,18 +76,15 @@ contract HiddenVoting is ZamaEthereumConfig {
         endTime = block.timestamp + _durationSeconds;
         votingState = VotingState.Active;
 
-        // 🔐 Initialize encrypted counters to zero
+        // Initialize encrypted counters
         _yesVotes = FHE.asEuint64(0);
         _noVotes = FHE.asEuint64(0);
         FHE.allowThis(_yesVotes);
         FHE.allowThis(_noVotes);
     }
 
-    // ==================== VOTING ====================
-
-    /// @notice Cast an encrypted vote
-    /// @dev Vote must be 0 (No) or 1 (Yes). Values > 1 are treated as Yes.
-    /// @param encryptedVote Encrypted vote (0 or 1)
+    /// @notice Cast an encrypted vote (0=No, 1=Yes)
+    /// @dev Homomorphic tallying: votes added without decryption!
     /// @param inputProof Proof validating the encrypted input
     function vote(
         externalEuint8 encryptedVote,
@@ -118,14 +94,13 @@ contract HiddenVoting is ZamaEthereumConfig {
         require(block.timestamp < endTime, "Voting has ended");
         require(!hasVoted[msg.sender], "Already voted");
 
-        // 🔐 Convert external encrypted input
-        // Note: Using euint8 for vote, but storing as euint64 for addition
+        // Convert vote and normalize to 0 or 1
         euint64 voteValue = FHE.asEuint64(
             FHE.fromExternal(encryptedVote, inputProof)
         );
 
-        // 📊 Homomorphic vote counting
-        // We use select to normalize: if vote > 0, count as 1 for Yes
+        // 🧮 Why homomorphic? Votes are tallied WITHOUT decrypting individual ballots!
+        // Individual votes remain private forever
         ebool isYes = FHE.gt(voteValue, FHE.asEuint64(0));
 
         // ➕ Add to Yes counter if vote is Yes (1)
@@ -136,7 +111,6 @@ contract HiddenVoting is ZamaEthereumConfig {
         );
         _yesVotes = FHE.add(_yesVotes, yesIncrement);
 
-        // ➕ Add to No counter if vote is No (0)
         euint64 noIncrement = FHE.select(
             isYes,
             FHE.asEuint64(0),
@@ -144,26 +118,21 @@ contract HiddenVoting is ZamaEthereumConfig {
         );
         _noVotes = FHE.add(_noVotes, noIncrement);
 
-        // ✅ Update permissions for new values
-        FHE.allowThis(_yesVotes);
         FHE.allowThis(_noVotes);
 
-        // 📋 Record that this address has voted
         hasVoted[msg.sender] = true;
         voterCount++;
 
         emit VoteCast(msg.sender);
     }
 
-    // ==================== CLOSE VOTING ====================
-
-    /// @notice Close voting and prepare results for decryption
+    /// @notice Close voting and mark results for decryption
     /// @dev Only owner can call after voting period ends
     function closeVoting() external onlyOwner {
         require(votingState == VotingState.Active, "Voting not active");
         require(block.timestamp >= endTime, "Voting not yet ended");
 
-        // 🔓 Make results publicly decryptable
+        // Mark totals for public decryption via relayer
         FHE.makePubliclyDecryptable(_yesVotes);
         FHE.makePubliclyDecryptable(_noVotes);
 
@@ -182,15 +151,15 @@ contract HiddenVoting is ZamaEthereumConfig {
     ) external {
         require(votingState == VotingState.Closed, "Voting not closed");
 
-        // 🔐 Build ciphertext list for verification
+        // Build handle array for signature verification
         bytes32[] memory cts = new bytes32[](2);
         cts[0] = FHE.toBytes32(_yesVotes);
         cts[1] = FHE.toBytes32(_noVotes);
 
-        // 🔍 Verify the decryption proof (reverts if invalid)
+        // Verify KMS proof (reverts if invalid)
         FHE.checkSignatures(cts, abiEncodedResults, decryptionProof);
 
-        // 📤 Decode the verified results
+        // Decode verified plaintext results
         (uint64 yesCount, uint64 noCount) = abi.decode(
             abiEncodedResults,
             (uint64, uint64)
@@ -203,15 +172,11 @@ contract HiddenVoting is ZamaEthereumConfig {
         emit ResultsRevealed(yesCount, noCount);
     }
 
-    // ==================== VIEW FUNCTIONS ====================
-
-    /// @notice Get encrypted Yes votes handle (after voting closed)
     function getEncryptedYesVotes() external view returns (euint64) {
         require(votingState != VotingState.Active, "Voting still active");
         return _yesVotes;
     }
 
-    /// @notice Get encrypted No votes handle (after voting closed)
     function getEncryptedNoVotes() external view returns (euint64) {
         require(votingState != VotingState.Active, "Voting still active");
         return _noVotes;

package/contracts/advanced/PrivateKYC.sol

@@ -12,24 +12,18 @@ 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 Demonstrates identity verification using FHE predicates:
- *      - Users submit encrypted KYC attributes (age, country, credit score)
- *      - Verifiers check conditions without seeing actual values
- *      - Only boolean results revealed: "Is 18+?", "Is from allowed country?"
- *      - Personal data never leaves encrypted form
- *
- * Verification types:
- * 1. Age verification: isAbove18(), isAbove21()
- * 2. Country check: isFromAllowedCountry()
- * 3. Credit score: hasCreditScoreAbove(threshold)
- *
- * ⚠️ IMPORTANT: This is a demo - production KYC needs trusted attesters!
+ * @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 {
-    // ==================== TYPES ====================
-
     struct Identity {
         euint8 age; // 0-255 years
         euint8 countryCode; // ISO 3166-1 numeric (1-255)
@@ -38,8 +32,6 @@ contract PrivateKYC is ZamaEthereumConfig {
         uint256 verifiedAt; // Timestamp of verification
     }
 
-    // ==================== STATE ====================
-
     /// Contract owner (KYC admin)
     address public owner;
 
@@ -56,8 +48,6 @@ contract PrivateKYC is ZamaEthereumConfig {
     /// Minimum credit score for "good" rating
     uint16 public constant MIN_CREDIT_GOOD = 700;
 
-    // ==================== EVENTS ====================
-
     /// @notice Emitted when user submits KYC
     /// @param user Address of user
     event KYCSubmitted(address indexed user);
@@ -76,8 +66,6 @@ contract PrivateKYC is ZamaEthereumConfig {
     /// @param minAge Minimum age required
     event AgeVerificationRequested(address indexed user, uint8 minAge);
 
-    // ==================== MODIFIERS ====================
-
     modifier onlyOwner() {
         require(msg.sender == owner, "Only owner");
         _;
@@ -88,8 +76,6 @@ contract PrivateKYC is ZamaEthereumConfig {
         _;
     }
 
-    // ==================== CONSTRUCTOR ====================
-
     /// @notice Creates the KYC contract
     /// @param _allowedCountryCodes Initial list of allowed country codes
     constructor(uint8[] memory _allowedCountryCodes) {
@@ -101,8 +87,6 @@ contract PrivateKYC is ZamaEthereumConfig {
         }
     }
 
-    // ==================== KYC SUBMISSION ====================
-
     /// @notice Submit encrypted KYC data
     /// @param encAge Encrypted age
     /// @param encCountry Encrypted country code
@@ -147,8 +131,6 @@ contract PrivateKYC is ZamaEthereumConfig {
         emit KYCRevoked(msg.sender);
     }
 
-    // ==================== VERIFICATION FUNCTIONS ====================
-
     /// @notice Check if user is 18 or older
     /// @param user Address to verify
     /// @return result Encrypted boolean result
@@ -232,8 +214,6 @@ contract PrivateKYC is ZamaEthereumConfig {
         return result;
     }
 
-    // ==================== DECRYPTABLE VERIFICATION ====================
-
     /// @notice Request age verification with public result
     /// @dev Makes the result publicly decryptable
     /// @param user Address to verify
@@ -252,8 +232,6 @@ contract PrivateKYC is ZamaEthereumConfig {
         return result;
     }
 
-    // ==================== ADMIN FUNCTIONS ====================
-
     /// @notice Update country allowlist
     /// @param countryCode Country code to update
     /// @param allowed Whether to allow or deny
@@ -278,8 +256,6 @@ contract PrivateKYC is ZamaEthereumConfig {
         }
     }
 
-    // ==================== VIEW FUNCTIONS ====================
-
     /// @notice Check if user has submitted KYC
     function hasSubmittedKYC(address user) external view returns (bool) {
         return _identities[user].isVerified;