# Run a Node, API, and CLI
In this first section, you will learn how to run a blockchain and discover how to interact with it.
There are different ways to run a node of a Cosmos blockchain. You will explore how to do so using
simapp (opens new window).
Before you start working with
simapp, take a look at what you are going to do:
The Cosmos SDK repository contains a folder called
simapp (opens new window). In this folder you can find the code to run a simulated version of the Cosmos SDK, so you can test commands without actually interacting with your chain. The binary is called
simd and you will be using it to interact with your node.
First, create and change the directory into a
cosmos folder, and then clone the
cosmos-sdk repo into that folder:
Make sure you are using the same version used at the time of writing:
The build takes a few minutes and creates a
build folder and a
simapp binary named
Now reset the database. Run this step not only when the database has already been initialized but even if this is the first time you are testing
The command output lists all of the files set to their initial state with their locations.
Time to initialize the application. The initialization creates the genesis block and an initial chain state:
This is a more readable version of the same initial chain state:
You can find your
chain_id in your output, which in our build happens to be called
test-chain-rT4wZY. Make a note of your output's name, as you will need it later to determine the chain ID by passing it to
simapp via the flag
You can inspect the initial configuration with:
# Prepare your account
It helps to understand the concepts clearly when working hands-on with the Cosmos SDK. Need a refresher? See the section on Accounts in the Main Concepts chapter.
You can also inspect your keys. These are held in the backend keyring, which by default is that of the operating system:
As you might have expected, you do not have any keys yet:
Now you can add a new key:
Which prints something similar to:
You can see the mnemonic at the end of the above output. This sequence of words is a mnemonic that you can use to recover your public and private keys. In a production setting, the mnemonic must be stored in a reliable and confidential fashion as part of the key-management infrastructure.
Confirm that the key has been added with:
You can also confirm the key has been added with:
# Make yourself a proper validator
As previously explained, a Cosmos SDK blockchain relies on identified validators to produce blocks. Initially there is no validator to generate blocks. You are in a catch-22 situation: your initialized and unstarted chain needs a genesis account and validator for bootstrapping purposes.
Make your key, also known as an account, have an initial balance in the genesis file:
Appended here to the amount is the
stake suffix. This
stake represents the unit for the tokens in this chain as per the genesis file. Therefore, this command adds
stake to your account. If in doubt, you can confirm the proper suffix in the
genesis.json file with:
You can also confirm in the genesis file itself that you have an initial balance:
Despite this initial balance, before you run your blockchain you still need to escape the catch-22 and include your bootstrap transactions in the genesis file.
In this scenario you must meet the 2/3 threshold for validation, so you must stake at least
70000000stake of your
100000000stake in the
b9lab account you just created. Make sure to not use all your stake, so you still have tokens to pay for gas.
Do not forget to use your own
Which confirms the action:
After you have created this genesis transaction in its own file, collect all the genesis transactions with
collect-gentxs to include it in your genesis file:
Which prints the resulting genesis file:
If you are curious, you can find the updated
gen_txs field in your genesis.
# Create blocks
Now you can start your single-node blockchain:
In the terminal window where you ran the command, you can see blocks being produced and validated:
Open a new terminal in the same folder and check the balances:
# Send a transaction
Practice sending a transaction. To do this, you are going to create another account named "student" and transfer some tokens to that account:
Before sending any tokens confirm that the balance of the new account is absent:
This account does not have a balance. The new account does not yet exist in your blockchain. Only the key pair has been generated and stored in your keyring:
You need to send a transaction to change this new account's balance:
You should be prompted to confirm the transaction before signing and broadcasting:
The command output includes useful information, such as
Now check the balance of the student account again:
That is a
# CLI routing
Now it is time for a bit of Go code. How does the
simd interact via the command-line interface? Inspect the
cosmos-sdk/simapp/simd/main.go (opens new window) file:
cmd.NewRootCmd() (opens new window) function is the CLI handler. It is imported via the
"github.com/cosmos/cosmos-sdk/simapp/simd/cmd" (opens new window) line. It can be found in the
cosmos-sdk/simapp/simd/cmd/root.go (opens new window) file:
In it, basic properties (opens new window) such as the application name are defined:
In addition, observe that Cobra is imported and used for the CLI (opens new window) to redirect:
Also, look at
simapp/app.go (opens new window), in which each module and key keeper will be imported. The first thing you will see is a considerable list of modules (opens new window) that are used by most Cosmos-sdk applications:
The modules in the
/cosmos-sdk/x/ folder are maintained by several organisations working on the Cosmos stack. To understand a module, the best way is to have a look at the respective
spec folder. For example, look at the
cosmos-sdk/x/bank/spec/01_state.md (opens new window) to understand the state of the
bank module which you used in this section.
Do you need a conceptual refresher about modules and their role in the Cosmos SDK? See the Modules section in the previous chapter.
To summarize, this section has explored:
- How to run and to interact with a blockchain by using
simapp, which contains the code necessary to run a simulated version of the Cosmos SDK called
simdso you can test commands without actually interacting with your chain.
- How to compile and initialize
simapp, and to inspect the initial configuration of your chain's genesis state.
- How to prepare your account, including how to add, confirm, and inspect your keys, and review your mnemonic.
- How to make yourself a proper validator, by adding and confirming the presence of an initial balance and including bootstrap transactions in the genesis file.
- How to start your single-node blockchain, observe blocks being created through the terminal window, and check the balances.
- How to practice sending transactions by creating another account and transferring tokens to it, and checking the balance of the new account to confirm the successful transfer.
- CLI routing with the examination of the initial Go code, revealing carious aspects of your nascent chain.