x/valrewards awards validators for signed blocks using per-epoch points. Rewards are not share-based: each validator earns points for signing, proposers receive a fixed bonus, and epoch rewards are allocated proportionally to points.

​
Runtime model

  • current_reward_settings are used for the epoch currently accumulating points.
  • next_reward_settings are staged values that become active at the next epoch boundary.
  • Changes made during epoch N do not alter calculations already in progress for epoch N.
  • Whitelisted accounts can submit runtime setter messages.
  • Whitelist changes are governance-only through MsgUpdateParams.
  • PROPOSER_BONUS_POINTS remains hardcoded and is currently 1.
If rewarding_paused is switched to true during an epoch, the current epoch still completes and pays normally. The next epoch starts paused, records no new validator points, and creates no new outstanding reward rows.

​
Core logic

AreaBehavior
PointsValidators that signed receive points proportional to voting power; proposer receives a fixed bonus.
Epoch rewardsAt epoch end, total points split configured rewards_per_epoch across validators.
ClaimingClaims are one-time and single-validator. Outstanding rewards are zeroed after success.
Sponsor callsCosmos msg and EVM precompile claim paths are sponsor-callable; payout always goes to the target validator operator.
FundingClaims are paid from the module rewards pool and fail if the pool has insufficient balance.
Epoch transitionsPayout uses completed epoch settings; only after payout are next settings promoted to current settings.

​
Default genesis

{
  "valrewards": {
    "params": {
      "whitelist": []
    },
    "current_reward_settings": {
      "blocks_in_epoch": 17280,
      "rewards_per_epoch": "45004521205479450000000",
      "rewarding_paused": false
    },
    "next_reward_settings": {
      "blocks_in_epoch": 17280,
      "rewards_per_epoch": "45004521205479450000000",
      "rewarding_paused": false
    },
    "epoch_state": {
      "current_epoch": 0,
      "blocks_into_current_epoch": 0
    },
    "epoch_to_pay": 0,
    "validator_points": [],
    "validator_outstanding_rewards": []
  }
}
The rewards pool balance is not duplicated inside app_state.valrewards; it remains part of the module account balance in auth/bank state.

​
Validation rules

FieldRule
blocks_in_epochint64, minimum 20, maximum 6500000
rewards_per_epochRequired decimal integer string, minimum 1000000000000000000, maximum 25000000000000000000000000
rewarding_pausedBoolean
params.whitelistValid bech32 account addresses only; duplicates rejected
Deposit amountValid positive coin amount
Outstanding rewardsMust use evmtypes.DefaultEVMDenom; sum cannot exceed the funded module account balance
epoch_to_payCannot exceed epoch_state.current_epoch
Points/rewards entry epochsCannot exceed epoch_state.current_epoch

​
Exposed methods

​
Cosmos SDK messages

  • MsgDepositRewardsPool(depositor, amount)
  • MsgClaimRewards(validator_operator, epoch, requester)
  • MsgSetBlocksInEpoch(signer, blocks_in_epoch)
  • MsgSetRewardsPerEpoch(signer, rewards_per_epoch)
  • MsgSetRewardingPaused(signer, rewarding_paused)
  • MsgUpdateParams(authority, params)
MsgClaimRewards is sponsor-callable: any valid requester may submit the transaction, but rewards are still paid only to the target validator account. Runtime setter messages require the signer to be present in params.whitelist; MsgUpdateParams is authority-only and intended for governance.

​
Queries

  • Query/RewardsPool
  • Query/ValidatorOutstandingRewards
  • Query/DelegationRewards
  • Query/Params
Query/ValidatorOutstandingRewards expects a canonical Bech32 validator operator address. Hex 0x... addresses are rejected.

​
EVM precompile

Address: 0x0000000000000000000000000000000000000714
  • rewardsPool()
  • validatorOutstandingRewards(epoch, validatorAddress)
  • delegationRewards(delegatorAddress, epoch)
  • depositValidatorRewardsPool(depositor, amount)
  • claimRewards(validatorOperatorAddress, epoch)
For exact ABI signatures, see Precompile ABI Reference.

​
CLI

ctmd query valrewards rewards-pool
ctmd query valrewards validator-outstanding-rewards <epoch> <c8valoper...>
ctmd query valrewards delegation-rewards <delegator> <epoch>
ctmd query valrewards params

ctmd tx valrewards deposit <amount>
ctmd tx valrewards claim <c8valoper...> <epoch>
ctmd tx valrewards set-blocks-in-epoch <blocks-in-epoch>
ctmd tx valrewards set-rewards-per-epoch <rewards-per-epoch>
ctmd tx valrewards set-rewarding-paused <true|false>