# Store Object - Make a Checkers Blockchain
Make sure you have all you need before proceeding with the exercise:
In this section, you will handle:
- The Stored Game object
- Protobuf objects
- Protobuf service interfaces
- Your first unit test
In the Ignite CLI introduction section you learned how to start a completely new blockchain. Now it is time to dive deeper and explore how you can create a blockchain to play a decentralized game of checkers.
A good start to developing a checkers blockchain is to define the ruleset of the game. There are many versions of the rules. Choose a very simple set of basic rules (opens new window) to avoid getting lost in the rules of checkers or the proper implementation of the board state.
Use a ready-made implementation (opens new window) with the additional rule that the board is 8x8 and played on black cells. This code will not need adjustments. Copy this rules file into a
rules folder inside your module. Change its package from
rules. You can do this by command-line:
Do not focus on the GUI, this procedure lays the foundation for an interface.
Now it is time to create the first object.
# The stored game object
Begin with the minimum game information needed to be stored:
- Red player. A string, the serialized address.
- Black player. A string, the serialized address.
- Game proper. A string, the game as it is serialized by the rules file.
- Player to play next. A string.
# How to store
After you know what to store, you have to decide how to store a game. This is important if you want your blockchain application to accommodate multiple simultaneous games. The game is identified by a unique ID.
How should you generate the ID? Players cannot choose it themselves, as this could lead to transactions failing because of an ID clash. You cannot rely on a large random number like a universally unique identifier (UUID), because transactions have to be verifiable in the future. It is better to have a counter incrementing on each new game. This is possible because the code execution happens in a single thread.
The counter must be kept in storage between transactions. Instead of a single counter, you can keep a unique object at a singular location, and easily add relevant elements to the object as needed in the future. Designate
idValue to the counter.
You can rely on Ignite CLI's assistance:
Call the object that contains the counter
NextGameand instruct Ignite CLI with
You must add
--no-message. If you omit it, Ignite CLI creates an
sdk.Msgand an associated service, whose purpose is to overwrite your
NextGame.IdValuemust be controlled/incremented by the application and not by a player sending a value of their own choosing. Ignite CLI still creates convenient getters.
You need a map because you're storing games by ID. Instruct Ignite CLI with
scaffold mapusing the
--no-messageprevents game objects from being created or overwritten with a simple
sdk.Msg. The application instead creates and updates the objects when receiving properly crafted messages like create game or play a move.
The command added new constants:
These constants are used as prefixes for the keys that can access the storage location of objects.
# Protobuf objects
Ignite CLI creates the Protobuf objects in the
proto directory before compiling them. The
NextGame object looks like this:
StoredGame object looks like this:
Both objects compile to:
They also compile to:
These are not the only created Protobuf objects. The genesis state is also defined in Protobuf:
This is compiled to:
You can find query objects as part of the boilerplate objects created by Ignite CLI. Ignite CLI creates the objects according to a model, but this does not prevent you from making changes later if you decide these queries are not needed:
The query objects for
StoredGame are more useful for your checkers game, and look like this:
# How Ignite CLI works
Ignite CLI puts the different Protobuf messages into different files depending on their use:
query.proto- for objects related to reading the state. Ignite CLI modifies this file as you add queries. This includes objects to query your stored elements (opens new window).
tx.proto- for objects that relate to updating the state. As you have only defined storage elements with
--no-message, it is empty for now. The file will be modified as you add transaction-related elements like the message to create a game.
genesis.proto- for the genesis. Ignite CLI modifies this file according to how your new storage elements evolve.
stored_game.proto- separate files created once, that remain untouched by Ignite CLI. You are free to modify them but be careful with numbering (opens new window).
Files updated by Ignite CLI include comments like:
Ignite CLI adds code right below the comments, which explains why the oldest lines appear lower than recent ones. Make sure to keep these comments where they are so that Ignite CLI knows where to inject code in the future. You could add your code above or below the comments.
Some files created by Ignite CLI can be updated, but you should not modify the Protobuf-compiled files
*.pb.go (opens new window) and
*.pb.gw.go (opens new window) as they are recreated on every re-run of
ignite generate proto-go or equivalent.
# Files to adjust
Ignite CLI creates files that you can and should update. For example, the default genesis values:
You can choose to start with no games or insert a number of games to start with. In either case, you must choose the first ID of the first game, which here is set at
1 by reusing the
# Protobuf service interfaces
In addition to created objects, Ignite CLI also creates services that declare and define how to access the newly-created storage objects. Ignite CLI introduces empty service interfaces that can be filled as you add objects and messages when scaffolding a brand new module.
In this case, Ignite CLI added to
service Query how to query for your objects:
Ignite CLI separates concerns into different files in the compilation of a service. Some should be edited and some should not. The following were prepared by Ignite CLI for your checkers game:
- The query parameters (opens new window), as well as how to serialize (opens new window) and make them conform to the right Protobuf
RequestQuery(opens new window) interface.
- The primary implementation of the gRPC service.
- The implementation of all the storage setters and getters (opens new window) as extra functions in the keeper.
- The implementation of the storage getters in the keeper as they come from the gRPC server (opens new window).
# Helper functions
Your stored game stores are only strings, but they represent
sdk.AccAddress or even a game from the
rules file. Therefore, you add helper functions to
StoredGame to do operations on them.
Get the game
Parse the game so that it can be played. The
Turnhas to be set by hand:
Introduce your own errors:
# Unit tests
Now that you have added some code on top of what Ignite CLI created for you, you should add unit tests. You will not add code to test the code generated by Ignite CLI, as your project is not yet ready to test the framework. However, Ignite CLI added some unit tests of its own. Run those for the keeper:
# Your first unit test
A good start is to test that the default genesis is created as expected. Beside
x/checkers/types/genesis.go, create a new
To run it, use
go test with the package name:
This should return something like:
Alternatively, call it from the folder itself:
You want your tests to pass when everything is okay, but you also want them to fail when something is wrong. Make sure your new test fails by changing
uint64(2). You should get the following:
This appears complex, but the significant aspect is this:
For expected and actual to make sense, you have to ensure that they are correctly placed in your call. When in doubt, go to the
require function definition:
# Debug your unit test
Your first unit test is a standard Go unit test. If you use an IDE like Visual Studio Code it is ready to assist run the test in debug mode. Next to the function name is a small green tick. If you hover below it, a faint red dot appears:
This red dot is a potential breakpoint. Add one on the
DefaultGenesis() line. The dot is now bright and stays there:
Right-click on the green tick, and choose Debug Test. If it asks you to install a package, accept. Eventually it stops at the breakpoint and displays the current variables and a panel for stepping actions:
If you are struggling with a test, create separate variables in order to inspect them in debug. From there, follow your regular step-by-step debugging process. If you are not familiar with debugging, this online tutorial (opens new window) will be helpful.
# More unit tests
With a simple yet successful unit test, you can add more consequential ones to test helper methods. Since you are going to repeat some actions, it is worth adding a reusable function:
Now you can test the function to get the creator's address. One test for the happy path, and another for the error:
Test that you can parse a game (opens new window), even if it has been tampered with (opens new window), except if the tamper is wrong (opens new window) or if the turn is wrongly saved (opens new window).
Interested in integration tests? Skip ahead to the section where you learn about them.
# Interact via the CLI
Ignite CLI created a set of files for you. It is time to see whether you can already interact with your new checkers blockchain.
Start the chain in its shell:
This ends with:
Check the values saved in
NextGame. Look at the relevant
client/clifile, which Ignite CLI created to find out what command is relevant. Here it is
query_next_game.go(opens new window). You can also ask the CLI:
And that is
show-next-game(opens new window):
This is as expected. No games have been created yet, so the game counter is still at
--outputflag allows you to get your results in a JSON format, which might be useful if you would like to use a script to parse the information. When you use the
--helpflag, you see which flags are available for a specific command:
Among the output, you see:
Now try again a bit differently:
This should print:
You can similarly confirm there are no stored games (opens new window):
This should print:
Remember how you wrote
--no-message? That was to not create messages or transactions, which would directly update your checkers storage. Soft-confirm there are no commands available:
# Next up
Want to continue developing your checkers blockchain? In the next section, you will learn all about introducing an
sdk.Msg to create a game.