Skip to content
Available on private testnetTestnet: yesMainnet: Not availableSoftware: Core bad4a06ea · protocol pqwerai-v8-testnet/1Updated

Set up a Smartnode

Smartnodes are stake-backed validators. They do not produce blocks (GhostRider miners do); they sign checkpoint votes every 32-block epoch, and a checkpoint signed by more than 2/3 of the epoch set's effective stake becomes final. Validators earn 19.8 % of block issuance for active duties and lose 25 % of stake (burned) for equivocation.

What was tested for this page

Key generation and the registry/finality reads below were executed against the local testnet. Registration, delegation and exit were not re-run for this documentation release because a registered validator that does not sign reduces finality participation on the shared test network; those commands come from the operator guide and the Windows Wallet's tested Smartnode page.

1. Requirements and custody

  • A host that runs a synced node and exactly one signer per validator key, ever. Two signers with the same key will equivocate and be slashed.
  • An owner account (secp256k1, holds the stake, receives rewards) — keep it in a wallet, not on the validator host.
  • A BFT key (Ed25519) generated on the validator host. Only its public field ever leaves the host.
  • The signer's anti-equivocation journal must never be restored from an old backup (the backup tool skips it on purpose).

2. Generate the validator key (on the validator host)

smartnode/keygen-and-inspect.sh
# Run ON THE VALIDATOR HOST. Generates an Ed25519 BFT key encrypted with your password file;
# only the "public" field may ever leave the host.
umask 077
pqwerai-cli -password-file sn.password sn-keygen -out sn-key.json
python3 -c 'import json; k=json.load(open("sn-key.json")); print("public:", k["public"])'
# Registry state and finality health (read-only).
pqwerai-cli -rpc "$RPC" sn-validators
pqwerai-cli -rpc "$RPC" sn-status

validator_id=1d2a21ddbc47f37ec09101dcefa8be922726e3bb5152a8cef50c4b2c29ab2f18
public: 1196c0bfb3d92132683f5d699f93def1b4027e1f63f1301c18b7fd9496976e04
[{"activation_epoch":0,"delegated_gwei":0,"id":"9a73…","owner":"0x4780…","stake_gwei":32000000000,"status":"exiting"}, …]
{"finality":true,"finalized_height":4448,"head":4501,"validators":5,"epoch_set_size":2, …}

3. Register and stake

Parameter Value
Minimum stake 1 PQAI (genesis validators: 32 PQAI)
Maximum effective stake 2048 PQAI
Activation delay 2 epochs (64 blocks)
Unbonding 4 epochs, and the withdrawable epoch must be BFT-finalized
Max active set / registered 64 / 256 
# from the machine that holds the OWNER key; the proof of possession binds key, owner, chain ID and genesis
pqwerai-cli -rpc "$RPC" -keystore <owner-keystore-dir> -password-file owner.pw \
  sn-register -from 0xOwner -keyfile sn-key.json -stake 32

Genesis validators instead send their public key and payout address to the network owner before the genesis ceremony. The Windows Wallet offers the same flow under Smartnodes → Register (Advanced mode).

4. Run the signer (voting)

sudo systemctl enable --now pqwerai-validator@<name>    # key + password in /etc/pqwerai/validator/<name>/ (0600)

The signer fetches the next checkpoint link (g4_link), signs it, and submits it to its own node with g4_submitVote. The node verifies the signature against the epoch validator set, rejects replays and stale votes, and relays a certificate once a quorum exists. These are operator interfaces: never expose them publicly.

5. Delegation, rewards, rotation, exit

pqwerai-cli … sn-delegate   -from 0xDelegator -id <validator id> -amount 5    # min 0.001 PQAI
pqwerai-cli … sn-undelegate -from 0xDelegator -id <validator id> -amount 5
pqwerai-cli … sn-claim      -from 0xOwner -id <validator id>
pqwerai-cli … sn-rotate     -from 0xOwner -id <validator id> -keyfile new-key.json   # then restart the signer
pqwerai-cli … sn-exit       -from 0xOwner -id <validator id>
pqwerai-cli … sn-withdraw   -from 0xOwner -id <validator id>   # only after unbonding + finality
pqwerai-cli … sn-slash      -from 0xAnyone -vote-a <hex> -vote-b <hex>   # report double/surround votes

Registry operations are ordinary transactions to the registry system account (gas 150,000 each); see Registry operations.

6. Finality health

  • g4_status.finalized_height should advance every one or two epochs.
  • With less than 2/3 of stake signing, PoW blocks continue but finality stalls until quorum returns.
  • Candidate liveness/v1 genesis profile (experimental, active on the local testnet): validators that carry no vote for K consecutive checkpoints are force-exited (not slashed); g4_status.liveness_ejected_validators counts them.

Common errors

Error Cause
vote does not authenticate against the checkpoint validator set Key not in the epoch set yet (activation delay) or wrong key
stale vote: target at or below the finalized checkpoint Signer behind; harmless
withdraw refused Unbonding not complete or withdrawable epoch not yet finalized
signer refuses to sign Its journal detected a would-be double or surround vote — do not delete the journal

Sources at 72057fe3ec: testnet/release/network/GUIDES.md · testnet/release/network/network.json · developers/examples/smartnode/keygen-and-inspect.sh

Found a problem? Report a documentation issue · Build testnet-rc1+72057fe3ec