logoCheckmate
Program

Instructions Reference

Complete reference for all program instructions

Platform Management

create_platform_config

Initializes the global platform configuration (admin only).

Accounts:

  • authority (signer) - Platform admin authority
  • platform_config (mut) - Platform configuration PDA
  • system_program - System program

Parameters:

  • fee_basis_points: u16 - Platform fee (e.g., 500 = 5%)
  • fee_vault: Pubkey - Address to receive platform fees

Example:

pub fn create_platform_config(
    ctx: Context<CreatePlatformConfig>,
    fee_basis_points: u16,
    fee_vault: Pubkey,
) -> Result<()>

Validation:

  • Fee basis points must be ≤ 10,000 (100%)
  • Only callable once per platform
  • Authority must be the program upgrade authority

update_platform_config

Updates platform configuration settings.

Accounts:

  • authority (signer) - Platform admin authority
  • platform_config (mut) - Platform configuration PDA

Parameters:

  • fee_basis_points: Option<u16> - New platform fee
  • fee_vault: Option<Pubkey> - New fee vault address

Example:

pub fn update_platform_config(
    ctx: Context<UpdatePlatformConfig>,
    fee_basis_points: Option<u16>,
    fee_vault: Option<Pubkey>,
) -> Result<()>

Integrator Management

initialize_integrator

Sets up a new integrator configuration.

Accounts:

  • integrator (signer) - Integrator authority
  • integrator_config (mut) - Integrator configuration PDA
  • platform_config - Platform configuration (for validation)
  • system_program - System program

Parameters:

  • integrator_id: Pubkey - Unique integrator identifier
  • fee_basis_points: u16 - Integrator fee percentage
  • fee_vault: Pubkey - Integrator fee collection address

Example:

pub fn initialize_integrator(
    ctx: Context<InitializeIntegrator>,
    integrator_id: Pubkey,
    fee_basis_points: u16,
    fee_vault: Pubkey,
) -> Result<()>

PDA Derivation:

["integrator_config", integrator_id.as_ref()]

Validation:

  • Integrator fee + platform fee ≤ 50% (5,000 basis points)
  • Integrator ID must be unique
  • Fee vault must be a valid address

update_integrator_config

Modifies integrator settings.

Accounts:

  • integrator (signer) - Integrator authority
  • integrator_config (mut) - Integrator configuration PDA
  • platform_config - Platform configuration (for validation)

Parameters:

  • fee_basis_points: Option<u16> - New integrator fee
  • fee_vault: Option<Pubkey> - New fee vault

Game Lifecycle

create_game

Creates a new chess game.

Accounts:

  • creator (signer) - Game creator (white player)
  • integrator_config (mut) - Integrator configuration
  • game_authority - Game authority PDA
  • game_account (mut) - Game state account
  • token_mint - Entry fee token mint
  • token_vault (mut) - Game token escrow
  • creator_token_account (mut) - Creator's token account
  • move_history (mut) - Move history account
  • token_program - SPL Token program
  • associated_token_program - Associated Token program
  • system_program - System program

Parameters:

  • entry_fee: u64 - Entry fee amount in token units
  • time_control: Option<TimeControl> - Time control settings
  • rated_game: bool - Whether game affects ratings
  • allow_draw_offers: bool - Whether draw offers are allowed

Example:

pub fn create_game(
    ctx: Context<CreateGame>,
    entry_fee: u64,
    time_control: Option<TimeControl>,
    rated_game: bool,
    allow_draw_offers: bool,
) -> Result<()>

PDA Derivations:

// Game Account
["game", integrator_id.as_ref(), game_id.to_le_bytes().as_ref()]

// Token Vault
["token_vault", token_mint.as_ref(), game_account.as_ref()]

// Move History
["move_history", game_account.as_ref()]

// Game Authority
["game_authority"]

State Changes:

  • Game status: WaitingForPlayer
  • Board initialized to starting position
  • Creator's entry fee transferred to escrow
  • Game ID incremented in integrator config

join_game

Joins an existing game as the black player.

Accounts:

  • joiner (signer) - Joining player (black)
  • integrator_config - Integrator configuration
  • game_authority - Game authority PDA
  • game_account (mut) - Game state account
  • token_mint - Entry fee token mint
  • token_vault (mut) - Game token escrow
  • player_token_account (mut) - Joiner's token account
  • move_history - Move history account
  • token_program - SPL Token program
  • system_program - System program

Example:

pub fn join_game(ctx: Context<JoinGame>) -> Result<()>

Validation:

  • Game must be in WaitingForPlayer status
  • Joiner cannot be the same as creator
  • Joiner must have sufficient token balance

State Changes:

  • Game status: InProgress
  • Black player set to joiner
  • Joiner's entry fee transferred to escrow
  • Game timer started (if time control enabled)

cancel_game

Cancels a game before an opponent joins.

Accounts:

  • creator (signer) - Game creator
  • integrator_config - Integrator configuration
  • game_authority - Game authority PDA
  • game_account (mut) - Game state account
  • token_mint - Entry fee token mint
  • token_vault (mut) - Game token escrow
  • player_token_account (mut) - Creator's token account
  • token_program - SPL Token program

Example:

pub fn cancel_game(ctx: Context<CancelGame>) -> Result<()>

Validation:

  • Only creator can cancel
  • Game must be in WaitingForPlayer status
  • No opponent has joined yet

State Changes:

  • Game status: Cancelled
  • Creator's entry fee refunded
  • Token vault emptied

Gameplay Instructions

make_move

Executes a chess move.

Accounts:

  • player (signer) - Player making the move
  • integrator_config - Integrator configuration
  • game_account (mut) - Game state account
  • move_history (mut) - Move history account

Parameters:

  • from_square: u8 - Source square (0-63)
  • to_square: u8 - Destination square (0-63)
  • promotion_piece: Option<PieceType> - Piece to promote to (for pawn promotion)

Example:

pub fn make_move(
    ctx: Context<MakeMove>,
    from_square: u8,
    to_square: u8,
    promotion_piece: Option<PieceType>,
) -> Result<()>

Validation:

  • Must be player's turn
  • Game must be in InProgress status
  • Move must be legal according to chess rules
  • Cannot leave own king in check
  • Time control validation (if enabled)

State Changes:

  • Board state updated
  • Move added to history
  • Turn switched to opponent
  • Game status updated if game ends
  • Time control updated

Special Move Handling:

  • Castling: King and rook moved simultaneously
  • En Passant: Captured pawn removed from board
  • Promotion: Pawn replaced with chosen piece

forfeit_game

Forfeits the current game.

Accounts:

  • player (signer) - Player forfeiting
  • integrator_config - Integrator configuration
  • game_account (mut) - Game state account

Example:

pub fn forfeit_game(ctx: Context<ForfeitGame>) -> Result<()>

Validation:

  • Player must be a participant in the game
  • Game must be in InProgress status

State Changes:

  • Game status: Finished
  • Game result: Resignation
  • Winner set to opponent
  • Forfeit timestamp recorded

Draw System

offer_draw

Offers a draw to the opponent.

Accounts:

  • player (signer) - Player offering draw
  • integrator_config - Integrator configuration
  • game_account (mut) - Game state account

Example:

pub fn offer_draw(ctx: Context<OfferDraw>) -> Result<()>

Validation:

  • Must be player's turn
  • Game must allow draw offers
  • Game must be in InProgress status
  • No pending draw offer exists

State Changes:

  • Draw offer flag set
  • Draw offer timestamp recorded
  • Offering player recorded

accept_draw

Accepts a pending draw offer.

Accounts:

  • player (signer) - Player accepting draw
  • integrator_config - Integrator configuration
  • game_account (mut) - Game state account

Example:

pub fn accept_draw(ctx: Context<AcceptDraw>) -> Result<()>

Validation:

  • Pending draw offer must exist
  • Player must be the opponent of draw offerer
  • Game must be in InProgress status

State Changes:

  • Game status: Finished
  • Game result: DrawByAgreement
  • No winner (draw)
  • Draw acceptance timestamp

reject_draw

Rejects a pending draw offer.

Accounts:

  • player (signer) - Player rejecting draw
  • integrator_config - Integrator configuration
  • game_account (mut) - Game state account

Example:

pub fn reject_draw(ctx: Context<RejectDraw>) -> Result<()>

State Changes:

  • Draw offer flag cleared
  • Game continues normally

Prize Management

claim_winnings

Claims the prize pool after game completion.

Accounts:

  • player (signer) - Player claiming winnings
  • integrator_config - Integrator configuration
  • platform_config - Platform configuration
  • game_authority - Game authority PDA
  • game_account - Game state account
  • token_mint - Prize token mint
  • token_vault (mut) - Game token escrow
  • player_token_account (mut) - Player's token account
  • platform_fee_vault (mut) - Platform fee collection
  • integrator_fee_vault (mut) - Integrator fee collection
  • token_program - SPL Token program

Example:

pub fn claim_winnings(ctx: Context<ClaimWinnings>) -> Result<()>

Validation:

  • Game must be finished
  • Player must be eligible for winnings
  • Winnings not already claimed

Prize Distribution:

let total_prize = entry_fee * 2;
let platform_fee = total_prize * platform_fee_bps / 10000;
let integrator_fee = total_prize * integrator_fee_bps / 10000;
let player_payout = total_prize - platform_fee - integrator_fee;

State Changes:

  • Winnings claimed flag set
  • Tokens distributed to respective accounts
  • Token vault emptied

close_game

Closes a finished game and reclaims rent.

Accounts:

  • authority (signer) - Game participant or admin
  • game_account (mut) - Game state account
  • move_history (mut) - Move history account
  • rent_receiver (mut) - Account to receive reclaimed rent

Example:

pub fn close_game(ctx: Context<CloseGame>) -> Result<()>

Validation:

  • Game must be finished or cancelled
  • All winnings must be claimed (if applicable)
  • Authority must be a game participant

State Changes:

  • Game account closed
  • Move history account closed
  • Rent returned to specified receiver

Error Conditions

Each instruction can fail with specific error codes. See the Error Codes reference for complete details.

Next Steps

Overview

The ChessMate program is a Solana program that implements a complete chess game with escrow functionality, built using the Anchor framework and optimized for Ephemeral Rollups.

Accounts

Program account structures and their usage