Chess Bot for Towns Protocol

A chess bot that enables users to play chess matches with wagers, allows spectators to place bets, and automatically distributes winnings.

Features

• 🎮 Play Chess: Start chess games with wagered ETH
• 💰 Wager System: Players tip to join games and wager ETH
• 👀 Spectator Betting: Spectators can bet on game outcomes
• 🖼️ Visual Boards: Automatically generates chess board images
• ⚡ Real-time Updates: Game state updates after each move
• 🏆 Auto Payouts: Automatic distribution of winnings (TODO: implement payment distribution)

What This Bot Does

This bot allows users in Towns Protocol channels to:

1. Start Games: Use /startchess [amount] to create a new game with a wager
2. Join Games: Tip the game message to accept the challenge and match the wager
3. Make Moves: Use /move [move] to play chess (e.g., /move e2e4)
4. Resign: Use /resign to forfeit your game
5. Spectate & Bet: Spectators can tip to bet on players

Setup

Prerequisites

• Node.js 18+ or Bun runtime
• Towns Developer Portal access at https://app.towns.com/developer
• Bot credentials (APP_PRIVATE_DATA and JWT_SECRET)

Installation

1. Install dependencies:

bun install
# or
npm install

2. Copy .env.sample to .env and fill in your credentials:

cp .env.sample .env

3. Add environment variables:

APP_PRIVATE_DATA=your_bot_private_data_here
JWT_SECRET=your_jwt_secret_here
MIN_WAGER=0.01  # Optional: minimum wager amount in ETH

4. Run the bot:

bun run dev     # Development with hot reload
# or
bun run start   # Production

Commands

/startchess [amount]

Start a new chess game with a wager amount.

Example:

/startchess 0.01

This creates a game with a 0.01 ETH wager. The game creator must tip the game message to pay their wager, then another player can tip to accept the challenge.

/move [move]

Make a chess move using standard algebraic notation.

Examples:

/move e2e4      # Pawn from e2 to e4
/move Nf3       # Knight to f3
/move O-O       # Kingside castling
/move O-O-O     # Queenside castling

/resign

Resign from your current game. The opponent automatically wins.

/help

Show all available commands and how to play.

How to Play

1. Start a Game: Use /startchess 0.01 to create a game with a 0.01 ETH wager
2. Pay Your Wager: Tip the game message with the wager amount
3. Wait for Opponent: Another player tips the message to accept
4. Play Chess: Make moves with /move [notation]
5. Win or Lose: Game ends when checkmate, stalemate, or resignation occurs

Spectator Betting

Spectators can tip the game message to bet on either player:

• Tips are automatically assigned to players (alternating)
• Winners receive proportional payouts (TODO: implement payout distribution)

Game Flow

1. Game Creation: Player uses /startchess command
2. Wager Payment: Player 1 tips the game message to pay wager
3. Challenge Acceptance: Player 2 tips to match wager and join
4. Gameplay: Players alternate moves with /move command
5. Game End: Checkmate, draw, or resignation
6. Payouts: Winnings distributed automatically (TODO: implement)

Architecture

Core Components

• GameManager (src/chess/GameManager.ts): Manages game state and moves
• BoardRenderer (src/chess/BoardRenderer.ts): Generates chess board images
• Types (src/chess/types.ts): TypeScript type definitions
• Main Handler (src/index.ts): Bot event handlers and webhook logic

Dependencies

• chess.js: Chess logic and move validation
• canvas: Chess board image generation
• @towns-protocol/bot: Towns Protocol bot framework
• viem: Ethereum utilities for handling ETH amounts

Deployment

Render.com

1. Push code to GitHub
2. Create new Web Service on Render
3. Connect GitHub repository
4. Set environment variables:
   • APP_PRIVATE_DATA
   • JWT_SECRET
   • MIN_WAGER (optional)
5. Set build command: bun install
6. Set start command: bun run start
7. Deploy!

Webhook Configuration

After deployment, configure your webhook URL in the Towns Developer Portal:

1. Go to https://app.towns.com/developer
2. Find your bot and click "Edit"
3. Set webhook URL: https://your-bot.onrender.com/webhook
4. Select message forwarding: ALL_MESSAGES or MENTIONS_REPLIES_REACTIONS
5. Save changes

Development

Project Structure

chess-bot/
├── src/
│   ├── index.ts          # Main bot handler
│   ├── commands.ts       # Slash command definitions
│   └── chess/
│       ├── types.ts      # TypeScript types
│       ├── GameManager.ts # Game state management
│       └── BoardRenderer.ts # Board image generation
├── .env                  # Environment variables
├── package.json         # Dependencies
└── README.md           # This file

Adding Features

To extend the bot:

1. Payment Distribution: Implement payout logic in src/index.ts (marked as TODO)
2. Database: Add persistent storage for games (SQLite, PostgreSQL, etc.)
3. Ratings: Implement ELO rating system
4. Time Controls: Add timer for blitz/rapid games
5. Tournaments: Multi-player tournament brackets

Troubleshooting

Bot Not Responding

1. Check Render logs for errors
2. Verify APP_PRIVATE_DATA and JWT_SECRET are correct
3. Ensure webhook URL ends with /webhook
4. Check bot permissions in Developer Portal
5. Verify message forwarding is set correctly

Games Not Starting

1. Ensure player tips the exact wager amount (within 1% tolerance)
2. Check that game status is correct (waiting_for_wager → waiting_for_opponent)
3. Verify bot has permission to receive tips

Invalid Moves

• Use standard chess notation (e.g., e2e4, Nf3, O-O)
• Moves must be legal according to chess rules
• Check that it's your turn before making a move

Resources

• Towns Academy: https://www.towns.com/academy/vibebot
• Developer Hub: https://www.towns.com/developer-hub
• Towns Documentation: https://docs.towns.com
• Chess.js: https://github.com/jhlywa/chess.js
• Base Network: https://base.org

License

MIT License - Feel free to use and modify for your own Towns bots!

---

Built following Towns Protocol bot development framework and official guidelines.