Smart Contracts

This page provides a technical overview of the Lotto Balls smart contract architecture.

Contract Overview

Contract	Purpose
LottoBalls.sol	Main game logic, betting, VRF integration
LTB.sol	ERC-20 token with role-based access

LottoBalls Contract

The main game contract handles all betting, randomness, and payout logic.

Inheritance

contract LottoBalls is
    ReentrancyGuard,      // Prevents reentrancy attacks
    Pausable,             // Emergency pause functionality
    VRFConsumerBaseV2Plus, // Chainlink VRF integration
    ILottoBalls           // Interface definition

State Variables

Tokens

IERC20 public ltbToken;    // LTB token contract
IERC20 public usdc;        // USDC token contract
IERC20 public lazerToken;  // Whitelist access token

Game Configuration

uint256 public feePercent;    // Protocol fee (default 20%)
uint256 public usdcCost;      // Cost per USDC bet
uint256 public jackpotCap;    // Maximum jackpot payout
uint256[3] public payoutsUSDC; // Payouts for 1, 2, 3 matches

Tracking

uint256 public totalPlays;           // Total games played
mapping(uint256 => Bet) public bets; // Request ID → Bet data
mapping(address => bool) public hasBet; // Player → Has pending bet

Bet Structure

struct Bet {
    address player;         // Player address
    bool payWithUsdc;       // Payment method
    uint8[4] numbers;       // Player's chosen numbers
    uint8[4] contractNumbers; // Drawn numbers (after resolution)
    bool resolved;          // Bet completed?
    uint256 ltbCostSnapshot; // LTB cost at bet time
}

Core Functions

play()

function play(uint8[4] calldata userNumbers, bool payWithUsdc)
    external payable nonReentrant whenNotPaused onlyWhitelisted

• Validates player has whitelist token

• Ensures no pending bet exists

• Transfers payment (USDC or LTB)

• Requests VRF random number

• Emits GameRequested event

fulfillRandomWords()

function fulfillRandomWords(uint256 requestId, uint256[] calldata randomWords)
    internal override

• Called by Chainlink VRF with random number

• Derives 4 numbers from single random word

• Calculates matches

• Distributes prizes (USDC and/or LTB)

• Emits GameResolved event

View Functions

function jackpot() public view returns (uint256)
function ltbBalance() public view returns (uint256)
function getLtbCost() public view returns (uint256)
function getLtbReward(uint8 matches) public view returns (uint256)
function getLtbRewards() external view returns (uint256, uint256, uint256, uint256)
function getBet(uint256 requestId) external view returns (...)

Admin Functions

function setUsdcCost(uint256 cost) external onlyOwner
function setJackpotCap(uint256 cap) external onlyOwner
function setPayoutsUSDC(uint256[3] memory payouts) external onlyOwner
function setFeePercent(uint256 percent) external onlyOwner
function setLazerToken(address _lazer) external onlyOwner
function setLtbToken(address _ltb) external onlyOwner
function setExternalCaller(address caller, bool isExternal) external onlyOwner
function withdrawUSDC(uint256 amount) external onlyOwner
function withdrawLTB(uint256 amount) external onlyOwner
function pause() external onlyOwner
function unpause() external onlyOwner
function manualOverrideGame(uint256 id) external onlyOwner

LTB Token Contract

Standard ERC-20 with role-based minting/burning.

Roles

bytes32 public constant MINTER_ROLE = keccak256("MINTER_ROLE");
bytes32 public constant BURNER_ROLE = keccak256("BURNER_ROLE");

Privileged Functions

function mint(address to, uint256 amount) external onlyRole(MINTER_ROLE)
function burn(address from, uint256 amount) external onlyRole(BURNER_ROLE)

Events

GameRequested

event GameRequested(address user, uint256 gameId);

Emitted when a bet is placed successfully.

GameResolved

event GameResolved(
    address indexed user,
    uint256 indexed gameId,
    uint8 matches,
    uint8[4] playerNumbers,
    uint8[4] drawnNumbers,
    bool payWithUsdc,
    uint256 ltbReward
);

Emitted when VRF fulfills and the bet is resolved.

ManualGameOverride

event ManualGameOverride(address user, uint256 gameId);

Emitted when admin manually resolves a stuck bet.

Constants

uint256 internal constant DIVISOR = 100;
uint256 internal constant BUFFER_RATE = 30;    // 30% buffer
uint256 internal constant JACKPOT_RATE = 35;   // 35% of available

uint256 internal constant MLTB = 1e5 * 1e18;   // 100,000 LTB
uint256 internal constant LTB_COST_PERCENT = 1e14;  // 0.01%
uint256 internal constant LTB_MIN_COST = 10 * MLTB;
uint256 internal constant LTB_MAX_COST = 100 * MLTB;

uint256 internal constant LTB_REWARD_MATCH0 = 24780000000000;   // 0.002478%
uint256 internal constant LTB_REWARD_MATCH1 = 37170000000000;   // 0.003717%
uint256 internal constant LTB_REWARD_MATCH2 = 124320000000000;  // 0.012432%
uint256 internal constant LTB_REWARD_MATCH3 = 496860000000000;  // 0.049686%

External Dependencies

Dependency	Purpose
OpenZeppelin ReentrancyGuard	Reentrancy protection
OpenZeppelin Pausable	Emergency circuit breaker
OpenZeppelin IERC20	Token interface
Chainlink VRFConsumerBaseV2Plus	VRF integration
Chainlink VRFV2PlusClient	VRF request building