📚 Monad Adventures Docs

Product + technical reference for gameplay, tokens, persistence, APIs, and security controls.

⚔️ 1) Core Gameplay

  • 🗺️ 3 dungeons: Training Field, Mad Wizard, Grand Colosseum.
  • 🏁 Runs are up to 10 levels with decreasing win odds as level increases.
  • 🧙 Character progression is unlimited and increases from boss kills.
  • 🧩 Item progression is level-based; equipped items gain EXP from boss kills.
  • 💨 Cash out lets players escape early and claim accumulated SPIKES.

💰 2) Currencies & Economy

  • 🪙 Primary in-game currency is SPIKES.
  • 🎟️ Mad Wizard + Grand Colosseum require SPIKES entry fees.
  • ⚡ Training Field is free entry, but consumes daily energy.
  • 🎁 Spike Loot Box gives 500 SPIKES for 2 USDC (fixed reward).
  • 🛒 Items can be sold for a flat 5 SPIKES each.
  • 🧯 Jackpot mechanics are disabled for now.

🐮 3) MON Boss Loot

  • 🎲 MON loot appearance chance is 10% per boss level.
  • 🏆 If MON appears and you defeat the boss, a win roll determines reward.
  • 💸 Reward is 5 MON and shown in the victory overlay with the MON icon.
  • 🧾 Claim IDs prevent duplicate payouts for the same boss clear.
  • 🔧 MON payout mode can be independent from SPIKES settlement mode.

🔋 4) Daily Energy

  • 📈 Daily cap is 100 energy; Training Field costs 10 per entry.
  • 🕛 Energy resets by day key and is enforced server-side (UTC day).
  • 🗝️ Mad Wizard + Grand Colosseum do not consume energy.
  • 📊 UI shows a full-width energy bar on the Training Field card.

🎒 5) Item Loot & Inventory

  • 🧪 Two-step loot: appearance roll, then win roll on boss victory.
  • 🍀 Current settings: 25% appear, 80% win if you beat the boss.
  • 🧷 Drops go to wallet inventory and can be equipped by slot.
  • ♻️ Selling an equipped item auto-unequips and recalculates boosts.
  • 🗄️ Inventory is identity-scoped and persisted in Postgres.

📈 6) Reward Scaling

  • 📊 SPIKES level rewards scale up as win odds decrease.
  • 🧮 Uses base dungeon reward + level win chance to scale payout.
  • 🎯 Higher risk levels pay more to match difficulty.

🧱 7) Persistence (Postgres)

  • 🗃️ State is persisted in PostgreSQL with normalized tables.
  • 🧾 Tables: players, sessions, wallet_items, used_payment_tx_hashes, jackpots, chat_messages.
  • ⚙️ Server keeps in-memory state and flushes to Postgres.
  • 🧳 Legacy migration supports old JSON / older DB formats.

🔐 8) Auth & Identity

  • 🧾 Onchain mode uses signed wallet challenge auth.
  • 🪪 Mock mode uses identity keys (wallet or guest) passed to APIs.
  • 🧷 Ownership checks protect player/session state mutations.

🚀 9) Deployment

  • 🌐 Frontend: Vercel (Next.js).
  • 🛤️ Backend: Railway (Node + Postgres plugin).
  • 🪙 SPIKES settlement: mock or onchain via escrow.
  • 🐮 MON payout: independent via MON_REWARD_MODE (mock/onchain).

🛡️ 10) Security Controls

  • 🚦 Global rate limiting with bounded bucket map.
  • 🧊 No-store API headers + basic hardening headers.
  • 🔁 Replay protection for token payment tx hashes.
  • 🧾 Duplicate-claim prevention for MON payouts.
  • 💬 Chat is capped to latest 20 messages (client load control).
  • 🧍 Chat + player creation require identity in mock mode.

🧰 11) API Overview

  • 👤 Players: create, resume, state, inventory, sell item.
  • 🏆 Ranking: global character leaderboard (level + EXP ordering).
  • 🗺️ Dungeons: list, enter.
  • 🧨 Sessions: equip, attack, cashout, claim.
  • 🎁 Tokens: buy (mock), open loot box.
  • 💬 Chat: list latest, post message.

✨ Tip: Docs are meant to be player-friendly; dev details live in the backend README.