# Messages

Remember from the previous section on transactions that transactions must be signed before a validator includes them in a block. Every message in a transaction must be signed by the addresses as specified by GetSigners.

The Cosmos SDK currently allows signing transactions with either SIGN_MODE_DIRECT or SIGN_MODE_LEGACY_AMINO_JSON methods.

When an account signs a message it signs an array of bytes. This array of bytes is the outcome of serializing the message. For the signature to be verifiable at a later date, this conversion needs to be deterministic. For this reason, you define a canonical bytes-representation of the message, typically with the parameters ordered alphabetically.

In the previous design exercise's code examples, the ABCI application was aware of a single transaction type: that of a checkers move with four int values. With multiple games, this is no longer sufficient. Additionally, you need to conform to the SDK's way of handling Tx, which means creating messages that are then included in a transaction.

If you want the guided coding exercise instead of design and implementation considerations, see the links at the bottom of the page.

What you need

Begin by describing the messages you need for your checkers application to have a solid starting point before diving into the code:

1. In the former Play transaction, your four integers need to move from the transaction to an sdk.Msg, wrapped in said transaction. Four flat int values are no longer sufficient, as you need to follow the sdk.Msg interface, identify the game for which a move is meant, and distinguish a move message from other message types.
2. You need to add a message type for creating a new game. When this is done, a player can create a new game which mentions other players. A generated (possibly) ID identifies this newly created game and is returned to the message creator.
3. It would be a good feature for the other person to be able to reject the challenge. This would have the added benefit of clearing the state of stale, unstarted games.

How to proceed

Focus on the messages around the game creation. There is no single true way of deciding what goes into your messages. The following is one reasonable example.

1. The message itself is structured like this:

   Copy type MsgCreateGame struct { Creator string Black string Red string }

   Note that Creator contains the address of the message signer.

2. The corresponding response message would then be:

   Copy type MsgCreateGameResponse struct { GameIndex string }

   The idea here is that when the creator does not know the ID of the game that will be created, the ID needs to be returned.

With the messages defined, you need to declare how the message should be handled. This involves:

1. Describing how the messages are deterministically serialized. For this, you use Protobuf.
2. Writing the code that handles the message and places the new game in the storage.
3. Putting hooks and callbacks at the right places in the general message handling.

How to proceed with v0.50 or after

The SDK takes care of a lot of things. In particular, by annotating your Protobuf message, you can have it implement sdk.Msg after compilation. For instance:

Then, you declare a Protobuf message server:

After compilation, you register this together with your interface registry so that the module knows to send any MsgCreateGame to the CreateGame function of the MsgClient interface.

You also define a local msgServer that implements the CreateGame function with the required actions, such as:

• Extracting and verifying the players and other values from the message.
• Creating a new game and saving it to storage.
• Returning the expected message.

How to proceed with v0.47 or earlier and Ignite

Thinking from design to implementation, Ignite CLI can help you create these elements, plus the MsgCreateGame and MsgCreateGameResponse objects, with this command:

Ignite CLI creates a variety of other files. See Run Your Own Cosmos Chain for details, and to make additions to existing files.

A sample of things Ignite CLI does for you

Ignite CLI significantly reduces the amount of work a developer has to do to build an application with the Cosmos SDK. Among others, it:

• Assists with making sure that your message conforms to sdk.Msg by adding the boilerplate for GetSigners and GetSignBytes.
• Adjusts the module's code so that this new message type is handled when received, and adds an empty function where you introduce the action this message is supposed to trigger. It even places a helpful // TODO: Handling the message where you should place your code.

Ignite CLI is opinionated in terms of which files it creates to separate which concerns. If you are not using it, you are free to create the files you want.

What is left to do?

Your work is mostly done. You want to create the specific game creation code to replace // TODO: Handling the message. For this, you need to:

1. Decide how to create a new and unique game ID: newIndex.
   
   

   

   For more details, and to avoid diving too deep in this section, see:

   • Run Your Own Cosmos Chain to start the guided coding exercise from scratch,
   • Create and Save a Game Properly to jump straight where you handle the new message.

2. Extract and verify addresses from the message.

3. Create a game object with all required parameters and save it to storage

4. And finally, return the expected message.

Remember, as a part of good design practice:

• If you encounter an internal error (one that denotes an error in logic or catastrophic failure), you should panic("This situation should not happen").
• If you encounter a user or regular error (like a user not having enough funds), you should return a regular error.

Other considerations

What would happen if one of the two players has accepted the game by playing, but the other player has neither accepted nor rejected the game? You can address this scenario by:

• Having a timeout after which the game is canceled.
• Keeping an index as a First-In-First-Out (FIFO) list, or a list of unstarted games ordered by their cancellation time, so that this automatic trigger does not consume too many resources.

What would happen if a player stops taking turns? To ensure functionality for your checkers application, you can consider:

• Having a timeout after which the game is forfeited. You could also automatically charge the forgetful player, if and when you implement a wager system. For the guided coding exercise on this part, head straight to Keep an Up-To-Date Game Deadline.
• Keeping an index of games that could be forfeited. If both timeouts are the same, you can keep a single FIFO list of games so you can clear them from the top of the list as necessary. For the guided coding exercise on this part, head straight to Put Your Games in Order.
• Handling the cancelation in ABCI's EndBlock (or rather its equivalent in the Cosmos SDK) without any of the players having to trigger the cancelation. For the guided coding exercise on this part, head straight to Auto-Expiring Games.

In general terms, you could add timeout: Timestamp to your StoredGame and update it every time something changes in the game. You can decide on a maximum delay, for example one day.

There are no open challenges, meaning a player cannot create a game where the second player is unknown until someone steps in. Therefore, player matching is left outside of the blockchain. The enterprising student can incorporate it inside the blockchain by changing the necessary models.