Module: evmvalidator

Description

The evmvalidator module receives EVM events from the execution layer and handles core validator-related logic, including validator set management, slashing evidence management, and stake withdrawal.

It aims to deactivate some code in the staking module provided by default in the Cosmos SDK and to replace those functionalities.

Messages

Message: MsgUpdateValidatorEntrypointContractAddr

The MsgUpdateParams message updates the ValidatorEntrypointContract address. It can only be executed through a governance proposal.

Message: MsgUpdateParams

The MsgUpdateParams message updates the evmvalidator module’s parameters. It can only be executed through a governance proposal.

Event processing

The evmvalidator module's event handler processes events emitted by the ConsensusValidatorEntrypoint contract on the EVM and performs the following key functions:

Event filtering. The FilterParams function only processes events from a specific contract address (govEntrypointContractAddr) and with a specific event ID (MsgExecute). It improves system efficiency by preventing unnecessary event processing.

Event delivery and handling. The Deliver function is the main function that receives and handles EVM log events. It uses a cached context to ensure atomicity of state changes and contains logic to either ignore or propagate errors based on their severity.

EVM event-execution processing. This involves the following functions.

• processRegisterValidator: This registers a new validator to the consensus layer and sets initial collateral and voting power.

• processDepositCollateral: This increases a validator's collateral and voting power.

• processWithdrawCollateral: This decreases a validator's collateral and voting power. The withdrawn balance is reflected to the execution layer after a certain period.

• processTransferCollateralOwnership: This transfers collateral ownership from one address to another, changing the ownership structure.

• processUnjail: This reactivates a jailed validator to participate in the consensus process again.

• processUpdateExtraVotingPower: This reflects the voting power from delegations occurring in the execution layer to the validator's voting power in the consensus layer.

The staking module vs evmvalidator module

This section outlines the differences between the original staking module and the evmvalidator module.

• Removal of the delegation system. In Cosmos SDK, delegators delegate tokens to validators. In EVMValidator, delegators also delegate tokens to validators, but this does not use the Cosmos SDK’s staking module. Instead, a smart contract on the execution layer handles delegation functionality. When a delegation is created in the contract, an event is emitted and relayed to the consensus layer, where it is added to the validator’s voting power as ExtraVotingPower.

• Simplification of the slashing mechanism. In Cosmos SDK, slashing applies not only to the validator’s self-stake but also to the delegated stake from delegators. In EVMValidator, slashing applies only to the validator’s own bonded tokens. However, limiting slashing to only the validator's stake does not allow malicious validators to abuse delegation as a way to avoid slashing. This is enforced by the max_leverage_ratio parameter.

ABCI++ handlers

Handler: EndBlocker

The EndBlocker of the evmvalidator module processes matured withdrawal requests. During this process, it handles only as many requests as defined by the WithdrawalLimit parameter, which sets the maximum number of requests processed per block. For each withdrawal request, it calls the InsertWithdrawal function of the evmengine module to update the recipient's balance in the execution layer through the Engine API. Once processed, withdrawal requests are removed from the state.

After completing all withdrawal-request processing, the EndBlocker retrieves a validator list sorted by current power, limited to the maximum number defined by the MaxValidators parameter. This list excludes validators in the jail state. Each validator's power is recalculated when changes occur to their collateral balance (when calling functions like DepositCollateral, RegisterValidator, Slash_, UpdateExtraVotingPower, or WithdrawCollateral) or when module parameters related to voting power are updated (when calling UpdateParams).

The EndBlocker then iterates through this validator list and compares it with the previous block. If a validator was included in the consensus participation ranking in the previous block but is excluded in the current block, they are removed from the list of validators participating in the next consensus process. Conversely, if a validator was not ranked in the previous block but has newly entered the ranking in the current block, they are included in the list for participating in the consensus process of the next block. In this case, the AfterValidatorBonded hook of the slashing module is called to update the ValidatorSigningInfo data that records history related to signing during the consensus process.