Add extension ERC7984Hooked that calls hooks before and after transfer

.changeset/wet-results-doubt.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-confidential-contracts': minor
+---
+
+`ERC7984Hooked`: Call external hooks before and after transfer of confidential tokens.

contracts/interfaces/IERC7984HookModule.sol

@@ -0,0 +1,28 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.24;
+
+import {euint64, ebool} from "@fhevm/solidity/lib/FHE.sol";
+import {IERC165} from "@openzeppelin/contracts/interfaces/IERC165.sol";
+
+/// @dev Interface for an ERC-7984 hook module.
+interface IERC7984HookModule is IERC165 {
+    /**
+     * @dev Hook that runs before a transfer. Should be non-mutating. Transient access is already granted
+     * to the module for `encryptedAmount`.
+     */
+    function preTransfer(address from, address to, euint64 encryptedAmount) external returns (ebool);
+
+    /// @dev Performs operation after transfer.
+    function postTransfer(address from, address to, euint64 encryptedAmount) external;
+
+    /// @dev Performs operations after installation.
+    function onInstall(bytes calldata initData) external;
+
+    /**
+     * @dev Performs operations after uninstallation.
+     *
+     * NOTE: The module uninstallation will succeed even if the function reverts.
+     */
+    function onUninstall(bytes calldata deinitData) external;
+}

contracts/interfaces/IERC7984Rwa.sol

@@ -9,51 +9,72 @@ import {IERC7984} from "./IERC7984.sol";
 interface IERC7984Rwa is IERC7984 {
     /// @dev Returns true if the contract is paused, false otherwise.
     function paused() external view returns (bool);
+
+    /// @dev Returns true if has admin role, false otherwise.
+    function isAdmin(address account) external view returns (bool);
+
+    /// @dev Returns true if agent, false otherwise.
+    function isAgent(address account) external view returns (bool);
+
     /// @dev Returns whether an account is allowed to interact with the token.
     function canTransact(address account) external view returns (bool);
+
     /// @dev Returns the confidential frozen balance of an account.
     function confidentialFrozen(address account) external view returns (euint64);
+
     /// @dev Returns the confidential available (unfrozen) balance of an account. Up to {IERC7984-confidentialBalanceOf}.
     function confidentialAvailable(address account) external returns (euint64);
+
     /// @dev Pauses contract.
     function pause() external;
+
     /// @dev Unpauses contract.
     function unpause() external;
+
     /// @dev Blocks a user account.
     function blockUser(address account) external;
+
     /// @dev Unblocks a user account.
     function unblockUser(address account) external;
+
     /// @dev Sets confidential amount of token for an account as frozen with proof.
     function setConfidentialFrozen(
         address account,
         externalEuint64 encryptedAmount,
         bytes calldata inputProof
     ) external;
+
     /// @dev Sets confidential amount of token for an account as frozen.
     function setConfidentialFrozen(address account, euint64 encryptedAmount) external;
+
     /// @dev Mints confidential amount of tokens to account with proof.
     function confidentialMint(
         address to,
         externalEuint64 encryptedAmount,
         bytes calldata inputProof
     ) external returns (euint64);
+
     /// @dev Mints confidential amount of tokens to account.
     function confidentialMint(address to, euint64 encryptedAmount) external returns (euint64);
+
     /// @dev Burns confidential amount of tokens from account with proof.
     function confidentialBurn(
         address account,
         externalEuint64 encryptedAmount,
         bytes calldata inputProof
     ) external returns (euint64);
+
     /// @dev Burns confidential amount of tokens from account.
     function confidentialBurn(address account, euint64 encryptedAmount) external returns (euint64);
+
     /// @dev Forces transfer of confidential amount of tokens from account to account with proof by skipping compliance checks.
     function forceConfidentialTransferFrom(
         address from,
         address to,
         externalEuint64 encryptedAmount,
         bytes calldata inputProof
     ) external returns (euint64);
+
     /// @dev Forces transfer of confidential amount of tokens from account to account by skipping compliance checks.
     function forceConfidentialTransferFrom(
         address from,

contracts/mocks/token/ERC7984/extensions/ERC7984HookedMock.sol

@@ -0,0 +1,27 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.24;
+
+import {euint64} from "@fhevm/solidity/lib/FHE.sol";
+import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";
+import {ERC7984Hooked} from "../../../../token/ERC7984/extensions/ERC7984Hooked.sol";
+import {ERC7984Mock} from "../../ERC7984Mock.sol";
+
+contract ERC7984HookedMock is ERC7984Hooked, ERC7984Mock, Ownable {
+    constructor(
+        string memory name,
+        string memory symbol,
+        string memory tokenUri,
+        address admin
+    ) ERC7984Mock(name, symbol, tokenUri) Ownable(admin) {}
+
+    function _update(
+        address from,
+        address to,
+        euint64 amount
+    ) internal virtual override(ERC7984Mock, ERC7984Hooked) returns (euint64) {
+        return super._update(from, to, amount);
+    }
+
+    function _authorizeModuleChange() internal virtual override onlyOwner {}
+}

contracts/mocks/token/ERC7984/utils/ERC7984HookModuleMock.sol

@@ -0,0 +1,58 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.24;
+
+import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
+import {FHE, ebool, euint64} from "@fhevm/solidity/lib/FHE.sol";
+import {IERC7984} from "../../../../interfaces/IERC7984.sol";
+import {ERC7984HookModule} from "../../../../token/ERC7984/utils/ERC7984HookModule.sol";
+
+contract ERC7984HookModuleMock is ERC7984HookModule, ZamaEthereumConfig {
+    bool public isCompliant = true;
+    bool public revertOnUninstall = false;
+
+    event PostTransfer();
+    event PreTransfer();
+
+    event OnInstall(bytes initData);
+    event OnUninstall(bytes deinitData);
+
+    function onInstall(bytes calldata initData) public override {
+        emit OnInstall(initData);
+        super.onInstall(initData);
+    }
+
+    function onUninstall(bytes calldata deinitData) public override {
+        if (revertOnUninstall) {
+            revert("Revert on uninstall");
+        }
+
+        emit OnUninstall(deinitData);
+        super.onUninstall(deinitData);
+    }
+
+    function setIsCompliant(bool isCompliant_) public {
+        isCompliant = isCompliant_;
+    }
+
+    function setRevertOnUninstall(bool revertOnUninstall_) public {
+        revertOnUninstall = revertOnUninstall_;
+    }
+
+    function _preTransfer(address token, address from, address, euint64) internal override returns (ebool) {
+        euint64 fromBalance = IERC7984(token).confidentialBalanceOf(from);
+
+        if (FHE.isInitialized(fromBalance)) {
+            _getTokenHandleAllowance(token, fromBalance);
+            assert(FHE.isAllowed(fromBalance, address(this)));
+        }
+
+        emit PreTransfer();
+        return FHE.asEbool(isCompliant);
+    }
+
+    function _postTransfer(address token, address from, address to, euint64 amount) internal override {
+        emit PostTransfer();
+        super._postTransfer(token, from, to, amount);
+    }
+}

contracts/mocks/token/ERC7984Mock.sol

@@ -37,6 +37,13 @@ contract ERC7984Mock is ERC7984, ZamaEthereumConfig {
         return encryptedAddr;
     }
 
+    function confidentialTransfer(address to, uint64 amount) public returns (euint64) {
+        euint64 ciphertext = FHE.asEuint64(amount);
+        FHE.allowTransient(ciphertext, msg.sender);
+
+        return confidentialTransfer(to, ciphertext);
+    }
+
     function _update(address from, address to, euint64 amount) internal virtual override returns (euint64 transferred) {
         transferred = super._update(from, to, amount);
         FHE.allow(confidentialTotalSupply(), _OWNER);

contracts/token/ERC7984/extensions/ERC7984Hooked.sol

@@ -0,0 +1,157 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.27;
+
+import {FHE, ebool, euint64} from "@fhevm/solidity/lib/FHE.sol";
+import {ERC165Checker} from "@openzeppelin/contracts/utils/introspection/ERC165Checker.sol";
+import {LowLevelCall} from "@openzeppelin/contracts/utils/LowLevelCall.sol";
+import {EnumerableSet} from "@openzeppelin/contracts/utils/structs/EnumerableSet.sol";
+import {IERC7984HookModule} from "./../../../interfaces/IERC7984HookModule.sol";
+import {HandleAccessManager} from "./../../../utils/HandleAccessManager.sol";
+import {ERC7984} from "./../ERC7984.sol";
+
+/**
+ * @dev Extension of {ERC7984} that supports hook modules. Inspired by ERC-7579 modules.
+ *
+ * Modules are called before and after transfers. Before the transfer, modules
+ * conduct checks to see if they approve the given transfer and return an encrypted boolean. If any module
+ * returns false, the transferred amount becomes 0. After the transfer, modules are notified of the final transfer
+ * amount and may do accounting as necessary. Modules may revert on either call, which will propagate
+ * and revert the entire transaction.
+ *
+ * NOTE: Hook modules are trusted contracts--they have access to any private state the token has access to.
+ */
+abstract contract ERC7984Hooked is ERC7984, HandleAccessManager {
+    using EnumerableSet for *;
+
+    EnumerableSet.AddressSet private _modules;
+
+    /// @dev Emitted when a module is installed.
+    event ERC7984HookedModuleInstalled(address module);
+    /// @dev Emitted when a module is uninstalled.
+    event ERC7984HookedModuleUninstalled(address module);
+
+    /// @dev The address is not a valid module.
+    error ERC7984HookedInvalidModule(address module);
+    /// @dev The module is already installed.
+    error ERC7984HookedDuplicateModule(address module);
+    /// @dev The module is not installed.
+    error ERC7984HookedNonexistentModule(address module);
+    /// @dev The maximum number of modules has been exceeded.
+    error ERC7984HookedExceededMaxModules();
+
+    modifier onlyAuthorizedModuleChange() {
+        _authorizeModuleChange();
+        _;
+    }
+
+    /// @dev Checks if a module is installed.
+    function isModuleInstalled(address module) public view virtual returns (bool) {
+        return _modules.contains(module);
+    }
+
+    /**
+     * @dev Installs a hook module.
+     *
+     * Consider gas footprint of the module before adding it since all modules will perform
+     * both steps (pre-hook, post-hook) on all transfers.
+     */
+    function installModule(address module, bytes memory initData) public virtual onlyAuthorizedModuleChange {
+        _installModule(module, initData);
+    }
+
+    /// @dev Uninstalls a hook module.
+    function uninstallModule(address module, bytes memory deinitData) public virtual onlyAuthorizedModuleChange {
+        _uninstallModule(module, deinitData);
+    }
+
+    /**
+     * @dev Returns a slice of the list of modules installed on the token with inclusive start and exclusive end.
+     *
+     * TIP: Use an end value of type(uint256).max to get the entire list of modules.
+     */
+    function modules(uint256 start, uint256 end) public view virtual returns (address[] memory) {
+        return _modules.values(start, end);
+    }
+
+    /// @dev Returns the maximum number of modules that can be installed.
+    function maxModules() public view virtual returns (uint256) {
+        return 15;
+    }
+
+    /// @dev Authorization logic for installing and uninstalling modules. Must be implemented by the concrete contract.
+    function _authorizeModuleChange() internal virtual;
+
+    /// @dev Internal function which installs a hook module.
+    function _installModule(address module, bytes memory initData) internal virtual {
+        require(_modules.length() < maxModules(), ERC7984HookedExceededMaxModules());
+        require(
+            ERC165Checker.supportsInterface(module, type(IERC7984HookModule).interfaceId),
+            ERC7984HookedInvalidModule(module)
+        );
+        require(_modules.add(module), ERC7984HookedDuplicateModule(module));
+
+        IERC7984HookModule(module).onInstall(initData);
+
+        emit ERC7984HookedModuleInstalled(module);
+    }
+
+    /// @dev Internal function which uninstalls a module.
+    function _uninstallModule(address module, bytes memory deinitData) internal virtual {
+        require(_modules.remove(module), ERC7984HookedNonexistentModule(module));
+
+        LowLevelCall.callNoReturn(module, abi.encodeCall(IERC7984HookModule.onUninstall, (deinitData)));
+
+        emit ERC7984HookedModuleUninstalled(module);
+    }
+
+    /**
+     * @dev See {ERC7984-_update}.
+     *
+     * Modified to run pre and post transfer hooks. Zero tokens are transferred if a module does not approve
+     * the transfer.
+     */
+    function _update(
+        address from,
+        address to,
+        euint64 encryptedAmount
+    ) internal virtual override returns (euint64 transferred) {
+        euint64 amountToTransfer = FHE.select(
+            _runPreTransferHooks(from, to, encryptedAmount),
+            encryptedAmount,
+            FHE.asEuint64(0)
+        );
+        transferred = super._update(from, to, amountToTransfer);
+        _runPostTransferHooks(from, to, transferred);
+    }
+
+    /// @dev Runs the pre-transfer hooks for all modules.
+    function _runPreTransferHooks(
+        address from,
+        address to,
+        euint64 encryptedAmount
+    ) internal virtual returns (ebool compliant) {
+        address[] memory modules_ = modules(0, type(uint256).max);
+        uint256 modulesLength = modules_.length;
+        compliant = FHE.asEbool(true);
+        for (uint256 i = 0; i < modulesLength; ++i) {
+            if (FHE.isInitialized(encryptedAmount)) FHE.allowTransient(encryptedAmount, modules_[i]);
+            compliant = FHE.and(compliant, IERC7984HookModule(modules_[i]).preTransfer(from, to, encryptedAmount));
+        }
+    }
+
+    /// @dev Runs the post-transfer hooks for all modules.
+    function _runPostTransferHooks(address from, address to, euint64 encryptedAmount) internal virtual {
+        address[] memory modules_ = modules(0, type(uint256).max);
+        uint256 modulesLength = modules_.length;
+        for (uint256 i = 0; i < modulesLength; i++) {
+            if (FHE.isInitialized(encryptedAmount)) FHE.allowTransient(encryptedAmount, modules_[i]);
+            IERC7984HookModule(modules_[i]).postTransfer(from, to, encryptedAmount);
+        }
+    }
+
+    /// @dev See {HandleAccessManager-_validateHandleAllowance}. Allow modules to access any handle the token has access to.
+    function _validateHandleAllowance(bytes32) internal view override returns (bool) {
+        return _modules.contains(msg.sender);
+    }
+}