create-fhevm-example 1.3.1 → 1.4.0

package/contracts/advanced/BlindAuction.sol

@@ -0,0 +1,255 @@
+// 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 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!
+ */
+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;
+
+    /// Current auction state
+    AuctionState public auctionState;
+
+    /// Minimum bid in plaintext (for gas efficiency)
+    uint64 public minimumBid;
+
+    /// Auction end timestamp
+    uint256 public endTime;
+
+    /// All bidder addresses (for iteration)
+    address[] public bidders;
+
+    /// Mapping from bidder address to their encrypted bid
+    mapping(address => euint64) private _bids;
+
+    /// Whether an address has bid
+    mapping(address => bool) public hasBid;
+
+    /// Encrypted winning bid amount (set after auction ends)
+    euint64 private _winningBid;
+
+    /// Encrypted winner index in bidders array
+    euint64 private _winnerIndex;
+
+    /// Address of the winner (set after reveal)
+    address public winner;
+
+    /// 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);
+
+    /// @notice Emitted when auction is closed
+    /// @param encryptedWinningBid Handle for encrypted winning bid
+    /// @param encryptedWinnerIndex Handle for encrypted winner index
+    event AuctionEnded(
+        euint64 encryptedWinningBid,
+        euint64 encryptedWinnerIndex
+    );
+
+    /// @notice Emitted when winner is revealed
+    /// @param winner Address of the winner
+    /// @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)
+    constructor(uint256 _endTime, uint64 _minimumBid) {
+        require(_endTime > block.timestamp, "End time must be in future");
+        owner = msg.sender;
+        endTime = _endTime;
+        minimumBid = _minimumBid;
+        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,
+        bytes calldata inputProof
+    ) external {
+        require(auctionState == AuctionState.Open, "Auction not open");
+        require(block.timestamp < endTime, "Auction has ended");
+        require(!hasBid[msg.sender], "Already placed a bid");
+
+        // 🔐 Convert external encrypted input to internal euint64
+        euint64 bidAmount = FHE.fromExternal(encryptedBid, inputProof);
+
+        // ✅ Grant contract permission to operate on this value
+        FHE.allowThis(bidAmount);
+
+        // 📋 Store the bid
+        _bids[msg.sender] = bidAmount;
+        hasBid[msg.sender] = true;
+        bidders.push(msg.sender);
+
+        emit BidPlaced(msg.sender);
+    }
+
+    // ==================== END AUCTION ====================
+
+    /// @notice End the auction and compute the winner
+    /// @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
+        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)
+            ebool isGreater = FHE.gt(candidateBid, currentMax);
+
+            // 🔀 Select the higher bid and its index
+            currentMax = FHE.select(isGreater, candidateBid, currentMax);
+            currentWinnerIdx = FHE.select(
+                isGreater,
+                FHE.asEuint64(uint64(i)),
+                currentWinnerIdx
+            );
+        }
+
+        // 📊 Check minimum bid threshold
+        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
+        FHE.allowThis(_winningBid);
+        FHE.allowThis(_winnerIndex);
+        FHE.makePubliclyDecryptable(_winningBid);
+        FHE.makePubliclyDecryptable(_winnerIndex);
+
+        auctionState = AuctionState.Closed;
+
+        emit AuctionEnded(_winningBid, _winnerIndex);
+    }
+
+    /// @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
+    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!
+        bytes32[] memory cts = new bytes32[](2);
+        cts[0] = FHE.toBytes32(_winningBid);
+        cts[1] = FHE.toBytes32(_winnerIndex);
+
+        // 🔍 Verify the decryption proof (reverts if invalid)
+        FHE.checkSignatures(cts, abiEncodedResults, decryptionProof);
+
+        // 📤 Decode the verified 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;
+        }
+
+        auctionState = AuctionState.Revealed;
+
+        emit WinnerRevealed(winner, winningAmount);
+    }
+
+    // ==================== VIEW FUNCTIONS ====================
+
+    /// @notice Get the number of bidders
+    function getBidderCount() external view returns (uint256) {
+        return bidders.length;
+    }
+
+    /// @notice Get bidder address by index
+    function getBidder(uint256 index) external view returns (address) {
+        require(index < bidders.length, "Index out of bounds");
+        return bidders[index];
+    }
+
+    /// @notice Get encrypted winning bid handle (after auction ends)
+    function getEncryptedWinningBid() external view returns (euint64) {
+        require(auctionState != AuctionState.Open, "Auction still open");
+        return _winningBid;
+    }
+
+    /// @notice Get encrypted winner index handle (after auction ends)
+    function getEncryptedWinnerIndex() external view returns (euint64) {
+        require(auctionState != AuctionState.Open, "Auction still open");
+        return _winnerIndex;
+    }
+}

package/contracts/advanced/EncryptedEscrow.sol

@@ -0,0 +1,315 @@
+// 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 Encrypted Escrow service - amounts hidden until release!
+ *
+ * @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
+ */
+contract EncryptedEscrow is ZamaEthereumConfig {
+    // ==================== TYPES ====================
+
+    enum EscrowState {
+        Created, // Escrow created, awaiting deposit
+        Funded, // Funds deposited
+        Released, // Funds released to seller
+        Refunded, // Funds returned to buyer
+        Disputed // Under dispute resolution
+    }
+
+    struct Escrow {
+        address buyer;
+        address seller;
+        address arbiter;
+        euint64 encryptedAmount;
+        uint256 depositedAmount;
+        EscrowState state;
+        uint256 createdAt;
+        uint256 deadline;
+    }
+
+    // ==================== STATE ====================
+
+    /// Contract owner
+    address public owner;
+
+    /// Escrow ID counter
+    uint256 public escrowCount;
+
+    /// Mapping from escrow ID to Escrow data
+    mapping(uint256 => Escrow) private _escrows;
+
+    /// 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
+    /// @param seller Address of seller
+    event EscrowCreated(
+        uint256 indexed escrowId,
+        address indexed buyer,
+        address indexed seller
+    );
+
+    /// @notice Emitted when escrow is funded
+    /// @param escrowId ID of the escrow
+    /// @param amount Amount deposited
+    event EscrowFunded(uint256 indexed escrowId, uint256 amount);
+
+    /// @notice Emitted when funds are released
+    /// @param escrowId ID of the escrow
+    /// @param recipient Address receiving funds
+    event FundsReleased(uint256 indexed escrowId, address indexed recipient);
+
+    /// @notice Emitted when funds are refunded
+    /// @param escrowId ID of the escrow
+    /// @param recipient Address receiving refund
+    event FundsRefunded(uint256 indexed escrowId, address indexed recipient);
+
+    /// @notice Emitted when dispute is raised
+    /// @param escrowId ID of the escrow
+    /// @param raisedBy Address raising dispute
+    event DisputeRaised(uint256 indexed escrowId, address indexed raisedBy);
+
+    /// @notice Emitted when dispute is resolved
+    /// @param escrowId ID of the escrow
+    /// @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) {
+        require(_arbiterFeePercent <= 10, "Fee too high");
+        owner = msg.sender;
+        arbiterFeePercent = _arbiterFeePercent;
+    }
+
+    // ==================== ESCROW CREATION ====================
+
+    /// @notice Create a new escrow with encrypted amount
+    /// @param seller Address of the seller
+    /// @param arbiter Address of dispute arbiter
+    /// @param encryptedAmount Encrypted escrow amount
+    /// @param inputProof Proof validating the encrypted input
+    /// @param deadline Deadline timestamp for delivery
+    /// @return escrowId The ID of created escrow
+    function createEscrow(
+        address seller,
+        address arbiter,
+        externalEuint64 encryptedAmount,
+        bytes calldata inputProof,
+        uint256 deadline
+    ) external returns (uint256 escrowId) {
+        require(seller != address(0), "Invalid seller");
+        require(seller != msg.sender, "Buyer cannot be seller");
+        require(arbiter != address(0), "Invalid arbiter");
+        require(arbiter != msg.sender && arbiter != seller, "Invalid arbiter");
+        require(deadline > block.timestamp, "Deadline must be future");
+
+        escrowId = ++escrowCount;
+
+        // 🔐 Convert external encrypted input
+        euint64 amount = FHE.fromExternal(encryptedAmount, inputProof);
+
+        // ✅ Grant permissions
+        FHE.allowThis(amount);
+        FHE.allow(amount, msg.sender); // Buyer can view
+        FHE.allow(amount, seller); // Seller can view
+        FHE.allow(amount, arbiter); // Arbiter can view
+
+        _escrows[escrowId] = Escrow({
+            buyer: msg.sender,
+            seller: seller,
+            arbiter: arbiter,
+            encryptedAmount: amount,
+            depositedAmount: 0,
+            state: EscrowState.Created,
+            createdAt: block.timestamp,
+            deadline: deadline
+        });
+
+        emit EscrowCreated(escrowId, msg.sender, seller);
+    }
+
+    /// @notice Fund the escrow
+    /// @dev Amount verified against encrypted value on release
+    /// @param escrowId ID of escrow to fund
+    function fundEscrow(uint256 escrowId) external payable {
+        Escrow storage escrow = _escrows[escrowId];
+        require(escrow.buyer == msg.sender, "Only buyer can fund");
+        require(escrow.state == EscrowState.Created, "Invalid state");
+        require(msg.value > 0, "Must send funds");
+
+        escrow.depositedAmount = msg.value;
+        escrow.state = EscrowState.Funded;
+
+        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
+    function release(uint256 escrowId) external {
+        Escrow storage escrow = _escrows[escrowId];
+        require(escrow.buyer == msg.sender, "Only buyer can release");
+        require(escrow.state == EscrowState.Funded, "Not funded");
+
+        uint256 amount = escrow.depositedAmount;
+        escrow.depositedAmount = 0;
+        escrow.state = EscrowState.Released;
+
+        // Transfer to seller
+        (bool sent, ) = escrow.seller.call{value: amount}("");
+        require(sent, "Transfer failed");
+
+        emit FundsReleased(escrowId, escrow.seller);
+    }
+
+    /// @notice Request refund (before deadline or after timeout)
+    /// @param escrowId ID of escrow
+    function requestRefund(uint256 escrowId) external {
+        Escrow storage escrow = _escrows[escrowId];
+        require(escrow.buyer == msg.sender, "Only buyer");
+        require(escrow.state == EscrowState.Funded, "Not funded");
+        require(block.timestamp > escrow.deadline, "Deadline not passed");
+
+        uint256 amount = escrow.depositedAmount;
+        escrow.depositedAmount = 0;
+        escrow.state = EscrowState.Refunded;
+
+        (bool sent, ) = escrow.buyer.call{value: amount}("");
+        require(sent, "Transfer failed");
+
+        emit FundsRefunded(escrowId, escrow.buyer);
+    }
+
+    // ==================== DISPUTE RESOLUTION ====================
+
+    /// @notice Raise a dispute
+    /// @param escrowId ID of escrow
+    function raiseDispute(uint256 escrowId) external {
+        Escrow storage escrow = _escrows[escrowId];
+        require(
+            escrow.buyer == msg.sender || escrow.seller == msg.sender,
+            "Not a party"
+        );
+        require(escrow.state == EscrowState.Funded, "Not funded");
+
+        escrow.state = EscrowState.Disputed;
+
+        emit DisputeRaised(escrowId, msg.sender);
+    }
+
+    /// @notice Resolve dispute - arbiter decides winner
+    /// @param escrowId ID of escrow
+    /// @param favorBuyer True to refund buyer, false to release to seller
+    function resolveDispute(uint256 escrowId, bool favorBuyer) external {
+        Escrow storage escrow = _escrows[escrowId];
+        require(escrow.arbiter == msg.sender, "Only arbiter");
+        require(escrow.state == EscrowState.Disputed, "Not disputed");
+
+        uint256 amount = escrow.depositedAmount;
+        uint256 arbiterFee = (amount * arbiterFeePercent) / 100;
+        uint256 payout = amount - arbiterFee;
+
+        escrow.depositedAmount = 0;
+
+        address winner;
+        if (favorBuyer) {
+            escrow.state = EscrowState.Refunded;
+            winner = escrow.buyer;
+        } else {
+            escrow.state = EscrowState.Released;
+            winner = escrow.seller;
+        }
+
+        // Pay arbiter fee
+        if (arbiterFee > 0) {
+            (bool feeSent, ) = escrow.arbiter.call{value: arbiterFee}("");
+            require(feeSent, "Arbiter fee failed");
+        }
+
+        // Pay winner
+        (bool sent, ) = winner.call{value: payout}("");
+        require(sent, "Payout failed");
+
+        emit DisputeResolved(escrowId, winner);
+    }
+
+    // ==================== VIEW FUNCTIONS ====================
+
+    /// @notice Get escrow details
+    function getEscrow(
+        uint256 escrowId
+    )
+        external
+        view
+        returns (
+            address buyer,
+            address seller,
+            address arbiter,
+            uint256 depositedAmount,
+            EscrowState state,
+            uint256 createdAt,
+            uint256 deadline
+        )
+    {
+        Escrow storage escrow = _escrows[escrowId];
+        return (
+            escrow.buyer,
+            escrow.seller,
+            escrow.arbiter,
+            escrow.depositedAmount,
+            escrow.state,
+            escrow.createdAt,
+            escrow.deadline
+        );
+    }
+
+    /// @notice Get encrypted amount handle (for permitted parties)
+    function getEncryptedAmount(
+        uint256 escrowId
+    ) external view returns (euint64) {
+        Escrow storage escrow = _escrows[escrowId];
+        require(
+            msg.sender == escrow.buyer ||
+                msg.sender == escrow.seller ||
+                msg.sender == escrow.arbiter,
+            "Not authorized"
+        );
+        return escrow.encryptedAmount;
+    }
+
+    /// @notice Check if deadline has passed
+    function isDeadlinePassed(uint256 escrowId) external view returns (bool) {
+        return block.timestamp > _escrows[escrowId].deadline;
+    }
+}