# Smart Contracts

## Contract Architecture

The BaseCase protocol comprises a set of interconnected smart contracts deployed on Base (Ethereum L2).

***

## Core Contracts

### ShadowMarket

Primary contract managing the bonding curve phase and shadow share accounting.

```solidity
interface IShadowMarket {
    // State queries
    function virtualYes() external view returns (uint256);
    function virtualNo() external view returns (uint256);
    function vaultBalance() external view returns (uint256);
    function totalShadowYes() external view returns (uint256);
    function totalShadowNo() external view returns (uint256);
    function solvencyPercent() external view returns (uint256);
    
    // Trading
    function buyShadowYes(uint256 usdcAmount) external returns (uint256 shares);
    function buyShadowNo(uint256 usdcAmount) external returns (uint256 shares);
    function sellShadowYes(uint256 shares) external returns (uint256 payout);
    function sellShadowNo(uint256 shares) external returns (uint256 payout);
    
    // Graduation
    function canGraduate() external view returns (bool);
    function graduate() external;
}
```

### MarketFactory

Factory contract for deploying new prediction markets.

```solidity
interface IMarketFactory {
    function createMarket(
        string calldata question,
        uint256 endTime,
        uint256 bondingDuration
    ) external returns (address market);
    
    function getMarkets() external view returns (address[] memory);
    function getMarketCount() external view returns (uint256);
}
```

### GraduationManager

Handles the graduation process and Order Book initialization.

```solidity
interface IGraduationManager {
    function mintOutcomeTokens(address market) external;
    function enableOrderBook(address market) external;
    function setTradingActive(address market) external;
}
```

### OutcomeToken

ERC-20 token contract for YES and NO outcome tokens. Minted at market creation as soulbound, become transferable at graduation.

```solidity
interface IOutcomeToken {
    function mint(address to, uint256 amount) external;
    function burn(address from, uint256 amount) external;
    function marketId() external view returns (bytes32);
    function isYes() external view returns (bool);
    function setSoulbound(bool _soulbound) external;
}
```

### Complete Sets

Post-graduation liquidity mechanism allowing users to mint/redeem YES+NO pairs.

```solidity
// Mint 1 YES + 1 NO for $1 USDC
function mintCompleteSet(uint256 amount) external;

// Redeem 1 YES + 1 NO for $1 USDC
function redeemCompleteSet(uint256 amount) external;
```

***

## External Dependencies

| Contract      | Address (Base)                               | Description                 |
| ------------- | -------------------------------------------- | --------------------------- |
| USDC          | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` | Collateral token            |
| UMA Oracle V3 | `0xfb55F43fB9F48F63f9269DB7Dde3BbBe1ebDC0dE` | Resolution oracle (mainnet) |

> \[!NOTE] **Testnet** uses `LocalResolver` with admin-based dispute resolution instead of UMA Oracle.

***

## Deployment Addresses

| Contract          | Address | Status             |
| ----------------- | ------- | ------------------ |
| MarketFactory     | TBD     | Pending deployment |
| GraduationManager | TBD     | Pending deployment |
| TokenWrapper      | TBD     | Pending deployment |

***

## Configuration Parameters

| Parameter                 | Value                | Description                                                   |
| ------------------------- | -------------------- | ------------------------------------------------------------- |
| `INITIAL_VIRTUAL_RESERVE` | 1,000                | Starting vYES and vNO                                         |
| `bondingTarget`           | 1,000 USDC (default) | Minimum vault for graduation (admin-configurable: $100-$100k) |
| `TRADE_FEE_BPS`           | **0**                | No fees during bonding                                        |
| `GRADUATION_FEE_BPS`      | 200                  | 2% graduation fee                                             |
| `MIN_SIDE_RATIO`          | 2000                 | 20% minimum on each side (basis points)                       |
| `MIN_BONDING_DURATION`    | 1 day                | Minimum bonding period                                        |
| `MAX_BONDING_DURATION`    | 30 days              | Maximum bonding period                                        |

***

## Events

```solidity
// ShadowMarket events
event ShadowBuy(address indexed user, bool isYes, uint256 amount, uint256 shares);
event ShadowSell(address indexed user, bool isYes, uint256 shares, uint256 payout);
event MarketGraduated(uint256 vaultBalance, uint256 totalYes, uint256 totalNo);

// MarketFactory events
event MarketCreated(address indexed market, string question, uint256 endTime);

// Resolution events
event OutcomeProposed(bytes32 assertionId, bool outcome);
event OutcomeResolved(bool outcome);
```

***

## Security Considerations

### Access Control

| Function           | Access                  |
| ------------------ | ----------------------- |
| `buyShadowYes/No`  | Public                  |
| `sellShadowYes/No` | Public                  |
| `graduate`         | Public (permissionless) |
| `setParameters`    | Owner only              |
| `pause/unpause`    | Owner only              |

### Reentrancy Protection

All state-modifying functions implement the checks-effects-interactions pattern and use reentrancy guards where applicable.

### Oracle Trust

Market resolution relies on UMA Optimistic Oracle (mainnet) or LocalResolver (testnet). Users should understand the dispute resolution mechanism and associated risks.

***

## Admin Functions

| Function                     | Description                                   |
| ---------------------------- | --------------------------------------------- |
| `setBondingTarget(uint256)`  | Set minimum vault for graduation ($100-$100k) |
| `setBondingDurations(...)`   | Configure bonding period limits               |
| `setOracleResolver(address)` | Set resolution oracle address                 |