Protocol Flow

This document describes the complete lifecycle of a BaseCase prediction market, from creation through resolution.

---

Market Lifecycle Overview

---

Phase 1: Market Creation

Initialization Parameters

Parameter	Description	Example
Question	Binary yes/no question	"Will BTC hit $150k by Jan 1?"
End Time	When trading stops	January 1, 2025 00:00 UTC
Bonding Period	Duration of curve phase	7 days
Virtual Reserve	Initial vYES and vNO	1,000 each

Initial State

vYES = 1,000
vNO = 1,000
k = vYES × vNO = 1,000,000

YES Price = vNO / (vYES + vNO) = 50%
NO Price = vYES / (vYES + vNO) = 50%

Vault = $0
Shadow YES = 0
Shadow NO = 0

---

Phase 2: Bonding Curve Trading

Trading Mechanics

During the bonding phase, users trade against a virtual Constant Product Market Maker (CPMM).

Buy Operation:

Input: USDC amount (A)

For YES purchase:
1. vNO_new = vNO + A
2. vYES_new = k / vNO_new
3. Shares = vYES_old - vYES_new
4. Vault += A

Sell Operation:

Input: Share quantity (S)

For YES sale:
1. vYES_new = vYES + S
2. vNO_new = k / vYES_new
3. cpmmPayout = vNO_old - vNO_new
4. Payout = MIN(cpmmPayout, S)  ← $1 CAP
5. Vault -= Payout

[!TIP] Winner Profit Guarantee: Buy operations include a $1 ceiling (min 1 share per $1), and sell operations have a $1 cap (max $1 payout per share). This ensures the vault can always pay $1/share to winners.

Example Trading Sequence

Action	Trader	Amount	Shares	Price	Vault
Buy YES	Alice	$500	500	$1.00	$500
Buy NO	Bob	$300	300	$1.00	$800
Buy YES	Charlie	$1,000	1,000	$1.00	$1,800
Buy YES	Dave	$2,000	2,000	$1.00	$3,800
Sell YES	Charlie	1,000	-	$0.95	$2,850
Buy NO	Eve	$2,000	2,150	$0.93	$4,850

Solvency Tracking

The protocol continuously monitors solvency:

Solvency = Vault Balance / MAX(Total Shadow YES, Total Shadow NO)

Checkpoint	Shadow YES	Shadow NO	Vault	Solvency
After trade 3	2,305	294	$1,800	78.1%
After trade 4	4,125	294	$3,800	92.1%
After trade 5	3,175	294	$2,765	87.1%
After trade 6	3,175	2,444	$4,765	150.1% ✓

Graduation Trigger

When solvency reaches 100%, the market qualifies for graduation:

Solvency >= 100% → Graduation eligible

Graduation can be triggered by any user calling the graduate() function.

---

Phase 3: Graduation

Graduation Sequence

Step 1: FREEZE
├── Disable bonding curve trading
├── Snapshot shadow balances
└── Lock current state

Step 2: CALCULATE
├── Total YES claims = Shadow YES total
├── Total NO claims = Shadow NO total
├── Required collateral = MAX(YES, NO)
└── Excess = Vault - Required

Step 3: MINT
├── Lock required USDC in vault as collateral
├── Mint ERC-20 YES and NO tokens
├── Total tokens = MAX(Shadow YES, Shadow NO)
└── Collateral locked in vault contract

Step 4: DISTRIBUTE
├── Transfer YES tokens to shadow YES holders (1:1)
├── Transfer NO tokens to shadow NO holders (1:1)
├── Excess tokens retained by protocol
└── Excess USDC to treasury

Step 5: OPEN ORDER BOOK
├── Initialize YES/USDC order book
├── Initialize NO/USDC order book
├── Enable limit order placement
└── Enable order matching

Example Graduation

Pre-Graduation State:

Shadow YES: 8,285 shares
Shadow NO: 3,024 shares
Vault: $12,259
Solvency: 148%

Graduation Execution:

Required sets: MAX(8,285, 3,024) = 8,285
Collateral locked: $8,285
Graduation fee (2%): $165

Token minting:
├── 8,285 YES tokens created
└── 8,285 NO tokens created

Distribution:
├── 8,285 YES → Shadow YES holders
├── 3,024 NO → Shadow NO holders
├── 5,261 NO → Protocol treasury
└── $3,809 USDC → Protocol treasury

---

Phase 4: Order Book Trading

Order Book Structure

Post-graduation, trading occurs on a Central Limit Order Book (CLOB):

YES/USDC Order Book
──────────────────────────────────────
ASKS (Sell orders)
├── $0.68 × 500 shares
├── $0.67 × 200 shares
├── $0.66 × 800 shares
────────────────────── Spread: $0.02
BIDS (Buy orders)
├── $0.64 × 1,000 shares
├── $0.62 × 500 shares
└── $0.60 × 2,000 shares

Order Types

Order Type	Description
Limit	Place order at specific price
Market	Execute against best available
Cancel	Remove unfilled order

No Liquidity Required

Unlike AMM-based post-graduation:

Aspect	AMM (Uniswap V3)	Order Book
LP capital needed	Yes (protocol seeds)	No
Price discovery	Formula-based	Supply/demand
Spread control	Tick ranges	Maker competition
Limit orders	Indirect	Native

Price Constraint

Order books enforce the binary outcome constraint:

YES_price + NO_price = $1.00

Valid:   YES @ $0.65 implies NO @ $0.35
Invalid: YES @ $0.65 with NO @ $0.40 (sum = $1.05)

---

Phase 5: Resolution

Oracle Process

Step 1: Market end time reached
├── Trading continues until resolution
└── No new information restrictions

Step 2: Assertion
├── Any user can propose outcome
├── Bond required: $100 USDC
└── Assertion: "YES" or "NO"

Step 3: Dispute Window
├── Duration: 2 hours
├── Disputers can challenge with counter-bond
└── If disputed → UMA DVM vote

Step 4: Settlement
├── If undisputed → Assertion accepted
├── If disputed → DVM determines outcome
└── Winning asserter receives bond back + reward

Token Redemption (Fixed $1 + OG Bonus)

Resolution: YES wins

Base Payout = User YES Shares × $1.00
OG Bonus = (User OG Shares / Total OG Shares) × OG Bonus Pool
Total Payout = Base Payout + OG Bonus

NO token value: $0.00

Redemption:
├── User calls claimWinnings()
├── Contract calculates: shares × $1 + OG bonus
├── Transfers USDC to user
└── Burns claimed tokens

Collateral Flow

Initial:  Vault holds $8,285 collateral
          8,285 YES tokens outstanding
          8,285 NO tokens outstanding

If YES wins:
├── 8,285 YES × $1.00 = $8,285 claimed
├── 8,285 NO × $0.00 = $0 claimed
└── Collateral exactly matches payouts

If NO wins:
├── 8,285 YES × $0.00 = $0 claimed
├── 8,285 NO × $1.00 = $8,285 claimed
└── Collateral exactly matches payouts

---

Fee Structure Summary

Phase	Fee	Distribution
Bonding - Buy	0%	—
Bonding - Sell	0%	—
Graduation	2%	50% Protocol / 25% Stakers / 25% Creator
Order Book - Maker	0%	—
Order Book - Taker	~0.2%	TBD
Resolution	0%	—

[!NOTE] Bonding phase has zero trading fees. Solvency is maintained through CPMM slippage mechanics, not fees.

Creator Rewards Example

Market graduates with $10,000 vault:

Graduation fee: 2% × $10,000 = $200
├── Protocol: $100 (50%)
├── Stakers:  $50  (25%)
└── Creator:  $50  (25%)

Post-graduation trading volume: $50,000
Taker fees: ~0.2% × $50,000 = ~$100
├── (Distribution TBD)

Total Creator Earnings (graduation only): $50

---

Risk Analysis

Solvency Guarantee

The protocol guarantees payout solvency through:

1. CPMM Slippage: Large one-sided trades pay premium prices

2. Natural Accumulation: Vault grows through buyer deposits

3. Graduation Threshold: Cannot graduate below 100% solvency + 20% each side

4. Collateral Lock: Vault holds required amount at graduation

Failure Modes

Scenario	Trigger	Resolution
Failed graduation	Solvency < 100% at deadline	Pro-rata refund
Oracle dispute	Challenged assertion	UMA DVM vote
Invalid market	Ambiguous question	Refund mode

---

Contract Interactions

User Actions by Phase

Bonding Phase:

function buyShadowYes(uint256 usdcAmount) external;
function buyShadowNo(uint256 usdcAmount) external;
function sellShadowYes(uint256 shares) external;
function sellShadowNo(uint256 shares) external;

Graduation:

function graduate() external;  // Anyone can call when eligible
function claimTokens() external;  // Shadow → Real tokens

Order Book:

function placeLimitOrder(bool isYes, bool isBuy, uint256 price, uint256 amount) external;
function cancelOrder(uint256 orderId) external;
function matchOrders(uint256[] orderIds) external;

Resolution:

function assertOutcome(bool outcome) external;  // Requires bond
function disputeAssertion() external;  // Requires counter-bond
function redeemWinnings() external;  // Claim USDC