feat!: Let consumer chains choose a minimum stake and validator rank

[p-offtermatt]

Description

Closes: #1916

Read the ADR and changes to the docs first, then the rest is mostly boilerplate.

---

Author Checklist

All items are required. Please add a note to the item if the item is not applicable and
please add links to any relevant follow up issues.

I have...

• Included the correct type prefix in the PR title
• Added ! to the type prefix if the change is state-machine breaking
• Confirmed this PR does not introduce changes requiring state migrations, OR migration code has been added to consumer and/or provider modules
• Targeted the correct branch (see PR Targeting)
• Provided a link to the relevant issue or specification
• Followed the guidelines for building SDK modules
• Included the necessary unit and integration tests
• Added a changelog entry to CHANGELOG.md
• Included comments for documenting Go code
• Updated the relevant documentation or specification
• Reviewed "Files changed" and left comments if necessary
• Confirmed all CI checks have passed
• If this PR is library API breaking, bump the go.mod version string of the repo, and follow through on a new major release

Reviewers Checklist

All items are required. Please add a note if the item is not applicable and please add
your handle next to the items reviewed if you only reviewed selected items.

I have...

• confirmed the correct type prefix in the PR title
• confirmed ! the type prefix if the change is state-machine breaking
• confirmed this PR does not introduce changes requiring state migrations, OR confirmed migration code has been added to consumer and/or provider modules
• confirmed all author checklist items have been addressed
• reviewed state machine logic
• reviewed API design and naming
• reviewed documentation is accurate
• reviewed tests and test coverage

Summary by CodeRabbit

• New Features

  • Introduced functionality for setting minimum stake and maximum validator rank requirements for consumer chains.
  • Added mechanisms for managing validator power distribution, including capping power, creating allowlists and denylists, and defining minimum validator stake.

• Bug Fixes

  • Corrected a bug in the computation of the maximum capped power in the interchain security module.

• Documentation

  • Updated documentation to clarify the impact of new validator management features on chain security and validator participation.

• Tests

  • Added test cases for minimum stake and maximum validator rank parameters to ensure correct system behavior under different conditions.

[coderabbitai]

Warning

Rate limit exceeded

@p-offtermatt has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 2 minutes and 21 seconds before requesting another review.

How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

Commits

Files that changed from the base of the PR and between 1ed6ec6 and 51ad903.

Walkthrough

Walkthrough

The changes implement audit suggestions and new features in the interchain security module. Key additions include setting minimum stake and maximum validator rank requirements for consumer chains, enhancing control over validator selection. The adjustments also involve bug fixes related to maximum capped power computation and test cases to ensure correct behavior of new parameters.

Changes

Files/Paths	Change Summaries
.changelog/unreleased/...	Summaries of bug fixes and new features related to validator stake and rank requirements.
docs/docs/...	Documentation updates to reflect new parameters (MinStake, MaxValidatorRank) and their impact on chain security.
proto/interchain_security/...	Added new fields min_stake and max_rank to relevant messages in provider.proto and tx.proto.
tests/integration/..., testutil/keeper/...	Added test cases and helpers to validate the new parameters and their effects on validator set composition.
x/ccv/provider/client/..., x/ccv/provider/keeper/...	Implemented logic to handle new parameters in proposals, manage storage, and validate minimum stake and maximum rank.
x/ccv/provider/types/...	Introduced new keys and functions to support storage and retrieval of MinStake and MaxValidatorRank values.

Sequence Diagram(s)

sequenceDiagram
    participant User
    participant ConsumerChain
    participant ProviderChain
    participant Validator
    User ->> ConsumerChain: Propose new chain with min_stake and max_rank
    ConsumerChain ->> ProviderChain: Submit proposal with min_stake, max_rank
    ProviderChain ->> ProviderChain: Store min_stake and max_rank
    ProviderChain ->> Validator: Validate based on new parameters
    Validator ->> ConsumerChain: Validate if within criteria

Loading

Assessment against linked issues

Objective	Addressed	Explanation
Allow consumer chains to disable non-provider-vals from validating (#1916)	✅
Enable setting a minimum stake requirement for validators (#2035)	✅
Enable setting a maximum validator rank requirement for validators (#2035)	✅
Ensure correct computation of maximum capped power in interchain security module (#1925)	✅
Implement necessary tests to validate new parameters and ensure system integrity (#2035, #1925)	✅

---

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?

Share

• X
• Mastodon
• Reddit
• LinkedIn

Tips

Chat

There are 3 ways to chat with CodeRabbit:

• Review comments: Directly reply to a review comment made by CodeRabbit. Example:
  • I pushed a fix in commit <commit_id>.
  • Generate unit testing code for this file.
  • Open a follow-up GitHub issue for this discussion.
• Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
  • @coderabbitai generate unit testing code for this file.
  • @coderabbitai modularize this function.
• PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
  • @coderabbitai generate interesting stats about this repository and render them as a table.
  • @coderabbitai show all the console.log statements in this repository.
  • @coderabbitai read src/utils.ts and generate unit testing code.
  • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
  • @coderabbitai help me debug CodeRabbit configuration file.

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 as PR comments)

• @coderabbitai pause to pause the reviews on a PR.
• @coderabbitai resume to resume the paused reviews.
• @coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
• @coderabbitai full review to do a full review from scratch and review all the files again.
• @coderabbitai summary to regenerate the summary of the PR.
• @coderabbitai resolve resolve all the CodeRabbit review comments.
• @coderabbitai configuration to show the current CodeRabbit configuration for the repository.
• @coderabbitai help to get help.

Additionally, you can add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.

CodeRabbit Configuration File (.coderabbit.yaml)

• You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
• Please see the configuration documentation for more information.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

• Visit our Documentation for detailed information on how to use CodeRabbit.
• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

Actionable comments posted: 6

Outside diff range, codebase verification and nitpick comments (5)

docs/docs/features/power-shaping.md (2)

15-15: Formatting Issue: Lists should be surrounded by blank lines.

To improve readability and conform to Markdown best practices, ensure that lists are surrounded by blank lines.

14a15
> 
26a28
> 

Also applies to: 27-27

Tools

Markdownlint

15-15: null
Lists should be surrounded by blank lines

(MD032, blanks-around-lists)

---

27-27: Grammatical Improvement Suggestion: Use of 'can' instead of 'able to'.

For conciseness and readability, consider using "can" instead of "able to".

- If neither list is set, all validators are able to validate the consumer chain.
+ If neither list is set, all validators can validate the consumer chain.

Tools

LanguageTool

[style] ~27-~27: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...hey cannot validate the consumer chain. If neither list is set, all validators are...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)

---

[style] ~27-~27: As a shorter alternative for ‘able to’, consider using “can”.
Context: ... If neither list is set, all validators are able to validate the consumer chain. :::warnin...

(BE_ABLE_TO)

Markdownlint

27-27: null
Lists should be surrounded by blank lines

(MD032, blanks-around-lists)

x/ccv/provider/keeper/proposal.go (1)

389-390: Approved with suggestion: New setter methods

The addition of SetMinStake and SetMaxValidatorRank methods is a good practice. However, adding comments to these methods would improve maintainability and clarity for other developers.

+ // SetMinStake sets the minimum stake required for a validator on a consumer chain.
+ // SetMaxValidatorRank sets the maximum rank a validator can have to participate on a consumer chain.

x/ccv/provider/keeper/partial_set_security_test.go (1)

710-750: Review of TestMinStake function

The test is well-structured with clear test cases for different minimum stake scenarios. However, it's essential to ensure that the FulfillsMinStake method, which is being tested, correctly handles edge cases and potential exceptions. It would be beneficial to add a test case where the minStake is negative to ensure robustness.

Consider adding a test case for negative stake values to ensure error handling is robust.

x/ccv/provider/keeper/proposal_test.go (1)

Line range hint 816-907: Review of TestBeginBlockInit function

This test function checks the initialization logic at the beginning of a block concerning consumer addition proposals. It's well-structured and covers scenarios with different spawn times and chain IDs. However, the test could be enhanced by verifying the state of the system after each proposal is processed to ensure that all effects are as expected.

Consider adding assertions to verify the system state after each proposal handling to ensure all side effects are correctly applied.

[insumity]

What is the relation between minimum stake and the validator power cap? It seems that a validator V might not be added due to a minimum stake requirement but after the application of the validator power cap, V might have an increase in its power (and hence an increase in V's supposedly tokens). If that's the case, why shouldn't we add V?

[p-offtermatt]

The minimum stake is meant to be a minimum amount of staked tokens; this is supposed to mitigate attacks by validators with very little stake, so the amount of stake is relevant, not the voting power.
(In reality, probably the dollar value of the stake would be even more relevant, but the amount of tokens is a decent proxy that doesn't need complicated things like oracles; whereas the post-power-shaping voting power is not a good proxy for the value of the collateral)