docs(staking): expand Owner/Operator/ValidatorWallet key model section

[MuncleUscles]

Why

Validators repeatedly ask which keys their node actually holds and how the owner/operator/ValidatorWallet relate — most recently someone discovered their previous devops never handed over the owner key. The current section is three sentences and doesn't answer the questions people actually have (which keys live on the server, what happens if a key is lost, where funds go).

What changed

staking.mdx — expanded Owner, Operator, and ValidatorWallet (heading/anchor unchanged):

• Mermaid diagram of the three entities and how funds flow
• Clarifies the ValidatorWallet is a contract, not a key; the node holds exactly one key (the operator); the owner key never touches the server and cannot be extracted from it
• "Which key does what" comparison table
• New "Key rotation and loss scenarios" subsection: operator rotation via setOperator or the two-step initiateOperatorTransfer flow; owner key loss is unrecoverable (no admin override) — with a warning callout for inherited validators
• Terminology callout mapping community terms ("node key" / "validator key" / "rewards key") to the operator key
• Short lifecycle summary with cross-links to the setup guide and CLI docs

setup-guide.mdx + content/validators/config.yaml:

• Added an explicit "back up the owner wallet" warning to the address table (the wizard's keystore export only covers the operator key)
• Fixed a misleading comment: the operator performs consensus duties for the ValidatorWallet — it does not own it (edited in content/validators/config.yaml, the source the setup-guide block is regenerated from)

Verification

• Content cross-checked against genlayer-consensus v0.6 (ValidatorWalletBlueprint.sol, StakingValidators.sol, spec 04-staking-system.md) and genlayer-node (config/keystore/signer wiring)
• All documented rotation functions (setOperator, initiateOperatorTransfer/completeOperatorTransfer/cancelOperatorTransfer, transferOwnership) confirmed present on the deployed Bradbury ValidatorWallet implementation (0x5f9DCdcEfAB114da8387d6Bf8cFd75E8d3bb6BB4) via read-only cast calls; confirmed no recovery path exists for a lost owner key
• Rendered locally with pnpm dev: Mermaid diagram renders, callouts/tables/anchors and cross-page links work

Summary by CodeRabbit

• Documentation
  • Clarified validator terminology and responsibilities across the docs, including the roles of owner, operator, and validator wallet.
  • Expanded the staking guide with a clearer breakdown of key ownership, rotation, and loss scenarios, plus a visual diagram and comparison table.
  • Updated the validator setup guide to better explain which key is backed up and the consequences of losing the owner key.
  • Refined a configuration comment to better describe the operator’s role in consensus duties.

[netlify]

✅ Deploy Preview for genlayer-docs ready!

Name	Link
🔨 Latest commit	b00e721
🔍 Latest deploy log	https://app.netlify.com/projects/genlayer-docs/deploys/6a4d043c8ad3b70008565cfa
😎 Deploy Preview	https://deploy-preview-440--genlayer-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: ca16e1ab-0923-4136-8d1a-4e2adb06df1e

📥 Commits

Reviewing files that changed from the base of the PR and between 19558ee and b00e721.

📒 Files selected for processing (3)

• content/validators/config.yaml
• pages/understand-genlayer-protocol/core-concepts/optimistic-democracy/staking.mdx
• pages/validators/setup-guide.mdx

---

📝 Walkthrough

Walkthrough

Documentation-only changes clarify the roles of owner and operator keys relative to the ValidatorWallet. The staking concepts page adds a Mermaid diagram, a responsibilities table, and key rotation/loss guidance. The setup guide and config.yaml comments are updated to correct the operator address description and add owner key backup instructions.

Changes

Owner/Operator Terminology Clarification

Layer / File(s)	Summary
Staking concepts rewrite pages/understand-genlayer-protocol/core-concepts/optimistic-democracy/staking.mdx	Adds a Callout import, a Mermaid diagram, an expanded "which key does what" table, key rotation/loss guidance, and rewritten step-by-step flow describing ValidatorWallet, owner key, and operator key relationships.
Setup guide and config comment updates pages/validators/setup-guide.mdx, content/validators/config.yaml	Updates the "Understanding Validator Addresses" callout to require backing up the owner wallet key and clarify keystore export scope, and corrects the operatorAddress comment to describe consensus duties for the ValidatorWallet.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• genlayerlabs/genlayer-docs#308: Overlapping updates to setup-guide.mdx and config.yaml clarifying Owner vs Operator roles and config fields.
• genlayerlabs/genlayer-docs#309: Both PRs rework the "Owner, Operator, and ValidatorWallet" concepts in staking.mdx.

Suggested reviewers: cristiam86

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is clear, specific, and matches the main docs change.
Description check	✅ Passed	The description covers motivation, changes, and verification, even though it uses Why/What changed/Verification instead of the template's Description heading.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/validator-key-roles

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}