search

betBlox developers guide

Welcome to the developer documentation for betBlox the decentralized betting infrastucture protocol. betBlox allows anyone to build and run decentralised non-custodial onchain betting dapps and services This guide will help you understand the architecture, interact with the smart contracts, and build applications on top of the betBlox protocol. Additionally the guide covers the use of betBase community services like the betBase API, betBase oracle, betBlox subgraph and the bloxTester dev test tool.

hashtag
Introduction

betBlox is a decentralized protocol designed to facilitate decentralized fully onchain non-custodial peer-to-peer betting markets. It uses EVM smart contracts to ensure transparency, security, and trustless execution of bets and markets. The protocol implements a virtual Onchain Betting Market (OBM) that allows users to place bets onchain or to become market makers and create markets for other bettors.

hashtag
Protocol Architecture

The betBlox protocol is built on a modular architecture, separating concerns into distinct contracts for better maintainability and upgradability. The first version of betBlox implements greenBlox for Sports betting and simple predictions. Future versions will implement blue, purple and orangeBlox for a complete suite of betting products.

hashtag
Core Components

  1. BetHandler: The primary entry point for placing bets. It validates bet parameters and interacts with the MarketHandler to record bets.

  2. MarketHandler: Manages the lifecycle of betting markets. It handles liquidity, odds, and settlement logic.

  3. EventHandler: Acts as the source of truth for event data (e.g., sports match results). It tracks the state of events (Active, Playing, Completed) and ensures markets are settled correctly based on these states.

  4. MarketmakerBox (lite): The vault system where market makers deposit control their liquidity and earn fees.

  5. ParlayHandler: A specialized handler for parlay bets, coordinating across multiple markets and events.

  6. LockBox: The foundational contract for locking bets and ensuring secure deposit and withdrawal of funds.

hashtag
Interaction Flow

  1. Create a MarketMaker: Create a MarketMakerBox via the MarketMakerBoxFactory.

  2. Create a Market: A Market Maker creates a market via MarketHandler, specifying the event and odds. Liquidity is reserved from their MarketmakerBox.

  3. Place a Bet: A user calls addBet on BetHandler. The contract verifies the market and odds, transfers the user's stake, and records the bet.

  4. Resolve an Event: An Oracle or authorized entity updates the event state in EventHandler to "Completed" and provides the result.

  5. Settle a Market: MarketHandler uses the event result to determine winning outcomes. Note: Settlement is a permissionless action; once the event is completed, anyone (Market Maker, Bettor, or a third party) can call settleMarket to finalize the market.

  6. Claim Payouts: Winners can claim their payouts via payoutBet in BetHandler, which releases the funds from the bet-lockbox (LockBox) and the locked stakes.

hashtag
Smart Contract Reference

This section provides a detailed reference for the core smart contracts in the betBlox protocol.

hashtag
BetHandler.sol

Introduction: This contract handles the betting logic. It communicates with the MarketHandler to add bets to markets and manages the lifecycle of a bet.

External Functions:

  • setBetAgent(address inBetAgent): Sets a bet agent for the caller, allowing the agent to place bets on their behalf.

  • addBet(bytes32 marketHash, uint256 betAmount, uint256 odds, uint16 outcomeId): Adds a regular bet to a market on behalf of the caller.

  • agentBet(bytes32 marketHash, address bettor, uint256 betAmount, uint256 odds, uint16 outcomeId): Adds a bet to a market on behalf of another user (requires being their agent).

  • payoutBet(bytes32 betHash): Pays out a winning bet to the bettor. Settles the market first if necessary.

  • payoutBets(bytes32[] calldata betHashes): Pays out a list of winning bets. Efficient for batch processing.

View Only Functions:

  • token(): Returns the address of the betting token.

  • tokenDecimals(): Returns the number of precision decimals in the betting token.

hashtag
EventHandler.sol

Introduction: This contract manages events, including storing event data, tracking states (Active, Playing, Completed), and firing chain events. It acts as a central registry for events.

External Functions:

  • checkOrAddEvent(bytes32 eventHash, uint32 marketType, address marketmaker): Checks if an event exists for a new market, or adds it if it doesn't.

  • addEvent(bytes32 eventHash, uint32 eventType): Adds a marketmaker-controlled event.

  • setEventActive(bytes32 eventHash, uint32 eventType): Updates an event to the Active state (called by Oracle).

  • setEventPlaying(bytes32 eventHash): Updates an event to the Playing state.

  • completeEvent(bytes32 eventHash, EventResult calldata result): Updates an event to the Completed state and records the result.

  • cancelEvent(bytes32 eventHash): Cancels an event.

  • invalidateEvent(bytes32 eventHash): Invalidates an event.

View Only Functions:

  • getEventData(bytes32 eventHash): Returns the full data of an event.

  • getEventState(bytes32 eventHash): Returns the current state of an event.

  • getEventResult(bytes32 eventHash): Returns the result of a completed event.

  • isOracleEvent(bytes32 eventHash): Checks if an event is controlled by an Oracle.

  • owner(bytes32 eventHash): Returns the owner of an event.

  • isValidMarket(uint32 inEventType, uint32 inMarketType): Checks if a market type is valid for a given event type.

  • isValidResult(uint32 inEventType, EventResult calldata inResult): Checks if a result is valid for a given event type.

  • assertEventIsActive(bytes32 eventHash): Reverts if the event is not in the Active state.

  • assertEventIsActiveOrPlaying(bytes32 eventHash): Reverts if the event is not Active or Playing.

hashtag
MarketHandler.sol

Introduction: This contract handles markets, including storing market data, managing liquidity, and processing settlements. It interacts with EventHandler and BetHandler.

External Functions:

  • addMarket(...): Adds a new market with liquidity, odds, and other parameters.

  • addBet(BetData calldata bet): Adds a bet to a market (restricted to BETS_ROLE, i.e., BetHandler).

  • addLiquidity(bytes32 marketHash, uint256 inAmount): Adds additional liquidity to an existing market.

  • removeLiquidity(bytes32 marketHash, uint256 inAmount): Removes unused liquidity from a market.

  • setOdds(bytes32 marketHash, uint16 outcomeId, uint256 inOdds): Updates the odds for a specific outcome in a market.

  • settleMarket(bytes32 marketHash): Settles a market to prepare it for payouts.

  • payoutAll(BetSettleData[] calldata bets): Pays the marketmaker and all listed bettors (restricted to BETS_ROLE).

  • payoutMarketmaker(bytes32 marketHash): Pays the marketmaker of a market.

  • payoutBettor(BetSettleData calldata bet): Pays a specific bettor (restricted to BETS_ROLE).

  • setVIPGroup(bytes32 marketHash, uint8 inGroup): Changes the VIP group access for a market.

View Only Functions:

  • getMarketData(bytes32 marketHash): Returns the full data of a market.

  • getEventState(bytes32 marketHash): Returns the event state associated with a market.

  • getOwner(bytes32 marketHash): Returns the owner of a market.

  • hasOutcome(bytes32 marketHash, uint16 outcomeId): Checks if a specific outcome exists in a market.

  • getOutcome(bytes32 marketHash, uint16 outcomeId): Returns data for a specific outcome.

  • getProcessor(uint32 id): Returns the processor contract address for a market type.

  • isValidOutcome(uint32 inMarketType, uint16 inOutcomeId): Checks if an outcome ID is valid for a market type.

  • getWinningOutcome(...): Determines the winning outcome based on the event result.

  • isValidOffset(uint32 inMarketType, int32 inOffset): Checks if an offset value is valid for a market type.

  • getValidOutcomes(uint32 inMarketType): Returns all valid outcome IDs for a market type.

hashtag
LockBox.sol

Introduction: Simple contract for storing tokens in a locked state. It keeps a list of locked tokens and can own the locked tokens. It inherits from LockBoxAbstract and TokenValidator.

External Functions:

  • lockAmount(address owner, address token, uint256 amount): Increases the users locked amount for a token. (Restricted to LOCKBOX_ROLE)

  • unlockAmount(address owner, address token, uint256 amount): Decreases the users locked amount. (Restricted to LOCKBOX_ROLE)

  • unlockAmountTo(address owner, address to, address token, uint256 amount): Decreases an owners locked amount and sets allowance to another address. (Restricted to LOCKBOX_ROLE)

  • transferLockAmount(address owner, address receiver, address token, uint256 amount): Transfers a lock amount from one owner to another. (Restricted to LOCKBOX_ROLE)

View Only Functions:

  • getLockedAmount(address owner, address token): Returns the amount currently locked for a user.

  • hasLockedAmount(address owner, address token, uint256 amount): Checks if a user has at least the specified amount locked.

hashtag
MarketmakerBoxLite.sol

Introduction: A lightweight vault contract where marketmakers deposit tokens. It inherits from LockBoxAbstract to provide secure fund management without exposing raw lock/unlock functionality, ensuring all fund movements are accounted for by the protocol.

External Functions:

  • deposit(uint256 inAmount): Deposits tokens into the box.

  • withdraw(uint256 inAmount): Withdraws tokens from the box to the owner.

  • withdrawMax(): Withdraws all available (unlocked) tokens.

  • reserveForMarket(uint256 inAmount): Reserves tokens for a market (restricted to MARKETS_ROLE).

  • returnToOwner(uint256 inAmount): Returns tokens from a market back to the owner (restricted to MARKETS_ROLE).

  • grantVIP(address inAddress, uint8 inGroup): Grants a VIP role to an address.

  • revokeVIP(address inAddress, uint8 inGroup): Revokes a VIP role.

  • grantSigner(address inAddress): Grants a signer role.

  • revokeSigner(address inAddress): Revokes a signer role.

View Only Functions:

  • isVIP(address inAddress, uint8 inGroup): Checks if an address has a specific VIP role.

  • getOwner(): Returns the owner of the box.

  • getLockedAmount(address owner, address token): Returns the amount currently locked for a user.

  • hasLockedAmount(address owner, address token, uint256 amount): Checks if a user has at least the specified amount locked.

hashtag
MarketmakerFactory.sol

Introduction: A factory contract for deploying MarketmakerBoxLite contracts. It ensures that new boxes are correctly initialized and registered.

External Functions:

  • createMarketmakerBox(): Creates and deploys a new MarketmakerBoxLite for the caller.

  • createMarketmakerBoxForUser(address inOwner): Creates a box for a specific user (admin only).

View Only Functions:

  • getMarketmakerList(): Returns a list of all created marketmaker boxes.

  • isMarketmaker(address inMarketmaker): Checks if an address has created a marketmaker box.

hashtag
ParlayHandler.sol

Introduction: COMING SOON! Not deployed in current version of betBlox. This contract will handle parlay bets, which are combined bets on multiple outcomes. It manages the creation, settlement, and payout of parlays. Like MarketHandler, it relies on EventHandler for retrieving event status and results.

External Functions:

  • setMaxOutcomes(uint8): Sets the max number outcomes that can be combined when a bettor makes a parlay bet. (Restricted to OPERATION_ADMIN_ROLE).

  • setParlayAgent(address): Assigns an agent that is allowed to parlay bet for the bettor making the call.

  • addParlay(ParlayInput calldata, bytes calldata): The regular way to create a parlay bet.

  • agentParlay(ParlayInput calldata, bytes calldata): Adding a parlay bet as agent, on behalf of another bettor.

  • settleParlay(bytes32): Settles a parlay bet, when all corresponding events are settled. There are only 2 accounts involved in a parlay bet, an MM and a bettor, and both are automatically paid from the settle.

View Only Functions:

  • getMaxOutcomes(): Returns the max allowed outcomes to combine.

  • getParlayData(bytes32): Returns the full data of a parlay.

  • getEventStates(bytes32): Returns a list of the event states, one for each outcome in the parlay bet.

hashtag
AccessHandler.sol

Introduction: Not deployed as a separate contract, but inherited by all other contracts. This contract provides functionalty to restrict function calls by assigned roles and to Pause transactions entirely.

External Functions:

  • addAdmin(address): Add another super-admin. (Restricted to DEFAULT_ADMIN_ROLE).

  • removeAdmin(address): Remove a super-admin. (Restricted to DEFAULT_ADMIN_ROLE).

  • grantRole(bytes32 role, address account): Grant role to account. (Restricted to DEFAULT_ADMIN_ROLE).

  • revokeRole(bytes32 role, address account): Revoke role for account. (Restricted to DEFAULT_ADMIN_ROLE).

  • renounceRole(bytes32 role, address callerConfirmation): Lets a user revoke one of their own roles.

  • pause(): Pauses the contract. (Restricted to PAUSER_ROLE).

  • unpause(): Unpauses the contract. (Restricted to PAUSER_ROLE).

View Only Functions:

  • getRoleAdmin(bytes32 role): Returns the admin role that controls role (super-admin).

  • hasRole(bytes32 role, address account): Returns true if account is assigned role.

  • paused(): Returns true if the contract is paused.

hashtag
Role Access Control

The betBlox protocol uses a robust role-based access control system to secure sensitive operations. Roles are identified by calculating a keccak256 hash of the roles name.

hashtag
System Roles

  • DEFAULT_ADMIN_ROLE: The super-admin role. Admins can grant and revoke other roles, including adding other admins. This particular role hash is always the zero hex hash.

  • OPERATION_ADMIN_ROLE: Allows for operational tasks, such as creating MarketmakerBox contracts for users via the factory.

  • PAUSER_ROLE: Grants the ability to pause and unpause contracts. This is an emergency control mechanism to stop protocol activity in case of a critical issue.

hashtag
Functional Roles

  • MARKETS_ROLE: Assigned to MarketHandler and coming ParlayHandler. This role allows these contracts to reserve and return tokens in a MarketmakerBox when markets are created or settled.

  • BETS_ROLE: Assigned to BetHandler. This role authorizes the contract to call sensitive functions in MarketHandler, such as addBet and payoutBettor.

  • ORACLE_ROLE: Assigned to trusted oracle addresses. Oracles with this role can control the state and results of events they manage.

  • SIGNER_ROLE: Assigned to trusted signers within a MarketmakerBox. ParlayHandler will then check the assigned role by calling mmBox.hasRole(SIGNER_ROLE, [signer_address]). This is used to validate off-chain agreements, such as the terms of a parlay bet.

hashtag
Oracle Integration

Oracles play an important role in the betBlox ecosystem by bridging real-world data (sports results) to the blockchain. Markets can be either Controlled (Oracle-managed) or Non-Controlled (Market Maker-managed).

hashtag
Controlled Markets (Oracle Managed)

In a controlled market, the lifecycle of the underlying event is managed by an approved Oracle.

  1. Market Creation: A Market Maker creates a market linked to a specific eventHash.

  2. Initialization: When the first market is created for this event_hash, the event is created and the event state is set to Init.

  3. Activation: The Oracle server constantly monitors for markets in the Init state. If it recognizes the eventHash as one it tracks, it calls setEventActive on the EventHandler. This transitions the event to Active.

  4. Lifecycle Management: The Oracle updates the event state as the real-world event progresses (e.g., setting it to Playing when the match starts).

  5. Resolution: Once the event concludes, the Oracle calls completeEvent with the final result. This allows the MarketHandler to settle markets and enable payouts.

hashtag
Non-Controlled Markets (Market Maker Managed)

If a market is not set to be controlled by an Oracle, the responsibility for lifecycle management falls on the Market Maker.

  • The Market Maker must manually update the event state and provide the final result.

  • This requires trust in the Market Maker, as they have direct control over the outcome resolution.

hashtag
Market Components & Types

Markets in betBlox are structured around a few key components that define how bets are placed and settled.

hashtag
Market Components

A market consists of the following parameters:

  • eventHash: Identifies the corresponding event.

  • liquidity: Is the amount of tokens the marketmaker has provided (laid) on the market.

  • betVolume: Is the combined amount of tokens the bettors have bet (backed) on the market.

  • paid: Is the combined amount settled, to both marketmaker and bettors, ignoring fee details.

  • marketType: Is a 32 bit unsigned (nonzero) number that identifies the marketType.

  • b2MmFeePermille: Is a market specific win fee rate, the bettors will pay to the marketmaker.

  • owner: Is the wallet address of the marketmaker, that "owns" this market.

  • vipGroup: Is a number between 0 and 255, that limits the access to who can bet. 0 means no VIP limitations.

  • offset: Is a number value used for some market types like "totals-goals", "spread" etc., to define the handicap or total line (e.g. -1.5 goals).

  • settled: Is a boolean stating if the market has been settled (event results processed and payout ready).

  • mmPaid: Is a Boolean stating if the marketmaker is paid yet.

  • bettorsPaid: Is a Boolean stating if all bettors are paid yet.

  • outcomes: Is an array of outcome data, holding specific data for each bettable outcome (se below).

MarketOutcomeData has these parameters:

  • outcomeId: Is a number from 0 - 65535 to define the outcome, as seen from the bettor (e.g. Home Win, Away Win, Draw).

  • odds: Is the current odds as decimal-odds, offered by the marketMaker, to bet on this outcome (is stored with 10 precision digits in contract).

  • available: Is the amount of the marketmakers volume, that is still available to bettors (unmatched).

  • betAmount: Is the combined amount betted by bettors in this outcome.

  • betsWagered: Is the number of bets on this outcome by bettors.

  • betsSettled: Is the number of bets settled to the bettors combined, or to the mm if its a loss.

  • result: Is an enum that defines if the result is a Win, HalfWin, Loss etc., after the market is settled.

hashtag
Single Outcome vs. Book Markets

Markets can be configured in two primary ways regarding how they accept bets:

  1. Single Outcome Markets: These markets are set up for a specific outcome (e.g., "Home Win" only). The Market Maker backs only this specific result.

  2. Book Markets: These markets cover all possible outcomes for a specific market type (e.g., Home, Draw, and Away).

    • Balanced Book Mechanics: In a book market, the Market Maker can accept bets up to 100% of the assigned liquidity on each outcome side.

    • This allows for capital efficiency, as the liquidity is shared across the potential outcomes, assuming a balanced book where losing bets on one side fund the winning bets on the other.

Example: Balanced Moneyline Book

Scenario:

  • Market: Moneyline (Home vs. Away)

  • Liquidity Provided: 1000 USDC

  • Odds: Home @ 2.0, Away @ 2.0

Action 1: Bettor A bets 1000 USDC on Home.

  • Potential Payout: 2000 USDC (1000 Stake + 1000 Profit).

  • Liquidity Usage: The market reserves 1000 USDC of the MM's liquidity to cover the potential profit.

  • State: Market is fully exposed on the Home side (100% of liquidity used).

Action 2: Bettor B bets 1000 USDC on Away.

  • Potential Payout: 2000 USDC (1000 Stake + 1000 Profit).

  • Liquidity Usage: Because this is a book market, the MM can also use the same 1000 USDC liquidity to back this side. The losing side's stake will cover the winning side's profit.

  • State: Market is fully exposed on the Away side as well.

Resolution:

  • If Home Wins:

    • Bettor A receives 2000 USDC (1000 Stake + 1000 Profit).

    • The 1000 Profit comes from Bettor B's lost stake.

    • The MM retains their original 1000 USDC liquidity.

  • Result: The MM facilitated 2000 USDC in volume with only 1000 USDC in capital, effectively doubling their capital efficiency compared to a single-outcome market.

hashtag
Market Types and Parameters

The protocol supports various market types, each with specific behaviors:

Moneyline (1x2)

  • Description: The simplest bet on who will win the match.

  • Outcomes: Home Win, Away Win, Draw (for sports like Soccer).

  • Parameters:

    • kMarketType_MoneyLine: Standard 2-way or 3-way moneyline (Multiple Outcomes / Book Market).

    • kMarketType_MoneyLine_Home / _Away: Single outcome variants.

Spread (Asian Handicap)

  • Description: Bets on the margin of victory. One team receives a virtual head start (handicap).

  • Outcomes: Home Win, Away Win (after applying the spread).

  • Parameters:

    • Offset: The handicap value (e.g., -150 for -1.5 goals). Stored with 2 decimal precision.

    • kMarketType_Spread: Standard spread market.

Total (Over/Under)

  • Description: Bets on whether the total score will be over or under a specified amount.

  • Outcomes: Over, Under.

  • Parameters:

    • Offset: The total line (e.g., 250 for 2.5 goals). Stored with 2 decimal precision.

    • kMarketType_Total: Standard total market.

Fulltime Result

  • Description: Similar to Moneyline but specifically for full-time results in sports like Soccer.

  • Outcomes: Home Win, Draw, Away Win.

  • Parameters:

    • kMarketType_FulltimeResult: Standard 3-way market.

Prediction

  • Description: Generic prediction markets with a fixed number of outcomes.

  • Outcomes: 1 to 5 specific prediction outcomes. Note: Outcomes are mutually exclusive, meaning there can only be one winning outcome per market.

  • Parameters:

    • kMarketType_Prediction1 to kMarketType_Prediction5: Defines the number of possible outcomes.

hashtag
Fee Structure

betBlox implements a flexible fee structure that incentivizes Market Makers while ensuring protocol sustainability. Fees are calculated based on the net winnings (profit) and are deducted automatically during payouts.

hashtag
1. Market Maker Fees (Bettor Wins)

When a bettor wins a bet, the Market Maker who created the market can charge a fee on the bettor's profit.

  • Fee Type: b2MmFeePermille (Bettor to Market Maker Fee).

  • Payer: The winning Bettor.

  • Receiver: The Market Maker.

  • Calculation: Bettor Profit * b2MmFeePermille / 1000.

  • Purpose: Compensates the Market Maker for providing liquidity and taking on risk.

hashtag
2. Protocol Fees (Bettor Wins)

The protocol can also charge a fee on a bettor's profit.

  • Fee Type: feePermilleBettor.

  • Payer: The winning Bettor.

  • Receiver: The Protocol (Fee Receiver address).

  • Calculation: Bettor Profit * feePermilleBettor / 1000.

hashtag
3. Protocol Fees (Market Maker Wins)

When a Market Maker wins (i.e., the bettor loses), the protocol charges a fee on the Market Maker's profit. The rate depends on whether the market was controlled by an Oracle or managed manually by the Market Maker.

  • Fee Types:

    • feePermilleOracleMM: Fee rate for Oracle-managed events.

    • feePermilleOwnMM: Fee rate for Market Maker-managed events.

  • Payer: The Market Maker.

  • Receiver: The Protocol (Fee Receiver address).

  • Calculation: Market Maker Profit * Applicable Fee Rate / 1000.

  • Purpose: Ensures the protocol earns revenue from trading activity, regardless of who wins.

hashtag
Agent Betting & Automation

betBlox includes a native "Agent" system that allows users to delegate betting execution to another address (an "Agent") without giving up custody of their funds. This is designed specifically for automated trading, AI clients and bots, and copy-betting services.

hashtag
How it Works

The system separates the Authorization (User) from the Execution (Agent).

  1. Custody: The User (Bettor) keeps their funds in their own wallet. They do not deposit funds into a bot's wallet.

  2. Approval: The User approves the BetHandler contract to spend their betting tokens (standard ERC20 approval).

  3. Delegation: The User calls setBetAgent(agentAddress) on the BetHandler to authorize a specific address (e.g., a bot's hot wallet) to place bets on their behalf.

  4. Execution: The Agent calls agentBet(...) specifying the User's address as the bettor.

  5. Acceptance: The BetHandler verifies the relationship and pulls the bet amount directly from the User's wallet. Any winnings are sent back directly to the User.

hashtag
Use Case: AI Betting Bot

This feature enables a secure setup for AI-driven betting services:

  • User Setup:

    • User holds 1000 USDC in their cold/warm wallet.

    • User approves BetHandler for 1000 USDC.

    • User authorizes the AI Bot's address as their agent.

  • Bot Operation:

    • The AI Bot scans markets for value bets.

    • When a specific opportunity arises (e.g., "Home Win" odds > 2.5), the Bot triggers agentBet for the User.

    • The transaction gas is paid by the Bot, but the 100 USDC stake is pulled from the User.

  • Security:

    • The Bot cannot withdraw funds or transfer them elsewhere. It can only place bets into the protocol.

    • The User can revoke the Agent's access at any time by calling setBetAgent(address(0)).

hashtag
VIP System

betBlox includes a granular access control system known as the VIP System. This allows Market Makers to restrict who can place bets on their markets. This feature is powerful for creating private betting clubs, exclusive high-roller markets, or regulatory-compliant KYC pools.

hashtag
How it Works

Every market has a vipGroup parameter (uint8) set during creation or updated via setVIPGroup.

  • Group 0: Public Market. Anyone can bet. (Default)

  • Groups 1-254: VIP Markets. Only addresses with the specific VIP role can bet.

  • Group 255: Closed Market. No one can bet (effectively pausing the market).

hashtag
Managing Access

Access is managed at the MarketmakerBox level. A Market Maker grants VIP roles to specific user addresses. Once a user has a VIP role (e.g., Group 1), they can bet on any market created by that Market Maker that is set to vipGroup = 1.

  • Grant Access: mmBox.grantVIP(userAddress, groupNumber)

  • Revoke Access: mmBox.revokeVIP(userAddress, groupNumber)

hashtag
Use Cases

1. Private Betting Club

Scenario: You want to run a betting pool exclusively for your friends or colleagues.

  • Setup:

    1. Create a MarketmakerBox.

    2. Assign "Group 1" status to all your friends' addresses using grantVIP.

    3. When creating markets, set vipGroup to 1.

  • Result: Only your friends can place bets. Random users on the blockchain will be rejected by the smart contract if they try to bet.

2. Exclusive Low-Fee Markets

Scenario: You are a professional Market Maker and want to offer reduced fees (e.g., 0% fee) to your high-volume VIP clients, while charging standard fees to the public.

  • Setup:

    1. Define "Group 10" as your "VIP High Roller" tier.

    2. Grant "Group 10" status to your qualifying large-volume customers.

    3. Create two identical markets for the same event:

      • Market A (Public): vipGroup = 0, Fee = 2%.

      • Market B (VIP): vipGroup = 10, Fee = 0%.

  • Result: Your VIP clients can bet on Market B with zero fees, while the general public can only access Market A. This allows for tiered service levels on-chain.

hashtag
Token Gating

In addition to role-based access control, betBlox uses a Token Gating system. This feature allows the protocol to restrict access to specific functions based on whether the caller holds a minimum balance of BET tokens.

In betBlox v1.0 only MarketMaking is token gated. This means that only users with a minimum balance of BET tokens can create markets.

hashtag
Token Gated Functions

The following contracts and functions support token gating:

  • MarketHandler

    • addMarket: Creating a new market.

    • addLiquidity: Adding liquidity to an existing market.

    • removeLiquidity: Removing liquidity from a market.

  • EventHandler

    • addEvent: Creating a new market maker-controlled event.

  • MarketmakerBoxLite

    • deposit: Depositing funds into the market maker box.

    • withdraw: Withdrawing funds from the box.

    • withdrawMax: Withdrawing all available funds.

hashtag
Finding Data & Indexing

To interact with the protocol effectively (e.g., placing a bet on a specific market), you need to know the unique identifiers (hashes) for Events, Markets, and Bets. Since all core actions emit events on the blockchain, you can retrieve this data in several ways.

hashtag
1. Transaction Logs (Direct)

When you execute a transaction (like addMarket or addBet), the smart contract emits an event containing the generated hash.

  • Event Created: Emits EventAdded(bytes32 eventHash, ...)

  • Market Created: Emits MarketAdded(bytes32 marketHash, ...)

  • Bet Placed: Emits BetAdded(bytes32 betHash, ...)

You can parse these logs from the transaction receipt immediately after execution to store the hashes in your local database.

hashtag
2. Block Explorers (Etherscan)

If you need to find a hash manually or verify data, you can use a block explorer like Etherscanarrow-up-right.

Manual Lookup:

  1. Navigate to the relevant contract address (e.g., MarketHandler).

  2. Click on the "Events" tab.

  3. Filter by the event topic (e.g., MarketAdded).

  4. The marketHash will be listed in the data fields.

API Access: Etherscan also provides a robust API that allows you to programmatically fetch these logs instead of doing it manually. For high-volume applications, Etherscan offers a free and a paid version with significantly higher rate limits, allowing for almost unlimited calls.

hashtag
3. TheGraph

For building scalable applications (dApps) that need to display lists of markets or user betting history, querying the blockchain directly can be inefficient.

betBase provides a hosted Subgraph on TheGraph protocol. This indexes selected betBlox protocol events (those critical for process flow) and makes them queryable via GraphQL. Note that many other events are emitted for debugging and manual verification purposes but may not be indexed.

Anyone can host their own subgraph on TheGraph protocol.

Aggregated Entities: The betBase subgraph goes beyond simple event indexing. It uses special constructed entities that assemble data from multiple contract events into single, easy-to-query objects. For example, a Market entity in the subgraph might combine data from MarketAdded, MarketOutcomeUpdated, and MarketSettled events, giving you the complete state of a market in one request.

  • Query Markets: Get all active markets for a specific sport.

  • Query Bets: Get all bets placed by a specific user.

  • Query Stats: Get volume and liquidity data.

See the betblox subgraph reference guide below for detailed information.

hashtag
betBase API

betBase provides a REST API to facilitate easy integration of betBlox AIoracle real-world sports data with the betBlox protocol. While betBlox handles the on-chain execution of bets and markets, the betBase API is the source for finding meta data for upcoming sports events handled by the AIoracle and their corresponding on-chain identifiers (eventHash).

hashtag
Core Concepts

The Event Hash

The eventHash is the critical link between the off-chain world (a football match happening in real life) and the on-chain protocol.

  • On-Chain: contracts like MarketHandler and EventHandler require an eventHash to create markets or track status.

  • Off-Chain: You use the betBase API to discover upcoming games (e.g., "Liverpool vs. Arsenal") and retrieve their unique eventHash.

hashtag
API Endpoints

Base URL: https://api.betbase.xyz

1. Get Sport Event Count

Endpoint: /get_sport_event_count_betblox

Description: Returns the number of active sport events within each sport category.

2. Get Sports & Leagues

Endpoint: /get_sports_leagues_betblox

Description: Returns a list of all sports and their IDs and the Leagues and IDs for each sport.

3. Get Events

Endpoint: /get_events_betblox?sport_id={id}&league_id={id}

Description: Returns a full list of events for all sports that are within the time range set to 48 hours before start. The parameters sport_id and league_id are optional event filters.

4. Get Event Info

Endpoint: /get_event_info_betblox?event_hash[]={hash}

Description: Returns information about one or more event_hashes. Input is one or more event_hash[]= appended.

hashtag
Integration Guide

hashtag
Getting Started

To start developing with betBlox, you will need to interact with the deployed contracts on the relevant network.

  1. Connect to the Network: Ensure your application is connected to the correct blockchain network (Base).

  2. Get Contract Addresses: Obtain the addresses of the core contracts (BetHandler, MarketHandler, etc.) from the official deployment list.

  3. Approve Tokens: Before placing bets or creating markets, you must approve the relevant contracts to spend your tokens.

hashtag
Placing a Bet

To place a bet, follow these steps:

  1. Identify the marketHash of the market you wish to bet on.

  2. Call approve on the betting token contract to allow BetHandler to spend your bet amount.

  3. Call addBet on BetHandler with the marketHash, betAmount, odds, and outcomeId.

hashtag
Becoming a Market Maker

  1. Create a MarketmakerBox using the MarketmakerFactory.

  2. Deposit tokens into your MarketmakerBox.

  3. Call addMarket on MarketHandler to create a new market using your deposited liquidity.

hashtag
bloxTester Dev Tool

The betBlox protocol provides a bloxTester dev tool to help you test the betBlox protocol directly on Base Mainnet.

You can find the bloxTester dev tool here: betBlox bloxTesterarrow-up-right (URL placeholder).

hashtag
betBlox Subgraph reference guide

hashtag
1. Introduction

The betBlox subgraph indexes events, markets, bets, and parlays from the betBlox smart contracts on the Base blockchain. It provides a queryable interface to access historical and real-time data about betting activities.

hashtag
Key Features

  • Events & Markets: Query detailed information about sports events and their associated betting markets.

  • Betting History: Access individual bets and parlay bets linked to specific users and outcomes.

  • Settlement Data: Retrieve results and payout information for settled markets and bets.

hashtag
Endpoint

You can access the subgraph via The Graph Gateway. You will need an API key from the Subgraph Studioarrow-up-right.

https://gateway.thegraph.com/api/[YOUR_API_KEY]/subgraphs/id/7MsG12oTAxnvLz1KyRyLFNm5RjrkYyXeYN9ww6wWunEM

Data Structure Overview

The subgraph is built around a few core entities:

  • EventData: The root entity representing a sports match or game.

  • MarketData: A specific betting market (e.g., "Match Winner") within an event.

  • MarketOutcomeData: A specific outcome (e.g., "Home Team Wins") within a market.

  • BetData: An individual user's bet on an outcome.

  • ParlayData: A multi-leg bet combining outcomes from different events. [Coming Soon]

  • ParlayOutcomeData: The leg specific data holding market/event relevant info. [Coming Soon]

  • PayoutInfo: A common entity used to detail all payouts.

hashtag
2. Entities

Here are the primary entities available in the betBlox subgraph, based on the schema.

EventData

The EventData entity represents a unique sports event or match.

  • id: Bytes! - (32 bytes) EventHash, unique identifier for the event.

  • state: Int! - (uint8) Current state of the event (e.g., scheduled, active, completed).

  • owner: Bytes - (address, 20 bytes) Address of the event creator/manager.

  • eventType: BigInt - (uint32) Type of event (e.g. Basketball, Football).

  • firstMarketType: BigInt! - (uint32) Identifier for the first market type. The type is saved for the market that created the event, so it can be used to check type compatibility, when the event type is later set.

  • controlled: Boolean - After being set Active this indicates if the event is Oracle controlled.

  • result_homeScore: Int - (uint16) The fulltime score of the home team.

  • result_awayScore: Int - (uint16 The fulltime score of the away team.

  • result_prediction: Int - (uint8) The winning outcome of the prediction: 1-5.

  • result_desc: String - (string) Optional description of the result. Could explain an overtime result, difference from the fulltime result, for instance.

  • markets: [MarketData!]! - List of associated markets.

  • parlayOutcomes: [ParlayOutcomeData!]! - List of associated parlay outcomes.

  • blockNumber: BigInt! - (BigInt) Number/id of the last modification block.

  • blockTimestamp: BigInt! - (BigInt) Timestamp of the last modification block.

  • transactionHash: Bytes! - (32 bytes) Hash of the last transaction that modified the entity.

MarketData

The MarketData entity represents a betting market within an event (e.g., "Match Winner").

  • id: Bytes! - (32 bytes) MarketHash, unique identifier for the market.

  • eventHash: Bytes! - (32 bytes) EventHash, unique identifier for the parent event.

  • owner: Bytes - (address, 20 bytes) Address of the Marketmaker.

  • marketType: BigInt - (uint32) Type of market (e.g. 1x2, moneyline, total-goals).

  • b2MmFeePermille: Int - (uint16) Is the market specific win fee rate, the bettors will pay to the marketmaker.

  • vipGroup: Int - (uint8) Is the VIP group (0-255), that limits the access to who can bet. 0 means no VIP limitations, 255 means all are restricted so betting is paused and all other values are assignable to bettors.

  • offset: Int - (int32) Is a number value used for some market types like "totals-goals", "spread" etc., to define the handicap or total line (e.g. -1.5 goals).

  • liquidity: BigInt! - (BigInt) Total liquidity available in the market.

  • betVolume: BigInt! - (BigInt) Total volume of bets placed.

  • allPaidAmount: BigInt! - (BigInt) Full paid amount, is only set after full payout.

  • settled: Boolean! - Whether the market has been settled.

  • mmPayout: PayoutInfo - Detail amounts of the Marketmaker payout

  • outcomes: [MarketOutcomeData!]! - List of possible outcomes in this market.

  • bets: [BetData!]! - List of bets placed on this market.

  • event: EventData - Link to the parent event.

  • blockNumber: BigInt! - (BigInt) Number/id of the last modification block.

  • blockTimestamp: BigInt! - (BigInt) Timestamp of the last modification block.

  • transactionHash: Bytes! - (32 bytes) Hash of the last transaction that modified the entity.

MarketOutcomeData

The MarketOutcomeData entity represents a specific outcome within a market (e.g. "Home Win").

  • id: Bytes! - (32+4 bytes) Unique identifier (MarketHash + OutcomeId).

  • marketHash: Bytes! - (32 bytes) MarketHash, unique identifier for the parent market.

  • odds: BigInt! - (BigInt) Is the current odds as decimal-odds, offered by the marketMaker, to bet on this outcome (is stored with 10 precision digits, eg. 19000000000 for 1.900 decimal odds).

  • outcomeId: Int! - (uint16) Numeric ID of the outcome (e.g. 1 for "Home Win", 2 for "Away Win").

  • available: BigInt! - (BigInt) Is the liquidity from the Marketmaker, still available for new bets. Is updated for every bet and add/remove liquidity.

  • betVolume: BigInt! - (BigInt) Is the total amount of bets from bettors, on this outcome. Is updated for every bet.

  • outcomeResult: Int! - (uint8) Is an enum to express the result of this outcome: { Undefined, Win, HalfWin, Void, HalfLoss, Loss }.

  • market: MarketData! - Link to the parent market.

  • bets: [BetData!]! - List of bets placed on this specific outcome.

  • blockNumber: BigInt! - (BigInt) Number/id of the last modification block.

  • blockTimestamp: BigInt! - (BigInt) Timestamp of the last modification block.

  • transactionHash: Bytes! - (32 bytes) Hash of the last transaction that modified the entity.

BetData

The BetData entity represents a single bet placed by a user.

  • id: Bytes! - (32 bytes) BetHash, unique identifier for the bet.

  • marketHash: - Bytes! (32 bytes) MarketHash, unique identifier for the parent market.

  • bettor: Bytes! - (address) Address of the user who placed the bet.

  • outcomeId: Int! - (uint16) Numeric ID of the bet outcome (e.g. 1 for "Home Win", 2 for "Away Win").

  • betType: BigInt - (uint8) Enum to determine bet type (to recognize agent bets): { Undefined, Market, Agent }.

  • betAmount: BigInt! - (BigInt) Amount wagered.

  • odds: BigInt! - (BigInt) Is the odds as decimal-odds, at the time the bet was placed.

  • settled: Boolean! - Whether the bet has been settled.

  • payout: PayoutInfo - Details about the payout (if settled).

  • outcome: MarketOutcomeData! - The specific outcome chosen.

  • market: MarketData! - The parent market the bet was placed on.

  • blockNumber: BigInt! - (BigInt) Number/id of the last modification block.

  • blockTimestamp: BigInt! - (BigInt) Timestamp of the last modification block.

  • transactionHash: Bytes! - (32 bytes) Hash of the last transaction that modified the entity.

ParlayData

The ParlayData entity represents a multi-leg bet (parlay).

  • id: Bytes! (32 bytes) ParlayHash, unique identifier for the parlay.

  • liquidity: BigInt! - (BigInt) Liquidity to the parlay by the Marketmaker.

  • betAmount: BigInt! - (BigInt) Amount wagered by the bettor.

  • odds: BigInt! - Combined odds for the parlay.

  • parlayType: BigInt - (uint8) Enum to determine parlay type (to recognize agent parlays): { Undefined, Parlay, Agent }.

  • b2MmFeePermille: BigInt! - (BigInt) Is a paraly specific win fee rate, the bettors will pay to the marketmaker.

  • mm: Bytes - (address, 20 bytes) Address of the Marketmaker.

  • bettor: Bytes! - (address) - Address of the user who placed the parlay bet.

  • settled: Boolean! - Whether the parlay has been settled.

  • parlayResult: Int! - (uint8) Is an enum to express the result of this parlay, as seen from the bettor: { Undefined, Win, Void, Loss }.

  • outcomes: [ParlayOutcomeData!]! - List of individual legs in the parlay.

  • bettorPayout: PayoutInfo - Detail amounts of the bettor payout.

  • mmPayout: PayoutInfo - Detail amounts of the Marketmaker payout.

  • blockNumber: BigInt! - (BigInt) Number/id of the last modification block.

  • blockTimestamp: BigInt! - (BigInt) Timestamp of the last modification block.

  • transactionHash: Bytes! - (32 bytes) Hash of the last transaction that modified the entity.

ParlayOutcomeData

The ParlayOutcomeData entity represents a single leg within a parlay bet.

  • id: Bytes! - (32+4 bytes) Unique identifier (txHash + logIndex). This is never updated, and does not need be easily recreated.

  • parlayHash: Bytes! (32 bytes) ParlayHash, unique identifier for the parent parlay.

  • eventHash: Bytes! - (32 bytes) EventHash, unique identifier for corresponding event.

  • marketType: BigInt - (uint32) Type of market (e.g. 1x2, moneyline, total-goals).

  • offset: Int - (int32) Is a number value used for some market types like "totals-goals", "spread" etc., to define the handicap or total line (e.g. -1.5 goals).

  • outcomeId: Int! - (uint16) The specific outcome selected.

  • parlay: ParlayData! - Link to the parent parlay bet.

  • event: EventData! - Link to the event associated with this leg.

  • blockNumber: BigInt! - (BigInt) Number/id of the last modification block.

  • blockTimestamp: BigInt! - (BigInt) Timestamp of the last modification block.

  • transactionHash: Bytes! - (32 bytes) Hash of the last transaction that modified the entity.

PayoutInfo

The PayoutInfo entity contains detailed payout information for settled bets and markets.

  • amountPaid: BigInt! - (BigInt) Amount paid out to the bettor/Marketmaker.

  • amountWon: BigInt! - (BigInt) Amount won by the receiver (profit).

  • amountReturned: BigInt! - (BigInt) Amount returned to the receiver (fee free amount).

  • amountFeesToMm: BigInt! - (BigInt) Fees paid to the Marketmaker.

  • amountFeesProto: BigInt! - (BigInt) Fees paid to the protocol.

hashtag
3. Querying Guide

This guide explains how to construct queries to fetch data from the betBlox subgraph.

Basic Query Structure

GraphQL queries allow you to fetch exactly the data you need.

Filtering

By ID

Fetch a specific event by its ID (Hash).

By State

Fetch only active events (e.g., state 1).

By Owner

Fetch events created by a specific address.

Pagination

Use first and skip to paginate through results.

Sorting

Use orderBy and orderDirection to sort results.

Nested Queries (Relationships)

The power of the subgraph lies in traversing relationships.

Events with Markets and Outcomes

Fetch events along with their markets and the outcomes for those markets.

Bets within a Market

Fetch the last 10 bets placed on a specific market.

hashtag
4. TypeScript Examples

Here are some practical examples of how to query the betBlox subgraph using TypeScript. We'll use graphql-request for simplicity, but you can use Apollo Client or fetch as well.

Setup

First, install the necessary package:

Example 1: Fetching Active Events with Markets

This example fetches all active events (state 1) along with their markets and outcomes.

Example 2: Fetching Recent Bets

Fetch the most recent bets placed in the system.

Example 3: Market Liquidity Analysis

Analyze liquidity and bet volume for specific markets.

hashtag
Parlay Betting Guide

Parlay Betting is a special case of betting in the protocol which requires off-chain interaction with a market maker server process to approve a combined bet of onchain markets. This guide explains the technical workflow of the ParlayHandler.sol smart contract, detailing how parlay bets are constructed, placed on-chain, and settled.

hashtag
1. The Parlay Input Data

A parlay bet is defined by the ParlayInput struct, which serves as the signed agreement between the Bettor (Client) and the Market Maker (Server).

Data Structure

The ParlayInput contains:

  • Participants: bettor (User address) and mm (Market Maker address).

  • Bet Terms:

    • betAmount: The user's stake.

    • liquidity: The amount the Market Maker is risking (the payout).

    • odds: The combined decimal odds for the parlay.

    • b2MmFeePermille: The fee rate paid to the MM on a win.

  • Outcomes: An array of selected predictions (outcomeId, marketType, eventHash) that must all occur.

The "Optimistic" Flow

  1. Client: Constructs the proposed bet (outcomes, stake).

  2. Server (MM): The market maker has assigned the server, via its public key, a parlay signer role in his marketMaker box. The server Validates the risk/odds off-chain. If accepted, the MM server process signs a hash of the ParlayInput with its private key.

  3. Client: Submit the ParlayInput data + the MM's server signature to the blockchain.

hashtag
2. On-Chain Placement (addParlay)

When the client calls addParlay(), the smart contract performs strict validation before locking funds.

Verification Steps

  1. Signature Check: The contract hashes the input data and uses ECDSA.recover to verify that the signature belongs to the Market Maker server. This ensures the terms haven't been tampered with.

  2. Validation:

    • Amounts: Checks if betAmount and liquidity align with the provided odds.

    • Uniqueness: Checks that the same event isn't used twice in one parlay.

    • Leg Validity: Verifies that every eventHash exists and the marketType/outcomeId are valid valid options.

    • Authorization: Checks if the bettor has approved the contract to spend their tokens.

Fund Locking

If valid, the contract:

  1. Transfers the betAmount from the Bettor.

  2. Reserves the liquidity from the Market Maker's vault (MarketMakerBox).

  3. Locks both sums into the BetBox (a secure LockBox contract) under the specific parlayHash.

hashtag
3. Settlement & Resolution (settleParlay)

Once the real-world events have concluded, the settleParlay function resolves the bet.

The Logic

The contract iterates through every single outcome in the parlay and checks its status via the EventHandler and MarketHandler.

  • Winning a Leg: An outcome is only a "Win" if the event is completed (Active state removed) and the resulting outcome matches the user's prediction.

  • Losing a Leg: If the prediction is wrong.

  • Void/Canceled Events: If an event is canceled or a market is voided.

The "All-or-Nothing" Rule

Crucially, this contract implements a strict All-or-Nothing rule:

  • WIN: Every single outcome must result in a Win.

  • LOSS: If ANY outcome is a Loss, OR matches are Canceled or Void, the entire parlay is marked as a LOSS.

Note: Unlike some traditional bookmakers that might remove a voided leg and reduce the odds, this contract treats a Void/Canceled leg as a failure of the parlay condition, resulting in a loss for the bettor.

Payout

  • If Parlay Wins:

    • Bettor receives: Their original betAmount + the MM's liquidity.

    • (Fees are deducted from the winnings).

  • If Parlay Loses:

    • Market Maker receives: Their reserved liquidity (unlocked) + the Bettor's betAmount (profit).

    • (Fees are deducted from the profit).

Last updated