Hello, Ignite CLI

This tutorial is a great place to start your journey into the Cosmos ecosystem. Instead of wondering how to build a blockchain, follow these steps to build your first blockchain and your first Cosmos SDK module.

Get started

In the previous chapter you've learned how to install Ignite CLI, the tool that offers everything you need to build, test, and launch your blockchain with a decentralized worldwide community.

This series of tutorials is based on a specific version of Ignite CLI, so be sure to install the correct version. For example, to install Ignite CLI v0.22.2 use the following command:

curl https://get.ignite.com/cli@v0.22.2! | bash

Ignite CLI comes with a number of scaffolding commands that are designed to make development easier by creating everything that's required to start working on a particular task.

First, use Ignite CLI to build the foundation of a fresh Cosmos SDK blockchain. With Ignite CLI, you don't have to write the blockchain code yourself.

Are you ready? Open a terminal window and navigate to a directory where you have permissions to create files.

To create your blockchain with the default directory structure, run this command:

ignite scaffold chain hello

This command creates a Cosmos SDK blockchain called hello in a hello directory. The source code inside the hello directory contains a fully functional ready-to-use blockchain.

This new blockchain imports standard Cosmos SDK modules, including:

• staking for delegated Proof-of-Stake (PoS) consensus mechanism
• bank for fungible token transfers between accounts
• gov for on-chain governance
• And other Cosmos SDK modules that provide the benefits of the extensive Cosmos SDK framework

You can get help on any command. Now that you have run your first command, take a minute to see all of the command line options for the scaffold command.

To learn about the command you just used, run:

ignite scaffold --help

Blockchain directory structure

After you create the blockchain, switch to its directory:

cd hello

The hello directory contains a number of generated files and directories that make up the structure of a Cosmos SDK blockchain. Most of the work in this tutorial happens in the x directory. Here is a quick overview of files and directories that are created by default:

File/directory	Purpose
app/	Files that wire together the blockchain. The most important file is app.go that contains type definition of the blockchain and functions to create and initialize it.
cmd/	The main package responsible for the CLI of compiled binary.
docs/	Directory for project documentation. By default, an OpenAPI spec is generated.
proto/	Protocol buffer files describing the data structure.
testutil/	Helper functions for testing.
vue/	A Vue 3 web app template.
x/	Cosmos SDK modules and custom modules.
config.yml	A configuration file for customizing a chain in development.
readme.md	A readme file for your sovereign application-specific blockchain project.

Now you can get your blockchain up and running locally on a single node.

Start a blockchain

You already have a fully-functional blockchain. To start your chain on your development machine, run the following command in the hello directory

ignite chain serve

This command downloads dependencies and compiles the source code into a binary called hellod. By default, the binary name is the name of the repo + d. From now on, use this hellod binary to run all of your chain commands. For example, to initialize a single validator node and start a node.

Leave this terminal window open while your chain is running.

HTTP API Console

By default, a validator node exposes two API endpoints:

• http://localhost:26657 for the low-level Tendermint API
• http://localhost:1317 for the high-level blockchain API

Now that you started your hello chain, use a web browser to see the high-level hello blockchain API:

Stop a blockchain

When you want to stop your blockchain, press Ctrl+C in the terminal window where it's running.

In the development environment, you can experiment and instantly see updates. You don't have to restart the blockchain after you make changes. Hot reloading automatically detects all of the changes you make in the hello directory files.

Say "Hello, Ignite CLI"

To get your blockchain to say Hello! Ignite CLI, you need to make these changes:

• Modify a protocol buffer file
• Create a keeper query function that returns data
• Register a query function

Protocol buffer files contain proto rpc calls that define Cosmos SDK queries and message handlers, and proto messages that define Cosmos SDK types. The rpc calls are also responsible for exposing an HTTP API.

For each Cosmos SDK module, the Keeper is an abstraction for modifying the state of the blockchain. Keeper functions let you query or write to the state. After you add the first query to your chain, the next step is to register the query. You only need to register a query once.

A typical blockchain developer workflow looks something like this:

• Start with proto files to define Cosmos SDK messages
• Define and register queries
• Define message handler logic
• Finally, implement the logic of these queries and message handlers in keeper functions

Create a query

For all subsequent commands, use a terminal window that is different from the window you started the chain in.

In a different terminal window, run the commands in your hello directory.

Create a hello query:

ignite scaffold query hello --response text

query accepts a name of the query (in this case, hello), an optional list of request parameters (in this case, empty), and an optional comma-separated list of response fields with a --response flag (in this case, text).

The query command has created and modified several files:

modify proto/hello/query.proto
modify x/hello/client/cli/query.go
create x/hello/client/cli/query_hello.go
create x/hello/keeper/grpc_query_hello.go

Let's examine some of these changes. For clarity, the following code blocks do not show the placeholder comments that Ignite CLI uses to scaffold code. Don't delete these placeholders since they are required to continue using Ignite CLI's scaffolding functionality.

Note: it's recommended to commit changes to a version control system (for example, Git) after scaffolding. This allows others to easily distinguish between code generated by Ignite and the code written by hand.

git add .
git commit -am "Scaffolded a hello query with Ignite CLI"

Updates to the query service

In the proto/hello/query.proto file, the Hello rpc has been added to the Query service.

service Query {
    rpc Hello(QueryHelloRequest) returns (QueryHelloResponse) {
        option (google.api.http).get = "/hello/hello/hello";
    }
}

Here's how the Hello rpc for the Query service works:

• Is responsible for returning a text string
• Accepts request parameters (QueryHelloRequest)
• Returns response of type QueryHelloResponse
• The option defines the endpoint that is used by gRPC to generate an HTTP API

Request and response types

Now, take a look at the following request and response types:

message QueryHelloRequest {
}

message QueryHelloResponse {
  string text = 1;
}

• The QueryHelloRequest message is empty because this request does not require parameters.
• The QueryHelloResponse message contains text that is returned from the chain.

Hello keeper function

The x/hello/keeper/grpc_query_hello.go file contains the Hello keeper function that handles the query and returns data.

func (k Keeper) Hello(goCtx context.Context, req *types.QueryHelloRequest) (*types.QueryHelloResponse, error) {
    if req == nil {
        return nil, status.Error(codes.InvalidArgument, "invalid request")
    }
    ctx := sdk.UnwrapSDKContext(goCtx)
    _ = ctx
    return &types.QueryHelloResponse{}, nil
}

The Hello function performs these actions:

• Makes a basic check on the request and throws an error if it's nil
• Stores context in a ctx variable that contains information about the environment of the request
• Returns a response of type QueryHelloResponse

Right now the response is empty.

Update keeper function

In the query.proto file, the response accepts text.

• Use a text editor to modify the x/hello/keeper/grpc_query_hello.go file that contains the keeper function.
• On the last line of the keeper function, change the line to return "Hello, Ignite CLI!":

func (k Keeper) Hello(c context.Context, req *types.QueryHelloRequest) (*types.QueryHelloResponse, error) {
    if req == nil {
        return nil, status.Error(codes.InvalidArgument, "invalid request")
    }
    ctx := sdk.UnwrapSDKContext(goCtx)
    _ = ctx
    return &types.QueryHelloResponse{Text: "Hello, Ignite CLI!"}, nil // <--
}

• Save the file to restart your chain.

• In a web browser, visit the hello endpoint http://localhost:1317/hello/hello/hello.

  Because the query handlers are not yet registered with gRPC, you see a not implemented or localhost cannot connect error. This error is expected behavior, because you still need to register the query handlers.

Register query handlers

Make the required changes to the x/hello/module.go file.

1. Add "context" to the list of packages in the import statement.

   import (
       // ...
   
       "context"
   
       // ...
   )

   Do not save the file yet, you need to continue with these modifications.

2. Search for RegisterGRPCGatewayRoutes.

3. Register the query handlers:

   func (AppModuleBasic) RegisterGRPCGatewayRoutes(clientCtx client.Context, mux *runtime.ServeMux) {
       types.RegisterQueryHandlerClient(context.Background(), mux, types.NewQueryClient(clientCtx))
   }

4. After the chain has been started, visit http://localhost:1317/hello/hello/hello and see your text displayed:

   {
     "text": "Hello, Ignite CLI!",
   }

The query command has also scaffolded x/hello/client/cli/query_hello.go that implements a CLI equivalent of the hello query and mounted this command in x/hello/client/cli/query.go . Run the following command and get the same JSON response:

hellod q hello hello

Congratulations, you have built your first blockchain and your first Cosmos SDK module. Continue the journey to learn more about scaffolding Cosmos SDK messages, types in protocol buffer files, the keeper, and more.