Skip to main content

Bet contract: how it works

Introduction​

This article explains how contracts created from the blueprint 'Bet' — namely bet contracts — work. Understanding their functioning is essential for anyone implementing a use case with them.

warning

Currently, this blueprint is available for testing purposes only. It was conceived to demonstrate how blueprints function and provide insight into the design, implementation, and documentation processes for future blueprints.

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.

Key takeaway​

In this article, we provide the necessary knowledge to model a bet contract use case. Now, to design and implement your use case, see Bet blueprint — interface.

What's next?​