Filters

# Make Sure a Player Can Reject a Game

Before proceeding, make sure you have all you need:

In this section, you will:

  • Add a new protocol rule.
  • Define custom errors.
  • Add a message handler.
  • Extend unit tests.

Your blockchain can now create and play games, and inform the outside world about the process. It would be good to add a way for players to back out of games they do not want to play. What do you need to make this possible?

# Some initial thoughts

Ask yourself:

  • What goes into the message?
  • How do you sanitize the inputs?
  • How do you unequivocally identify games?
  • What conditions have to be satisfied to reject a game?
  • How do you report back errors?
  • What event should you emit?
  • How do you use your files that implement the checkers rules?
  • What do you do with a rejected game?

# Code needs

When you think about the code you might need, try to first answer the following questions:

  • What Ignite CLI commands will create your message?
  • How do you adjust what Ignite CLI created for you?
  • How would you unit-test these new elements?
  • 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?

As before, do not bother yet with niceties like gas metering.

If anyone can create a game for any two other players, it is important to allow a player to reject a game. But a player should not be allowed to reject a game once they have made their first move.

To reject a game, a player needs to provide the ID of the game that the player wants to reject. Call the field gameIndex. This should be sufficient, as the signer of the message is implicitly the player.

# Working with Ignite CLI

Name the message object RejectGame. Invoke Ignite CLI:

This creates all the boilerplate for you and leaves a single place for the code you want to include:

Copy func (k msgServer) RejectGame(goCtx context.Context, msg *types.MsgRejectGame) (*types.MsgRejectGameResponse, error) { ctx := sdk.UnwrapSDKContext(goCtx) // TODO: Handling the message _ = ctx return &types.MsgRejectGameResponse{}, nil } x checkers keeper msg_server_reject_game.go View source

# Additional information

A new rule of the game should be that a player cannot reject a game once they begin to play. When loading a StoredGame from storage you have no way of knowing whether a player already played or not. To access this information add a new field to the StoredGame called MoveCount. In proto/checkers/stored_game.proto:

Copy message StoredGame { ... + uint64 moveCount = 6; } proto checkers stored_game.proto View source

Run Protobuf to recompile the relevant Go files:

MoveCount should start at 0 and increment by 1 on each move.

  1. Adjust it first in the handler when creating the game:

    Copy storedGame := types.StoredGame{ ... + MoveCount: 0, } x checkers keeper msg_server_create_game.go View source
  2. Before saving to the storage, adjust it in the handler when playing a move:

    Copy ... + storedGame.MoveCount++ storedGame.Board = game.String() ... x checkers keeper msg_server_play_move.go View source

With MoveCount counting properly, you are now ready to handle a rejection request.

# The reject handling

To follow the Cosmos SDK conventions, declare the following new errors:

Copy var ( ... + ErrBlackAlreadyPlayed = sdkerrors.Register(ModuleName, 1107, "black player has already played") + ErrRedAlreadyPlayed = sdkerrors.Register(ModuleName, 1108, "red player has already played") ) x checkers types errors.go View source

This time you will add an event for rejection. Begin by preparing the new keys:

Copy const ( GameRejectedEventType = "game-rejected" GameRejectedEventCreator = "creator" GameRejectedEventGameIndex = "game-index" ) x checkers types keys.go View source

In the message handler, the reject steps are:

  1. Fetch the relevant information:

    Copy storedGame, found := k.Keeper.GetStoredGame(ctx, msg.GameIndex) if !found { return nil, sdkerrors.Wrapf(types.ErrGameNotFound, "%s", msg.GameIndex) } x checkers keeper msg_server_reject_game.go View source
  2. Is the player expected? Did the player already play? Check with:

    Copy if storedGame.Black == msg.Creator { if 0 < storedGame.MoveCount { // Notice the use of the new field return nil, types.ErrBlackAlreadyPlayed } } else if storedGame.Red == msg.Creator { if 1 < storedGame.MoveCount { // Notice the use of the new field return nil, types.ErrRedAlreadyPlayed } } else { return nil, sdkerrors.Wrapf(types.ErrCreatorNotPlayer, "%s", msg.Creator) } x checkers keeper msg_server_reject_game.go View source

    Remember that the player with the color black plays first.

  3. Remove the game using the Keeper.RemoveStoredGame (opens new window) function created long ago by the ignite scaffold map storedGame... command:

    Copy k.Keeper.RemoveStoredGame(ctx, msg.GameIndex) x checkers keeper msg_server_reject_game.go View source
  4. Emit the relevant event:

    Copy ctx.EventManager().EmitEvent( sdk.NewEvent(types.GameRejectedEventType, sdk.NewAttribute(types.GameRejectedEventCreator, msg.Creator), sdk.NewAttribute(types.GameRejectedEventGameIndex, msg.GameIndex), ), ) x checkers keeper msg_server_reject_game.go View source
  5. Leave the returned object as it is, as you have nothing new to tell the caller.

Finally, confirm that your project at least compiles with (opens new window):

# Unit tests

Before testing what you did when rejecting a game, you have to fix the existing tests by adding MoveCount: 0 (opens new window) (or more (opens new window)) when testing a retrieved StoredGame.

When you are done with the existing tests, the tests for reject here are similar to those you created for create and play, except that now you test a game rejection by the game creator (opens new window), the black player (opens new window), or the red player (opens new window) which is made before anyone has played (opens new window), or after one (opens new window) or two moves (opens new window) have been made. Check also that the game is removed (opens new window), and that events are emitted (opens new window).

For instance:

Copy func TestRejectGameByRedOneMoveRemovedGame(t *testing.T) { msgServer, keeper, context := setupMsgServerWithOneGameForRejectGame(t) msgServer.PlayMove(context, &types.MsgPlayMove{ Creator: bob, GameIndex: "1", FromX: 1, FromY: 2, ToX: 2, ToY: 3, }) msgServer.RejectGame(context, &types.MsgRejectGame{ Creator: carol, GameIndex: "1", }) systemInfo, found := keeper.GetSystemInfo(sdk.UnwrapSDKContext(context)) require.True(t, found) require.EqualValues(t, types.SystemInfo{ NextId: 2, }, systemInfo) _, found = keeper.GetStoredGame(sdk.UnwrapSDKContext(context), "1") require.False(t, found) } x checkers keeper msg_server_reject_game_test.go View source

Try these tests:

# Interact with the CLI

Time to see if it is possible to reject a game from the command line. If you did not do it already, start your chain with Ignite.

First, is it possible to reject the current game from the command line?

This prints:

Copy ... Available Commands: ... reject-game Broadcast message rejectGame

reject-game is the command. What is its syntax?

This prints:

Copy ... Usage: checkersd tx checkers reject-game [game-index] [flags]

Have Bob, who played poorly in game 1, try to reject it:

This returns:

Copy ... raw_log: '[{"events":[{"type":"game-rejected","attributes":[{"key":"creator","value":"cosmos14g3qw6nkk8zc762k87cg77w7vd8xdnffnp2w6u"},{"key":"game-index","value":"1"}]},{"type":"message","attributes":[{"key":"action","value":"reject_game"}]}]}]'

Against expectations, the system carried out Bob's request to reject the game. Confirm that the game has indeed been removed from storage:

This returns:

Copy Error: rpc error: code = NotFound desc = rpc error: code = NotFound desc = not found: key not found ...

How is it possible that Bob could reject a game he had already played in, despite the code preventing that? Because game 1 was created in an earlier version of your code. This earlier version created a game without any .MoveCount, or more precisely with MoveCount == 0. When you later added the code for rejection, Ignite CLI kept the current state of your blockchain. In effect, your blockchain was in a broken state, where the code and the state were out of sync.

To see how to properly handle code changes that would otherwise result in a broken state, see the section on migrations.

You have to create other games and test the rejection on them. Notice the incrementing game ID.

1

Black rejects:

Above, Alice creates a game and rejects it immediately. This returns:

Copy ... raw_log: '[{"events":[{"type":"game-rejected","attributes":[{"key":"creator","value":"cosmos1uhfa4zhsvz7cyec7r62p82swk8c85jaqt2sff5"},{"key":"game-index","value":"2"}]},{"type":"message","attributes":[{"key":"action","value":"reject_game"}]}]}]'

Correct result, because nobody played a move.

2

Red rejects:

Above, Alice creates a game and Bob rejects it immediately. This returns:

Copy ... raw_log: '[{"events":[{"type":"game-rejected","attributes":[{"key":"creator","value":"cosmos14g3qw6nkk8zc762k87cg77w7vd8xdnffnp2w6u"},{"key":"game-index","value":"3"}]},{"type":"message","attributes":[{"key":"action","value":"reject_game"}]}]}]'

Correct again, because nobody played a move.

3

Black plays and rejects:

Above, Alice creates a game, makes a move, and then rejects the game. This returns:

Copy ... raw_log: 'failed to execute message; message index: 0: black player has already played'

Correct: the request fails, because Alice has already played a move.

4

Alice plays and Bob rejects:

Above, Alice creates a game, makes a move, and Bob rejects the game. This returns:

Copy ... raw_log: '[{"events":[{"type":"game-rejected","attributes":[{"key":"creator","value":"cosmos14g3qw6nkk8zc762k87cg77w7vd8xdnffnp2w6u"},{"key":"game-index","value":"5"}]},{"type":"message","attributes":[{"key":"action","value":"reject_game"}]}]}]'

Correct: Bob has not played a move yet, so he can still reject the game.

5

Alice & Bob play, Bob rejects:

Above, Alice creates a game and makes a move, then Bob makes a poor move and rejects the game. This returns:

Copy ... raw_log: 'failed to execute message; message index: 0: red player has already played'

Correct: this time Bob could not reject the game because the state recorded his move in .MoveCount.


To belabor the point made in the earlier box: if you change your code, think about what it means for the current state of the chain and whether you end up in a broken state.

In this case, you could first introduce the MoveCount and its handling. Then when all games have been correctly counted, you introduce the rejection mechanism.

synopsis

To summarize, this section has explored:

  • How to use messages and handlers to build on the gameplay functionalities of your application by adding the capacity for players to reject participating in a game.
  • How to create a new RejectGame message object including ID of the game to be rejected.
  • How to add a new rule with the necessary additional information to prevent players from backing out of games in which they have already played moves, and how to declare new errors that respond to attempts to break this new rule.
  • How to add a unit test to check that games can be rejected by the game creator, the black player, and the red player under the approved circumstances, and to check that rejected games are removed and that events are emitted.
  • How to interact via the CLI to confirm the new "game rejection" function is performing as required, and to be aware that preexisting games will permit incorrect game rejection due to your blockchain being in a broken state due to your subsequent changes.