@openzeppelin/confidential-contracts 0.4.0 → 0.5.0-rc.0

package/token/ERC7984/extensions/ERC7984Hooked.sol

@@ -0,0 +1,158 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Confidential Contracts (last updated v0.5.0-rc.0) (token/ERC7984/extensions/ERC7984Hooked.sol)
+
+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 handle) internal view virtual override returns (bool) {
+        return super._validateHandleAllowance(handle) || _modules.contains(msg.sender);
+    }
+}

package/token/ERC7984/extensions/ERC7984IdentityCheck.sol

@@ -0,0 +1,58 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Confidential Contracts (last updated v0.5.0-rc.0) (token/ERC7984/extensions/ERC7984IdentityCheck.sol)
+
+pragma solidity ^0.8.27;
+
+import {euint64} from "@fhevm/solidity/lib/FHE.sol";
+import {ERC7984} from "../ERC7984.sol";
+
+/**
+ * @dev Extension of {ERC7984} that enforces identity verification
+ * on token recipients by querying an external identity registry.
+ *
+ * See https://github.com/ERC-3643/ERC-3643/blob/main/contracts/registry/interface/IIdentityRegistry.sol[IIdentityRegistry]
+ * for more information.
+ */
+abstract contract ERC7984IdentityCheck is ERC7984 {
+    /// @dev Emitted when the identity registry is updated.
+    event IdentityRegistryUpdated(address indexed oldRegistry, address indexed newRegistry);
+
+    /// @dev The provided registry address is invalid.
+    error ERC7984InvalidIdentityRegistry(address registry);
+
+    /// @dev The `account` is not verified in the identity registry.
+    error ERC7984InvalidIdentity(address account);
+
+    address private _identityRegistry;
+
+    constructor(address identityRegistry_) {
+        _setIdentityRegistry(identityRegistry_);
+    }
+
+    /// @dev See {ERC7984-_update}. Performs identity check on the recipient before updating the balance.
+    function _update(address from, address to, euint64 amount) internal virtual override returns (euint64) {
+        if (to != address(0) && !IIdentityRegistry(_identityRegistry).isVerified(to)) {
+            revert ERC7984InvalidIdentity(to);
+        }
+        return super._update(from, to, amount);
+    }
+
+    /// @dev Returns the address of the identity registry.
+    function identityRegistry() public view virtual returns (address) {
+        return _identityRegistry;
+    }
+
+    /// @dev Sets the identity registry. Inheriting contracts are responsible for access control.
+    function _setIdentityRegistry(address identityRegistry_) internal virtual {
+        require(
+            identityRegistry_ != address(0) && identityRegistry_.code.length != 0,
+            ERC7984InvalidIdentityRegistry(identityRegistry_)
+        );
+        emit IdentityRegistryUpdated(_identityRegistry, identityRegistry_);
+        _identityRegistry = identityRegistry_;
+    }
+}
+
+interface IIdentityRegistry {
+    function isVerified(address account) external view returns (bool);
+}

package/token/ERC7984/extensions/ERC7984Restricted.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Confidential Contracts (last updated v0.4.0) (token/ERC7984/extensions/ERC7984Restricted.sol)
+// OpenZeppelin Confidential Contracts (last updated v0.5.0-rc.0) (token/ERC7984/extensions/ERC7984Restricted.sol)
 
 pragma solidity ^0.8.27;
 
@@ -35,7 +35,7 @@ abstract contract ERC7984Restricted is ERC7984 {
     }
 
     /**
-     * @dev Returns whether a user account is allowed to interact with the token.
+     * @dev Returns whether a user account is allowed to receive or send tokens.
      *
      * Default implementation only disallows explicitly BLOCKED accounts (i.e. a blocklist).
      */
@@ -44,7 +44,7 @@ abstract contract ERC7984Restricted is ERC7984 {
     }
 
     /**
-     * @dev See {ERC7984-_update}. Enforces transfer restrictions (excluding minting and burning).
+     * @dev See {ERC7984-_update}. Enforces transfer restrictions.
      *
      * Requirements:
      *

package/token/ERC7984/extensions/ERC7984Rwa.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Confidential Contracts (last updated v0.4.0) (token/ERC7984/extensions/ERC7984Rwa.sol)
+// OpenZeppelin Confidential Contracts (last updated v0.5.0-rc.0) (token/ERC7984/extensions/ERC7984Rwa.sol)
 
 pragma solidity ^0.8.27;
 
@@ -9,8 +9,8 @@ import {ERC165} from "@openzeppelin/contracts/utils/introspection/ERC165.sol";
 import {IERC165} from "@openzeppelin/contracts/utils/introspection/IERC165.sol";
 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 +20,18 @@ import {ERC7984Restricted} from "./ERC7984Restricted.sol";
  * This interface provides compliance checks, transfer controls and enforcement actions.
  */
 abstract contract ERC7984Rwa is IERC7984Rwa, ERC7984Freezable, ERC7984Restricted, Pausable, Multicall, AccessControl {
+    /// @dev The operation failed because the lost account is the same as the new account.
+    error ERC7984RwaSelfRecoveryNotAllowed();
+
     /**
      * @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.
+     * * 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");
 
@@ -157,6 +160,38 @@ abstract contract ERC7984Rwa is IERC7984Rwa, ERC7984Freezable, ERC7984Restricted
         return burntAmount;
     }
 
+    /// @inheritdoc IERC7984Rwa
+    function recoverAddress(address lostAccount, address newAccount) public virtual onlyAgent returns (euint64) {
+        require(lostAccount != newAccount, ERC7984RwaSelfRecoveryNotAllowed());
+
+        euint64 balance = confidentialBalanceOf(lostAccount);
+        euint64 lostFrozenBalance = confidentialFrozen(lostAccount);
+
+        if (FHE.isInitialized(lostFrozenBalance)) {
+            _setConfidentialFrozen(lostAccount, euint64.wrap(0));
+        }
+
+        euint64 tokensRecovered = _transfer(lostAccount, newAccount, balance);
+        FHE.allow(tokensRecovered, msg.sender);
+
+        if (FHE.isInitialized(lostFrozenBalance)) {
+            _setConfidentialFrozen(
+                newAccount,
+                FHESafeMath.saturatingAdd(confidentialFrozen(newAccount), FHE.min(tokensRecovered, lostFrozenBalance))
+            );
+            _setConfidentialFrozen(lostAccount, FHESafeMath.saturatingSub(lostFrozenBalance, tokensRecovered));
+        }
+
+        Restriction restriction = getRestriction(lostAccount);
+        if (restriction == Restriction.BLOCKED) {
+            _blockUser(newAccount);
+        }
+
+        emit TokensRecovered(lostAccount, newAccount, tokensRecovered);
+
+        return tokensRecovered;
+    }
+
     /// @dev Variant of {forceConfidentialTransferFrom-address-address-euint64} with an input proof.
     function forceConfidentialTransferFrom(
         address from,
@@ -164,7 +199,9 @@ abstract contract ERC7984Rwa is IERC7984Rwa, ERC7984Freezable, ERC7984Restricted
         externalEuint64 encryptedAmount,
         bytes calldata inputProof
     ) public virtual onlyAgent returns (euint64) {
-        return _forceUpdate(from, to, FHE.fromExternal(encryptedAmount, inputProof));
+        euint64 transferred = _transfer(from, to, FHE.fromExternal(encryptedAmount, inputProof));
+        FHE.allow(transferred, msg.sender);
+        return transferred;
     }
 
     /**
@@ -176,12 +213,14 @@ abstract contract ERC7984Rwa is IERC7984Rwa, ERC7984Freezable, ERC7984Restricted
         address from,
         address to,
         euint64 encryptedAmount
-    ) public virtual onlyAgent returns (euint64 transferred) {
+    ) public virtual onlyAgent returns (euint64) {
         require(
             FHE.isAllowed(encryptedAmount, msg.sender),
             ERC7984UnauthorizedUseOfEncryptedAmount(encryptedAmount, msg.sender)
         );
-        return _forceUpdate(from, to, encryptedAmount);
+        euint64 transferred = _transfer(from, to, encryptedAmount);
+        FHE.allow(transferred, msg.sender);
+        return transferred;
     }
 
     /// @inheritdoc ERC7984Freezable
@@ -218,29 +257,27 @@ abstract contract ERC7984Rwa is IERC7984Rwa, ERC7984Freezable, ERC7984Restricted
         return super._update(from, to, encryptedAmount);
     }
 
-    /// @dev Internal function which forces transfer of confidential amount of tokens from account to account by skipping compliance checks.
-    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`
-        euint64 transferred = super._update(from, to, encryptedAmount);
-        FHE.allow(transferred, msg.sender);
-        return transferred;
-    }
-
-    /**
-     * @dev Bypasses the `from` restriction check when performing a {forceConfidentialTransferFrom}.
-     */
+    /// @dev Bypasses {ERC7984Restricted} `from` restriction check when performing a {forceConfidentialTransferFrom}.
     function _checkSenderRestriction(address account) internal view override {
-        if (_isForceTransfer()) {
+        if (_isForceTransfer(msg.sig)) {
             return;
         }
         super._checkSenderRestriction(account);
     }
 
-    /// @dev Private function which checks if the called function is a {forceConfidentialTransferFrom}.
-    function _isForceTransfer() private pure returns (bool) {
+    /// @dev Bypasses {Pausable} check when performing a {forceConfidentialTransferFrom}.
+    function _requireNotPaused() internal view override {
+        if (_isForceTransfer(msg.sig)) {
+            return;
+        }
+        super._requireNotPaused();
+    }
+
+    /// @dev Internal function which checks if the current function call should be treated as a force transfer.
+    function _isForceTransfer(bytes4 selector) internal pure returns (bool) {
         return
-            msg.sig == 0x6c9c3c85 || // bytes4(keccak256("forceConfidentialTransferFrom(address,address,bytes32,bytes)"))
-            msg.sig == 0x44fd6e40; // bytes4(keccak256("forceConfidentialTransferFrom(address,address,bytes32)"))
+            selector == 0x6c9c3c85 || // bytes4(keccak256("forceConfidentialTransferFrom(address,address,bytes32,bytes)"))
+            selector == 0x44fd6e40 || // bytes4(keccak256("forceConfidentialTransferFrom(address,address,bytes32)"))
+            selector == this.recoverAddress.selector;
     }
 }

package/token/ERC7984/utils/ERC7984BalanceCapHookModule.sol

@@ -0,0 +1,92 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Confidential Contracts (last updated v0.5.0-rc.0) (token/ERC7984/utils/ERC7984BalanceCapHookModule.sol)
+
+pragma solidity ^0.8.27;
+
+import {FHE, ebool, euint64, externalEuint64} from "@fhevm/solidity/lib/FHE.sol";
+import {IERC7984Rwa} from "./../../../interfaces/IERC7984Rwa.sol";
+import {FHESafeMath} from "./../../../utils/FHESafeMath.sol";
+import {ERC7984HookModule} from "./ERC7984HookModule.sol";
+
+/**
+ * @dev An ERC-7984 hook module that limits the balance of each investor.
+ *
+ * The cap is stored as an encrypted `euint64` value. The pre-transfer hook compares the recipient's prospective balance to the
+ * encrypted cap and emits an encrypted compliance result via {ERC7984HookModule-_emitPreTransferResults}.
+ *
+ * This module is compatible with {ERC7984Hooked}.
+ *
+ * WARNING: This module notifies senders of the result of the pre-transfer hook. This can be used to leak
+ * information about the balance of the recipient. This is a potential security risk and should be used
+ * with caution. Production use-cases may want to remove this notification.
+ */
+contract ERC7984BalanceCapHookModule is ERC7984HookModule {
+    /// @dev Emitted when the max balance for a given token is set.
+    event ERC7984BalanceCapHookModuleMaxBalanceSet(address indexed token, euint64 newMaxBalance);
+
+    mapping(address => euint64) private _maxBalances;
+
+    /**
+     * @dev Sets the max balance for a given token `token` to the encrypted value `newMaxBalance`.
+     *
+     * `msg.sender` must have the agent role on `token`.
+     */
+    function setMaxBalance(address token, externalEuint64 newMaxBalance, bytes calldata inputProof) public virtual {
+        require(IERC7984Rwa(token).isAgent(msg.sender), ERC7984HookModuleUnauthorizedAccount(msg.sender));
+        _setMaxBalance(token, FHE.fromExternal(newMaxBalance, inputProof));
+    }
+
+    /// @dev Gets the encrypted max balance for a given token `token`. Returns the zero handle if unset.
+    function maxBalance(address token) public view virtual returns (euint64) {
+        return _maxBalances[token];
+    }
+
+    /// @dev Sets the encrypted max balance for a given token, grants the module persistent ACL, and emits an event.
+    function _setMaxBalance(address token, euint64 newMaxBalance) internal virtual {
+        _maxBalances[token] = newMaxBalance;
+        FHE.allowThis(newMaxBalance);
+        FHE.allow(newMaxBalance, msg.sender);
+
+        emit ERC7984BalanceCapHookModuleMaxBalanceSet(token, newMaxBalance);
+    }
+
+    /// @inheritdoc ERC7984HookModule
+    function _preTransfer(
+        address token,
+        address from,
+        address to,
+        euint64 encryptedAmount
+    ) internal override returns (ebool) {
+        ebool compliant;
+        if (to == address(0) || from == to || !FHE.isInitialized(maxBalance(token))) {
+            compliant = FHE.asEbool(true);
+        } else {
+            euint64 balance = IERC7984Rwa(token).confidentialBalanceOf(to);
+            _accessHandle(token, balance);
+
+            // Note, if the balance would result in an overflow, transfer will fail due to total supply overflow.
+            (, euint64 futureBalance) = FHESafeMath.tryIncrease(balance, encryptedAmount);
+            compliant = FHE.le(futureBalance, maxBalance(token));
+        }
+
+        _emitPreTransferResults(token, from, to, encryptedAmount, compliant, bytes32(0));
+
+        return FHE.and(compliant, super._preTransfer(token, from, to, encryptedAmount));
+    }
+
+    /**
+     * @dev See {ERC7984HookModule-_onInstall}. The `initData` must contain the initial max balance for the token
+     * along with the input proof for the max balance. These are encoded using standard ABI encoding.
+     */
+    function _onInstall(address token, bytes calldata initData) internal virtual override {
+        super._onInstall(token, initData);
+        (externalEuint64 maxBalance_, bytes memory inputProof) = abi.decode(initData, (externalEuint64, bytes));
+        _setMaxBalance(token, FHE.fromExternal(maxBalance_, inputProof));
+    }
+
+    /// @inheritdoc ERC7984HookModule
+    function _onUninstall(address token, bytes calldata deinitData) internal virtual override {
+        super._onUninstall(token, deinitData);
+        _maxBalances[token] = euint64.wrap(0);
+    }
+}

package/token/ERC7984/utils/ERC7984HolderCapHookModule.sol

@@ -0,0 +1,145 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Confidential Contracts (last updated v0.5.0-rc.0) (token/ERC7984/utils/ERC7984HolderCapHookModule.sol)
+
+pragma solidity ^0.8.27;
+
+import {FHE, ebool, euint64} from "@fhevm/solidity/lib/FHE.sol";
+import {IERC7984Rwa} from "./../../../interfaces/IERC7984Rwa.sol";
+import {ERC7984HookModule} from "./ERC7984HookModule.sol";
+
+/**
+ * @dev An ERC-7984 hook module that limits the number of holders for a given token.
+ *
+ * NOTE: This module must be installed prior to minting any tokens. After the total supply is initialized,
+ * it is not possible to guarantee that the number of holders is 0, so the module can not be installed.
+ *
+ * WARNING: This module may not function correctly with non-standard tokens such as fee on transfer.
+ */
+contract ERC7984HolderCapHookModule is ERC7984HookModule {
+    /// @dev Emitted when the max holder count for a given token is set.
+    event ERC7984HolderCapHookModuleMaxHolderCountSet(address indexed token, uint64 newMaxHolderCount);
+
+    /// @dev The new max holder count `maxHolderCount` is invalid.
+    error ERC7984HolderCapHookModuleInvalidMaxHolderCount(uint64 maxHolderCount);
+
+    /**
+     * The total supply of the token is already initialized.
+     * This module must be installed before the total supply is initialized.
+     */
+    error ERC7984HolderCapHookModuleTotalSupplyInitialized();
+
+    mapping(address => uint64) private _maxHolderCounts;
+    mapping(address => euint64) private _holderCounts;
+
+    /**
+     * @dev Sets the max number of holders for the given token `token` to `maxHolderCount_`.
+     *
+     * `msg.sender` must have the agent role on `token`
+     **/
+    function setMaxHolderCount(address token, uint64 maxHolderCount_) public virtual {
+        require(IERC7984Rwa(token).isAgent(msg.sender), ERC7984HookModuleUnauthorizedAccount(msg.sender));
+        _setMaxHolderCount(token, maxHolderCount_);
+    }
+
+    /// @dev Gets max number of holders for the given token `token`.
+    function maxHolderCount(address token) public view virtual returns (uint64) {
+        return _maxHolderCounts[token];
+    }
+
+    /// @dev Gets current number of holders for the given token `token`.
+    function holderCount(address token) public view virtual returns (euint64) {
+        return _holderCounts[token];
+    }
+
+    /// @dev Sets the max holder count for a given token to `maxHolderCount_` and emits an event.
+    function _setMaxHolderCount(address token, uint64 maxHolderCount_) internal virtual {
+        require(maxHolderCount_ != 0, ERC7984HolderCapHookModuleInvalidMaxHolderCount(maxHolderCount_));
+        _maxHolderCounts[token] = maxHolderCount_;
+        emit ERC7984HolderCapHookModuleMaxHolderCountSet(token, maxHolderCount_);
+    }
+
+    /// @inheritdoc ERC7984HookModule
+    function _preTransfer(
+        address token,
+        address from,
+        address to,
+        euint64 encryptedAmount
+    ) internal override returns (ebool) {
+        if (to == address(0) || to == from) {
+            return FHE.asEbool(true);
+        }
+
+        euint64 fromBalance = IERC7984Rwa(token).confidentialBalanceOf(from);
+        euint64 toBalance = IERC7984Rwa(token).confidentialBalanceOf(to);
+
+        _accessHandle(token, fromBalance);
+        _accessHandle(token, toBalance);
+
+        euint64 encryptedZero = FHE.asEuint64(0);
+
+        // note, if from is address(0):
+        // - fromBalance is an encrypted zero
+        // - from will be (erroneously) removed from the holder count only encryptedAmount is a zero
+        // that is fine because if encryptedAmount is a zero, then this value is dropped anyway.
+        euint64 adjustedHolderCount = FHE.add(
+            FHE.sub(holderCount(token), FHE.asEuint64(FHE.eq(fromBalance, encryptedAmount))),
+            FHE.asEuint64(FHE.and(FHE.eq(toBalance, encryptedZero), FHE.ne(encryptedAmount, encryptedZero)))
+        );
+
+        ebool compliant = FHE.le(adjustedHolderCount, maxHolderCount(token));
+
+        return FHE.and(compliant, super._preTransfer(token, from, to, encryptedAmount));
+    }
+
+    /// @inheritdoc ERC7984HookModule
+    function _postTransfer(address token, address from, address to, euint64 encryptedAmount) internal virtual override {
+        super._postTransfer(token, from, to, encryptedAmount);
+
+        if (from == to) return;
+
+        euint64 fromBalance = IERC7984Rwa(token).confidentialBalanceOf(from);
+        euint64 toBalance = IERC7984Rwa(token).confidentialBalanceOf(to);
+
+        _accessHandle(token, fromBalance);
+        _accessHandle(token, toBalance);
+
+        euint64 encryptedZero = FHE.asEuint64(0);
+        ebool transferNotZero = FHE.ne(encryptedAmount, encryptedZero);
+        euint64 newHolderCount = holderCount(token);
+
+        if (to != address(0)) {
+            ebool addHolder = FHE.and(transferNotZero, FHE.eq(toBalance, encryptedAmount));
+            newHolderCount = FHE.add(newHolderCount, FHE.asEuint64(addHolder));
+        }
+
+        if (from != address(0)) {
+            ebool subHolder = FHE.and(transferNotZero, FHE.eq(fromBalance, encryptedZero));
+            newHolderCount = FHE.sub(newHolderCount, FHE.asEuint64(subHolder));
+        }
+
+        _holderCounts[token] = newHolderCount;
+        FHE.allowThis(newHolderCount);
+    }
+
+    /**
+     * @dev See {ERC7984HookModule-_onInstall}. The `initData` must contain the initial max holder count for the token
+     * as a standard ABI encoded uint64.
+     **/
+    function _onInstall(address token, bytes calldata initData) internal virtual override {
+        require(
+            !FHE.isInitialized(IERC7984Rwa(token).confidentialTotalSupply()),
+            ERC7984HolderCapHookModuleTotalSupplyInitialized()
+        );
+
+        super._onInstall(token, initData);
+
+        uint64 maxHolderCount_ = abi.decode(initData, (uint64));
+        _setMaxHolderCount(token, maxHolderCount_);
+    }
+
+    function _onUninstall(address token, bytes calldata deinitData) internal virtual override {
+        super._onUninstall(token, deinitData);
+        delete _maxHolderCounts[token];
+        _holderCounts[token] = euint64.wrap(0);
+    }
+}