Pokedex TCG Whitepaper

2.1 Card Sets

Cards are organized into sets (e.g., Base Set, Jungle Set). Each set contains cards of varying rarities: Common, Uncommon, Rare, and Holo Rare. Sets can be enabled or disabled, and players can select which sets they want cards from when purchasing packs.

2.2 Pack Opening

Players acquire booster packs that contain multiple cards. When opening a pack, cards are revealed one by one, sorted by rarity. Each pack displays the correct wrapper based on the set it contains. Cards are revealed with animations and stored in the player's collection.

2.3 Card Management

• Favoriting: Players can favorite cards to prioritize them when selecting teams for battle
• Card Viewing: Click any card to view it in fullscreen with detailed information including abilities, stats, and rarity
• Collection Tracking: View your collection progress for each set, including unique cards collected out of the total set size
• Card Owners: For uncollected cards, view other players who own that card (requires 2,000,000 tokens)

2.4 Card Burning

Players can burn cards they don't want in exchange for energy. This provides a way to convert unwanted cards into battle resources. The burn process is irreversible and transfers the card to a burn address.

3.1 Escrow-Based Trading

All trades use an escrow-based system for security and reliability. When creating a trade:

1. The trade creator deposits their cards into an escrow wallet
2. The trade recipient accepts and deposits their cards into escrow
3. Once both parties have deposited, the trade completes automatically
4. Cards are distributed to their new owners atomically

This system ensures that trades never expire and supports multi-card swaps without transaction expiration issues.

3.2 Trade Features

• Multi-Card Trades: Trade multiple cards simultaneously
• Trade Messages: Add optional messages to trade offers
• Trade Offers: Create offers to specific wallet addresses
• Trade Inbox: View and manage received and sent trade offers
• Trade Cancellation: Either party can cancel a trade before completion, returning cards to original owners

3.3 Token Requirements

To use the trading system and view card owners, players must hold at least 2,000,000 tokens. This requirement helps ensure active participation and prevents spam. The token balance is checked when creating trades or viewing card ownership information.

3.4 Card Transfers

Players can send individual cards to other wallets as gifts. The transfer process uses on-chain cNFT transfers, ensuring true ownership transfer. Cards can be sent to any Solana wallet address.

4.1 Battle Modes

• Turn-Based Mode: Strategic battles where Pokemon take turns attacking. Abilities trigger at specific turn phases, and status conditions affect gameplay.
• Positional Mode: Real-time battles with Pokemon positioned in formations. Pokemon can roam, attack with projectiles or melee attacks, and use positional abilities.

4.2 Unique Pokemon Abilities

Each Pokemon has unique abilities based on their card text and characteristics. Abilities can be:

• Attack Abilities: Deal damage or apply effects to enemies
• Defense Abilities: Protect allies or reduce incoming damage
• Utility Abilities: Provide buffs, healing, or status effects
• Terrain Abilities: Affect the battlefield environment
• Passive Abilities: Continuous effects that trigger automatically

Abilities have visual particle effects and animations when triggered, providing clear feedback during battles.

4.3 Status Conditions

The battle system includes comprehensive status conditions:

4.4 Battle Mechanics

• Damage Calculation: Based on attack, defense, type effectiveness, and critical hits
• Evasion: Pokemon can dodge attacks based on their evade stat
• Critical Hits: Random chance for increased damage based on critical stat
• Attack Types: Melee attacks (close combat) and ranged attacks (projectiles)
• Fainting: Pokemon at 0 HP become grayscale with a skull overlay but remain visible

4.5 Tier-Based Matchmaking

Players are assigned tiers (S, A, B, C, D) based on their battle performance. The tier calculation considers:

• Win rate and total battles
• Best Pokemon performance
• Recent activity
• Highest level Pokemon
• Overall battle statistics

Players can battle others in their tier, ensuring balanced matchmaking. The tier is displayed next to the wallet address and battle button.

7.1 Blockchain Technology

• Solana Blockchain: All cards are minted as compressed NFTs (cNFTs) on Solana
• Metaplex Bubblegum: Used for cNFT creation and management
• True Ownership: Cards are stored on-chain, ensuring players truly own their digital assets
• Interoperability: Cards can be transferred to any Solana wallet

7.2 Security Features

• Wallet Verification: All actions that modify user state require cryptographic wallet signature verification
• Escrow System: Trades use an escrow wallet to securely hold cards during the trade process
• Input Validation: All user inputs are validated server-side using Zod schemas
• Key Vault: Admin keys are encrypted and stored securely, requiring decryption for sensitive operations

7.3 Battle Engine

The battle system uses a deterministic engine that can run both client-side (for testing) and server-side (for real battles). Battles are simulated using seeded random number generation, ensuring reproducible results. Battle transcripts are generated server-side and replayed client-side with smooth animations.

7.4 Data Storage

• PostgreSQL Database: Stores card metadata, user collections, trade records, and battle statistics
• Vercel Blob Storage: Stores card images and other media files
• On-Chain Storage: Card ownership and transfers are recorded on the Solana blockchain