🕸️Boxes Smart Contracts Ecosystem

BoxFactory

The Factory contract serves as a central hub for managing and creating boxes instances using a predefined contract model. This contract utilizes events to facilitate the monitoring of its activities, particularly the creation of boxes

null

Box Contract

Manages the details, participations, and distributions of individual predictions.

null

Oracle

Provides match results, acting as an external source of truth, powered via AI.

null

🔄 Simplified Operation

  • Dynamic Deployment: Each user-initiated prediction is instantiated as a separate smart-contract, dynamically deployed via the Factory contract.

  • Autonomous Management: These contracts autonomously manage predictions, enforce the specific rules of each wager, and facilitate the distribution of winnings post-result validation.

  • Secure Interactions: The contracts guarantee that all transactions are executed securely and remain immutable once recorded on the blockchain.

BoxFactory Contract

Overview

The BoxFactory contract serves as the foundational contract for the WhaleInTheBox platform. It is responsible for the creation and management of individual prediction events, known as "boxes." By leveraging the factory pattern, this contract allows for scalable and efficient deployment of new boxes, each encapsulating its own logic and state.

Key Functions

  • createBox: Allow you to create a new Box contract instance with specified parameters such as details, end time, maximum amount per prediction, and whether the box is public or private.

    function createBox(
    string memory _details,
    uint256 _endTime,
    uint256 _maxAmount,
    bool _isPublic,
    address _betTokenAddress,
    Box.BoxEvent[] calldata _initialEvents,
    string memory _gameId,
    string memory _leagueId,
    string memory _sportId
) external returns (address)

  • setOracleAddress: Enables the contract owner to update the address of the Oracle contract, which provides outcomes for prediction events.

Key Features

  • Scalability: By using the factory pattern, the platform can handle an arbitrary number of prediction events without congesting a single contract.

  • Modularity: Each Box contract operates independently, promoting better organization and easier maintenance.

  • Creator Tracking: The factory maintains a mapping of creators to the boxes they've created, facilitating easy retrieval and management.

Box Contract

Overview

The Box contract represents an individual prediction event. It encapsulates all the logic related to managing predictions, storing participants' stakes, and settling outcomes. The contract is composed of several inherited contracts that modularize its functionality:

  • BoxStorage: Handles data storage and access control.

  • BoxBetting: Manages prediction placements.

  • BoxSettlement: Handles the settlement of predictions and distribution of rewards.

Key Functions

  • createBox: Initializes the box with specific details, including events, game IDs, and visibility settings.

    function createBox(
    string memory _details,
    uint256 _endTime,
    uint256 _maxAmount,
    bool _isPublic,
    BoxEvent[] calldata _initialEvents,
    string memory _gameId,
    string memory _leagueId,
    string memory _sportId
) external onlyRole(ADMIN_ROLE)

Interactions with Other Contracts

  • Oracle Contract: Utilizes the Oracle to obtain the outcome of the prediction event for settlement.

BoxStorage Contract

Overview

BoxStorage is an abstract contract that provides the foundational data structures and access control mechanisms for the Box contract. It defines the roles, events, and core variables used across the BoxBetting and BoxSettlement contracts.

Data Structures

  • Bet: Stores information about each participant's prediction and stake.

    struct Bet {
    address participant;
    bool prediction;
    uint256 amount;
}

  • BoxEvent: Represents specific events or conditions tied to the prediction.

    struct BoxEvent {
    string who;
    string what;
    string when;
}

  • BoxDetails: Aggregates all relevant information about the box.

    struct BoxDetails {
    string details;
    uint256 endTime;
    uint256 maxAmount;
    bool isPublic;
    bool isSettled;
    bool outcome;
    uint256 totalAmount;
    Bet[] bets;
    BoxEvent[] boxEvents;
    string gameId;
    string leagueId;
    string sportId;
}

BoxBetting Contract

Overview

The BoxBetting contract extends BoxStorage and handles all functionalities related to placing predictions. It ensures that participants adhere to the rules set for each box, such as maximum stake amounts and time constraints.

Key Functions

  • createBet: Allows participants to place a prediction using native tokens.

    function createBet(string calldata prediction) external payable nonReentrant

  • createBetWithAmount: Enables participants to place a prediction using ERC20 tokens.

    function createBetWithAmount(string calldata prediction, uint256 betAmount) external nonReentrant

Features

  • Prediction Validation: Converts string inputs to boolean predictions for processing.

  • Stake Management: Updates the total amount and individual stakes upon each prediction.

  • Public and Private Boxes: Enforces access control based on whether a box is public or private.

BoxSettlement Contract

Overview

BoxSettlement is responsible for finalizing prediction events and distributing rewards to the participants. It interacts with the Oracle contract to obtain the outcome and calculates winnings based on participants' stakes.

Settlement Process

  1. Outcome Retrieval: Fetches the result from the Oracle contract.

  2. Outcome Recording: Updates the box's state to reflect the settled outcome.

  3. Winnings Calculation: Determines each participant's winnings based on their stake and the total pool.

  4. Fee Deduction: Applies a fee percentage, transferring it to the staking address.

  5. Reward Distribution: Transfers winnings to participants.

Key Functions

  • settleBetFromOracle: Fetches and records the outcome from the Oracle.

    function settleBetFromOracle() public nonReentrant

  • claimWinnings: Allows participants to claim their rewards after settlement.

    function claimWinnings() external nonReentrant

  • getWinningsToClaim: Provides a view function for participants to check their potential winnings.

Oracle Contract

The Oracle Contract serves as a source of information to settle Boxes with announced Events’ outcomes. Once a Box is settled its Outcome may not be altered.

Key Functions

  • Constructor

    Constructor(address initialAI)

    • Purpose: Initializes the Oracle contract by setting up roles and permissions.

    • Parameters:

      • initialAI: The address granted the AI_ROLE, typically an AI or external system responsible for providing outcomes.

  • setResult

    function setResult(address boxId, bool _outcome) external onlyRole(OPERATOR_ROLE)

    • Purpose: Allows an AI to set the outcome of a prediction event (box).

    • Parameters:

      • boxId: The address of the Box contract whose outcome is being set.

      • _outcome: The boolean result of the prediction event (true or false).

    • Requirements:

      • Caller must have the AI_ROLE.

      • The result for the boxId must not have been settled previously.

  • getResult

    function getResult(address boxId) external view returns (bool isSettled, bool outcome)

    • Purpose: Retrieves the outcome of a prediction event for a given boxId.

    • Parameters:

      • boxId: The address of the Box contract whose outcome is being queried.

    • Returns:

      • isSettled: A boolean indicating whether the result has been set.

      • outcome: The boolean result of the prediction event.

Interactions with Other Contracts

  • Box Contracts

    • Outcome Retrieval: Box contracts call the getResult function to retrieve the outcome of their prediction event during the settlement process.

    • Result Dependency: The settlement logic within a Box contract depends on the outcome provided by the Oracle.

Autonomous Functionality

The WhaleInTheBox smart contracts are designed to operate autonomously, minimizing the need for external intervention after deployment. Key aspects include:

  • Automated Settlement: Boxes can be settled automatically through the Oracle without manual input.

  • Self-Contained Boxes: Each Box contract functions independently, ensuring that issues in one do not affect others.

PreviousKrillNextBoxes

Last updated