> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ondo.finance/llms.txt
> Use this file to discover all available pages before exploring further.

# Integration Guidelines for Protocols Supporting USDY on Mantle

## **USDY & mUSD**

### USDY

**USDY (US Dollar Yield Token)**: USDY is a tokenized note secured by short-term US Treasuries and bank demand deposits. USDY holders receive yield generated from the underlying assets in the form of increasing redemption value (accumulating token). USDY contract is an upgradeable (Transparent Upgradeable Proxy) ERC-20 token. To hold, send, and receive USDY, users should not be on the [blocklist](https://github.com/code-423n4/2023-09-ondo/blob/main/contracts/usdy/blocklist/Blocklist.sol).

### mUSD

**mUSD** is the rebasing version of USDY, maintaining a consistent peg to \$1. Interest is distributed via new token units. Users can swap freely between USDY and mUSD. A swapper UI will be available in October on [ondo.finance](https://ondo.finance/).

mUSD is heavily based on other rebasing tokens such as `stETH`. Users can acquire mUSD tokens by calling the `wrap(uint256)` function on the contract. While the price of a single USDY token increases over time, the price of a single mUSD token is fixed at a price of 1 Dollar, with yield being accrued in the form of additional mUSD tokens. Similarly when a user wishes to convert their `mUSD` to `USDY` they can call the `unwrap(uint256)` function, and receive their corresponding amount of `USDY`.

In order to determine the USD value of the USDY locked in the contract, mUSD will call into `RWADynamicRateOracle.sol` in order to fetch the current price.

Because `mUSD` is the rebasing variant of `USDY` the same transfer restrictions for `USDY` are also applied to the `mUSD` token in the `beforeTransfer(address,address,uint256)` hook.

`mUSD` rebases daily at 12:00am GMT.

## USDY Oracle (**RWADynamicRateOracle)**

The RWADynamicRateOracle contract is used to post price evolution for USDY on chain. This contract accepts a [`Range`](https://github.com/code-423n4/2023-09-ondo/blob/main/contracts/rwaOracles/RWADynamicOracle.sol#L295) as input from a trusted admin, and will apply the following conversion to the `lastSetPrice` for a given range:

```
currentPrice = (Range.dailyInterestRate ** (Days Elapsed + 1)) * Range.lastSetPrice
```

There is a functionality within the contract that if a range has elapsed and there is no subsequent range set, the oracle will return the maximum price of the previous range for all `block.timestamp` > `Range.end`

## Integrating USDY into Your Web3 Application

As users may hold USDY or mUSD, a good practice is to support both.

Let's assume a user holds mUSD and wants to supply to your USDY pool.

### Option 1: Native integration

The user can directly use his mUSD to interact with your contracts. This means that your contracts will add an extra call to swap from mUSD to USDY before depositing the USDY in the pool.

Example of a native integration: [Compound pool on curve.fi](https://curve.fi/#/ethereum/pools/compound/deposit)

<div style={{display: "flex", gap: "1.5rem", marginTop: "2rem"}}>
  <div style={{display: "flex", justifyContent: "space-between", flexDirection: "column"}}>
    <img src="https://mintcdn.com/ondofinance-8a00cd96/KRJ38X1ymyGq9hDd/images/docs/curve1.png?fit=max&auto=format&n=KRJ38X1ymyGq9hDd&q=85&s=cbf1b70b9684a3e504963ef12f686965" alt="Curve unwrapped" width="772" height="1200" data-path="images/docs/curve1.png" />

    <br />

    <figcaption>The user can deposit stables (unwrapped)</figcaption>
  </div>

  <div style={{display: "flex", justifyContent: "space-between", flexDirection: "column"}}>
    <img src="https://mintcdn.com/ondofinance-8a00cd96/KRJ38X1ymyGq9hDd/images/docs/curve2.png?fit=max&auto=format&n=KRJ38X1ymyGq9hDd&q=85&s=6efb942cd8bca3a0b177205badaad317" alt="Curve wrapped" width="754" height="1152" data-path="images/docs/curve2.png" />

    <br />

    <figcaption>...or stables lent into Compound (wrapped)</figcaption>
  </div>
</div>

### Option 2: Informative integration

When trying to supply mUSD, your app informs the user they need to swap to USDY before depositing to the pool: "To supply USDY, you must first swap your mUSD for USDY at [ondo.finance](https://ondo.finance)"

Example of an informative integration: [wstETH on Balancer](https://app.balancer.fi/#/ethereum/pool/0x93d199263632a4ef4bb438f1feb99e57b4b5f0bd0000000000000000000005c2/add-liquidity)

<div style={{ display: "flex", alignItems: "start", marginTop: "2rem" }}>
  <div
    style={{
  display: "flex",
  justifyContent: "space-between",
  flexDirection: "column",
  alignItems: "center",
}}
  >
    <img src="https://mintcdn.com/ondofinance-8a00cd96/KRJ38X1ymyGq9hDd/images/docs/balancer.png?fit=max&auto=format&n=KRJ38X1ymyGq9hDd&q=85&s=220d67c89efb9ca9a2f60aa161953e98" alt="Balancer guidelines" width="980" height="938" data-path="images/docs/balancer.png" />

    <br />

    <figcaption>The user is informed on how to wrap/unwrap</figcaption>
  </div>
</div>

## SmartContracts details

* **[rUSDY.sol](https://github.com/code-423n4/2023-09-ondo/blob/main/contracts/usdy/rUSDY.sol)** - This contract serves as the backbone for an interest-bearing token where users can `wrap and unwrap` their `USDY` tokens to earn interest. It also includes features for access control and address management.
* **[rUSDYFactory.sol](https://github.com/code-423n4/2023-09-ondo/blob/main/contracts/usdy/rUSDYFactory.sol)** - This is a factory contract that allows the deployment of upgradable instances of the `mUSD token` contract. It is managed by a guardian address, and the deployment process involves creating an implementation contract, a proxy admin contract, and a proxy contract for the token. The code is designed to facilitate the upgradeability of the `mUSD` token and includes functions for batched external calls.
* **[RWADynamicOracle.sol](https://github.com/code-423n4/2023-09-ondo/blob/main/contracts/rwaOracles/RWADynamicOracle.sol)** - This contract is a dynamic Oracle that provides the price of `USDY` based on configured time ranges and daily interest rates. It also includes mechanisms for pausing and access control to manage the ranges and contract operation.
* **[IRWADynamicOracle](https://github.com/code-423n4/2023-09-ondo/blob/main/contracts/rwaOracles/IRWADynamicOracle.sol)** - This is an interface that sets a standard for any contract wishing to provide information about the price of `RWA` (Asset-Backed Real World Assets) or similar assets. Contracts that implement this interface must provide a `getPrice()` function that returns the current price of `RWA`. The interface does not contain implementation logic but simply establishes a common structure for communication with dynamic asset price oracles.

## Resources

* [Media Kit](https://www.notion.so/3bc0a5aced014cc4b0ef62f1638bbf8e?pvs=21)
* [Contract addresses](/addresses)
* [Audits](/audits)
* [USDY github repository](https://github.com/ondoprotocol/usdy)

<Snippet file="usdy-legal-notice.mdx" />