Add ERC20Freezable, ERC20Restricted and ERC20uRWA

contracts/interfaces/IERC7943.sol

@@ -0,0 +1,83 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.26;
+
+import {IERC165} from "@openzeppelin/contracts/utils/introspection/IERC165.sol";
+
+/// @notice Defines the ERC-7943 interface, the uRWA.
+/// When interacting with specific token standards:
+/// - For ERC-721 like (non-fungible) tokens 'amount' parameters typically represent a single token (i.e., 1).
+/// - For ERC-20 like (fungible) tokens, 'tokenId' parameters are generally not applicable and should be set to 0.
+interface IERC7943 is IERC165 {
+    /// @notice Emitted when tokens are taken from one address and transferred to another.
+    /// @param from The address from which tokens were taken.
+    /// @param to The address to which seized tokens were transferred.
+    /// @param tokenId The ID of the token being transferred.
+    /// @param amount The amount seized.
+    event ForcedTransfer(address indexed from, address indexed to, uint256 tokenId, uint256 amount);
+
+    /// @notice Emitted when `setFrozen` is called, changing the frozen `amount` of `tokenId` tokens for `user`.
+    /// @param user The address of the user whose tokens are being frozen.
+    /// @param tokenId The ID of the token being frozen.
+    /// @param amount The amount of tokens frozen after the change.
+    event Frozen(address indexed user, uint256 indexed tokenId, uint256 amount);
+
+    /// @notice Error reverted when a user is not allowed to interact.
+    /// @param account The address of the user which is not allowed for interactions.
+    error ERC7943NotAllowedUser(address account);
+
+    /// @notice Error reverted when a transfer is not allowed due to restrictions in place.
+    /// @param from The address from which tokens are being transferred.
+    /// @param to The address to which tokens are being transferred.
+    /// @param tokenId The ID of the token being transferred.
+    /// @param amount The amount being transferred.
+    error ERC7943NotAllowedTransfer(address from, address to, uint256 tokenId, uint256 amount);
+
+    /// @notice Error reverted when a transfer is attempted from `user` with an `amount` of `tokenId` less or equal than its balance, but greater than its unfrozen balance.
+    /// @param user The address holding the tokens.
+    /// @param tokenId The ID of the token being transferred.
+    /// @param amount The amount being transferred.
+    /// @param unfrozen The amount of tokens that are unfrozen and available to transfer.
+    error ERC7943InsufficientUnfrozenBalance(address user, uint256 tokenId, uint256 amount, uint256 unfrozen);
+
+    /// @notice Takes tokens from one address and transfers them to another.
+    /// @dev Requires specific authorization. Used for regulatory compliance or recovery scenarios.
+    /// @param from The address from which `amount` is taken.
+    /// @param to The address that receives `amount`.
+    /// @param tokenId The ID of the token being transferred.
+    /// @param amount The amount to force transfer.
+    function forceTransfer(address from, address to, uint256 tokenId, uint256 amount) external;
+
+    /// @notice Changes the frozen status of `amount` of `tokenId` tokens belonging to an `user`.
+    /// This overwrites the current value, similar to an `approve` function.
+    /// @dev Requires specific authorization. Frozen tokens cannot be transferred by the user.
+    /// @param user The address of the user whose tokens are to be frozen/unfrozen.
+    /// @param tokenId The ID of the token to freeze/unfreeze.
+    /// @param amount The amount of tokens to freeze/unfreeze.
+    function setFrozen(address user, uint256 tokenId, uint256 amount) external;
+
+    /// @notice Checks the frozen status/amount of a specific `tokenId`.
+    /// @param user The address of the user.
+    /// @param tokenId The ID of the token.
+    /// @return amount The amount of `tokenId` tokens currently frozen for `user`.
+    function getFrozen(address user, uint256 tokenId) external view returns (uint256 amount);
+
+    /// @notice Checks if a transfer is currently possible according to token rules. It enforces validations on the frozen tokens.
+    /// @dev This may involve checks like allowlists, blocklists, transfer limits and other policy-defined restrictions.
+    /// @param from The address sending tokens.
+    /// @param to The address receiving tokens.
+    /// @param tokenId The ID of the token being transferred.
+    /// @param amount The amount being transferred.
+    /// @return allowed True if the transfer is allowed, false otherwise.
+    function isTransferAllowed(
+        address from,
+        address to,
+        uint256 tokenId,
+        uint256 amount
+    ) external view returns (bool allowed);
+
+    /// @notice Checks if a specific user is allowed to interact according to token rules.
+    /// @dev This is often used for allowlist/KYC/KYB/AML checks.
+    /// @param user The address to check.
+    /// @return allowed True if the user is allowed, false otherwise.
+    function isUserAllowed(address user) external view returns (bool allowed);
+}

contracts/token/ERC20/extensions/ERC20Freezable.sol

@@ -0,0 +1,58 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.26;
+
+import {ERC20} from "@openzeppelin/contracts/token/ERC20/ERC20.sol";
+import {IERC7943} from "../../../interfaces/IERC7943.sol";
+
+/**
+ * @dev Extension of {ERC20} that allows to implement a freezing
+ * mechanism that can be managed by an authorized account with the
+ * {_freezeTokens} and {_unfreezeTokens} functions.
+ *
+ * The freezing mechanism provides the guarantee to the contract owner
+ * (e.g. a DAO or a well-configured multisig) that a specific amount
+ * of tokens held by an account won't be transferable until those
+ * tokens are unfrozen using {_unfreezeTokens}.
+ */
+abstract contract ERC20Freezable is ERC20 {
+    /// @dev Frozen amount of tokens per address.
+    mapping(address account => uint256) private _frozenBalances;
+
+    /// @dev The operation failed because the user has insufficient unfrozen balance.
+    error ERC20InsufficientUnfrozenBalance(address user, uint256 needed, uint256 available);
+
+    /// @dev Returns the frozen balance of an account.
+    function frozen(address account) public view virtual returns (uint256) {
+        return _frozenBalances[account];
+    }
+
+    /// @dev Returns the available (unfrozen) balance of an account. Up to {balanceOf}.
+    function available(address account) public view virtual returns (uint256) {
+        return balanceOf(account) - _frozenBalances[account];
+    }
+
+    /// @dev Internal function to set the frozen token amount for a user.
+    function _setFrozen(address user, uint256 amount) internal virtual {
+        _frozenBalances[user] = amount;
+        emit IERC7943.Frozen(user, 0, amount);
+    }
+
+    /**
+     * @dev See {ERC20-_update}.
+     *
+     * Requirements:
+     *
+     * * `from` must have sufficient unfrozen balance.
+     */
+    function _update(address from, address to, uint256 value) internal virtual override {
+        if (from != address(0)) {
+            uint256 unfrozen = available(from);
+            require(unfrozen >= value, ERC20InsufficientUnfrozenBalance(from, value, unfrozen));
+        }
+        super._update(from, to, value);
+    }
+
+    // We don't check frozen balance for approvals since the actual transfer
+    // will be checked in _update. This allows for more flexible approval patterns.
+}

contracts/token/ERC20/extensions/ERC20Restricted.sol

@@ -0,0 +1,96 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.20;
+
+import {ERC20} from "@openzeppelin/contracts/token/ERC20/ERC20.sol";
+
+/**
+ * @dev Extension of {ERC20} that allows to implement user access restrictions
+ * through the {isUserAllowed} function. Inspired by https://eips.ethereum.org/EIPS/eip-7943[EIP-7943].
+ *
+ * By default, each user has no explicit restriction. The {isUserAllowed} function acts as
+ * an allowlist. Developers can override {isUserAllowed} to check that `restriction != RESTRICTED`
+ * to implement a blocklist.
+ */
+abstract contract ERC20Restricted is ERC20 {
+    enum Restriction {
+        DEFAULT, // User has no explicit restriction
+        RESTRICTED, // User is explicitly restricted
+        UNRESTRICTED // User is explicitly unrestricted
+    }
+
+    mapping(address user => Restriction) private _restrictions;
+
+    /// @dev Emitted when a user's restriction is updated.
+    event UserRestrictionsUpdated(address indexed user, Restriction restriction);
+
+    /// @dev The operation failed because the user is restricted.
+    error ERC20Restricted(address user);
+
+    /// @dev Returns the restriction of an account.
+    function getRestriction(address user) public view virtual returns (Restriction) {
+        return _restrictions[user];
+    }
+
+    /**
+     * @dev Returns whether a user is allowed to interact with the token.
+     *
+     * Default implementation only disallows explicitly RESTRICTED users (i.e. a blocklist).
+     *
+     * To convert into an allowlist, override as:
+     *
+     * ```solidity
+     * function isUserAllowed(address user) public view virtual override returns (bool) {
+     *     return getRestriction(user) != Restriction.UNRESTRICTED; // i.e. DEFAULT && UNRESTRICTED
+     * }
+     * ```
+     */
+    function isUserAllowed(address user) public view virtual returns (bool) {
+        return getRestriction(user) != Restriction.RESTRICTED; // i.e. DEFAULT && UNRESTRICTED
+    }
+
+    /**
+     * @dev See {ERC20-_update}. Enforces restriction transfers (excluding minting and burning).
+     *
+     * Requirements:
+     *
+     * * `from` must be allowed to transfer tokens (see {isUserAllowed}).
+     * * `to` must be allowed to receive tokens (see {isUserAllowed}).
+     */
+    function _update(address from, address to, uint256 value) internal virtual override {
+        if (from != address(0)) _checkRestricted(from); // Minting
+        if (to != address(0)) _checkRestricted(to); // Burning
+        super._update(from, to, value);
+    }
+
+    // We don't check restrictions for approvals since the actual transfer
+    // will be checked in _update. This allows for more flexible approval patterns.
+
+    /// @dev Updates the restriction of a user.
+    function _setRestriction(address user, Restriction restriction) internal virtual {
+        if (getRestriction(user) != restriction) {
+            _restrictions[user] = restriction;
+            emit UserRestrictionsUpdated(user, restriction);
+        } // no-op if restriction is unchanged
+    }
+
+    /// @dev Convenience function to restrict a user (set to RESTRICTED).
+    function _allowUser(address user) internal virtual {
+        _setRestriction(user, Restriction.RESTRICTED);
+    }
+
+    /// @dev Convenience function to disallow a user (set to UNRESTRICTED).
+    function _disallowUser(address user) internal virtual {
+        _setRestriction(user, Restriction.UNRESTRICTED);
+    }
+
+    /// @dev Convenience function to reset a user to default restriction.
+    function _resetUser(address user) internal virtual {
+        _setRestriction(user, Restriction.DEFAULT);
+    }
+
+    /// @dev Checks if a user is restricted. Reverts with {ERC20Restricted} if so.
+    function _checkRestricted(address user) internal view virtual {
+        require(isUserAllowed(user), ERC20Restricted(user));
+    }
+}

contracts/token/ERC20/extensions/ERC20uRWA.sol

@@ -0,0 +1,104 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.26;
+
+import {IERC7943} from "../../../interfaces/IERC7943.sol";
+import {ERC20} from "@openzeppelin/contracts/token/ERC20/ERC20.sol";
+import {ERC165, IERC165} from "@openzeppelin/contracts/utils/introspection/ERC165.sol";
+import {ERC20Freezable} from "./ERC20Freezable.sol";
+import {ERC20Restricted} from "./ERC20Restricted.sol";
+
+/**
+ * @dev Extension of {ERC20} according to https://eips.ethereum.org/EIPS/eip-7943[EIP-7943].
+ *
+ * Combines standard ERC-20 functionality with RWA-specific features like user restrictions,
+ * asset freezing, and forced asset transfers.
+ */
+// solhint-disable-next-line contract-name-capwords
+abstract contract uRWA20 is ERC20, ERC20Freezable, ERC20Restricted, IERC7943, ERC165 {
+    /// @inheritdoc ERC20Restricted
+    function isUserAllowed(address user) public view virtual override(IERC7943, ERC20Restricted) returns (bool) {
+        return super.isUserAllowed(user);
+    }
+
+    /// @inheritdoc ERC165
+    function supportsInterface(bytes4 interfaceId) public view virtual override(ERC165, IERC165) returns (bool) {
+        return interfaceId == type(IERC7943).interfaceId || super.supportsInterface(interfaceId);
+    }
+
+    /// @inheritdoc IERC7943
+    function isTransferAllowed(address from, address to, uint256, uint256 amount) public view virtual returns (bool) {
+        return (amount <= available(from) && isUserAllowed(from) && isUserAllowed(to));
+    }
+
+    /// @inheritdoc IERC7943
+    function getFrozen(address user, uint256) public view virtual returns (uint256 amount) {
+        return frozen(user);
+    }
+
+    /// @inheritdoc IERC7943
+    function setFrozen(address user, uint256, uint256 amount) public virtual {
+        require(amount <= balanceOf(user), ERC20InsufficientBalance(user, balanceOf(user), amount));
+        _checkFreezer(user, amount);
+        _setFrozen(user, amount);
+    }
+
+    /// @inheritdoc IERC7943
+    function forceTransfer(address from, address to, uint256, uint256 amount) public virtual {
+        require(isUserAllowed(to), ERC7943NotAllowedUser(to));
+        _checkEnforcer(from, to, amount);
+
+        // Update frozen balance if needed
+        uint256 currentFrozen = frozen(from);
+        uint256 currentBalance = balanceOf(from);
+        if (currentFrozen > currentBalance - amount) {
+            _setFrozen(from, currentBalance - amount);
+        }
+
+        ERC20._update(from, to, amount); // Explicit raw update to bypass all restrictions
+        emit ForcedTransfer(from, to, 0, amount);
+    }
+
+    /**
+     * @dev See {ERC20-_update}.
+     *
+     * Requirements:
+     *
+     * * `from` and `to` must be allowed to transfer `amount` tokens (see {isTransferAllowed}).
+     */
+    function _update(
+        address from,
+        address to,
+        uint256 amount
+    ) internal virtual override(ERC20, ERC20Freezable, ERC20Restricted) {
+        if (from == address(0)) {
+            // Minting
+            require(isUserAllowed(to), ERC7943NotAllowedUser(to));
+        } else if (to != address(0)) {
+            // Transfer
+            require(isTransferAllowed(from, to, 0, amount), ERC7943NotAllowedTransfer(from, to, 0, amount));
+        }
+        super._update(from, to, amount);
+    }
+
+    /**
+     * @dev Internal function to check if the enforcer is allowed to force transfer.
+     *
+     * Example usage with {AccessControl-onlyRole}:
+     *
+     * ```solidity
+     * function _checkEnforcer(address from, address to, uint256 amount) internal view override onlyRole(ENFORCER_ROLE) {}
+     * ```
+     */
+    function _checkEnforcer(address from, address to, uint256 amount) internal view virtual;
+
+    /**
+     * @dev Internal function to check if the user has sufficient unfrozen balance.
+     *
+     * Example usage with {AccessControl-onlyRole}:
+     *
+     * ```solidity
+     * function _checkFreezer(address user, uint256 amount) internal view override onlyRole(FREEZER_ROLE) {}
+     * ```
+     */
+    function _checkFreezer(address user, uint256 amount) internal view virtual;
+}