# UsualUSDC

## High-Level Overview

The **UsualUSDC** smart contract manages the **UsualUSDC** ERC20 Token and acts as a wrapped version of the USDC token. It allows users to wrap USDC tokens into **UsualUSDC**, adding enhanced functionality such as pausability, blacklist enforcement, mint cap restrictions, redemption fees, and allowlist-based redemption controls. It also supports permits and implements role-based access control to ensure secure operations.\
This contract is specifically designed to interact with the USDC token while enforcing access control through a Registry Access Contract. Key features include wrapping, unwrapping with fee collection, minting, pausing operations, and redemption allowlist management.

### Contract Summary

**UsualUSDC** is an ERC-20 token with additional features that provide security, operational flexibility, and revenue generation capabilities. 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, limits the maximum supply via a configurable mint cap, implements redemption fees for revenue generation, and restricts unwrapping to allowlisted addresses only.

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

Wrapping Functions:

* **wrap(address recipient, uint256 amount):** Wraps the specified amount of USDC tokens into **UsualUSDC** tokens for the recipient.
* **wrapWithPermit(address recipient, uint256 amount, uint256 deadline, uint8 v, bytes32 r, bytes32 s):** Wraps USDC tokens using a permit signature for approval, enabling gasless wrapping.

Unwrapping Functions:

* **unwrap(address recipient, uint256 amount):** Unwraps **UsualUSDC** tokens into USDC tokens, subject to allowlist checks and redemption fee collection.

Admin Functions:

* **setMintCap(uint256 newMintCap)**: Updates the mint cap for the token. Callable only by accounts with the **USUAL\_USDC\_MINTCAP\_ALLOCATOR** role.
* **pause()**: Pauses all token transfers. Callable only by accounts with the **USUAL\_USDC\_PAUSE** role.
* **unpause()**: Resumes all token transfers. Callable only by accounts with the **USUAL\_USDC\_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**.

Redemption Management Functions:

* **addToRedemptionAllowList(address account)**: Adds an account to the redemption allowlist. Callable only by accounts with the **USUAL\_USDC\_REDEMPTION\_ROLE**.
* **removeFromRedemptionAllowList(address account)**: Removes an account from the redemption allowlist. Callable only by accounts with the **USUAL\_USDC\_REDEMPTION\_ROLE**.
* **setRedemptionFee(uint256 newRedemptionFeeBps)**: Sets the redemption fee in basis points. Callable only by accounts with the **USUAL\_USDC\_REDEMPTION\_ROLE**.
* **setFeeRecipient(address newFeeRecipient)**: Sets the fee recipient address. Callable only by accounts with the **USUAL\_USDC\_FEE\_RECIPIENT\_ROLE**.

## Functionality Breakdown

### SC-Flows

<figure><img src="/files/Cp1tUpYE7fEtvtMJprQn" alt=""><figcaption></figcaption></figure>

#### Key Functionalities

* **Wrapping**: Users can wrap USDC tokens into **UsualUSDC**, making use of enhanced token features.
* **Unwrapping** **with Fees**: Users can unwrap **UsualUSDC** tokens back into USDC, subject to allowlist checks and redemption fee collection.
* **Mint Cap Enforcement**: Ensures that the total supply of **UsualUSDC** 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.
* **Redemption Allowlist**: Restricts unwrapping functionality to allowlisted addresses only.
* **Fee Collection**: Implements configurable redemption fees for revenue generation.

### Constants

* **USUAL\_USDC\_PAUSE**: Role required to pause the contract.
* **USUAL\_USDC\_UNPAUSE**: Role required to unpause the contract.
* **USUAL\_USDC\_MINTCAP\_ALLOCATOR**: Role required to update the mint cap.
* **BLACKLIST\_ROLE**: Role required to blacklist/unblacklist accounts.
* **USUAL\_USDC\_REDEMPTION\_ROLE**: Role required to manage redemption allowlist and fees.
* **USUAL\_USDC\_FEE\_RECIPIENT\_ROLE**: Role required to update fee recipient.
* **USUAL\_USDC\_DECIMALS**: Token decimals (6, matching USDC).
* **BPS\_SCALAR**: Basis points scalar (10,000 for 100%).

### 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, blacklisting, updating the mint cap, managing redemption allowlist, and setting fees are restricted to accounts with specific roles. This ensures that only authorized entities can perform these operations.
* **Mint Cap Enforcement**: The total supply of **UsualUSDC** 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.
* **Redemption Allowlist**: Unwrapping is restricted to allowlisted addresses only, providing additional control over who can redeem tokens.
* **Fee Collection**: Configurable redemption fees provide revenue generation while discouraging excessive unwrapping.
* **Input Validation**: Comprehensive checks for zero addresses, invalid amounts, and same-value operations prevent common errors and ensure data integrity.


---

# 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/usdc-by-circle/usualusdc.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.