> 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/usdtb-by-ethena/usualusdtb.md).

# UsualUSDtb

## High-Level Overview

The **UsualUSDTB** smart contract manages the **UsualUSDTB** ERC20 Token and acts as a wrapped version of the **USDTB** token. It allows users to wrap **USDTB** tokens into **UsualUSDTB**, 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 **USDTB** token while enforcing access control through a Registry Access Contract. Key features include wrapping, unwrapping, minting, and pausing operations.

### Contract Summary

**UsualUSDTB** 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 **USDTB** tokens into **UsualUSDTB** tokens for the recipient.
* **wrapWithPermit(address recipient, uint256 amount, uint256 deadline, uint8 v, bytes32 r, bytes32 s)**: Wraps **USDTB** tokens using a permit signature for approval, enabling gasless wrapping.
* **unwrap(address recipient, uint256 amount)**: Unwraps **UsualUSDTB** tokens into **USDTB** 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\_USDTB\_MINTCAP\_ALLOCATOR** role.
* **pause()**: Pauses all token transfers. Callable only by accounts with the **USUAL\_USDTB\_PAUSE** role.
* **unpause()**: Resumes all token transfers. Callable only by accounts with the **USUAL\_USDTB\_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

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

#### Key Functionalities

* **Wrapping**: Users can wrap **USDTB** tokens into **UsualUSDTB**, making use of enhanced token features.
* **Unwrapping**: Users can unwrap **UsualUSDTB** tokens back into **USDTB**, subject to role checks.
* **Mint Cap Enforcement**: Ensures that the total supply of **UsualUSDTB** 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\_USDTB\_UNWRAP**: Role required to unwrap tokens.
* **USUAL\_USDTB\_PAUSE**: Role required to pause the contract.
* **USUAL\_USDTB\_UNPAUSE**: Role required to unpause the contract.
* **USUAL\_USDTB\_MINTCAP\_ALLOCATOR**: Role required to update the mint cap.
* **BLACKLIST\_ROLE**: Role required to blacklist/unblacklist accounts.
* **USUAL\_USDTB\_DECIMALS**: Set to 18 decimals for the token.

### 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 **UsualUSDTB** 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.
* **Safe Type Conversion**: The contract includes \_safe96() function to safely convert uint256 to uint96 for mint cap storage, preventing overflow issues.