Chesster - Decentralized Chess on Stellar

A fully decentralized, two-player chess game built on the Stellar network using Soroban smart contracts. Chesster features full move validation, database persistence for game state, and an on-chain escrow system for wagering tokens on matches.

🏗 Architecture

For high-level subsystem architecture, wager match lifecycle, disconnect & forfeit recovery protocols, and trust boundaries, see the Architecture Guide. For contract storage layout, the full error code catalog, token decimal handling, and local Soroban sandbox setup, see the Soroban Integration Guide.

Chesster/
├── backend/          # Node.js + Express API
│   ├── config/       # Supabase & Stellar config
│   ├── controllers/  # Request handlers
│   ├── models/       # Database operations
│   ├── routes/       # API endpoints
│   ├── services/     # Chess engine & Escrow logic
│   └── database/     # SQL schemas
├── frontend/         # React + TypeScript
│   └── src/
│       ├── components/  # ChessBoard, GameLobby, WalletConnect
│       ├── services/    # Stellar & API services
│       └── store/       # Zustand state management
└── contracts/        # Rust / Soroban Smart Contracts
    └── soroban/
        └── contracts/
            └── escrow/  # Escrow contract for wagering

✨ Features

• Web3 Integration: Connect with Freighter wallet to play and wager on games.
• On-Chain Escrow: Secure, trustless wagering using a Soroban smart contract.
• Full Chess Engine: Complete move validation (pawns, rooks, knights, bishops, queens, kings, castling, en passant).
• Real-time Gameplay: Turn-based gameplay with real-time board updates.
• Database Persistence: Game state and move history stored securely in Supabase.
• CI/CD Pipelines: Automated testing and linting via GitHub Actions.

🚀 Prerequisites

Before you begin, ensure you have the following installed:

• Node.js (v20+)
• Rust (for Soroban contracts)
• Soroban CLI
• Freighter Wallet browser extension
• A Supabase account

🛠 Setup Instructions

1. Smart Contract Deployment

cd contracts/soroban
rustup target add wasm32-unknown-unknown
cargo build --target wasm32-unknown-unknown --release
soroban contract deploy \
  --wasm target/wasm32-unknown-unknown/release/escrow.wasm \
  --source <YOUR_SECRET_KEY> \
  --network testnet

Save the deployed contract ID for the environment variables.

2. Supabase Setup

1. Create a new project on Supabase.
2. Run the SQL schemas located in backend/database/schema.sql and backend/database/migrations/add_escrow_columns.sql.
3. Copy your Project URL and Anon Key.

3. Backend Setup

cd backend
cp .env.example .env
# Edit .env with your Supabase credentials and Soroban Contract ID
npm install
npm run dev

Backend runs on http://localhost:3000

4. Frontend Setup

cd frontend
cp .env.example .env
# Edit .env with your Backend URL and Soroban Contract ID
npm install
npm run dev

Frontend runs on http://localhost:5173

🎮 How to Play

1. Connect Wallet: Click "Connect Wallet" to link your Freighter extension.
2. Player 1 (Create): Click "Create New Game", set a wager amount, and share the generated game code.
3. Player 2 (Join): Enter the game code, approve the wager transaction in Freighter, and join as Black.
4. Play: Click a piece to select it, then click the destination square. All moves are validated by the backend engine.
5. Resolution: Upon checkmate or draw, the backend automatically calls the smart contract to distribute the wagered tokens to the winner (or refunds both players in a draw).

🔗 API Endpoints

• POST /api/games - Create a new game
• POST /api/games/:code/join - Join an existing game
• GET /api/games/:code - Get current game state
• POST /api/games/:code/move - Make a move
• GET /api/games/:code/moves - Get move history

📜 Smart Contract (Escrow)

The Soroban smart contract (ChessterEscrow) handles the financial logic of the game:

• init: Initializes the contract with a coordinator address and fee percentage.
• create_match: Player 1 locks their wager in the contract.
• join_match: Player 2 locks their matching wager.
• resolve_match: The coordinator (backend) resolves the match, paying the winner (minus a small fee) or refunding both players.
• refund_after_timeout: Allows players to reclaim funds if a match is abandoned.
• emergency_refund: Lets either player split the locked wager evenly if an active match sees no coordinator resolution for 72 hours.

🧪 Testing

The project includes comprehensive test suites:

• Smart Contract: cd contracts/soroban && cargo test
• Backend: cd backend && npm test

💖 Support & Funding

If you find Chesster valuable, consider supporting development:

🤝 Contributing

Contributions are welcome! All active development pull requests should target the dev branch. See CONTRIBUTING.md for full branch workflow and DEVELOPMENT.md for running local CI checks.

📄 License

This project is licensed under the MIT License.