quai-node / the keepers / claim

Claim your node

Every keeper on the roll is state-proven: we check its state against the chain with quai_getProof, every few minutes. Claiming adds a second ring to its seal. It proves that whoever keeps the tag also holds the node's own p2p key, and it locks the tag to that node. It takes one command on the node, and the private key never leaves the machine.

on quai-node

quai-node keepers claim

It reads the key from quai-node's home and your tag from quai-node.toml, signs, sends, and prints the answer with your node's page.

anywhere else: your command

Type your tag, choose where the key is, copy, and paste it into bash or zsh on the node. This page watches for the claim to land, and your terminal prints the answer too.

What you need

› A node we've verified at least once. It reports with --node.quaistats (quai-node sets that up) and has passed our checks. A tag we haven't verified a node for can't be claimed yet: the claim is refused until it has.
› A shell on that node that can read its private.key.
› bash or zsh, xxd, curl and OpenSSL 3. Standard on current Linux. On macOS, install OpenSSL 3 with Homebrew. quai-node's own keepers claim needs none of them.

The command, line by line

Read it before you run it. It's short on purpose.

KEY="$HOME/.local/share/quai-node/config/private.key": Where the node's p2p identity key lives. quai-node keeps it in config/ under its home (on macOS, ~/Library/Application Support/quai-node). Stock go-quai keeps it in ~/.config/go-quai, unless you start it with --node.private-key or --global.config-dir. In Docker, point it at the key inside your volume.
M="quainode.org keeper claim v1 tag=YourTag ts=$(date +%s)": The exact text you sign: this site, your tag and the current time. Nothing else.
F=$(mktemp); printf %s "$M" > "$F": Writes that one line to a fresh temporary file, because openssl's Ed25519 signing reads its input from a file. It's removed at the end.
xxd -p -s 36 -l 32 "$KEY": Reads the node's public key, the last 32 bytes of private.key. Your node ID is derived from it.
(printf 302e…0420; xxd -p -s 4 -l 32 "$KEY") | xxd -r -p: Wraps the private key's 32-byte seed in the standard format openssl expects and hands it to openssl through a pipe. It's never written anywhere.
openssl pkeyutl -sign -rawin …: Signs the line with the node's key (Ed25519).
curl -s https://keepers.quainode.org/v1/claim …: Sends three things: the line, the public key and the signature. Prints our answer.
rm -f "$F": Removes the temporary line.

What we check

01The line is ours and current. It must read exactly quainode.org keeper claim v1 tag=… ts=…, and the time must be within 10 minutes of now.
02The signature is real. We verify it against the public key you sent. A wrong or edited line fails here.
03It's fresh. Each claim must be newer than the last one accepted for the tag, so an old signature can't be replayed.
04We know the node. The tag exists and its node has passed our checks at least as far as the p2p step. There's no claiming ahead of time.
05The key is that node's. Your node ID comes from the public key, and it must equal the ID of the node we verify for your tag. Nobody else can claim your node.

What leaves your machine

✓ The node's public key, which it already announces to every peer on the Quai network.
✓ One signed line naming this site, your tag and the time. It can't be reused anywhere else, and it can't be reused here.
✗ Never the private key, and never your stats secret.

Locked to its node

Once a tag is claimed, it belongs to that node. Verification fails for any other node reporting under the tag, so the tag can't be pointed at another machine by whoever knows the secret.

› Why. go-quai sends the stats secret over plain HTTP on its first hop, so someone on that path could read it. The lock means a sniffed secret can't move a live, claimed tag to someone else's node.
› Moving to a new machine, or a new private.key: claim again from the new node once the old one has been off the roll for 7 days. Until then the new node fails its checks under this tag, and our answer says which node holds it.
› Ran it on the wrong machine? Run it on the old node instead: that one still matches, and it renews the claim.
› Your node stops passing checks. It leaves the roll, and the second ring with it. Both come back when it passes again, with nothing to redo.

If something goes wrong

Our answers, roughly as your terminal prints them, and what to do:

✗ … claim once it has passed its checks: We haven't verified a node for your tag yet. Let go-quai log in and pass its checks (quai-node keepers status, or the status page), then claim.
✗ YourTag is claimed by node … To move the tag, claim from the new node once the old one has been off the roll for 7 days, or run this on the old node.: The tag is locked to another node (section 6). If you moved the node, wait out the 7 days. If you meant the old node, run it there.
✗ That key belongs to node …, but the node we verify for YourTag is …: You ran it on a different machine, or KEY points at another node's key. Run it on the node that reports as your tag.
✗ Couldn't read your node's public key: KEY doesn't point at a go-quai private.key. Check the path, and pick the right one in the box above.
✗ openssl didn't produce an Ed25519 signature: You need OpenSSL 3 (openssl version). macOS ships LibreSSL: brew install openssl, then use $(brew --prefix openssl)/bin/openssl. Or use quai-node keepers claim.
✗ Your node's clock is … minutes off: Sync the clock (timedatectl set-ntp true) and run it again.
✗ Too many claim attempts: We limit claims per address. Wait 10 minutes.
bash: syntax error near unexpected token `(': You're in sh or dash. Run bash first, then paste the command.

Still stuck? Your node's status page shows every check we ran and where your claim stands.