# System Architecture

## High-Level Overview

The BaseCase protocol implements a multi-phase prediction market system with the following component structure:

{% @mermaid/diagram content="flowchart TB
Frontend\["Frontend<br/>React + Wagmi + Viem"]

```
ShadowMarket["ShadowMarket<br/>Virtual CPMM + Share Accounting"]

TokenMinting["Token Minting<br/>ERC-20 YES/NO"]
UMA["UMA Oracle<br/>Resolution"]
OrderBook["Order Book<br/>Post-Graduation"]

Frontend --> ShadowMarket
ShadowMarket --> TokenMinting
ShadowMarket --> UMA
ShadowMarket --> OrderBook

style Frontend fill:#e0f2fe,stroke:#0284c7,stroke-width:2px,color:#000000
style ShadowMarket fill:#f0fdf4,stroke:#22c55e,stroke-width:2px,color:#000000
style TokenMinting fill:#fef3c7,stroke:#f59e0b,stroke-width:2px,color:#000000
style UMA fill:#fce7f3,stroke:#ec4899,stroke-width:2px,color:#000000
style OrderBook fill:#ede9fe,stroke:#8b5cf6,stroke-width:2px,color:#000000" %}
```

***

## Component Responsibilities

### Frontend Layer

| Component        | Technology    | Function                          |
| ---------------- | ------------- | --------------------------------- |
| UI Framework     | React 18      | User interface rendering          |
| State Management | React Context | Application state                 |
| Web3 Integration | Wagmi + Viem  | Blockchain interaction            |
| Build Tool       | Vite          | Development and production builds |

### Contract Layer

| Contract          | Responsibility                  |
| ----------------- | ------------------------------- |
| MarketFactory     | Market creation and registry    |
| ShadowMarket      | Virtual CPMM, shadow accounting |
| GraduationManager | Token minting, distribution     |
| OutcomeToken      | ERC-20 YES/NO token contracts   |
| OracleResolver    | UMA Oracle integration          |

### External Integrations

| System     | Purpose                          |
| ---------- | -------------------------------- |
| ERC-20     | Standard token interface         |
| UMA Oracle | Decentralized dispute resolution |
| Order Book | Post-graduation trading venue    |

***

## Data Flow

### Phase 1: Bonding Curve

```
User Action          Contract State             Result
────────────         ─────────────              ──────
USDC Deposit    →    vNO += amount        →    Soulbound tokens issued
                     vault += amount           (no fees during bonding)
                     vYES = k/vNO
                     
Token Sell      →    vYES += shares       →    USDC returned
                     vNO = k/vYES              (no fees)
                     vault -= payout
```

### Phase 2: Graduation

```
Trigger                    Process                    Result
───────                    ─────────                  ──────
Solvency ≥100%        →    1. Verify 20% min sides → Tokens become transferable
+ 20% min each side        2. Deduct 2% fee           Order book enabled
                           3. Unlock tokens            Complete Sets active
                           4. Enable order book
```

### Phase 3: Resolution (Winner Profit Guarantee)

```
Event                  Process                    Result
─────                  ─────────                  ──────
Market End Time   →    Oracle assertion      →   Winners get $1/share + OG bonus
                       Dispute window             Losers receive $0
                       Settlement
```

***

## State Machine

Markets progress through a defined lifecycle:

{% @mermaid/diagram content="stateDiagram-v2
\[\*] --> CREATED: Market Created
CREATED --> BONDING: Trading Opens

```
BONDING --> GRADUATED: Solvency ≥ 100%
BONDING --> FAILED: Deadline Expired

GRADUATED --> RESOLVED: Oracle Settlement
GRADUATED --> DISPUTED: Dispute Filed

DISPUTED --> RESOLVED: Dispute Settled

RESOLVED --> [*]
FAILED --> [*]" %}
```

| State     | Description                     | Transitions         |
| --------- | ------------------------------- | ------------------- |
| CREATED   | Market initialized              | → BONDING           |
| BONDING   | Virtual CPMM active             | → GRADUATED, FAILED |
| GRADUATED | Real tokens, Order Book trading | → RESOLVED          |
| FAILED    | Solvency not reached            | Terminal            |
| RESOLVED  | Outcome determined              | Terminal            |
| DISPUTED  | Oracle dispute active           | → RESOLVED          |

***

## Technology Stack

| Layer                 | Technology               |
| --------------------- | ------------------------ |
| Blockchain            | Base (Ethereum L2)       |
| Smart Contracts       | Solidity 0.8.20          |
| Development Framework | Foundry                  |
| Frontend              | React + Vite             |
| Web3 Library          | Wagmi + Viem             |
| Indexing              | The Graph (planned)      |
| Oracle                | UMA Optimistic Oracle V3 |

***

## Security Architecture

### Trust Assumptions

| Component       | Trust Requirement            |
| --------------- | ---------------------------- |
| Smart Contracts | Code correctness (auditable) |
| UMA Oracle      | Honest majority of voters    |
| Order Book      | Contract security            |
| Base L2         | Sequencer liveness           |

### Attack Vectors and Mitigations

| Vector              | Mitigation                               |
| ------------------- | ---------------------------------------- |
| Price manipulation  | CPMM slippage, fee accumulation          |
| Flash loan attacks  | No flash loan integration points         |
| Oracle manipulation | UMA dispute mechanism, bond requirements |
| Front-running       | Slippage tolerance parameters            |