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.