ops/xone-signer-setup.sh takes an encrypted keystore file to a checked signer configuration in three steps: it proves the file holds the address you name, copies it into the datadir only when you pass --apply, and runs a read-only roles report. It never prints a key and never turns on block production. It arrived in PR #996 (merged 2026-11-15, closes #685) and is not in the v0.1.0 release.
For where keys live and the rotation rules, see key custody and seat rotation. For the whole validator path on net2040, see the net2040 validator guide.
How do I run it?
ops/xone-signer-setup.sh --keystore FILE --address 0xADDR --password FILE --datadir DIR [--network apothem] [--apply]
--keystore, --address, --password and --datadir are required. --network defaults to apothem. The password comes from a file, not from the command line. The script calls the xone binary named by $XONE (default xone) (xone-signer-setup.sh).
What does step 1 check?
Step 1 runs xone account verify-backup with the file, the password and --address. It passes only if the file unlocks with the password and holds exactly that address. If either is wrong, the script stops with exit status 1 and the message that nothing was configured. A malformed address (not 0x and 40 hex characters) stops it with exit status 2 before any step.
When does it write anything?
Only in step 2, and only with --apply. Then it runs xone account import-keystore, which copies the encrypted file into DIR/keystore. Without --apply the script says "skipped (no --apply): nothing is written". If the import is refused, for example because the address is already in the keystore, the script stops and the keystore is unchanged.
What does the roles report do?
Step 3 runs xone account roles --datadir DIR --etherbase 0xADDR --password FILE, a read-only identity report for that address. If it names a problem, the script stops and asks you to fix it before signing.
Does it turn on block production?
No. On success it prints the lines for /etc/xone/<network>.env (mode 600), with the EXTRA_ARGS=--mine ... line commented out on purpose. Producing blocks on a public network needs the owner's approval, and xone refuses --mine on mainnet (chain 50) in any case. The script tells you to run ops/xone-validator-readiness.py before you enable it; that tool is covered in the ops toolbox.
How is the script tested?
ci/test-xone-signer-setup.sh runs it against a stub xone binary with six fixtures: a wrong address, no import without --apply, an import with it, a refused import, a roles problem and a malformed address. PR #996 says a run against a real keystore was not repeated there; the xone account commands it calls have their own tests.
PR #996 also corrected a stale status line in docs/ops/keys.md, which had said the node does not call the signer.
How do other clients describe key setup?
| Client | What its documentation states | xOne |
|---|---|---|
| besu | QBFT validator keys; --security-module selects a hardware security module, as stated in the Besu QBFT guide |
A geth keystore v3 file, checked against its address before import; no HSM option is described |
Frequently asked questions
Does the script ever show my private key?
No. It calls only commands that print addresses and paths, and it takes the password as a file.
What happens if I pass the wrong address?
Step 1 fails: the file does not hold that address, so the script stops with exit status 1. Nothing is imported and nothing is configured.
Do I need --apply to test it?
No. Without --apply the script checks the file and runs the read-only roles report, and writes nothing.
Does the v0.1.0 release include the script?
No. It came in PR #996, merged on 2026-11-15, after v0.1.0. Use the script from main with a xone binary that has the account verify-backup, import-keystore and roles commands.
Sources
This article describes the source and evidence at its review date. Check the linked repository for current implementation and qualification status.
Explore the engineering evidenceEdit this page on GitHub opens the Markdown source (content/blog/signer-setup-script/index.md). GitHub may ask you to sign in. Report a correction opens a prefilled GitHub issue for this page.