QUACDocs

Operating

Running a node

This page covers running quacd yourself: a local devnet, the configuration files, and what each setting QUAC changes is for.

Build

make build         # build/quacd, build/quacfaucet for this machine
make build-linux   # build/linux-amd64/… static binaries for servers

QUAC is pure Go (CGO_ENABLED=0 works), so cross-compiling needs no C toolchain.

The devnet script

scripts/devnet.sh creates and runs a single-node chain in .devnet/.

scripts/devnet.sh init    # wipe .devnet/, create keys and genesis
scripts/devnet.sh start   # exec quacd start

Environment overrides:

Variable Default Meaning
QUACD build/quacd (or .exe) Binary to use
QUAC_HOME .devnet Node home directory
CHAIN_ID quac-devnet-1 Chain ID

init runs these steps:

quacd init devnet-node --chain-id quac-devnet-1     # ML-DSA-65 consensus key by default
quacd keys add validator|alice|bob                  # ML-DSA-65 account keys
quacd genesis add-genesis-account validator 100000000000000uquac
quacd genesis add-genesis-account alice     1000000000000uquac
quacd genesis gentx validator 10000000000000uquac   # self-delegation, ML-DSA-signed
quacd genesis collect-gentxs
quacd genesis validate

It then edits the configuration (enable_api):

File Setting Value Why
config.toml consensus.timeout_commit 1s Fast blocks for development
app.toml api.enable true REST API on localhost:1317 for the explorer
app.toml api.enabled-unsafe-cors true Let browser pages on other origins call the API
config.toml rpc.cors_allowed_origins ["*"] Same for the CometBFT RPC
app.toml grpc.address localhost:9190 Off the default 9090, see below

The gRPC port pitfall. In Cosmos SDK v0.55, the gRPC server and the REST API run in one error group. If gRPC can't bind its port, the group cancels and the REST API shuts down too, with only a "stopping API server" line in the log. Port 9090 is a common default for Prometheus and other tools, so QUAC's scripts move gRPC to 9190.

The home directory

.devnet/
├── config/
│   ├── app.toml                  application settings (API, gRPC, gas price, pruning)
│   ├── config.toml               CometBFT settings (P2P, RPC, consensus timeouts)
│   ├── client.toml               CLI defaults (chain-id, keyring, node)
│   ├── genesis.json              the chain's starting state
│   ├── node_key.json             P2P identity (Ed25519)
│   └── priv_validator_key.json   consensus key (ML-DSA-65). Back this up, and never run two nodes with it.
├── data/                         blocks, state, priv_validator_state.json
└── keyring-test/                 account keys (test backend)

Settings that matter

app.toml

Setting QUAC default Notes
minimum-gas-prices 0.0025uquac Set by initAppConfig in cmd/quacd/cmd/commands.go. Nodes reject cheaper transactions.
api.enable false Turn on for nodes that serve the explorer or wallets.
api.address tcp://localhost:1317 Keep it on localhost and put a proxy or tunnel in front.
grpc.address localhost:9090 Scripts move it to 9190.
pruning default Keeps recent state; set nothing for archive nodes.

config.toml

Setting Notes
p2p.persistent_peers nodeid@host:26656 entries to always stay connected to.
p2p.external_address What this node advertises to peers. The testnet leaves it empty, so the node never publishes its IP.
p2p.pex Peer exchange. Off on the testnet, which has a fixed peer set.
rpc.laddr tcp://127.0.0.1:26657: RPC on localhost only.
consensus.timeout_commit Pause after each block. Block time ≈ this + voting time.

Validator operations

# Is the node in sync?
quacd status | jq .sync_info

# This node's consensus public key (ML-DSA-65, base64)
quacd comet show-validator

# Create a validator from a funded account (on a running chain)
quacd tx staking create-validator validator.json --from mywallet --chain-id quac-testnet-1 \
  --gas auto --gas-adjustment 1.4 --gas-prices 0.0025uquac

# Unjail after downtime slashing
quacd tx slashing unjail --from mywallet --chain-id quac-testnet-1 --gas auto --gas-prices 0.0025uquac

validator.json includes "pubkey" from quacd comet show-validator. On QUAC it must be a /cosmos.crypto.mldsa65.PubKey, or x/staking rejects it.

Running as a service

The testnet servers use this systemd unit (written by deploy/testnet/install-node.sh):

[Unit]
Description=QUAC testnet node (quacd)
After=network-online.target
Wants=network-online.target

[Service]
User=quac
ExecStart=/usr/local/bin/quacd start --home /var/lib/quac/.quacd
Restart=always
RestartSec=5
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target

The node runs as an unprivileged quac user with its home at /var/lib/quac/.quacd (mode 700).

Resource use

Measured on the testnet with four validators:

  • Memory: a node uses about 300–800 MB.
  • Disk: each block stores one 3,309-byte signature per validator, so with four validators about 13 KB per block goes to signatures, or about 80 GB a year at 5-second blocks before pruning. Pruned nodes keep far less.
  • Hardware: 4 GB RAM and 40+ GB of disk is comfortable for a testnet node.

Edit this page on GitHub