create-fhevm-example 1.3.1 → 1.4.0

package/contracts/advanced/PrivatePayroll.sol

@@ -0,0 +1,285 @@
+// SPDX-License-Identifier: BSD-3-Clause-Clear
+pragma solidity ^0.8.24;
+
+import {
+    FHE,
+    euint64,
+    ebool,
+    externalEuint64
+} from "@fhevm/solidity/lib/FHE.sol";
+import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
+
+/**
+ * @notice Private Payroll system - salaries stay encrypted, only employees see their own!
+ *
+ * @dev Demonstrates confidential enterprise use case:
+ *      - Employee salaries stored encrypted
+ *      - Bulk payments without revealing individual amounts
+ *      - Each employee can decrypt only their own salary
+ *      - Total payroll visible to employer for budgeting
+ *
+ * Flow:
+ * 1. Employer adds employees with encrypted salaries
+ * 2. Employer funds the contract
+ * 3. Employer calls payAll() to process all salaries
+ * 4. Employees can view (decrypt) their own salary
+ *
+ * ⚠️ IMPORTANT: Uses cumulative encrypted sum for total payroll tracking
+ */
+contract PrivatePayroll is ZamaEthereumConfig {
+    // ==================== STATE ====================
+
+    /// Contract owner (employer)
+    address public employer;
+
+    /// List of employee addresses
+    address[] public employees;
+
+    /// Mapping from employee to their encrypted salary
+    mapping(address => euint64) private _salaries;
+
+    /// Whether an address is an employee
+    mapping(address => bool) public isEmployee;
+
+    /// Last payment timestamp per employee
+    mapping(address => uint256) public lastPayment;
+
+    /// Total encrypted salary sum (for budget tracking)
+    euint64 private _totalSalaries;
+
+    /// Payment period in seconds (default: 30 days)
+    uint256 public paymentPeriod;
+
+    // ==================== EVENTS ====================
+
+    /// @notice Emitted when a new employee is added
+    /// @param employee Address of the employee
+    event EmployeeAdded(address indexed employee);
+
+    /// @notice Emitted when an employee is removed
+    /// @param employee Address of the removed employee
+    event EmployeeRemoved(address indexed employee);
+
+    /// @notice Emitted when salary is updated
+    /// @param employee Address of the employee
+    event SalaryUpdated(address indexed employee);
+
+    /// @notice Emitted when payment is processed
+    /// @param employee Address of paid employee
+    /// @param timestamp Payment time
+    event PaymentProcessed(address indexed employee, uint256 timestamp);
+
+    /// @notice Emitted when contract is funded
+    /// @param amount Amount funded
+    event ContractFunded(uint256 amount);
+
+    // ==================== MODIFIERS ====================
+
+    modifier onlyEmployer() {
+        require(msg.sender == employer, "Only employer");
+        _;
+    }
+
+    modifier onlyEmployee() {
+        require(isEmployee[msg.sender], "Not an employee");
+        _;
+    }
+
+    // ==================== CONSTRUCTOR ====================
+
+    /// @notice Creates a new private payroll contract
+    /// @param _paymentPeriod Time between payments in seconds
+    constructor(uint256 _paymentPeriod) {
+        employer = msg.sender;
+        paymentPeriod = _paymentPeriod > 0 ? _paymentPeriod : 30 days;
+        _totalSalaries = FHE.asEuint64(0);
+        FHE.allowThis(_totalSalaries);
+    }
+
+    // ==================== EMPLOYEE MANAGEMENT ====================
+
+    /// @notice Add a new employee with encrypted salary
+    /// @param employee Address of the employee
+    /// @param encryptedSalary Encrypted salary amount
+    /// @param inputProof Proof validating the encrypted input
+    function addEmployee(
+        address employee,
+        externalEuint64 encryptedSalary,
+        bytes calldata inputProof
+    ) external onlyEmployer {
+        require(employee != address(0), "Invalid address");
+        require(!isEmployee[employee], "Already an employee");
+
+        // 🔐 Convert external encrypted input
+        euint64 salary = FHE.fromExternal(encryptedSalary, inputProof);
+
+        // ✅ Grant permissions
+        FHE.allowThis(salary);
+        FHE.allow(salary, employee); // Employee can view their own salary
+
+        // 📋 Store employee data
+        _salaries[employee] = salary;
+        isEmployee[employee] = true;
+        employees.push(employee);
+
+        // 📊 Update total
+        _totalSalaries = FHE.add(_totalSalaries, salary);
+        FHE.allowThis(_totalSalaries);
+
+        emit EmployeeAdded(employee);
+    }
+
+    /// @notice Update an employee's salary
+    /// @param employee Address of the employee
+    /// @param encryptedSalary New encrypted salary amount
+    /// @param inputProof Proof validating the encrypted input
+    function updateSalary(
+        address employee,
+        externalEuint64 encryptedSalary,
+        bytes calldata inputProof
+    ) external onlyEmployer {
+        require(isEmployee[employee], "Not an employee");
+
+        // Get old salary for total adjustment
+        euint64 oldSalary = _salaries[employee];
+
+        // 🔐 Convert new salary
+        euint64 newSalary = FHE.fromExternal(encryptedSalary, inputProof);
+
+        // ✅ Grant permissions
+        FHE.allowThis(newSalary);
+        FHE.allow(newSalary, employee);
+
+        // 📋 Update salary
+        _salaries[employee] = newSalary;
+
+        // 📊 Update total: subtract old, add new
+        _totalSalaries = FHE.sub(_totalSalaries, oldSalary);
+        _totalSalaries = FHE.add(_totalSalaries, newSalary);
+        FHE.allowThis(_totalSalaries);
+
+        emit SalaryUpdated(employee);
+    }
+
+    /// @notice Remove an employee
+    /// @param employee Address to remove
+    function removeEmployee(address employee) external onlyEmployer {
+        require(isEmployee[employee], "Not an employee");
+
+        // Get salary for total adjustment
+        euint64 salary = _salaries[employee];
+
+        // 📊 Update total
+        _totalSalaries = FHE.sub(_totalSalaries, salary);
+        FHE.allowThis(_totalSalaries);
+
+        // Remove from list
+        for (uint256 i = 0; i < employees.length; i++) {
+            if (employees[i] == employee) {
+                employees[i] = employees[employees.length - 1];
+                employees.pop();
+                break;
+            }
+        }
+
+        // Clear data - euint64 cannot use delete, assign to zero instead
+        _salaries[employee] = FHE.asEuint64(0);
+        isEmployee[employee] = false;
+        lastPayment[employee] = 0;
+
+        emit EmployeeRemoved(employee);
+    }
+
+    // ==================== PAYMENTS ====================
+
+    /// @notice Fund the contract for payroll
+    function fund() external payable onlyEmployer {
+        require(msg.value > 0, "Must send funds");
+        emit ContractFunded(msg.value);
+    }
+
+    /// @notice Process payment for a single employee
+    /// @dev Requires decryption of salary - simplified for demo
+    /// @param employee Address to pay
+    /// @param abiEncodedSalary ABI-encoded salary amount
+    /// @param decryptionProof KMS decryption proof
+    function processPayment(
+        address employee,
+        bytes memory abiEncodedSalary,
+        bytes memory decryptionProof
+    ) external onlyEmployer {
+        require(isEmployee[employee], "Not an employee");
+        require(
+            block.timestamp >= lastPayment[employee] + paymentPeriod,
+            "Too early for next payment"
+        );
+
+        // Verify decryption
+        bytes32[] memory cts = new bytes32[](1);
+        cts[0] = FHE.toBytes32(_salaries[employee]);
+        FHE.checkSignatures(cts, abiEncodedSalary, decryptionProof);
+
+        uint64 salaryAmount = abi.decode(abiEncodedSalary, (uint64));
+        require(address(this).balance >= salaryAmount, "Insufficient funds");
+
+        lastPayment[employee] = block.timestamp;
+
+        // Transfer salary
+        (bool sent, ) = employee.call{value: salaryAmount}("");
+        require(sent, "Payment failed");
+
+        emit PaymentProcessed(employee, block.timestamp);
+    }
+
+    // ==================== VIEW FUNCTIONS ====================
+
+    /// @notice Get encrypted salary handle for an employee
+    /// @dev Only callable by the employee themselves
+    function getMySalary() external view onlyEmployee returns (euint64) {
+        return _salaries[msg.sender];
+    }
+
+    /// @notice Get encrypted total salaries handle
+    /// @dev Only employer can access for budget planning
+    function getTotalSalaries() external view onlyEmployer returns (euint64) {
+        return _totalSalaries;
+    }
+
+    /// @notice Get number of employees
+    function getEmployeeCount() external view returns (uint256) {
+        return employees.length;
+    }
+
+    /// @notice Get employee at index
+    function getEmployee(uint256 index) external view returns (address) {
+        require(index < employees.length, "Index out of bounds");
+        return employees[index];
+    }
+
+    /// @notice Check if payment is due for an employee
+    function isPaymentDue(address employee) external view returns (bool) {
+        if (!isEmployee[employee]) return false;
+        return block.timestamp >= lastPayment[employee] + paymentPeriod;
+    }
+
+    /// @notice Get contract balance
+    function getBalance() external view returns (uint256) {
+        return address(this).balance;
+    }
+
+    /// @notice Get payroll info
+    function getPayrollInfo()
+        external
+        view
+        returns (uint256 employeeCount, uint256 balance, uint256 period)
+    {
+        return (employees.length, address(this).balance, paymentPeriod);
+    }
+
+    // ==================== RECEIVE ====================
+
+    /// @notice Accept ETH deposits
+    receive() external payable {
+        emit ContractFunded(msg.value);
+    }
+}

package/contracts/basic/decryption/PublicDecryptMultipleValues.sol

@@ -0,0 +1,160 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.24;
+
+import {FHE, euint8} from "@fhevm/solidity/lib/FHE.sol";
+import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
+
+/**
+ * @notice Implements a simple 8-sided Die Roll game demonstrating public, permissionless decryption
+ *
+ * @dev Uses FHE.makePubliclyDecryptable feature to allow anyone to decrypt the game results.
+ *      Inherits from ZamaEthereumConfig to access FHE functions like FHE.randEuint8() and FHE.checkSignatures().
+ */
+contract HighestDieRoll is ZamaEthereumConfig {
+    constructor() {}
+
+    // Simple counter to assign a unique ID to each new game.
+    uint256 private counter = 0;
+
+    /**
+     * Defines the entire state for a single Die Roll game instance.
+     */
+    struct Game {
+        address playerA;
+        address playerB;
+        euint8 playerAEncryptedDieRoll;
+        euint8 playerBEncryptedDieRoll;
+        address winner;
+        bool revealed;
+    }
+
+    // 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
+    /// @param gameId The unique identifier for the game
+    /// @param playerA The address of playerA
+    /// @param playerB The address of playerB
+    /// @param playerAEncryptedDieRoll The encrypted die roll result of playerA
+    /// @param playerBEncryptedDieRoll The encrypted die roll result of playerB
+    event GameCreated(
+        uint256 indexed gameId,
+        address indexed playerA,
+        address indexed playerB,
+        euint8 playerAEncryptedDieRoll,
+        euint8 playerBEncryptedDieRoll
+    );
+
+    /// @notice Initiates a new highest die roll game, generates the result using FHE,
+    /// @notice and makes the result publicly available for decryption.
+    function highestDieRoll(address playerA, address playerB) external {
+        require(playerA != address(0), "playerA is address zero");
+        require(playerB != address(0), "playerB player is address zero");
+        require(playerA != playerB, "playerA and playerB should be different");
+
+        euint8 playerAEncryptedDieRoll = FHE.randEuint8();
+        euint8 playerBEncryptedDieRoll = FHE.randEuint8();
+
+        counter++;
+
+        // gameId > 0
+        uint256 gameId = counter;
+        games[gameId] = Game({
+            playerA: playerA,
+            playerB: playerB,
+            playerAEncryptedDieRoll: playerAEncryptedDieRoll,
+            playerBEncryptedDieRoll: playerBEncryptedDieRoll,
+            winner: address(0),
+            revealed: false
+        });
+
+        // We make the results publicly decryptable.
+        FHE.makePubliclyDecryptable(playerAEncryptedDieRoll);
+        FHE.makePubliclyDecryptable(playerBEncryptedDieRoll);
+
+        // You can catch the event to get the gameId and the die rolls handles
+        // for further decryption requests, or create a view function.
+        emit GameCreated(
+            gameId,
+            playerA,
+            playerB,
+            playerAEncryptedDieRoll,
+            playerBEncryptedDieRoll
+        );
+    }
+
+    /// @notice Returns the number of games created so far.
+    function getGamesCount() public view returns (uint256) {
+        return counter;
+    }
+
+    /// @notice Returns the encrypted euint8 handle that stores the playerA die roll.
+    function getPlayerADieRoll(uint256 gameId) public view returns (euint8) {
+        return games[gameId].playerAEncryptedDieRoll;
+    }
+
+    /// @notice Returns the encrypted euint8 handle that stores the playerB die roll.
+    function getPlayerBDieRoll(uint256 gameId) public view returns (euint8) {
+        return games[gameId].playerBEncryptedDieRoll;
+    }
+
+    /// @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");
+        return games[gameId].winner;
+    }
+
+    /// @notice Returns `true` if the game result is publicly revealed, `false` otherwise.
+    function isGameRevealed(uint256 gameId) public view returns (bool) {
+        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.
+    function recordAndVerifyWinner(
+        uint256 gameId,
+        bytes memory abiEncodedClearGameResult,
+        bytes memory decryptionProof
+    ) public {
+        require(!games[gameId].revealed, "Game already revealed");
+
+        // 1. FHE Verification: Build the list of ciphertexts (handles) and verify the proof.
+        //    The verification checks that 'abiEncodedClearGameResult' is the true decryption
+        //    of the '(playerAEncryptedDieRoll, playerBEncryptedDieRoll)' handle pair using
+        //    the provided 'decryptionProof'.
+
+        // Creating the list of handles in the right order! In this case the order does not matter since the proof
+        // only involves 1 single handle.
+        bytes32[] memory cts = new bytes32[](2);
+        cts[0] = FHE.toBytes32(games[gameId].playerAEncryptedDieRoll);
+        cts[1] = FHE.toBytes32(games[gameId].playerBEncryptedDieRoll);
+
+        // This FHE call reverts the transaction if the decryption proof is invalid.
+        FHE.checkSignatures(cts, abiEncodedClearGameResult, decryptionProof);
+
+        // 2. Decode the clear result and determine the winner's address.
+        //    In this very specific case, the function argument `abiEncodedClearGameResult` could have been replaced by two
+        //    `uint8` instead of an abi-encoded uint8 pair. In this case, we should have to compute abi.encode on-chain
+        (
+            uint8 decodedClearPlayerADieRoll,
+            uint8 decodedClearPlayerBDieRoll
+        ) = abi.decode(abiEncodedClearGameResult, (uint8, uint8));
+
+        // The die is an 8-sided die (d8) (1..8)
+        decodedClearPlayerADieRoll = (decodedClearPlayerADieRoll % 8) + 1;
+        decodedClearPlayerBDieRoll = (decodedClearPlayerBDieRoll % 8) + 1;
+
+        address winner = decodedClearPlayerADieRoll > decodedClearPlayerBDieRoll
+            ? games[gameId].playerA
+            : (
+                decodedClearPlayerADieRoll < decodedClearPlayerBDieRoll
+                    ? games[gameId].playerB
+                    : address(0)
+            );
+
+        // 3. Store the revealed flag
+        games[gameId].revealed = true;
+        games[gameId].winner = winner;
+    }
+}

package/contracts/basic/decryption/PublicDecryptSingleValue.sol

@@ -0,0 +1,142 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.24;
+
+import {FHE, ebool} from "@fhevm/solidity/lib/FHE.sol";
+import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
+
+/**
+ * @notice Implements a simple Heads or Tails game demonstrating public, permissionless decryption
+ *
+ * @dev Uses FHE.makePubliclyDecryptable feature to allow anyone to decrypt the game results.
+ *      Inherits from ZamaEthereumConfig to access FHE functions like FHE.randEbool() and FHE.checkSignatures().
+ */
+contract HeadsOrTails is ZamaEthereumConfig {
+    constructor() {}
+
+    /// Simple counter to assign a unique ID to each new game.
+    uint256 private counter = 0;
+
+    /**
+     * Defines the entire state for a single Heads or Tails game instance.
+     */
+    struct Game {
+        address headsPlayer;
+        address tailsPlayer;
+        ebool encryptedHasHeadsWon;
+        address winner;
+    }
+
+    // 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
+    /// @param gameId The unique identifier for the game
+    /// @param headsPlayer The address choosing Heads
+    /// @param tailsPlayer The address choosing Tails
+    /// @param encryptedHasHeadsWon The encrypted handle (ciphertext) storing the result
+    event GameCreated(
+        uint256 indexed gameId,
+        address indexed headsPlayer,
+        address indexed tailsPlayer,
+        ebool encryptedHasHeadsWon
+    );
+
+    /// @notice Initiates a new Heads or Tails game, generates the result using FHE,
+    /// @notice and makes the result publicly available for decryption.
+    function headsOrTails(address headsPlayer, address tailsPlayer) external {
+        require(headsPlayer != address(0), "Heads player is address zero");
+        require(tailsPlayer != address(0), "Tails player is address zero");
+        require(
+            headsPlayer != tailsPlayer,
+            "Heads player and Tails player should be different"
+        );
+
+        // true: Heads
+        // false: Tails
+        ebool headsOrTailsResult = FHE.randEbool();
+
+        counter++;
+
+        // gameId > 0
+        uint256 gameId = counter;
+        games[gameId] = Game({
+            headsPlayer: headsPlayer,
+            tailsPlayer: tailsPlayer,
+            encryptedHasHeadsWon: headsOrTailsResult,
+            winner: address(0)
+        });
+
+        // We make the result publicly decryptable.
+        FHE.makePubliclyDecryptable(headsOrTailsResult);
+
+        // You can catch the event to get the gameId and the encryptedHasHeadsWon handle
+        // for further decryption requests, or create a view function.
+        emit GameCreated(
+            gameId,
+            headsPlayer,
+            tailsPlayer,
+            games[gameId].encryptedHasHeadsWon
+        );
+    }
+
+    /// @notice Returns the number of games created so far.
+    function getGamesCount() public view returns (uint256) {
+        return counter;
+    }
+
+    /// @notice Returns the encrypted ebool handle that stores the game result.
+    function hasHeadsWon(uint256 gameId) public view returns (ebool) {
+        return games[gameId].encryptedHasHeadsWon;
+    }
+
+    /// @notice Returns the address of the game winner.
+    function getWinner(uint256 gameId) public view returns (address) {
+        require(
+            games[gameId].winner != address(0),
+            "Game winner not yet revealed"
+        );
+        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.
+    /// @dev gameId: The ID of the game to settle.
+    ///      abiEncodedClearGameResult: The ABI-encoded clear value (bool) associated to the `decryptionProof`.
+    ///      decryptionProof: The proof that validates the decryption.
+    function recordAndVerifyWinner(
+        uint256 gameId,
+        bytes memory abiEncodedClearGameResult,
+        bytes memory decryptionProof
+    ) public {
+        require(
+            games[gameId].winner == address(0),
+            "Game winner already revealed"
+        );
+
+        // 1. FHE Verification: Build the list of ciphertexts (handles) and verify the proof.
+        //    The verification checks that 'abiEncodedClearGameResult' is the true decryption
+        //    of the 'encryptedHasHeadsWon' handle using the provided 'decryptionProof'.
+
+        // Creating the list of handles in the right order! In this case the order does not matter since the proof
+        // only involves 1 single handle.
+        bytes32[] memory cts = new bytes32[](1);
+        cts[0] = FHE.toBytes32(games[gameId].encryptedHasHeadsWon);
+
+        // This FHE call reverts the transaction if the decryption proof is invalid.
+        FHE.checkSignatures(cts, abiEncodedClearGameResult, decryptionProof);
+
+        // 2. Decode the clear result and determine the winner's address.
+        //    In this very specific case, the function argument `abiEncodedClearGameResult` could have been a simple
+        //    `bool` instead of an abi-encoded bool. In this case, we should have compute abi.encode on-chain
+        bool decodedClearGameResult = abi.decode(
+            abiEncodedClearGameResult,
+            (bool)
+        );
+        address winner = decodedClearGameResult
+            ? games[gameId].headsPlayer
+            : games[gameId].tailsPlayer;
+
+        // 3. Store the winner
+        games[gameId].winner = winner;
+    }
+}

package/contracts/basic/decryption/UserDecryptMultipleValues.sol

@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: BSD-3-Clause-Clear
+pragma solidity ^0.8.24;
+
+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
+ *
+ * @dev Shows how to create encrypted values from plaintext and grant permissions
+ *      for multiple values of different types (ebool, euint32, euint64).
+ */
+contract UserDecryptMultipleValues is ZamaEthereumConfig {
+    // 🔐 Multiple encrypted values of different types
+    ebool private _encryptedBool;
+    euint32 private _encryptedUint32;
+    euint64 private _encryptedUint64;
+
+    constructor() {}
+
+    /// @notice Initialize multiple encrypted values from plaintext
+    /// @dev Uses FHE.asEuintX() to create encrypted constants from plaintext
+    ///      (The plaintext IS visible on-chain, but result is encrypted)
+    function initialize(bool a, uint32 b, uint64 c) external {
+        // Create encrypted values from plaintext constants
+        // FHE.asEbool(a) encrypts a boolean value
+        _encryptedBool = FHE.xor(FHE.asEbool(a), FHE.asEbool(false));
+
+        // FHE.asEuint32(b) + 1 creates an encrypted (b + 1)
+        _encryptedUint32 = FHE.add(FHE.asEuint32(b), FHE.asEuint32(1));
+        _encryptedUint64 = FHE.add(FHE.asEuint64(c), FHE.asEuint64(1));
+
+        // ⚠️ CRITICAL: Grant permissions for EACH value separately
+        // You cannot batch permission grants!
+        FHE.allowThis(_encryptedBool);
+        FHE.allowThis(_encryptedUint32);
+        FHE.allowThis(_encryptedUint64);
+
+        FHE.allow(_encryptedBool, msg.sender);
+        FHE.allow(_encryptedUint32, msg.sender);
+        FHE.allow(_encryptedUint64, msg.sender);
+    }
+
+    /// @notice Returns the encrypted boolean value
+    /// @dev Client decrypts with: fhevm.userDecrypt(FhevmType.ebool, handle, ...)
+    function encryptedBool() public view returns (ebool) {
+        return _encryptedBool;
+    }
+
+    /// @notice Returns the encrypted uint32 value
+    /// @dev Client decrypts with: fhevm.userDecrypt(FhevmType.euint32, handle, ...)
+    function encryptedUint32() public view returns (euint32) {
+        return _encryptedUint32;
+    }
+
+    /// @notice Returns the encrypted uint64 value
+    /// @dev Client decrypts with: fhevm.userDecrypt(FhevmType.euint64, handle, ...)
+    function encryptedUint64() public view returns (euint64) {
+        return _encryptedUint64;
+    }
+}