# 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://tech.usual.money/smart-contracts/usd0-collateral/m-by-m0/usualm.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.