CON-349: Update Spec and Website related to the validator Exit flow

[cgmello]

Summary by CodeRabbit

• Documentation
  • Updated staking documentation to clarify the validator exit process with a detailed timeline showing the two-step exit mechanism where exit is scheduled but rewards stop only after processing in the next epoch, with visibility into the interim period when validators remain active before being officially removed.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[netlify]

❌ Deploy Preview for genlayer-docs failed. Why did it fail? →

Name	Link
🔨 Latest commit	75e531f
🔍 Latest deploy log	https://app.netlify.com/projects/genlayer-docs/deploys/693c667f79d4100007993d85

[coderabbitai]

Walkthrough

The documentation clarifies validator exit mechanics, replacing an immediate exit model with a detailed epoch-by-epoch timeline spanning epochs N through N+7, specifying when exit is scheduled, when rewards stop, when the validator is removed from participation, and when tokens become claimable.

Changes

Cohort / File(s)	Change Summary
Documentation Update pages/understand-genlayer-protocol/core-concepts/optimistic-democracy/staking.mdx	Clarifies validator exit flow from a single-step to multi-epoch process, detailing state changes across Epoch N (exit scheduled), N+1 (exit processed, rewards stop), N+2 (marked inactive), and N+7 (tokens claimable). Replaces assertion of immediate reward cessation with explicit timeline of validator participation removal.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

• Verify technical accuracy of the epoch-by-epoch timing sequence against protocol implementation
• Confirm the clarification aligns with actual staking contract behavior to avoid documentation drift

Poem

A validator bids farewell with grace,
Exit scheduled—but keeps their place!
One epoch more they earn their share,
Then out they go without a care.
Seven epochs to claim their stake— 🐰✨
Timing's clear, no more mistakes!

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The pull request description is missing entirely; no description was provided by the author despite the repository template requiring one.	Add a detailed pull request description following the template, including what was changed and why. Reference issue CON-349 and explain the validator exit flow updates.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the main change as an update to documentation related to validator exit flow, with reference to ticket CON-349.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch CON-349-updated-docs

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 1895087 and 75e531f.

📒 Files selected for processing (1)

• pages/understand-genlayer-protocol/core-concepts/optimistic-democracy/staking.mdx (1 hunks)

🧰 Additional context used

📓 Path-based instructions (1)

pages/**/*.mdx

📄 CodeRabbit inference engine (CLAUDE.md)

pages/**/*.mdx: All content is in MDX format supporting React components
Import and use custom components within MDX files
Create .mdx file in appropriate pages/ subdirectory when adding new pages
All content should support React components in MDX files

Files:

• pages/understand-genlayer-protocol/core-concepts/optimistic-democracy/staking.mdx

🧠 Learnings (1)

📓 Common learnings

Learnt from: CR
Repo: genlayerlabs/genlayer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-07-24T07:56:58.272Z
Learning: Applies to pages/validators/setup-guide.mdx : Setup Guide Updates (pages/validators/setup-guide.mdx): Update version references in download examples and version lists, update configuration examples with new contract addresses when applicable, enhance command documentation when new features are added to existing commands, update genesis block configuration in consensus section when network upgrades occur

Learnt from: CR
Repo: genlayerlabs/genlayer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-07-24T07:56:58.272Z
Learning: Applies to pages/validators/setup-guide.mdx : Update version list in curl command output example (line ~88), download command version variable (line ~113), consensus contract addresses and genesis block number (lines ~143-146), and command documentation (line ~347) in setup-guide.mdx for new validator releases

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)

• GitHub Check: Redirect rules - genlayer-docs
• GitHub Check: Header rules - genlayer-docs
• GitHub Check: Pages changed - genlayer-docs
• GitHub Check: Playwright E2E

🔇 Additional comments (1)

pages/understand-genlayer-protocol/core-concepts/optimistic-democracy/staking.mdx (1)

214-221: Verify semantics against the protocol specification and clarify recipient terminology.

The concerns raised are partially valid but require precision:

1. Off-by-one potential: The mathematical semantics are internally consistent (current_epoch >= exit_epoch + 7 is correct for a 7-epoch period starting at exit). However, the narrative could be tighter. "Countdown starts from the exit epoch" is ambiguous—does it mean the exit epoch counts as epoch 1, or is it epoch 0? Consider clarifying: "After exiting at epoch N, funds become claimable starting at epoch N+7 (7 epochs must fully pass)."

2. Recipient ambiguity: "Tokens released to validator owner" uses terminology that is never defined. Confirm what on-chain field this refers to (e.g., Owner address, ValidatorWallet, or caller). Similarly for delegators, clarify if "delegator" is the original token provider or a designated recipient.

3. Timeline diagram: The review references "Epoch N+7: validatorClaim() callable" and "7 epochs have passed since exit call," but no such timeline diagram exists in the current file. If this diagram was intended, it should be added for clarity.

These apply to both sections (lines 214–221 for validators and lines 240–243 for delegators).

---

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 and usage tips.}