Gaambl Documentation

🎯 What is Gaambl?

Gaambl is a decentralized gaming platform that allows users to create and participate in lottery-style games with customizable risk profiles. Built on Ethereum, it uses Pyth Network's Entropy service for provably fair randomness generation.

🎮 Create Games

Anyone can create a lottery game with custom entry fees, player limits, duration, and risk modes.

🎲 Join Games

Players can join existing games by paying the entry fee in ETH or whitelisted tokens.

🏆 Win Prizes

Winners are selected using cryptographically secure randomness and receive prizes based on the chosen risk profile.

💰 Earn Fees

Game creators earn 0.5% of the total pot, while the platform takes 0.5% for maintenance.

⚡ How Gaambl Works

Game Creation

A user creates a game by setting parameters like entry fee (0.001+ ETH), max players (10-1000), duration (24 hours - 30 days), and risk mode. They pay a 0.001 ETH creation fee.

Player Registration

Players join by paying the entry fee. The game can complete when max players is reached OR when the creator manually completes it OR when the time expires.

Randomness Generation

When the game is ready to complete, it requests randomness from Pyth Network's Entropy service, which provides cryptographically secure random numbers.

Winner Selection

The random number is used to shuffle all players using the Fisher-Yates algorithm. Winners are selected from the top of this shuffled list.

Prize Distribution

Prizes are calculated using an exponential decay curve and distributed to winners. Platform and creator fees are deducted before prize calculation.

                    Important: If a game expires without enough players, all participants receive full refunds through a batched refund system.
                

🎯 Risk Modes & Prize Distribution

Gaambl offers 5 different risk modes that determine what percentage of players win and how prizes are distributed among winners.

Conservative

40% of players win

Curve Factor: 200

More equal prize distribution

Moderate

25% of players win

Curve Factor: 300

Balanced risk/reward

Aggressive

15% of players win

Curve Factor: 500

Higher concentration

High Risk

10% of players win

Curve Factor: 800

Big winners, small losers

Extreme

5% of players win

Curve Factor: 1500

Winner takes most

📊 Prize Curve Visualization

The curve factor determines how dramatically prize amounts decrease from 1st place to last place. Here's how different risk modes distribute prizes among 100 players:

🧮 Prize Calculation Formula

The contract uses an exponential decay formula to calculate prize amounts:

position = (winnerIndex × 1000) ÷ totalWinners
decayFactor = (curveFactor × position) ÷ 1000
rawValue = (1000 - decayFactor)²
prize = (prizePool × rawValue) ÷ totalRawValues

                    Example: In a High Risk game with 100 players and 1 ETH prize pool:

                    • 1st place gets ~0.45 ETH (45% of pool)

                    • 5th place gets ~0.18 ETH (18% of pool)

                    • 10th place gets ~0.01 ETH (1% of pool)

🎲 Provably Fair Randomness

Gaambl uses Pyth Network's Entropy service to ensure completely fair and unpredictable winner selection.

🔐 How Randomness Works

Entropy Request

When a game is ready to complete, the contract requests a random number from Pyth Network's Entropy service with a user commitment hash.

Random Number Generation

Pyth Network generates a cryptographically secure random number using multiple entropy sources and returns it to the contract.

Fisher-Yates Shuffle

The contract uses the random number to perform a Fisher-Yates shuffle of all players, creating a completely randomized order.

Winner Selection

Winners are selected from the top of the shuffled list based on the risk mode's winner percentage.

🔄 Fisher-Yates Shuffle Algorithm

function _shufflePlayers(address[] memory players, uint256 randomNumber) private pure returns (address[] memory) {
    address[] memory shuffled = new address[](players.length);
    
    // Copy all players to shuffled array
    for (uint256 i = 0; i < players.length; i++) {
        shuffled[i] = players[i];
    }
    
    // Perform Fisher-Yates shuffle
    for (uint256 i = shuffled.length - 1; i > 0; i--) {
        uint256 j = uint256(keccak256(abi.encodePacked(randomNumber, i))) % (i + 1);
        (shuffled[i], shuffled[j]) = (shuffled[j], shuffled[i]);
    }
    
    return shuffled;
}
                

Provably Fair: The entire randomness process is transparent and verifiable on-chain. No one, including the platform operators, can predict or influence the outcome.

💰 Fee Structure

Gaambl has a transparent and fair fee structure that supports both the platform and game creators.

Fee Type	Amount	Purpose	When Charged
Game Creation Fee	0.001 ETH	Prevent spam games	When creating a game
Platform Fee	0.5% of total pot	Platform maintenance	When game completes
Creator Fee	0.5% of total pot	Game creator reward	When game completes

📊 Fee Calculation Example

Game Setup

Entry Fee: 0.01 ETH
Players: 100
Total Pot: 1.0 ETH

Fee Breakdown

Platform Fee: 0.005 ETH (0.5%)
Creator Fee: 0.005 ETH (0.5%)
Total Fees: 0.01 ETH (1%)

Prize Pool

Available for Winners: 0.99 ETH
(99% of total pot goes to winners)

Important: Fees are calculated and deducted BEFORE prize distribution, ensuring the contract never distributes more than it receives.

🔧 Technical Details

📋 Contract Parameters

Parameter	Minimum	Maximum	Description
Players per Game	10	1,000	Number of participants allowed
Game Duration	24 hours	30 days	How long players can join
Entry Fee	0.001 ETH	No limit	Cost to join a game
Max Platform Fee	-	5%	Platform + creator fees combined

🛡️ Security Features

Reentrancy Protection

Uses OpenZeppelin's ReentrancyGuard to prevent reentrancy attacks during prize distribution and refunds.

Safe Token Transfers

Implements SafeERC20 for secure token operations and handles failed transfers gracefully.

Token Whitelist

Only whitelisted tokens can be used for games, preventing malicious token attacks.

Batched Refunds

Expired games refund players in batches to prevent gas limit issues while maintaining fund safety.

🔗 Supported Networks

Gaambl is deployed on Ethereum mainnet and uses Pyth Network's Entropy service for randomness generation.

📚 Smart Contract Functions

// Core functions
createGame(GameConfig memory config) → uint256 gameId
joinGame(uint256 gameId) → void
completeGame(uint256 gameId) → void
handleExpiredGame(uint256 gameId) → void

// View functions
getGame(uint256 gameId) → (game details)
getActiveGames() → uint256[] gameIds
getUserGames(address user) → uint256[] gameIds
getRiskModeInfo(RiskMode mode) → (winnerPercent, curveFactor)
                

Open Source: The Gaambl smart contract is fully open source and auditable. All game logic, randomness generation, and prize distribution can be verified on-chain.