feat: Prophecy NFT Gallery (Innovation Cycle #49 — The Living Cosmos)

[Eli5DeFi]

Summary

Implements the complete Prophecy NFT system from Innovation Cycle #49. This is the top-priority Week 1-6 feature that transforms Voidborne from a prediction market into a collectible narrative cosmos.

"The best stories begin with a prophecy."

Before each chapter resolves, the AI generates 10-20 cryptic prophecies. Readers mint them as NFTs for 5 $FORGE. After chapter resolution, each prophecy transforms:

• ★ Fulfilled (direct match) → Legendary golden artifact, 10× value
• ◈ Echoed (thematic match) → Silver artifact, 3× value
• ▪ Void Relic (unfulfilled) → Dark collectible, still cool

---

Changes

🗄️ Database (Prisma Schema + Migration)

• New Prophecy model — sealed prophecy per chapter (max 100 mints each)
• New ProphecyMint model — one per user per prophecy, mint order 1-100
• New ProphecyStatus enum — PENDING | FULFILLED | ECHOED | UNFULFILLED
• SQL migration: packages/database/prisma/migrations/20260218_prophecy_nft/
• ProphecyMint[] relation added to User model
• Prophecy[] relation added to Chapter model

🔌 API Routes (4 new endpoints)

Endpoint	Description
GET /api/prophecies	List all prophecies (filterable by status, paginated)
POST /api/prophecies	Seed new prophecies for a chapter (oracle/admin)
GET /api/prophecies/[chapterId]	Chapter gallery + fulfillment summary
PATCH /api/prophecies/[chapterId]	Batch fulfill post-resolution (oracle)
POST /api/prophecies/mint	Mint single NFT or Oracle Pack (10% discount)
GET /api/prophecies/mint	User's full mint history by wallet
GET /api/prophecies/leaderboard	Oracle leaderboard (ranked by fulfilled count)

🎨 Components (6 new, all in components/prophecy/)

Component	Purpose
ProphecyCard	NFT card with dark/silver/golden art based on status + hover animations
ProphecyGallery	Filterable/sortable chapter gallery with oracle pack hint
ProphecyMintModal	Full mint flow: preview → confirm → mint → success animation
ProphecyRarityBadge	Rarity tier badge (COMMON → MYTHIC)
ProphecyBanner	Compact story sidebar teaser with mint progress bar
OracleLeaderboard	Top collectors with rank titles (Novice → Void Eye)

📄 Pages (2 new)

Page	Description
/prophecies	Global gallery — all chapters, leaderboard sidebar, empty+live states
/prophecies/[chapterId]	Chapter gallery — "My Mints" section, resolution banner, full gallery

🔗 Integrations (2 modified files)

• Navbar — Added "Prophecies ✦" navigation link
• Story page — ProphecyBanner injected in sidebar above betting interface

📚 Documentation

• docs/PROPHECY_NFT_SYSTEM.md — Full API reference, migration guide, seeding examples, revenue model

---

Rarity System

Status + Mint Order	Rarity	Multiplier
Fulfilled, mint #1-5	MYTHIC	20×
Fulfilled, mint #6-100	LEGENDARY	10×
Echoed, mint #1-10	RARE	4×
Echoed, mint #11-100	UNCOMMON	3×
Unfulfilled, any	COMMON	1×

---

Revenue Impact (Year 1 → Year 5)

$61K → $1.82M annual revenue from:

• Primary mints (5 $FORGE × volume)
• Oracle Pack premium volume (10% discount drives 3-5× more mints per user)
• 5% royalty on secondary sales

---

Testing Checklist

• TypeScript compiles with 0 errors (npx tsc --noEmit clean)
• All API routes return proper HTTP status codes + error messages
• ProphecyCard renders correctly in all 4 states (PENDING/FULFILLED/ECHOED/UNFULFILLED)
• ProphecyMintModal flow: preview → confirm → mint → success/error
• Oracle Pack discount correctly applied (10%, 4.5 $FORGE each)
• Sold-out / already-minted guards in mint API
• ProphecyBanner silently hides when chapter has no prophecies
• OracleLeaderboard empty state when no mints exist
• Mobile responsive (grid cols collapse correctly)
• Prisma client regenerated after schema changes

---

Deployment Notes

Required: Run DB Migration

cd packages/database
npx prisma migrate deploy
# or on dev:
npx prisma migrate dev --name prophecy_nft

Seed Initial Prophecies

Use the oracle POST endpoint or the AI generator in packages/prophecy-nft/src/generator.ts:

curl -X POST https://voidborne.app/api/prophecies \
  -H 'Content-Type: application/json' \
  -d '{"chapterId": "<id>", "prophecies": [...]}'

Smart Contract (Future)

The ERC-721 contract at packages/prophecy-nft/src/ProphecyNFT.sol is POC-ready.
When deploying:

1. Deploy to Base Sepolia → update PROPHECY_NFT_ADDRESS env var
2. Connect ProphecyNFTClient in mint API for on-chain verification
3. Set oracle wallet key in ORACLE_PRIVATE_KEY env var

---

Screenshots

The gallery follows the "Ruins of the Future" design system:

• Dark void background (#05060b)
• Gold/amber accents for fulfilled artifacts
• Silver/slate for echoed artifacts
• Monospace font (JetBrains Mono) for all technical labels
• Cinzel serif for prophecy text and headings
• Animated hover states + particle symbols on fulfilled cards

---

Related

• Innovation Cycle feat: Narrative Guilds & Faction Wars UI — Innovation Cycle #52 #49 spec: INNOVATION_CYCLE_49_FEB_18_2026.md
• POC Smart Contract: packages/prophecy-nft/src/ProphecyNFT.sol
• POC SDK: packages/prophecy-nft/src/client.ts
• Full docs: docs/PROPHECY_NFT_SYSTEM.md