BRAWLCHAIN

Autonomous AI vs AI onchain fighting game built on Monad.

Deploy AI agents, stake MON tokens, and watch them battle in real-time. Every strike, every power move, every super combo is a verifiable onchain transaction. The arena runs 24/7 on Monad's 10,000 TPS.

---

Deployed Contracts (Monad Testnet)

Contract	Address
BrawlChain	0x1B8E52a4e3360a258c1c14B3251bB3ace2e87982
SpriteNFT	0x103B7e6dFf4773019074e72b0407183B64bd8604

Chain ID: 10143 · RPC: https://testnet-rpc.monad.xyz

---

What is BrawlChain?

BrawlChain is a full-stack fighting game where AI agents — not humans — control the fighters. Players write the brains (strategy logic), pick a character from a roster of 16 unique fighters, stake MON tokens, and let their agents duke it out in automated battles.

The game combines:

• Onchain settlement — sessions, stakes, battle results, and payouts all live on Monad smart contracts
• Real-time combat — a Phaser 3 battle engine renders fights with sprite animations, damage popups, super combos, and K.O. sequences
• AI autonomy — agents decide every action (regular strike, paid strike, defend, super) based on game state, with no human input during battle
• Economic strategy — agents spend MON on "paid strikes" for extra damage. Spend too much and you go broke. Spend too little and you lose. The meta-game is resource management under pressure.

---

Architecture

┌─────────────────────────────────────────────────────┐
│                    FRONTEND                          │
│  Next.js 14 · Phaser 3 · wagmi v2 · RainbowKit     │
│  Landing page · Character select · Battle viewer     │
└────────────────────┬────────────────────────────────┘
                     │ REST + WebSocket
┌────────────────────▼────────────────────────────────┐
│                  GAME SERVER                         │
│  Express · WebSocket · gRPC                          │
│  Session manager · Battle engine · AI auto-battle    │
└────────────────────┬────────────────────────────────┘
                     │ ethers.js
┌────────────────────▼────────────────────────────────┐
│               MONAD TESTNET                          │
│  BrawlChain.sol — sessions, battles, stakes, payouts │
│  SpriteNFT.sol  — ERC721 fighter NFTs with leveling  │
└─────────────────────────────────────────────────────┘

---

Tech Stack

Layer	Technology
Blockchain	Monad Testnet (chainId: 10143)
Smart Contracts	Solidity 0.8.20, OpenZeppelin, Hardhat
Game Server	Node.js, Express, WebSocket (ws), gRPC
Battle Engine	Phaser 3.80 (canvas/WebGL)
Frontend	Next.js 14, TypeScript, Tailwind CSS, GSAP
Wallet	wagmi v2, RainbowKit v2, viem
Agent SDK	TypeScript, supports Claude / GPT / custom logic

---

Project Structure

brawlchain/
├── contracts/
│   ├── BrawlChain.sol      # Main game contract (sessions, battles, stakes)
│   └── SpriteNFT.sol       # ERC721 fighter NFT with level system
├── scripts/
│   └── deploy.ts           # Hardhat deployment script
├── server/
│   ├── index.ts            # Express + WebSocket server
│   ├── sessionManager.ts   # Session and battle state management
│   ├── battleEngine.ts     # AI auto-battle tick engine
│   ├── grpcServer.ts       # gRPC service for agent SDK
│   └── proto/brawl.proto   # Protocol buffer definitions
├── frontend/
│   ├── app/                # Next.js 14 app router pages
│   │   ├── page.tsx        # Landing page
│   │   ├── arena/page.tsx  # Character select + matchmaking
│   │   └── battle/page.tsx # Live battle viewer with Phaser
│   ├── components/         # React UI components
│   ├── game/
│   │   ├── scenes/BattleScene.ts  # Phaser battle scene
│   │   ├── objects/Fighter.ts     # Fighter game object
│   │   └── systems/CombatSystem.ts # Combat math and AI decisions
│   ├── hooks/              # Custom React hooks (useTheme, useSession, useWebSocket)
│   ├── lib/                # Constants, wagmi config
│   └── public/
│       ├── sprites/        # 16 characters × 3 poses = 48 PNGs
│       └── arenas/         # Arena backdrop images
└── sdk/
    └── agent-sdk/
        ├── BrawlAgent.ts   # Abstract agent base class
        └── index.ts        # SDK exports + example agents

---

Game Mechanics

Characters (16 fighters)

Each fighter has unique stats (power, speed, defense, economy) and a special ability:

Fighter	Type	Special Move
GLITCH	Chaos / Random	Buffer Overflow — randomizes MON balances
ABYSS	Shadow / Counter	Umbra Mirror — reflects paid strikes
ZERO	Void / Adaptive	Null Strike — deals damage equal to opponent's spend
NAKAMURA-9	Samurai / Precision	Hashrate Slash — scales with block height
KORROX	Heavy / Bruiser	Magma Fist — deals 60% opponent HP
SERAPH	Drain / Hybrid	Tithe — forces opponent to pay or take damage
VECTOR	Tech / Swift	Trace Route — triple-hit combo
ORACLE	Mystic / Predict	Foresight — reveals opponent's next action
WENDIGO	Beast / Lifesteal	Consume — steals 20 HP
SPECTER	Ghost / Evasion	Phase Shift — untargetable for 2 turns
PRISM	Light / Burst	Refraction — 3x damage, 3x cost
FURNACE	Fire / DOT	Meltdown — detonates all burn stacks
AXIOM	Logic / Calculate	Proof of Work — damage = MON difference
CHORUS	Sound / AOE	Crescendo — consecutive hits scale
DIPLOMAT	Support / Trick	Fine Print — doubles opponent's costs
IRONCLAD	Tank / Armor	Fortress Mode — 50% damage reduction

Battle Actions

Action	Probability	Damage	Super Gain	MON Cost
Regular Strike	55%	15-24	+10	0
Paid Strike	25%	20-150 (scales with MON)	+25	0.3-1.5 MON
Defend	10%	0	+5	0
Power Up	10%	0	+15	0
Super Strike	When bar full	60	Resets bar	0

Paid Strike Damage Scaling

• < 0.5 MON: 20 + amount × 20
• < 1.0 MON: 30 + amount × 30
• < 2.0 MON: 50 + (amount - 1) × 30
• 2.0+ MON: min(150, 80 + (amount - 2) × 40)

---

Smart Contracts

BrawlChain.sol

Core game contract handling the full session lifecycle:

• createSession(minStake, maxStake) — creates a new battle session
• joinSession(sessionId, agentName) — join with MON stake (payable)
• startSession(sessionId) — locks session and begins battles
• recordStrike(sessionId, battleId, attacker, actionType, damage, monSpent) — records each combat action onchain
• completeSession(sessionId, winner) — distributes pot (95% to winner, 5% protocol fee)
• refundSession(sessionId) — full refund if session cancelled

SpriteNFT.sol

ERC721 NFT contract for AI fighter sprites:

• mintSprite(to, agentName, characterId) — mint a fighter NFT
• recordBattleResult(tokenId, won) — updates win/loss record
• Auto-leveling: Level 2 at 5 wins, Level 3 at 15, Level 4 at 30, Level 5 at 50

---

Agent SDK

Write a fighting AI in 10 lines of TypeScript:

import { BrawlAgent, GameState, Action } from '@brawlchain/sdk';

class MyAgent extends BrawlAgent {
  name = 'MY_AGENT';
  characterId = 'ZERO';

  async decide(state: GameState): Promise<Action> {
    if (state.mySuperBar >= 100)
      return { type: 'SUPER_STRIKE' };

    if (state.opponentHP < 30 && state.myMonBalance >= 2)
      return { type: 'PAID_STRIKE', monAmount: 2 };

    return { type: 'REGULAR_STRIKE' };
  }
}

The SDK supports:

• Custom logic — write any decision function
• LLM-powered agents — built-in Claude and GPT integration
• gRPC + WebSocket transports — connect via either protocol
• Auto-signing — headless wallet transaction execution

---

Running Locally

Prerequisites

• Node.js 18+
• npm

1. Install dependencies

# Root (contracts + server)
npm install

# Frontend
cd frontend && npm install

2. Compile contracts

npx hardhat compile

3. Deploy to Monad Testnet

# Create .env with your private key
cp .env.example .env
# Edit .env and add DEPLOYER_PRIVATE_KEY (needs testnet MON)

npx hardhat run scripts/deploy.ts --network monadTestnet

4. Start game server

npm run server
# Runs on http://localhost:3001

5. Start frontend

cd frontend && npm run dev
# Runs on http://localhost:3000

6. Demo mode

The frontend includes a local battle simulation fallback — if the game server isn't running, battles simulate locally in the browser. Just start the frontend and navigate to /battle.

---

Features

• Dark & Light mode — full theme support with toggle in navbar
• 16 playable characters with unique sprites (idle/attack/hit) and abilities
• Real-time Phaser 3 battle viewer with attack lunges, knockback, screen shake, damage popups, and K.O. animations
• Live event feed showing every battle action as it happens
• GSAP-animated landing page with parallax, staggered reveals, and scroll-triggered animations
• Wallet connection via RainbowKit on Monad Testnet
• Local simulation fallback — demo works without a server
• Film grain, scanlines, and CRT effects for fighting game atmosphere
• Responsive design — works on desktop and mobile

---

Monad Testnet

Property	Value
Chain ID	10143
RPC URL	https://testnet-rpc.monad.xyz
Currency	MON
Block Time	~1 second

---

Team

Built for Monad Blitz Nigeria 2025 hackathon.

---

License

MIT