Introduction to the XO Transaction Family¶
What is XO?¶
XO is an example transaction family contained within the Sawtooth SDK. It is an implementation of the popular game Tic-tac-toe (otherwise known as Noughts and Crosses or X’s and O’s).
X’s and O’s-style games have been played across the world for many centuries. The origin of this type of game is unclear; however, some historians believe that the first version of Tic-tac-toe may have originated in ancient Egypt. Others believe that the modern Tic-tac-toe is an evolution of a game known as Terni Lapilli, which was popular within the Roman Empire.
Tic-tac-toe also has historical significance within the field of Computer Science. In 1952, it became the basis of one of the first-ever video games when OXO was developed by Alexander S. Douglas at the University of Cambridge. More information regarding the origins and properties of Tic-tac-toe can be found here.
XO was chosen as an example transaction family for Sawtooth due to its simplicity, global player base, and straightforward implementation as a computer program. This example transaction family demonstrates the functionality of Sawtooth, and the code that implements it serves as a reference for building other transaction processors.
How to Play XO¶
Tic-tac-toe is a two-player game in which players take turns marking spaces on a 3x3 grid. Conventionally, player one marks spaces with an ‘X’ and player two marks spaces with an ‘O’; and player one always takes the first turn.
A player wins the game by marking 3 spaces in a horizontal, vertical, or diagonal row. If all 9 spaces on the grid have been marked but no player has achieved a winning board position, the game is considered a draw.
Playing XO Using the Command-line Interface¶
A command-line interface is provided for playing XO which handles the construction and submission of transactions. Instructions on how to use the CLI are detailed below:
Start up a validator, XO transaction processor, and the REST API. For more information on configuring and running Sawtooth components, see Installing and Running Sawtooth.
A user creates a new game using the
xo create [name] command.
- The name argument is the identifier for the new game to be created.
Players take turns using the
xo take [name] [space] command to mark spaces on
- The name argument is the identifier for an existing game.
- The space argument is the space that is to be marked, which is an integer in the range of 1 through 9.
The first player to issue an
xo take command to a newly created game is
recorded by their username as player one. The second player to issue a
command is recorded by their username as player two.
xo create and
xo take each take
--key-dir arguments. These are used to locate the user’s private
key-dir defaults to
username defaults to the name of the OS
xo commands also support
but these options are not used in this example.
Each time a user attempts to take a space, the transaction processor will verify that their username matches the name of the player whose turn it is. This ensures that no player is able to mark a space out of turn.
The XO transaction processor will scan for winning or draw board conditions after
each turn. If either condition occurs, further
take actions on the finished game
will not be allowed.
Either user can use the
xo reset command to delete their local XO data.
This includes the saved URL and username.
Viewing the Game State¶
The XO CLI also supports commands to view the state of ongoing or finished games.
These commands are
xo show [game] and
xo show [game]shows the board of a specified game, as well as data about the players and game state.
xo listshows a list of all ongoing and finished games.
The XO client optionally supports authentication. If the REST API
is connected to an authentication proxy, you can point the XO
client at it with the
--url argument. You must enter your
authentication information using the
--auth-user [user] and
--auth-password [password] options for each XO command.
Note that the value of the
--auth-user argument is not the
same username that is entered with the
Playing XO with the XO Client (Example)¶
Now that we have gone through the basics of the XO transaction processor, we are ready to play a game. The steps below show you how to set up and play a game using the XO CLI.
Start the Necessary Components¶
To play XO, ensure that the following components are running and connected:
- At least one validator
- An XO family transaction processor
- The REST API
Create keys for two players to play the game:
$ sawtooth keygen jack $ sawtooth keygen jill
The command produces output similar to the following for both players:
writing file: /home/ubuntu/.sawtooth/keys/jack.priv writing file: /home/ubuntu/.sawtooth/keys/jack.addr writing file: /home/ubuntu/.sawtooth/keys/jill.priv writing file: /home/ubuntu/.sawtooth/keys/jill.addr
Create a Game¶
Create a game with the following command:
$ xo create game --username jack
To see list of the created games, enter the following command:
$ xo list
The command outputs a list of the games that have been created:
GAME PLAYER 1 PLAYER 2 BOARD STATE game --------- P1-NEXT
Take a Space as Player One¶
Start playing by taking a space as the first player, “jack”:
$ xo take game 5 --username jack
The board spaces are numbered from 1 to 9. The upper-left corner is number 1, and the lower right corner is number 9.
Take a Space as Player Two¶
Now take a space on the board as player two:
$ xo take game 1 --username jill
Show the Current State of the Game Board¶
Whenever you want to see the current state of the game board, enter the following command:
$ xo show game
You will see the current state of the board displayed:
GAME: : game PLAYER 1 : 02403a PLAYER 2 : 03729b STATE : P1-NEXT O | | ---|---|--- | X | ---|---|--- | |
Continue the Game¶
You can continue the game until one of the players wins, or the game ends in a draw:
$ xo show game GAME: : game PLAYER 1 : 02403a PLAYER 2 : 03729b STATE : TIE O | X | O ---|---|--- X | X | O ---|---|--- X | O | X