♟️ Chessxu - Multi-chain Crypto Chess

Complete React + Clarity integration documentation Play chess and wager STX securely on the Stacks blockchain ⚡

Welcome to Chessxu, a fully decentralized chess application built on the Stacks and Celo blockchains. Chessxu enables players to engage in PvP chess matches, completely tracked and resolved using smart contract state-machines, with crypto token wagers on the line.

▶️ Play on Farcaster: farcaster.xyz/miniapps/nRpKP2ahbJIm/chessxu

🏗️ Project Structure

The repository is organized into a monorepo containing both the frontend web application and the Clarity smart contracts.

chessxu/
├── src/               # @morelucks/chessxu-sdk TypeScript SDK
├── frontend/          # React + Vite web application
├── stacks-contracts/  # Clarinet project with Stacks smart contracts
└── celo-contracts/    # Hardhat project with Celo smart contracts (EVM)

The SDK's helper API (error decoding, game-status predicates, wager and address validation, CHESS amount formatting and explorer links) is documented in docs/SDK.md. Run its test suite with npm test.

🚀 Quick Start

1. Running the Frontend

The frontend is a modern React application powered by Vite, providing the chess logic, UI, and Stacks wallet integration.

git clone https://github.com/morelucks/chessxu.git
cd chessxu/frontend

# Install dependencies
npm install

# Start the development server
npm run dev

Your client will be running locally at http://localhost:5173 with optimistic updates and seamless blockchain connectivity.

2. Developing the Smart Contract

The core game logic and STX wagering system are managed by a Clarity smart contract (chessxu.clar). You need Clarinet installed to interact with it.

cd chessxu/stacks-contracts

# Check the syntax of the Clarity contracts
clarinet check

# Run the Clarinet console to interact locally
clarinet console

📦 @morelucks/chessxu-sdk

The Chessxu platform exports a lightweight TypeScript SDK for interacting with the Stacks smart contracts. This allows other developers to easily fetch game states, decode on-chain errors, and build custom bots or interfaces for Chessxu.

Installation

npm install @morelucks/chessxu-sdk

Usage Example

import { CONTRACTS, GAME_STATUS, ERRORS } from '@morelucks/chessxu-sdk';

console.log(`Connecting to game contract at: ${CONTRACTS.GAME}`);

// Easily map contract state uints to readable statuses
const getStatus = (statusId: number) => {
  if (statusId === GAME_STATUS.ONGOING) return "Game is Active";
  if (statusId === GAME_STATUS.WHITE_WINS) return "White Won";
  return "Unknown";
};

📚 Technical Architecture

The Frontend (frontend/)

• Framework: React + Vite + TypeScript
• Styling: TailwindCSS
• State Management: React useReducer for complex chess logic, combined with Context API.
• Blockchain Integration: (Planned) @stacks/connect for wallet authentication and transaction signing.

The Smart Contract (stacks-contracts/)

• Language: Clarity
• Core Features:
  1. Game Creation: Players escrow STX to initialize a match (create-game).
  2. Matchmaking: Opponents match the wager to join (join-game).
  3. State Machine: Sequential validation of turns using FEN/ASCII board states (submit-move).
  4. Resolution: Securely handles forfeits (resign) or mutually/Oracle-agreed game resolutions (resolve-game).

Architecture Overview

graph TD
    A[Player 1] -->|create-game + Escrow| B(Chessxu Contract)
    C[Player 2] -->|join-game + Escrow| B
    B -->|Game Active| D{Gameplay Loop}
    D -->|submit-move| D
    D -->|resign / resolve| E[Winner / Refund]
    E -->|Unlock Escrow| A
    E -->|Unlock Escrow| C
    B -.->|SIP-010| F[CHESS Token]
    B -.->|Native| G[STX]

📝 Deployed Contracts (Mainnet)

Stacks Mainnet

All Stacks contracts are deployed under the deployer address SP34MN3DMM07BNAWYJSHTS4B08T8JRVK8AT810X1B.

| Contract | Address | Explorer | |---|---|---| | SIP-010 Trait | SP34MN3DMM07BNAWYJSHTS4B08T8JRVK8AT810X1B.sip-010-trait-ft-standard | View | | Chessxu Token (CHESS) | SP34MN3DMM07BNAWYJSHTS4B08T8JRVK8AT810X1B.chessxu-token | View | | Chessxu Game | SP34MN3DMM07BNAWYJSHTS4B08T8JRVK8AT810X1B.chessxu | View |

Celo Mainnet

The Celo contract is deployed on the Celo Mainnet.

| Contract | Address | Explorer | |---|---|---| | Chessxu Game (v1) | 0xC43b25bB19a6Ccca549bb8E5C21fF0C44161EA14 | View | | Chessxu Game (v2) | 0xf4776929EB56F8C0fC41f87Cc7c4aEa4702de02E | View |

🛠️ Interaction Scripts (Celo)

We provide utility scripts in the celo-contract/ directory to interact with the deployed Chessxu contract directly from the command line.

Getting Started

Ensure your .env file contains the correct CONTRACT_ADDRESS and MAINNET_PRIVATE_KEY.

Usage

cd celo-contract
# Get help and list of commands
node scripts/util-interact.js --help

# Examples
node scripts/util-interact.js balance          # Check your wallet balance
node scripts/util-interact.js last             # Get the ID of the last game created
node scripts/util-interact.js create 0.1       # Create a new game with 0.1 CELO wager
node scripts/util-interact.js get 5            # View details of game #5

🎯 What You'll Learn

By exploring this repository, you'll see how to:

• Structure a monorepo for Stacks DApp development.
• Build complex game state handlers in React.
• Write robust, trustless state-machines in Clarity to track off-chain game progression securely.

🛠️ Tech Stack

Frontend:  React + Vite + TypeScript + TailwindCSS
State:     Context API + useReducer
Wallet:    Stacks Wallet (Leather/Xverse)
Contract:  Clarity + Clarinet

🌟 Key Features

⚡ Instant Feedback

• Playable purely in the browser with local move validation.
• Background blockchain confirmation without interrupting gameplay.

🔧 Developer Experience

• Complete TypeScript integration for strict type-safety.
• Separated boundaries between the stacks-contracts (and celo-contracts), and frontend.
• Zero-error ESLint configuration and production-ready npm run build process.

Ready to build the future of onchain gaming? Jump into the frontend/, stacks-contracts/ or celo-contracts/ directories to begin! 🚀