> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cosmos.network/llms.txt
> Use this file to discover all available pages before exploring further.

# Running a Node

<Note>
  **Synopsis**

  This section explains how to run a blockchain node. The application used in this tutorial is [`simapp`](https://github.com/cosmos/cosmos-sdk/tree/main/simapp), and its corresponding CLI binary `simd`.
</Note>

<Note>
  **Prerequisite Readings**

  * [Prerequisites](/sdk/latest/node/prerequisites) - Set up Go and build the `simd` binary
  * [Anatomy of a Cosmos SDK Application](/sdk/latest/learn/intro/sdk-app-architecture)
  * [Setting up the keyring](/sdk/latest/node/keyring)
</Note>

## 1. Initialize the chain

Before running the node, initialize the chain and its genesis file. Use the `init` subcommand:

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
# The argument <moniker> is the custom username of your node, it should be human-readable.
simd init <moniker> --chain-id my-test-chain
```

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.

<Tip>
  All these configuration files are in `~/.simapp` by default, but you can overwrite the location of this folder by passing the `--home` flag to each command,
  or set an `$APPD_HOME` environment variable (where `APPD` is the name of the binary).
</Tip>

<Note>
  **Windows users**: Replace `~/.simapp` with `%USERPROFILE%\.simapp` (or `$HOME\.simapp` in PowerShell). For `jq` and `sed` commands in this tutorial, install via [Chocolatey](https://chocolatey.org/) (`choco install jq sed`) or use [Git Bash](https://gitforwindows.org/)/WSL2.
</Note>

The `~/.simapp` folder has the following structure:

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
.                                   # ~/.simapp
  |- data                           # Contains the databases used by the node.
  |- config/
      |- app.toml                   # Application-related configuration file.
      |- config.toml                # CometBFT-related configuration file.
      |- genesis.json               # The genesis file.
      |- node_key.json              # Private key to use for node authentication in the p2p protocol.
      |- priv_validator_key.json    # Private key to use as a validator in the consensus protocol.
```

## 2. Update configuration settings (optional)

To change field values in configuration files (for example, genesis.json), use `jq` ([installation](https://stedolan.github.io/jq/download/) & [docs](https://stedolan.github.io/jq/manual/#Assignment)) and `sed` commands. A few examples are listed here.

```bash expandable theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
# to change the chain-id
jq '.chain_id = "testing"' genesis.json > temp.json && mv temp.json genesis.json

# to enable the api server
sed -i '/\[api\]/,+3 s/enable = false/enable = true/' app.toml

# to change the voting_period
jq '.app_state.gov.voting_params.voting_period = "600s"' genesis.json > temp.json && mv temp.json genesis.json

# to change the inflation
jq '.app_state.mint.minter.inflation = "0.300000000000000000"' genesis.json > temp.json && mv temp.json genesis.json
```

### Client Interaction

When instantiating a node, gRPC and REST are defaulted to localhost to avoid unknown exposure of your node to the public. It is recommended not to expose these endpoints without a proxy that can handle load balancing or authentication set up between your node and the public.

<Tip>
  A commonly used tool for this is [nginx](https://nginx.org).
</Tip>

## 3. Add genesis accounts

Earlier in this tutorial, you [created an account in the keyring](/sdk/latest/node/keyring#create-a-key) named `my_validator` under the `test` keyring backend.

Now, you can grant this account some `stake` tokens in your chain's genesis file. Doing so will also make sure your chain is aware of this account's existence:

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
simd genesis add-genesis-account $MY_VALIDATOR_ADDRESS 100000000000stake
```

Recall that `$MY_VALIDATOR_ADDRESS` is a variable that holds the address of the `my_validator` key in the [keyring](/sdk/latest/node/keyring#create-a-key). Also note that the tokens in the Cosmos SDK have the `{amount}{denom}` format: `amount` is an 18-digit-precision decimal number, and `denom` is the unique token identifier with its denomination key (e.g., `atom` or `uatom`). Here, `stake` tokens are granted, as `stake` is the token identifier used for staking in [`simapp`](https://github.com/cosmos/cosmos-sdk/tree/main/simapp). For your own chain with its own staking denom, that token identifier should be used instead.

## 4. Create genesis transaction

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](/sdk/latest/learn/intro/sdk-app-architecture#cometbft)) 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, your local node (created via the `init` command above) will be added 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`:

1. Create a gentx.

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
simd genesis gentx my_validator 100000000stake --chain-id my-test-chain --keyring-backend test
```

2. Add the gentx to the genesis file:

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
simd genesis collect-gentxs
```

A `gentx` does three things:

1. Registers the validator account you created as a validator operator account (i.e., the account that controls the validator).
2. Self-delegates the provided `amount` of staking tokens.
3. Link the operator account with a CometBFT node pubkey that will be used for signing blocks. If no `--pubkey` flag is provided, it defaults to the local node pubkey created via the `simd init` command above.

For more information on `gentx`, use the following command:

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
simd genesis gentx --help
```

## 5. Configure the node using `app.toml` and `config.toml`

The Cosmos SDK automatically generates two configuration files inside `~/.simapp/config`:

* `config.toml`: used to configure the CometBFT, learn more on [CometBFT's documentation](/cometbft/latest/docs/core/configuration),
* `app.toml`: generated by the Cosmos SDK, and used to configure your app, such as state pruning strategies, telemetry, gRPC and REST server 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 purposes of this tutorial, the minimum gas price is set to 0:

```toml theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
 # The minimum gas prices a validator is willing to accept for processing a
 # transaction. A transaction's fees must meet the minimum of any denomination
 # specified in this config (e.g. 0.25token1;0.0001token2).
 minimum-gas-prices = "0stake"
```

<Tip>
  When running a node (not a validator!) and not wanting to run the application mempool, set the `max-txs` field to `-1`.

  ```toml theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
  [mempool]
  # Setting max-txs to 0 will allow for an unbounded amount of transactions in the mempool.
  # Setting max_txs to negative 1 (-1) will disable transactions from being inserted into the mempool.
  # Setting max_txs to a positive number (> 0) will limit the number of transactions in the mempool, by the specified amount.
  #
  # Note, this configuration only applies to SDK built-in app-side mempool
  # implementations.
  max-txs = "-1"
  ```
</Tip>

## 6. Start the node

Now that everything is set up, you can finally start your node:

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
simd start
```

You should see blocks come in.

### What happens when the node starts

The `start` command (defined in [`server/start.go`](https://github.com/cosmos/cosmos-sdk/blob/release/v0.54.x/server/start.go)) boots up the full-node in the following sequence:

1. It opens the `db` (LevelDB by default) containing the latest persisted state. On first start, this is empty.
2. It creates a new instance of the application via an `appCreator` function, which is the [application constructor](/sdk/latest/learn/intro/sdk-app-architecture#constructor-function).
3. It instantiates a CometBFT node using the application. As part of `node.New`, CometBFT checks that the application's block height matches its own. If the application is behind, it replays blocks to catch up. If the height is `0`, it calls [`InitChain`](/sdk/latest/learn/concepts/baseapp#initchain) to initialize state from the genesis file.
4. Once in sync, the node starts its RPC and P2P servers and begins dialing peers. During the handshake, if the node is behind its peers, it queries missing blocks sequentially. Once caught up, it waits for new block proposals and validator signatures.

The previous command allows 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, [Docker Compose](https://docs.docker.com/compose/) can be leveraged to run a localnet. If you need inspiration on how to set up your own localnet with Docker Compose, refer to the Cosmos SDK's [`docker-compose.yml`](https://github.com/cosmos/cosmos-sdk/blob/release/v0.54.x/docker-compose.yml).

### Standalone App/CometBFT

By default, the Cosmos SDK runs CometBFT in-process with the application
If you want to run the application and CometBFT in separate processes,
start the application with the `--with-comet=false` flag
and set `rpc.laddr` in `config.toml` to the CometBFT node's RPC address.

## Logging

Logging provides a way to see what is going on with a node. The default logging level is `info`. This is a global level and all info logs will be outputted to the terminal. If you would like to filter specific logs to the terminal instead of all, then setting `module:log_level` is how this can work.

Example in `config.toml`:

```toml theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
log_level: "state:info,p2p:info,consensus:info,x/staking:info,x/ibc:info,*error"
```

### Verbose log level

Some operations, such as chain upgrades, emit additional log messages when a higher log level is active. You can control this with the `--verbose_log_level` flag:

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
simd start --verbose_log_level debug
```

See the [Log Overview](/sdk/latest/guides/testing/log) for more information on logging.

## 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](/cometbft/latest/docs/core/state-sync).

State sync works thanks to snapshots. Read how the SDK handles snapshots [here](https://github.com/cosmos/cosmos-sdk/blob/825245d/store/snapshots/README.md).

### Local State Sync

Local state sync works similarly 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 design considerations.

1. As mentioned in the [state sync documentation](/cometbft/latest/docs/core/state-sync), one must set a height and hash in the config.toml along with a few RPC servers (the aforementioned link has instructions on how to do this).
2. Run `<appd> snapshot restore <height> <format>` to restore a local snapshot (note: first load it from a file with the *load* command).
3. Bootstrapping Comet state to start the node after the snapshot has been ingested. This can be done with the bootstrap command `<app> comet 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 `cmd/<app>/root.go`:

```go theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
import (
    
  "github.com/cosmos/cosmos-sdk/client/snapshot"
)

func initRootCmd(/* ... */) {
  // ...
  rootCmd.AddCommand(
    snapshot.Cmd(appCreator),
  )
}
```

Then the 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

## Congratulations!

Your node is now running and producing blocks. You have successfully initialized a Cosmos SDK blockchain from scratch.

## Next steps

* [Interact with the node](/sdk/latest/node/interact-node) to send transactions and query state
* [Generate and sign transactions](/sdk/latest/node/txs) to learn advanced transaction workflows