# Store Object
Make sure you have all you need before proceeding with the exercise:
- You understand the concepts of accounts, Protobuf, and multistore.
- Go is installed.
- You have the bare blockchain scaffold codebase with a single module named
checkers. If not, follow the previous steps or check out the relevant version (opens new window).
- You have the
checkers_iDocker image if you work with Docker. If not, follow the previous steps.
In this section, you will handle:
- The Stored Game object
- Protobuf objects
- Protobuf service interfaces
- Your first unit test
- Interactions via the command-line
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.
# Some initial thoughts
As you are face-to-face with the proverbial blank page: where do you start?
A good place to start with is thinking about the objects you keep in storage. A game, obviously... but what does any game have to keep in storage?
Questions to ask that could influence your design include, but are not limited to:
- What is the lifecycle of a game?
- How are participants selected to be in a game?
- What fields make it possible to play across a span of time and transactions?
- What fields make it possible to differentiate between different games?
- How do you ensure safety against malice, sabotage, or even simple errors?
- What limitations does your design intentionally impose on participants?
- What limitations does your design unintentionally impose on participants?
After thinking about what goes into each individual game, you should consider the demands of the wider system. In general terms, before you think about the commands that achieve what you seek, ask:
- How do you lay games in storage?
- How do you save and retrieve games?
The goal here is not to finalize every conceivable game feature immediately. For instance, handling wagers or leaderboards can be left for another time. But there should be a basic game design good enough to accommodate future improvements.
# Code needs
Do not dive headlong into coding the rules of checkers in Go - examples will already exist which you can put to use. Your job is to make a blockchain that just happens to enable the game of checkers.
With that in mind:
- What Ignite CLI commands will get you a long way when it comes to implementation?
- How do you adjust what Ignite CLI created for you?
- How would you unit-test your modest additions?
- How would you use Ignite CLI to locally run a one-node blockchain and interact with it via the CLI to see what you get?
Run the commands, make the adjustments, and run some tests regarding game storage. Do not go into deeper issues like messages and transactions yet.
# Defining the rule set
A good start to developing a checkers blockchain is to define the rule set 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, is played on black cells, and black plays first. 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:
- Black player. A string, the serialized address.
- Red player. A string, the serialized address.
- Board proper. A string, the board as it is serialized by the rules file.
- Player to play next. A string, specifying whose turn it is.
When you save strings, it makes it easier to understand what comes straight out of storage, but at the expense of storage space. As an advanced consideration, you could store the same information in binary.
# 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? If you let players choose it themselves, 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. Verifiable means that nodes verifying the block need to arrive at the same conclusion. However, the
new UUID() command is not deterministic. In this context, 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 in storage, you can keep the counter in a unique object at a singular storage location, and easily add relevant elements to the object as needed in the future. Name the counter as
nextId and its container as
As for the game type, you can name it as
You can rely on Ignite CLI's assistance for both the counter and the game:
For the counter and its container, you instruct Ignite CLI with
In this command:
nextIdis explicitly made to be a
uint. If you left it to Ignite's default, it would be a
- You must add
--no-message. If you omit it, Ignite CLI creates an
sdk.Msgand an associated service whose purpose is to overwrite your
SystemInfoobject. However, your
SystemInfo.NextIdmust be controlled/incremented by the application and not by a player sending a value of their own choosing. Ignite CLI still creates convenient getters.
For the game type, because you are storing games by ID, you need a map. Instruct Ignite CLI with
scaffold mapusing the
In this command:
redare by default strings, so there is no need to be explicit with for instance
indexis the id field picked, and anyway is the default name when scaffolding a map.
idcannot be chosen when scaffolding with Ignite.
--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.
Why have the game
index be a string when it is created out of
nextId, a number?
The fact that the underlying value is parseable to a number is an artefact of its creation, and not a necessity:
- By default, any object stored in a map has a string as its key, so you might as well stay within that standard.
- At no other point in the code is there an embedded assumption that the game index is a number.
Looking ahead, you should keep your data structure versatile.
# Looking around
The command added new constants:
These constants are used as prefixes for the keys that can access the storage location of objects.
In the case of games, the store model lets you narrow the search. For instance:
This gets the store to access any game if you have its index:
# Protobuf objects
Ignite CLI creates the Protobuf objects in the
proto directory before compiling them. The
SystemInfo object looks like this:
StoredGame object looks like this:
Both objects compile to:
At this point, note that
StoredGame do not have a field named creator. That is because they were created with the
--no-message flag. If you had omitted this flag, the message creator would always be saved into the object's creator. Like so:
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(opens new window) - for objects related to reading the state. Ignite CLI modifies this file whenever you instruct it to add queries. This includes objects to query your stored elements (opens new window).
tx.proto(opens new window) - 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(opens new window) - for the genesis. Ignite CLI modifies this file according to how your new storage elements evolve.
system_info.proto(opens new window) and
stored_game.proto(opens new window) - separate files created once, that will remain untouched by Ignite CLI. You are free to modify them but be careful with field numbering (opens new window).
Files updated by Ignite CLI include comments like:
Ignite CLI adds code right below the comments, which explains why at times 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 start as:
This is not correct. Your chain needs to start with an initial system info. This raises the point that the genesis'
SystemInfo should in fact never be null (opens new window). You can enforce that in
After compilation, this
nullable = false flag changes the
SystemInfo type in genesis from a pointer to a straight value. Make sure you recompile:
Then set a default value for
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 future created game, which here is set at
1 by reusing the
Do not forget to fix the other compilation errors (opens new window) due to the change of type.
As you can see, it is possible to adjust what Ignite CLI created.
# 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).
# Additional helper functions
Your stored game's
red fields are only strings, but they represent
sdk.AccAddress or even a game from the
rules file. Therefore, add helper functions to
StoredGame to facilitate operations on them. Create a new file
Get the game's black player:
Note how it introduces a new error
ErrInvalidBlack, which you define shortly. Do the same for the red (opens new window) player.
Parse the game so that it can be played. The
Turnhas to be set by hand:
Add a function that checks a game's validity:
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:
It should pass and return something like:
# Your first unit test
A good start is to test that the default genesis is created as expected. Ignite already created a unit test for the genesis in
x/checkers/types/genesis_test.go (opens new window). It runs simple validity tests on different genesis examples.
Take your time to understand how it works, as this testing pattern is reused elsewhere. Three cases (opens new window) are tested: case 1 (opens new window), case 2 (opens new window), and case 3 (opens new window). In each case, there is a made-up genesis object (opens new window), an expected validity result (opens new window), and some text (opens new window) to help the reader make sense of it. This array of cases (opens new window) is then run through the test proper (opens new window).
The unit test you add is more modest. Your test checks that the starting id on a default genesis is
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 temporarily 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 and have Go installed locally, it is ready to assist you with running the test in debug mode. Next to the function name is a small green tick or arrow. If you hover below it, a faint red dot appears:
This red dot is a potential breakpoint. Add one on the
types.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 your helper methods.
First, create a file that declares some constants that you will reuse throughout:
Create a new file
x/checkers/types/full_game_test.go and declare it in
package types_test (opens new window). Since you are going to repeat some actions, it is worth adding a reusable function:
Now you can test the function to get the black player's address. One test for the happy path, and another for the error:
You can do the same for
Red (opens new window).
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).
Also make sure that a default test created by Ignite CLI is correct in using the default values of
SystemInfo instead of erasing them:
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 and holds with:
Check the values saved in
SystemInfo. Look at the relevant
client/clifile, which Ignite CLI created to find out what command is relevant. Here it is
query_system_info.go(opens new window). You can also ask the CLI:
Which returns something like:
Therefore, you call it:
This is as expected. No games have been created yet, so the game counter is still at
You may encounter an error like the following:
This indicates that you likely have not configured Go correctly. Refer back to
GOPATHin our Go introduction.
--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:
To summarize, this section has explored:
- How to begin creating an original blockchain application, in this case a checkers game, identifying and prioritizing the basic core game features to build a foundation for future improvements.
- How to define a checkers rule set by searching for and obtaining an existing implementation, rather than needlessly duplicating complex coding work.
- The minimum game information it is necessary to store, and how to store it making use of Ignite CLI.
- The Protobuf objects created by Ignite CLI, which locates objects in different files depending on their use and updates them to include informative comments indicating where code has been added.
- The files created by Ignite CLI which you can and should update, for example by setting the default genesis values.
- The Protobuf services and service interfaces created by Ignite CLI that you will fill with objects and messages when scaffolding a new module.
- How to add helper functions which you can add to perform operations on the strings that represent your stored games, such as getting the game creator and players and introducing your own errors.
- How to add, run, and debug unit tests to check the functionality of your code.
- How to use Ignite CLI to confirm that you can interact with your new checkers blockchain.