docs: fix typos and improve clarity in architecture #23255
Conversation
…ation - Corrected "fail" to "fails" in staking messages for consistency. - Fixed "Best Pratices" to "Best Practices" in sign mode documentation. - Clarified the definition of "optimistic proposal" in governance improvements. - Enhanced the explanation of error handling in Rosetta documentation.
📝 WalkthroughWalkthroughThe pull request introduces significant architectural changes across multiple documentation files. The most substantial modification is in the epoch-based staking design (ADR-039), which proposes a new mechanism for buffering staking weight updates over defined epochs. This approach allows delayed application of staking updates like delegations and unbonds, providing more stability and predictability in validator set management. Additionally, the PR includes minor documentation improvements in governance proposal types (ADR-069) and some grammatical corrections in user documentation. Changes
Sequence DiagramsequenceDiagram
participant Delegator
participant StakingModule
participant EpochManager
Delegator->>StakingModule: Submit Delegation
StakingModule->>EpochManager: Queue Delegation
Note over StakingModule,EpochManager: Delegation stored but not activated
EpochManager->>StakingModule: Process Epoch Boundary
StakingModule->>StakingModule: Apply Queued Delegations
Possibly related PRs
Suggested Labels
Suggested Reviewers
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
Documentation and Community
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (3)
docs/architecture/adr-069-gov-improvements.md (2)
62-62: Enhance the definition of optimistic proposalThe definition could be clearer by explicitly stating the default behavior and conditions. Consider expanding it to: "An optimistic proposal is a proposal that automatically passes by default unless a specified threshold of NO votes is reached during the voting period."
66-66: Add validation information for governance parametersConsider adding information about the validation requirements for these parameters, such as:
- Valid ranges for
optimistic_rejected_threshold- Format requirements for addresses in
optimistic_authorized_addressesdocs/architecture/adr-039-epoched-staking.md (1)
82-84: Improve message handling documentation clarityThe message handling descriptions could be improved for clarity and consistency:
- Add missing comma after "if valid" in MsgEditValidator description
- Remove redundant "back" in the return statements
- Consider standardizing the structure of each message description
Here's the suggested improvement:
- Move user's self-bond to `EpochDelegationPool` immediately. Queue a message for the epoch boundary to handle the self-bond, taking the funds from the `EpochDelegationPool`. If Epoch execution fails, return back funds from `EpochDelegationPool` to user's account. - Validate message and if valid queue the message for execution at the end of the Epoch. - Move user's funds to `EpochDelegationPool` immediately. Queue a message for the epoch boundary to handle the delegation, taking the funds from the `EpochDelegationPool`. If Epoch execution fails, return back funds from `EpochDelegationPool` to user's account. + Move user's self-bond to `EpochDelegationPool` immediately. Queue a message for the epoch boundary to handle the self-bond, taking the funds from the `EpochDelegationPool`. If Epoch execution fails, return funds from `EpochDelegationPool` to user's account. + Validate message and, if valid, queue the message for execution at the end of the Epoch. + Move user's funds to `EpochDelegationPool` immediately. Queue a message for the epoch boundary to handle the delegation, taking the funds from the `EpochDelegationPool`. If Epoch execution fails, return funds from `EpochDelegationPool` to user's account.🧰 Tools
🪛 LanguageTool
[style] ~82-~82: Consider using just “return”.
Context: ...egationPool. If Epoch execution fails, return back funds fromEpochDelegationPool` to use...(RETURN_BACK)
[uncategorized] ~83-~83: Possible missing comma found.
Context: ...ditValidator**: Validate message and if valid queue the message for execution at the ...(AI_HYDRA_LEO_MISSING_COMMA)
[style] ~84-~84: Consider using just “return”.
Context: ...egationPool. If Epoch execution fails, return back funds fromEpochDelegationPool` to use...(RETURN_BACK)
📜 Review details
Configuration used: .coderabbit.yml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (4)
docs/architecture/adr-039-epoched-staking.md(1 hunks)docs/architecture/adr-050-sign-mode-textual-annex1.md(1 hunks)docs/architecture/adr-069-gov-improvements.md(1 hunks)docs/user/run-node/04-rosetta.md(1 hunks)
✅ Files skipped from review due to trivial changes (2)
- docs/architecture/adr-050-sign-mode-textual-annex1.md
- docs/user/run-node/04-rosetta.md
🧰 Additional context used
📓 Path-based instructions (2)
docs/architecture/adr-039-epoched-staking.md (1)
Pattern **/*.md: "Assess the documentation for misspellings, grammatical errors, missing documentation and correctness"
docs/architecture/adr-069-gov-improvements.md (1)
Pattern **/*.md: "Assess the documentation for misspellings, grammatical errors, missing documentation and correctness"
🪛 LanguageTool
docs/architecture/adr-039-epoched-staking.md
[style] ~82-~82: Consider using just “return”.
Context: ...egationPool. If Epoch execution fails, return back funds from EpochDelegationPool` to use...
(RETURN_BACK)
[uncategorized] ~83-~83: Possible missing comma found.
Context: ...ditValidator**: Validate message and if valid queue the message for execution at the ...
(AI_HYDRA_LEO_MISSING_COMMA)
[style] ~84-~84: Consider using just “return”.
Context: ...egationPool. If Epoch execution fails, return back funds from EpochDelegationPool` to use...
(RETURN_BACK)
⏰ Context from checks skipped due to timeout of 90000ms (1)
- GitHub Check: Summary
julienrbrt
changed the title
|
No need to update typos on ADRs - these are just records. Closing as this does not fit our CONTRIBUTING guidelines |
…ation
Summary by CodeRabbit
Documentation Updates
Governance Improvements