Skip to main content

Bet blueprint

Introduction​

This article presents the documentation for the sample blueprint 'Bet'. We will cover:

  • which use cases can be modeled using the blueprint 'Bet';
  • the terminology to be employed in the context of bet contracts;
  • how to use it;
  • how it works; and
  • the specifications for modeling a use case with this blueprint.
warning

This blueprint is available only as an example. It was conceived to demonstrate how blueprints function and provide insight into the design, implementation, and documentation processes for future blueprints.

Use cases​

This blueprint was conceived to implement bet contracts for the following use cases:

  • Skill-based games
  • Gambling
  • Prediction markets

Skill-based games are those that require skill, strategy, or knowledge to play and succeed, such as sports, esports, tabletop games (chess, etc.), etc. Gambling are those games based purely on luck or chance. Prediction markets are speculative financial markets where participants trade contracts based on the outcome likelihood of specific events, harnessing the "wisdom of the crowd" to generate predictions.

Terminology​

Each blueprint has its own terminology. In the context of blueprint 'Bet', we will use the following terms:

  • Bet: an agreement among multiple parties, where each party wagers on a different result for a future event, with the intention of winning additional value from the opposing party(ies) if their prediction is correct.
  • Bettor: someone who places a bet.
  • Wager: the amount of assets of a bet.
  • Result: the outcome of the event.
  • Betting option: a bet opportunity available for bettors, related to a specific future event.
  • Betting event: the event of a betting option.
  • Bookmaker: someone who creates betting options.
  • Place a bet: the act of a bettor, of commiting a wager and a result prediction to a betting option.
  • Handle: the collective amount of assets wagered by all bettors.
  • Commission: fee that the bookmaker takes on bets.
  • Winning bet: a bet that correctly predicted the result of the betting event.
  • Winning bettor: a bettor who placed a winning bet.
  • Winnings: the amount of assets earned by bettors who correctly predicted the result of a betting event (including the original wager plus profit).
  • Betting platform: an online platform that provides the infrastructure and services for customers to engage in betting activities. Also, it may serve as an intermediary among bettors and bookmakers.

Actors​

There are three different actors that interact with a bet contract:

  • bookmaker;
  • bettors; and
  • oracle.

Bookmaker​

Bookmaker is the one who creates a bet contract for a given event, and once doing it, establishes the terms of the contract.

Bettors​

Bettors are the ones who place bets on the result of the event to which the bet contract refers.

Oracle​

A bet contract has one and only one oracle. This oracle is responsible for providing the contract the result of the betting event.

Life cycle​

The following diagram illustrates the life cycle of a bet contract:

Life cycle of a bet contract

Credits: Bookmaker icon created by Freepik - Flaticon; Bettor icon created by Smashicons - Flaticon; Oracle icon created by Becris - Flaticon; Winning bettor icon created by Freepik - Flaticon; and Hathor users icon created by SBTS from the Noun Project.

Different contract execution actions take place in different phases of its life cycle. The life cycle of a bet contract has three phases:

  • Bets
  • Event
  • Winnings

Bets phase​

This phase is when bettors place their bets. It begins once the bookmaker successfully creates a new contract. It does it submitting a nano contract transaction calling the method initialize. Once the contract is created until the end of the phase, bettors can place their bets. A bettor can place as many bets they wish, each with a different wager. They do it submitting a nano contract transaction calling the method bet. This phase ends when the date and hour specified by the attribute date_last_bet is reached. Thereafter, the contract will not accept new bets.

Event phase​

The event phase is when the contract's betting event takes place. This phase begins from the date and time specified by attribute date_last_bet and lasts until the oracle sets the final_result attribute, with the result of the betting event. Indeed, the only contract execution that will succeed in this phase, is the set of the result, done by the oracle. It does it submitting a nano contract transaction calling the set_result method.

Winnings phase​

The third and last phase is when winning bettors can withdraw their winnings. This phase begins as soon as the oracle set the result of the betting event, and lasts indefinitely — as long as Hathor Network runs. A winning bettor can withdraw to any address — not necessarily their own — any fraction of their winnings using any number of transactions. They do it submitting a nano contract transaction calling the method withdraw.

Further considerations​

Note that the state of the contract does not cover all the information that describes a betting option. For example, there is no attribute to describe the betting event. Therefore, bookmakers must communicate these informations to bettors in an off-chain manner.

One such piece of information concerns which results are liable to occur in the betting event, and what string formats these results must have to be eligible for a winnings. As already explained, a bet contract will accept as valid any bet that contains a string as an argument. There is no format validation for this string. However, only strings that perfectly match the final_result attribute will be considered as winning bets.

Thus, it is necessary for the bookmaker to agree with bettors and oracle about the set of possible event results as well as their formatting. The bookmaker can establish a betting option with a finite number of results, and in this case provide the oracle and the bettors with a list of strings that can be used to place a bet, and to set final_result. For example, for a UFC fight, the bookmaker may create a contract, modeling a betting option, in which there are only two possible results: victory for fighter 1, or victory for fighter 2. In this case, the bookmaker specifies the following list of strings:

  • fighter_1
  • fighter_2

Or, the bookmaker can specify a betting option in which there is an infinite number of possible results. For example, in a football match, the score could theoretically be any combination of two non-negative integers. In this case, instead of specifying a list of strings, the bookmaker specifies a regular expression, such as: <score_team_1>x<score_team_2>, in which <score_team_1> and <score_team_2> are non-negative integers indicating the goals of teams 1 and 2 respectively.

Therefore, the bookmaker should work in tandem with the oracle to provide to bettors guidance about how to place their bets correctly — i.e., with scores with the right string format.