pnp-markets-solana

# PNP Markets (Solana)

Create and manage prediction markets on Solana with any SPL token collateral. Supports V2 AMM markets, P2P direct bets, custom oracle resolution for AI agents, and social media markets (Twitter, YouTube, DeFiLlama).

## When to Use This Skill

Use when the user wants to:
- **Create prediction markets** on Solana (V2 AMM, P2P, or custom oracle)
- **Trade on markets** (buy/sell YES/NO outcome tokens)
- **Settle markets** as an oracle after the trading period ends
- **Redeem winning positions** after settlement
- **Create social media markets** (Twitter engagement, YouTube views, DeFiLlama metrics)
- **Use custom tokens** as prediction market collateral (any SPL token including Token-2022)
- **Build autonomous AI agents** that create, trade, and resolve markets
- **Build info finance infrastructure** using market prices as probability signals

**Triggers**: `prediction market`, `betting`, `oracle`, `settlement`, `forecast`, `YES/NO`, `outcome token`, `market resolution`, `P2P bet`, `custom oracle`, `social media market`, `autonomous market`, `info finance`, `market creation`, `prediction`, `wager`, `binary outcome`

Do not use when:
- The task is generic Solana wallet operations (use solana-dev-skill instead)
- The task is token swaps/DEX trading without prediction markets (use jupiter-skill)
- The task is NFT-related (use metaplex-foundation/skill)
- The task is about other prediction market protocols (use their specific skill)

---

## Program IDs & Core Constants

| Item | Address | Notes |
|------|---------|-------|
| **PNP Program (Mainnet)** | `8PyE2dizL52ga7ytqLtqRyjwWp4yXEx8M5Z4BAHgHuTb` | Main prediction market program |
| **PNP Program (Devnet)** | `pnpkv2qnh4bfpGvTugGDSEhvZC7DP4pVxTuDykV3BGz` | Devnet testing program |
| **USDC Mint** | `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` | Common collateral (6 decimals) |
| **USDT Mint** | `Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB` | Alternative stable (6 decimals) |
| **WSOL Mint** | `So11111111111111111111111111111111111111112` | Wrapped SOL (9 decimals) |

### Precision Reference

| Token Type | Decimals | Example |
|-----------|----------|---------|
| USDC / USDT | 6 | 1 USDC = `1_000_000n` |
| SOL (wrapped) | 9 | 1 SOL = `1_000_000_000n` |
| Decision tokens (YES/NO) | 6 | Minted per-market by the program |

```typescript
// Conversion helpers
const usdcToRaw = (amount: number) => BigInt(Math.floor(amount * 1_000_000));
const daysFromNow = (days: number) => BigInt(Math.floor(Date.now() / 1000) + days * 86400);

// Example
const liquidity = usdcToRaw(100);  // 100 USDC -> 100_000_000n
const endTime = daysFromNow(7);    // 7 days from now -> Unix timestamp as bigint
```

> [!IMPORTANT]
> **Collateral can be any SPL token or Token-2022 token.** Pass the token's mint address as `baseMint` or `collateralTokenMint`. Make sure to use the correct decimals for the chosen token (e.g., USDC/USDT = 6, SOL = 9). Common mints are listed in the table above for reference.

---

## Prerequisites

1. **Solana Wallet**: Base58-encoded private key with SOL for fees (~0.05 SOL minimum)
2. **Collateral Tokens**: Any SPL token (including Token-2022) for market liquidity — USDC, USDT, SOL, or any custom token
3. **RPC Endpoint**: Mainnet RPC URL (public or dedicated like Helius/QuickNode)

```bash
# Install dependencies
cd scripts && npm install

# Set environment variables
export PRIVATE_KEY=<base58_private_key>
export RPC_URL=https://api.mainnet-beta.solana.com  # or dedicated RPC
```

---

## Quick Start

```typescript
import { PNPClient } from 'pnp-sdk';
import { PublicKey } from '@solana/web3.js';

const client = new PNPClient(
  process.env.RPC_URL || 'https://api.mainnet-beta.solana.com',
  process.env.PRIVATE_KEY!  // Base58 string or Uint8Array
);

// Collateral can be any SPL token (including Token-2022) — use the mint address of your chosen token
const USDC = new PublicKey('EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v');

// Create a prediction market
const result = await client.market.createMarket({
  question: 'Will Bitcoin reach $100K by end of 2025?',
  initialLiquidity: 1_000_000n,  // 1 USDC (6 decimals) — adjust decimals for your collateral token
  endTime: BigInt(Math.floor(Date.now() / 1000) + 30 * 24 * 60 * 60),
  baseMint: USDC,  // Any SPL or Token-2022 mint
});

console.log('Market created:', result.market.toBase58());
// Returns: { signature: string, market: PublicKey }
```

> [!TIP]
> Use `PNPClient.parseSecretKey(process.env.PRIVATE_KEY)` to handle both Base58 strings and JSON array formats automatically.

---

## Market Lifecycle & State Machine

Markets follow a strict state progression:

### V2 AMM Market (Standard)

```
CREATED ──────► ACTIVE ──────► ENDED ──────► RESOLVED ──────► CLAIMED
   │               │              │               │               │
   │          Trading live    No new trades   Oracle declares  Winners redeem
   │          Users buy/sell  allowed         YES/NO winner    collateral
   │          YES/NO tokens
   │
   └── initialLiquidity locked, PNP global oracle resolves
```

### Custom Oracle Market (Agent-Controlled)

```
CREATED ──► [15-MIN BUFFER] ──► ACTIVE ──► ENDED ──► RESOLVED ──► CLAIMED
   │               │                │          │           │           │
   │    setMarketResolvable(true)  Trade     Wait for   settleMarket() redeem
   │    MUST call within 15 min!   live      endTime    (oracle only)
   │
   └── Market starts frozen. If not activated within 15 minutes,
       it is PERMANENTLY FROZEN and cannot be recovered.
```

### State Transition Rules

| From | To | Method | Condition |
|------|-----|--------|-----------|
| CREATED | ACTIVE | `setMarketResolvable(market, true)` | Custom oracle only; must be within 15 min of creation |
| ACTIVE | ENDED | *(automatic)* | Unix timestamp reaches `endTime` |
| ENDED | RESOLVED | `settleMarket({market, yesWinner})` | Oracle-only; can only be called after `endTime` |
| RESOLVED | CLAIMED | `redeemPosition(marke