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


---

# 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/contracts.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.