@openzeppelin/confidential-contracts 0.2.0-rc.1 → 0.2.0

package/governance/utils/VotesConfidential.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Confidential Contracts (last updated v0.2.0-rc.1) (governance/utils/VotesConfidential.sol)
+// OpenZeppelin Confidential Contracts (last updated v0.2.0) (governance/utils/VotesConfidential.sol)
 pragma solidity ^0.8.24;
 
 import {FHE, ebool, euint64} from "@fhevm/solidity/lib/FHE.sol";
@@ -9,9 +9,25 @@ import {EIP712} from "@openzeppelin/contracts/utils/cryptography/EIP712.sol";
 import {SafeCast} from "@openzeppelin/contracts/utils/math/SafeCast.sol";
 import {Nonces} from "@openzeppelin/contracts/utils/Nonces.sol";
 import {Time} from "@openzeppelin/contracts/utils/types/Time.sol";
+import {HandleAccessManager} from "./../../utils/HandleAccessManager.sol";
 import {CheckpointsConfidential} from "./../../utils/structs/CheckpointsConfidential.sol";
 
-abstract contract VotesConfidential is Nonces, EIP712, IERC6372 {
+/**
+ * @dev A confidential votes contract tracking confidential voting power of accounts over time.
+ * It features vote delegation to delegators.
+
+ * This contract keeps a history (checkpoints) of each account's confidential vote power. Confidential
+ * voting power can be delegated either by calling the {delegate} function directly, or by providing
+ * a signature to be used with {delegateBySig}. Confidential voting power handles can be queried
+ * through the public accessors {getVotes} and {getPastVotes} but can only be decrypted by accounts
+ * allowed to access them. Ensure that {HandleAccessManager-_validateHandleAllowance} is implemented properly, allowing all 
+ * necessary addresses to access voting power handles.
+ *
+ * By default, voting units does not account for voting power. This makes transfers of underlying
+ * voting units cheaper. The downside is that it requires users to delegate to themselves in order
+ * to activate checkpoints and have their voting power tracked.
+ */
+abstract contract VotesConfidential is Nonces, EIP712, IERC6372, HandleAccessManager {
     using FHE for *;
     using CheckpointsConfidential for CheckpointsConfidential.TraceEuint64;
 
@@ -168,7 +184,6 @@ abstract contract VotesConfidential is Nonces, EIP712, IERC6372 {
                 store = _delegateCheckpoints[from];
                 euint64 newValue = store.latest().sub(amount);
                 newValue.allowThis();
-                newValue.allow(from);
                 euint64 oldValue = _push(store, newValue);
                 emit DelegateVotesChanged(from, oldValue, newValue);
             }
@@ -176,7 +191,6 @@ abstract contract VotesConfidential is Nonces, EIP712, IERC6372 {
                 store = _delegateCheckpoints[to];
                 euint64 newValue = store.latest().add(amount);
                 newValue.allowThis();
-                newValue.allow(to);
                 euint64 oldValue = _push(store, newValue);
                 emit DelegateVotesChanged(to, oldValue, newValue);
             }

package/interfaces/IConfidentialFungibleToken.sol

@@ -1,10 +1,10 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Confidential Contracts (last updated v0.2.0-rc.1) (interfaces/IConfidentialFungibleToken.sol)
+// OpenZeppelin Confidential Contracts (last updated v0.2.0) (interfaces/IConfidentialFungibleToken.sol)
 pragma solidity ^0.8.24;
 
 import {euint64, externalEuint64} from "@fhevm/solidity/lib/FHE.sol";
 
-/// @dev Draft interface for a confidential fungible token standard utilizing the Zama TFHE library.
+/// @dev Draft interface for a confidential fungible token standard utilizing the Zama FHE library.
 interface IConfidentialFungibleToken {
     /**
      * @dev Emitted when the expiration timestamp for an operator `operator` is updated for a given `holder`.

package/interfaces/IConfidentialFungibleTokenReceiver.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Confidential Contracts (last updated v0.2.0-rc.1) (interfaces/IConfidentialFungibleTokenReceiver.sol)
+// OpenZeppelin Confidential Contracts (last updated v0.2.0) (interfaces/IConfidentialFungibleTokenReceiver.sol)
 pragma solidity ^0.8.24;
 
 import {ebool, euint64} from "@fhevm/solidity/lib/FHE.sol";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@openzeppelin/confidential-contracts",
   "description": "Smart Contract library for use with confidential coprocessors",
-  "version": "0.2.0-rc.1",
+  "version": "0.2.0",
   "files": [
     "**/*.sol",
     "/build/contracts/*.json",

package/token/ConfidentialFungibleToken.sol

@@ -1,10 +1,10 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Confidential Contracts (last updated v0.2.0-rc.1) (token/ConfidentialFungibleToken.sol)
+// OpenZeppelin Confidential Contracts (last updated v0.2.0) (token/ConfidentialFungibleToken.sol)
 pragma solidity ^0.8.27;
 
 import {FHE, externalEuint64, ebool, euint64} from "@fhevm/solidity/lib/FHE.sol";
 import {IConfidentialFungibleToken} from "./../interfaces/IConfidentialFungibleToken.sol";
-import {TFHESafeMath} from "./../utils/TFHESafeMath.sol";
+import {FHESafeMath} from "./../utils/FHESafeMath.sol";
 import {ConfidentialFungibleTokenUtils} from "./utils/ConfidentialFungibleTokenUtils.sol";
 
 /**
@@ -220,7 +220,7 @@ abstract contract ConfidentialFungibleToken is IConfidentialFungibleToken {
         _requestHandles[requestID] = encryptedAmount;
     }
 
-    /// @dev May only be called by the gateway contract. Finalizes a disclose encrypted amount request.
+    /// @dev Finalizes a disclose encrypted amount request.
     function finalizeDiscloseEncryptedAmount(
         uint256 requestId,
         uint64 amount,
@@ -266,14 +266,11 @@ abstract contract ConfidentialFungibleToken is IConfidentialFungibleToken {
         euint64 sent = _transfer(from, to, amount);
 
         // Perform callback
-        transferred = FHE.select(
-            ConfidentialFungibleTokenUtils.checkOnTransferReceived(msg.sender, from, to, sent, data),
-            sent,
-            FHE.asEuint64(0)
-        );
+        ebool success = ConfidentialFungibleTokenUtils.checkOnTransferReceived(msg.sender, from, to, sent, data);
 
-        // Refund if success fails. refund should never fail
-        _update(to, from, FHE.sub(sent, transferred));
+        // Try to refund if callback fails
+        euint64 refund = _update(to, from, FHE.select(success, FHE.asEuint64(0), sent));
+        transferred = FHE.sub(sent, refund);
     }
 
     function _update(address from, address to, euint64 amount) internal virtual returns (euint64 transferred) {
@@ -281,13 +278,13 @@ abstract contract ConfidentialFungibleToken is IConfidentialFungibleToken {
         euint64 ptr;
 
         if (from == address(0)) {
-            (success, ptr) = TFHESafeMath.tryIncrease(_totalSupply, amount);
+            (success, ptr) = FHESafeMath.tryIncrease(_totalSupply, amount);
             FHE.allowThis(ptr);
             _totalSupply = ptr;
         } else {
             euint64 fromBalance = _balances[from];
             require(FHE.isInitialized(fromBalance), ConfidentialFungibleTokenZeroBalance(from));
-            (success, ptr) = TFHESafeMath.tryDecrease(fromBalance, amount);
+            (success, ptr) = FHESafeMath.tryDecrease(fromBalance, amount);
             FHE.allowThis(ptr);
             FHE.allow(ptr, from);
             _balances[from] = ptr;

package/token/extensions/ConfidentialFungibleTokenERC20Wrapper.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Confidential Contracts (last updated v0.2.0-rc.1) (token/extensions/ConfidentialFungibleTokenERC20Wrapper.sol)
+// OpenZeppelin Confidential Contracts (last updated v0.2.0) (token/extensions/ConfidentialFungibleTokenERC20Wrapper.sol)
 
 pragma solidity ^0.8.27;
 
@@ -15,6 +15,9 @@ import {ConfidentialFungibleToken} from "./../ConfidentialFungibleToken.sol";
  * @dev A wrapper contract built on top of {ConfidentialFungibleToken} that allows wrapping an `ERC20` token
  * into a confidential fungible token. The wrapper contract implements the `IERC1363Receiver` interface
  * which allows users to transfer `ERC1363` tokens directly to the wrapper with a callback to wrap the tokens.
+ *
+ * WARNING: Minting assumes the full amount of the underlying token transfer has been received, hence some non-standard
+ * tokens such as fee-on-transfer or other deflationary-type tokens are not supported by this wrapper.
  */
 abstract contract ConfidentialFungibleTokenERC20Wrapper is ConfidentialFungibleToken, IERC1363Receiver {
     IERC20 private immutable _underlying;
@@ -70,14 +73,14 @@ abstract contract ConfidentialFungibleTokenERC20Wrapper is ConfidentialFungibleT
         // check caller is the token contract
         require(address(underlying()) == msg.sender, ConfidentialFungibleTokenUnauthorizedCaller(msg.sender));
 
-        // transfer excess back to the sender
-        uint256 excess = amount % rate();
-        if (excess > 0) SafeERC20.safeTransfer(underlying(), from, excess);
-
         // mint confidential token
         address to = data.length < 20 ? from : address(bytes20(data));
         _mint(to, FHE.asEuint64(SafeCast.toUint64(amount / rate())));
 
+        // transfer excess back to the sender
+        uint256 excess = amount % rate();
+        if (excess > 0) SafeERC20.safeTransfer(underlying(), from, excess);
+
         // return magic value
         return IERC1363Receiver.onTransferReceived.selector;
     }
@@ -125,8 +128,7 @@ abstract contract ConfidentialFungibleTokenERC20Wrapper is ConfidentialFungibleT
     }
 
     /**
-     * @dev Called by the fhEVM gateway with the decrypted amount `amount` for a request id `requestId`.
-     * Fills unwrap requests.
+     * @dev Fills an unwrap request for a given request id related to a decrypted unwrap amount.
      */
     function finalizeUnwrap(uint256 requestID, uint64 amount, bytes[] memory signatures) public virtual {
         FHE.checkSignatures(requestID, signatures);
@@ -156,6 +158,15 @@ abstract contract ConfidentialFungibleTokenERC20Wrapper is ConfidentialFungibleT
         _receivers[requestID] = to;
     }
 
+    /**
+     * @dev Returns the default number of decimals of the underlying ERC-20 token that is being wrapped.
+     * Used as a default fallback when {_tryGetAssetDecimals} fails to fetch decimals of the underlying
+     * ERC-20 token.
+     */
+    function _fallbackUnderlyingDecimals() internal pure virtual returns (uint8) {
+        return 18;
+    }
+
     /**
      * @dev Returns the maximum number that will be used for {decimals} by the wrapper.
      */
@@ -170,6 +181,6 @@ abstract contract ConfidentialFungibleTokenERC20Wrapper is ConfidentialFungibleT
         if (success && encodedDecimals.length == 32) {
             return abi.decode(encodedDecimals, (uint8));
         }
-        return 18;
+        return _fallbackUnderlyingDecimals();
     }
 }

package/token/extensions/ConfidentialFungibleTokenVotes.sol

@@ -1,12 +1,20 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Confidential Contracts (last updated v0.2.0-rc.1) (token/extensions/ConfidentialFungibleTokenVotes.sol)
+// OpenZeppelin Confidential Contracts (last updated v0.2.0) (token/extensions/ConfidentialFungibleTokenVotes.sol)
 pragma solidity ^0.8.27;
 
 import {euint64} from "@fhevm/solidity/lib/FHE.sol";
 import {VotesConfidential} from "./../../governance/utils/VotesConfidential.sol";
 import {ConfidentialFungibleToken} from "./../ConfidentialFungibleToken.sol";
 
+/**
+ * @dev Extension of {ConfidentialFungibleToken} supporting confidential votes tracking and delegation.
+ *
+ * The amount of confidential voting units an account has is equal to the confidential token balance of
+ * that account. Voing power is taken into account when an account delegates votes to itself or to another
+ * account.
+ */
 abstract contract ConfidentialFungibleTokenVotes is ConfidentialFungibleToken, VotesConfidential {
+    /// @inheritdoc ConfidentialFungibleToken
     function confidentialTotalSupply()
         public
         view

package/token/utils/ConfidentialFungibleTokenUtils.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Confidential Contracts (last updated v0.2.0-rc.1) (token/utils/ConfidentialFungibleTokenUtils.sol)
+// OpenZeppelin Confidential Contracts (last updated v0.2.0) (token/utils/ConfidentialFungibleTokenUtils.sol)
 pragma solidity ^0.8.24;
 
 import {FHE, ebool, euint64} from "@fhevm/solidity/lib/FHE.sol";

package/utils/{TFHESafeMath.sol → FHESafeMath.sol}

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Confidential Contracts (last updated v0.2.0-rc.1) (utils/TFHESafeMath.sol)
+// OpenZeppelin Confidential Contracts (last updated v0.2.0) (utils/FHESafeMath.sol)
 pragma solidity ^0.8.24;
 
 import {FHE, ebool, euint64} from "@fhevm/solidity/lib/FHE.sol";
@@ -8,7 +8,7 @@ import {FHE, ebool, euint64} from "@fhevm/solidity/lib/FHE.sol";
  * @dev Library providing safe arithmetic operations for encrypted values
  * to handle potential overflows in FHE operations.
  */
-library TFHESafeMath {
+library FHESafeMath {
     /**
      * @dev Try to increase the encrypted value `oldValue` by `delta`. If the operation is successful,
      * `success` will be true and `updated` will be the new value. Otherwise, `success` will be false

package/utils/HandleAccessManager.sol

@@ -0,0 +1,29 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Confidential Contracts (last updated v0.2.0) (utils/HandleAccessManager.sol)
+pragma solidity ^0.8.24;
+
+import {Impl} from "@fhevm/solidity/lib/Impl.sol";
+
+abstract contract HandleAccessManager {
+    /**
+     * @dev Get handle access for the given handle `handle`. Access will be given to the
+     * account `account` with the given persistence flag.
+     *
+     * NOTE: This function call is gated by `msg.sender` and validated by the
+     * {_validateHandleAllowance} function.
+     */
+    function getHandleAllowance(bytes32 handle, address account, bool persistent) public virtual {
+        _validateHandleAllowance(handle);
+        if (persistent) {
+            Impl.allow(handle, account);
+        } else {
+            Impl.allowTransient(handle, account);
+        }
+    }
+
+    /**
+     * @dev Unimplemented function that must revert if the message sender is not allowed to call
+     * {getHandleAllowance} for the given handle.
+     */
+    function _validateHandleAllowance(bytes32 handle) internal view virtual;
+}

package/utils/structs/CheckpointsConfidential.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Confidential Contracts (last updated v0.2.0-rc.1) (utils/structs/CheckpointsConfidential.sol)
+// OpenZeppelin Confidential Contracts (last updated v0.2.0) (utils/structs/CheckpointsConfidential.sol)
 // This file was procedurally generated from scripts/generate/templates/CheckpointsConfidential.js.
 
 pragma solidity ^0.8.24;
@@ -18,11 +18,6 @@ import {Checkpoints} from "./temporary-Checkpoints.sol";
 library CheckpointsConfidential {
     using Checkpoints for Checkpoints.Trace256;
 
-    /**
-     * @dev A value was attempted to be inserted on a past checkpoint.
-     */
-    error CheckpointUnorderedInsertion();
-
     struct TraceEuint32 {
         Checkpoints.Trace256 _inner;
     }

package/utils/structs/temporary-Checkpoints.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Confidential Contracts (last updated v0.2.0-rc.1) (utils/structs/temporary-Checkpoints.sol)
+// OpenZeppelin Confidential Contracts (last updated v0.2.0) (utils/structs/temporary-Checkpoints.sol)
 // OpenZeppelin Contracts (last updated v5.3.0) (utils/structs/Checkpoints.sol)
 // This file was procedurally generated from scripts/generate/templates/Checkpoints.js.
 // WARNING: This file is temporary and will be deleted once the latest version of the file is released in v5.5.0 of @openzeppelin/contracts.