create-fhevm-example 1.3.1 → 1.4.0

package/contracts/concepts/FHEAntiPatterns.sol

@@ -0,0 +1,329 @@
+// SPDX-License-Identifier: BSD-3-Clause-Clear
+pragma solidity ^0.8.24;
+
+import {
+    FHE,
+    euint32,
+    ebool,
+    externalEuint32
+} from "@fhevm/solidity/lib/FHE.sol";
+import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
+
+/**
+ * @notice Common FHE mistakes and their correct alternatives. Covers: branching, permissions, require/revert, re-encryption, loops, noise, and deprecated APIs.
+ *
+ * @dev This contract demonstrates 9 critical anti-patterns in FHE development:
+ *      1. Branching on encrypted values (causes decryption!)
+ *      2. Returning encrypted values without permissions
+ *      3. Using require/revert with encrypted conditions
+ *      4. Encrypted computation without permission grants
+ *      5. Leaking information through gas/timing
+ *      6. Unauthenticated re-encryption (security critical!)
+ *      7. Encrypted loop iterations (gas/timing leak)
+ *      8. Too many chained operations (noise accumulation)
+ *      9. Using deprecated FHEVM APIs
+ *
+ *      Each anti-pattern shows both ❌ WRONG and ✅ CORRECT implementations.
+ */
+contract FHEAntiPatterns is ZamaEthereumConfig {
+    euint32 private _secretBalance;
+    euint32 private _threshold;
+
+    // solhint-disable-next-line no-empty-blocks
+    constructor() {}
+
+    /// @notice Initialize the contract with encrypted balance and threshold values
+    /// @dev Both values are encrypted and permissions are granted to the caller
+    function initialize(
+        externalEuint32 balance,
+        externalEuint32 threshold,
+        bytes calldata inputProof
+    ) external {
+        _secretBalance = FHE.fromExternal(balance, inputProof);
+        _threshold = FHE.fromExternal(threshold, inputProof);
+
+        FHE.allowThis(_secretBalance);
+        FHE.allowThis(_threshold);
+        FHE.allow(_secretBalance, msg.sender);
+        FHE.allow(_threshold, msg.sender);
+    }
+
+    // ========================================================================
+    // ANTI-PATTERN 1: Branching on encrypted values
+    // ========================================================================
+
+    /**
+     * ❌ WRONG: if/else on encrypted value causes decryption
+     * @dev This pattern LEAKS information by decrypting on-chain
+     *
+     * DO NOT USE THIS PATTERN - It defeats the purpose of encryption!
+     */
+    // function wrongBranching() external {
+    //     // ❌ This would compile but LEAK the comparison result!
+    //     // if (_secretBalance > _threshold) {  // WRONG: decrypts!
+    //     //     // do something
+    //     // }
+    // }
+
+    /**
+     * @notice ✅ CORRECT: Use FHE.select for conditional logic
+     * @dev All computation stays encrypted - demonstrates proper encrypted branching
+     */
+    function correctConditional() external {
+        // Compare encrypted values - result is encrypted boolean
+        ebool isAboveThreshold = FHE.gt(_secretBalance, _threshold);
+
+        // Use select for encrypted branching
+        // If above threshold: result = balance - 10
+        // Else: result = balance
+        euint32 penaltyAmount = FHE.asEuint32(10);
+        euint32 balanceMinusPenalty = FHE.sub(_secretBalance, penaltyAmount);
+
+        // ✅ Encrypted conditional - no information leaked
+        _secretBalance = FHE.select(
+            isAboveThreshold,
+            balanceMinusPenalty,
+            _secretBalance
+        );
+
+        FHE.allowThis(_secretBalance);
+        FHE.allow(_secretBalance, msg.sender);
+    }
+
+    // ========================================================================
+    // ANTI-PATTERN 2: View function returning encrypted without permissions
+    // ========================================================================
+
+    /**
+     * @notice ❌ WRONG: Returns encrypted value but caller can't decrypt
+     * @dev Without prior allow(), the returned handle is useless
+     */
+    function wrongGetBalance() external view returns (euint32) {
+        // ❌ Caller has no permission to decrypt this!
+        return _secretBalance;
+    }
+
+    /**
+     * @notice ✅ CORRECT: Ensure permissions were granted before returning
+     * @dev Caller must have been granted access in a previous transaction
+     */
+    function correctGetBalance() external view returns (euint32) {
+        // ✅ Caller should have been granted access via allow()
+        // The initialize() function grants access to msg.sender
+        return _secretBalance;
+    }
+
+    // ========================================================================
+    // ANTI-PATTERN 3: Using require/revert with encrypted conditions
+    // ========================================================================
+
+    /**
+     * ❌ WRONG: Cannot use require with encrypted values
+     * @dev This pattern doesn't even compile - encrypted bools can't be used in require
+     */
+    // function wrongRequire() external {
+    //     ebool hasEnough = FHE.ge(_secretBalance, FHE.asEuint32(100));
+    //     // ❌ COMPILE ERROR: require expects bool, not ebool
+    //     // require(hasEnough, "Insufficient balance");
+    // }
+
+    /**
+     * @notice ✅ CORRECT: Use encrypted flags instead of require
+     * @dev Store result and let client check after decryption
+     */
+    function correctValidation() external returns (ebool) {
+        // ✅ Return encrypted boolean for client to check
+        ebool hasEnough = FHE.ge(_secretBalance, FHE.asEuint32(100));
+
+        FHE.allowThis(hasEnough);
+        FHE.allow(hasEnough, msg.sender);
+
+        return hasEnough;
+    }
+
+    // ========================================================================
+    // ANTI-PATTERN 4: Encrypted computation without permission grants
+    // ========================================================================
+
+    /**
+     * @notice ❌ WRONG: Compute but forget to grant permissions
+     * @dev Result exists but no one can ever decrypt it
+     */
+    function wrongCompute() external {
+        euint32 doubled = FHE.mul(_secretBalance, FHE.asEuint32(2));
+        _secretBalance = doubled;
+        // ❌ Missing FHE.allowThis and FHE.allow!
+        // This value is now locked forever
+    }
+
+    /// @notice ✅ CORRECT: Always grant permissions after computation
+    function correctCompute() external {
+        euint32 doubled = FHE.mul(_secretBalance, FHE.asEuint32(2));
+        _secretBalance = doubled;
+
+        // ✅ Grant permissions
+        FHE.allowThis(_secretBalance);
+        FHE.allow(_secretBalance, msg.sender);
+    }
+
+    // ========================================================================
+    // ANTI-PATTERN 5: Leaking information through gas/timing
+    // ========================================================================
+
+    /**
+     * @notice ⚠️ CAUTION: Be aware of side-channel attacks
+     * @dev Even with FHE.select, be careful about operations that might
+     *      have different gas costs based on values
+     *
+     * BEST PRACTICES:
+     * - Use constant-time operations when possible
+     * - Avoid loops with encrypted iteration counts
+     * - Don't make external calls conditionally based on encrypted values
+     */
+    function cautionSideChannels() external pure returns (string memory) {
+        return "Be aware of gas/timing side channels";
+    }
+
+    // ========================================================================
+    // ANTI-PATTERN 6: Unauthenticated Re-encryption (SECURITY CRITICAL)
+    // ========================================================================
+
+    /**
+     * @notice ❌ WRONG: Re-encrypt for any provided public key
+     * @dev This allows impersonation attacks - anyone can request re-encryption
+     *      for any public key and pretend to be that user
+     *
+     * ATTACK SCENARIO:
+     * 1. Alice has encrypted balance
+     * 2. Eve calls wrongReencrypt(evePublicKey)
+     * 3. Eve gets Alice's balance re-encrypted for her key
+     * 4. Eve decrypts and learns Alice's secret balance!
+     */
+    // function wrongReencrypt(bytes calldata userPublicKey) external view {
+    //     // ❌ NO AUTHENTICATION! Anyone can provide any public key
+    //     // Re-encrypt _secretBalance for userPublicKey
+    //     // This leaks information to unauthorized users
+    // }
+
+    /**
+     * @notice ✅ CORRECT: Require cryptographic proof of identity
+     * @dev Use EIP-712 signature to prove the requester owns the public key
+     *
+     * CLIENT-SIDE:
+     * 1. User signs a message: "I authorize re-encryption for contract X"
+     * 2. Signature is verified on-chain before re-encryption
+     *
+     * Note: In practice, this is handled by the FHEVM SDK's userDecrypt flow
+     */
+    function correctReencryptPattern() external pure returns (string memory) {
+        return
+            "Always verify EIP-712 signature before re-encryption. "
+            "Use fhevm.js userDecrypt which handles this automatically.";
+    }
+
+    // ========================================================================
+    // ANTI-PATTERN 7: Encrypted Loop Iterations (GAS/TIMING LEAK)
+    // ========================================================================
+
+    /// ❌ WRONG: Using encrypted value as loop count
+    /// @dev Loop count is visible through gas consumption and timing
+    ///
+    /// PROBLEM: If we loop `encryptedCount` times, the gas cost reveals the count!
+    // function wrongEncryptedLoop(euint32 encryptedCount) external {
+    //     // ❌ GAS LEAK: Number of iterations visible!
+    //     // for (uint i = 0; i < decrypt(encryptedCount); i++) {
+    //     //     // Each iteration costs gas
+    //     // }
+    // }
+
+    /// @notice ✅ CORRECT: Use fixed iteration count with select
+    /// @dev Always iterate the maximum possible times, use FHE.select to
+    ///      conditionally apply operations
+    function correctFixedIterations() external {
+        // ✅ Fixed iteration count - no information leaked
+        uint256 MAX_ITERATIONS = 10;
+
+        euint32 accumulator = FHE.asEuint32(0);
+        euint32 counter = FHE.asEuint32(0);
+
+        for (uint256 i = 0; i < MAX_ITERATIONS; i++) {
+            // Check if we should still be iterating
+            ebool shouldContinue = FHE.lt(counter, _secretBalance);
+
+            // Conditionally add (add 1 if continuing, add 0 otherwise)
+            euint32 increment = FHE.select(
+                shouldContinue,
+                FHE.asEuint32(1),
+                FHE.asEuint32(0)
+            );
+            accumulator = FHE.add(accumulator, increment);
+            counter = FHE.add(counter, FHE.asEuint32(1));
+        }
+
+        FHE.allowThis(accumulator);
+        FHE.allow(accumulator, msg.sender);
+    }
+
+    // ========================================================================
+    // ANTI-PATTERN 8: Too Many Chained Operations (Noise Accumulation)
+    // ========================================================================
+
+    /// @notice ⚠️ CAUTION: FHE operations accumulate "noise"
+    /// @dev Each FHE operation adds noise to the ciphertext. After too many
+    ///      operations, the ciphertext becomes corrupted and undecryptable.
+    ///
+    /// FHEVM handles this via "bootstrapping" which is expensive.
+    /// Best practice: minimize operation chains where possible.
+    ///
+    /// EXAMPLE OF NOISE ACCUMULATION:
+    /// - Each add/sub: +1 noise
+    /// - Each mul: +10 noise (roughly)
+    /// - Bootstrapping threshold: ~100 noise (varies by scheme)
+    function cautionNoiseAccumulation() external pure returns (string memory) {
+        return
+            "Keep FHE operation chains short. Multiplications add more noise than additions. "
+            "If you need many operations, consider batching or restructuring logic.";
+    }
+
+    // ========================================================================
+    // ANTI-PATTERN 9: Using Deprecated FHEVM APIs
+    // ========================================================================
+
+    /**
+     * @notice Caution about deprecated FHEVM APIs
+     * @dev OLD (v0.8 and earlier):
+     * - Decryption went through Zama Oracle
+     * - Used TFHE.decrypt() directly
+     *
+     * NEW (v0.9+):
+     * - Self-relaying public decryption
+     * - Use FHE.makePubliclyDecryptable() + off-chain relay
+     */
+    function cautionDeprecatedAPIs() external pure returns (string memory) {
+        return
+            "Use FHEVM v0.9+ APIs. Old TFHE.decrypt() is deprecated. "
+            "Use FHE.makePubliclyDecryptable() for public decryption, "
+            "or userDecrypt pattern via fhevm.js for user decryption.";
+    }
+
+    // ========================================================================
+    // SUMMARY: Key Rules (Always check before deploying!)
+    // ========================================================================
+
+    /**
+     * @notice Quick reference for FHE best practices
+     * @return rules Summary of all 9 key rules
+     */
+    function getRules() external pure returns (string memory rules) {
+        return
+            "1. Never branch (if/else) on encrypted values - use FHE.select\n"
+            "2. Always call FHE.allowThis() AND FHE.allow(user) after computation\n"
+            "3. Cannot use require/revert with encrypted conditions\n"
+            "4. Return ebool for validations, let client decrypt and check\n"
+            "5. Be aware of gas/timing side channels\n"
+            "6. Always authenticate re-encryption requests (use EIP-712 signatures)\n"
+            "7. Never use encrypted values as loop iteration counts\n"
+            "8. Avoid chaining too many FHE operations (noise accumulation)\n"
+            "9. Use FHEVM v0.9+ APIs, avoid deprecated TFHE.decrypt()";
+    }
+}

package/contracts/concepts/FHEHandles.sol

@@ -0,0 +1,128 @@
+// SPDX-License-Identifier: BSD-3-Clause-Clear
+pragma solidity ^0.8.24;
+
+import {FHE, euint32, externalEuint32} from "@fhevm/solidity/lib/FHE.sol";
+import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
+
+/**
+ * @notice Understanding FHE handles: creation, computation, immutability, and symbolic execution in mock mode.
+ *
+ * @dev Handle = uint256 pointer to encrypted data stored by FHE coprocessor.
+ *      Types: euint8/16/32/64/128/256, ebool, eaddress, ebytes64/128/256
+ */
+contract FHEHandles is ZamaEthereumConfig {
+    // 🔐 Storage handles - persist across transactions
+    // These are just uint256 pointers, actual ciphertext is off-chain
+    euint32 private _storedValue;
+    euint32 private _computedValue;
+
+    event HandleCreated(string operation, uint256 gasUsed);
+    event HandleStored(string description);
+
+    constructor() {}
+
+    // ==================== HANDLE CREATION ====================
+
+    /// @notice Pattern 1: Create handle from user's encrypted input
+    function createFromExternal(
+        externalEuint32 input,
+        bytes calldata inputProof
+    ) external {
+        uint256 gasBefore = gasleft();
+
+        // 📥 FHE.fromExternal: converts external handle to internal handle
+        // The proof is verified automatically
+        _storedValue = FHE.fromExternal(input, inputProof);
+
+        emit HandleCreated("fromExternal", gasBefore - gasleft());
+
+        FHE.allowThis(_storedValue);
+        FHE.allow(_storedValue, msg.sender);
+    }
+
+    /// @notice Pattern 2: Create handle from plaintext constant
+    /// @dev ⚠️ The plaintext IS visible on-chain! But result is encrypted.
+    function createFromPlaintext(uint32 plaintextValue) external {
+        uint256 gasBefore = gasleft();
+
+        // 📥 FHE.asEuint32: encrypts a public constant
+        // Use for: thresholds, comparison values, zero-initialization
+        _storedValue = FHE.asEuint32(plaintextValue);
+
+        emit HandleCreated("asEuint32", gasBefore - gasleft());
+
+        FHE.allowThis(_storedValue);
+        FHE.allow(_storedValue, msg.sender);
+    }
+
+    // ==================== HANDLE COMPUTATION ====================
+
+    /// @notice Key insight: FHE operations create NEW handles
+    /// @dev Original handles are IMMUTABLE - they never change
+    function computeNewHandle() external {
+        uint256 gasBefore = gasleft();
+
+        euint32 constant10 = FHE.asEuint32(10);
+
+        // 🔄 FHE.add creates a BRAND NEW handle
+        // _storedValue handle is UNCHANGED
+        // _computedValue gets the NEW handle
+        _computedValue = FHE.add(_storedValue, constant10);
+
+        emit HandleCreated("add (new handle)", gasBefore - gasleft());
+
+        // ⚠️ Must grant permissions for the NEW handle!
+        FHE.allowThis(_computedValue);
+        FHE.allow(_computedValue, msg.sender);
+
+        emit HandleStored("Computed value stored with new handle");
+    }
+
+    /// @notice Chained operations = multiple intermediate handles
+    function chainedOperations() external {
+        // 📝 Each operation creates a new handle:
+        euint32 step1 = FHE.add(_storedValue, FHE.asEuint32(5)); // Handle #1
+        euint32 step2 = FHE.mul(step1, FHE.asEuint32(2)); // Handle #2
+        euint32 step3 = FHE.sub(step2, FHE.asEuint32(1)); // Handle #3
+
+        _computedValue = step3;
+
+        // Only final result needs permissions (if we're storing it)
+        // Intermediate handles (step1, step2) have ephemeral permission
+        // and are automatically cleaned up after transaction
+        FHE.allowThis(_computedValue);
+        FHE.allow(_computedValue, msg.sender);
+    }
+
+    // ==================== HANDLE IMMUTABILITY ====================
+
+    /// @notice Demonstrates: updating a variable creates NEW handle
+    function demonstrateImmutability()
+        external
+        returns (euint32 original, euint32 updated)
+    {
+        // 📌 Save reference to current handle
+        euint32 originalHandle = _storedValue;
+
+        // 🔄 This creates NEW handle, assigns to _storedValue
+        // originalHandle still points to OLD value!
+        _storedValue = FHE.add(_storedValue, FHE.asEuint32(100));
+
+        FHE.allowThis(_storedValue);
+        FHE.allow(_storedValue, msg.sender);
+
+        // originalHandle → old value
+        // _storedValue → new value (old + 100)
+        return (originalHandle, _storedValue);
+    }
+
+    // ==================== GETTERS ====================
+
+    function getStoredValue() external view returns (euint32) {
+        return _storedValue;
+    }
+
+    function getComputedValue() external view returns (euint32) {
+        return _computedValue;
+    }
+}

package/contracts/concepts/FHEInputProof.sol

@@ -0,0 +1,104 @@
+// SPDX-License-Identifier: BSD-3-Clause-Clear
+pragma solidity ^0.8.24;
+
+import {
+    FHE,
+    euint32,
+    euint64,
+    externalEuint32,
+    externalEuint64
+} from "@fhevm/solidity/lib/FHE.sol";
+import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
+
+/**
+ * @notice Explains input proof validation in FHEVM: what proofs are, why they are needed, and how to use them correctly with single and batched inputs.
+ *
+ * @dev Why proofs? They ensure:
+ *      1. Ciphertext is valid (not garbage data)
+ *      2. Value is in valid range for the type
+ *      3. Sender knows the plaintext (proof of knowledge)
+ */
+contract FHEInputProof is ZamaEthereumConfig {
+    euint32 private _singleValue;
+    euint32 private _valueA;
+    euint64 private _valueB;
+
+    constructor() {}
+
+    // ==================== SINGLE INPUT ====================
+
+    /// @notice Receive single encrypted value with proof
+    function setSingleValue(
+        externalEuint32 encryptedInput,
+        bytes calldata inputProof
+    ) external {
+        // 📥 FHE.fromExternal validates proof automatically
+        // If proof is invalid → transaction reverts
+        // Proof ensures:
+        //   ✓ Valid euint32 ciphertext
+        //   ✓ Encrypted for THIS contract
+        //   ✓ Sender knows the plaintext
+        _singleValue = FHE.fromExternal(encryptedInput, inputProof);
+
+        FHE.allowThis(_singleValue);
+        FHE.allow(_singleValue, msg.sender);
+    }
+
+    // ==================== MULTIPLE INPUTS (BATCHED) ====================
+
+    /// @notice Receive multiple encrypted values with SINGLE proof
+    /// @dev Client-side batching is more gas-efficient!
+    ///
+    /// Client code:
+    ///   const input = fhevm.createEncryptedInput(contractAddr, userAddr);
+    ///   input.add32(valueA);  // → handles[0]
+    ///   input.add64(valueB);  // → handles[1]
+    ///   const enc = await input.encrypt();
+    ///   // enc.inputProof covers BOTH values!
+    function setMultipleValues(
+        externalEuint32 inputA,
+        externalEuint64 inputB,
+        bytes calldata inputProof // ← Single proof covers both!
+    ) external {
+        // Both validated by same proof
+        _valueA = FHE.fromExternal(inputA, inputProof);
+        _valueB = FHE.fromExternal(inputB, inputProof);
+
+        // ⚠️ Each value needs its own permission grants
+        FHE.allowThis(_valueA);
+        FHE.allowThis(_valueB);
+        FHE.allow(_valueA, msg.sender);
+        FHE.allow(_valueB, msg.sender);
+    }
+
+    // ==================== COMPUTATION WITH NEW INPUT ====================
+
+    /// @notice Add new encrypted input to existing stored value
+    function addToValue(
+        externalEuint32 addend,
+        bytes calldata inputProof
+    ) external {
+        // Validate the new input
+        euint32 validatedAddend = FHE.fromExternal(addend, inputProof);
+
+        // Combine with stored value
+        _singleValue = FHE.add(_singleValue, validatedAddend);
+
+        FHE.allowThis(_singleValue);
+        FHE.allow(_singleValue, msg.sender);
+    }
+
+    // ==================== GETTERS ====================
+
+    function getSingleValue() external view returns (euint32) {
+        return _singleValue;
+    }
+
+    function getValueA() external view returns (euint32) {
+        return _valueA;
+    }
+
+    function getValueB() external view returns (euint64) {
+        return _valueB;
+    }
+}