feat(action,staking): IIP-59 SetCommissionRate action + handler (PR 3/5)

[envestcc]

Summary

PR 3 of the IIP-59 series. Introduces the on-chain entry point delegates use to opt into protocol-native voter reward distribution: SetCommissionRate(uint64 rate). No reward-distribution logic yet — that arrives in PR 4. This PR is independently reviewable: the action is gated at Validate, so until the IIP-59 feature flag activates the protocol rejects every SetCommissionRate at mempool admission and chain behavior is unchanged.

Series

#	PR	Status
0	iotex-proto: SetCommissionRate + Candidate.commissionRate	iotexproject/iotex-proto#174 (draft)
1	iotex-core: fields + feature flag	#4859 (draft, prerequisite for this PR)
2	iotex-core: VoterWeightView infrastructure	#4860 (draft, independent of this PR)
3	This PR — SetCommissionRate action + handler	here, depends on #4859
4	distributeVoterReward + PutPollResult snapshot	TODO (depends on this PR + #4860 + PR 2.5)
5	multi-node stress test + e2e harness	TODO

What's in this PR

Action (action/set_commission_rate.go):

• SetCommissionRate{ rate uint64 } with IntrinsicGas (10000) and SanityCheck (rate in [0, MaxCommissionRate=10000]).
• Full Proto/LoadProto/FillAction wiring for the iotex-proto field 56 oneof slot.
• EthCompatibleAction implementation + NewSetCommissionRateFromABIBinary decoder so MetaMask/hardhat tooling can submit via the same ETH-tx path as candidateActivate / candidateDeactivate.
• PackCommissionRateSetEvent helper for the receipt log indexers will subscribe to.

ABI surface (action/native_staking_contract_interface.sol + .json):

event CommissionRateSet(address indexed candidate, uint64 newRate);

function setCommissionRate(uint64 rate) external;

Hand-added to both the source .sol and the parsed .json (the repo doesn't auto-regen).

Envelope (action/envelope.go):

• Route ActionCore.setCommissionRate (field 56) into the existing unmarshal dispatch.

Handler (action/protocol/staking/handler_set_commission_rate.go):

• handleSetCommissionRate: owner-check via csm.GetByOwner; write the new rate to staking.Candidate.CommissionRate via Upsert; emit the CommissionRateSet event through receiptLog.AddEvent (the events-path, per the staking CLAUDE.md red-line — never via legacy r.topics / r.data).
• Non-owner caller returns errCandNotExist (the existing handleError), so the receipt is marked failed but block production continues.
• No cooldown check: IIP-59 doesn't prescribe one, and our design's ~1.5-epoch reaction window comes for free via the PutPollResult snapshot mechanism (this point was already settled in PR feat(staking,state): IIP-59 commissionRate fields + feature flag (PR 1/5) #4859 review with envestcc).

Validate (action/protocol/staking/validations.go):

• validateSetCommissionRate: hard-reject when NoVoterRewardDistribution is true (pre-fork mempool admission gate); otherwise delegate to act.SanityCheck for the rate-range check. Returns action.ErrInvalidAct to match the surrounding validateMigrateStake / validateCandidate* convention.

Protocol wiring (action/protocol/staking/protocol.go):

• Register the new action in both the handle and Validate switches.

Test plan

• go build ./... passes
• go test ./action/... -count=1 — 14 new tests added, all pass
  • action/set_commission_rate_test.go (7): SanityCheck boundaries, IntrinsicGas, proto roundtrip, ABI roundtrip, FromABIBinary garbage-rejection, event packing.
  • action/protocol/staking/handler_set_commission_rate_test.go (7): validate pre-fork reject, post-fork accept, rate-over-max reject; handler non-owner errCandNotExist, owner persists, owner re-update; full p.Handle envelope success; pre-fork p.Validate rejection.
• Full action-package sweep passes (modulo the pre-existing flaky TestProtocol_FetchBucketAndValidate bug: TestProtocol_FetchBucketAndValidate flaky in staking test suite #4813 unrelated to this PR).

Behavior gating

• Pre-flag (default): NoVoterRewardDistribution = true. Validate rejects every SetCommissionRate with ErrInvalidAct. The action never reaches the handler; chain behavior identical to today.
• Post-flag: rate writes land on staking.Candidate.CommissionRate. The persisted rate stays inert until PR 4 wires PutPollResult to snapshot it into the per-epoch state.Candidate and GrantEpochReward to consume it.

🤖 Generated with Claude Code

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[envestcc]

Closing as part of IIP-59 PR reorganization. The proposal was amended (iotexproject/iips#73) to cover both block reward + epoch reward and to base voter distribution on a per-epoch snapshot. The new PR split is:

• PR 1 (new): commissionRate schema + SetCommissionRate action (merges the old feat(staking,state): IIP-59 commissionRate fields + feature flag (PR 1/5) #4859 + feat(action,staking): IIP-59 SetCommissionRate action + handler (PR 3/5) #4862)
• PR 2: snapshot layer at PutPollResult (commission rate + voter weight blob)
• PR 3: voter reward distribution (epoch path)
• PR 4: block reward folding (pending pool + orphan drain)
• PR 5: stress test + e2e determinism harness
• PR 6: mainnet fork activation

The incremental voter weight view (old #4860 + #4863) is dropped in favor of a per-PutPollResult full scan; ~40k buckets sorted+encoded once per epoch fits well inside the mint budget and eliminates the 13-handler-hook consensus-safety surface. Old #4864 (voter reward distribution) is replaced by new PR 3 which reads the snapshot instead of the live view.

Superseded by new PRs — will link once opened.