Gno Land Topaz Cheat Sheet and Key Management

This guide provides essential commands for managing wallets, nodes, and validators on topaz. Make sure the environment variables mentioned at the end (and GNOROOT) are correctly configured before using these commands.

1. Key Management

Create a New Wallet

gnokey add $WALLET

Keep the generated seed phrase safe. It is the only way to recover your wallet.

Recover Wallet from Seed Phrase

gnokey add $WALLET --recover

You will be prompted to enter your seed phrase.

List Wallets

gnokey list

Delete Wallet

gnokey delete $WALLET

INFO

Unlike Cosmos SDK chains, gnokey doesn't have a keys show subcommand. Get your address from gnokey list — the g1... address next to your key name.

2. Wallet Operations

Check Balance

gnokey query \
  -remote "https://rpc.topaz.testnets.gno.land" \
  auth/accounts/$(gnokey list | grep -oP 'addr: \K\S+')

Send Tokens

gnokey maketx send \
  -send "<amount>ugnot" \
  -to "<receiver_address>" \
  -gas-fee 1000000ugnot \
  -gas-wanted 10000000 \
  -broadcast \
  -chainid "topaz-1" \
  -remote "https://rpc.topaz.testnets.gno.land" \
  $WALLET

Example:

gnokey maketx send \
  -send "1000000ugnot" \
  -to "g1...yyy" \
  -gas-fee 1000000ugnot \
  -gas-wanted 10000000 \
  -broadcast \
  -chainid "topaz-1" \
  -remote "https://rpc.topaz.testnets.gno.land" \
  $WALLET

3. Validator Management

Ensure your operator wallet ($WALLET) holds enough ugnot for the registration gas fee — request a drip from the faucet if it's empty.

ℹ️ Registration also incurs a storage fee on top of the gas fee, charged for the bytes your profile data adds to permanent chain state (shown as STORAGE FEE in the tx result). Budget extra GNOT beyond --gas-fee for this.

⚠️ Two different pubkeys exist — don't mix them up: gnoland secrets get validator_key → pub_key is your validator/node pubkey and is what goes in Register/UpdateSigningKey. gnokey list → pub: is your wallet/operator pubkey and never belongs in the validator-pubkey argument. Submitting the wrong one won't error — it succeeds with a broken profile, and fixing it via UpdateSigningKey is throttled (see §3.1 Fixing a Wrong Validator Pubkey).

Register as Validator Candidate

Configuration:

Description

Infrastructure type

Validator pubkey

Generated Code:

Loading...

Parameter Explanation:

Parameter	Details
$MONIKER	Your node's moniker, pulled from .bash_profile.
Description	Short description of your validator (2048 char limit).
Infrastructure	One of cloud, on-prem, data-center.
Operator address	Your g1... wallet address — must be the signer of this tx.
Validator pubkey	The pub_key from gnoland secrets get validator_key — not the address in that same output, and not your gnokey list pubkey.
$WALLET	Wallet used for the transaction.

⚠️ NOTE

Registering only lists you as a candidate on the valoper realm. You only join the active validator set once a GovDAO member creates and passes a proposal via r/sys/validators/v3 — there's no self-service "create-validator" transaction like on Cosmos SDK chains.

Get Validator Pubkey

cd $HOME && gnoland secrets get validator_key

Run this from $HOME (or wherever gnoland-data lives) without -data-dir after the positional argument — putting -data-dir after validator_key causes an internal panic on some builds. If you need -data-dir explicitly, put it before the positional arg: gnoland secrets get -data-dir $HOME/gnoland-data validator_key.

Update Validator Description

gnokey maketx call \
  --pkgpath gno.land/r/gnops/valopers \
  --func UpdateDescription \
  --args "$(gnokey list | grep -oP 'addr: \K\S+')" \
  --args "<new-description>" \
  --gas-fee 1000000ugnot \
  --gas-wanted 90000000 \
  --chainid topaz-1 \
  --remote https://rpc.topaz.testnets.gno.land \
  --broadcast \
  $WALLET

Fixing a Wrong Validator Pubkey

If Register was submitted with the wrong pubkey, rotate it with UpdateSigningKey — no need to re-register:

gnokey maketx call \
  -pkgpath "gno.land/r/gnops/valopers" \
  -func "UpdateSigningKey" \
  -args "$(gnokey list | grep -oP 'addr: \K\S+')" \
  -args "<CORRECT_VAL_PUBKEY>" \
  -gas-fee 1000000ugnot \
  -gas-wanted 90000000 \
  -send "" \
  -broadcast \
  -chainid "topaz-1" \
  -remote "https://rpc.topaz.testnets.gno.land" \
  $WALLET

⚠️ NOTE

• Fee scales with gas-wanted. topaz's minimum block gas price is 10ugnot/1000gas. -gas-fee 1000000ugnot covers -gas-wanted up to ~100,000,000 — if you raise gas-wanted well beyond that, raise gas-fee to match or you'll hit InsufficientFeeError.
• Rotation is throttled (ChainHeight() - LastRotationHeight >= rotationPeriodBlocks), and the timer starts at Register, not at your first rotation attempt. If you get rotation throttled: try again later, wait and retry with an incremented -account-sequence (a failed DeliverTx still consumes the sequence).
• Key reuse is permanently blocked — once a pubkey is used (active or retired), the registry never accepts it again. Verify the new pubkey before broadcasting.

Check Your Valoper Profile / Active Set

• Registered candidates: https://topaz.testnets.gno.land/r/gnops/valopers
• Active validator set: https://topaz.testnets.gno.land/r/sys/validators/v3

4. Node Status & Info

Check Sync Status

curl -s http://localhost:${GNOLAND_PORT}657/status | jq .result.sync_info

Check Peer Count

curl -s http://localhost:${GNOLAND_PORT}657/net_info | jq .result.n_peers

Show Node ID

cd $HOME && gnoland secrets get node_id

Restart Node

sudo systemctl restart gnoland

View Node Logs

sudo journalctl -u gnoland -f --no-hostname -o cat

5. Backup & Key Safety

File	Backup?	Notes
gnoland-data/secrets/priv_validator_key.json	Yes — critical	Your validator's consensus signing key. Losing it means losing your validator identity.
gnoland-data/secrets/node_key.json	Yes	Your node's P2P identity (node_id). Not critical, but avoids peers needing to re-trust a new ID.
Operator wallet mnemonic (gnokey add)	Yes — critical	Controls your g1... account used to sign transactions. Store it outside the server.
gnoland-data/secrets/priv_validator_state.json	No	Runtime signing state — never copy this onto another node alongside the same validator key, doing so risks double-signing.
gnoland-data/config/genesis.json, config.toml	No	Reproducible from the setup steps.
gnoland-data/db/, wal/	No	Blockchain data, re-syncable from peers.

6. Common Pitfalls

• panic: gno was unable to determine GNOROOT — GNOROOT isn't set in your current shell. Export it (export GNOROOT=$HOME/gno), and add it to both ~/.bashrc and ~/.bash_profile so it persists across sessions.
• invalid data directory provided — gnoland secrets/gnoland config commands resolve the default gnoland-data path relative to your current working directory. Run the command from $HOME, or pass -data-dir $HOME/gnoland-data explicitly.

7. Environment Variables

Make sure to set these in your ~/.bash_profile and ~/.bashrc (so they load in every shell, not just login shells):

export WALLET="wallet"
export MONIKER="YourMoniker"
export GNOLAND_CHAIN_ID="topaz-1"
export GNOLAND_PORT="54"
export GNOROOT="$HOME/gno"
export PATH="/usr/local/go/bin:$HOME/go/bin:$PATH"

Apply the changes with:

source ~/.bashrc

---

This cheat sheet is provided to streamline topaz validator and wallet management.