# Backend Script for Game Indexing

Make sure you have all you need before proceeding:

• You understand the concepts of CosmJS.
• You have the checkers CosmJS codebase up to the integrated GUI. If not, follow the previous steps or go ahead and clone and checkout this branch (opens new window) to get the version needed for this tutorial.

This exercise assumes that:

1. You are running your checkers blockchain with:

   Copy $ docker network create checkers-net $ docker run --rm -it \ -p 26657:26657 \ --name checkers \ --network checkers-net \ --detach \ checkersd_i:standalone start $ sleep 10 $ docker run --rm -it \ -p 4500:4500 \ --name cosmos-faucet \ --network checkers-net \ --detach \ cosmos-faucet_i:0.28.11 start http://checkers:26657 $ sleep 20

2. You have the following in .env:

   • Local
   • Docker

   Copy RPC_URL="http://localhost:26657" FAUCET_URL="http://localhost:4500"

   When you run npm on your local computer.

   Copy RPC_URL="http://checkers:26657" FAUCET_URL="http://cosmos-faucet:4500"

   When you run npm in a Docker container.

Now that your blockchain is complete, you can think about additional data and services that would add value without increasing cost or complexity on-chain.

For example, how do you list all of a player's games? Currently this information is not easily available. You can find the players of a given game, but not the games of a given player. Indexing this on-chain would add storage and computation costs.

# Server idea

To implement this functionality, build a Web 2.0 server to do the indexing. The server:

1. Listens to updates from the checkers chain:
   1. On a game creation event, adds the game ID under each player.
   2. On a game deletion event, removes it.
2. When asked about its status, returns the latest block height up to which it has indexed players.
3. When asked about a given player, returns the list of game IDs for this player.
4. When a game ID is submitted, patches its information about that game ID on a best effort basis (to palliate potential de-synchronization).

# Barebones server

As a fast and simple Web 2.0 solution, navigate to the checkers CosmJS repository (opens new window) for the checkers blockchain, in the existing gui branch, and perform the following steps:

1. Create a sub-directory of the src folder (e.g. server).
2. Use the express Node.js module to create an HTTP REST API.
3. Use a local db.json as a database. This is obviously primitive and not thread-safe. In a production setting use a proper database.
4. Poll the blockchain at regular intervals. As part of an advanced topic, you can use WebSockets.

# Data types

To keep the code type-safe, define the types of your db.json in types.ts:

Not only does this keep information about players, it also keeps a copy of games. This gets around a current limitation of CosmJS, where you cannot get information about a game that has just been erased from the latest state. In practice you would need to query the game at an earlier block height, but this functionality is not yet available with CosmJS. Note that nodes may prune the old state, especially if they migrate, which may unpredictably impact any query at an earlier block height.

# Empty indexer module

Define a barebones server without any Cosmos elements in an indexer.ts. This is not CosmJS related, so start from something else if you prefer.

Note:

1. The timer is set at the end of the previous poll, in case indexing takes longer than the interval.
2. The database is, for now, purely in memory as it runs and is saved on exit by catching the interruption signal.

# Files for execution

Prepare these files around the indexer to run it in the terminal:

1. Create an index.ts that describes how to run the indexer:

   Copy require("./indexer").createIndexer().then(console.log).catch(console.error) export {} src server index.ts View source

   The export {} prevents Visual Studio Code from complaining.

2. Add a specific tsconfig.json file if necessary:

   Copy { "extends": "../../tsconfig.json", "compilerOptions": { "target": "ESNext", "isolatedModules": false, "module": "CommonJS" } } src server tsconfig.json View source

3. In package.json, add a run target:

   Copy "scripts": { ... + "indexer-dev": "npx ts-node src/server/index.ts" } package.json View source

4. Add your database, db.json by making a copy of the sample:

   Copy { "status": { "block": { "height": 0 } }, "players": {}, "games": {} } src server db.json.sample View source

   You cannot ask for block at height 0, so the indexer first asks for the next block at 1.

# Quick test

Check that the indexer works:

It should print:

Now, in another terminal, test the endpoints. Omit the | jq beautifier if it is not installed on your system:

# Add CosmJS StargateClient

You need to create a client to connect to your checkers blockchain. The client only needs read-only functionality because this server does not submit transactions. Your repository already contains useful elements:

• The CheckersStargateClient.
• An .env (opens new window) file.

Add the following to indexer.ts:

1. The declarations:

   Copy import { config } from "dotenv" import { CheckersStargateClient } from "../checkers_stargateclient" src server indexer.ts View source

   The pickup of RPC_URL:

   Copy config() src server indexer.ts View source

   The client in the indexer:

   Copy let client: CheckersStargateClient src server indexer.ts View source

2. The modified init:

   Copy const init = async() => { client = await CheckersStargateClient.connect(process.env.RPC_URL!) console.log("Connected to chain-id:", await client.getChainId()) setTimeout(poll, 1) } src server indexer.ts View source

3. The modified poll:

   Copy const poll = async() => { const currentHeight = await client.getHeight() console.log( new Date(Date.now()).toISOString(), "Current heights:", db.status.block.height, "<=", currentHeight, ) timer = setTimeout(poll, pollIntervalMs) } src server indexer.ts View source

If you have not done it yet, start your checkers chain as described at the beginning of this section.

Relaunch the indexer:

• Local
• Docker

Copy $ npm run indexer-dev

Copy $ docker run --rm -it \ -v $(pwd):/client -w /client \ -p 3001:3001 \ --network checkers-net \ --env RPC_URL="http://checkers:26657" \ node:18.7-slim \ npm run indexer-dev

Note how the container is started inside checkers-net alongside the checkers blockchain.

You should see the current height rising:

# Handle blocks

To index games, take each block and listen for the following relevant events:

1. A transaction with a new-game-created event.
2. An EndBlock with a game-forfeited event.

Start by getting each block from your last saved state. Update poll:

This needs a new import:

The indexer:

• Declares a new function handleBlock. Create one and put console.log(block) inside to explore what this object is and consider what actions you would take with it.
• Saves the db after a poll, so you can watch it in real time.
• Uses process.stdout.write and process.stdout.cursorTo(0) so that the repetitive logging happens on a single line.

Observe the relevant content in handleBlock. It must:

1. Extract the events from transactions.
2. Extract the events from EndBlock.

If you examine block.txs directly you find transactions as they were posted. However, this does not reveal any execution results, such as if a transaction executed as expected or what game ID it used for the new game. To get this extra information:

1. Calculate txHash from the transaction.
2. Call await client.getTx(txHash), which returns an IndexedTx.

The handleBlock function can be:

This needs new imports:

• while() { await } simplifies the syntax of awaiting multiple times sequentially.
• The hash is calculated this way as per here (opens new window).
• console.log("") puts a new line (poll does a process.stdout.write which adds no line).
• The handleBlock function uses a new function, handleTx. Create one and put console.log(indexed) inside to explore what this object is and consider what actions you can take with it.
• The EndBlock part has not yet been incorporated. This is explained in Prepare for EndBlock.

# Handle a transaction

Define the handleTx function:

This needs new imports:

• .flatMap (opens new window) transforms an array of arrays into a flattened array.
• The handleTx function uses a new function, handleEvents. Create one and put console.log(events) in it to explore what this object is and consider what actions you can take with it.

# Handle events

Define the handleEvents function:

• while() {} simplifies the syntax of awaiting multiple times sequentially.
• The handleEvents function only keeps events that emanate from the checkers module.
• It uses a new function, handleEvent. Create one and put console.log(event) inside to explore what this object is and consider what actions you can take with it.
• It skips in case of error, as the likely cause is that the transactions in fact failed. This is not good enough if the goal is to be absolutely accurate.

# Handle one event

Define handleEvent as follows:

• new-game-created (opens new window) and move-played (opens new window) are constant values defined in your Go code. They are put as the event's type (opens new window).
• handleEvent uses two new functions: handleEventCreate and handleEventPlay. Create them and put console.log(event) inside each to explore what these objects are and consider what actions you would take with them.

# Handle one create event

Now update your db with the information provided. First, define a convenience function in createIndexer:

This needs a new import:

Now define handleEventCreate as:

• game-index (opens new window), black (opens new window), and red (opens new window) are constants from the Go code.
• You have implemented error handling.
• handleEventCreate is careful not to double-add a given game ID.
• It does not save db as this is under the purview of poll().

# Handle one play event

Not all play events are equal. handleEventPlay is only interested when there is a winner. Until then, there is no need to take any action.

• handleEventPlay returns quietly if there is no winner, because this means there is nothing to do.
• It keeps the game information in the db.
• It removes the id from both players' list of games.

# Test time

You can now test what happens when a game is created and played on. Restart npm run indexer-dev locally or in Docker.

You can choose how to create and play games:

• Run the GUI prepared in the previous section with npm start.
• Run checkersd command lines.
• Any other way available.

Via command lines, in another terminal:

What remains is handling the games that get removed or forfeited in EndBlock.

# Prepare for EndBlock

Nicely formatted EndBlock events are still missing from CosmJS, so these require a little extra work:

1. To get a block's EndBlock events, you need to ask for the block information from a CometBFT client. This client is a private field (opens new window) of StargateClient.
2. The function to call is blockResults (opens new window).
3. It returns a BlockResultsResponse (opens new window), of which endBlockEvents: Event is of interest.
4. This Event (opens new window) type has attributes: Attribute[] of interest.
5. The Attribute (opens new window) type is coded as Uint8Array.

With this information, you can do the necessary actions:

1. To handle the conversion of CometBFT Events into StringEvents, create a helper in a new src/server/events.ts:

   Copy import { fromUtf8 } from "@cosmjs/encoding" import { Attribute as TendermintAttribute, Event } from "@cosmjs/tendermint-rpc" import { Attribute, StringEvent } from "cosmjs-types/cosmos/base/abci/v1beta1/abci" export const convertTendermintEvents = (events: readonly Event[]): StringEvent[] => { return events.map( (event: Event): StringEvent => ({ type: event.type, attributes: event.attributes.map( (attribute: TendermintAttribute): Attribute => ({ key: fromUtf8(attribute.key), value: fromUtf8(attribute.value), }), ), }), ) } src server events.ts View source

2. To handle the call to blockResults, you need access to a CometBFT client. One option is to make a copy of the private CometBFT client. You can do this only on construction, so create a child class of CheckersStargateClient to do that. It is recommended to keep it close by indexer.ts. In a new indexer_stargateclient.ts:

Now swap out CheckersStargateClient with IndexerStargateClient:

With this in place, go back to handleBlock and work on the remaining TODO.

# Handle one block's EndBlock

Go to the function and update it:

The events that you have converted are compatible with those emanating from transactions, so you can just pass them on. You still need to update handleEvent so that it acts on the new event type:

To achieve this, add a new function:

Again there is a lot of error handling. handleEvent only soft-deletes the game, although it removes it from the list of games for the players.

# Test time of forfeit

Run the previous tests again. Create a game and see how the deletion event is picked up:

In the standalone checkers in Docker, the deadline is unfortunately set at 24 hours, so feedback is not exactly coming fast. At this state of the exercise, if you want to test the expiry quickly, you will have to run Ignite CLI and adjust the MaxTurnDuration as described here.

# Patch a game

In the actions that the Express server exposes, app.patch still remains to be implemented. This allows a user to inform the server that its database is no longer synchronized, and that it should look at a specific game. It is a matter of data re-synchronization:

1. If the game can be found in the blockchain state, update the indexer's database accordingly:
   1. If there is a winner, then the game should be removed from its players' lists of games.
   2. If there is no winner, then the game should be added to its players' lists of games.
2. If the game cannot be found in the blockchain state, but is present in the indexer's database, then the game should be removed from the lists of games of its players, and marked as soft-deleted. This shows the usefulness of keeping old games.
3. If the game cannot be found either in the blockchain state nor in the indexer's database, then it is better not to do anything. To remove it from all players' lists of games is potentially expensive. This could expose the server to a DoS attack.

Code the following:

There are some issues to be aware of:

1. JavaScript is not thread-safe, so you could cause two opposite actions: one coming from the polling and the other from a patch submission, or even from two concurrent patch submissions. To reduce this risk the database is not saved to disk in this function, but instead relies on the polling to save it at the next run.
2. Assuming that there is no such game when you cannot find it can result in deleting data that is simply taking time to appear on your blockchain node.

Next, you need to call patchGame from the app.patch callback:

# Test time of patch

To simulate a case where the game is in the blockchain state but not the indexer's:

1. Stop your indexer.

2. Create a game and check at what block it is included (for example, at index 3 and block 1001).

3. Update your indexer's db.json to pretend that it already indexed the game's block by setting:

   Copy "status": { "block": { "height": 1001 } }

4. Restart the indexer.

5. From another terminal, make a call to it:

   Copy $ curl -X PATCH localhost:3001/games/3 | jq

It should return:

And the indexer should log something like:

Develop your own ways to test the other scenarios.

If you started the chain in Docker, when you are done you can stop the containers with:

# Conclusion

You have created a small server that:

• Polls the blockchain to get events about created, won, and forfeited games.
• Maintains a database with information indexed in real time.
• Offers this information as a Web service.
• Accepts requests for patches.

These are examples of server-side scripts, which can improve user experience.

You can find the complete code here (opens new window).