feat: added validator whitelisting module

[aniketdivekar]

Description

This PR implements a comprehensive validator whitelist system for the Shardeum EVM chain, providing governance-controlled validator consensus participation management. The implementation includes a full Cosmos SDK module with on-chain state management, governance proposals, and fail-fast transaction processing.

Key Features

• On-chain Governance Module: Complete x/validatorwhitelist module with keeper, message server, query server, and genesis support
• Governance Proposals: Three proposal types for runtime whitelist management:
  • MsgUpdateWhitelist: Enable/disable whitelist and update allowlist
  • MsgAddValidator: Add validators to the allowlist
  • MsgRemoveValidator: Remove validators from the allowlist
• Fail-fast Transaction Processing: Zero gas consumption for blocked delegations to non-whitelisted validators
• Comprehensive Testing: Full test suite covering types, keeper, interfaces, and integration scenarios
• Production-ready Documentation: Complete runbook and technical documentation

Critical Files to Review

Core Module Implementation

• x/validatorwhitelist/keeper/keeper.go - Core keeper with state management
• x/validatorwhitelist/keeper/msg_server.go - Governance message handlers
• x/validatorwhitelist/keeper/query_server.go - Query interface implementation
• x/validatorwhitelist/types/params.go - Parameter validation and business logic

Integration & Ante Handler

• ante/cosmos/validator_whitelist.go - Transaction decorator for fail-fast processing
• ante/interfaces/validator_whitelist_keeper.go - Interface implementations for modularity
• shardeumd/app.go - Module wiring and keeper initialization

Protobuf Definitions

• proto/shardeum/validatorwhitelist/v1/tx.proto - Message definitions
• proto/shardeum/validatorwhitelist/v1/query.proto - Query definitions
• proto/shardeum/validatorwhitelist/v1/genesis.proto - Genesis state

Testing & Documentation

• x/validatorwhitelist/types/*_test.go - Parameter and genesis validation tests
• x/validatorwhitelist/keeper/*_test.go - Keeper functionality tests
• ante/interfaces/validator_whitelist_keeper_test.go - Interface compliance tests
• docs/validator_whitelist.md - Technical documentation
• docs/validator_whitelist_runbook.md - End-to-end testing guide

Behavior Changes

• Validator Creation: Non-whitelisted validators cannot create validator transactions (prevents self-delegation bypass)
• Delegation Control: Delegations to non-whitelisted validators are blocked with zero gas consumption
• Governance Integration: Whitelist management through standard Cosmos governance proposals
• Runtime Configuration: Whitelist can be enabled/disabled and validators added/removed without chain restart

Testing

The implementation includes comprehensive test coverage:

• Unit tests for all core functionality
• Integration tests for end-to-end workflows
• Interface compliance testing
• Production scenario validation

Run tests with:

go test -v ./x/validatorwhitelist/...
go test -v ./ante/interfaces/

Documentation

Complete documentation is provided:

• Technical specification in docs/validator_whitelist.md
• End-to-end testing runbook in docs/validator_whitelist_runbook.md
• Inline code documentation and examples

---

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...

• tackled an existing issue or discussed with a team member
• left instructions on how to review the changes
• targeted the main branch

Review Instructions

1. Start with the documentation (docs/validator_whitelist.md) to understand the system design
2. Review the core module (x/validatorwhitelist/keeper/) for business logic implementation
3. Check the ante handler (ante/cosmos/validator_whitelist.go) for transaction processing logic
4. Validate the interface design (ante/interfaces/) for modularity and testability
5. Run the test suite to ensure all functionality works as expected
6. Follow the runbook (docs/validator_whitelist_runbook.md) for end-to-end validation

Key Design Decisions

• Interface-based Architecture: Enables multiple keeper implementations (config-based, on-chain, mock)
• Fail-fast Processing: Zero gas consumption for blocked transactions prevents resource waste
• Governance Integration: Standard Cosmos governance proposals for runtime management
• Comprehensive Testing: Full test coverage ensures reliability and maintainability

[mssabr01]

do security review

[github-actions]

🔍 Security Review Report

❌ Failed to generate security review report. Please check the action logs for details.

You can also download the full output as an artifact if available.