Skip to main content
Now that you’ve built a module from scratch and walked through the full counter module, the next step is learning the workflow for running and validating a production-ready chain. This page shows how to start the chain locally, interact with it through the CLI, and use the main layers of testing before shipping changes.

​
Single-node local chain

Use a single-node chain for the fastest local development loop. It gives you one validator with predictable state so you can quickly test queries and transactions.

​
Start

This builds the binary, initializes chain data, and starts a single validator node. It handles cleanup automatically — existing chain state is reset on each run. The chain uses:
  • Chain ID: demo
  • Pre-funded accounts: alice, bob
  • Default denomination: stake

​
Stop

Press Ctrl+C in the terminal running make start.

​
Reset chain state

Re-running make start resets state automatically. There is no separate reset command.

​
Localnet (multi-validator)

Use localnet when you want a setup that is closer to a real network. It runs multiple validators in Docker so you can test multi-node behavior locally. For a multi-validator setup using Docker:

​
CLI reference

Once the chain is running, these are the core CLI commands you’ll use to inspect state and submit transactions.

​
Query commands

Use query commands to read module state without changing anything on-chain.

​
Transaction commands

Use transaction commands to submit state-changing messages to the chain.

​
Useful flags

These flags are the ones you’ll use most often while iterating locally.

​
Node Configuration

When you run make start, the chain creates ~/.exampleapp/config/ automatically and initializes two config files inside it:

​
app.toml

The most common settings to change during development:

​
config.toml

The settings most likely to change during development:

​
Unit tests

Start here when you want fast feedback on module logic without running a chain. These tests isolate the keeper and gRPC servers from the rest of the app. The unit test logic lives in the counter keeper package on main: the shared suite setup is in x/counter/keeper/keeper_test.go, message-path tests are in x/counter/keeper/msg_server_test.go, and query-path tests are in x/counter/keeper/query_server_test.go. The keeper test suite covers the keeper, msg server, and query server in isolation using an in-memory store and a mock bank keeper. No running chain is required.
To run with verbose output:
To run a specific test:
The test suite is structured around three files:

​
E2E tests

Run E2E tests when you want to verify the full request path against a real node. They give you higher confidence than unit tests, but take longer to complete. The E2E logic lives on main in tests/counter_test.go, which starts an in-process network, builds signed transactions, and verifies query results. The shared network fixture it uses is defined in tests/test_helpers.go. The E2E test suite starts a real in-process validator network and submits actual transactions against it. This tests the full stack: transaction encoding, message routing, keeper logic, and query responses.
E2E tests take longer than unit tests because they spin up a real node. Run them before merging significant changes.

​
Simulation tests

Simulation tests stress the chain with randomized activity to catch edge cases that targeted tests can miss. In this repo, that simulation flow is built with simsx, the Cosmos SDK’s higher-level simulation framework for defining random on-chain activity at the module level. The top-level simulation test commands on main run through sim_test.go. The counter module’s simsx registration lives in x/counter/module.go, the random MsgAdd generation lives in x/counter/simulation/msg_factory.go, and randomized counter genesis lives in x/counter/simulation/genesis.go. In practice, simsx lets each module describe three things: how to generate random starting state, which operations can happen during simulation, and how often each operation should be chosen. For x/counter, that means generating a random initial counter value, registering MsgAdd as a simulation operation, and assigning it a weight so the simulator knows how frequently to try it relative to other module operations. When you run a simulation target, the test harness repeatedly builds app instances, creates random accounts and balances, generates random transactions from the registered module operations, and executes them over many blocks. That makes simsx useful for catching issues that are hard to cover with hand-written tests, like state machine bugs, unexpected panics, invariant violations, and non-deterministic behavior across runs. Simulation runs the chain with randomly generated transactions to detect non-determinism and invariant violations.
Simulation requires the sims build tag, which the Makefile targets handle automatically.

​
Lint

Linting is the quickest way to catch style problems and common code-quality issues before CI or code review does. The lint commands are defined in the repo Makefile, which installs golangci-lint and runs it across the full module tree.
This installs and runs golangci-lint across the repository. To auto-fix issues where possible:

​
Test summary

Use this table as a quick reference for choosing the right validation command for the kind of change you made.