Local Network

Spin up a single-node local chain for contract testing, CLI experiments, and integration work without depending on public RPC.

When to use this

Use localnet for fast iteration. Use testnet for multi-party or public infra. Use bootstrap / state sync when you need real network state.

Prerequisites

terpd installed and on PATH — Environment installation or Install
jq (optional, for prettier queries)

Initialize a single-node localnet

Use a dedicated home directory so you do not clobber mainnet/testnet data:

export CHAIN_ID=localterp-1
export MONIKER=local-dev
export HOME_DIR=$HOME/.terpd-local
export DENOM=uthiol
export KEY=local-validator

# Clean previous localnet (destructive)
rm -rf "$HOME_DIR"

# Init
terpd init "$MONIKER" --chain-id "$CHAIN_ID" --home "$HOME_DIR"

# Key (test keyring is fine for disposable localnet)
terpd keys add "$KEY" --keyring-backend test --home "$HOME_DIR"

# Genesis account with balance
terpd genesis add-genesis-account \
  "$(terpd keys show "$KEY" -a --keyring-backend test --home "$HOME_DIR")" \
  1000000000000${DENOM} \
  --home "$HOME_DIR"

# Gentx + collect
terpd genesis gentx "$KEY" 100000000${DENOM} \
  --chain-id "$CHAIN_ID" \
  --keyring-backend test \
  --home "$HOME_DIR"

terpd genesis collect-gentxs --home "$HOME_DIR"
terpd genesis validate --home "$HOME_DIR"

CLI subcommand drift

Exact genesis subcommands vary slightly across Cosmos SDK versions (add-genesis-account vs nested genesis group). If a command fails, run terpd genesis --help / terpd --help on your binary and adjust. The intent is: init → key → funded genesis account → gentx → collect → validate → start.

Minimum gas prices

Edit $HOME_DIR/config/app.toml:

minimum-gas-prices = "0.0uthiol"

For local-only use, 0 is acceptable. Never run a public node with zero min gas.

Start the node

terpd start --home "$HOME_DIR"

In another terminal:

export HOME_DIR=$HOME/.terpd-local
terpd status --home "$HOME_DIR" | jq '.sync_info'
# catching_up should be false almost immediately on a single node

Default RPC is typically tcp://127.0.0.1:26657. REST/gRPC ports follow your app.toml.

Fund accounts and send txs

Additional keys on the same local chain:

terpd keys add alice --keyring-backend test --home "$HOME_DIR"

terpd tx bank send "$KEY" \
  "$(terpd keys show alice -a --keyring-backend test --home "$HOME_DIR")" \
  1000000uthiol \
  --chain-id "$CHAIN_ID" \
  --home "$HOME_DIR" \
  --keyring-backend test \
  --fees 500uthiol \
  -y

There is no public faucet on localnet — genesis balances and bank sends are the funding model. For public testnet faucet, see Quick start.

Deploy a contract (outline)

Build optimized WASM (Docker CosmWasm optimizer recommended)
terpd tx wasm store … --home $HOME_DIR …
Instantiate with the returned code id
Verify: recompute code hash and compare on-chain — Compile & verify code ID

Full CosmWasm workflow: CosmWasm guides.

Interact

terpd query bank balances \
  "$(terpd keys show alice -a --keyring-backend test --home "$HOME_DIR")" \
  --home "$HOME_DIR"

# If API is enabled in app.toml (api.enable = true)
curl -s "http://127.0.0.1:1317/cosmos/bank/v1beta1/balances/<terp1...>" | jq .

curl -s http://127.0.0.1:26657/status | jq '.result.sync_info'

Client libraries against http://127.0.0.1:26657: API libraries.

Multi-node and Docker

Multi-node local: out of scope for this page — use integration test harnesses (e.g. project e2e images) or tools like ignite / interchain test frameworks if your team standardizes on them.
Dockerized terpd: Install → Docker and Terp Core Docker.

Cleanup

# Stop the process (Ctrl+C), then:
rm -rf "$HOME_DIR"

Unsafe reset while keeping config (when supported):

terpd tendermint unsafe-reset-all --home "$HOME_DIR" --keep-addr-book

Verify

Check	Command / action
Chain ID	`jq -r .chain_id $HOME_DIR/config/genesis.json`
Node producing blocks	`terpd status --home $HOME_DIR` — height increases
Balances move	Bank send + query as above
Contracts (if used)	Local code hash vs on-chain checksum

P2P — how real networks discover peers
Governance — not needed on disposable localnet
Trustlessness — localnet is trusted by definition; still practice hash checks on WASM

Local Network

Local Network

Prerequisites

Initialize a single-node localnet

Minimum gas prices

Start the node

Fund accounts and send txs

Deploy a contract (outline)

Interact

Multi-node and Docker

Cleanup

Verify

Further reading

On this page