A monster card battler on Solana with a deterministic, server-authoritative battle engine. Claim a roster, fight 3v3 team battles, evolve your team, climb the leaderboard. The game ships first. The economy rides on top.
Play · Telegram · X / Twitter
PokeEvolve is a Solana-native monster card battler that closes three failure modes of Web3 gaming: opaque RNG, spreadsheet-with-token-glued-on game design, and trivially cheated outcomes. Every battle resolves through a deterministic, seeded engine the server controls. Same seed produces the same fight, every time, on every machine.
| Pillar | Implementation |
|---|---|
| Provably fair fights | Pure-function engine resolve(teamA, teamB, seed) over a seeded PRNG (xmur3 → mulberry32) |
| Server-authoritative | Roster, levels, BP, and seed live in the DB. HMAC-signed single-use match tokens. Client cannot fake a win. |
| Wallet-native identity | SIWS (Sign-In With Solana). Ed25519 signature with a ±60s replay window. No email, no password. |
| Off-chain ownership (MVP) | DB-keyed roster tied to the wallet address. NFT minting deliberately deferred to reduce IP surface area. |
| Fair launch | $POKEVO ships 100% on the PumpFun bonding curve. 0% team allocation. 0% pre-mine. |
| Mechanic | Value |
|---|---|
| Roster size | 3 starter monsters per wallet |
| Catalog | 47 monsters across 20 evolution lines |
| Rarity tiers | Common · Uncommon · Rare · Epic · Legendary |
| Type chart | 18 elemental types, full effectiveness matrix |
| Damage multipliers | Super-effective ×1.5 · Resisted ×0.75 · Neutral ×1.0 |
| Battle format | 3v3 team, first to 3 KOs wins |
| Battle modes | Random PvP · Friend (by code) · NPC bot |
| BP awards | Win +25 BP · Loss +5 BP |
| Progression | Spend BP to Level Up (+1 to each stat) or Evolve at the required level |
| Rate limit | 4s cooldown between battles |
| Tier | Holdings | Perks |
|---|---|---|
| Rookie | 0% | Full game, standard BP, public + NPC, leaderboard |
| Trainer | 0.1% | +10% BP earn rate, ranked-season access |
| Ace | 0.5% | +25% BP earn rate, gated tournaments, exclusive frames |
| Champion | 1%+ | +50% BP earn rate, governance vote, early monster access |
The game is free and fair for everyone. The token buys edge, access, and cosmetics. It does not buy power. Battle outcomes cannot be paid into.
┌──────────────────────────────────────────────────────────────┐
│ THE CORE LOOP │
│ │
│ 1. Connect Solana wallet ─► SIWS handshake │
│ │ │
│ ▼ │
│ 2. Claim 3 starter monsters ─► roster keyed to wallet │
│ │ │
│ ▼ │
│ 3. Pick a mode ─► Random PvP / Friend code / NPC bot │
│ │ │
│ ▼ │
│ 4. Engine resolves fight from seed │
│ type chart × damage formula × speed order │
│ │ │
│ ▼ │
│ 5. Win +25 BP · Loss +5 BP │
│ │ │
│ ▼ │
│ 6. Spend BP ─► Level Up (+1 each stat) or Evolve │
│ │ │
│ ▼ │
│ 7. Stronger roster ─► climb the leaderboard ─► loop │
│ │
└──────────────────────────────────────────────────────────────┘
┌──────────────────────────────────────────────────────────────┐
│ SYSTEM OVERVIEW │
│ │
│ ┌────────────┐ server actions ┌────────────────────┐ │
│ │ GAME │ ◄──────────────────► │ NEXT.JS SERVER │ │
│ │ CLIENT │ (RSC, mutations) │ (authoritative) │ │
│ │ Next 14 │ │ │ │
│ │ │ │ · owns roster, BP │ │
│ │ · roster │ │ · runs battle sim │ │
│ │ · arena │ │ · signs match tok │ │
│ │ · Pokédex │ │ · rate-limit (4s) │ │
│ │ · wallet │ │ · SIWS verify │ │
│ └─────┬──────┘ └─────────┬──────────┘ │
│ │ SIWS sign (Phantom/Solflare) │ Prisma │
│ ▼ ▼ │
│ ┌────────────┐ ┌────────────────────┐ │
│ │ SOLANA L1 │ │ POSTGRES (schema: │ │
│ │ │ │ pokeevolve) │ │
│ │ · ed25519 │ │ · User / Card │ │
│ │ · wallets │ │ · UserCard │ │
│ │ │ │ · Battle │ │
│ └────────────┘ └────────────────────┘ │
│ │
│ Battle sim is a pure deterministic function. Re-runnable. │
└──────────────────────────────────────────────────────────────┘
The full container view (C4) lives in SYSTEM_DESIGN.md.
| Layer | Technology |
|---|---|
| Monorepo | Turborepo + pnpm workspaces |
| Landing | Next.js 14 (apps/landing, port 3000) |
| Game client | Next.js 14 App Router (apps/game, port 3001) |
| Styling | Tailwind, neon-on-dark battle-arena theme |
| Database | Postgres with pokeevolve schema |
| ORM | Prisma |
| Auth | SIWS via tweetnacl ed25519, HMAC httpOnly session cookie |
| Engine | TypeScript, xmur3 → mulberry32, 18-type effectiveness chart |
| Audio | Procedural Web Audio (no asset files) |
| Storage | Object storage bucket cards for art |
| Launch | PumpFun bonding curve (scripts/pump_integrator.ts) |
pokeevolve-core/
├── README.md ← you are here
├── CHANGELOG.md
├── SYSTEM_DESIGN.md ← C4 containers, deployment view
├── scripts/
│ ├── tokenomics_calc.ts ← $POKEVO supply / tier math
│ └── pump_integrator.ts ← PumpFun bonding-curve helpers
├── .github/
│ └── workflows/
│ └── build.yml ← lint + typecheck + tokenomics dry-run
└── tags.md
# 1. Install
pnpm install
# 2. Configure environment
cp .env.example .env
# Set AUTH_SECRET, DATABASE_URL, SOLANA_RPC_URL
# 3. Run the tokenomics sanity check
pnpm tsx scripts/tokenomics_calc.ts
# 4. Run the PumpFun launch dry-run (does not broadcast)
pnpm tsx scripts/pump_integrator.ts --dry-run| Phase | Window | Deliverables |
|---|---|---|
| 1 — Launch-ready game | Shipped | 47 monsters, 20 evo lines, deterministic 3v3 engine, claim/level/evolve, async PvP, friend battles, NPC, SIWS auth, Pokédex, leaderboard |
| 2 — Economy & ranked | 1–2 months | $POKEVO fair launch on PumpFun, tier perks, ranked seasons, cosmetic frames, buy-back & burn |
| 3 — Depth | 3–5 months | More monsters/abilities, status effects, tournaments, guilds, on-chain seed commit, tradeable roster, spectate & replay |
| 4 — Ecosystem | 6–12 months | Open leaderboard/replay API, sponsored tournaments, mobile client, governance-driven balance |
| Resource | URL |
|---|---|
| Live game | https://pokeevolve.fun |
| X / Twitter | https://x.com/pokeevolvefun |
| Telegram channel | https://t.me/pokeevolve |
| Telegram bot | https://t.me/pokeevolve_bot |
| GitHub | https://github.com/pokeevolve |
| Documentation | pokeevolve-docs |
| API & SDK | pokeevolve-api |
PRs welcome on the engine, the type chart, the move pool, and the Pokédex UI. Run pnpm test and pnpm typecheck before opening one. Game-design contributions (balance changes, new monster proposals) should land in the docs repo as a draft first, then propagate here as code.
MIT.
PokeEvolve is an experimental Web3 game. $POKEVO is a community token with no intrinsic value and no promise of financial return. In-game monsters are collectibles, not securities or investments. Crypto and game assets are volatile and may lose all value. Play and participate only with what you can afford to lose. A public/token launch should use original monster designs to avoid third-party IP exposure. Nothing here is financial advice.