Skip to content

docs(runbooks): operator-keyring setup for the BYO validator migration#383

Merged
bdchatham merged 1 commit into
mainfrom
docs/runbook-operator-keyring
Jun 3, 2026
Merged

docs(runbooks): operator-keyring setup for the BYO validator migration#383
bdchatham merged 1 commit into
mainfrom
docs/runbook-operator-keyring

Conversation

@bdchatham
Copy link
Copy Markdown
Collaborator

Adds an Operator account keyring section to migrating-validator-to-byo-secrets.md, capturing the procedure exercised live on arctic-1 node-19 (whose validator now mounts the operator key for on-node governance voting).

Covers:

  • Identifying the operator account on-chain from the consensus pubkey → valoper → operator account, and checking for delegated authority (authz grants / redirected withdraw address).
  • Converting admin_key.json (a seid keys add --output json mnemonic export) into a file-backend keyring — including the --recover stdin gotcha (it reads mnemonic and passphrase from stdin; feed all three lines or the prompts hit EOF).
  • Two distinct SOPS Secrets (keyring + passphrase) using data:/base64 — not stringData — because .info/keyhash are exact-byte sensitive, with an encoding-validation check (decode → JWE / bcrypt) before commit, and the "base64 ≠ encrypted" reminder.
  • Wiring validator.operatorKeyring (four distinct secretNames, CEL-enforced) + the on-node seid tx gov vote command.
  • The security tradeoff (full operator key = treasury+gov authority on an internet-exposed pod under shareProcessNamespace) and the safer authz MsgVote-only alternative, so the choice is deliberate.

Follow-up to #382 (the original migration runbook). Content is grounded in the node-19 setup we just executed + verified on-chain.

Captures the procedure exercised on arctic-1 node-19: identifying the operator
account on-chain from the consensus pubkey (+ checking authz/withdraw delegation),
converting a `seid keys add --output json` admin_key.json into a file-backend
keyring (with the stdin mnemonic+passphrase feeding gotcha), the two distinct
SOPS Secrets (data/base64 for exact-byte fidelity, not stringData), the encoding
validation, and wiring validator.operatorKeyring into the SND.

Includes the security tradeoff (full operator key = treasury+gov on an
internet-exposed pod under shareProcessNamespace) and the safer authz MsgVote-only
alternative, so future operators choose deliberately.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@cursor
Copy link
Copy Markdown

cursor Bot commented Jun 3, 2026

PR Summary

Low Risk
Documentation-only; no runtime or cluster behavior changes.

Overview
Extends migrating-validator-to-byo-secrets.md with an Operator account keyring subsection so BYO validator migrations can optionally mount on-node governance/operator signing (arctic-1 node-19 pattern).

The migration table now points optional operatorKeyring at that section. New content covers when to mount (vs off-node operator use), blast radius (treasury/gov vs consensus-only slashing) and the authz MsgVote-only alternative under shareProcessNamespace, on-chain operator resolution from the consensus pubkey plus authz/withdraw checks, admin_key.json → file keyring import (including seid keys add --recover stdin), two SOPS data: secrets (keyring vs passphrase, byte-exact encoding checks), and validator.operatorKeyring SND wiring with four distinct secret names plus on-node seid tx gov vote.

Reviewed by Cursor Bugbot for commit 8cd476e. Bugbot is set up for automated code reviews on this repo. Configure here.

@bdchatham bdchatham merged commit 1b26c5c into main Jun 3, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant