> For the complete documentation index, see [llms.txt](https://csigma-edge.gitbook.io/csigma-protocol/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://csigma-edge.gitbook.io/csigma-protocol/technical-resources/csusd-architecture.md).

# csUSD Architecture

**csUSD (cSigma USD)** is the unified, yield-bearing token at the core of the Edge platform.\
It is designed to replace multiple legacy ERC-4626 pools with a single **multi-asset ERC-7575 vault**, simplifying the user experience and improving capital efficiency.

When users deposit supported stablecoins (currently **USDC** and **USDT**) into Edge, they receive **csUSD**, which represents their proportional ownership of the total vault assets. As institutional borrowers repay loans with interest, the value of csUSD increases — delivering yield directly through the token’s exchange rate.

***

### Architecture Components

The csUSD protocol is composed of the following smart contract modules:

1. #### ERC-7575 Sub-Vaults
2. #### Share Token (csUSD ERC-20)
3. #### Fund Manager
4. #### Asset Oracle
5. #### Withdraw Managers (per Sub-Vault)
6. #### Router (Cross-Chain Bridge)

<figure><img src="/files/hGWAia1FQD2TriN3ADB8" alt="" width="563"><figcaption></figcaption></figure>

***

#### 1. ERC-7575 Sub-Vaults

* One **sub-vault** is deployed for each underlying asset type:
  * **USDC Vault**
  * **USDT Vault**
* Each sub-vault inherits the [**ERC-7575 multi-asset tokenized vault standard**](https://eips.ethereum.org/EIPS/eip-7575)
* Sub-vaults manage deposits, withdrawals, and accounting for that specific asset
* Yield from all sub-vaults is aggregated into the csUSD token

**Benefits of ERC-7575:**

* Native support for multiple assets within a single vault system
* Interoperable with DeFi protocols
* Standardized accounting and share minting

**How to Mint:**

```solidity
/// @notice mints exactly shares vault shares to receiver 
//          by depositing assets of underlying tokens.
function mint(uint256 shares, address receiver) public returns (uint256 assets);

/// @notice deposits assets of underlying tokens into the vault
//          and grants ownership of shares to receiver.
function deposit(uint256 assets, address receiver) public returns (uint256 shares);
```

<figure><img src="/files/76DXKQAzcoUnCwIzgpLw" alt=""><figcaption></figcaption></figure>

**How to Redeem:**

```solidity
/// @notice redeems a specific number of shares from owner and sends assets of underlying token
//           from the vault to receiver. 
function redeem(uint256 shares, address receiver, address owner) public returns (uint256 assets);

/// @notice burns shares from owner and send exactly assets token
//          from the vault to receiver.
function withdraw(uint256 assets, address receiver, address owner) public returns (uint256 shares);
```

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

***

#### 2. Share Token (csUSD ERC-20)

* **ERC-20 token** that represents a user’s share of the **entire csUSD vault**
* Minted when users deposit into any sub-vault
* Burned when users withdraw underlying assets
* Backed by a proportional claim on all sub-vault reserves and deployed capital
* Transferable like any ERC-20, making csUSD composable across DeFi

***

#### 3. Fund Manager

* Oversees capital deployment across **cSigma Institutional Borrower Pools**
* Allocates funds from USDC and USDT sub-vaults to multiple lending strategies
* Monitors repayments, interest accrual, and liquidity buffers
* Updates the Oracle with real-time asset valuations

**Responsibilities:**

* Maintain optimal reserve ratios for instant withdrawals
* Diversify lending to reduce counterparty risk
* Rebalance between sub-vaults if necessary

***

#### 4. Asset Oracle

The **Csigma Asset Oracle** is a critical component of the csUSD ecosystem. It provides real-time asset pricing, valuation, and conversion logic for supported stablecoins (e.g., USDC, USDT) using trusted price feeds.

#### Purpose

* Tracks and manages all supported assets and their associated Chainlink USD price feeds.
* Calculates accurate USD values for underlying assets across csUSD sub-vaults.
* Provides exchange rate and conversion logic between underlying assets and csUSD share tokens.
* Enforces strict price bounds and staleness checks to protect against faulty or manipulated price data.

#### Key Features

1. **Supported Assets Registry**
   * Each asset has:
     * Pool address where it is deployed.
     * Chainlink price feed.
     * Decimals for both token and price feed.
     * Price bounds (`lowerBound`, `upperBound`) for peg stability.
     * Validity period for price freshness.
2. **Price Retrieval**
   * Fetches latest price from Chainlink oracles.
   * Normalizes to 18 decimals.
   * Optionally enforces bounds for stricter price safety.
   * Rejects stale data beyond configured validity period.
3. **Total USD Valuation**
   * Aggregates the USD value of all supported assets held across sub-vault pools.
   * Used to determine the csUSD exchange rate.
4. **Exchange Rate Calculation**
   * `exchangeRate()` = `totalAssetsUSD / csUSD totalSupply`
   * Ensures fair share token pricing based on actual reserves.
5. **Conversion Functions**
   * `convertToShares(token, assets)` → Estimates how many csUSD a deposit will mint.
   * `convertToAssets(token, shares)` → Estimates how much of an underlying token a csUSD redemption will return.
6. **Role-Based Access Control**
   * `DEFAULT_ADMIN_ROLE` → Full control over upgrades and role assignments.
   * `ROLE_MANAGER` → Can add/remove assets, update price ranges.

#### Cross-Module Role

The Asset Oracle is consumed by:

* **Sub vaults** → To value deposits and withdrawals in USD terms.
* **Withdraw Managers** → To calculate fair redemption amounts.
* **Frontend UI** → To display accurate AUM and exchange rates to users.

#### Example Flow

1. **User Deposits USDC**
   * Oracle fetches USDC/USD price from Chainlink.
   * Value normalized to 18 decimals.
   * Converted to USD amount → csUSD minted accordingly.
2. **User Redeems csUSD**
   * Oracle calculates USD value of csUSD shares.
   * Converts back to underlying stablecoin amount at current oracle price.
   * Amount returned to user.

#### Security Measures

* **Bounds Enforcement:** Rejects prices outside a configured peg range (e.g., ±1%).
* **Staleness Checks:** Rejects oracle prices older than the validity period.
* **Upgradeable via UUPS:** Allows protocol improvements while retaining security.

***

#### 5. Withdraw Managers (per Sub-Vault)

* One Withdraw Manager is assigned to **each sub-vault** (USDC, USDT)
* Handles withdrawal requests when immediate liquidity is insufficient
* Implements **FIFO queue** to ensure fairness
* Continues to accrue yield on queued withdrawals until fulfillment

**Key Functions:**

```solidity
requestWithdrawal(uint256 _LPTokenAmount, address receiver)
repay(uint256 uptoQueuePosition, uint256 amount)
claim(uint256 queuePosition, uint256 repaymentDataIndex)
```

***

#### 6. Router (Cross-Chain Bridge)

* Integrates with **LayerZero** and **Stargate** to support deposits and withdrawals across multiple chains.
* Bridges both **underlying stablecoins** and **csUSD share tokens**.
* Ensures seamless user experience regardless of origin or destination chain.

**Cross-Chain Deposit Flow**

1. User deposits **USDC/USDT** on Source Chain
2. Tokens bridged to target chain via **Stargate**
3. Deposit executed in corresponding **sub-vault**
4. **csUSD** minted to user wallet on target chain

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

**Cross-Chain Withdrawal Flow**

1. User initiates withdrawal on source chain
2. **csUSD tokens** burned, underlying assets released
3. Assets bridged to user’s target chain
4. Delivered in chosen stablecoin (**USDC** or **USDT**)

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