Module: incentive

Description

The incentive module manages rewards for finality providers (FPs) and delegators on the Babylon chain. It provides a mechanism for distributing rewards collected from transaction fees as well as interfaces for users to withdraw accumulated rewards.

Messages

MsgWithdrawReward

The MsgWithdrawReward message allows a user to withdraw all accumulated rewards, resetting the user’s reward balance in the process. If a withdrawal address has been set beforehand via MsgSetWithdrawAddress, the rewards are sent to that address instead of the default address.

When a Babylon node receives MsgWithdrawReward, it performs the following:

• Withdraws all accumulated rewards for the user

• Resets the accumulated reward balance to zero

• Sends the rewards to that address if a custom withdrawal address was set

MsgSetWithdrawAddress

The MsgSetWithdrawAddress message specifies an alternative address to receive rewards withdrawn via MsgWithdrawReward.

When a Babylon node receives MsgSetWithdrawAddress, it 1) validates the new address provided by the user and 2) updates the address mapping so that subsequent MsgWithdrawReward operations send rewards to the designated address.

MsgUpdateParams

MsgUpdateParams updates the parameters of the incentive module. This message can only be executed through a governance proposal.

ABCI++ handlers

BeginBlock

At the start of each block, a portion of the transaction fees accumulated in the fee collector is directed to BTC stakers. The exact proportion is defined by the BtcStakingPortion parameter in the incentive module. The system sends these fees to the designated gauge for BTC stakers, which later distributes them to FPs and delegators.

PostHandler

RefundTxDecorator

If a specific message’s execution triggers the IndexRefundableMsg function and the message is successfully executed, the transaction fee paid for that message is refunded to the user. This process occurs at the end of the message execution.

Test coverage

The x/incentive package has low test coverage (11.4%), while the keeper module is well-tested (78.2%), and the types module is mostly untested (1.1%).

ok      github.com/babylonlabs-io/babylon/x/incentive   1.443s  coverage: 11.4% of statements
ok      github.com/babylonlabs-io/babylon/x/incentive/keeper    1.108s  coverage: 78.2% of statements
ok      github.com/babylonlabs-io/babylon/x/incentive/types     1.032s  coverage: 1.1% of statements

Attack surface

Specifically, a very large attack surface is exposed in the incentive module due to the refunding functionality, as any message that can be superficially inflated to consume a lot of gas could be used to cause a DOS. Other possible issues in the exposed messages would result in difficulties withdrawing funds or withdrawing funds multiple times.