Game States

Understanding the lifecycle and state transitions of Gaambl Lotto games

Game State Lifecycle

Games progress through several states from creation to completion. Understanding these states helps with monitoring and participation.

ACTIVE

Accepting Players

Game is accepting new players. Players can join by paying the entry fee.

Duration: From creation until max players reached or expiration

Player Actions: Can join by paying entry fee

Auto-Complete: Triggers when max players reached

WAITING_RANDOMNESS

Requesting Entropy

Game reached completion trigger and randomness has been requested from Pyth Network.

Trigger: Max players reached OR manual completion of expired game

Duration: Usually 1-2 blocks, max 10 minutes before retry possible

Player Actions: No actions available, wait for randomness

READY_FOR_COMPLETION

Ready to Finalize

Randomness received from Pyth Network, waiting for finalization with 2-block delay for MEV protection.

Requirement: Must wait 2 blocks after randomness for MEV protection

Finalization: Anyone can call finalizeGameCompletion(gameId)

Bot Opportunity: Monitor for this state to trigger finalization

COMPLETED

Game Finished

Game finalized, winners selected, and prizes distributed. Winners can claim their prizes.

Winners: Can claim prizes with claimPrize(gameId)

Final State: No further state changes possible

Prizes: Must be manually claimed by winners

CANCELLED

Game Cancelled

Game cancelled due to emergency or no participants at expiration.

Trigger: Emergency admin action or zero participants at expiration

Refunds: All participants get full refunds through claim system

Final State: No further actions possible

REFUNDED

Single Player Refund

Game had only one participant (creator) at expiration and was automatically refunded.

Trigger: Single participant (creator) at expiration

Refund: Single participant gets entry fee back

Automatic: Handled automatically during expired game completion

State Transitions

Games follow a predictable state transition pattern based on player participation and timing.

Normal Completion Flow

ACTIVE → WAITING_RANDOMNESS → READY_FOR_COMPLETION → COMPLETED

Expired Game Flow

ACTIVE → (expired) → REFUNDED (1 player) or WAITING_RANDOMNESS → COMPLETED (2+ players)

Emergency Flow

Any state → CANCELLED (emergency admin action)

Monitoring Games

Key functions for monitoring game states and triggering finalization.

State Checking

  • • getGameBasicInfo(gameId) - Get current game state and info
  • • isGameReadyForCompletion(gameId) - Check if ready for finalization
  • • isGameExpired(gameId) - Check if game can be manually completed

Finalization

  • • finalizeGameCompletion(gameId) - Finalize ready games
  • • completeExpiredGame(gameId) - Complete expired games
  • • retryRandomness(gameId) - Retry failed randomness (admin only)
← Game Modes Creating Games →