docs: Fix operator runbook config template and key-setup guidance#804
Merged
Conversation
|
Collaborator
Style Guide AuditAudited 1 file(s) against the Sui Documentation Style Guide. 2 violation(s) found. All must be fixed before merge.
|
bmwill
approved these changes
Jul 13, 2026
Bridgerz
force-pushed
the
docs-operator-config-fixes
branch
from
2d2848c to
30ee0a8
Compare
Fixes from validator onboarding feedback: - The validator config template put [hashi-ids] and [bitcoin-rpc-auth] mid-file, so every top-level key after them (bitcoin-chain-id, bitcoin-rpc, db, backup-*, all tuning keys) silently nested under those tables and the server panicked on a missing db. Sections now sit at the end with an explicit field-order warning. The template was verified to parse with the intended structure. - backup-pgp-cert claimed to accept a file path; the config field only accepts inline armored text (paths work only on the CLI override). Docs now show the inline multi-line form. - Documented how to generate the operator/TLS keys (openssl PKCS#8 PEM) and that sui keytool output formats are not accepted. - Unified the operator-address placeholders in 2.3/2.4 and clarified that one registration tx both registers and delegates, with re-runs idempotent.
Addresses the Style Guide Audit on the PR: no em dashes in prose, and 'for example' instead of 'e.g.'. Also cleans the two em dashes inside the config template comments that the audit did not flag.
The config field now resolves file paths (custom deserializer added in #806), so the original path-or-inline wording is accurate again; drop this PR's inline-only rewrite.
Operators asked whether newer Bitcoin Core releases (v31.x) are supported; per Brandon, any version >= v29 works.
Bridgerz
force-pushed
the
docs-operator-config-fixes
branch
from
30ee0a8 to
b2f149a
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes for issues validators hit during testnet onboarding (reported by ContributionDAO, Staking Facilities, Chainode Tech, Brightlystake, and Michal Zegarek in the operator channel).
Bitcoin Core version is a minimum, not a target
§1.5 said "Hashi targets Bitcoin Core v29", which read as an exact-version requirement. Per Brandon: any v29+ works, including the latest release. Now stated as "v29 or newer".
TLS key generation
Added the
openssl genpkeycommand to §2.2 and a file-permissions note (an unreadable TLS key file caused an incomplete registration; the loud-failure code fix is #805). TLS keys remain PEM/DER-only — unaffected by the new multi-format operator-key loading.§2.3 vs §2.4 confusion
Both sections showed the same
hashi registercommand with differently-named placeholders, and it wasn't stated whether that address is the validator address or the fresh operator key. Unified the placeholder, stated it's the operator key's address, and clarified that one registration tx both registers and delegates — re-running is idempotent.Config template polish (on top of #807)
A prose "field order matters" note above the template (describing the post-#807 unknown-field error), and the
[hashi-ids]template comment now points at the Networks table where the published IDs live.Dropped as superseded
Also includes the style-guide audit fixes (no em dashes in prose, "for example" instead of "e.g.").