This document outlines the planned development phases for Checkmate-Escrow, expanding on the high-level roadmap in the README.
The foundation of trustless chess wagering on Stellar.
- Multi-token escrow: Players stake any Stellar token (XLM, USDC, or custom assets) via a generic token interface
- Match lifecycle management: Create, deposit, activate, complete, cancel, and expire matches
- Lichess Oracle integration: Automated result verification via Lichess public API
- Chess.com platform support:
Platform::ChessDotComvariant supported in match creation - Winner payouts: Automatic distribution of the full pot to the winner
- Draw handling: Stakes returned to both players when games end in a draw
- Cancellation logic: Players can cancel unfunded matches before both deposits are made
- Match expiry: Pending matches that exceed a configurable ledger timeout can be expired by anyone, refunding any deposits
- Token allowlist: Admin can restrict which tokens are accepted via
add_allowed_token - Contract pause/unpause: Admin can halt
create_match,deposit, andsubmit_resultin an emergency - Admin management: Two-step admin transfer (
propose_admin/accept_admin) and directtransfer_admin - Match indexing:
get_player_matchesandget_active_matchesfor efficient on-chain lookups - Basic security: Admin-gated oracle submission, duplicate game ID prevention
- Result submission: Admin submits verified match results on-chain
- Result queries: Public
has_resultand admin-gatedhas_result_admin - Result deletion: Admin can remove a previously submitted result via
delete_result - Oracle pause/unpause: Admin can halt result submission independently of the escrow contract
- Admin rotation:
update_adminrotates the oracle admin address
✅ Complete — deployed to testnet
Expand the off-chain oracle service to cover Chess.com and standardize the token integration.
- Chess.com Oracle: Implement the off-chain API client for Chess.com result verification
- Platform validation: Validate that game IDs match the declared platform format (numeric strings for Chess.com)
- Token interface documentation: Document the generic token transfer pattern for integrators
- Add Chess.com API client to the oracle off-chain service
- Update validation to handle Chess.com game ID format
- Document token integration patterns
Q2 2026
Enable multi-game tournaments with bracket-style payouts.
- Tournament creation: Define multi-round tournaments with entry fees
- Bracket management: Track tournament structure and progression
- Prize pool distribution: Configurable payout splits (e.g., 60% winner, 30% runner-up, 10% third place)
- Batch result submission: Oracle can submit multiple match results in a single transaction
- Tournament state tracking: Monitor active tournaments, completed rounds, and remaining matches
- New
Tournamentcontract with bracket logic - Link multiple
Matchinstances to a single tournament - Implement prize pool calculation and distribution
- Add tournament admin controls (pause, cancel, modify structure)
- Chess club tournaments with on-chain prize pools
- Online tournaments with automatic payouts
- Bracket-style competitions with transparent prize distribution
Q3-Q4 2026
Make Checkmate-Escrow accessible to non-technical users.
- Web application: React-based frontend for creating and managing matches
- Wallet integration: Support for Freighter, Albedo, and other Stellar wallets
- Match browser: View active matches, tournament brackets, and historical results
- Real-time updates: WebSocket integration for live match status
- User profiles: Track match history, win/loss records, and earnings
- Mobile-responsive design: Optimized for desktop and mobile browsers
- React + TypeScript
- Stellar SDK for wallet integration
- TailwindCSS for styling
- WebSocket server for real-time updates
Q1-Q2 2027
Native mobile experience with intelligent player matching.
- Native mobile apps: iOS and Android applications
- ELO-based matchmaking: Match players of similar skill levels
- Leaderboards: Global and regional rankings based on match performance
- Push notifications: Alerts for match invitations, deposits, and results
- In-app wallet: Simplified Stellar wallet for casual users
- Social features: Friend lists, match challenges, and chat
- React Native mobile app
- ELO rating calculation and storage
- Matchmaking algorithm based on rating and stake preferences
- Push notification service integration
- Simplified wallet creation and management
- Casual players finding opponents at their skill level
- Competitive players climbing leaderboards
- Mobile-first chess betting experience
Q3-Q4 2027
Beyond v4.0, potential features include:
- Multi-chain support: Bridge to other blockchain networks
- Streaming integration: Automatic result verification from Twitch/YouTube chess streams
- Team tournaments: Multi-player team-based competitions
- Staking rewards: Earn yield on escrowed funds during active matches
- Governance token: Community-driven platform decisions
- Sponsorship integration: Allow sponsors to fund prize pools
Have ideas for features or improvements? Open an issue or discussion on GitHub. We welcome community input on prioritization and new feature proposals.
See CONTRIBUTING.md for details on how to contribute.
- Tournament Entity: Stores metadata (name, entry fee, game ID).
- Bracket Structure: A tree-based model where each node represents a 'Match'.
- Match Entity: Links two Participant IDs, stores WinnerID, and Status (Pending/Complete).
- Mechanism: Single-elimination tournament style.
- Payout: Winner takes X% of the pool; remaining Y% distributed to runner-up/finalists based on a configurable PayoutTable.
- Escrow Integration: Funds are locked at tournament start and released automatically via execute_payout upon Match conclusion.
- Entry Fees: Should fees be collected per game or per tournament?
- Sponsorship: How can third-party sponsors inject liquidity into the prize pool?
- Cancellation: What is the mechanism for refunding entries if a tournament fails to fill?