Usual WebsiteGeneral DocsContract DeploymentsAuditsAccess dApp

USD0a

High-Level Overview

The USD0a contract is designed to manage the USD0a ERC20 Token, implementing functionalities for minting, burning, transfer operations, and value accounting while incorporating blacklist checks to restrict these operations to authorized addresses. USD0a is a yield-bearing token that represents a proportional share of the total value of underlying collateral assets. The token's price in USD depends on the prices of the underlying collateral tokens and the total supply of USD0a. USD0a value increases based on the increased value of the underlying collateral assets.

Contract Summary

USD0a is an ERC-20 compliant token that integrates additional security, access control, and value accounting features to enhance its governance and usability. It inherits functionalities from ERC20PausableUpgradeable and ERC20PermitUpgradeable to support permit-based approvals and pausability.

Key Characteristics

  • Dynamic Pricing: The price of USD0a in USD is calculated based on the total value of collateral backing divided by the total supply. The price depends on the prices of the underlying collateral tokens (as provided by the oracle) and the total supply of USD0a. Changes in collateral prices or supply will affect the USD0a price accordingly.

  • Collateral Backing: USD0a tokens are backed by collateral tokens (such as USCC, USTB, and USDC) held in the collateral treasury. The price reflects the ratio of total collateral value to total supply.

Minting USD0a

Users can swap their collateral tokens via the DaoCollateral contract to mint an equivalent amount of USD0a. The minting process is subject to several checks:

  • The amount must not exceed the current mint cap

  • The caller must have the USD0X_MINT role

  • The recipient address must not be blacklisted

The amount of USD0a minted is calculated based on the current USD0a price in USD, which depends on the prices of the underlying collateral tokens and the total supply. The price reflects the current ratio of total collateral value to total supply.

Redeeming USD0a

Users can swap any USD0a back to the underlying collateral tokens at any time via the DaoCollateral contract, burning the USD0a in the process. The redemption process includes a configurable fee to prevent oracle manipulation attacks. When redeeming, users receive collateral tokens based on the current USD0a price in USD, which reflects the current value of the underlying collateral assets.

Regulatory Compliance

The contract includes a blacklist feature to ensure regulatory compliance. Sanctioned addresses are prevented from interacting with the contract, and the list is kept up to date. Blacklisted addresses cannot send or receive USD0a tokens.

Price Calculation

The USD0a price in USD is calculated dynamically based on the total value of collateral backing divided by the total supply. The price depends on two main factors:

  1. Collateral Prices: The prices of the underlying collateral tokens (as provided by the oracle)

  2. Total Supply: The total number of USD0a tokens in circulation

Price Calculation:

  • The contract retrieves all collateral tokens from the TokenMapping contract

  • For each collateral token, it calculates the USD value: balance × price (where price comes from the oracle)

  • Sums all collateral USD values to get total collateral backing

  • Divides total collateral backing by total supply to get the price per USD0a token

Price Formula:

USD0a Price = Total Collateral Value / Total Supply

The price can increase or decrease depending on:

  • Changes in collateral token prices (as reported by the oracle)

  • Changes in total supply (from minting or burning)

  • Changes in collateral backing (from deposits or withdrawals)

The price can be retrieved with either floor or ceiling rounding using the getUsd0xPriceInUSD() function.

Functionality Breakdown

Key Functionalities

  • Minting: Tokens can be minted to a non-blacklisted address, subject to role checks and mint cap requirements.

  • Burning: Tokens can be burned from an address, subject to role checks.

  • Transfers: Only non-blacklisted addresses can send or receive tokens.

  • Harvest Mechanism: The harvest function calculates the amount to mint based on the configured Annual Percentage Yield (APY) and daily harvest fee, reflecting the value that has been generated by the underlying collateral assets. Harvest can only be executed once per day (enforced by HARVEST_FREQUENCY).

  • Mint Cap Management: The contract implements a mint cap that can be adjusted by authorized roles.

  • Value Accounting: The contract implements a harvest mechanism that accounts for increased collateral value by minting USD0a tokens to the yield treasury based on configured APY and daily harvest fee.

  • Dynamic Pricing: The contract calculates the USD0a price in USD based on collateral backing and total supply.

Functions Description

Public/External Functions

  • pause(): Pauses all token transfer operations; callable only by the PAUSING_CONTRACTS_ROLE.

  • unpause(): Resumes all token transfer operations; callable only by the UNPAUSING_CONTRACTS_ROLE.

  • mint(address to, uint256 amount): Mints tokens to a non-blacklisted address if the caller has the USD0X_MINT role and the mint cap is not exceeded.

  • burn(uint256 amount) and burnFrom(address account, uint256 amount): Burns tokens from an address, requiring the USD0X_BURN role.

  • setMintCap(uint256 newMintCap): Updates the maximum amount of USD0a that can be minted; callable only by the MINT_CAP_OPERATOR role. The new mint cap must be greater than or equal to the current total supply.

  • getMintCap(): Returns the current mint cap for USD0a.

  • blacklist(address account) and unblacklist(address account): Allows the admin to blacklist or remove from blacklist malicious users from using this token. Only callable by the BLACKLIST_ROLE.

  • isBlacklisted(address account): Checks if an address is blacklisted.

  • harvest(): Only callable by USD0X_HARVEST_OPERATOR_ROLE. Can only be called once per day (enforced by HARVEST_FREQUENCY).

  • setDailyHarvestFee(uint256 newDailyHarvestFee): Sets the daily harvest fee (in basis points). Only callable by USD0X_HARVEST_FEE_OPERATOR_ROLE. Maximum allowed is 25% (2500 basis points).

  • setAnnualPercentageYield(uint256 newAnnualPercentageYield): Sets the annual percentage yield (in basis points). Only callable by USD0X_HARVEST_APY_OPERATOR_ROLE. Maximum allowed is 100% (10000 basis points).

  • getUsd0xPriceInUSD(bool roundingUp): Returns the USD price of 1 USD0a token based on collateral backing. The price is calculated as total collateral value divided by total supply. Can return with floor or ceiling rounding.

  • getDailyHarvestFee(): Returns the current daily harvest fee in basis points.

  • getAnnualPercentageYield(): Returns the current annual percentage yield in basis points.

Role-Based Access Control

The contract implements several roles for different operations:

  • USD0X_MINT: Required for minting new tokens

  • USD0X_BURN: Required for burning tokens

  • BLACKLIST_ROLE: Required for managing the blacklist

  • MINT_CAP_OPERATOR: Required for adjusting the mint cap

  • PAUSING_CONTRACTS_ROLE: Required for pausing the contract

  • UNPAUSING_CONTRACTS_ROLE: Required for unpausing the contract

  • USD0X_HARVEST_OPERATOR_ROLE: Required for executing the harvest function

  • USD0X_HARVEST_FEE_OPERATOR_ROLE: Required for setting the daily harvest fee

  • USD0X_HARVEST_APY_OPERATOR_ROLE: Required for setting the annual percentage yield

Safeguards Implementation

  • Pausability: Allows pausing of all token transfers in emergencies

  • Blacklist: Prevents sanctioned addresses from interacting with the token

  • Mint Cap: Limits the maximum supply of USD0a

  • Role-Based Access: Restricts sensitive operations to authorized roles

  • Harvest Frequency Limit: Prevents harvest from being called too frequently (minimum 1 day - 60 seconds between harvests)

  • Harvest Fee Limits: Maximum daily harvest fee is capped at 25% (2500 basis points)

  • APY Limits: Maximum annual percentage yield is capped at 100% (10000 basis points)

  • Mint Cap Validation: Ensures new mint cap is not smaller than current total supply

Key Components

  • Oracle Integration: Uses an oracle to fetch real-time price data for collateral tokens when calculating USD0a price.

  • Token Mapping: Manages the list of supported collateral tokens through the TokenMapping contract.

  • Access Control: Implements role-based access control for administrative functions through the RegistryAccess contract.

  • Yield Treasury: Receives minted USD0a tokens from the harvest mechanism, which accounts for increased collateral value and benefits all USD0a holders proportionally.

  • Collateral Treasury: Holds the collateral tokens that back USD0a tokens

PreviousUSD0++NextETH0

Last updated

Was this helpful?