# 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)
***
#### 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);
```
**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);
```
***
#### 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
**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**)
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://csigma-edge.gitbook.io/csigma-protocol/technical-resources/csusd-architecture.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.