create-fhevm-example 1.4.5 → 1.4.7

package/README.md

@@ -56,8 +56,8 @@ npx create-fhevm-example --category basic
 npx create-fhevm-example --add
 npx create-fhevm-example --add --target ./my-existing-project
 
-# With auto-install and testing
-npx create-fhevm-example --example fhe-counter --output ./my-project --install --test
+# With auto-install
+npx create-fhevm-example --example fhe-counter --output ./my-project --install
 ```
 
 ---
@@ -72,7 +72,6 @@ npx create-fhevm-example --example fhe-counter --output ./my-project --install -
 | `--target <dir>` | Target directory for `--add` mode (default: current dir) |
 | `--output <dir>` | Output directory for new projects |
 | `--install` | Auto-install dependencies after scaffolding |
-| `--test` | Auto-run tests (requires `--install`) |
 | `--help`, `-h` | Show help information |
 
 ---
@@ -85,7 +84,7 @@ npx create-fhevm-example --example fhe-counter --output ./my-project --install -
 
 **FHE Operations** (4): `fhe-add`, `fhe-if-then-else`, `fhe-arithmetic`, `fhe-comparison`
 
-**Concepts** (4): `fhe-access-control`, `fhe-input-proof`, `fhe-handles`, `fhe-anti-patterns`
+**Concepts** (6): `fhe-access-control`, `fhe-input-proof`, `fhe-handles`, `control-flow`, `permissions`, `operations-gas-noise`
 
 **Gaming** (3): `rock-paper-scissors`, `encrypted-lottery`, `encrypted-poker`
 

package/contracts/concepts/antipatterns/ControlFlow.sol

@@ -0,0 +1,160 @@
+// 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 Control flow anti-patterns in FHE development.
+ *         Demonstrates common mistakes when using conditional logic
+ *         and loops with encrypted values.
+ *
+ * @dev Covers 3 critical patterns: if/else branching, require statements,
+ *      and encrypted loop iterations.
+ *      Each shows ❌ WRONG and ✅ CORRECT implementations.
+ */
+contract FHEControlFlowAntiPatterns is ZamaEthereumConfig {
+    euint32 private _secretBalance;
+    euint32 private _threshold;
+    ebool private _validationResult;
+
+    /// @notice Initialize contract with encrypted balance (threshold fixed for simplicity)
+    function initialize(
+        externalEuint32 balance,
+        bytes calldata inputProof
+    ) external {
+        _secretBalance = FHE.fromExternal(balance, inputProof);
+        _threshold = FHE.asEuint32(100); // Fixed threshold for simpler testing
+
+        FHE.allowThis(_secretBalance);
+        FHE.allowThis(_threshold);
+        FHE.allow(_secretBalance, msg.sender);
+        FHE.allow(_threshold, msg.sender);
+    }
+
+    // ═══════════════════════════════════════════════════════════════════════
+    // ANTI-PATTERN 1: If/Else Branching on Encrypted Values
+    // ═══════════════════════════════════════════════════════════════════════
+
+    /**
+     * ❌ WRONG: Using if/else with encrypted comparison
+     * @dev This pattern leaks information through control flow
+     */
+    function wrongBranching() external returns (uint256) {
+        // ❌ This would decrypt the comparison result!
+        // The branch taken reveals encrypted information
+        // if (decrypt(_secretBalance > _threshold)) {
+        //     return 1;
+        // }
+        // return 0;
+
+        // Placeholder to make function compile
+        return 0;
+    }
+
+    /**
+     * ✅ CORRECT: Use FHE.select for conditional logic
+     * @dev All computation stays encrypted
+     */
+    function correctConditional() external {
+        ebool isAboveThreshold = FHE.gt(_secretBalance, _threshold);
+
+        // Apply penalty if above threshold, otherwise keep balance
+        euint32 penaltyAmount = FHE.asEuint32(10);
+        euint32 balanceMinusPenalty = FHE.sub(_secretBalance, penaltyAmount);
+
+        _secretBalance = FHE.select(
+            isAboveThreshold,
+            balanceMinusPenalty,
+            _secretBalance
+        );
+
+        FHE.allowThis(_secretBalance);
+        FHE.allow(_secretBalance, msg.sender);
+    }
+
+    // ═══════════════════════════════════════════════════════════════════════
+    // ANTI-PATTERN 2: Require/Revert with Encrypted Conditions
+    // ═══════════════════════════════════════════════════════════════════════
+
+    /**
+     * ❌ WRONG: Cannot use require with encrypted boolean
+     * @dev This doesn't compile - ebool cannot be used in require
+     */
+    function wrongRequire() external pure returns (string memory) {
+        // ❌ COMPILE ERROR: require expects bool, not ebool
+        // ebool hasEnough = FHE.ge(_secretBalance, FHE.asEuint32(100));
+        // require(hasEnough, "Insufficient balance");
+
+        return "This pattern doesn't work with encrypted values";
+    }
+
+    /**
+     * ✅ CORRECT: Store encrypted boolean for client to check
+     * @dev Let the client decrypt via getter and handle validation
+     */
+    function correctValidation() external {
+        ebool hasEnough = FHE.ge(_secretBalance, FHE.asEuint32(100));
+
+        _validationResult = hasEnough;
+        FHE.allowThis(_validationResult);
+        FHE.allow(_validationResult, msg.sender);
+    }
+
+    /// @notice Get validation result
+    function getValidationResult() external view returns (ebool) {
+        return _validationResult;
+    }
+
+    // ═══════════════════════════════════════════════════════════════════════
+    // ANTI-PATTERN 3: Encrypted Loop Iterations
+    // ═══════════════════════════════════════════════════════════════════════
+
+    /**
+     * ❌ WRONG: Loop count based on encrypted value
+     * @dev Gas consumption reveals the loop count
+     */
+    function wrongEncryptedLoop() external pure returns (string memory) {
+        // ❌ GAS LEAK: Number of iterations visible through gas cost!
+        // for (uint i = 0; i < decrypt(_secretBalance); i++) {
+        //     // Each iteration costs gas
+        // }
+
+        return "Loop iterations leak through gas consumption";
+    }
+
+    /**
+     * ✅ CORRECT: Fixed iterations with FHE.select
+     * @dev Always loop maximum times, conditionally apply operations
+     */
+    function correctFixedIterations() external {
+        uint256 MAX_ITERATIONS = 5;
+        euint32 result = FHE.asEuint32(0);
+
+        for (uint256 i = 0; i < MAX_ITERATIONS; i++) {
+            // Check if we should add (i < _secretBalance)
+            ebool shouldAdd = FHE.lt(FHE.asEuint32(uint32(i)), _secretBalance);
+
+            // Add 1 if condition true, 0 otherwise
+            euint32 toAdd = FHE.select(
+                shouldAdd,
+                FHE.asEuint32(1),
+                FHE.asEuint32(0)
+            );
+            result = FHE.add(result, toAdd);
+        }
+
+        FHE.allowThis(result);
+        FHE.allow(result, msg.sender);
+    }
+
+    /// @notice Helper to get balance for testing
+    function getBalance() external view returns (euint32) {
+        return _secretBalance;
+    }
+}

package/contracts/concepts/antipatterns/OperationsGasNoise.sol

@@ -0,0 +1,190 @@
+// SPDX-License-Identifier: BSD-3-Clause-Clear
+pragma solidity ^0.8.24;
+
+import {
+    FHE,
+    euint32,
+    euint256,
+    externalEuint32
+} from "@fhevm/solidity/lib/FHE.sol";
+import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
+
+/**
+ * @notice Operations, gas, and noise anti-patterns in FHE development.
+ *         Demonstrates performance issues, side-channel leaks, and
+ *         inefficient encrypted computation patterns.
+ *
+ * @dev Covers 4 patterns: gas/timing side channels, noise accumulation,
+ *      deprecated APIs, and type mismatches.
+ */
+contract FHEOperationsGasNoiseAntiPatterns is ZamaEthereumConfig {
+    euint32 private _secretValue;
+
+    // ═══════════════════════════════════════════════════════════════════════
+    // ANTI-PATTERN 1: Gas/Timing Side Channel Attacks
+    // ═══════════════════════════════════════════════════════════════════════
+
+    /**
+     * ❌ WRONG: Different code paths have different gas costs
+     * @dev Gas consumption reveals which branch was taken
+     */
+    function wrongGasLeak(
+        externalEuint32 input,
+        bytes calldata inputProof
+    ) external {
+        euint32 value = FHE.fromExternal(input, inputProof);
+
+        // ❌ These operations have different gas costs!
+        // If value > 100: expensive operation
+        // If value <= 100: cheap operation
+        // Gas cost reveals the comparison result!
+
+        // Simulating different paths (commented to avoid actual leak)
+        // if (decrypt(value > 100)) {
+        //     // Expensive: 10 multiplications
+        // } else {
+        //     // Cheap: 1 addition
+        // }
+
+        _secretValue = value;
+        FHE.allowThis(_secretValue);
+    }
+
+    /**
+     * ✅ CORRECT: Constant-time operations
+     * @dev All paths consume same gas
+     */
+    function correctConstantTime(
+        externalEuint32 input,
+        bytes calldata inputProof
+    ) external {
+        euint32 value = FHE.fromExternal(input, inputProof);
+
+        // ✅ Always perform same operations regardless of value
+        euint32 result = FHE.mul(value, FHE.asEuint32(2));
+
+        _secretValue = result;
+        FHE.allowThis(_secretValue);
+        FHE.allow(_secretValue, msg.sender);
+    }
+
+    // ═══════════════════════════════════════════════════════════════════════
+    // ANTI-PATTERN 2: Noise Accumulation (Too Many Operations)
+    // ═══════════════════════════════════════════════════════════════════════
+
+    /**
+     * ❌ WRONG: Long chain of FHE operations
+     * @dev Each operation adds noise, eventually corrupting ciphertext
+     */
+    function wrongNoiseAccumulation(
+        externalEuint32 input,
+        bytes calldata inputProof
+    ) external {
+        euint32 value = FHE.fromExternal(input, inputProof);
+
+        // ❌ Too many chained operations!
+        // Each mul adds significant noise
+        euint32 result = value;
+        for (uint i = 0; i < 5; i++) {
+            result = FHE.mul(result, FHE.asEuint32(2)); // High noise per operation
+        }
+
+        _secretValue = result;
+        FHE.allowThis(_secretValue);
+    }
+
+    /**
+     * ✅ CORRECT: Minimize operation chains
+     * @dev Use mathematical optimization to reduce operations
+     */
+    function correctMinimizeOperations(
+        externalEuint32 input,
+        bytes calldata inputProof
+    ) external {
+        euint32 value = FHE.fromExternal(input, inputProof);
+
+        // ✅ Instead of 5 multiplications by 2, use single multiplication
+        // 2^5 = 32
+        euint32 result = FHE.mul(value, FHE.asEuint32(32));
+
+        _secretValue = result;
+        FHE.allowThis(_secretValue);
+        FHE.allow(_secretValue, msg.sender);
+    }
+
+    // ═══════════════════════════════════════════════════════════════════════
+    // ANTI-PATTERN 3: Using Deprecated FHEVM APIs
+    // ═══════════════════════════════════════════════════════════════════════
+
+    /**
+     * ❌ WRONG: Using old TFHE.decrypt() pattern
+     * @dev Deprecated in FHEVM v0.9+
+     */
+    function wrongDeprecatedAPI() external pure returns (string memory) {
+        // ❌ OLD (v0.8 and earlier):
+        // TFHE.decrypt() - went through Zama Oracle
+        //
+        // This pattern is deprecated and no longer supported
+
+        return "Don't use TFHE.decrypt() - it's deprecated";
+    }
+
+    /**
+     * ✅ CORRECT: Use modern FHEVM v0.9+ APIs
+     * @dev Use FHE.makePubliclyDecryptable() or userDecrypt pattern
+     */
+    function correctModernAPI() external pure returns (string memory) {
+        // ✅ NEW (v0.9+):
+        // - FHE.makePubliclyDecryptable() for public decryption
+        // - userDecrypt pattern via fhevm.js for user decryption
+
+        return "Use FHE.makePubliclyDecryptable() or fhevm.js userDecrypt()";
+    }
+
+    // ═══════════════════════════════════════════════════════════════════════
+    // ANTI-PATTERN 4: Unnecessary Large Data Types
+    // ═══════════════════════════════════════════════════════════════════════
+
+    /**
+     * ❌ WRONG: Using euint256 when euint32 is sufficient
+     * @dev Larger types = more gas + more noise
+     */
+    function wrongOversizedType(
+        externalEuint32 input,
+        bytes calldata inputProof
+    ) external {
+        euint32 value = FHE.fromExternal(input, inputProof);
+
+        // ❌ Unnecessarily converting to euint256!
+        // euint256 operations are limited and more expensive
+        // This conversion is wasteful when euint32 would suffice
+        euint256 largeValue = FHE.asEuint256(value);
+
+        // Converting back to euint32 (double conversion waste!)
+        _secretValue = FHE.asEuint32(largeValue);
+        FHE.allowThis(_secretValue);
+    }
+
+    /**
+     * ✅ CORRECT: Use smallest sufficient data type
+     * @dev euint32 is cheaper than euint256
+     */
+    function correctRightSizedType(
+        externalEuint32 input,
+        bytes calldata inputProof
+    ) external {
+        euint32 value = FHE.fromExternal(input, inputProof);
+
+        // ✅ Keep using euint32 if values fit
+        euint32 result = FHE.mul(value, FHE.asEuint32(2));
+
+        _secretValue = result;
+        FHE.allowThis(_secretValue);
+        FHE.allow(_secretValue, msg.sender);
+    }
+
+    /// @notice Helper to get value for testing
+    function getValue() external view returns (euint32) {
+        return _secretValue;
+    }
+}

package/contracts/concepts/antipatterns/Permissions.sol

@@ -0,0 +1,254 @@
+// 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 Permission management anti-patterns in FHE development.
+ *         Demonstrates common mistakes with allowThis, allow, and
+ *         permission propagation across transfers and contracts.
+ *
+ * @dev Covers 6 critical patterns: missing allowThis, missing allow(user),
+ *      view functions without permissions, unauthenticated re-encryption,
+ *      transfer permission issues, and cross-contract delegation.
+ */
+contract FHEPermissionsAntiPatterns is ZamaEthereumConfig {
+    euint32 private _secretValue;
+    mapping(address => euint32) private _balances;
+
+    // ═══════════════════════════════════════════════════════════════════════
+    // ANTI-PATTERN 1: Missing allowThis After Computation
+    // ═══════════════════════════════════════════════════════════════════════
+
+    /**
+     * ❌ WRONG: Compute but forget allowThis
+     * @dev Result exists but contract can't use it in future operations
+     */
+    function wrongMissingAllowThis(
+        externalEuint32 input,
+        bytes calldata inputProof
+    ) external {
+        _secretValue = FHE.fromExternal(input, inputProof);
+        euint32 doubled = FHE.mul(_secretValue, FHE.asEuint32(2));
+        _secretValue = doubled;
+
+        // ❌ Missing FHE.allowThis! Contract can't use this value later
+        FHE.allow(_secretValue, msg.sender);
+    }
+
+    /**
+     * ✅ CORRECT: Always grant allowThis after computation
+     * @dev Contract needs permission to use encrypted values
+     */
+    function correctWithAllowThis(
+        externalEuint32 input,
+        bytes calldata inputProof
+    ) external {
+        _secretValue = FHE.fromExternal(input, inputProof);
+        euint32 doubled = FHE.mul(_secretValue, FHE.asEuint32(2));
+        _secretValue = doubled;
+
+        FHE.allowThis(_secretValue);
+        FHE.allow(_secretValue, msg.sender);
+    }
+
+    // ═══════════════════════════════════════════════════════════════════════
+    // ANTI-PATTERN 2: Missing allow(user)
+    // ═══════════════════════════════════════════════════════════════════════
+
+    /**
+     * ❌ WRONG: Only allowThis without user permission
+     * @dev No one can decrypt the value
+     */
+    function wrongMissingUserAllow(
+        externalEuint32 input,
+        bytes calldata inputProof
+    ) external {
+        _secretValue = FHE.fromExternal(input, inputProof);
+
+        // ❌ Contract can compute but no one can decrypt!
+        FHE.allowThis(_secretValue);
+    }
+
+    /**
+     * ✅ CORRECT: Grant both allowThis and allow(user)
+     * @dev User can decrypt after contract operations
+     */
+    function correctWithUserAllow(
+        externalEuint32 input,
+        bytes calldata inputProof
+    ) external {
+        _secretValue = FHE.fromExternal(input, inputProof);
+
+        FHE.allowThis(_secretValue);
+        FHE.allow(_secretValue, msg.sender);
+    }
+
+    // ═══════════════════════════════════════════════════════════════════════
+    // ANTI-PATTERN 3: View Function Without Permissions
+    // ═══════════════════════════════════════════════════════════════════════
+
+    /**
+     * ❌ WRONG: Store value without granting permission to caller
+     * @dev When caller tries to get value via view, they can't decrypt it
+     */
+    function wrongStoreWithoutPermission(
+        externalEuint32 input,
+        bytes calldata inputProof
+    ) external {
+        _secretValue = FHE.fromExternal(input, inputProof);
+
+        // ❌ Only allowThis, caller has no permission!
+        FHE.allowThis(_secretValue);
+    }
+
+    /**
+     * ✅ CORRECT: Grant permission to caller when storing
+     * @dev Caller can now decrypt value returned from view function
+     */
+    function correctStoreWithPermission(
+        externalEuint32 input,
+        bytes calldata inputProof
+    ) external {
+        _secretValue = FHE.fromExternal(input, inputProof);
+
+        FHE.allowThis(_secretValue);
+        FHE.allow(_secretValue, msg.sender); // ✅ Grant permission!
+    }
+
+    /// @notice View function to get stored value
+    function getValue() external view returns (euint32) {
+        return _secretValue;
+    }
+
+    // ═══════════════════════════════════════════════════════════════════════
+    // ANTI-PATTERN 4: Unauthenticated Re-encryption
+    // ═══════════════════════════════════════════════════════════════════════
+
+    /**
+     * ❌ WRONG: Re-encrypt without verifying public key ownership
+     * @dev Anyone can provide any public key and steal encrypted data
+     */
+    function wrongReencryptWithoutAuth(
+        bytes32 publicKey
+    ) external view returns (bytes memory) {
+        // ❌ SECURITY RISK: No verification that caller owns this public key!
+        // Attacker can provide victim's public key and get their data
+
+        // This would allow impersonation attacks:
+        // return Gateway.reencrypt(_secretValue, publicKey);
+
+        return ""; // Placeholder
+    }
+
+    /**
+     * ✅ CORRECT: Use FHEVM's built-in authentication
+     * @dev fhevm.js SDK verifies EIP-712 signature automatically
+     *      Only the owner of the public key can decrypt
+     */
+    function correctReencryptWithAuth() external view returns (euint32) {
+        // ✅ Return handle directly
+        // Client uses fhevm.instance.reencrypt() which:
+        // 1. Signs request with their private key (EIP-712)
+        // 2. Gateway verifies signature matches public key
+        // 3. Only then re-encrypts for that public key
+
+        return _secretValue;
+    }
+
+    // ═══════════════════════════════════════════════════════════════════════
+    // ANTI-PATTERN 5: Transfer Without Permission Propagation
+    // ═══════════════════════════════════════════════════════════════════════
+
+    /**
+     * @notice Initialize balance for msg.sender
+     * @dev Required before using transfer functions
+     */
+    function initializeBalance(
+        externalEuint32 initialBalance,
+        bytes calldata inputProof
+    ) external {
+        _balances[msg.sender] = FHE.fromExternal(initialBalance, inputProof);
+        FHE.allowThis(_balances[msg.sender]);
+        FHE.allow(_balances[msg.sender], msg.sender);
+    }
+
+    /**
+     * ❌ WRONG: Transfer without granting permissions
+     * @dev Recipient gets balance but can't use or decrypt it
+     */
+    function wrongTransferWithoutPermission(
+        address recipient,
+        externalEuint32 amount,
+        bytes calldata inputProof
+    ) external {
+        euint32 transferAmount = FHE.fromExternal(amount, inputProof);
+
+        _balances[msg.sender] = FHE.sub(_balances[msg.sender], transferAmount);
+        _balances[recipient] = FHE.add(_balances[recipient], transferAmount);
+
+        // ❌ Recipient has no permission to use their new balance!
+    }
+
+    /**
+     * ✅ CORRECT: Grant permissions after transfer
+     * @dev Both parties can use and decrypt their updated balances
+     */
+    function correctTransferWithPermission(
+        address recipient,
+        externalEuint32 amount,
+        bytes calldata inputProof
+    ) external {
+        euint32 transferAmount = FHE.fromExternal(amount, inputProof);
+
+        _balances[msg.sender] = FHE.sub(_balances[msg.sender], transferAmount);
+        _balances[recipient] = FHE.add(_balances[recipient], transferAmount);
+
+        // ✅ Grant permissions to both parties
+        FHE.allowThis(_balances[msg.sender]);
+        FHE.allow(_balances[msg.sender], msg.sender);
+        FHE.allowThis(_balances[recipient]);
+        FHE.allow(_balances[recipient], recipient);
+    }
+
+    // ═══════════════════════════════════════════════════════════════════════
+    // ANTI-PATTERN 6: Cross-Contract Permission Delegation
+    // ═══════════════════════════════════════════════════════════════════════
+
+    /**
+     * ❌ WRONG: Call another contract without granting permission
+     * @dev Other contract can't use the encrypted value
+     */
+    function wrongCrossContractCall(address processor) external returns (bool) {
+        // ❌ processor contract has no permission to use _secretValue!
+        // This call will fail or return garbage
+        (bool success, ) = processor.call(
+            abi.encodeWithSignature("process(uint256)", _secretValue)
+        );
+        return success;
+    }
+
+    /**
+     * ✅ CORRECT: Grant temporary permission before cross-contract call
+     * @dev Use allowTransient for gas-efficient temporary access
+     */
+    function correctCrossContractCall(
+        address processor
+    ) external returns (bool) {
+        // ✅ Grant temporary permission (expires at end of transaction)
+        FHE.allowTransient(_secretValue, processor);
+
+        // Now processor can use _secretValue in this transaction
+        (bool success, ) = processor.call(
+            abi.encodeWithSignature("process(uint256)", _secretValue)
+        );
+
+        return success;
+    }
+
+    /// @notice Helper to get balance for testing
+    function getBalance(address user) external view returns (euint32) {
+        return _balances[user];
+    }
+}

package/dist/scripts/commands/add-mode.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"add-mode.d.ts","sourceRoot":"","sources":["../../../scripts/commands/add-mode.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA2OH;;GAEG;AACH,wBAAsB,UAAU,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA8ElE"}
+{"version":3,"file":"add-mode.d.ts","sourceRoot":"","sources":["../../../scripts/commands/add-mode.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAuOH;;GAEG;AACH,wBAAsB,UAAU,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA8ElE"}