> For the complete documentation index, see [llms.txt](https://tech.usual.money/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tech.usual.money/smart-contracts/usd0-collateral/m-by-m0/usualm.md).

# UsualM

## High-Level Overview

The **UsualM** smart contract manages the **UsualM ERC20 Token** and acts as a wrapped version of the **WrappedM** token (wrapped version of the M token). It allows users to wrap **WrappedM** tokens into **UsualM**, adding enhanced functionality such as pausability, blacklist enforcement, and mint cap restrictions. It also supports permits and implements role-based access control to ensure secure operations.

This contract is specifically designed to interact with the **WrappedM** token while enforcing access control through a **Registry Access Contract**. Key features include wrapping, unwrapping, minting, and pausing operations.

### Contract Summary

**UsualM** is an ERC-20 token with additional features that provide security and operational flexibility. It integrates with OpenZeppelin upgradeable modules for pausability and permit-based approvals. Moreover, it enforces blacklist restrictions to prevent interactions with malicious or sanctioned addresses and limits the maximum supply via a configurable mint cap.

#### **Inherited Contracts**

* **ERC20PausableUpgradeable**: Enables pausability of token transfers, ensuring operations can be halted in emergencies.
* **ERC20PermitUpgradeable**: Supports gasless approvals through EIP-2612 signatures, enabling off-chain approval of token transfers.
* **ERC20Upgradeable**: Provides the core ERC-20 token implementation.

### Functions Description

#### Public/External Functions

* **wrap(address recipient, uint256 amount):** Wraps the specified amount of **WrappedM** tokens into **UsualM** tokens for the `recipient`.
* **wrapWithPermit(address recipient, uint256 amount, uint256 deadline, uint8 v, bytes32 r, bytes32 s):** Wraps **WrappedM** tokens using a permit signature for approval, enabling gasless wrapping.
* **unwrap(address recipient, uint256 amount):** Unwraps **UsualM** tokens into **WrappedM** tokens, subject to role checks on the caller.
* **setMintCap(uint256 newMintCap):** Updates the mint cap for the token. Callable only by accounts with the `USUAL_M_MINTCAP_ALLOCATOR` role.
* **pause():** Pauses all token transfers. Callable only by accounts with the `USUAL_M_PAUSE` role.
* **unpause():** Resumes all token transfers. Callable only by accounts with the `USUAL_M_UNPAUSE` role.
* **blacklist(address account):** Blacklists an address, preventing it from interacting with the token. Callable only by accounts with the `BLACKLIST_ROLE`.
* **unBlacklist(address account):** Removes an address from the blacklist. Callable only by accounts with the `BLACKLIST_ROLE`.

## Functionality Breakdown

### SC-Flows

#### Key Functionalities

* **Wrapping:** Users can wrap **WrappedM** tokens into **UsualM**, making use of enhanced token features.
* **Unwrapping:** Users can unwrap **UsualM** tokens back into **WrappedM**, subject to role checks.
* **Mint Cap Enforcement:** Ensures that the total supply of **UsualM** tokens does not exceed the configured mint cap.
* **Blacklist Enforcement:** Prevents blacklisted addresses from participating in token transfers.
* **Pausability:** Allows administrators to halt all token transfers during emergencies.

### Constants

* **USUAL\_M\_UNWRAP:** Role required to unwrap tokens.
* **USUAL\_M\_PAUSE:** Role required to pause the contract.
* **USUAL\_M\_UNPAUSE:** Role required to unpause the contract.
* **USUAL\_M\_MINTCAP\_ALLOCATOR:** Role required to update the mint cap.
* **BLACKLIST\_ROLE:** Role required to blacklist/unblacklist accounts.

### Safeguards Implementation

* **Pausability:** The contract integrates pausability to ensure all token transfers can be halted in emergencies. Only accounts with the appropriate roles can pause/unpause the contract.
* **Role-Based Access Control:** Sensitive operations such as pausing, unwrapping, blacklisting, and updating the mint cap are restricted to accounts with specific roles. This ensures that only authorized entities can perform these operations.
* **Mint Cap Enforcement:** The total supply of **UsualM** tokens is capped by a configurable limit, ensuring supply control.
* **Blacklist Enforcement:** The contract prevents interactions with blacklisted addresses, safeguarding the token economy from malicious actors.