# Graduation Protocol

## Overview

Graduation is the protocol mechanism that transitions a market from the bonding phase to order book trading. With our **Zero-Migration Architecture**, tokens already exist during bonding as "soulbound" ERC-20s—graduation simply enables transfers and deploys the Order Book.

***

## Graduation Trigger

The market graduates when **all** conditions are met:

1. **Bonding Target**: Vault balance ≥ bonding target (default $1,000 USDC, admin-configurable)
2. **Solvency**: Vault balance ≥ MAX(TotalYES, TotalNO)
3. **Market Balance**: Each side has ≥ 20% of total tokens

```
canGraduate = (VaultBalance ≥ bondingTarget) 
           AND (Solvency ≥ 100%)
           AND (YES / Total ≥ 20%)
           AND (NO / Total ≥ 20%)
```

> \[!IMPORTANT] The **20% minimum side ratio** ensures healthy two-sided markets. One-sided markets (e.g., 95% YES / 5% NO) cannot graduate until more balanced.

This ensures markets have meaningful liquidity and genuine two-sided participation before transitioning to order book trading.

***

## Solvency Calculation

### Example State

| Metric            | Value                      |
| ----------------- | -------------------------- |
| Total YES Tokens  | 10,000 shares              |
| Total NO Tokens   | 8,000 shares               |
| Maximum Liability | 10,000 (if YES wins)       |
| Vault Balance     | $10,500                    |
| **Solvency**      | 10,500 / 10,000 = **105%** |

At 105% solvency, graduation is triggered.

***

## Zero-Migration Graduation

Unlike traditional systems that mint tokens at graduation, BaseCase uses **Zero-Migration**:

> **Tokens exist from the start**, minted directly when users buy during bonding. Graduation just "unlocks" them by enabling transfers.

### Graduation Sequence

| Step | Operation            | Description                                   |
| ---- | -------------------- | --------------------------------------------- |
| 1    | Verify               | Check all graduation conditions met           |
| 2    | Fee Extraction       | Deduct 2% graduation fee                      |
| 3    | Fee Distribution     | 50% Protocol / 25% Stakers / 25% Creator      |
| 4    | **Enable Transfers** | Call `enableTransfers()` on YES and NO tokens |
| 5    | Deploy Order Book    | Deploy OrderBook contract                     |
| 6    | Trading Active       | Users can now trade tokens freely             |

### Key Advantage: O(1) Gas Cost

```
OLD (Manual Migration):
  - Admin calls mintTokensToHolders(holders[])
  - Iterates through every holder
  - Gas scales with number of users: O(n)
  - Could run out of gas with many holders!

NEW (Zero-Migration):
  - Contract calls enableTransfers()
  - Single state change
  - Gas is constant: O(1)
  - Works with any number of holders!
```

***

## Token Architecture

### Token Lifecycle

{% @mermaid/diagram content="flowchart TB
Create\["Market Created"]
Bonding\["Bonding Phase\u003cbr/\u003eTokens soulbound"]
Graduation\["Graduation"]
Trading\["Order Book\u003cbr/\u003eTokens transferable"]

```
Create --> Bonding
Bonding --> Graduation
Graduation --> Trading

style Create fill:#f0fdf4,stroke:#22c55e,stroke-width:2px,color:#000000
style Bonding fill:#fef3c7,stroke:#f59e0b,stroke-width:2px,color:#000000
style Graduation fill:#eff6ff,stroke:#3b82f6,stroke-width:2px,color:#000000
style Trading fill:#ede9fe,stroke:#8b5cf6,stroke-width:2px,color:#000000" %}
```

### Token Specifications

| Token     | Standard | Phase           | Transferable |
| --------- | -------- | --------------- | ------------ |
| YES Token | ERC-20   | Bonding         | ❌ Soulbound  |
| NO Token  | ERC-20   | Bonding         | ❌ Soulbound  |
| YES Token | ERC-20   | Post-Graduation | ✅ Full       |
| NO Token  | ERC-20   | Post-Graduation | ✅ Full       |

Each market deploys its own YES and NO token contracts **at market creation**.

***

## Order Book Activation

Upon graduation, the Order Book is enabled for secondary trading:

### Trading Capabilities

| Feature            | Description                       |
| ------------------ | --------------------------------- |
| Limit Orders       | Place orders at specific prices   |
| Market Orders      | Execute immediately at best price |
| Order Cancellation | Cancel unfilled orders anytime    |
| Price Discovery    | Supply/demand matching            |

***

## Post-Graduation State Changes

| Property          | Before           | After            |
| ----------------- | ---------------- | ---------------- |
| Trading Venue     | Protocol CPMM    | Order Book       |
| Fee Rate          | 2%               | 0.1% (taker)     |
| Token Transfers   | ❌ Blocked        | ✅ Enabled        |
| Limit Orders      | Not available    | Available        |
| Wallet Visibility | Visible (ERC-20) | Visible (ERC-20) |

***

## Failed Graduation

If the bonding deadline expires before reaching graduation conditions:

### Refund Mode Activation

```
IF (block.timestamp > bondingDeadline) AND (Solvency < 100% OR Vault < bondingTarget)
THEN activateRefundMode()
```

### Refund Calculation

Users receive a pro-rata share of the vault:

```
UserRefund = (UserDeposits / TotalDeposits) × VaultBalance
```

### Expected Recovery

| Solvency at Deadline | Expected Recovery |
| -------------------- | ----------------- |
| 90-99%               | \~90-95%          |
| 80-89%               | \~85-90%          |
| < 80%                | \~80-85%          |

Recovery is less than 100% due to fees paid and slippage incurred during trading.

***

## Atomicity Requirements

The graduation process executes atomically:

* **Single Transaction**: All graduation operations complete together
* **No Front-Running**: Price manipulation impossible
* **Consistent State**: Tokens enabled for all users simultaneously

With Zero-Migration, atomicity is guaranteed since `enableTransfers()` is a single state change affecting all holders equally.