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

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.