# Add a Way to Make a Move

Make sure you have all you need before proceeding:

• You understand the concepts of transactions, messages, and Protobuf.
• Go is installed.
• You have the checkers blockchain codebase with MsgCreateGame and its handling. If not, follow the previous steps or check out the relevant version (opens new window).

In this section, you will:

• Extend message handling - play the game.
• Handle moves and update the game state.
• Validate input.
• Extend unit tests.

Your blockchain can now create games, but can you play them? Not yet...so what do you need to make this possible?

# Some initial thoughts

Before diving into the exercise, take some time to think about the following questions:

• What goes into the message?
• How do you sanitize the inputs?
• How do you unequivocally identify games?
• How do you report back errors?
• How do you use your files that implement the checkers rules?
• How do you make sure that nothing is lost?

# Code needs

When it comes to the code you need, ask yourself:

• 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 or event emission.

To play a game a player only needs to specify:

• The ID of the game the player wants to join. Call the field gameIndex.
• The initial positions of the pawn. Call the fields fromX and fromY and make them uint.
• The final position of the pawn after a player's move. Call the fields toX and toY to be uint too.

The player does not need to be explicitly added as a field in the message because the player is implicitly the signer of the message. Name the object PlayMove.

Unlike when creating the game, you want to return:

• The captured piece, if any. Call the fields capturedX and capturedY. Make then int so that you can pass -1 when no pieces have been captured.
• The (potential) winner in the field winner.

# With Ignite CLI

Ignite CLI can create the message and the response objects with a single command:

Ignite CLI once more creates all the necessary Protobuf files and boilerplate for you. See tx.proto:

All you have to do is fill in the needed parts:

• In x/checkers/types/message_play_move.go:

  Copy func (msg *MsgPlayMove) ValidateBasic() error { _, err := sdk.AccAddressFromBech32(msg.Creator) if err != nil { return sdkerrors.Wrapf(sdkerrors.ErrInvalidAddress, "invalid creator address (%s)", err) } return nil } x checkers types message_play_move.go View source

• And in x/checkers/keeper/msg_server_play_move.go:

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

  Where the TODO is replaced as per the following.

# The message basic validation

With a game index and board positions, there are a number of stateless error situations that can be detected:

• You know there will not be a game index at the value given.
• A piece position is out of the bounds of the board.
• from and to are identical.

Declare your new errors:

Then you can check that:

1. The game index is reasonable:

   Copy gameIndex, err := strconv.ParseInt(msg.GameIndex, 10, 64) if err != nil { return sdkerrors.Wrapf(ErrInvalidGameIndex, "not parseable (%s)", err) } if uint64(gameIndex) < DefaultIndex { return sdkerrors.Wrapf(ErrInvalidGameIndex, "number too low (%d)", gameIndex) } x checkers types message_play_move.go View source

2. The positions are within bounds, checking an array of situations:

   Copy boardChecks := []struct { value uint64 err string }{ { value: msg.FromX, err: "fromX out of range (%d)", }, { value: msg.ToX, err: "toX out of range (%d)", }, { value: msg.FromY, err: "fromY out of range (%d)", }, { value: msg.ToY, err: "toY out of range (%d)", }, } for _, situation := range boardChecks { if situation.value < 0 || rules.BOARD_DIM <= situation.value { return sdkerrors.Wrapf(ErrInvalidPositionIndex, situation.err, situation.value) } } x checkers types message_play_move.go View source

   Yes, a uint64 like msg.FromY can never be < 0, but since there is no compilation warning you can keep it for future reference if the type changes.

3. There is an actual move:

   Copy if msg.FromX == msg.ToX && msg.FromY == msg.ToY { return sdkerrors.Wrapf(ErrMoveAbsent, "x (%d) and y (%d)", msg.FromX, msg.FromY) } x checkers types message_play_move.go View source

It is conceivable, perhaps even for the benefit of players, to add more stateless checks. For instance, to detect when playing out of wrong cells; after all, only half the cells are valid. Or to detect when moves are not along a diagonal.

These are all worthy checks, although they tend to distract from learning about Cosmos SDK.

If you are nonetheless interested, a good place to look at for a start is the rules file (opens new window).

# The move handling

The rules represent the ready-made file containing the rules of the game you imported earlier. Declare your new errors in x/checkers/types/errors.go, given your code has to handle new error situations:

Take the following steps to replace the TODO:

1. Fetch the stored game information using the Keeper.GetStoredGame (opens new window) function created by Ignite CLI:

   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_play_move.go View source

   You return an error because this is a player mistake.

2. Is the player legitimate? Check with:

   Copy isBlack := storedGame.Black == msg.Creator isRed := storedGame.Red == msg.Creator var player rules.Player if !isBlack && !isRed { return nil, sdkerrors.Wrapf(types.ErrCreatorNotPlayer, "%s", msg.Creator) } else if isBlack && isRed { player = rules.StringPieces[storedGame.Turn].Player } else if isBlack { player = rules.BLACK_PLAYER } else { player = rules.RED_PLAYER } x checkers keeper msg_server_play_move.go View source

   This uses the certainty that the MsgPlayMove.Creator has been verified by its signature (opens new window).

3. Instantiate the board in order to implement the rules:

   Copy game, err := storedGame.ParseGame() if err != nil { panic(err.Error()) } x checkers keeper msg_server_play_move.go View source

   Fortunately you previously created this helper (opens new window). Here you panic because if the game cannot be parsed the cause may be database corruption.

4. Is it the player's turn? Check using the rules file's own TurnIs (opens new window) function:

   Copy if !game.TurnIs(player) { return nil, sdkerrors.Wrapf(types.ErrNotPlayerTurn, "%s", player) } x checkers keeper msg_server_play_move.go View source

5. Properly conduct the move, using the rules' Move (opens new window) function:

   Copy captured, moveErr := game.Move( rules.Pos{ X: int(msg.FromX), Y: int(msg.FromY), }, rules.Pos{ X: int(msg.ToX), Y: int(msg.ToY), }, ) if moveErr != nil { return nil, sdkerrors.Wrapf(types.ErrWrongMove, moveErr.Error()) } x checkers keeper msg_server_play_move.go View source

6. Prepare the updated board to be stored and store the information:

   Copy storedGame.Board = game.String() storedGame.Turn = rules.PieceStrings[game.Turn] k.Keeper.SetStoredGame(ctx, storedGame) x checkers keeper msg_server_play_move.go View source

   This updates the fields that were modified using the Keeper.SetStoredGame (opens new window) function, as when you created and saved the game.

7. Return relevant information regarding the move's result:

   Copy return &types.MsgPlayMoveResponse{ CapturedX: int32(captured.X), CapturedY: int32(captured.Y), Winner: rules.PieceStrings[game.Winner()], }, nil x checkers keeper msg_server_play_move.go View source

   The Captured and Winner information would be lost if you did not get it out of the function one way or another. More accurately, one would have to replay the transaction to discover the values. It is best to make this information easily accessible.

This completes the move process, facilitated by good preparation and the use of Ignite CLI.

# Unit tests

Adding unit tests for this play message is very similar to what you did for the previous message.

# On the message

Adjust and add to types/message_play_move_test.go. First, change its package for consistency:

Then adjust and add to the test cases:

You can try these tests:

# On the keeper

Create a new keeper/msg_server_play_move_test.go file and declare it as package keeper_test. Start with a function that conveniently sets up the keeper for the tests. In this case, already having a game saved can reduce several lines of code in each test:

Note that it reuses alice, bob and carol found in the file msg_server_create_game_test.go (opens new window) of the same package.

Now test the result of a move. Blacks play first, which according to setupMsgServerWithOneGameForPlayMove corresponds to bob:

Also test whether the game was saved correctly (opens new window). Check what happens when the game cannot be found (opens new window), the sender is not a player (opens new window), a player tries to play out of turn (opens new window), or makes a wrong move (opens new window). Check after two (opens new window) or three turns with a capture (opens new window).

As a special case, add a test to check what happens when a board is not parseable, which is expected to end up in a panic, not with a returned error:

Note the use of defer (opens new window), which can be used as a Go way of implementing try catch of panics. The defer statement is set up right before the msgServer.PlayMove statement that is expected to fail, so that it does not catch panics that may happen earlier.

Try these tests:

# Interact via the CLI

Start your chain again:

If you restarted from the previous section, there is already one game in storage and it is waiting for Alice's move. If that is not the case, recreate a game via the CLI.

# Bob plays out of turn

Can Bob make a move? Look at the play-move message and which parameters it expects:

This returns:

So Bob tries:

After you accept sending the transaction, it should complain with the result including:

If you did not get this raw_log, your transaction may have been sent asynchronously. You can always query a transaction by using the txhash with the following command:

• Local
• Docker

Copy $ checkersd query tx D10BB8A706870F65F19E4DF48FB870E4B7D55AF4232AE0F6897C23466FF7871B

Copy $ docker exec -it checkers \ checkersd query tx D10BB8A706870F65F19E4DF48FB870E4B7D55AF4232AE0F6897C23466FF7871B

And you are back on track:

Copy ... raw_log: 'failed to execute message; message index: 0: {red}: player tried to play out of turn'

This error by Bob was caught when he tried to play out of turn. The check was a stateful check as the message itself was valid. This failure cost him gas.

# Alice plays a wrong move

Can Alice, who plays black, make a move? Can she make a wrong move? There are two kinds of wrong moves that Alice can make: she can make one whose wrongness will be caught statelessly, and another that will be caught because of the current state of the board.

1. As an example of a statelessly wrong move, she could try to take a piece on the side and move it just outside the board:

   • Local
   • Docker

   Copy $ checkersd tx checkers play-move 1 7 2 8 3 --from $alice

   Copy $ docker exec -it checkers \ checkersd tx checkers play-move 1 7 2 8 3 --from $alice

   The computer says "no" immediately:

   Copy Error: toX out of range (8): position index is invalid ...

   The transaction never went into the mem pool. This mistake did not cost Alice any gas.

2. As an example of a statefully wrong move, Alice can try to move from 0-1 to 1-0, which is occupied by one of her pieces.

   • Local
   • Docker

   Copy $ checkersd tx checkers play-move 1 1 0 0 1 --from $alice

   Copy $ docker exec -it checkers \ checkersd tx checkers play-move 1 1 0 0 1 --from $alice

   The computer says "no" again, but this time after the transaction has been validated:

   Copy ... raw_log: 'failed to execute message; message index: 0: Already piece at destination position: {0 1}: wrong move'

   This mistake cost Alice some gas.

So far all seems to be working.

# Alice plays correctly

Time for Alice to make a correct move:

This returns:

Confirm the move went through with your one-line formatter from the previous section:

This shows:

Alice's piece moved down and right.

When you are done with this exercise you can stop Ignite's chain serve.