# Technical Architecture

Foundation utilizes a **Hub-and-Spoke** architecture designed for maximum capital efficiency and security.

***

## System Components

| Component         | Role                                                                      |
| ----------------- | ------------------------------------------------------------------------- |
| **The Hub**       | Foundation Vault — immutable accounting engine                            |
| **The Spokes**    | Yield Strategies — ERC4626 tokenized vaults (PrimeUSD, ApolloUSD, OrdUSD) |
| **The Connector** | Rebalance Router — enables atomic swaps between strategies                |

***

## Core Components

### 1. Prime Manager

The central orchestrator of the Foundation protocol.

| Responsibility            | Description                                     |
| ------------------------- | ----------------------------------------------- |
| **Minting Authority**     | Only contract authorized to mint or burn `USD'` |
| **Permission Management** | Controls strategy whitelisting and access       |
| **Oracle Integration**    | Manages price feeds for NAV calculations        |
| **Minting Limits**        | Enforces per-strategy and global caps           |

### 2. Foundation Vault (Accounting Engine)

The Vault holds all physical collateral and maintains the global solvency mapping.

| Feature                | Implementation                                     |
| ---------------------- | -------------------------------------------------- |
| **Collateral Custody** | USDC, USDT, RWA tokens, LP tokens                  |
| **Ledger Mapping**     | Real-time `Asset ↔ Liability` tracking             |
| **Virtual Settlement** | Internal ledger updates instead of token transfers |

**Key Innovation:** When a user swaps strategies, the Vault updates its internal ledger—crediting one strategy and debiting another—without requiring gas-heavy token transfers.

### 3. Rebalance Router

Enables atomic movement of value between strategies.

| Function                | Description                                        |
| ----------------------- | -------------------------------------------------- |
| **NAV Calculation**     | Queries oracles to determine fair share value      |
| **Burn/Mint Cycle**     | Executes redemption and deposit in one transaction |
| **Slippage Protection** | Enforces `minSharesOut` parameter                  |

***

## Transaction Flow

The rebalancing process executes in two steps within a single atomic transaction:

### Step 1: Virtual Redemption

| Action                | Description                                    |
| --------------------- | ---------------------------------------------- |
| User initiates swap   | Calls `swapStrategies(sharesIn, minSharesOut)` |
| Router redeems shares | Burns source strategy shares                   |
| Vault updates ledger  | Credits USD' to the Router (virtual balance)   |

### Step 2: Virtual Deposit

| Action                     | Description                                   |
| -------------------------- | --------------------------------------------- |
| Router deposits USD'       | Deposits into destination strategy            |
| Vault allocates collateral | Updates internal ledger allocation            |
| User receives shares       | Destination strategy mints new shares to user |

**Result:** Completed in 1 block with 0% slippage.

***

## Security & Risk Management

### Asset Isolation

| Principle                 | Benefit                                                   |
| ------------------------- | --------------------------------------------------------- |
| **Vault-Held Collateral** | Collateral lives in the Vault, not in strategy contracts  |
| **Strategy Sandboxing**   | A bug in one strategy cannot drain collateral from others |
| **Access Controls**       | Only whitelisted strategies can interact with the Vault   |

### Solvency Protection

The global solvency invariant is maintained at all times:

```
Total Assets (Collateral in Vault) ≥ Total Liabilities (Minted USD')
```

### Liquidation Waterfall

In the event a strategy suffers a loss (NAV drops below $1.00):

| Stage                         | Action                                                                 |
| ----------------------------- | ---------------------------------------------------------------------- |
| **1. Strategy Absorbs Loss**  | The specific strategy's share price decreases                          |
| **2. User Impact**            | Only users in *that specific strategy* absorb the loss                 |
| **3. Base Layer Protected**   | USD' peg is maintained because liability decreases 1:1 with asset loss |
| **4. System Remains Solvent** | The global Vault remains solvent; other strategies unaffected          |

***

## Smart Contract Standards

| Standard      | Usage                     |
| ------------- | ------------------------- |
| **ERC20**     | USD' base asset token     |
| **ERC4626**   | All yield strategy vaults |
| **Multi-Sig** | Administrative functions  |
| **Timelock**  | Parameter changes         |