# Running a Node
Now that the application is ready and the keyring populated, it's time to see how to run the blockchain node. In this section, the application we are running is called
simapp (opens new window), and its corresponding CLI binary
# Pre-requisite Readings
# Initialize the Chain
Make sure you can build your own binary, and replace
simd with the name of your binary in the snippets.
Before actually running the node, we need to initialize the chain, and most importantly its genesis file. This is done with the
The command above creates all the configuration files needed for your node to run, as well as a default genesis file, which defines the initial state of the network. All these configuration files are in
~/.simapp by default, but you can overwrite the location of this folder by passing the
~/.simapp folder has the following structure:
# Updating Some Default Settings
If you want to change any field values in configuration files (for ex: genesis.json) you can use
jq (installation (opens new window) & docs (opens new window)) &
sed commands to do that. Few examples are listed here.
# Adding Genesis Accounts
Before starting the chain, you need to populate the state with at least one account. To do so, first create a new account in the keyring named
my_validator under the
test keyring backend (feel free to choose another name and another backend).
Now that you have created a local account, go ahead and grant it some
stake tokens in your chain's genesis file. Doing so will also make sure your chain is aware of this account's existence:
$MY_VALIDATOR_ADDRESS is a variable that holds the address of the
my_validator key in the keyring. Also note that the tokens in the Cosmos SDK have the
amount is is a 18-digit-precision decimal number, and
denom is the unique token identifier with its denomination key (e.g.
uatom). Here, we are granting
stake tokens, as
stake is the token identifier used for staking in
simapp (opens new window). For your own chain with its own staking denom, that token identifier should be used instead.
Now that your account has some tokens, you need to add a validator to your chain. Validators are special full-nodes that participate in the consensus process (implemented in the underlying consensus engine) in order to add new blocks to the chain. Any account can declare its intention to become a validator operator, but only those with sufficient delegation get to enter the active set (for example, only the top 125 validator candidates with the most delegation get to be validators in the Cosmos Hub). For this guide, you will add your local node (created via the
init command above) as a validator of your chain. Validators can be declared before a chain is first started via a special transaction included in the genesis file called a
gentx does three things:
- Registers the
validatoraccount you created as a validator operator account (i.e. the account that controls the validator).
- Self-delegates the provided
amountof staking tokens.
- Link the operator account with a Tendermint node pubkey that will be used for signing blocks. If no
--pubkeyflag is provided, it defaults to the local node pubkey created via the
simd initcommand above.
For more information on
gentx, use the following command:
# Configuring the Node Using
The Cosmos SDK automatically generates two configuration files inside
config.toml: used to configure the Tendermint, learn more on Tendermint's documentation (opens new window),
app.toml: generated by the Cosmos SDK, and used to configure your app, such as state pruning strategies, telemetry, gRPC and REST servers configuration, state sync...
Both files are heavily commented, please refer to them directly to tweak your node.
One example config to tweak is the
minimum-gas-prices field inside
app.toml, which defines the minimum gas prices the validator node is willing to accept for processing a transaction. Depending on the chain, it might be an empty string or not. If it's empty, make sure to edit the field with some value, for example
10token, or else the node will halt on startup. For the purpose of this tutorial, let's set the minimum gas price to 0:
# Run a Localnet
Now that everything is set up, you can finally start your node:
Note: By default nodes are run in full node mode. Running a local network means in most cases, the node is the only node in the network, requiring you to set the mode.
You should see blocks come in.
The previous command allow you to run a single node. This is enough for the next section on interacting with this node, but you may wish to run multiple nodes at the same time, and see how consensus happens between them.
The naive way would be to run the same commands again in separate terminal windows. This is possible, however in the Cosmos SDK, we leverage the power of Docker Compose (opens new window) to run a localnet. If you need inspiration on how to set up your own localnet with Docker Compose, you can have a look at the Cosmos SDK's
docker-compose.yml (opens new window).
# State Sync
State sync is the act in which a node syncs the latest or close to the latest state of a blockchain. This is useful for users who don't want to sync all the blocks in history. Read more in CometBFT documentation (opens new window).
State sync works thanks to snapshots. Read how the SDK handles snapshots here (opens new window).
# Local State Sync
Local state sync work similar to normal state sync except that it works off a local snapshot of state instead of one provided via the p2p network. The steps to start local state sync are similar to normal state sync with a few different designs.
- As mentioned in https://docs.cometbft.com/v0.34/core/state-sync, one must set a height and hash in the config.toml along with a few rpc servers (the afromentioned link has instructions on how to do this).
<appd snapshot restore <height> <format>to restore a local snapshot (note: first load it from a file with the load command).
- Bootsrapping Comet state in order to start the node after the snapshot has been ingested. This can be done with the bootstrap command
<app> tendermint bootstrap-state
# Snapshots Commands
The Cosmos SDK provides commands for managing snapshots.
These commands can be added in an app with the following snippet in
Then following commands are available at
<appd> snapshots [command]:
- list: list local snapshots
- load: Load a snapshot archive file into snapshot store
- restore: Restore app state from local snapshot
- export: Export app state to snapshot store
- dump: Dump the snapshot as portable archive format
- delete: Delete a local snapshot