Smart Contracts

Learn about Illumind's smart contract architecture, security measures, and how our decentralized prediction system works at the blockchain level.

🏗️ Contract Architecture

Main Contracts Overview:

📝 Illumind Smart Contracts:
├── 🎯 IllumindPrediction.sol (Main prediction logic)
├── 🪙 IllumindToken.sol (ERC-20 token)
├── 🔮 PriceOracle.sol (Moralis price feeds)
├── 🎁 RewardDistributor.sol (Automated payouts)
├── 🗳️ Governance.sol (DAO functionality)
└── 🔄 CrossChainBridge.sol (Multi-chain support)

Contract Relationships:

🎯 IllumindPrediction.sol - Main Contract

Core Data Structures:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.19;

contract IllumindPrediction {
    struct PredictionRound {
        uint256 id;
        uint256 startTime;
        uint256 endTime;
        uint256 priceAtStart;
        uint256 priceAtEnd;
        uint256 totalUpAmount;
        uint256 totalDownAmount;
        bool isResolved;
        bool isActive;
    }
    
    struct UserPrediction {
        address user;
        uint256 roundId;
        bool predictedUp;
        uint256 amount;
        bool claimed;
        uint256 reward;
    }
    
    struct AIInsight {
        uint256 confidence;
        string analysis;
        uint256 timestamp;
        bytes32 modelHash;
    }
}

Key Functions:

1. Round Management

/**
 * @dev Start a new prediction round
 * @return roundId The ID of the newly created round
 */
function startNewRound() external returns (uint256 roundId) {
    require(block.timestamp >= lastRoundEndTime, "Previous round not ended");
    
    uint256 currentPrice = priceOracle.getCurrentPrice();
    require(currentPrice > 0, "Invalid price from oracle");
    
    roundId = ++currentRoundId;
    
    rounds[roundId] = PredictionRound({
        id: roundId,
        startTime: block.timestamp,
        endTime: block.timestamp + ROUND_DURATION,
        priceAtStart: currentPrice,
        priceAtEnd: 0,
        totalUpAmount: 0,
        totalDownAmount: 0,
        isResolved: false,
        isActive: true
    });
    
    lastRoundEndTime = block.timestamp + ROUND_DURATION;
    
    emit RoundStarted(roundId, currentPrice, block.timestamp);
    return roundId;
}

/**
 * @dev Resolve a finished round and determine winners
 * @param roundId The round to resolve
 */
function resolveRound(uint256 roundId) external {
    PredictionRound storage round = rounds[roundId];
    require(block.timestamp >= round.endTime, "Round not finished");
    require(!round.isResolved, "Round already resolved");
    
    uint256 finalPrice = priceOracle.getCurrentPrice();
    round.priceAtEnd = finalPrice;
    round.isResolved = true;
    round.isActive = false;
    
    bool upWins = finalPrice > round.priceAtStart;
    
    // Distribute rewards
    rewardDistributor.distributeRewards(roundId, upWins);
    
    emit RoundResolved(roundId, finalPrice, upWins);
}

2. Prediction Functions

/**
 * @dev Make a prediction for an active round
 * @param roundId The round to predict on
 * @param predictUp True for UP, false for DOWN
 * @param amount Amount of ILLUMIND tokens to stake
 */
function makePrediction(
    uint256 roundId, 
    bool predictUp, 
    uint256 amount
) external {
    PredictionRound storage round = rounds[roundId];
    require(round.isActive, "Round not active");
    require(block.timestamp < round.endTime, "Round ended");
    require(amount >= MIN_PREDICTION_AMOUNT, "Amount too small");
    require(amount <= MAX_PREDICTION_AMOUNT, "Amount too large");
    
    // Check user has enough tokens
    require(illumindToken.balanceOf(msg.sender) >= amount, "Insufficient balance");
    
    // Transfer tokens to contract
    illumindToken.transferFrom(msg.sender, address(this), amount);
    
    // Record prediction
    userPredictions[msg.sender][roundId] = UserPrediction({
        user: msg.sender,
        roundId: roundId,
        predictedUp: predictUp,
        amount: amount,
        claimed: false,
        reward: 0
    });
    
    // Update round totals
    if (predictUp) {
        round.totalUpAmount += amount;
    } else {
        round.totalDownAmount += amount;
    }
    
    emit PredictionMade(msg.sender, roundId, predictUp, amount);
}

/**
 * @dev Claim rewards for a won prediction
 * @param roundId The round to claim rewards from
 */
function claimReward(uint256 roundId) external {
    UserPrediction storage prediction = userPredictions[msg.sender][roundId];
    require(prediction.amount > 0, "No prediction found");
    require(!prediction.claimed, "Already claimed");
    
    PredictionRound storage round = rounds[roundId];
    require(round.isResolved, "Round not resolved");
    
    uint256 reward = calculateReward(roundId, msg.sender);
    if (reward > 0) {
        prediction.claimed = true;
        prediction.reward = reward;
        
        illumindToken.transfer(msg.sender, reward);
        emit RewardClaimed(msg.sender, roundId, reward);
    }
}

3. Reward Calculation

/**
 * @dev Calculate reward for a user's prediction
 * @param roundId The round ID
 * @param user The user address
 * @return reward The calculated reward amount
 */
function calculateReward(uint256 roundId, address user) 
    public view returns (uint256 reward) {
    
    UserPrediction memory prediction = userPredictions[user][roundId];
    PredictionRound memory round = rounds[roundId];
    
    if (prediction.amount == 0 || !round.isResolved) {
        return 0;
    }
    
    // Determine if user won
    bool upWon = round.priceAtEnd > round.priceAtStart;
    bool userWon = (prediction.predictedUp && upWon) || 
                   (!prediction.predictedUp && !upWon);
    
    if (!userWon) {
        return 0;
    }
    
    // Calculate total pool and winning pool
    uint256 totalPool = round.totalUpAmount + round.totalDownAmount;
    uint256 winningPool = upWon ? round.totalUpAmount : round.totalDownAmount;
    uint256 losingPool = totalPool - winningPool;
    
    // 90% of total pool goes to winners, 8% to platform, 2% burned
    uint256 rewardPool = (totalPool * REWARD_PERCENTAGE) / 100; // 90%
    
    // User's share based on their stake proportion
    uint256 userShare = (prediction.amount * rewardPool) / winningPool;
    
    // Apply AI confidence multiplier
    uint256 confidence = aiInsights[roundId].confidence;
    uint256 multiplier = 100 + ((confidence - 50) * AI_MULTIPLIER_FACTOR) / 100;
    
    reward = (userShare * multiplier) / 100;
    
    return reward;
}

🔮 PriceOracle.sol - Price Feeds

Oracle Architecture:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.19;

import "@chainlink/contracts/src/v0.8/interfaces/AggregatorV3Interface.sol";

contract PriceOracle {
    AggregatorV3Interface internal priceFeed;
    
    // Backup price sources
    mapping(string => address) public priceFeeds;
    uint256 public constant PRICE_DECIMALS = 8;
    uint256 public constant MAX_PRICE_AGE = 300; // 5 minutes
    
    constructor() {
        // Ethereum mainnet ETH/USD price feed
        priceFeed = AggregatorV3Interface(0x5f4eC3Df9cbd43714FE2740f5E3616155c5b8419);
    }
    
    /**
     * @dev Get current ETH price in USD
     * @return price Current price scaled to 8 decimals
     */
    function getCurrentPrice() external view returns (uint256 price) {
        (
            uint80 roundId,
            int256 priceInt,
            uint256 startedAt,
            uint256 updatedAt,
            uint80 answeredInRound
        ) = priceFeed.latestRoundData();
        
        require(priceInt > 0, "Invalid price");
        require(updatedAt > 0, "Price not updated");
        require(block.timestamp - updatedAt <= MAX_PRICE_AGE, "Price too old");
        
        return uint256(priceInt);
    }
    
    /**
     * @dev Get price at specific round for historical data
     * @param roundId Chainlink round ID
     * @return price Historical price
     */
    function getHistoricalPrice(uint80 roundId) 
        external view returns (uint256 price) {
        (
            ,
            int256 priceInt,
            ,
            uint256 updatedAt,
        ) = priceFeed.getRoundData(roundId);
        
        require(priceInt > 0, "Invalid historical price");
        require(updatedAt > 0, "Invalid timestamp");
        
        return uint256(priceInt);
    }
}

🎁 RewardDistributor.sol - Automated Payouts

Reward Distribution Logic:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.19;

contract RewardDistributor {
    IllumindGame public immutable game;
    IllumindToken public immutable token;
    
    uint256 public constant WINNER_PERCENTAGE = 90; // 90% to winners
    uint256 public constant PLATFORM_PERCENTAGE = 8; // 8% to platform
    uint256 public constant BURN_PERCENTAGE = 2; // 2% burned
    
    event RewardsDistributed(uint256 indexed roundId, uint256 totalRewards, uint256 burned);
    
    /**
     * @dev Distribute rewards for a completed round
     * @param roundId The round to distribute rewards for
     * @param upWins Whether UP predictions won
     */
    function distributeRewards(uint256 roundId, bool upWins) external {
        require(msg.sender == address(game), "Only game contract");
        
        (
            uint256 totalUpAmount,
            uint256 totalDownAmount
        ) = game.getRoundAmounts(roundId);
        
        uint256 totalPool = totalUpAmount + totalDownAmount;
        uint256 winningPool = upWins ? totalUpAmount : totalDownAmount;
        
        if (totalPool == 0 || winningPool == 0) {
            return; // No valid predictions
        }
        
        // Calculate distributions
        uint256 rewardAmount = (totalPool * WINNER_PERCENTAGE) / 100;
        uint256 platformFee = (totalPool * PLATFORM_PERCENTAGE) / 100;
        uint256 burnAmount = (totalPool * BURN_PERCENTAGE) / 100;
        
        // Send platform fee
        token.transfer(game.platformWallet(), platformFee);
        
        // Burn tokens
        token.burn(burnAmount);
        
        emit RewardsDistributed(roundId, rewardAmount, burnAmount);
    }
    
    /**
     * @dev Emergency withdrawal function
     * @param amount Amount to withdraw
     */
    function emergencyWithdraw(uint256 amount) external {
        require(msg.sender == game.owner(), "Only owner");
        require(game.emergencyMode(), "Not in emergency mode");
        
        token.transfer(msg.sender, amount);
    }
}

🗳️ Governance.sol - DAO Functionality

Governance Structure:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.19;

contract Governance {
    struct Proposal {
        uint256 id;
        address proposer;
        string description;
        uint256 votesFor;
        uint256 votesAgainst;
        uint256 startTime;
        uint256 endTime;
        bool executed;
        bool cancelled;
        bytes callData;
        address target;
    }
    
    mapping(uint256 => Proposal) public proposals;
    mapping(uint256 => mapping(address => bool)) public hasVoted;
    
    uint256 public proposalCount;
    uint256 public constant VOTING_PERIOD = 7 days;
    uint256 public constant MIN_PROPOSAL_TOKENS = 1000 * 10**18; // 1000 ILLUMIND
    uint256 public constant QUORUM_PERCENTAGE = 10; // 10% of supply
    
    /**
     * @dev Create a new governance proposal
     * @param description Human readable description
     * @param target Contract to call if proposal passes
     * @param callData Function call data
     */
    function createProposal(
        string memory description,
        address target,
        bytes memory callData
    ) external returns (uint256 proposalId) {
        require(
            token.balanceOf(msg.sender) >= MIN_PROPOSAL_TOKENS,
            "Insufficient tokens to propose"
        );
        
        proposalId = ++proposalCount;
        
        proposals[proposalId] = Proposal({
            id: proposalId,
            proposer: msg.sender,
            description: description,
            votesFor: 0,
            votesAgainst: 0,
            startTime: block.timestamp,
            endTime: block.timestamp + VOTING_PERIOD,
            executed: false,
            cancelled: false,
            callData: callData,
            target: target
        });
        
        emit ProposalCreated(proposalId, msg.sender, description);
    }
    
    /**
     * @dev Vote on a proposal
     * @param proposalId The proposal to vote on
     * @param support True for yes, false for no
     */
    function vote(uint256 proposalId, bool support) external {
        Proposal storage proposal = proposals[proposalId];
        require(block.timestamp <= proposal.endTime, "Voting ended");
        require(!hasVoted[proposalId][msg.sender], "Already voted");
        
        uint256 voterTokens = token.balanceOf(msg.sender);
        require(voterTokens > 0, "No voting power");
        
        hasVoted[proposalId][msg.sender] = true;
        
        if (support) {
            proposal.votesFor += voterTokens;
        } else {
            proposal.votesAgainst += voterTokens;
        }
        
        emit VoteCast(msg.sender, proposalId, support, voterTokens);
    }
}

🛡️ Security Measures

Access Control:

// Role-based access control
contract IllumindPrediction is AccessControl {
    bytes32 public constant ADMIN_ROLE = keccak256("ADMIN_ROLE");
    bytes32 public constant ORACLE_ROLE = keccak256("ORACLE_ROLE");
    bytes32 public constant EMERGENCY_ROLE = keccak256("EMERGENCY_ROLE");
    
    modifier onlyAdmin() {
        require(hasRole(ADMIN_ROLE, msg.sender), "Not admin");
        _;
    }
    
    modifier onlyOracle() {
        require(hasRole(ORACLE_ROLE, msg.sender), "Not oracle");
        _;
    }
    
    modifier notInEmergency() {
        require(!emergencyMode, "Emergency mode active");
        _;
    }
}

Emergency Controls:

// Emergency pause functionality
contract EmergencyControls {
    bool public emergencyMode = false;
    address public emergencyAdmin;
    
    event EmergencyActivated(address indexed admin);
    event EmergencyDeactivated(address indexed admin);
    
    function activateEmergency() external {
        require(
            msg.sender == emergencyAdmin || 
            hasRole(EMERGENCY_ROLE, msg.sender), 
            "Not authorized"
        );
        
        emergencyMode = true;
        emit EmergencyActivated(msg.sender);
    }
    
    function deactivateEmergency() external {
        require(msg.sender == emergencyAdmin, "Only emergency admin");
        
        emergencyMode = false;
        emit EmergencyDeactivated(msg.sender);
    }
}

Reentrancy Protection:

// ReentrancyGuard implementation
abstract contract ReentrancyGuard {
    uint256 private constant _NOT_ENTERED = 1;
    uint256 private constant _ENTERED = 2;
    
    uint256 private _status;
    
    constructor() {
        _status = _NOT_ENTERED;
    }
    
    modifier nonReentrant() {
        require(_status != _ENTERED, "ReentrancyGuard: reentrant call");
        _status = _ENTERED;
        _;
        _status = _NOT_ENTERED;
    }
}

🔧 Deployment & Upgrades

Deployment Script:

// deployment/deploy.js
const { ethers, upgrades } = require("hardhat");

async function main() {
    // Deploy ILLUMIND Token
    const IllumindToken = await ethers.getContractFactory("IllumindToken");
    const token = await IllumindToken.deploy();
    await token.deployed();
    
    // Deploy Price Oracle
    const PriceOracle = await ethers.getContractFactory("PriceOracle");
    const oracle = await PriceOracle.deploy();
    await oracle.deployed();
    
    // Deploy Reward Distributor
    const RewardDistributor = await ethers.getContractFactory("RewardDistributor");
    const distributor = await RewardDistributor.deploy();
    await distributor.deployed();
    
    // Deploy Main Game Contract (Upgradeable)
    const IllumindPrediction= await ethers.getContractFactory("IllumindPrediction");
    const game = await upgrades.deployProxy(IllumindGame, [
        token.address,
        oracle.address,
        distributor.address
    ], { initializer: 'initialize' });
    await game.deployed();
    
    console.log("Contracts deployed:");
    console.log("Token:", token.address);
    console.log("Oracle:", oracle.address);
    console.log("Distributor:", distributor.address);
    console.log("Game:", game.address);
}

Upgrade Process:

// Upgradeable contract pattern
contract IllumindGameV2 is IllumindGameV1 {
    // New state variables go at the end
    mapping(address => uint256) public userExperience;
    uint256 public newFeatureEnabled;
    
    // New functions can be added
    function newFeature() external {
        require(newFeatureEnabled == 1, "Feature not enabled");
        // Implementation
    }
    
    // Override functions to modify behavior
    function calculateReward(uint256 roundId, address user) 
        public view override returns (uint256) {
        // Enhanced reward calculation
        uint256 baseReward = super.calculateReward(roundId, user);
        uint256 experienceBonus = userExperience[user] / 1000; // 0.1% per 1000 exp
        
        return baseReward + (baseReward * experienceBonus / 1000);
    }
}

📊 Contract Monitoring

Event Monitoring:

// Key events for monitoring
event RoundStarted(uint256 indexed roundId, uint256 startPrice, uint256 timestamp);
event PredictionMade(address indexed user, uint256 indexed roundId, bool predictedUp, uint256 amount);
event RoundResolved(uint256 indexed roundId, uint256 endPrice, bool upWon);
event RewardClaimed(address indexed user, uint256 indexed roundId, uint256 reward);
event EmergencyActivated(address indexed admin);

Gas Optimization:

// Gas-efficient struct packing
struct OptimizedPrediction {
    address user;        // 20 bytes
    uint96 amount;       // 12 bytes (fits in same slot)
    uint32 roundId;      // 4 bytes
    uint32 timestamp;    // 4 bytes
    bool predictedUp;    // 1 byte
    bool claimed;        // 1 byte
    // Total: 42 bytes across 2 storage slots
}

🔍 Contract Verification

Verification Commands:

# Verify on Etherscan
npx hardhat verify --network mainnet DEPLOYED_CONTRACT_ADDRESS "Constructor" "Arguments"

# Verify proxy implementation
npx hardhat verify --network mainnet IMPLEMENTATION_ADDRESS

# Verify with libraries
npx hardhat verify --network mainnet DEPLOYED_CONTRACT_ADDRESS \
  --libraries libraries.json "Constructor" "Arguments"

---

Next: Learn about our API endpoints → API Reference