# 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            |


---

# 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://docs.basecase.gg/technical-reference/architecture.md?ask=<question>
```

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.