feature(state-processor): update validators `EffectiveBalance` only when epoch turns

[abi87]

This PR fixes validators' balances and effective balances to make it closer to Eth 2.0 specs. In more details:

• [x] we introduce processEffectiveBalanceUpdates to update balances at each epoch turn
• [x] we process effective balances only once per epoch (not every slot as it is currently)
• [x] we add unit tests around validators creation and balances update logic
• [x] added small README highlighting some relevant invariants around validators.

Note: the PR is somewhat large, but most of the code (> 300LOC) comes from added unit tests.

Left for upcoming PRs:

• Optimize validator set returned to consensus to strictly contains only validators that changed (i.e. increased/reduced their weight or where evicted). See https://github.com/berachain/beacon-kit/pull/2143
• Account for CometBFT three slots delay in activating validators
• Code exit processing to unlock cap on validators set

Summary by CodeRabbit

Release Notes

• New Features

  • Introduced new methods for accessing hysteresis parameters in the chain specification.
  • Enhanced configuration options with new hysteresis-related fields.
  • Improved error handling and clarity in state processing logic.

• Bug Fixes

  • Resolved issues with validator balance updates and processing logic.

• Documentation

  • Added a section in the README detailing validator management and balance thresholds.

• Tests

  • Expanded and refined test cases for validator balance updates and transitions.

[coderabbitai[bot]]

Walkthrough

The changes in this pull request introduce new methods and fields related to hysteresis parameters in the Spec interface and SpecData struct. Specifically, three methods are added to the Spec interface, and corresponding fields are added to the SpecData struct. Additionally, modifications are made to the BaseSpec function to initialize these new fields. The state processing logic is refined, particularly concerning validator updates and effective balances, alongside various improvements in error handling and testing.

Changes

File Path	Change Summary
mod/chain-spec/pkg/chain/chain_spec.go	Added methods: HysteresisQuotient(), HysteresisDownwardMultiplier(), HysteresisUpwardMultiplier() to Spec interface and chainSpec struct.
mod/chain-spec/pkg/chain/data.go	Added fields: HysteresisQuotient, HysteresisDownwardMultiplier, HysteresisUpwardMultiplier to SpecData struct.
mod/config/pkg/spec/testnet.go	Updated BaseSpec function to include new hysteresis fields initialized with specific values.
mod/state-transition/pkg/core/state_processor.go	Refactored ProcessSlots, updated processEpoch, and modified processBlockHeader for improved validator and error handling. Added processEffectiveBalanceUpdates method.
mod/state-transition/pkg/core/state_processor_committee.go	Updated processSyncCommitteeUpdates to filter validators based on effective balance using a new slice activeVals.
mod/state-transition/pkg/core/state_processor_genesis.go	Enhanced InitializePreminedBeaconStateFromEth1 to process validator activations and compute effective balances.
mod/state-transition/pkg/core/state_processor_genesis_test.go	Renamed deposits to genDeposits, added new variables for deposit calculations, and updated test assertions.
mod/state-transition/pkg/core/state_processor_staking.go	Simplified deposit processing logic, removed processDeposits, and updated applyDeposit and createValidator methods.
mod/state-transition/pkg/core/state_processor_staking_test.go	Added TestTransitionUpdateValidator to verify state processor behavior on validator balance updates and introduced a new test function TestTransitionCreateValidator.
mod/state-transition/pkg/core/errors.go	Added new error variable ErrProposerMismatch for handling proposer-related discrepancies.
mod/state-transition/pkg/core/README.md	Introduced a new section detailing validator management based on effective balance thresholds.
mod/config/pkg/spec/special_cases.go	Renamed constant BArtioValRoot to BartioValRoot for standardization.

Possibly related PRs

• #1518: The changes in this PR involve modifications to the BaseSpec function, which includes adding new fields related to hysteresis parameters. This is relevant as the main PR also introduces new methods related to hysteresis in the Spec interface.
• #1572: This PR updates the return types of several methods to use transition.ValidatorUpdates instead of slices of transition.ValidatorUpdate. The main PR's changes to the Spec interface and chainSpec struct may relate to how data is structured and accessed, which could impact how validator updates are processed.
• #2102: This PR enhances proposer validation by ensuring that the proposer address matches the expected address derived from the validator's public key. The main PR's introduction of new methods related to hysteresis parameters could be relevant in the context of how validators are managed and validated.
• #2111: This PR focuses on ensuring that the balance of a validator is increased when their balance is updated. The main PR's changes to the Spec interface and related structures may influence how validator balances are calculated and updated.
• #2116: This PR addresses an issue with the eth1 deposit index during genesis processing. The main PR's modifications to the Spec interface and related methods could be relevant to how deposits and validator states are initialized and managed.
• #2147: This PR proposes to skip execution payload timestamp validation on Bartio, which is relevant as it highlights the need for special handling of certain parameters. The main PR's changes to the Spec interface and related methods may also involve similar considerations for different chain specifications.

Suggested labels

Merge me daddy

Suggested reviewers

• itsdevbear
• nidhi-singh02
• calbera

🐇 In the code, I hop and play,
New methods added, hip-hip-hooray!
Hysteresis now has its say,
With balances that sway and sway.
Let’s test and check, come what may,
In the rabbit hole, we code all day! 🐇

---

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](https://twitter.com/intent/tweet?text=I%20just%20used%20%40coderabbitai%20for%20my%20code%20review%2C%20and%20it%27s%20fantastic%21%20It%27s%20free%20for%20OSS%20and%20offers%20a%20free%20trial%20for%20the%20proprietary%20code.%20Check%20it%20out%3A&url=https%3A//coderabbit.ai) - [Mastodon](https://mastodon.social/share?text=I%20just%20used%20%40coderabbitai%20for%20my%20code%20review%2C%20and%20it%27s%20fantastic%21%20It%27s%20free%20for%20OSS%20and%20offers%20a%20free%20trial%20for%20the%20proprietary%20code.%20Check%20it%20out%3A%20https%3A%2F%2Fcoderabbit.ai) - [Reddit](https://www.reddit.com/submit?title=Great%20tool%20for%20code%20review%20-%20CodeRabbit&text=I%20just%20used%20CodeRabbit%20for%20my%20code%20review%2C%20and%20it%27s%20fantastic%21%20It%27s%20free%20for%20OSS%20and%20offers%20a%20free%20trial%20for%20proprietary%20code.%20Check%20it%20out%3A%20https%3A//coderabbit.ai) - [LinkedIn](https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fcoderabbit.ai&mini=true&title=Great%20tool%20for%20code%20review%20-%20CodeRabbit&summary=I%20just%20used%20CodeRabbit%20for%20my%20code%20review%2C%20and%20it%27s%20fantastic%21%20It%27s%20free%20for%20OSS%20and%20offers%20a%20free%20trial%20for%20proprietary%20code)

🪧 Tips

### Chat There are 3 ways to chat with [CodeRabbit](https://coderabbit.ai): - Review comments: Directly reply to a review comment made by CodeRabbit. Example: - `I pushed a fix in commit , please review it.` - `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 gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.` - `@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 using 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. ### Other keywords and placeholders - Add `@coderabbitai ignore` anywhere in the PR description to prevent this PR from being reviewed. - Add `@coderabbitai summary` to generate the high-level summary at a specific location in the PR description. - Add `@coderabbitai` anywhere in the PR title to generate the title automatically. ### 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](https://docs.coderabbit.ai/guides/configure-coderabbit) 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](https://docs.coderabbit.ai) for detailed information on how to use CodeRabbit. - Join our [Discord Community](http://discord.gg/coderabbit) to get help, request features, and share feedback. - Follow us on [X/Twitter](https://twitter.com/coderabbitai) for updates and announcements.

[codecov[bot]]

Codecov Report

Attention: Patch coverage is 61.29032% with 48 lines in your changes missing coverage. Please review.

Project coverage is 26.51%. Comparing base (8a04173) to head (e72fe31).

Files with missing lines	Patch %	Lines
mod/state-transition/pkg/core/state_processor.go	54.71%	16 Missing and 8 partials :warning:
...ate-transition/pkg/core/state_processor_genesis.go	65.78%	2 Missing and 11 partials :warning:
mod/chain-spec/pkg/chain/chain_spec.go	0.00%	6 Missing :warning:
...ate-transition/pkg/core/state_processor_staking.go	64.28%	4 Missing and 1 partial :warning:

Additional details and impacted files

[](https://app.codecov.io/gh/berachain/beacon-kit/pull/2142?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=berachain) ```diff @@ Coverage Diff @@ ## main #2142 +/- ## ========================================== + Coverage 26.28% 26.51% +0.22% ========================================== Files 360 360 Lines 16243 16244 +1 Branches 12 12 ========================================== + Hits 4270 4307 +37 + Misses 11705 11658 -47 - Partials 268 279 +11 ``` | [Files with missing lines](https://app.codecov.io/gh/berachain/beacon-kit/pull/2142?dropdown=coverage&src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=berachain) | Coverage Δ | | |---|---|---| | [mod/config/pkg/spec/testnet.go](https://app.codecov.io/gh/berachain/beacon-kit/pull/2142?src=pr&el=tree&filepath=mod%2Fconfig%2Fpkg%2Fspec%2Ftestnet.go&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=berachain#diff-bW9kL2NvbmZpZy9wa2cvc3BlYy90ZXN0bmV0Lmdv) | `100.00% <100.00%> (ø)` | | | [...e-transition/pkg/core/state\_processor\_committee.go](https://app.codecov.io/gh/berachain/beacon-kit/pull/2142?src=pr&el=tree&filepath=mod%2Fstate-transition%2Fpkg%2Fcore%2Fstate_processor_committee.go&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=berachain#diff-bW9kL3N0YXRlLXRyYW5zaXRpb24vcGtnL2NvcmUvc3RhdGVfcHJvY2Vzc29yX2NvbW1pdHRlZS5nbw==) | `84.21% <100.00%> (+5.63%)` | :arrow_up: | | [...ate-transition/pkg/core/state\_processor\_staking.go](https://app.codecov.io/gh/berachain/beacon-kit/pull/2142?src=pr&el=tree&filepath=mod%2Fstate-transition%2Fpkg%2Fcore%2Fstate_processor_staking.go&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=berachain#diff-bW9kL3N0YXRlLXRyYW5zaXRpb24vcGtnL2NvcmUvc3RhdGVfcHJvY2Vzc29yX3N0YWtpbmcuZ28=) | `54.21% <64.28%> (-0.58%)` | :arrow_down: | | [mod/chain-spec/pkg/chain/chain\_spec.go](https://app.codecov.io/gh/berachain/beacon-kit/pull/2142?src=pr&el=tree&filepath=mod%2Fchain-spec%2Fpkg%2Fchain%2Fchain_spec.go&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=berachain#diff-bW9kL2NoYWluLXNwZWMvcGtnL2NoYWluL2NoYWluX3NwZWMuZ28=) | `11.90% <0.00%> (-0.92%)` | :arrow_down: | | [...ate-transition/pkg/core/state\_processor\_genesis.go](https://app.codecov.io/gh/berachain/beacon-kit/pull/2142?src=pr&el=tree&filepath=mod%2Fstate-transition%2Fpkg%2Fcore%2Fstate_processor_genesis.go&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=berachain#diff-bW9kL3N0YXRlLXRyYW5zaXRpb24vcGtnL2NvcmUvc3RhdGVfcHJvY2Vzc29yX2dlbmVzaXMuZ28=) | `49.39% <65.78%> (-0.61%)` | :arrow_down: | | [mod/state-transition/pkg/core/state\_processor.go](https://app.codecov.io/gh/berachain/beacon-kit/pull/2142?src=pr&el=tree&filepath=mod%2Fstate-transition%2Fpkg%2Fcore%2Fstate_processor.go&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=berachain#diff-bW9kL3N0YXRlLXRyYW5zaXRpb24vcGtnL2NvcmUvc3RhdGVfcHJvY2Vzc29yLmdv) | `35.27% <54.71%> (+8.57%)` | :arrow_up: | ... and [3 files with indirect coverage changes](https://app.codecov.io/gh/berachain/beacon-kit/pull/2142/indirect-changes?src=pr&el=tree-more&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=berachain)