@openzeppelin/confidential-contracts 0.3.0-rc.0 → 0.3.1

package/token/ERC7984/extensions/ERC7984Freezable.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Confidential Contracts (last updated v0.3.0-rc.0) (token/ERC7984/extensions/ERC7984Freezable.sol)
+// OpenZeppelin Confidential Contracts (last updated v0.3.0) (token/ERC7984/extensions/ERC7984Freezable.sol)
 
 pragma solidity ^0.8.27;
 
@@ -31,8 +31,16 @@ abstract contract ERC7984Freezable is ERC7984 {
         return _frozenBalances[account];
     }
 
-    /// @dev Returns the confidential available (unfrozen) balance of an account. Up to {confidentialBalanceOf}.
+    /// @dev Returns the confidential available (unfrozen) balance of an account. Gives ACL allowance to `account`.
     function confidentialAvailable(address account) public virtual returns (euint64) {
+        euint64 amount = _confidentialAvailable(account);
+        FHE.allowThis(amount);
+        FHE.allow(amount, account);
+        return amount;
+    }
+
+    /// @dev Internal function to calculate the available balance of an account. Does not give any allowances.
+    function _confidentialAvailable(address account) internal virtual returns (euint64) {
         (ebool success, euint64 unfrozen) = FHESafeMath.tryDecrease(
             confidentialBalanceOf(account),
             confidentialFrozen(account)
@@ -54,11 +62,12 @@ abstract contract ERC7984Freezable is ERC7984 {
      * The `from` account must have sufficient unfrozen balance,
      * otherwise 0 tokens are transferred.
      * The default freezing behavior can be changed (for a pass-through for instance) by overriding
-     * {confidentialAvailable}.
+     * {_confidentialAvailable}. The internal function is used for actual gating (not the public function)
+     * to avoid unnecessarily granting ACL allowances.
      */
     function _update(address from, address to, euint64 encryptedAmount) internal virtual override returns (euint64) {
         if (from != address(0)) {
-            euint64 unfrozen = confidentialAvailable(from);
+            euint64 unfrozen = _confidentialAvailable(from);
             encryptedAmount = FHE.select(FHE.le(encryptedAmount, unfrozen), encryptedAmount, FHE.asEuint64(0));
         }
         return super._update(from, to, encryptedAmount);

package/token/ERC7984/extensions/ERC7984ObserverAccess.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Confidential Contracts (last updated v0.3.0-rc.0) (token/ERC7984/extensions/ERC7984ObserverAccess.sol)
+// OpenZeppelin Confidential Contracts (last updated v0.3.0) (token/ERC7984/extensions/ERC7984ObserverAccess.sol)
 
 pragma solidity ^0.8.27;
 
@@ -11,7 +11,7 @@ import {ERC7984} from "../ERC7984.sol";
  * permanent ACL access to its transfer and balance amounts. A observer can be added or removed at any point in time.
  */
 abstract contract ERC7984ObserverAccess is ERC7984 {
-    mapping(address => address) private _observers;
+    mapping(address account => address) private _observers;
 
     /// @dev Emitted when the observer is changed for the given account `account`.
     event ERC7984ObserverAccessObserverSet(address account, address oldObserver, address newObserver);

package/token/ERC7984/extensions/ERC7984Omnibus.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Confidential Contracts (last updated v0.3.0-rc.0) (token/ERC7984/extensions/ERC7984Omnibus.sol)
+// OpenZeppelin Confidential Contracts (last updated v0.3.0) (token/ERC7984/extensions/ERC7984Omnibus.sol)
 
 pragma solidity ^0.8.27;
 
@@ -189,8 +189,6 @@ abstract contract ERC7984Omnibus is ERC7984 {
         euint64 amount,
         bytes calldata data
     ) internal virtual returns (euint64) {
-        euint64 transferred = confidentialTransferFromAndCall(omnibusFrom, omnibusTo, amount, data);
-
         FHE.allowThis(sender);
         FHE.allow(sender, omnibusFrom);
         FHE.allow(sender, omnibusTo);
@@ -199,6 +197,8 @@ abstract contract ERC7984Omnibus is ERC7984 {
         FHE.allow(recipient, omnibusFrom);
         FHE.allow(recipient, omnibusTo);
 
+        euint64 transferred = confidentialTransferFromAndCall(omnibusFrom, omnibusTo, amount, data);
+
         FHE.allowThis(transferred);
         FHE.allow(transferred, omnibusFrom);
         FHE.allow(transferred, omnibusTo);

package/token/ERC7984/extensions/ERC7984Restricted.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Confidential Contracts (last updated v0.3.0-rc.0) (token/ERC7984/extensions/ERC7984Restricted.sol)
+// OpenZeppelin Confidential Contracts (last updated v0.3.0) (token/ERC7984/extensions/ERC7984Restricted.sol)
 
 pragma solidity ^0.8.27;
 
@@ -38,14 +38,6 @@ abstract contract ERC7984Restricted is ERC7984 {
      * @dev Returns whether a user account is allowed to interact with the token.
      *
      * Default implementation only disallows explicitly BLOCKED accounts (i.e. a blocklist).
-     *
-     * To convert into an allowlist, override as:
-     *
-     * ```solidity
-     * function isUserAllowed(address account) public view virtual override returns (bool) {
-     *     return getRestriction(account) == Restriction.ALLOWED;
-     * }
-     * ```
      */
     function isUserAllowed(address account) public view virtual returns (bool) {
         return getRestriction(account) != Restriction.BLOCKED; // i.e. DEFAULT && ALLOWED
@@ -59,7 +51,7 @@ abstract contract ERC7984Restricted is ERC7984 {
      * * `from` must be allowed to transfer tokens (see {isUserAllowed}).
      * * `to` must be allowed to receive tokens (see {isUserAllowed}).
      *
-     * The default restriction behaviour can be changed (for a pass-through for instance) by overriding
+     * The default restriction behavior can be changed (for a pass-through for instance) by overriding
      * {_checkSenderRestriction} and/or {_checkRecipientRestriction}.
      */
     function _update(address from, address to, euint64 value) internal virtual override returns (euint64) {
@@ -91,7 +83,7 @@ abstract contract ERC7984Restricted is ERC7984 {
         _setRestriction(account, Restriction.DEFAULT);
     }
 
-    /// @dev Checks if a user account is restricted. Reverts with {ERC20Restricted} if so.
+    /// @dev Checks if a user account is restricted. Reverts with {UserRestricted} if so.
     function _checkRestriction(address account) internal view virtual {
         require(isUserAllowed(account), UserRestricted(account));
     }

package/token/ERC7984/extensions/ERC7984Rwa.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Confidential Contracts (last updated v0.3.0-rc.0) (token/ERC7984/extensions/ERC7984Rwa.sol)
+// OpenZeppelin Confidential Contracts (last updated v0.3.0) (token/ERC7984/extensions/ERC7984Rwa.sol)
 
 pragma solidity ^0.8.27;
 
@@ -11,7 +11,6 @@ import {Multicall} from "@openzeppelin/contracts/utils/Multicall.sol";
 import {Pausable} from "@openzeppelin/contracts/utils/Pausable.sol";
 import {IERC7984} from "./../../../interfaces/IERC7984.sol";
 import {IERC7984Rwa} from "./../../../interfaces/IERC7984Rwa.sol";
-import {FHESafeMath} from "./../../../utils/FHESafeMath.sol";
 import {ERC7984} from "./../ERC7984.sol";
 import {ERC7984Freezable} from "./ERC7984Freezable.sol";
 import {ERC7984Restricted} from "./ERC7984Restricted.sol";
@@ -20,15 +19,17 @@ import {ERC7984Restricted} from "./ERC7984Restricted.sol";
  * @dev Extension of {ERC7984} that supports confidential Real World Assets (RWAs).
  * This interface provides compliance checks, transfer controls and enforcement actions.
  */
-abstract contract ERC7984Rwa is
-    IERC7984Rwa,
-    ERC7984Freezable,
-    ERC7984Restricted,
-    Pausable,
-    Multicall,
-    ERC165,
-    AccessControl
-{
+abstract contract ERC7984Rwa is IERC7984Rwa, ERC7984Freezable, ERC7984Restricted, Pausable, Multicall, AccessControl {
+    /**
+     * @dev Accounts granted the agent role have the following permissioned abilities:
+     *
+     * - Mint/Burn to/from a given address (does not require permission)
+     * - Force transfer from a given address (does not require permission)
+     *   - Bypasses pause and restriction checks (not frozen)
+     * - Pause/Unpause the contract
+     * - Block/Unblock a given account
+     * - Set frozen amount of tokens for a given account.
+     */
     bytes32 public constant AGENT_ROLE = keccak256("AGENT_ROLE");
 
     /// @dev Checks if the sender is an admin.
@@ -50,11 +51,8 @@ abstract contract ERC7984Rwa is
     /// @inheritdoc ERC165
     function supportsInterface(
         bytes4 interfaceId
-    ) public view virtual override(IERC165, ERC165, AccessControl) returns (bool) {
-        return
-            interfaceId == type(IERC7984Rwa).interfaceId ||
-            interfaceId == type(IERC7984).interfaceId ||
-            super.supportsInterface(interfaceId);
+    ) public view virtual override(IERC165, ERC7984, AccessControl) returns (bool) {
+        return interfaceId == type(IERC7984Rwa).interfaceId || super.supportsInterface(interfaceId);
     }
 
     /// @dev Returns true if has admin role, false otherwise.
@@ -94,10 +92,10 @@ abstract contract ERC7984Rwa is
 
     /// @dev Unblocks a user account.
     function unblockUser(address account) public virtual onlyAgent {
-        _allowUser(account);
+        _resetUser(account);
     }
 
-    /// @dev Sets confidential frozen for an account.
+    /// @dev Sets confidential frozen for an account with proof.
     function setConfidentialFrozen(
         address account,
         externalEuint64 encryptedAmount,
@@ -106,7 +104,7 @@ abstract contract ERC7984Rwa is
         _setConfidentialFrozen(account, FHE.fromExternal(encryptedAmount, inputProof));
     }
 
-    /// @dev Sets confidential frozen for an account with proof.
+    /// @dev Sets confidential frozen for an account.
     function setConfidentialFrozen(address account, euint64 encryptedAmount) public virtual onlyAgent {
         require(
             FHE.isAllowed(encryptedAmount, msg.sender),
@@ -121,7 +119,9 @@ abstract contract ERC7984Rwa is
         externalEuint64 encryptedAmount,
         bytes calldata inputProof
     ) public virtual onlyAgent returns (euint64) {
-        return _mint(to, FHE.fromExternal(encryptedAmount, inputProof));
+        euint64 mintedAmount = _mint(to, FHE.fromExternal(encryptedAmount, inputProof));
+        FHE.allow(mintedAmount, msg.sender);
+        return mintedAmount;
     }
 
     /// @dev Mints confidential amount of tokens to account.
@@ -130,7 +130,9 @@ abstract contract ERC7984Rwa is
             FHE.isAllowed(encryptedAmount, msg.sender),
             ERC7984UnauthorizedUseOfEncryptedAmount(encryptedAmount, msg.sender)
         );
-        return _mint(to, encryptedAmount);
+        euint64 mintedAmount = _mint(to, encryptedAmount);
+        FHE.allow(mintedAmount, msg.sender);
+        return mintedAmount;
     }
 
     /// @dev Burns confidential amount of tokens from account with proof.
@@ -139,7 +141,9 @@ abstract contract ERC7984Rwa is
         externalEuint64 encryptedAmount,
         bytes calldata inputProof
     ) public virtual onlyAgent returns (euint64) {
-        return _burn(account, FHE.fromExternal(encryptedAmount, inputProof));
+        euint64 burntAmount = _burn(account, FHE.fromExternal(encryptedAmount, inputProof));
+        FHE.allow(burntAmount, msg.sender);
+        return burntAmount;
     }
 
     /// @dev Burns confidential amount of tokens from account.
@@ -148,10 +152,12 @@ abstract contract ERC7984Rwa is
             FHE.isAllowed(encryptedAmount, msg.sender),
             ERC7984UnauthorizedUseOfEncryptedAmount(encryptedAmount, msg.sender)
         );
-        return _burn(account, encryptedAmount);
+        euint64 burntAmount = _burn(account, encryptedAmount);
+        FHE.allow(burntAmount, msg.sender);
+        return burntAmount;
     }
 
-    /// @dev Forces transfer of confidential amount of tokens from account to account with proof by skipping compliance checks.
+    /// @dev Variant of {forceConfidentialTransferFrom-address-address-euint64} with an input proof.
     function forceConfidentialTransferFrom(
         address from,
         address to,
@@ -161,7 +167,11 @@ abstract contract ERC7984Rwa is
         return _forceUpdate(from, to, FHE.fromExternal(encryptedAmount, inputProof));
     }
 
-    /// @dev Forces transfer of confidential amount of tokens from account to account by skipping compliance checks.
+    /**
+     * @dev Force transfer callable by the role {AGENT_ROLE} which transfers tokens from `from` to `to` and
+     * bypasses the {ERC7984Restricted} (only on from) and https://docs.openzeppelin.com/contracts/api/utils#pausable[`++Pausable++`]
+     * checks. Frozen tokens are not transferred and must be unfrozen first.
+     */
     function forceConfidentialTransferFrom(
         address from,
         address to,
@@ -214,7 +224,9 @@ abstract contract ERC7984Rwa is
     function _forceUpdate(address from, address to, euint64 encryptedAmount) internal virtual returns (euint64) {
         // bypassing `from` restriction check with {_checkSenderRestriction}. Still performing `to` restriction check.
         // bypassing paused state by directly calling `super._update`
-        return super._update(from, to, encryptedAmount);
+        euint64 transferred = super._update(from, to, encryptedAmount);
+        FHE.allow(transferred, msg.sender);
+        return transferred;
     }
 
     /**

package/token/ERC7984/extensions/ERC7984Votes.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Confidential Contracts (last updated v0.3.0-rc.0) (token/ERC7984/extensions/ERC7984Votes.sol)
+// OpenZeppelin Confidential Contracts (last updated v0.3.0) (token/ERC7984/extensions/ERC7984Votes.sol)
 pragma solidity ^0.8.27;
 
 import {euint64} from "@fhevm/solidity/lib/FHE.sol";

package/token/ERC7984/utils/ERC7984Utils.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Confidential Contracts (last updated v0.3.0-rc.0) (token/ERC7984/utils/ERC7984Utils.sol)
+// OpenZeppelin Confidential Contracts (last updated v0.3.0) (token/ERC7984/utils/ERC7984Utils.sol)
 pragma solidity ^0.8.27;
 
 import {FHE, ebool, euint64} from "@fhevm/solidity/lib/FHE.sol";
@@ -16,7 +16,8 @@ library ERC7984Utils {
      * The transfer callback is not invoked on the recipient if the recipient has no code (i.e. is an EOA). If the
      * recipient has non-zero code, it must implement
      * {IERC7984Receiver-onConfidentialTransferReceived} and return an `ebool` indicating
-     * whether the transfer was accepted or not. If the `ebool` is `false`, the transfer will be reversed.
+     * whether the transfer was accepted or not. If the `ebool` is `false`, the transfer function
+     * should try to refund the `from` address.
      */
     function checkOnTransferReceived(
         address operator,

package/utils/FHESafeMath.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Confidential Contracts (last updated v0.3.0-rc.0) (utils/FHESafeMath.sol)
+// OpenZeppelin Confidential Contracts (last updated v0.3.0) (utils/FHESafeMath.sol)
 pragma solidity ^0.8.24;
 
 import {FHE, ebool, euint64} from "@fhevm/solidity/lib/FHE.sol";
@@ -7,6 +7,9 @@ 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.
+ *
+ * NOTE: An uninitialized `euint64` value (equivalent to euint64.wrap(bytes32(0))) is evaluated as 0.
+ * This library will may return an uninitialized value if all inputs are uninitialized.
  */
 library FHESafeMath {
     /**
@@ -33,7 +36,7 @@ library FHESafeMath {
             if (!FHE.isInitialized(delta)) {
                 return (FHE.asEbool(true), oldValue);
             }
-            return (FHE.eq(oldValue, delta), oldValue);
+            return (FHE.eq(delta, 0), FHE.asEuint64(0));
         }
         success = FHE.ge(oldValue, delta);
         updated = FHE.select(success, FHE.sub(oldValue, delta), oldValue);

package/utils/structs/temporary-Checkpoints.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Confidential Contracts (last updated v0.3.0-rc.0) (utils/structs/temporary-Checkpoints.sol)
+// OpenZeppelin Confidential Contracts (last updated v0.3.0) (utils/structs/temporary-Checkpoints.sol)
 // OpenZeppelin Contracts (last updated v5.4.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.